help/html/features/annotationsFormat.html

   1 <html>
   2
   3 <head>
   4 <title>The Alignment Annotations File</title>
   5 </head>
   6
   7 <body>
   8 <p><strong>The Alignment Annotations File</strong></p>
   9 <p>Alignment annotations can be imported onto an alignment since
  10 version 2.08 of Jalview, via an annotations file. It is a simple ASCII
  11 text file consisting of tab delimited records similar to the <a
  12         href="featuresFormat.html">Sequence Features File</a>, and introduced
  13 primarily for use with the Jalview applet.</p>
  14 <p>Alignment annotations files are imported into Jalview in the
  15 following ways:<br>
  16 <ul>
  17         <li>from the command line<strong><pre>
  18  -annotations &lt;<em>Annotations filename</em>&gt;</pre></strong></li>
  19         <li>Dragging an annotations file onto an alignment window</li>
  20         <li>Via the &quot;Load Features / Annotations&quot; entry in the <strong>File</strong>
  21         menu of an alignment window.</li>
  22 </ul>
  23 </p>
  24 <p><strong>Annotations File Format</strong></p>
  25 <p>The File consists of lines containing an instruction followed by
  26 tab delimited fields, and any lines starting with &quot;#&quot; are
  27 ignored. The first non-commented out line of a valid Annotations file
  28 must begin with :<strong><pre>JALVIEW_ANNOTATION</pre></strong></p>
  29 <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>
  30 <p>The <em>GRAPH_TYPE</em> field, which appears first, defines the
  31 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;
  32 separated value fields. Each value field is itself a comma separated list of fields of a particular type defined by the annotation row's
  33 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>
  34         <li>BAR_GRAPH<br>
  35         Plots a histogram with labels below each bar.<br>
  36         <em>number</em>,<em>text character</em></li>
  37         <li>LINE_GRAPH<br>
  38         Draws a line between values on the annotation row.<br>
  39         <em>number</em></li>
  40         <li>NO_GRAPH<br>
  41         For a row consisting of text labels and/or secondary structure symbols.<br>
  42         <em>{Secondary Structure Symbol}</em>,<em>text label</em><br>
  43         Currently supported secondary structure structure symbols are <em>H</em> (for   helix) and <em>E</em> (for strand)</li>
  44 </ul>
  45 Any or all value fields may be left empty, as well as the BAR_GRAPH's
  46 text character field, and either or both of the text-label and secondary
  47 structure symbol fields of the NO_GRAPH type annotation rows.</p>
  48 <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.
  49 </p>
  50 <p>You can associate an annotation with a sequence by preceding its
  51 definition with the line:
  52 <pre>SEQUENCE_REF&#9;<em>seq_name</em>&#9;<em>[startIndex]</em></pre>
  53 All Annotations defined after a SEQUENCE_REF command will then be
  54 associated with that sequence, and the first field in the Value field
  55 list will (optionally) be placed at the <em>startIndex</em>'th column.</p>
  56 <ul><em>New in Jalview 2.4</em>: the tooltip displayed when the mouse is moved over the row
  57 label for sequence associated annotation  gives the associated
  58 sequence's name followed by the annotation row's description.</ul>
  59 <p>Sequence associations are turned off for subsequent annotation
  60 definitions by:
  61 <pre>SEQUENCE_REF&#9;ALIGNMENT</pre>
  62 </p>
  63 <p><em>LINE_GRAPH</em> type annotations can be given a colour
  64 (specified as 24 bit RGB triplet in hexadecimal or comma separated
  65 values), combined onto the same vertical axis, and have ordinate lines
  66 (horizontal lines at a particular vertical axis value) using the
  67 following commands (respectively):
  68 <pre>COLOUR&#9;<em>graph_name</em>&#9;<em>colour</em>
  69 COMBINE&#9;<em>graph_1_name</em>&#9;<em>graph_2_name</em>
  70 GRAPHLINE&#9;<em>graph_name</em>&#9;<em>value</em>&#9;<em>label</em>&#9;<em>colour</em><strong><em>
  71 </em></strong></pre>
  72 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.4.1) ROWPROPERTIES</font></h3>
  73 <p>The visual display properties for a set of annotation rows can be modified using the following tab-delimited line:</p>
  74 <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>
  75 <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:
  76 <ul><li><em>centrelabs</em> Centre each label on its column.</li>
  77 <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>
  78 <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.</li>
  79 </ul></p>
  80 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.2.1) SEQUENCE_GROUP</font></h3>
  81 <p>Groups of sequences can be defined using the tab delimited line</p>
  82 <pre>SEQUENCE_GROUP     Group_Name      Group_Start     Group_End       Sequences</pre>
  83 <p>The sequences can be defined by alignment index and a range of sequences can
  84   be defined in a comma delimited field such as</p>
  85 <p>2-5,8-15,20,22</p>
  86 <p>Enter * to select all groups. </p>
  87 <p>If the alignment indices are not known, enter -1 then a tab delimited list
  88   of sequence ids. </p>
  89 <p>If the SEQUENCE_REF has been defined, the group_start and group_end will be
  90   relative to the sequence residue numbering, otherwise the group_start and group_end
  91   will be the alignment column indices. </p>
  92 <p>The group can (optionally) be assigned various visualisation properties via
  93   another tab delimited line thus:</p>
  94 <pre>PROPERTIES Group_name      tab_delimited_key_value_pairs
  95 </pre>
  96 <p>The key_value_pairs allow you to define a description and to colour the group
  97   in various ways. All, none or some of the following values could be used for
  98   a group:</p>
  99 <p>description=Text <br>
 100   colour=Helix Propensity<br>
 101   pidThreshold=0<br>
 102   consThreshold=0<br>
 103   outlineColour=red <br>
 104   displayBoxes=true<br>
 105   displayText=false<br>
 106   colourText=false<br>
 107   textCol1=black<br>
 108   textCol2=black<br>
 109   textColThreshold=0<br>
 110   idColour=ff3322<br>
 111   hide=false<br>
 112   hidecols=false<br>
 113   showunconserved=false</p>
 114 <ul><li><em>New Features in 2.4:</em><br>if the <strong>idColour</strong> property
 115 is given without specifying a colour scheme with the <strong>colour</strong>
 116 property, then the idColour will also be used to colour the sequence.</li>
 117 <li>the <strong>colour</strong> property can take either a colour scheme name,
 118  or a single colour specification (either a colour name like 'red' or an RGB
 119  triplet like 'ff0066'). If a single colour is specified, then the group
 120  will be coloured with that colour.</li>
 121  <li><em>New Features in 2.4.1</em></li>
 122  <li>hide and hidecols instruct jalview to hide the sequences or columns covered by the group.</li>
 123   <li>Sequence associated Groups<br>If a group is defined after a valid
 124  <em>SEQUENCE_REF</em> sequence reference statement, the sequence representative
 125  for the group will be set to the referenced sequence.<br><strong>Note:</strong> if the <em>hide</em>
 126  property is set then only the representative sequence for the group will be shown in the alignment.</li>
 127 </ul>
 128 <p> </p>
 129 <p>An example Annotation file is given below:
 130 <pre>#Comment lines follow the hash symbol
 131 JALVIEW_ANNOTATION
 132 SEQUENCE_REF&#9;FER1_MESCR&#9;5
 133 BAR_GRAPH&#9;Bar Graph 1&#9;||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
 134 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
 135 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
 136 BAR_GRAPH&#9;Bar Graph&#9;2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
 137 NO_GRAPH&#9;Icons &#9;||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
 138 NO_GRAPH&#9;Purple Letters&#9;m|y|p|r|o|t|e|i|n
 139 COLOUR&#9;Bar Graph 2&#9;blue
 140 COLOUR&#9;Red Values&#9;255,0,0
 141 COLOUR&#9;Green Values&#9;green
 142 COLOUR&#9;Purple Letters&#9;151,52,228
 143 COMBINE&#9;Green Values&#9;Red Values
 144 GRAPHLINE&#9;Red Values&#9;2.6&#9;threshold&#9;black
 145
 146 SEQUENCE_GROUP Group_A 30 50 *
 147 SEQUENCE_GROUP Group_B 1 351 2-5
 148 SEQUENCE_GROUP Group_C 12 14 -1 seq1    seq2    seq3
 149 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
 150 PROPERTIES Group_B outlineColour=red
 151 PROPERTIES Group_C colour=Clustal
 152 </pre>
 153 </p>
 154 </body>
 155 </html>