uk.ac.ebi.arrayexpress2.magetab.datamodel

Class SDRF

java.lang.Object

uk.ac.ebi.arrayexpress2.magetab.datamodel.graph.AbstractGraph<SDRFNode>

uk.ac.ebi.arrayexpress2.magetab.datamodel.SDRF

All Implemented Interfaces:

Graph<SDRFNode>

public class SDRF
extends AbstractGraph<SDRFNode>

A datastructure that simply models SDRF in the MAGE-TAB spec. Nodes are stored in an internal node store, and can be accessed by the AbstractGraph.getNode(String, Class) method. Because nodes are arranged in a graph-like structure, each node contains a reference to the ID of the child node.

For example, lets consider we have an SDRF snippet like:

 Source     Characteristic[organism]    ...
 source_1   homo sapiens                ...
 source_2   mus musculus                ...
 

The SDRF representation on the object model is slightly different from the IDF, it stores the graph rather than a direct representation of the spreadsheet. Therefore, you can use the methods getNode() and getAllNodes() on the SDRF to access the top-level nodes on the graph. These methods are generically typed, so for example you could do:

 // this list will contain two nodes
 List sources = investigation.SDRF.getAllNodes(SourceNode.class);
 

 // will print "source_1" then "source_2"
 for (SourceNode source : sources) {
   System.out.println(source.getNodeName());
 }
 

Alternatively, if you already know the node name, you can retrieve it specifically

 // this is the first source node, source_1 SourceNode source_1 =
 investigation.SDRF.getNode("source_1", SourceNode.class);
 

You can then extract the attributes of these by accessing the public fields. Some nodes can have a list of attributes, in which case the public field returns a list. For characteristics of this source_1 node, you might want some code like this:

 // this list will contain one element List
 characteristicsList = source_1.characteristics;
 

To get the specific types and values, now all you need to do with this list of elements is the following;

 for (CharacteristicsAttribute characteristics : characteristicsList) {
   // will return "organism" for the above snippet
   String organism = characteristics.type;
   // will return "homo sapiens" for source_1
   String homo_sapiens = characteristics.getNodeName();
 }
 

Obviously, because the attributes are tied to each node, it isn't possible to get all values from a single attribute column - you have to iterate over all the nodes in the graph to "rebuild" the attribute columns.

Note that protocols are the exception to this general pattern. To obtain Protocols, you should not use the AbstractGraph.getNodes(Class) method, instead look for the public field on the node to which this protocol is associated. So, for example...

   SourceNode src = ...
   List protocols = src.protocols
 

Author:

Tony Burdett

See Also:

IDF, ADF

Constructor Summary

Constructors

Constructor and Description
SDRF()

Method Summary

Methods

Modifier and Type	Method and Description
int	getChannelNumber(String label) Returns the channel number assigned to any given label.
String	getLabelForChannel(int channelNumber) Returns the label that tags a given channel.
SDRFLayout	getLayout() Get the layout of this SDRF.
URL	getLocation() Get the known location of this SDRF, being the location of the file which was parsed to generate it.
int	getNumberOfChannels() Returns the number of channels in this experiment.
boolean	hasBeenHandled(String nodeName, Class<? extends SDRFNode> nodeType) Determine whether a given node has been handled already, and exists in the graph.
<T extends SDRFNode> T	lookupNode(String nodeName, Class<T> nodeType) Deprecated. since version 1.1, use AbstractGraph.getNode(String, Class) instead
SDRFNode	lookupNode(String nodeName, String nodeType) Deprecated. since version 1.1, use AbstractGraph.getNode(String, String) instead
<T extends SDRFNode> Collection<T>	lookupNodes(Class<T> nodeType) Deprecated. since version 1.1, use AbstractGraph.getNodes(Class) instead
Collection<? extends SDRFNode>	lookupNodes(String nodeType) Deprecated. since version 1.1, use AbstractGraph.getNodes(String) instead
Collection<String>	lookupProtocols() Lookup all named protocols references in this SDRF.
void	removeNodeFromGraph(SDRFNode node) Deprecated. since version 1.1, use AbstractGraph.removeNode(uk.ac.ebi.arrayexpress2.magetab.datamodel.graph.Node) instead
void	setLocation(URL location) Get the known location of this SDRF, being the location of the file which was parsed to generate it.
void	storeNode(SDRFNode node) Deprecated. since version 1.1, use AbstractGraph.addNode(uk.ac.ebi.arrayexpress2.magetab.datamodel.graph.Node) instead

Methods inherited from class uk.ac.ebi.arrayexpress2.magetab.datamodel.graph.AbstractGraph

addNode, checkForCycles, getAllNodes, getLog, getNode, getNode, getNodeCount, getNodes, getNodes, getRootNodes, removeNode, resolveGraphStructure, updateNode

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SDRF

public SDRF()

Method Detail

getLocation

public URL getLocation()

Get the known location of this SDRF, being the location of the file which was parsed to generate it. This may be used by handlers wishing to read files declared with some relative location to the SDRF.

Returns:

the location of the SDRF file

setLocation

public void setLocation(URL location)

Get the known location of this SDRF, being the location of the file which was parsed to generate it. This may be used by handlers wishing to read files declared with some relative location to the SDRF.

Parameters:

location - the full URL of the SDRF file represented by this SDRF object

getLayout

public SDRFLayout getLayout()

Get the layout of this SDRF. This layout can be used for tracking error locations or writing an SDRF to file.

Returns:

the layout of this SDRF in it's file form

storeNode

@Deprecated
public void storeNode(SDRFNode node)
               throws ParseException

