help/html/features/annotationsFormat.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  * Copyright (C) $$Year-Rel$$ 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>
  28     <strong>The Alignment Annotations File</strong>
  29   </p>
  30   <p>
  31     Alignment annotations can be imported onto an alignment since
  32     version 2.08 of Jalview, via an annotations file. It is a simple
  33     ASCII text file consisting of tab delimited records similar to the <a
  34       href="featuresFormat.html"
  35     >Sequence Features File</a>, and introduced primarily for use with the
  36     Jalview applet.
  37   </p>
  38
  39   <p>
  40     <strong>Importing annotation files</strong><br /> Alignment
  41     annotations files are imported into Jalview in the following ways:<br />
  42   <ul>
  43     <li>from the command line<strong><pre>
  44  -annotations &lt;<em>Annotations filename</em>&gt;</pre></strong></li>
  45     <li>Dragging an annotations file onto an alignment window</li>
  46     <li>Via the &quot;Load Features / Annotations&quot; entry in
  47       the <strong>File</strong> menu of an alignment window.
  48     </li>
  49   </ul>
  50   </p>
  51   <p>
  52     <strong>Exporting annotation files</strong><br /> An annotation
  53     file can be created for any alignment view from the &quot;Export
  54     Annotations ...&quot; entry in the <strong>File</strong> menu of an
  55     alignment window.
  56   </p>
  57   <p>
  58     <strong>THE ANNOTATION FILE FORMAT</strong> <br />An annotation file
  59     consists of lines containing an instruction followed by tab
  60     delimited fields. Any lines starting with &quot;#&quot; are
  61     considered comments, and ignored. The sections below describe the
  62     structure of an annotation file.
  63   </p>
  64   <ul>
  65     <li><a href="#annheader">JALVIEW_ANNOTATION</a> mandatory
  66       header</li>
  67     <li><a href="#annrows">LINE_GRAPH, BAR_GRAPH and NO_GRAPH</a>
  68       to create annotation rows</li>
  69     <li><a href="#combine">COMBINE, COLOUR and GRAPHLINE</a> for
  70       thresholds and complex line graphs</li>
  71     <li><a href="#annrowprops">ROWPROPERTIES</a> control the
  72       display of individual annotation rows</li>
  73     <li><a href="#groupdefs">SEQUENCE_GROUP</a> to define groups of
  74       sequences for further annotation</li>
  75     <li><a href="#groupprops">PROPERTIES</a> to set visualisation
  76       properties for sequence groups</li>
  77     <li><a href="#seqgrprefs">SEQUENCE_REF and GROUP_REF</a> for
  78       specifying target sequences and groups for annotation, reference
  79       sequence and column visibilty commands.</li>
  80     <li><a href="#refsandviews">VIEW_SETREF, VIEW_HIDECOLS and
  81         HIDE_INSERTIONS</a> for assigning the reference sequence on the
  82       alignment and hiding columns.</li>
  83   </ul>
  84   <p>
  85     At the end of this document, you can also find notes on <a
  86       href="#compatibility"
  87     >compatibility</a> of annotation files across different versions of
  88     Jalview. An <a href="#exampleann">example annotation file</a> is
  89     also provided along with instructions on how to import it to
  90     Jalview.
  91   </p>
  92   <hr />
  93   <p>
  94     <strong><em><a name="annheader">Header line</a></em></strong><br />The
  95     first non-commented out line of a valid Annotations file must begin
  96     with :<strong><pre>JALVIEW_ANNOTATION</pre></strong>
  97   </p>
  98   <hr />
  99   <p>
 100     <strong><em><a name="annrows">LINE_GRAPH,
 101           BAR_GRAPH and NO_GRAPH</a></em></strong><br /> Labels, secondary structure,
 102     histograms and line graphs are added with a line like <strong><pre>
 103         <em>GRAPH_TYPE</em>&#9;<em>Label</em>&#9;<em>Description</em> (optional)&#9;<em>Values</em>
 104       </pre></strong>
 105   </p>
 106   <p>
 107     Here, the <em>GRAPH_TYPE</em> field in the first column defines the
 108     appearance of the annotation row when rendered by Jalview. The next
 109     field is the row <em>label</em> for the annotation. This may be
 110     followed by a <em>description</em> for the row, which is shown in a
 111     tooltip when the user mouses over the annotation row's label. Since
 112     Jalview 2.7, the description field may also contain HTML tags (in
 113     the same way as a <a href="featuresFile.html">sequence feature's</a>
 114     label), providing the text is enclosed in an &lt;html/&gt; tag.
 115   <ul>
 116     <em>Please note: URL links embedded in HTML descriptions are
 117       not yet supported.</em>
 118   </ul>
 119   </p>
 120   <p>
 121     The final <em>Values</em> field contains a series of &quot;|&quot;
 122     separated value fields. Each value field is itself a comma separated
 123     list of fields of a particular type defined by the annotation row's
 124     <em>GRAPH_TYPE</em>. The allowed values of <em>GRAPH_TYPE</em> and
 125     corresponding interpretation of each <em>Value</em> are shown below:
 126
 127
 128   <ul>
 129     <li><strong>BAR_GRAPH</strong><br> Plots a histogram with
 130       labels below each bar.<br> <em>number</em>,<em>text
 131         character</em>,<em>Tooltip text</em></li>
 132     <li><strong>LINE_GRAPH</strong><br> Draws a line between
 133       values on the annotation row.<br> <em>number</em></li>
 134     <li><strong>NO_GRAPH</strong><br>For a row consisting of
 135       text labels and/or secondary structure symbols.<br> <em>{Secondary
 136         Structure Symbol}</em>,<em>text label</em>,<em>Tooltip text</em><br />
 137       <br />The type of secondary structure symbol depends on the
 138       alignment being annotated being either Protein or RNA. <br />For
 139       proteins, structure symbols are <em>H</em> (for helix) and <em>E</em>
 140       (for strand)<br /> <br />For RNA structures, VIENNA, WUSS, and
 141       extended notations can be used to specify paired positions.
 142       <ul>e.g. &quot;(|(||)|)&quot; or
 143         &quot;|A|A|A|(|a|a|a|)&quot;)
 144       </ul></li>
 145   </ul>
 146   Any or all value fields may be left empty, as well as the BAR_GRAPH's
 147   text character field, and either or both of the text-label and
 148   secondary structure symbol fields of the NO_GRAPH type annotation
 149   rows.
 150   </p>
 151   <p>Color strings can be embedded in a value field by enclosing an
 152     RGB triplet in square brackets to colour that position in an
 153     annotation row.</p>
 154   <hr />
 155   <p>
 156     <strong><a name="combine">COMBINE, COLOUR and GRAPHLINE</a>
 157       for line graphs</font></strong><br /> <em>LINE_GRAPH</em> type annotations can be
 158     given a colour (specified as 24 bit RGB triplet in hexadecimal or
 159     comma separated values), combined onto the same vertical axis, and
 160     have ordinate lines (horizontal lines at a particular vertical axis
 161     value) using the following commands (respectively):
 162   <pre>COLOUR&#9;<em>graph_name</em>&#9;<em>colour</em>
 163 COMBINE&#9;<em>graph_1_name</em>&#9;<em>graph_2_name</em>
 164 GRAPHLINE&#9;<em>graph_name</em>&#9;<em>value</em>&#9;<em>label</em>&#9;<em>colour</em><strong><em>
 165 </em></strong>
 166   </pre>
 167   </p>
 168   <hr />
 169   <p>
 170     <strong><a name="annrowprops">ROWPROPERTIES</a></strong><br /> The
 171     visual display properties for a set of annotation rows can be
 172     modified using the following tab-delimited line:
 173   </p>
 174   <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>
 175   </pre>
 176   <p>
 177     This sets the visual display properties according to the given
 178     values for all the annotation rows with labels matching <em>Row
 179       label</em>. The properties mostly affect the display of multi-character
 180     column labels, and are as follows:
 181   <ul>
 182     <li><em>centrelabs</em> Centre each label on its column.</li>
 183     <li><em>showalllabs</em> Show every column label rather than
 184       only the first of a run of identical labels (setting this to true
 185       can have a drastic effect on secondary structure rows).</li>
 186     <li><em>scaletofit</em> Shrink each label's font size so that
 187       the label fits within the column. Useful when annotating an
 188       alignment with a specific column numbering system. (<em>Not
 189         available in Jalview applet due to AWT 1.1 limitations</em>)</li>
 190   </ul>
 191   </p>
 192   <p>
 193     <strong><a name="groupdefs">SEQUENCE_GROUP</a></strong><br /> Groups
 194     of sequences and column ranges can be defined using a tab delimited
 195     statement like:
 196   </p>
 197   <pre>SEQUENCE_GROUP&#9;Group_Name&#9;Group_Start&#9;Group_End&#9;<em>Sequences</em>
 198   </pre>
 199   <p>The sequences can be defined by alignment index and a range of
 200     sequences can be defined in a comma delimited field such as</p>
 201   <p>2-5,8-15,20,22</p>
 202   <p>Enter * to select all groups.</p>
 203   <p>
 204     <strong>Note:</strong> If the alignment indices are not known, enter
 205     -1, followed by a tab and then a tab delimited list of sequence IDs.
 206   </p>
 207   <p>
 208     If a <a href="#seqgrprefs"><strong>SEQUENCE_REF</strong></a> has
 209     been defined, then <em>group_start</em> and <em>group_end</em> will
 210     be relative to the sequence residue numbering, otherwise the <em>group_start</em>
 211     and <em>group_end</em> will be alignment column indices.
 212   </p>
 213   <hr />
 214   <p>
 215     <strong><a name="groupprops">PROPERTIES</a></strong><br />This
 216     statement allows various visualisation properties to be assigned to
 217     a named group. This takes a series of tab-delimited <em>key</em>=<em>value</em>
 218     pairs:
 219   </p>
 220   <pre>PROPERTIES&#9;Group_name&#9;tab_delimited_key_value_pairs
 221 </pre>
 222   <p>The currently supported set of sequence group key-value pairs
 223     that can be provided here are :</p>
 224   <table border="1">
 225     <tbody>
 226       <tr>
 227         <td width="50%">Key</td>
 228         <td>Value</td>
 229       </tr>
 230       <tr>
 231         <td width="50%">description</td>
 232         <td>Text - may include simple HTML tags</td>
 233       </tr>
 234       <tr>
 235         <td width="50%">colour</td>
 236         <td>A string resolving to a valid Jalview colourscheme
 237           (e.g. Helix Propensity)</td>
 238       </tr>
 239       <tr>
 240         <td width="50%">pidThreshold</td>
 241         <td>A number from 0-100 specifying the Percent Identity
 242           Threshold for colouring columns in the group or alignment</td>
 243       </tr>
 244       <tr>
 245         <td width="50%">consThreshold</td>
 246         <td>A number from 0-100 specifying the degree of bleaching
 247           applied for conservation colouring</td>
 248       </tr>
 249       <tr>
 250         <td width="50%">outlineColour</td>
 251         <td>Line colour used for outlining the group (default is
 252           red)</td>
 253       </tr>
 254       <tr>
 255         <td width="50%">displayBoxes</td>
 256         <td>Boolean (default true) controlling display of shaded
 257           box for each alignment position</td>
 258       </tr>
 259       <tr>
 260         <td width="50%">displayText</td>
 261         <td>Boolean (default true) controlling display of text for
 262           each alignment position</td>
 263       </tr>
 264       <tr>
 265         <td width="50%">colourText</td>
 266         <td>Boolean (default false) specifying whether text should
 267           be shaded by applied colourscheme</td>
 268       </tr>
 269       <tr>
 270         <td width="50%">textCol1</td>
 271         <td>Colour for text when shown on a light background</td>
 272       </tr>
 273       <tr>
 274         <td width="50%">textCol2</td>
 275         <td>Colour for text when shown on a dark background</td>
 276       </tr>
 277       <tr>
 278         <td width="50%">textColThreshold</td>
 279         <td>Number from 0-100 specifying switching threshold
 280           between light and dark background</td>
 281       </tr>
 282       <tr>
 283         <td width="50%">idColour</td>
 284         <td>Colour for highlighting the Sequence ID labels for this
 285           group<br />If <em>idColour</em> is given but <em>colour</em>
 286           is not, then idColor will also be used for the group
 287           background colour.
 288         </td>
 289       </tr>
 290       <tr>
 291         <td width="50%">showunconserved</td>
 292         <td>Boolean (default false) indicating whether residues
 293           should only be shown that are different from current reference
 294           or consensus sequence</td>
 295       </tr>
 296       <tr>
 297         <td width="50%">hide</td>
 298         <td>Boolean (default false) indicating whether the rows in
 299           this group should be marked as hidden.<br />
 300         <em>Note:</em> if the group is sequence associated (specified by
 301           SEQUENCE_REF), then all members will be hidden and marked as
 302           represented by the reference sequence.
 303         </td>
 304       </tr>
 305       <!-- <tr><td width="50%">hidecols</td><td>Boolean (default false) indicating whether columns in this groushould be marked as hidden</td></tr> -->
 306     </tbody>
 307   </table>
 308
 309   <p>
 310     <strong>Specifying colours in PROPERTIES key-value pairs</strong><br />
 311     The <strong>colour</strong> property can take either a colour scheme
 312     name, or a single colour specification (either a colour name like
 313     'red' or an RGB triplet like 'ff0066'). If a single colour is
 314     specified, then the group will be coloured with that colour.
 315   </p>
 316   <hr />
 317   <p>
 318     <strong><a name="seqgrprefs">SEQUENCE_REF and GROUP_REF</a></strong><br />
 319     By default, annotation is associated with the alignment as a whole.
 320     However, it is also possible to have an annotation row associated
 321     with a specific sequence, or a sequence group. Clicking the
 322     annotation label for sequence or group associated annotation will
 323     highlight the associated rows in the alignment, and double clicking
 324     will select those rows, allowing further analysis. While group
 325     associated annotation remains associated with a particular
 326     alignment, sequence associated annotation can move with a sequence -
 327     so copying a sequence to another alignment will also copy its
 328     associated annotation.
 329   </p>
 330   <p>You can associate an annotation with a sequence by preceding
 331     its definition with the line:
 332   <pre>SEQUENCE_REF&#9;<em>seq_name</em>&#9;<em>[startIndex]</em>
 333   </pre>
 334   All Annotations defined after a SEQUENCE_REF command will then be
 335   associated with that sequence, and the first field in the Value field
 336   list will (optionally) be placed at the
 337   <em>startIndex</em>'th column.
 338   </p>
 339
 340   <p>Sequence associations are turned off for subsequent annotation
 341     definitions by:
 342   <pre>SEQUENCE_REF&#9;ALIGNMENT</pre>
 343   </p>
 344   <p>Similarly, since Jalview 2.5, group associated annotation can
 345     be defined by preceding the row definitions with the line:
 346   <pre>GROUP_REF&#9;<em>group_name</em>
 347   </pre>
 348   Group association is turned off for subsequent annotation rows by:
 349   <pre>GROUP_REF&#9;<em>ALIGNMENT</em>
 350   </pre>
 351   </p>
 352   <hr />
 353   <p>
 354     <strong><a name="refsandviews">VIEW_SETREF,
 355         VIEW_HIDECOL and HIDE_INSERTIONS</a></strong><br /> Since Jalview 2.9, the
 356     Annotations file has also supported the definition of reference
 357     sequences and hidden regions for an alignment view.
 358   </p>
 359   <!--  <p>
 360                 <em>VIEW_DEF</em> allows the current view to be named according to the
 361                 first argument after the tab character. If a second argument is
 362                 provided, then a new view is created with the given name, and
 363                 properties.
 364         </p> -->
 365   <p>
 366     <em>VIEW_SETREF</em><br />Marks the first sequence in the
 367     alignment, or alternately, the one specified by the most recent <em>SEQUENCE_REF</em>
 368     statement, as the <a href="../calculations/referenceseq.html">reference
 369       sequence</a> for the alignment.
 370   </p>
 371   <p>
 372     <em>HIDE_INSERTIONS</em><br />This command hides all gapped
 373     positions in the current target sequence. Any columns already hidden
 374     will be re-displayed.<br /> <br>The current target sequence is
 375     either the one specified by the most recent <em>SEQUENCE_REF</em>
 376     statement, the alignment's reference sequence, or the first sequence
 377     in the alignment.
 378   </p>
 379   <p>
 380     <em>VIEW_HIDECOLS</em><br />Modifies the visibility of columns in
 381     the view. The statement is followed by a single argument consisting
 382     of a comma separated series of single integers or integer pairs
 383     (like <em>3-4</em>). These define columns (starting from the
 384     left-hand column 0) that should be marked as hidden in the alignment
 385     view.
 386   </p>
 387
 388   <hr />
 389   <p>
 390     <strong><a name="compatibility">COMPATIBILITY NOTES</a></strong><br />
 391     The interpretation of the COMBINE statement in <em>Version
 392       2.8.1</em> was refined so that only annotation line graphs with the
 393     given names ands the same <strong>SEQUENCE_REF</strong> and <strong>GROUP_REF</strong>
 394     scope are grouped.
 395   </p>
 396   <hr />
 397
 398   <p>
 399     <strong><a name="exampleann">EXAMPLES</a></strong><br /> An example
 400     Annotation file is given below. Copy and paste the contents into a
 401     text file and load it onto the Jalview example protein alignment.
 402   </p>
 403   <pre>#Comment lines follow the hash symbol
 404 JALVIEW_ANNOTATION
 405 SEQUENCE_REF&#9;FER1_MESCR&#9;5
 406 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,+
 407 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
 408 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
 409 BAR_GRAPH&#9;Bar Graph 2&#9;1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
 410 NO_GRAPH&#9;Icons &#9;||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
 411 NO_GRAPH&#9;Purple Letters&#9;m|y|p|r|o|t|e|i|n
 412 COLOUR&#9;Bar Graph 2&#9;blue
 413 COLOUR&#9;Red Values&#9;255,0,0
 414 COLOUR&#9;Green Values&#9;green
 415 COLOUR&#9;Purple Letters&#9;151,52,228
 416 COMBINE&#9;Green Values&#9;Red Values
 417 GRAPHLINE&#9;Red Values&#9;2.6&#9;threshold&#9;black
 418
 419 SEQUENCE_GROUP&#9;Group_A&#9;30&#9;50&#9;*
 420 SEQUENCE_GROUP&#9;Group_B&#9;1&#9;351&#9;2-5
 421 SEQUENCE_GROUP&#9;Group_C&#9;12&#9;14&#9;-1&#9;seq1&#9;seq2&#9;seq3
 422 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
 423 PROPERTIES&#9;Group_B&#9;outlineColour=red
 424 PROPERTIES&#9;Group_C&#9;colour=Clustal
 425 </pre>
 426   </p>
 427 </body>
 428 </html>