3 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.7)
4 * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
6 * This file is part of Jalview.
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 of the License, or (at your option) any later version.
12 * Jalview is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty
14 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
15 * PURPOSE. See the GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.
20 <title>The Alignment Annotations File</title>
24 <p><strong>The Alignment Annotations File</strong></p>
25 <p>Alignment annotations can be imported onto an alignment since
26 version 2.08 of Jalview, via an annotations file. It is a simple ASCII
27 text file consisting of tab delimited records similar to the <a
28 href="featuresFormat.html">Sequence Features File</a>, and introduced
29 primarily for use with the Jalview applet.</p>
30 <p>Alignment annotations files are imported into Jalview in the
33 <li>from the command line<strong><pre>
34 -annotations <<em>Annotations filename</em>></pre></strong></li>
35 <li>Dragging an annotations file onto an alignment window</li>
36 <li>Via the "Load Features / Annotations" entry in the <strong>File</strong>
37 menu of an alignment window.</li>
40 <p><h3><font face="Arial, Helvetica, sans-serif">Format of an Annotations File</font></h3>
41 <p>The file consists of lines containing an instruction followed by
42 tab delimited fields, and any lines starting with "#" are
43 ignored. The first non-commented out line of a valid Annotations file
44 must begin with :<strong><pre>JALVIEW_ANNOTATION</pre></strong></p>
45 <p>A row of annotation is added with a line like <strong><pre><em>GRAPH_TYPE</em>	<em>Label</em>	<em>Description</em> (optional)	<em>Values</em></pre></strong></p>
47 The <em>GRAPH_TYPE</em> field, which appears first, defines the
48 appearance of the annotation row when rendered by Jalview. The next
49 field is the row <em>label</em> for the annotation. This may be
50 followed by a <em>description</em> for the row, which is shown in a
51 tooltip when the user mouses over the annotation row's label. Since
52 Jalview 2.7, the description field may also contain html in the same
53 way as a <a href="featuresFile.html">sequence feature's</a> label,
54 providing the html is enclosed in an <html/> tag.
56 <ul><em>Please note: URL links embedded in HTML descriptions will
57 be supported in a future release of Jalview</em>
60 <p>The final <em>Values</em>
61 field contains a series of "|" separated value fields. Each
62 value field is itself a comma separated list of fields of a particular
63 type defined by the annotation row's GRAPH_TYPE. The allowed values of
64 GRAPH_TYPE and the format of their respective value fields (with the
65 trailing "<strong>|</strong>" symbol) are shown below:
68 <li>BAR_GRAPH<br> Plots a histogram with labels below each
69 bar.<br> <em>number</em>,<em>text character</em>,<em>Tooltip
72 <li>LINE_GRAPH<br> Draws a line between values on the
73 annotation row.<br> <em>number</em>
75 <li>NO_GRAPH<br> For a row consisting of text labels and/or
76 secondary structure symbols.<br> <em>{Secondary Structure
77 Symbol}</em>,<em>text label</em>,<em>Tooltip text</em><br> Currently
78 supported secondary structure structure symbols are <em>H</em> (for
79 helix) and <em>E</em> (for strand)</li>
81 Any or all value fields may be left empty, as well as the BAR_GRAPH's
82 text character field, and either or both of the text-label and secondary
83 structure symbol fields of the NO_GRAPH type annotation rows.</p>
84 <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.
86 <p><h3><font face="Arial, Helvetica, sans-serif">SEQUENCE_REF and GROUP_REF</font></h3>
88 default, annotation is associated with the alignment as a whole.
89 However, it is also possible to have an annotation row associated with
90 a specific sequence, or a sequence group. Clicking the annotation
91 label for sequence or group associated annotation will highlight the
92 associated rows in the alignment, and double clicking will select
93 those rows, allowing further analysis. While group associated
94 annotation remains associated with a particular alignment, sequence
95 associated annotation can move with a sequence - so copying a sequence
96 to another alignment will also copy its associated annotation.
98 <p>You can associate an annotation with a sequence by preceding its
99 definition with the line:
100 <pre>SEQUENCE_REF	<em>seq_name</em>	<em>[startIndex]</em></pre>
101 All Annotations defined after a SEQUENCE_REF command will then be
102 associated with that sequence, and the first field in the Value field
103 list will (optionally) be placed at the <em>startIndex</em>'th column.</p>
105 <p>Sequence associations are turned off for subsequent annotation
107 <pre>SEQUENCE_REF	ALIGNMENT</pre>
109 <p>Similarly, since Jalview 2.5, group associated annotation can be defined by preceding the row definitions with the line:
110 <pre>GROUP_REF	<em>group_name</em></pre>
111 Group association is turned off for subsequent annotation rows by:
112 <pre>GROUP_REF	<em>ALIGNMENT</em></pre>
114 <h3><font face="Arial, Helvetica, sans-serif">LINE_GRAPH Grouping</font></h3>
115 <p><em>LINE_GRAPH</em> type annotations can be given a colour
116 (specified as 24 bit RGB triplet in hexadecimal or comma separated
117 values), combined onto the same vertical axis, and have ordinate lines
118 (horizontal lines at a particular vertical axis value) using the
119 following commands (respectively):
120 <pre>COLOUR	<em>graph_name</em>	<em>colour</em>
121 COMBINE	<em>graph_1_name</em>	<em>graph_2_name</em>
122 GRAPHLINE	<em>graph_name</em>	<em>value</em>	<em>label</em>	<em>colour</em><strong><em>
125 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.5) ROWPROPERTIES</font></h3>
126 <p>The visual display properties for a set of annotation rows can be modified using the following tab-delimited line:</p>
127 <pre>ROWPROPERTIES	<em>Row label</em>	<em>centrelabs=true( or false)</em>	<em>showalllabs=true(default is false)</em>	<em>scaletofit=true (default is false)</em></pre>
128 <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:
129 <ul><li><em>centrelabs</em> Centre each label on its column.</li>
130 <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>
131 <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>
133 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.2.1) SEQUENCE_GROUP</font></h3>
134 <p>Groups of sequences can be defined using the tab delimited line</p>
135 <pre>SEQUENCE_GROUP Group_Name Group_Start Group_End Sequences</pre>
136 <p>The sequences can be defined by alignment index and a range of sequences can
137 be defined in a comma delimited field such as</p>
138 <p>2-5,8-15,20,22</p>
139 <p>Enter * to select all groups. </p>
140 <p>If the alignment indices are not known, enter -1 then a tab delimited list
141 of sequence ids. </p>
142 <p>If the SEQUENCE_REF has been defined, the group_start and group_end will be
143 relative to the sequence residue numbering, otherwise the group_start and group_end
144 will be the alignment column indices. </p>
145 <p>The group can (optionally) be assigned various visualisation properties via
146 another tab delimited line thus:</p>
147 <pre>PROPERTIES Group_name tab_delimited_key_value_pairs
149 <p>The key_value_pairs allow you to define a description and to colour the group
150 in various ways. All, none or some of the following values could be used for
152 <p>description=Text <br>
153 colour=Helix Propensity<br>
156 outlineColour=red <br>
157 displayBoxes=true<br>
158 displayText=false<br>
162 textColThreshold=0<br>
164 <!-- Not yet implemented in 2.5 release
166 hidecols=false<br> -->
167 showunconserved=false</p>
168 <ul><li><em>New Features in 2.4:</em><br>if the <strong>idColour</strong> property
169 is given without specifying a colour scheme with the <strong>colour</strong>
170 property, then the idColour will also be used to colour the sequence.</li>
171 <li>the <strong>colour</strong> property can take either a colour scheme name,
172 or a single colour specification (either a colour name like 'red' or an RGB
173 triplet like 'ff0066'). If a single colour is specified, then the group
174 will be coloured with that colour.</li>
175 <!-- <li><em>New Features in 2.5</em></li>
176 <li>hide and hidecols instruct jalview to hide the sequences or columns covered by the group.</li> -->
177 <li>Sequence associated Groups<br>If a group is defined after a valid
178 <em>SEQUENCE_REF</em> sequence reference statement, the sequence representative
179 for the group will be set to the referenced sequence.<!-- <br><strong>Note:</strong> if the <em>hide</em>
180 property is set then only the representative sequence for the group will be shown in the alignment.--></li>
183 <p>An example Annotation file is given below:
184 <pre>#Comment lines follow the hash symbol
186 SEQUENCE_REF	FER1_MESCR	5
187 BAR_GRAPH	Bar Graph 1	<html>an <em>html tooltip</em> for Bar graph 1.</html>	||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
188 LINE_GRAPH	Green Values	1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2
189 LINE_GRAPH	Red Values	2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2
190 BAR_GRAPH	Bar Graph	2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
191 NO_GRAPH	Icons 	||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
192 NO_GRAPH	Purple Letters	m|y|p|r|o|t|e|i|n
193 COLOUR	Bar Graph 2	blue
194 COLOUR	Red Values	255,0,0
195 COLOUR	Green Values	green
196 COLOUR	Purple Letters	151,52,228
197 COMBINE	Green Values	Red Values
198 GRAPHLINE	Red Values	2.6	threshold	black
200 SEQUENCE_GROUP Group_A 30 50 *
201 SEQUENCE_GROUP Group_B 1 351 2-5
202 SEQUENCE_GROUP Group_C 12 14 -1 seq1 seq2 seq3
203 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
204 PROPERTIES Group_B outlineColour=red
205 PROPERTIES Group_C colour=Clustal