Deprecated. since version 1.1, use AbstractGraph.addNode(uk.ac.ebi.arrayexpress2.magetab.datamodel.graph.Node) instead

Store a node in the SDRF graph. This node will be added to the internal graph representation of nodes represented by this SDRF object. In this way, this SDRF object represents the data encoded by the spreadsheet rather than directly representing the spreadsheet data structure.

Parameters:

node - the node to store

Throws:

ParseException - if the node being stored would violate the principle that the graph is acyclic

removeNodeFromGraph

@Deprecated
public void removeNodeFromGraph(SDRFNode node)

Deprecated. since version 1.1, use AbstractGraph.removeNode(uk.ac.ebi.arrayexpress2.magetab.datamodel.graph.Node) instead

Remove a node that was previously stored in the SDRF graph. This node will be taken out of the internal graph representation of nodes represented by this SDRF object.

Note: this method also removes any references elsewhere in the graph to this Node, from parent and child nodes. You should relink your SDRF graph around the removed node once you have taken it out: but be warned, this may compromise the structure of the graph in terms of Protocol applications either side of the removed node.

Parameters:

node - the node to remove

hasBeenHandled

public boolean hasBeenHandled(String nodeName,
                     Class<? extends SDRFNode> nodeType)

Determine whether a given node has been handled already, and exists in the graph. Essentially this is a convenience method that delegates to lookupNode(String, Class).

Parameters:

nodeName - the name of the node

nodeType - the class type of the node

Returns:

true if it exists in the graph already, false otherwise

lookupNode

@Deprecated
public <T extends SDRFNode> T lookupNode(String nodeName,
                                           Class<T> nodeType)

Deprecated. since version 1.1, use AbstractGraph.getNode(String, Class) instead

Lookup a node by name and class type in the SDRF graph. This will return the node if it exists, or null if not.

Type Parameters:

T - the generic node type to lookup

Parameters:

nodeName - the node name

nodeType - the class type of the node

Returns:

the node, if it exists, or null otherwise

lookupNode

@Deprecated
public SDRFNode lookupNode(String nodeName,
                             String nodeType)

Deprecated. since version 1.1, use AbstractGraph.getNode(String, String) instead

Lookup a node by name and type in the SDRF graph. This will return the node if it exists, or null if not.

Parameters:

nodeName - the node name

nodeType - the tag that describes the node in the SDRF spec

Returns:

the node, if it exists, or null otherwise

lookupNodes

@Deprecated
public <T extends SDRFNode> Collection<T> lookupNodes(Class<T> nodeType)

Deprecated. since version 1.1, use AbstractGraph.getNodes(Class) instead

Lookup all nodes of the given class type in the SDRF graph. This will return a collection of the nodes of this type, which will be empty if there are none.

Type Parameters:

T - the generic node type to lookup

Parameters:

nodeType - the class type of the node

Returns:

the node, if it exists, or null otherwise

lookupNodes

public Collection<? extends SDRFNode> lookupNodes(String nodeType)

Deprecated. since version 1.1, use AbstractGraph.getNodes(String) instead

Lookup all nodes of the given type (by SDRF spec name) in the SDRF graph. This will return a collection of the nodes of this type, which will be empty if there are none.

Parameters:

nodeType - the class type of the node

Returns:

the node, if it exists, or null otherwise

getNumberOfChannels

public int getNumberOfChannels()

Returns the number of channels in this experiment. Most MAGE-TAB investigations tend to be single channel experiments, so unless multiple channels are observed (by labelling extracts with different dyes) this method will return 1. For multichannel experiments, this will increase with every unique dye described. This method does no validation, so typos in the label column will be interpreted as new dyes and could falsely increase the number of channels. Checking the number of incoming edges into every hybridization against the number of labelling dyes is a good way to check these results are correct.

Returns:

the number of channels in this experiment

getChannelNumber

public int getChannelNumber(String label)

Returns the channel number assigned to any given label. Factor Values are attributes of hybridizations, but are assigned a channel number (FactorValueAttribute.scannerChannel). This method returns the scanner channel assigned to a given label.

Parameters:

label - the label that uniquely identifies a channel in an SDRF

Returns:

the channel number assigned to that label

getLabelForChannel

public String getLabelForChannel(int channelNumber)

Returns the label that tags a given channel. By passing the channel number for a given factor value attribute to this method, you can acquire the label that matches this channel.

Parameters:

channelNumber - the channel number assigned to a factor value attribute

Returns:

the label name this channel is labeled with

lookupProtocols

public Collection<String> lookupProtocols()

Lookup all named protocols references in this SDRF. Protocols are treated as a special case in SDRF parsing - whenever a Protocol REF column is observed in the SDRF, a new node type, ProtocolApplicationNode, is created. This represents a unique node in the graph where the given protocol is applied to the given parent node. This ProtocolApplicationNode then references the protocol named in the SDRF (or "Unknown Protocol" if the reference is not specified).

Using this method, you can retrieve a list of all protocol names referenced within the SDRF. Alternatively, to find the unique applications of these protocols, you can do getAllNodes(ProtocolApplicationNode.class);. By iterating over the list of returned protocol application nodes, and extracting the protocol from each (use protocolApplicationNode.protocol) you can reconstruct this list, or count the number of times a particular protocol was applied, and so on.

This method returns a collection that only contains the names of the protocols referenced in the SDRF. It does not contain duplicates, and ti does not imply anything about the usage of these protocols or a collection of the "nodes" that utilise these protocols. You can acquire more detailed information about protocol usages by retrieving a list of ProtocolApplicationNodes using the AbstractGraph.getNodes(Class) and providing the parameter "ProtocolApplicationNode.class

Returns:

a collection of the names of all the protocols referenced in this SDRF