JAL-1705 fetch Uniprot and PDB xrefs for Ensembl protein products
[jalview.git] / 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>