KeyNodes hub

KeyNodes hub is a BioHub which can be used in Regulator search and Effector search analyses as well as several helper analyses. Its main purpose is provide abilities to traverse through gene/molecules network represented as directed weighted graph.

Implementation details

All the KeyNodes hubs must extends the KeyNodesHub class. If the hub is based on MySQL database, it's better to extend KeyNodesSqlHub class as it provides additional support for handling SQL connection. Both classes are parametrized by type which represents hub node.

Nodes representation

Hub node (molecule or gene) can be represented by any type. Sometimes it's ok to use Integer, String, sometimes it's better to create your own class. The Object.toString() of this class should produce stable accession number for the molecule or gene which belongs to the registered reference type. The Object.equals(Object) and Object.hashCode() methods must be redefined for node type. Nodes with the same string representation must be equal and have the same hashCode.

To support hub nodes you should override the following methods:

• BioHubSupport.getSupportedInputTypes(): return an array of possible reference types which can be converted to internal node type. Usually it's only one type.
• KeyNodesHub.getElementConverter(): return an ElementConverter object which is capable to convert internal nodes from/to Element objects:
  • ElementConverter.toNode(Element) method should create a hub node object using Element. The toString() method of the resulting node should produce the same string as Element.getAccession().
  • ElementConverter.fromNode(N) method must create a new Element object by existing node. It must have the full path set, preferably linked to the existing element (substance/protein/gene/etc.) in the repository.

Edges representation

Hub edge must implement the HubEdge interface. It has the following methods:

• HubEdge.createElement(KeyNodesHub) method must create a new

Element object by existing edge. It must have the full path set, preferably linked to the existing element (reaction/semantic relation) in the repository.

• HubEdge.getRelationType(boolean) method must return relation type string (see the constants in RelationType class).

Additionally a toString() method must return an accession number for given relation.

To spare memory it's recommended to make both node and edge objects as simple as possible. They should not be linked to each other or to the graph. Also edges should not contain the weight: it might be changed by decorators.

Graph represenation

The graph is represented by HubGraph interface. It has the following methods:

• HubGraph.nodes() method must return the stream of all nodes in the graph
• HubGraph.hasNode(N) method must return true if given node appears in the graph
• HubGraph.visitEdges() method must call given visitor for all the nodes directly adjacent to supplied start node in either upstream or downstream direction.

Usually it's unnecessary to implement this interface. Instead you may use a MemoryHubGraph implementation. To create it, construct a stream of HubRelation objects which represent single relation from given start node to given end node with given edge object and given weight. After that collect this stream with MemoryHubGraph.toMemoryHub() collector.

Graph chaining

The graphs can be modified by set of decorators supplied by user during analysis. To support this feature in your hub you should define a hub cache. The easiest way is to store a MemoryHubCache instance into hub field and use it when defining KeyNodesHub.getHub(TargetOptions, String[]) method. You must supply a function which will create the base hub (for example, read something from SQL database). The hub cache will take care on caching and chaining with decorators.