This documents explains the detailed structure of the VisML (VisANT xml) format. It serves as an reference for you to create/parse VisML files.

Note:

A specific version notation will be presented for all new elements and attributes that are added after VisML 1.32.

All optional attributes and elements can be ignored in VisML and default values will be used in VisANT.

Detailed Explanation

Root  element: <VisAnt>

VisML is the XML format designed for VisANT to store the information of a network. A VisML file starts with:

  <?xml version="1.0" ?>

and is rooted at element <VisAnt> , as shown as following:

- <VisAnt ver="1.35" species="hsa" nodecount="3" edgeopp="true" fineArt="true" autoFit="true" double_click="gcard">
  <method name="M0029" desc="monoclonal antibody" weight="null" type="E" visible="true" color="0,182,212" />
  ............
  <method name="M0027" desc="Interaction adhesion assay" weight="null" type="E" visible="true" color="255,0,212" /> 

 <exLink id="gcard" menu_name="GeneCard" URL="http://bioinfo.weizmann.ac.il/cards-bin/carddisp?" />

 <exLink id="hgnc" menu_name="Flybase Report" URL="http://flybase.net/.bin/fbidq.html?" />

+ <Nodes>

+ <Edges>
  </VisAnt>

<VisAnt> element has following attributes:

ver: indicates the version of visML, this attribute is required. However, it is used only for internal control. For most users, simply put an number that is bigger than 1.32 will be fine.

Note: If you create your own VisML, please make sure the VisAnt tag starts with ver attribute, i.e., it should start like  <VisAnt ver=

         This is because it has been used to ensure the compatibility of early VisML file. This restriction will be removed after VisANT 4.0

         and old version of VisML (1.0) will no long supported.

species: indicates the species of the network, this attribute is required. If the species of your network is not species-specific, or not in the complete list of species supported in VisANT, simply put "uno" to indicate that the species is "unkown". This attribute is useful if you need to query database for further information of your network. For VisANT 2.46 and above, all corresponding database queries will be disabled if the species is "unknown".

nodecount: indicates the total number of nodes, this attribute is required. Be aware it is the number of total visible and invisible nodes.

edgeopp: used for meta graph only, optional, default value is false.

fineArt: used to indicate whether to use better graph drawing, such as thick line, optional, default value is true. Turn it off for large network

autoFit: used to indicate whether need to fit the network to the default network window, optional, default false.

double_click: used to change the default behavior when user double-clicking a non-meta-node, if the value of this attribute matches the id attribute of <exLink> double-clicking on the node will launch the link in default browser..

db_online: used to indicate whether need to query database, optional, default is true. This option will be overwritten if the species is unknown. Available after visML 1.33.

layout: used to layout the network with specified type of layout, optional. This attribute supports all type of layout that is available in VisANT. Available after visML 1.33. Note that this is a read-only attribute. Therefore if a file with this attribute is loaded into VisANT and is later saved by the user, this attribute will be gone in the new-saved file. Here is the list of possible values of this attribute: circle, spoke, scramble, relax, embedded, and elegant. The later three can have additional parameter for the number of iterations of the layout in the format of embedded:100, as an example. The default iteration is 250. Be aware that this number should be bigger if you have a large network. Here is a list of examples with different variants of this optional attribute:

       layout="relax", load this network     |    layout="elegant", load this network

    layout="embedded", load this network    |    layout="embedded:100", load this network

    layout="circle", load this network     |    layout="spoke", load this network    |    layout="scramble", load this network   

 

net_size: use to specify the canvas size of the network in the format of "width, height",  Available after visML 1.34

fs: use to specify the font style, 0 for plain, 1 for bold, and 2 for italic.  Available after visML 1.34

Element <VisAnt> has several child element, a list of  <method> and  <exLink>, and one <Nodes> and one <Edges>.

 

Element: <method>

The <method> element is used to represent the method that detects the association between biological components, such as protein/gene. VisANT use method to color the edge (so far there is no other way to customize the edge color except assigning a new color to the corresponding color of the method of the edge). An example of method element has been shown above, it has following attributes:

name: the method id used in VisANT, required. If you need to have your own method, please put the id in the range M7000-M7999 so that VisANT will not enable querying all interaction of this method in the databases.

desc: the description of the method, required.

type: the type of the method, either "E" or "C" to indicate experimental or computational, required.

visible: indicates whether the edge determined by this method only is visible or not, default is true, optional.

weight: the reliability score of the method, optional, not used so far.

 

Element: <VScreen>

 

The <VScreen> is an optional element used to retain the zooming level of the network. It is not suggest for user to customize it. In case you do need this element, it is highly suggest you use VisANT to zoom at the level you prefer and then save the network. You can then copy the elements into your own VisML file.

 

 

