JAL-1551 spotlessApply
[jalview.git] / 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>