<html>
-
+<!--
+ * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.0b1)
+ * Copyright (C) 2014 The Jalview Authors
+ *
+ * This file is part of Jalview.
+ *
+ * Jalview is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Jalview is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ * PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.
+ * The Jalview Authors are detailed in the 'AUTHORS' file.
+-->
<head>
<title>The Alignment Annotations File</title>
</head>
menu of an alignment window.</li>
</ul>
</p>
-<p><strong>Annotations File Format</strong></p>
-<p>The File consists of lines containing an instruction followed by
+<p><h3><font face="Arial, Helvetica, sans-serif">Format of an Annotations File</font></h3>
+<p>The file consists of lines containing an instruction followed by
tab delimited fields, and any lines starting with "#" are
ignored. The first non-commented out line of a valid Annotations file
must begin with :<strong><pre>JALVIEW_ANNOTATION</pre></strong></p>
-<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>
-<p>The <em>GRAPH_TYPE</em> field, which appears first, defines the
-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 "|"
-separated value fields. Each value field is itself a comma separated list of fields of a particular type defined by the annotation row's
-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>
- <li>BAR_GRAPH<br>
- Plots a histogram with labels below each bar.<br>
- <em>number</em>,<em>text character</em></li>
- <li>LINE_GRAPH<br>
- Draws a line between values on the annotation row.<br>
- <em>number</em></li>
- <li>NO_GRAPH<br>
- For a row consisting of text labels and/or secondary structure symbols.<br>
- <em>{Secondary Structure Symbol}</em>,<em>text label</em><br>
- Currently supported secondary structure structure symbols are <em>H</em> (for helix) and <em>E</em> (for strand)</li>
-</ul>
-Any or all value fields may be left empty, as well as the BAR_GRAPH's
+<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>
+ <p>
+ The <em>GRAPH_TYPE</em> field, which appears first, defines the
+ appearance of the annotation row when rendered by Jalview. The next
+ field is the row <em>label</em> for the annotation. This may be
+ followed by a <em>description</em> for the row, which is shown in a
+ tooltip when the user mouses over the annotation row's label. Since
+ Jalview 2.7, the description field may also contain html in the same
+ way as a <a href="featuresFile.html">sequence feature's</a> label,
+ providing the html is enclosed in an <html/> tag.
+
+ <ul><em>Please note: URL links embedded in HTML descriptions will
+ be supported in a future release of Jalview</em>
+ </ul>
+ </p>
+ <p>The final <em>Values</em>
+ field contains a series of "|" separated value fields. Each
+ value field is itself a comma separated list of fields of a particular
+ type defined by the annotation row's 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>
+ <li>BAR_GRAPH<br> Plots a histogram with labels below each
+ bar.<br> <em>number</em>,<em>text character</em>,<em>Tooltip
+ text</em>
+ </li>
+ <li>LINE_GRAPH<br> Draws a line between values on the
+ annotation row.<br> <em>number</em>
+ </li>
+ <li>NO_GRAPH<br> For a row consisting of text labels and/or
+ secondary structure symbols.<br> <em>{Secondary Structure
+ Symbol}</em>,<em>text label</em>,<em>Tooltip text</em><br> Currently
+ supported secondary structure structure symbols are <em>H</em> (for
+ helix) and <em>E</em> (for strand)</li>
+ </ul>
+ Any or all value fields may be left empty, as well as the BAR_GRAPH's
text character field, and either or both of the text-label and secondary
-structure symbol fields of the NO_GRAPH type annotation rows.
+structure symbol fields of the NO_GRAPH type annotation rows.</p>
+<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.
</p>
-<p>You can associate an annotation with a sequence by preceding its
+<p><h3><font face="Arial, Helvetica, sans-serif">SEQUENCE_REF and GROUP_REF</font></h3>
+ By
+ default, annotation is associated with the alignment as a whole.
+ However, it is also possible to have an annotation row associated with
+ a specific sequence, or a sequence group. Clicking the annotation
+ label for sequence or group associated annotation will highlight the
+ associated rows in the alignment, and double clicking will select
+ those rows, allowing further analysis. While group associated
+ annotation remains associated with a particular alignment, sequence
+ associated annotation can move with a sequence - so copying a sequence
+ to another alignment will also copy its associated annotation.
+ </p>
+ <p>You can associate an annotation with a sequence by preceding its
definition with the line:
<pre>SEQUENCE_REF	<em>seq_name</em>	<em>[startIndex]</em></pre>
All Annotations defined after a SEQUENCE_REF command will then be
associated with that sequence, and the first field in the Value field
list will (optionally) be placed at the <em>startIndex</em>'th column.</p>
-<ul><em>New in Jalview 2.4</em>: the tooltip displayed when the mouse is moved over the row
-label for sequence associated annotation gives the associated
-sequence's name followed by the annotation row's description.</ul>
+
<p>Sequence associations are turned off for subsequent annotation
definitions by:
<pre>SEQUENCE_REF	ALIGNMENT</pre>
</p>
+<p>Similarly, since Jalview 2.5, group associated annotation can be defined by preceding the row definitions with the line:
+<pre>GROUP_REF	<em>group_name</em></pre>
+Group association is turned off for subsequent annotation rows by:
+<pre>GROUP_REF	<em>ALIGNMENT</em></pre>
+</p>
+<h3><font face="Arial, Helvetica, sans-serif">LINE_GRAPH Grouping</font></h3>
<p><em>LINE_GRAPH</em> type annotations can be given a colour
(specified as 24 bit RGB triplet in hexadecimal or comma separated
values), combined onto the same vertical axis, and have ordinate lines
COMBINE	<em>graph_1_name</em>	<em>graph_2_name</em>
GRAPHLINE	<em>graph_name</em>	<em>value</em>	<em>label</em>	<em>colour</em><strong><em>
</em></strong></pre>
+</p>
+<h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.5) ROWPROPERTIES</font></h3>
+<p>The visual display properties for a set of annotation rows can be modified using the following tab-delimited line:</p>
+<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>
+<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:
+<ul><li><em>centrelabs</em> Centre each label on its column.</li>
+<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>
+<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>
+</ul></p>
<h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.2.1) SEQUENCE_GROUP</font></h3>
<p>Groups of sequences can be defined using the tab delimited line</p>
-<pre>SEQUENCE_GROUP Group_Name Group_Start Group_End Sequences</pre>
+<pre>SEQUENCE_GROUP Group_Name Group_Start Group_End <em>Sequences</em></pre>
<p>The sequences can be defined by alignment index and a range of sequences can
be defined in a comma delimited field such as</p>
<p>2-5,8-15,20,22</p>
<p>Enter * to select all groups. </p>
-<p>If the alignment indices are not known, enter -1 then a tab delimited list
- of sequence ids. </p>
+<p><strong>Note:</strong> If the alignment indices are not known, enter -1, followed by a tab and then a tab delimited list
+specifying the sequence ids. </p>
<p>If the SEQUENCE_REF has been defined, the group_start and group_end will be
relative to the sequence residue numbering, otherwise the group_start and group_end
will be the alignment column indices. </p>
textCol1=black<br>
textCol2=black<br>
textColThreshold=0<br>
- idColour=ff3322</p>
-<em>New Features in 2.4:</em><ul><li>if the <strong>idColour</strong> property
+ idColour=ff3322<br>
+ <!-- Not yet implemented in 2.5 release
+ hide=false<br>
+ hidecols=false<br> -->
+ showunconserved=false</p>
+<ul><li><em>New Features in 2.4:</em><br>if the <strong>idColour</strong> property
is given without specifying a colour scheme with the <strong>colour</strong>
property, then the idColour will also be used to colour the sequence.</li>
<li>the <strong>colour</strong> property can take either a colour scheme name,
or a single colour specification (either a colour name like 'red' or an RGB
triplet like 'ff0066'). If a single colour is specified, then the group
will be coloured with that colour.</li>
+ <!-- <li><em>New Features in 2.5</em></li>
+ <li>hide and hidecols instruct jalview to hide the sequences or columns covered by the group.</li> -->
+ <li>Sequence associated Groups<br>If a group is defined after a valid
+ <em>SEQUENCE_REF</em> sequence reference statement, the sequence representative
+ for the group will be set to the referenced sequence.<!-- <br><strong>Note:</strong> if the <em>hide</em>
+ property is set then only the representative sequence for the group will be shown in the alignment.--></li>
+ <li>The interpretation of the COMBINE statement in <em>Version 2.8.1</em> was refined
+ so that only annotation line graphs with the given names ands the same
+ <strong>SEQUENCE_REF</strong> and <strong>GROUP_REF</strong> scope are grouped.</li>
</ul>
<p> </p>
<p>An example Annotation file is given below:
<pre>#Comment lines follow the hash symbol
JALVIEW_ANNOTATION
SEQUENCE_REF	FER1_MESCR	5
-BAR_GRAPH	Bar Graph 1	||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
+BAR_GRAPH	Bar Graph 1	<html>an <em>html tooltip</em> for Bar graph 1.</html>	||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
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
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
BAR_GRAPH	Bar Graph	2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
COMBINE	Green Values	Red Values
GRAPHLINE	Red Values	2.6	threshold	black
-SEQUENCE_GROUP Group_A 30 50 *
-SEQUENCE_GROUP Group_B 1 351 2-5
-SEQUENCE_GROUP Group_C 12 14 -1 seq1 seq2 seq3
-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
-PROPERTIES Group_B outlineColour=red
-PROPERTIES Group_C colour=Clustal
+SEQUENCE_GROUP	Group_A	30	50	*
+SEQUENCE_GROUP	Group_B	1	351	2-5
+SEQUENCE_GROUP	Group_C	12	14	-1	seq1	seq2	seq3
+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
+PROPERTIES	Group_B	outlineColour=red
+PROPERTIES	Group_C	colour=Clustal
</pre>
</p>
+<p><em>Last updated for version 2.8.1</em></p>
</body>
</html>