JNETS

Runs only on Java 1.5 or above.
For large networks, it is advised that you give the JVM more memory than default. I generally use 1G (more than enough).

JNets was written by Jamie MacPherson. Any problems or questions should be directed to:

	jamie.macpherson@postgrad.manchester.ac.uk

JNets is based on InterView by John Pinney. InterView uses the TouchGraph package.

___________________________________________________________________________________________

HOW TO RUN

To run the application, go to the JNets_application folder in the downloaded package and double click the JNets.jar file. If you have Java 1.5 or above, JNets should start up and the JNets user-interface should appear. If this does not happen, try looking at your console to see if you can debug the issue. If you get stuck, please contact the above email address.


___________________________________________________________________________________________

BACKGROUND

JNets -- dynamic, lightweight, platform independent software designed for PPI network visualisation and analysis. 

The motivation behind JNets development is to create a tool that is sufficiently lightweight that it can be deployed as an applet or application, that is also capable of useful network analysis, based upon biological annotation that accompanies the graph data. The specific aim was that groups of proteins (nodes) and interactions (edges) can be created using SQL-like user queries of the accompanying biological annotation and that these groups can then be analysed to explore relationships between proteins in terms of their annotation.

____________________________________________________________________________________________

INPUT FILES IN DETAIL

The input file supplies JNets with network data. JNets takes two kinds of network data, XGMML and GraphML. You are advised to use XGMML (eXtensible Graph Modelling Markup Language) input files; as the file format is explained here. However, when you have an XGMML file, you can load it in to JNets and then "save as GraphML", this will convert it for you.

Getting the input file right is important*, or JNets will either fail to work completely, or not run properly.

*For easy production of an XGMML file, you can use tab-delimited data and convert it using JNets, this is the best way to create an input file. To do this read the EASY XGMML FILE CREATION section further down the page. 

An example XGMML file is given at the end of this file, you can probably look at it to learn most of what is going on, however, there are some things you may miss, so please read this.

More general info about XGMML can be found on the web if you google it. BUT there are specific things that JNets needs for it to work and be fully functional. These fall in to 5 categories: 

(1) a XML header line. This should be at the top of your xgmml document and look something like this:

	<?xml version="1.0" encoding="UTF-8"?>

(2) a graph element. This is the element inside which all other data should be contained. A graph element needs 4 things. The xmlns attribute, the xmlns:xsi attribute, the id attribute and the  attribute. Without these your XGMML may not work properly. An example graph element, consisting of a start and an end tag is shown below

	<graph xmlns="http://www.cs.rpi.edu/XGMML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="graph 1" name="My favourite graph">
		(put all the other data in this tag)
	</graph>

(3) a set of nodes. In a PPI network, these represent proteins. Below is the most basic example of a node entry. Each tag is then explained.

  <node id="155871" name="Tat protein">
    <att name="ng" type="string" label="node group" value="HIV accessory proteins" />
    <att name="nx" type="double" label="node x-coordinate" value="70.0" />
    <att name="ny" type="double" label="node y-coordinate" value="-100.0" />
    <att name="nlo" type="boolean" label="node label on" value="true" />
    <att name="ns" type="int" label="node size" value="12" />
    <att name="nf" type="boolean" label="node fixed" value="false" />
  </node>

The node tag must have an id and a name attribute. The id attribute must be distinct between nodes, the name does not have to be distinct (but this is advisable for your sake). The name tag is the label that will appear on the node.
Within the node tag, there are 6 child "att" tags; it is recommended that you use all of these. The most important thing to note is the "name" attribute of the att tags. These are special keys that JNets uses to identify these particular node attributes.

	ng = node group, this is the group of nodes that the this node will belong to, this group will appear in the key in the JNets GUI.
	nx = the x-coordinate of the node. This can be a decimal or an integer value, positive or negative.*
	ny = the y-coordinate, as above.*
	nlo = a boolean to say whether the node label i.e. the name of the node, is displayed on the node at startup.*
	ns = the size of the node in pixels when the node label is turned off. The default value is 12.*
	nf = a boolean to say whether the node is fixed when the graph is rehndered, or whether the node will be free to move around n the spring layout*

	

(4) a set of edges. In a PPI network, these represent interactions. Below is the most basic example of an edge element.

  <edge id="e1" name="protein interaction 1" source="155871" target="58">
    <att name="et" type="int" label="edge type" value="0" />
    <att name="eg" label="edge group" type="string" value="HIV-human interactions" />
  </edge>

