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><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
  34 <p><strong>Importing annotation files</strong><br/>
  35 Alignment annotations files are imported into Jalview in the
  36 following ways:<br/>
  37 <ul>
  38         <li>from the command line<strong><pre>
  39  -annotations &lt;<em>Annotations filename</em>&gt;</pre></strong></li>
  40         <li>Dragging an annotations file onto an alignment window</li>
  41         <li>Via the &quot;Load Features / Annotations&quot; entry in the <strong>File</strong>
  42         menu of an alignment window.</li>
  43 </ul>
  44 </p>
  45 <p>
  46   <strong>Exporting annotation files</strong><br /> An annotation file
  47   can be created for any alignment view from the &quot;Export
  48   Annotations ...&quot; entry in the <strong>File</strong> menu of an
  49   alignment window.
  50 </p>
  51 <p><strong>THE ANNOTATION FILE FORMAT</strong>
  52 <br/>An annotation file consists of lines containing an instruction followed by
  53 tab delimited fields. Any lines starting with &quot;#&quot; are considered comments, and
  54 ignored. The sections below describe the structure of an annotation file.
  55 </p><ul>
  56 <li><a href="#annheader">JALVIEW_ANNOTATION</a> mandatory header</li>
  57 <li><a href="#annrows">LINE_GRAPH, BAR_GRAPH and NO_GRAPH</a> to create annotation rows</li>
  58 <li><a href="#combine">COMBINE, COLOUR and GRAPHLINE</a> for thresholds and complex line graphs</li>
  59 <li><a href="#annrowprops">ROWPROPERTIES</a> control the display of individual annotation rows</li>
  60 <li><a href="#groupdefs">SEQUENCE_GROUP</a> to define groups of sequences for further annotation</li>
  61 <li><a href="#groupprops">PROPERTIES</a> to set visualisation properties for sequence groups</li>
  62 <li><a href="#seqgrprefs">SEQUENCE_REF and GROUP_REF</a> for specifying target sequences and groups for annotation, reference sequence and column visibilty commands.</li>
  63                 <li><a href="#refsandviews">VIEW_SETREF, VIEW_HIDECOLS and HIDE_INSERTIONS</a>
  64                         for assigning the reference sequence on the alignment and hiding columns.</li>
  65         </ul>
  66         <p>
  67                 At the end of this document, you can also find notes on <a
  68                         href="#compatibility">compatibility</a> of annotation files across
  69                 different versions of Jalview. An <a href="#exampleann">example
  70                         annotation file</a> is also provided along with instructions on how to
  71                 import it to Jalview.
  72         </p>
  73         <hr/>
  74 <p><strong><em><a name="annheader">Header line</a></em></strong><br/>The first non-commented out line of a valid Annotations file
  75 must begin with :<strong><pre>JALVIEW_ANNOTATION</pre></strong></p>
  76 <hr/>
  77 <p><strong><em><a name="annrows">LINE_GRAPH, BAR_GRAPH and NO_GRAPH</a></em></strong><br/>
  78 Labels, secondary structure, histograms and line graphs are 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>
  79         <p>
  80                 Here, the <em>GRAPH_TYPE</em> field in the first column defines the
  81                 appearance of the annotation row when rendered by Jalview. The next
  82                 field is the row <em>label</em> for the annotation. This may be
  83                 followed by a <em>description</em> for the row, which is shown in a
  84                 tooltip when the user mouses over the annotation row's label. Since
  85                 Jalview 2.7, the description field may also contain HTML tags (in the same
  86                 way as a <a href="featuresFile.html">sequence feature's</a> label),
  87                 providing the text is enclosed in an &lt;html/&gt; tag.
  88
  89         <ul><em>Please note: URL links embedded in HTML descriptions are not yet supported.</em>
  90         </ul>
  91         </p>
  92         <p>
  93                 The final <em>Values</em> field contains a series of &quot;|&quot;
  94                 separated value fields. Each value field is itself a comma separated
  95                 list of fields of a particular type defined by the annotation row's <em>GRAPH_TYPE</em>.
  96                 The allowed values of <em>GRAPH_TYPE</em> and corresponding
  97                 interpretation of each <em>Value</em> are shown below:
  98
  99         <ul>
 100                 <li><strong>BAR_GRAPH</strong><br> Plots a histogram with
 101                         labels below each bar.<br> <em>number</em>,<em>text
 102                                 character</em>,<em>Tooltip text</em></li>
 103                 <li><strong>LINE_GRAPH</strong><br> Draws a line between
 104                         values on the annotation row.<br> <em>number</em></li>
 105                 <li><strong>NO_GRAPH</strong><br>For a row consisting of
 106                         text labels and/or secondary structure symbols.<br> <em>{Secondary
 107                                 Structure Symbol}</em>,<em>text label</em>,<em>Tooltip text</em><br /> <br />The
 108                         type of secondary structure symbol depends on the alignment being
 109                         annotated being either Protein or RNA. <br />For proteins, structure
 110                         symbols are <em>H</em> (for helix) and <em>E</em> (for strand)<br />
 111                         <br />For RNA structures, VIENNA, WUSS, and extended notations can
 112                         be used to specify paired positions.
 113                         <ul>e.g. &quot;(|(||)|)&quot; or &quot;|A|A|A|(|a|a|a|)&quot;)
 114                         </ul></li>
 115         </ul>
 116         Any or all value fields may be left empty, as well as the BAR_GRAPH's
 117         text character field, and either or both of the text-label and
 118         secondary structure symbol fields of the NO_GRAPH type annotation rows.
 119         </p>
 120 <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.
 121 </p>
 122 <hr/>
 123 <p><strong><a name="combine">COMBINE, COLOUR and GRAPHLINE</a> for line graphs</font></strong><br/>
 124 <em>LINE_GRAPH</em> type annotations can be given a colour
 125 (specified as 24 bit RGB triplet in hexadecimal or comma separated
 126 values), combined onto the same vertical axis, and have ordinate lines
 127 (horizontal lines at a particular vertical axis value) using the
 128 following commands (respectively):
 129 <pre>COLOUR&#9;<em>graph_name</em>&#9;<em>colour</em>
 130 COMBINE&#9;<em>graph_1_name</em>&#9;<em>graph_2_name</em>
 131 GRAPHLINE&#9;<em>graph_name</em>&#9;<em>value</em>&#9;<em>label</em>&#9;<em>colour</em><strong><em>
 132 </em></strong></pre>
 133 </p>
 134 <hr/>
 135 <p><strong><a name="annrowprops">ROWPROPERTIES</a></strong><br/>
 136 The visual display properties for a set of annotation rows can be modified using the following tab-delimited line:</p>
 137 <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>
 138 <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:
 139 <ul><li><em>centrelabs</em> Centre each label on its column.</li>
 140 <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>
 141 <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>
 142 </ul></p>
 143 <p><strong><a name="groupdefs">SEQUENCE_GROUP</a></strong><br/>
 144 Groups of sequences and column ranges can be defined using a tab delimited statement like:</p>
 145 <pre>SEQUENCE_GROUP&#9;Group_Name&#9;Group_Start&#9;Group_End&#9;<em>Sequences</em></pre>
 146 <p>The sequences can be defined by alignment index and a range of sequences can
 147   be defined in a comma delimited field such as</p>
 148 <p>2-5,8-15,20,22</p>
 149 <p>Enter * to select all groups. </p>
 150 <p><strong>Note:</strong> If the alignment indices are not known, enter -1, followed by a tab and then a tab delimited list
 151 of sequence IDs. </p>
 152 <p>If a <a href="#seqgrprefs"><strong>SEQUENCE_REF</strong></a> has been defined, then <em>group_start</em> and <em>group_end</em> will be
 153   relative to the sequence residue numbering, otherwise the <em>group_start</em> and <em>group_end</em>
 154   will be alignment column indices. </p>
 155 <hr/>
 156 <p><strong><a name="groupprops">PROPERTIES</a></strong><br/>This statement allows various visualisation properties to be assigned to a named group. This takes a series of tab-delimited <em>key</em>=<em>value</em> pairs:</p>
 157 <pre>PROPERTIES&#9;Group_name&#9;tab_delimited_key_value_pairs
 158 </pre>
 159 <p>The currently supported set of sequence group key-value pairs that can be provided here are :</p>
 160 <table border="1">
 161 <tbody><tr><td width="50%">Key</td><td>Value</td></tr>
 162 <tr><td width="50%">description</td><td>Text - may include simple HTML tags</td></tr>
 163 <tr><td width="50%">colour</td><td>A string resolving to a valid Jalview colourscheme (e.g. Helix Propensity)</td></tr>
 164 <tr><td width="50%">pidThreshold</td><td>A number from 0-100 specifying the Percent Identity Threshold for colouring columns in the group or alignment</td></tr>
 165 <tr><td width="50%">consThreshold</td><td>A number from 0-100 specifying the degree of bleaching applied for conservation colouring</td></tr>
 166 <tr><td width="50%">outlineColour</td><td>Line colour used for outlining the group (default is red)</td></tr>
 167 <tr><td width="50%">displayBoxes</td><td>Boolean (default true) controlling display of shaded box for each alignment position</td></tr>
 168 <tr><td width="50%">displayText</td><td>Boolean (default true) controlling display of text for each alignment position</td></tr>
 169 <tr><td width="50%">colourText</td><td>Boolean (default false) specifying whether text should be shaded by applied colourscheme</td></tr>
 170 <tr><td width="50%">textCol1</td><td>Colour for text when shown on a light background</td></tr>
 171 <tr><td width="50%">textCol2</td><td>Colour for text when shown on a dark background</td></tr>
 172 <tr><td width="50%">textColThreshold</td><td>Number from 0-100 specifying switching threshold between light and dark background</td></tr>
 173 <tr><td width="50%">idColour</td><td>Colour for highlighting the Sequence ID labels for this group<br/>If <em>idColour</em> is given but <em>colour</em> is not, then idColor will also be used for the group background colour.</td></tr>
 174 <tr><td width="50%">showunconserved</td><td>Boolean (default false) indicating whether residues should only be shown that are different from current reference or consensus sequence</td></tr>
 175 <tr><td width="50%">hide</td><td>Boolean (default false) indicating whether the rows in this group should be marked as hidden.<br/><em>Note:</em> if the group is sequence associated (specified by SEQUENCE_REF), then all members will be hidden and marked as represented by the reference sequence.</td></tr>
 176 <!-- <tr><td width="50%">hidecols</td><td>Boolean (default false) indicating whether columns in this groushould be marked as hidden</td></tr> --></tbody>
 177 </table>
 178
 179 <p><strong>Specifying colours in PROPERTIES key-value pairs</strong><br/>
 180 The <strong>colour</strong> property can take either a colour scheme name,
 181  or a single colour specification (either a colour name like 'red' or an RGB
 182  triplet like 'ff0066'). If a single colour is specified, then the group
 183  will be coloured with that colour.</p>
 184  <hr/>
 185  <p><strong><a name="seqgrprefs">SEQUENCE_REF and GROUP_REF</a></strong><br/>
 186         By
 187                 default, annotation is associated with the alignment as a whole.
 188                 However, it is also possible to have an annotation row associated with
 189                 a specific sequence, or a sequence group. Clicking the annotation
 190                 label for sequence or group associated annotation will highlight the
 191                 associated rows in the alignment, and double clicking will select
 192                 those rows, allowing further analysis. While group associated
 193                 annotation remains associated with a particular alignment, sequence
 194                 associated annotation can move with a sequence - so copying a sequence
 195                 to another alignment will also copy its associated annotation.
 196         </p>
 197         <p>You can associate an annotation with a sequence by preceding its
 198 definition with the line:
 199 <pre>SEQUENCE_REF&#9;<em>seq_name</em>&#9;<em>[startIndex]</em></pre>
 200 All Annotations defined after a SEQUENCE_REF command will then be
 201 associated with that sequence, and the first field in the Value field
 202 list will (optionally) be placed at the <em>startIndex</em>'th column.</p>
 203
 204 <p>Sequence associations are turned off for subsequent annotation
 205 definitions by:
 206 <pre>SEQUENCE_REF&#9;ALIGNMENT</pre>
 207 </p>
 208 <p>Similarly, since Jalview 2.5, group associated annotation can be defined by preceding the row definitions with the line:
 209 <pre>GROUP_REF&#9;<em>group_name</em></pre>
 210 Group association is turned off for subsequent annotation rows by:
 211 <pre>GROUP_REF&#9;<em>ALIGNMENT</em></pre>
 212 </p>
 213 <hr/>
 214 <p><strong><a name="refsandviews">VIEW_SETREF, VIEW_HIDECOL and HIDE_INSERTIONS</a></strong><br/>
 215 Since Jalview 2.9, the Annotations file has also supported the definition of reference sequences and hidden regions for an alignment view.</p>
 216 <!--    <p>
 217                 <em>VIEW_DEF</em> allows the current view to be named according to the
 218                 first argument after the tab character. If a second argument is
 219                 provided, then a new view is created with the given name, and
 220                 properties.
 221         </p> -->
 222         <p>
 223                 <em>VIEW_SETREF</em> marks the first sequence in the alignment, or
 224                 alternately, the one specified by the most recent <em>SEQUENCE_REF</em>
 225                 statement, as the <a href="../features/refsequence.html">reference
 226                         sequence</a> for the alignment.
 227         </p>
 228         <p>
 229                 <em>HIDE_INSERTIONS</em>This command hides all gapped positions in the
 230                 current target sequence. Any columns already hidden will be
 231                 re-displayed.<br />
 232                 <br>The current target sequence is either the one specified by
 233                 the most recent <em>SEQUENCE_REF</em> statement, the alignment's
 234                 reference sequence, or the first sequence in the alignment.
 235         </p>
 236         <p>
 237                 <em>VIEW_HIDECOLS</em> modifies the visibility of columns in the view.
 238                 The statement is followed by a single argument consisting of a comma
 239                 separated series of single integers or integer pairs (like <em>3-4</em>).
 240                 These define columns (starting from the left-hand column 0) that
 241                 should be marked as hidden in the alignment view.
 242         </p>
 243
 244         <hr/>
 245 <p><strong><a name="compatibility">COMPATIBILITY NOTES</a></strong><br/>
 246  The interpretation of the COMBINE statement in <em>Version 2.8.1</em> was refined
 247  so that only annotation line graphs with the given names ands the same
 248  <strong>SEQUENCE_REF</strong> and <strong>GROUP_REF</strong> scope are grouped.</p>
 249  <hr/>
 250
 251 <p><strong><a name="exampleann">EXAMPLES</a></strong><br/>
 252 An example Annotation file is given below. Copy and paste the contents into a text file and load it onto the Jalview example protein alignment.</p>
 253 <pre>#Comment lines follow the hash symbol
 254 JALVIEW_ANNOTATION
 255 SEQUENCE_REF&#9;FER1_MESCR&#9;5
 256 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,+
 257 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
 258 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
 259 BAR_GRAPH&#9;Bar Graph 2&#9;1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
 260 NO_GRAPH&#9;Icons &#9;||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
 261 NO_GRAPH&#9;Purple Letters&#9;m|y|p|r|o|t|e|i|n
 262 COLOUR&#9;Bar Graph 2&#9;blue
 263 COLOUR&#9;Red Values&#9;255,0,0
 264 COLOUR&#9;Green Values&#9;green
 265 COLOUR&#9;Purple Letters&#9;151,52,228
 266 COMBINE&#9;Green Values&#9;Red Values
 267 GRAPHLINE&#9;Red Values&#9;2.6&#9;threshold&#9;black
 268
 269 SEQUENCE_GROUP&#9;Group_A&#9;30&#9;50&#9;*
 270 SEQUENCE_GROUP&#9;Group_B&#9;1&#9;351&#9;2-5
 271 SEQUENCE_GROUP&#9;Group_C&#9;12&#9;14&#9;-1&#9;seq1&#9;seq2&#9;seq3
 272 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
 273 PROPERTIES&#9;Group_B&#9;outlineColour=red
 274 PROPERTIES&#9;Group_C&#9;colour=Clustal
 275 </pre>
 276 </p>
 277 </body>
 278 </html>