help/html/features/annotationsFormat.html

   1 #-------------------------------------------------------------------------------
   2 # Jalview - A Sequence Alignment Editor and Viewer (Version 2.5.1)
   3 # Copyright (C) 2010 J Procter, AM Waterhouse, G Barton, M Clamp, S Searle
   4 #
   5 # This file is part of Jalview.
   6 #
   7 # Jalview is free software: you can redistribute it and/or
   8 # modify it under the terms of the GNU General Public License
   9 # as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  10 #
  11 # Jalview is distributed in the hope that it will be useful, but
  12 # WITHOUT ANY WARRANTY; without even the implied warranty
  13 # of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  14 # PURPOSE.  See the GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  17 #-------------------------------------------------------------------------------
  18 <html>
  19 <!--
  20  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.5)
  21  * Copyright (C) 2010 J Procter, AM Waterhouse, G Barton, M Clamp, S Searle
  22  *
  23  * This file is part of Jalview.
  24  *
  25  * Jalview is free software: you can redistribute it and/or
  26  * modify it under the terms of the GNU General Public License
  27  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  28  *
  29  * Jalview is distributed in the hope that it will be useful, but
  30  * WITHOUT ANY WARRANTY; without even the implied warranty
  31  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  32  * PURPOSE.  See the GNU General Public License for more details.
  33  *
  34  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  35 -->
  36 <head>
  37 <title>The Alignment Annotations File</title>
  38 </head>
  39
  40 <body>
  41 <p><strong>The Alignment Annotations File</strong></p>
  42 <p>Alignment annotations can be imported onto an alignment since
  43 version 2.08 of Jalview, via an annotations file. It is a simple ASCII
  44 text file consisting of tab delimited records similar to the <a
  45         href="featuresFormat.html">Sequence Features File</a>, and introduced
  46 primarily for use with the Jalview applet.</p>
  47 <p>Alignment annotations files are imported into Jalview in the
  48 following ways:<br>
  49 <ul>
  50         <li>from the command line<strong><pre>
  51  -annotations &lt;<em>Annotations filename</em>&gt;</pre></strong></li>
  52         <li>Dragging an annotations file onto an alignment window</li>
  53         <li>Via the &quot;Load Features / Annotations&quot; entry in the <strong>File</strong>
  54         menu of an alignment window.</li>
  55 </ul>
  56 </p>
  57 <p><strong>Annotations File Format</strong></p>
  58 <p>The File consists of lines containing an instruction followed by
  59 tab delimited fields, and any lines starting with &quot;#&quot; are
  60 ignored. The first non-commented out line of a valid Annotations file
  61 must begin with :<strong><pre>JALVIEW_ANNOTATION</pre></strong></p>
  62 <p>A row of annotation is added with a line like <strong><pre><em>GRAPH_TYPE</em>&#9;<em>Label</em>&#9;<em>Values</em></pre></strong></p>
  63 <p>The <em>GRAPH_TYPE</em> field, which appears first, defines the
  64 appearance of the annotation row when rendered by Jalview. The next field is the row label for the annotation. The final <em>Values</em> field contains a series of &quot;|&quot;
  65 separated value fields. Each value field is itself a comma separated list of fields of a particular type defined by the annotation row's
  66 GRAPH_TYPE. The allowed values of GRAPH_TYPE and the format of their respective value fields (with the trailing &quot;<strong>|</strong>&quot; symbol) are shown below:<ul>
  67         <li>BAR_GRAPH<br>
  68         Plots a histogram with labels below each bar.<br>
  69         <em>number</em>,<em>text character</em>,<em>Tooltip text</em></li>
  70         <li>LINE_GRAPH<br>
  71         Draws a line between values on the annotation row.<br>
  72         <em>number</em></li>
  73         <li>NO_GRAPH<br>
  74         For a row consisting of text labels and/or secondary structure symbols.<br>
  75         <em>{Secondary Structure Symbol}</em>,<em>text label</em>,<em>Tooltip text</em><br>
  76         Currently supported secondary structure structure symbols are <em>H</em> (for   helix) and <em>E</em> (for strand)</li>
  77 </ul>
  78 Any or all value fields may be left empty, as well as the BAR_GRAPH's
  79 text character field, and either or both of the text-label and secondary
  80 structure symbol fields of the NO_GRAPH type annotation rows.</p>
  81 <p>Color strings can be embedded in a value field by enclosing an RGB triplet in square brackets to colour that position in an annotation row.
  82 </p>
  83 <p>You can associate an annotation with a sequence by preceding its
  84 definition with the line:
  85 <pre>SEQUENCE_REF&#9;<em>seq_name</em>&#9;<em>[startIndex]</em></pre>
  86 All Annotations defined after a SEQUENCE_REF command will then be
  87 associated with that sequence, and the first field in the Value field
  88 list will (optionally) be placed at the <em>startIndex</em>'th column.</p>
  89 <ul><em>New in Jalview 2.4</em>: the tooltip displayed when the mouse is moved over the row
  90 label for sequence associated annotation  gives the associated
  91 sequence's name followed by the annotation row's description.<br/>
  92 <em>New in Jalview 2.5 Desktop</em>: Clicking on a sequence or group associated annotation row's label will highlight the sequence or sequence group in the alignment, and double clicking the annotation row label will select the associated sequence or group.</ul>
  93 <p>Sequence associations are turned off for subsequent annotation
  94 definitions by:
  95 <pre>SEQUENCE_REF&#9;ALIGNMENT</pre>
  96 </p>
  97 <p>Since version 2.5, Jalview allows annotation rows to be associated with a group defined on the alignment, by preceding the annotation row with the line:
  98 <pre>GROUP_REF&#9;<em>group_name</em></pre>
  99 Group association is turned off for subsequent annotation rows by
 100 <pre>GROUP_REF&#9;<em>ALIGNMENT</em></pre>
 101 Annotations may be associated with both a sequence and a group, however - group annotations are still experimental and unexpected behaviour may be observed when editing alignments containing both group and sequence associated annotation rows.</p>
 102 <p><em>LINE_GRAPH</em> type annotations can be given a colour
 103 (specified as 24 bit RGB triplet in hexadecimal or comma separated
 104 values), combined onto the same vertical axis, and have ordinate lines
 105 (horizontal lines at a particular vertical axis value) using the
 106 following commands (respectively):
 107 <pre>COLOUR&#9;<em>graph_name</em>&#9;<em>colour</em>
 108 COMBINE&#9;<em>graph_1_name</em>&#9;<em>graph_2_name</em>
 109 GRAPHLINE&#9;<em>graph_name</em>&#9;<em>value</em>&#9;<em>label</em>&#9;<em>colour</em><strong><em>
 110 </em></strong></pre>
 111 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.5) ROWPROPERTIES</font></h3>
 112 <p>The visual display properties for a set of annotation rows can be modified using the following tab-delimited line:</p>
 113 <pre>ROWPROPERTIES&#9;<em>Row label</em>&#9;<em>centrelabs=true( or false)</em>&#9;<em>showalllabs=true(default is false)</em>&#9;<em>scaletofit=true (default is false)</em></pre>
 114 <p>This sets the visual display properties according to the given values for all the annotation rows with labels matching <em>Row label</em>. The properties mostly affect the display of multi-character column labels, and are as follows:
 115 <ul><li><em>centrelabs</em> Centre each label on its column.</li>
 116 <li><em>showalllabs</em> Show every column label rather than only the first of a run of identical labels (setting this to true can have a drastic effect on secondary structure rows).</li>
 117 <li><em>scaletofit</em> Shrink each label's font size so that the label fits within the column. Useful when annotating an alignment with a specific column numbering system. (<em>Not available in Jalview applet due to AWT 1.1 limitations</em>)</li>
 118 </ul></p>
 119 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.2.1) SEQUENCE_GROUP</font></h3>
 120 <p>Groups of sequences can be defined using the tab delimited line</p>
 121 <pre>SEQUENCE_GROUP     Group_Name      Group_Start     Group_End       Sequences</pre>
 122 <p>The sequences can be defined by alignment index and a range of sequences can
 123   be defined in a comma delimited field such as</p>
 124 <p>2-5,8-15,20,22</p>
 125 <p>Enter * to select all groups. </p>
 126 <p>If the alignment indices are not known, enter -1 then a tab delimited list
 127   of sequence ids. </p>
 128 <p>If the SEQUENCE_REF has been defined, the group_start and group_end will be
 129   relative to the sequence residue numbering, otherwise the group_start and group_end
 130   will be the alignment column indices. </p>
 131 <p>The group can (optionally) be assigned various visualisation properties via
 132   another tab delimited line thus:</p>
 133 <pre>PROPERTIES Group_name      tab_delimited_key_value_pairs
 134 </pre>
 135 <p>The key_value_pairs allow you to define a description and to colour the group
 136   in various ways. All, none or some of the following values could be used for
 137   a group:</p>
 138 <p>description=Text <br>
 139   colour=Helix Propensity<br>
 140   pidThreshold=0<br>
 141   consThreshold=0<br>
 142   outlineColour=red <br>
 143   displayBoxes=true<br>
 144   displayText=false<br>
 145   colourText=false<br>
 146   textCol1=black<br>
 147   textCol2=black<br>
 148   textColThreshold=0<br>
 149   idColour=ff3322<br>
 150  <!-- Not yet implemented in 2.5 release
 151   hide=false<br>
 152   hidecols=false<br> -->
 153   showunconserved=false</p>
 154 <ul><li><em>New Features in 2.4:</em><br>if the <strong>idColour</strong> property
 155 is given without specifying a colour scheme with the <strong>colour</strong>
 156 property, then the idColour will also be used to colour the sequence.</li>
 157 <li>the <strong>colour</strong> property can take either a colour scheme name,
 158  or a single colour specification (either a colour name like 'red' or an RGB
 159  triplet like 'ff0066'). If a single colour is specified, then the group
 160  will be coloured with that colour.</li>
 161  <!--  <li><em>New Features in 2.5</em></li>
 162  <li>hide and hidecols instruct jalview to hide the sequences or columns covered by the group.</li> -->
 163   <li>Sequence associated Groups<br>If a group is defined after a valid
 164  <em>SEQUENCE_REF</em> sequence reference statement, the sequence representative
 165  for the group will be set to the referenced sequence.<!-- <br><strong>Note:</strong> if the <em>hide</em>
 166  property is set then only the representative sequence for the group will be shown in the alignment.--></li>
 167 </ul>
 168 <p> </p>
 169 <p>An example Annotation file is given below:
 170 <pre>#Comment lines follow the hash symbol
 171 JALVIEW_ANNOTATION
 172 SEQUENCE_REF&#9;FER1_MESCR&#9;5
 173 BAR_GRAPH&#9;Bar Graph 1&#9;||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
 174 LINE_GRAPH&#9;Green Values&#9;1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2
 175 LINE_GRAPH&#9;Red Values&#9;2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2
 176 BAR_GRAPH&#9;Bar Graph&#9;2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
 177 NO_GRAPH&#9;Icons &#9;||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
 178 NO_GRAPH&#9;Purple Letters&#9;m|y|p|r|o|t|e|i|n
 179 COLOUR&#9;Bar Graph 2&#9;blue
 180 COLOUR&#9;Red Values&#9;255,0,0
 181 COLOUR&#9;Green Values&#9;green
 182 COLOUR&#9;Purple Letters&#9;151,52,228
 183 COMBINE&#9;Green Values&#9;Red Values
 184 GRAPHLINE&#9;Red Values&#9;2.6&#9;threshold&#9;black
 185
 186 SEQUENCE_GROUP Group_A 30 50 *
 187 SEQUENCE_GROUP Group_B 1 351 2-5
 188 SEQUENCE_GROUP Group_C 12 14 -1 seq1    seq2    seq3
 189 PROPERTIES Group_A description=This is the description colour=Helix Propensity pidThreshold=0 outlineColour=red displayBoxes=true displayText=false     colourText=false textCol1=black textCol2=black textColThreshold=0
 190 PROPERTIES Group_B outlineColour=red
 191 PROPERTIES Group_C colour=Clustal
 192 </pre>
 193 </p>
 194 </body>
 195 </html>