The edge tag must have an id and a name attribute. The id attribute value must be unique between edges. In addition, edge elements must have a source and a target attribute. The values of these correspond to node ids and are the two nodes that the edge connects.
Within the edge tag there are 2 additional "att" tags; you must include the first of these. The most important thing to note is the "name" attribute of the att tags. These are special keys that JNets uses to identify these particular edge attributes.
	et = edge type; this is the type of edge that JNets draws between nodes. This must be one of the following integer values:
		0 = non-directional
		1 = directional, an arrow-head will be drawn in the direction of the target node.
		2 = bi-directional, both ends of the edge will have an arrow head drawn.
	ecg = edge colour group, this is the group of edges that the this edge will belong to, this group will appear in the key in the JNets GUI.*

*don't worry, these can be changed in JNets once it is running, they're just starting values.

(5) annotations that accompany a node or edge. These are not a necessity, but play a large part of the main JNets functionality. These take the form of additional attribute tags within node and edge elements. Below are the same node and edge elements shown above, but this time some extra annotation has been added.

   <node id="155871" name="Tat protein">
    <att name="ng" type="string" label="node group" value="HIV accessory proteins" />
    <att name="nx" type="double" label="node x-coordinate" value="70.0" />
    <att name="ny" type="double" label="node y-coordinate" value="-100.0" />
    <att name="nlo" type="boolean" label="node label on" value="true" />
    <att name="ns" type="int" label="node size" value="12" />
    <att name="nf" type="boolean" label="node fixed" value="false" />
    <att name="a1" type="int" label="number of interactions with human" value="774" />
    <att name="a2" type="string" label="alternative name" value="Trans-activator accessory protein" />
    <att name="ma1" type="string" label="general activity notes" value="Transcription factor activation" />
    <att name="ma1" type="string" label="general activity notes" value="Upregulates matrix proteins" />
    <att name="ma1" type="string" label="general activity notes" value="binds histones" />
  </node>

  <edge id="e1" name="protein interaction 1" source="155871" target="58">
    <att name="et" type="int" label="edge type" value="0" />
    <att name="eg" label="edge group" type="string" value="HIV-human interactions" />
    <att name="a3" type="boolean" label="direct interaction" value="false" />
    <att name="a4" type="double" label="confidence p-value" value="0.000003422" />
    <att name="a5" type="String" label="geneRif" value="HIV-1 Tat induces actin cytoskeletal rearrangements through p21-activated kinase 1 (PAK1) and downstream activation of the endothelial NADPH oxidase, an effect that is lost by introduction of mutations into the Tat cysteine-rich or basic domains"/>
  </edge>


Annotation names, to be recognised must either begin "a", or "ma". Begin "a" if only one value is present per node/edge element. Begin "ma" if more than one value can be present for one node/edge element. Be careful to get this right as it affects JNets functionality. Attribute names must all be distinct. The type attribute can either be string, double, int or boolean. The value must correspond to this type.
Please note: There are some annotation names that you should not use because JNets will assign some internal identifiers to annotations it will automatically build. These ids are:
	"a_id" -- The ids of the nodes
	"a_eid" -- The ids of the edges
	"a_nl" -- The labels of the nodes
	"a_el" -- The labels of the nedges
	"ma_nnon" -- The node-neighbours of nodes
	"ma_enon" -- The edge-neighbours of nodes
	"a_nsoe" -- The source-node of edges
	"a_ntoe" -- The target-node of edges

These annotations are available for you to use when making subgroups. Plus, if you build a config file with custom menu items, you can use these automatic annotations as well as the ones that you have supplied.

In addition to these, you can include "groupcolor" tags these set the color of node or edge groups to the color you want. These are place within the "graph" tags along with the nodes and edges (not inside each node or edge tag). They look like this:

<groupcolor name="HIV Proteins" value="244,110,132" />
<groupcolor name="Human Proteins" value="0,244,122" />
<groupcolor name="HIV-Human PPI" value="192,192,192" />

The colors are represented as RGB values. Remember that the name is case sensitive!


____________________________________________________________________________________________________


EASY XGMML FILE CREATION

Writing this all out by hand is not practical, even producing a script that makes a file that adheres to this is not, for most of us, an easy task.
So, instead I advise that you use tab delimited data and the JNets convertor. The tab delimited data should be in three sections; nodes, edges and annotation. One node per line, one edge per line, one annotation value per line.

Nodes in the format:

id	name	group	x-coord	y-coord

Edges in the format:

id	name	group	sourceNodeId	targetNodeId	edgeType**

** for a definition of edge type see above, put as 0 for a non directional edge, 1 for directional, 2 for bidirectional

Annotation in the format:

annotId	name	valueType	forElementType	multipleAnnotationBoolean	elementId	value

The annot id should always begin with either "a" or "ma". Use "a" unless more than one annotation value can be assigned to a single element, for a that annotation. 
The value type must be on of {int, double, string, boolean}.
The forElementType must be one of {node, edge}.
The multiple annotation boolean should be false unless more than one annotation value can be assigned to a single element; in this case the value should be true AND the annotation id should begin "ma".

