+++ /dev/null
-<html>
-<!--
- * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
- * Copyright (C) $$Year-Rel$$ 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>
-
-<body>
- <p>
- <strong>The Alignment Annotations File</strong>
- </p>
- <p>
- Alignment annotations can be imported onto an alignment since
- version 2.08 of Jalview, via an annotations file. It is a simple
- ASCII text file consisting of tab delimited records similar to the <a
- href="featuresFormat.html">Sequence Features File</a>, and
- introduced primarily for use with the Jalview applet.
- </p>
-
- <p>
- <strong>Importing annotation files</strong><br /> Alignment
- annotations files are imported into Jalview in the following ways:<br />
- <ul>
- <li>from the command line<strong><pre>
- -annotations <<em>Annotations filename</em>></pre></strong></li>
- <li>Dragging an annotations file onto an alignment window</li>
- <li>Via the "Load Features / Annotations" entry in
- the <strong>File</strong> menu of an alignment window.
- </li>
- </ul>
- </p>
- <p>
- <strong>Exporting annotation files</strong><br /> An annotation
- file can be created for any alignment view from the "Export
- Annotations ..." entry in the <strong>File</strong> menu of an
- alignment window.
- </p>
- <p>
- <strong>THE ANNOTATION FILE FORMAT</strong> <br />An annotation
- file consists of lines containing an instruction followed by tab
- delimited fields. Any lines starting with "#" are
- considered comments, and ignored. The sections below describe the
- structure of an annotation file.
- </p>
- <ul>
- <li><a href="#annheader">JALVIEW_ANNOTATION</a> mandatory
- header</li>
- <li><a href="#annrows">LINE_GRAPH, BAR_GRAPH and NO_GRAPH</a>
- to create annotation rows</li>
- <li><a href="#combine">COMBINE, COLOUR and GRAPHLINE</a> for
- thresholds and complex line graphs</li>
- <li><a href="#annrowprops">ROWPROPERTIES</a> control the
- display of individual annotation rows</li>
- <li><a href="#groupdefs">SEQUENCE_GROUP</a> to define groups of
- sequences for further annotation</li>
- <li><a href="#groupprops">PROPERTIES</a> to set visualisation
- properties for sequence groups</li>
- <li><a href="#seqgrprefs">SEQUENCE_REF and GROUP_REF</a> for
- specifying target sequences and groups for annotation, reference
- sequence and column visibilty commands.</li>
- <li><a href="#refsandviews">VIEW_SETREF, VIEW_HIDECOLS and
- HIDE_INSERTIONS</a> for assigning the reference sequence on the
- alignment and hiding columns.</li>
- </ul>
- <p>
- At the end of this document, you can also find notes on <a
- href="#compatibility">compatibility</a> of annotation files
- across different versions of Jalview. An <a href="#exampleann">example
- annotation file</a> is also provided along with instructions on how to
- import it to Jalview.
- </p>
- <hr />
- <p>
- <strong><em><a name="annheader">Header line</a></em></strong><br />The
- first non-commented out line of a valid Annotations file must begin
- with :<strong><pre>JALVIEW_ANNOTATION</pre></strong>
- </p>
- <hr />
- <p>
- <strong><em><a name="annrows">LINE_GRAPH,
- BAR_GRAPH and NO_GRAPH</a></em></strong><br /> Labels, secondary structure,
- histograms and line graphs are 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>
- Here, the <em>GRAPH_TYPE</em> field in the first column 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 tags (in
- the same way as a <a href="featuresFormat.html">sequence
- feature's</a> label), providing the text is enclosed in an
- <html/> tag.
- <ul>
- <em>Please note: URL links embedded in HTML descriptions are
- not yet supported.</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
- <em>GRAPH_TYPE</em>. The allowed values of <em>GRAPH_TYPE</em> and
- corresponding interpretation of each <em>Value</em> are shown below:
-
-
-
- <ul>
- <li><strong>BAR_GRAPH</strong><br> Plots a histogram with
- labels below each bar.<br> <em>number</em>,<em>text
- character</em>,<em>Tooltip text</em></li>
- <li><strong>LINE_GRAPH</strong><br> Draws a line between
- values on the annotation row.<br> <em>number</em></li>
- <li><strong>NO_GRAPH</strong><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 />
- <br />The type of secondary structure symbol depends on the
- alignment being annotated being either Protein or RNA. <br />For
- proteins, structure symbols are <em>H</em> (for helix) and <em>E</em>
- (for strand)<br /> <br />For RNA structures, VIENNA, WUSS, and
- extended notations can be used to specify paired positions.
- <ul>e.g. "(|(||)|)" or
- "|A|A|A|(|a|a|a|)")
- </ul></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.
- </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>
- <hr />
- <p>
- <strong><a name="combine">COMBINE, COLOUR and GRAPHLINE</a>
- for line graphs</font></strong><br /> <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 (horizontal lines at a particular vertical axis
- value) using the following commands (respectively):
- <pre>COLOUR	<em>graph_name</em>	<em>colour</em>
-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>
- <hr />
- <p>
- <strong><a name="annrowprops">ROWPROPERTIES</a></strong><br /> 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>
- <p>
- <strong><a name="groupdefs">SEQUENCE_GROUP</a></strong><br />
- Groups of sequences and column ranges can be defined using a tab
- delimited statement like:
- </p>
- <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>
- <strong>Note:</strong> If the alignment indices are not known, enter
- -1, followed by a tab and then a tab delimited list of sequence IDs.
- </p>
- <p>
- If a <a href="#seqgrprefs"><strong>SEQUENCE_REF</strong></a> has
- been defined, then <em>group_start</em> and <em>group_end</em> will
- be relative to the sequence residue numbering, otherwise the <em>group_start</em>
- and <em>group_end</em> will be alignment column indices.
- </p>
- <hr />
- <p>
- <strong><a name="groupprops">PROPERTIES</a></strong><br />This
- statement allows various visualisation properties to be assigned to
- a named group. This takes a series of tab-delimited <em>key</em>=<em>value</em>
- pairs:
- </p>
- <pre>PROPERTIES	Group_name	tab_delimited_key_value_pairs
-</pre>
- <p>The currently supported set of sequence group key-value pairs
- that can be provided here are :</p>
- <table border="1">
- <tbody>
- <tr>
- <td width="50%">Key</td>
- <td>Value</td>
- </tr>
- <tr>
- <td width="50%">description</td>
- <td>Text - may include simple HTML tags</td>
- </tr>
- <tr>
- <td width="50%">colour</td>
- <td>A string resolving to a valid Jalview colourscheme
- (e.g. Helix Propensity)</td>
- </tr>
- <tr>
- <td width="50%">pidThreshold</td>
- <td>A number from 0-100 specifying the Percent Identity
- Threshold for colouring columns in the group or alignment</td>
- </tr>
- <tr>
- <td width="50%">consThreshold</td>
- <td>A number from 0-100 specifying the degree of bleaching
- applied for conservation colouring</td>
- </tr>
- <tr>
- <td width="50%">outlineColour</td>
- <td>Line colour used for outlining the group (default is
- red)</td>
- </tr>
- <tr>
- <td width="50%">displayBoxes</td>
- <td>Boolean (default true) controlling display of shaded
- box for each alignment position</td>
- </tr>
- <tr>
- <td width="50%">displayText</td>
- <td>Boolean (default true) controlling display of text for
- each alignment position</td>
- </tr>
- <tr>
- <td width="50%">colourText</td>
- <td>Boolean (default false) specifying whether text should
- be shaded by applied colourscheme</td>
- </tr>
- <tr>
- <td width="50%">textCol1</td>
- <td>Colour for text when shown on a light background</td>
- </tr>
- <tr>
- <td width="50%">textCol2</td>
- <td>Colour for text when shown on a dark background</td>
- </tr>
- <tr>
- <td width="50%">textColThreshold</td>
- <td>Number from 0-100 specifying switching threshold
- between light and dark background</td>
- </tr>
- <tr>
- <td width="50%">idColour</td>
- <td>Colour for highlighting the Sequence ID labels for this
- group<br />If <em>idColour</em> is given but <em>colour</em>
- is not, then idColor will also be used for the group
- background colour.
- </td>
- </tr>
- <tr>
- <td width="50%">showunconserved</td>
- <td>Boolean (default false) indicating whether residues
- should only be shown that are different from current reference
- or consensus sequence</td>
- </tr>
- <tr>
- <td width="50%">hide</td>
- <td>Boolean (default false) indicating whether the rows in
- this group should be marked as hidden.<br /> <em>Note:</em>
- if the group is sequence associated (specified by
- SEQUENCE_REF), then all members will be hidden and marked as
- represented by the reference sequence.
- </td>
- </tr>
- <!-- <tr><td width="50%">hidecols</td><td>Boolean (default false) indicating whether columns in this groushould be marked as hidden</td></tr> -->
- </tbody>
- </table>
-
- <p>
- <strong>Specifying colours in PROPERTIES key-value pairs</strong><br />
- 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.
- </p>
- <hr />
- <p>
- <strong><a name="seqgrprefs">SEQUENCE_REF and GROUP_REF</a></strong><br />
- 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>
-
- <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>
- <hr />
- <p>
- <strong><a name="refsandviews">VIEW_SETREF,
- VIEW_HIDECOL and HIDE_INSERTIONS</a></strong><br /> Since Jalview 2.9, the
- Annotations file has also supported the definition of reference
- sequences and hidden regions for an alignment view.
- </p>
- <!-- <p>
- <em>VIEW_DEF</em> allows the current view to be named according to the
- first argument after the tab character. If a second argument is
- provided, then a new view is created with the given name, and
- properties.
- </p> -->
- <p>
- <em>VIEW_SETREF</em><br />Marks the first sequence in the
- alignment, or alternately, the one specified by the most recent <em>SEQUENCE_REF</em>
- statement, as the <a href="../calculations/referenceseq.html">reference
- sequence</a> for the alignment.
- </p>
- <p>
- <em>HIDE_INSERTIONS</em><br />This command hides all gapped
- positions in the current target sequence. Any columns already hidden
- will be re-displayed.<br /> <br>The current target sequence is
- either the one specified by the most recent <em>SEQUENCE_REF</em>
- statement, the alignment's reference sequence, or the first sequence
- in the alignment.
- </p>
- <p>
- <em>VIEW_HIDECOLS</em><br />Modifies the visibility of columns in
- the view. The statement is followed by a single argument consisting
- of a comma separated series of single integers or integer pairs
- (like <em>3-4</em>). These define columns (starting from the
- left-hand column 0) that should be marked as hidden in the alignment
- view.
- </p>
-
- <hr />
- <p>
- <strong><a name="compatibility">COMPATIBILITY NOTES</a></strong><br />
- 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.
- </p>
- <hr />
-
- <p>
- <strong><a name="exampleann">EXAMPLES</a></strong><br /> An example
- Annotation file is given below. Copy and paste the contents into a
- text file and load it onto the Jalview example protein alignment.
- </p>
- <pre>#Comment lines follow the hash symbol
-JALVIEW_ANNOTATION
-SEQUENCE_REF	FER1_MESCR	5
-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
-NO_GRAPH	Icons 	||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
-NO_GRAPH	Purple Letters	m|y|p|r|o|t|e|i|n
-COLOUR	Bar Graph 2	blue
-COLOUR	Red Values	255,0,0
-COLOUR	Green Values	green
-COLOUR	Purple Letters	151,52,228
-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
-</pre>
- </p>
-</body>
-</html>
git://source.jalview.org / jalview.git / blobdiff