<VScreen x1="196" y1="154" x2="479" y2="367" w="692" h="585" ps="14" />

 

Element: <exLink>

The <exLink> element allows you to add links to external databases for both node and edge, in associated with element <id>. When the attribute name of element <id> under <data> matches the attribute name of element <exLink>, an menu will be created in VisANT with the name determined by the attribute menu_name in element <exLink> and click the menu will launch the default browser with the URL determined by the URL attribute of <exLink> and the value attribute of <id> element under <data> element. For an example, giving an element:

 

 <exLink id="mim" menu_name="OMIM" URL="OMIM=http://www.ncbi.nlm.nih.gov/entrez/dispomim.cgi?id=" />

 

and a <VNodes> element as:

 

- <VNodes x="343" y="285" counter="2" w="14" h="14" labelOn="true" linkDisplayed="true" linkLoaded="true" extend="false">
  <vlabel>ASPP2</vlabel>
- <data name="TP53BP2" index="0" type="0" alias="ASPP2,53BP2,HGNC:12000,PPP1R13A">
  <id name="gi_gene" value="51511461" />
  <id name="mim" value="602143" />
- <link to="TP53" method="M0048:8875926">
  <id name="hgnc" value="12000" />
  <id name="SP" value="Q13625" />
  </link>
  <link to="PFTK1" method="M0010:12694406" />
  </data>
  </VNodes>

A menu named OMIM will be available under menu Nodes/Available Links in VisANT which will launch following URL:

 

http://www.ncbi.nlm.nih.gov/entrez/dispomim.cgi?id=602143

 

when the node is selected.

 

Using same way we can create cross-link menu for the edge if the corresponding <id> element of the <link> matches the id attribute of <exLink>

 

Element: <Nodes> & <VNodes>

The <Nodes> element contains a list of <VNodes> elements that is shown below:

 

- <VNodes x="332" y="275" counter="2" w="16" h="16" labelOn="true" linkDisplayed="true" linkLoaded="true" extend="false" size="16" ncc="255 0 204" labelSize="19" labelPos="0" esymbol="false">
  <vlabel>ASPP2</vlabel>
- <data name="TP53BP2" index="0" type="0" alias="ASPP2,53BP2,HGNC:12000,PPP1R13A">
  <desc>tumor protein p53 binding protein; 2|1q42.1</desc>
  <id name="original" value="ASPP2" />
  <id name="gi_protein" value="33860140" />
- <link to="TP53" method="M0048:8875926">
  <desc>edge description</desc>
  <id name="SP" value="Q13625" />
  <id name="hgnc" value="12000" />
  </link>
  <link to="PFTK1" method="M0010:12694406" />
  </data>
  </VNodes>

Please be aware that the visual information in general is separated from actually information of a biological entity. Please reference VisANT data model for more information. Element <VNodes> has following attributes:

x: x coordinate, required.

y: y coordinate, required.

counter: reference counter, its value equals to the number of links connecting to the node. It is also used to determine whether the node is visible or not, set it to at least 1 if the node should be visible, required.

w: width of the node, required.

h: height of the node, required.

labelOn: determine whether the node label is visible, optional, default false.

linkDisplayed: used to indicate whether all the nodes link is displayed, special designed for step-wise expansion of the interaction network, optional, default false. When it is true, the node show "-" sign, otherwise, "+" sign.

size: indicated whether the node has been queried against database , optional, default false. Set it to be true if you do not want to query database when double-click the node.

extend: designed for step-wise expansion of the interaction network, optional, default true. Set it to true if you do not want the node position to be changed when double-click the node.

size: node size, optional. Default -1:auto, Range: 4-30.

ncc: RGB value of node color, optional.

labelSize: size of the node label, optional. Default -1:auto, Range: 6-25.

labelPos: position of the label, optional. Default -1:auto, 0:center, 1:left, 2:right, 3:above, 4:below

esymbol: determine whether to show the extension symbol (+/-) or not, optional, default is true.

group: if the node is in a group, this attribute represents the corresponding group id, optional.

 

 

Element <VNodes> can has three child elements:

<vlabel>: is used to customize the node label, optional

<data>: and is used represent the information of a node except those visual properties, required.

<Dup>: is only presented if the node has duplications. Optional. There can be a list of this elements in case of multiple duplications.

<children>: if the node is meta-node (group node, data type 3-7), this element will appear and contains the ids of the nodes belong to the group delimited using ",".

 

Element: <data>

This element has following attributes:

name: default node name, required.

index: integer used to identify node, should be different for each <data> element, including <Dup>, required.