Here is an example of a tab delim file:


1	one	proteins	7.0	1.0
2	two	proteins	3.2	45.6
3	a	drugs	22.1	-12.3
4	b	drugs	11.1	-56.3
e1	e1	PPI	1	2	0
e2	e2	DTI	3	1	0
e3	e3	DTI	4	2	1
e4	e4	DDI	4	3	2
a1	no of Interactions	int	node	false	1	2
a1	no of Interactions	int	node	false	2	2
a1	no of Interactions	int	node	false	3	2
a1	no of Interactions	int	node	false	4	2
a2	description	string	edge	false	e1	agonistic
a2	description	string	edge	false	e2	agonistic
a2	description	string	edge	false	e3	antagonistic
a2	description	string	edge	false	e4	antagonistic
ma1	multi annot example	double	node	true	1	1.1
ma1	multi annot example	double	node	true	1	1.9
ma1	multi annot example	double	node	true	1	1.5
ma1	multi annot example	double	node	true	1	1.34
ma1	multi annot example	double	node	true	2	101.82
ma1	multi annot example	double	node	true	2	100.18
ma1	multi annot example	double	node	true	2	97.89
ma1	multi annot example	double	node	true	2	103.85
ma1	multi annot example	double	node	true	3	0.24
ma1	multi annot example	double	node	true	3	0.2242
ma1	multi annot example	double	node	true	3	0.11
ma1	multi annot example	double	node	true	3	0.79
ma1	multi annot example	double	node	true	4	138.5
ma1	multi annot example	double	node	true	4	15.314
ma1	multi annot example	double	node	true	4	12.212
ma1	multi annot example	double	node	true	4	11.21
ma1	multi annot example	double	node	true	4	11.29
ma1	multi annot example	double	node	true	4	18.15
ma1	multi annot example	double	node	true	4	12.34
ma1	multi annot example	double	node	true	4	11.22


To perform the conversion, run JNets and in the File menu, select Convert Tab-delim. Browse and select your tab delim file and press the Build XGMML button, then choose the save location.

____________________________________________________________________________________________

CONFIG FILES

