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