4 <title>The Alignment Annotations File</title>
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
17 <li>from the command line<strong><pre>
18 -annotations <<em>Annotations filename</em>></pre></strong></li>
19 <li>Dragging an annotations file onto an alignment window</li>
20 <li>Via the "Load Features / Annotations" entry in the <strong>File</strong>
21 menu of an alignment window.</li>
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 "#" 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>	<em>Label</em>	<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 "|"
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 "<strong>|</strong>" symbol) are shown below:<ul>
35 Plots a histogram with labels below each bar.<br>
36 <em>number</em>,<em>text character</em></li>
38 Draws a line between values on the annotation row.<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>
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.
49 <p>You can associate an annotation with a sequence by preceding its
50 definition with the line:
51 <pre>SEQUENCE_REF	<em>seq_name</em>	<em>[startIndex]</em></pre>
52 All Annotations defined after a SEQUENCE_REF command will then be
53 associated with that sequence, and the first field in the Value field
54 list will (optionally) be placed at the <em>startIndex</em>'th column.</p>
55 <ul><em>New in Jalview 2.4</em>: the tooltip displayed when the mouse is moved over the row
56 label for sequence associated annotation gives the associated
57 sequence's name followed by the annotation row's description.</ul>
58 <p>Sequence associations are turned off for subsequent annotation
60 <pre>SEQUENCE_REF	ALIGNMENT</pre>
62 <p><em>LINE_GRAPH</em> type annotations can be given a colour
63 (specified as 24 bit RGB triplet in hexadecimal or comma separated
64 values), combined onto the same vertical axis, and have ordinate lines
65 (horizontal lines at a particular vertical axis value) using the
66 following commands (respectively):
67 <pre>COLOUR	<em>graph_name</em>	<em>colour</em>
68 COMBINE	<em>graph_1_name</em>	<em>graph_2_name</em>
69 GRAPHLINE	<em>graph_name</em>	<em>value</em>	<em>label</em>	<em>colour</em><strong><em>
71 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.4.1) ROWPROPERTIES</font></h3>
72 <p>The visual display properties for a set of annotation rows can be modified using the following tab-delimited line:</p>
73 <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>
74 <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:
75 <ul><li><em>centrelabs</em> Centre each label on its column.</li>
76 <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>
77 <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 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.2.1) SEQUENCE_GROUP</font></h3>
80 <p>Groups of sequences can be defined using the tab delimited line</p>
81 <pre>SEQUENCE_GROUP Group_Name Group_Start Group_End Sequences</pre>
82 <p>The sequences can be defined by alignment index and a range of sequences can
83 be defined in a comma delimited field such as</p>
85 <p>Enter * to select all groups. </p>
86 <p>If the alignment indices are not known, enter -1 then a tab delimited list
88 <p>If the SEQUENCE_REF has been defined, the group_start and group_end will be
89 relative to the sequence residue numbering, otherwise the group_start and group_end
90 will be the alignment column indices. </p>
91 <p>The group can (optionally) be assigned various visualisation properties via
92 another tab delimited line thus:</p>
93 <pre>PROPERTIES Group_name tab_delimited_key_value_pairs
95 <p>The key_value_pairs allow you to define a description and to colour the group
96 in various ways. All, none or some of the following values could be used for
98 <p>description=Text <br>
99 colour=Helix Propensity<br>
102 outlineColour=red <br>
103 displayBoxes=true<br>
104 displayText=false<br>
108 textColThreshold=0<br>
112 showunconserved=false</p>
113 <ul><li><em>New Features in 2.4:</em><br>if the <strong>idColour</strong> property
114 is given without specifying a colour scheme with the <strong>colour</strong>
115 property, then the idColour will also be used to colour the sequence.</li>
116 <li>the <strong>colour</strong> property can take either a colour scheme name,
117 or a single colour specification (either a colour name like 'red' or an RGB
118 triplet like 'ff0066'). If a single colour is specified, then the group
119 will be coloured with that colour.</li>
120 <li><em>New Features in 2.4.1</em></li>
121 <li>hide and hidecols instruct jalview to hide the sequences or columns covered by the group.</li>
122 <li>Sequence associated Groups<br>If a group is defined after a valid
123 <em>SEQUENCE_REF</em> sequence reference statement, the sequence representative
124 for the group will be set to the referenced sequence.<br><strong>Note:</strong> if the <em>hide</em>
125 property is set then only the representative sequence for the group will be shown in the alignment.</li>
128 <p>An example Annotation file is given below:
129 <pre>#Comment lines follow the hash symbol
131 SEQUENCE_REF	FER1_MESCR	5
132 BAR_GRAPH	Bar Graph 1	||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
133 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
134 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
135 BAR_GRAPH	Bar Graph	2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
136 NO_GRAPH	Icons 	||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
137 NO_GRAPH	Purple Letters	m|y|p|r|o|t|e|i|n
138 COLOUR	Bar Graph 2	blue
139 COLOUR	Red Values	255,0,0
140 COLOUR	Green Values	green
141 COLOUR	Purple Letters	151,52,228
142 COMBINE	Green Values	Red Values
143 GRAPHLINE	Red Values	2.6	threshold	black
145 SEQUENCE_GROUP Group_A 30 50 *
146 SEQUENCE_GROUP Group_B 1 351 2-5
147 SEQUENCE_GROUP Group_C 12 14 -1 seq1 seq2 seq3
148 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
149 PROPERTIES Group_B outlineColour=red
150 PROPERTIES Group_C colour=Clustal