type: type of the node, optional, default 0. built in value=0:normal protein/gene, 1:chemical compound, 2:KEGG Map,3: general group node, 4:Protein Complex, 5:Node of Go Term, 6:Pathway Node, 7:KEGG group node, >=100:user added

alias: a list of alias delimited ",".

 

The <data> element may have following child elements:

<desc>: description of the node, will be shown in the tooltip when mouse-over the node, optional.

<id>: external database ids of the node, optional. If its name attribute matches the id attribute of <exLink> element, a menu will be created to allow the http link to external database as mentioned earlier. There can be more than one id elements.

<link>: this element represents a link starts from the node represented by element, and stops at the node indicated by the to attribute, optional (a node can have no links/edges). It needs to be aware that one edge may have more than one links.

<group>: this elements will appear if the node represented by the data element is in groups. This element has two attribute: name determines the type of group ("common" for most cases), while the value represents the group ids delimited by ",", in case there are more than one group (in such case, the node itself must have duplications).

 

 

Element: <link>

This element has following attributes:

to: the node name that this link connects to, required.

method: the method id associated with the link. If there is a literature reference corresponding pubmed id can be appended as the format shown below. required.

toType: integer number to determine the type of the to-end of the edge, optional, default is 0. Its value can be ranged (please reference KEGG database for the meaning of different edge type:

fromType: integer number to determine the type of the from-end of the edge, optional. The value has the exact same range as toType.

 

In addition to the attributes, the element can also have <desc> element and <id> element similar to <data> element. As mentioned earlier, the <id> element can also be used to create HTTP link by matching to the id attribute of <exLink>. element.

 

Element: <Dup>

In case of duplication, this element will be appear under <VNodes> element. this element describes visual properties of the duplicated nodes and have similar attributes as <VNodes>, except following:

uid: the identification of the duplicated node, required.

group: if the duplicated node is in a group, this attribute denotes the corresponding group id. optional.

 

- <Nodes>
- <VNodes x="305" y="363" counter="1" w="135" h="82" linkDisplayed="true">
  <vlabel>5</vlabel>
  <children>TP53BP2_0,TP53,</children>
  <data name="5" index="5" type="3" />
  </VNodes>
- <VNodes x="269" y="156" counter="2" w="16" h="16" labelOn="true" linkDisplayed="true" linkLoaded="true" extend="false" size="16" ncc="255 0 204" labelSize="19" labelPos="0" group="3" esymbol="false">
  <vlabel>ASPP2</vlabel>
- <data name="TP53BP2" index="0" type="0" alias="ASPP2,53BP2,HGNC:12000,PPP1R13A">
  <desc>description of duplicated node</desc>
  <id name="original" value="ASPP2" />
  <id name="gi_protein" value="33860140" />
  <id name="gi_gene" value="51511461" />
  <id name="mim" value="602143" />
  <id name="SP" value="Q13625" />
  <id name="O_N_hsa" value="TP53BP2" />
- <link to="TP53" method="M0048:8875926">
  <desc>edge description</desc>
  <id name="SP" value="Q13625" />
  <id name="hgnc" value="12000" />
  </link>
  <link to="PFTK1" method="M0010:12694406" />
  <group name="common" value="3,5" />
  </data>
- <Dup x="248" y="394" counter="1" w="14" h="14" linkDisplayed="true" index="7" uid="TP53BP2_0" group="5">
  <vlabel>ASPP2</vlabel>
  </Dup>
  </VNodes>
  </Nodes>
- <Edges>
  <VEdge from="TP53BP2" to="PFTK1" />
  <VEdge from="TP53BP2" to="TP53" elabel="edge label" la="True" />
  </Edges>

 

Element: <Edges> & <VEdge>

As shown above, edges are listed under <Edges> element named as VEdge.

 

Element <Edges> has following attributes:

thick_line: the option to use the line thickness to represent the edge weight, default is true, optional.

color_line: the option to use the line color to represent the edge weight, default is false, optional.

exclude_meta: the option to exclude the metaedges when use weight cutoff, optional.

Following lists an example of this element with all attributes on.

<Edges thick_line="false" color_line="true" exclude_meta="true">

 

Element <VEdge> has following attributes:

from: the id of from node, required.

to: the id of to node, required.

elabel: the label of the edge, optional.

la: boolean flag to determine whether the edge label shown be visible, optional, default false.

 

The complete VisML file used in this document can be downloaded here: Sample VisML file, which can also be directly launched using following URL:

 

http://visant.bu.edu:8080/vserver/DAI?command=link&location=http://visant.bu.edu/misi/sample_visml.xml

 

and following figure shows the image of the corresponding network: