help/html/features/annotationsFormat.html

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