The best way to make a config file is to take the configTemplate.config file that is found in the JNets package download. It is best to examine this file in an editor that colours things in so that the comments and the actual XML tags are distinct (plenty freely available on the web i.e. Google for 'free XML editor'.
There are comment lines in this file that explain exactly what you need to do to create a config file; what attributes it needs and so on.
Much of this customization will involve setting the enable attributes in tags to enable JNets features. In addition to this, a custom menu (drop down menu) template is given; details of the custom menu and the items in the custom menu, must be given in the config file. The custom menu items contain filters, to filter nodes and edges from the main graph. An autofilter example and a manualfilter example are given. An autofilter will group elements according to their value for ONE annotation, while a manual filter can use any combination of user-defined filters. A manual filter puts nodes and edges in to either a true or false group depending whether the element meets all the criteria for the given annotations. To use these you will have to fill in the filter details in the config file. Any number of these filters, custom menu items and custom menus may be configured. 

If you have any problems creating a config file please contact jamie.macpherson@postgrad.manchester.ac.uk for help.


____________________________________________________________________________________________




USING JNETS

The File menu
----------
Load Network Data = Load in an XML file using the file menu, you can then try some of the JNets functions.
Load Layout as Binary = load a saved binary of a network (I wouldn't bother using this)
Save graph = save graph either as XML format or as simple list data (list data is for parsing, getting node ids from groups etc)
Convert tab-delim = convert tab delimited data to XML format
Export as PNG/PDF = export the network as picture
Quit = quit!

The Mode menu
----------
Topology = normal network layout
Container = piuts nodes from the same group in a container with a size proportional to the number of nodes. Only suited to smaller networks.

The Display menu
__________
Neighbour tags = show/hide tags when node neighbours are hidden
border = show borders round nodes when they are stuck down.
Show/Hide all labels = turn node labels on or off
Stick/free all nodes = set node behaviour when movement is on
Show all nodes = show any hidden nodes
Toggle text colour = make node label text white/black

The Subgroups menu
----------
This is the main JNets tool menu.

Create subgroups from whole network = bring up the subgroup menu to act on the whole network
Create subgroups from node group = bring up the subgroup menu to act on a certain node group
Create subgroups from edge group = bring up the subgroup menu to act on a certain edge group
Regroup all = regroup all nodes in to one group and all edges in to one group
Regroup all nodes = regroup all nodes in to one group
regroup all edges = regroup all edges in to one group
Reset all groups = reset the groupings to how they are in the input file 
Reset node groups = regroup all node groupings to how they are in the input file 
regroup all edges = regroup all edge groupings to how they are in the input file
investigate edit whole network = bring up the tool panel for the whole network
investigate edit node group = bring up the tool panel for a certain node group
investigate edit node group = bring up the tool panel for a certain edge group

The subgroups panel
---------
This is used to create edge and node groups from pre-existing groups. 

The first tab is the "Subgroup Options" tab: Use this to make some basic choices about what group you want to create:

First select whether you want to create a set of subgroups automatically (uses all different values from one annotation), or manually which selects a group of nodes that meet certain criteria that you specify (using as many combinations of annotations as you like).
If you select manual grouping, enter a name for the group you are creating in to the text box.

Then select what you actually wish to group. You can obviously create node groups from already existing node groups (and edge groups from other edgegroups). BUT ALSO you can create node groups from edge groups (as an edge knows what nodes it is in contact with), a node group from an edge group (as nodes know what edges are in contact with them), or both a node group and an edge group at the same time (uses a combination of these).

The second tab is the "Filter Options" tab. On the left of this, select an annotation based on the element type (node/edge) and then the annotation id and name. If you have chosen to do an automatic filter, this is sufficient information, just press the add button, then OK. If you have chosen a manual filter, select the constraint such as "==" or "contains" (the options you get depends on the data type) and select the limit (what the annotation == or what the annotation contains.) Then press add. You can then use the and/or and brackets buttons on the left to add separators between a number of queries, just keep adding more until you are done. Remember to close the right number of brackets. Press OK when you are done. At any time you can delete parts of your query by selecting on them and pressing the delete button.

When you press okay the legend on the left and the network should show any new groups you've created.

The Investigate/Edit panel
---------
This is used to find things out about node groups and edge groups and also edit them in the network.

At the top some basic stats are given. This will say how many nodes and how many edges are part of this group and also the mean degree (with standard deviation).

You can do statistical significance tests on the group to find out whether certain values of annotation are over or under represented in this group. For non-numerical data you can select all values that the annotation takes to test at once but for numerical data you must select a limit. When you calculate the test, a new panel of results will appear, showing how many occurrences of the annotation are present in the whole network, how many are present in the group and the p-value (by Fishers exacvt test or chi squared test for larger samples). An indicator also shows whether the feature is over or under represented a "+" shows that the number if incidences in the group (of the annotation you selected) is above the proportion for the whole network, a "++" means the same but p<0.05 and a "+++" means the same but p<0.001. The same can be applied to "-" signs but this refers to under-representation in the group.
You can save your output as a basic text file by pressing the Save button.

The Edit actions are quite self-explanitory, select one then press Go and this will only affect the group you have selected. One of the most useful is the "Rename group" tool, using this you can rename groups, but also merge one group with another if you give it the same name.

Annotation can be added to a group you have created by using the bottom section. Two different values must be given; the value to nodes/edges in the group and the value to the nodes/edges not in the group.



The legend
----------
Node and edge groups will be shown in the key on the left hand side. To alter the colour of any of these, click on the key where the name is shown, then select a new colour in the colour picker that appears. 

The Top slider and Combo
----------
This slider can be used to zoom in and out, rotate the network and alter the spring weight (the amount that edges pull nodes coser together)

Left Click on nodes
----------
Hides all the nodes that are not joined to that node by an edge. The hidden nodes are within nodes surrounding that node you double clicked on, how many nodes are hidden is shown as a number. To re-show these nodes, click on those little numbers, or go to the display menu and select "Show all Nodes".

Right Click on nodes
----------
This gives you a little menu of stuff to do with nodes.
Show Label = show the label of this node
Focus on this node = hide all nodes that are not within two edges of this node.
Collapse node = hide all nodes that are only attached to this node
Hide node = hide this node
Free node/Stick node = free/stick this node, the behavior this node has when movement is on.
Get node info = get a popup menu telling you what JNets knows about this node, including the annotation it has.

Right Click on Background
----------
Shake= give the network a shake, this can help it reach a better equilibrium if it is in a local optima.
start/stop motion =  starts or stops the motion of the network.

Left Click and hold on Background
----------
Moves the network around the screen

Left Click and hold on Node
---------
Moves the node around

Right Click on edges
---------
Relax edge = reduces the spring in the edge
Tighten edge = incereases the spring in the edge
Hide edge = hides the edge, tabs appear in neighbour nodes
Get edge info = brings up a panel summarising what JNets knows about this edge, including the annotation that accompanie it.

_______________________________________________________________________

EXAMPLE FILES

Example XGMML files have been supplied with this package. The most comprehensive is the hivNetwork.xgmml file. This has all human genes that interact with HIV-1 proteins and several annotations. There is also a config file called hivNetwork.config that can be loaded for this network; this has several predefined network views (based on interaction descriptions and Gene Ontology terms). 

There are also two smaller networks that contain targets to immunosuppressant drugs. They are coloured according to the action that HIV has on them.




