3 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.5)
4 * Copyright (C) 2010 J Procter, AM Waterhouse, 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>Sequence Features File</title>
24 <p><strong>Sequence Features File</strong></p>
25 <p>The Sequence features file (which used to be known as the
26 "Groups file" prior to version 2.08) is a simple way of
27 getting your own sequence annotations into Jalview. It was introduced to
28 allow sequence features to be rendered in the Jalview applet, and so is
29 intentionally lightweight and minimal because the applet is often used
30 in situations where data file size must be kept to a minimum, and no XML
31 parser is available.</p>
32 <p>Features files are imported into Jalview in the following ways:<br>
34 <li>from the command line<strong><pre>
35 -features <<em>Features filename</em>></pre></strong></li>
36 <li>Dragging a features file onto an alignment window</li>
37 <li>Via the "Load Features / Annotations" entry in the <strong>File</strong>
38 menu of an alignment window.</li>
41 <p><strong>Sequence Features File Format</strong></p>
42 <p>A features file is a simple ASCII text file, where each line
43 contains tab separated text fields. <strong>No comments are
45 <p>The first set of lines contain type definitions:<strong>
46 <pre><em>Feature label</em>	<em>Feature Colour</em><!-- 	<em>Feature links</em> --></pre> </strong>A feature
47 type has a text label, and a colour specification. This can be either:
49 <li>A single colour specified as either a red,green,blue 24 bit
50 triplet in hexadecimal (eg. 00ff00) or as comma separated numbers
51 (ranging from 0 to 255))</li>
52 <li>A <a href="featureschemes.html">graduated colourscheme</a> specified as a "|" separated list
54 <mincolor>|<maxcolor>|[absolute|]<minvalue>|<maxvalue>[|<thresholdtype>|[<threshold value>]]
55 </pre>The fields are as follows
57 <li><em>mincolor</em> and <em>maxcolor</em><br>
58 Colour triplets specified as hexadecimal or comma separated values</li>
59 <li><em>absolute</em><br>
60 An optional switch indicating that the <em>minvalue</em> and <em>maxvalue</em>
61 parameters should be left as is, rather than rescaled according to the
62 range of scores for this feature type.
63 <li><em>minvalue</em> and <em>maxvalue</em><br>
64 Minimum and maximum values defining the range of scores for which the colour range will be defined over. If minvalue is greater than maxvalue then the linear mapping will have negative gradient.
66 <li><em>thresholdtype</em> <br>
67 Either "none", "below", or "above". <em>below</em>
68 and <em>above</em> require an additional <em>threshold value</em>
69 which is used to control the display of features with a score either
70 below or above the value.</li>
75 <p>The remaining lines in the file are the sequence annotation
76 definitions, where the now defined features are attached to regions on
77 particular sequences, optionally with some descriptive text (displayed
78 in a tooltip when the mouse is near the feature on that sequence). There
79 are two alternate ways of referring to a sequence, either by its text
80 ID, or its index in an associated alignment.
82 <em>description</em>	<em>sequenceId</em>	<em>sequenceIndex</em>	<em>start</em>	<em>end</em>	<em>featureType</em>	<em>score (optional)</em></pre>
83 Normally, sequence features are associated with sequences rather than
84 alignments, and the sequenceIndex field is given as "-1". In
85 order to specify a sequence by its index in a particular alignment, the
86 sequenceId should be given as "ID_NOT_SPECIFIED", otherwise
87 the sequenceId field will be used in preference to the sequenceIndex
90 <p>The description may contain simple HTML document body tags if
91 enclosed by "<html></html>" and these will be
92 rendered as formatted tooltips in the Jalview Application (the Jalview
93 applet is not capable of rendering HTML tooltips, so all formatting tags
95 <em>Attaching Links to Sequence Features</em> <br>
96 Any anchor tags in an html formatted description line will be translated
97 into URL links. A link symbol will be displayed adjacent to any feature
98 which includes links, and these are made available from the <a
99 href="../menus/popupMenu.html#sqid.popup">links submenu</a> of the
100 popup menu which is obtained by right-clicking when a link symbol is
101 displayed in the tooltip.<br>
102 <em>Non-positional features</em><br>
103 Specify the <em>start</em> and <em>end</em> for a feature to be <strong>0</strong>
104 in order to attach it to the whole sequence. Non-positional features are
105 shown in a tooltip when the mouse hovers over the sequence ID panel, and
106 any embedded links can be accessed from the popup menu.
108 Scores can be associated with sequence features, and used to sort sequences or shade the alignment (this was added in jalview 2.5). The score field is optional, and malformed scores will be ignored.
110 <p>Feature annotations can be collected into named groups by
111 prefixing definitions with lines of the form:<strong><pre>startgroup	groupname</pre></strong>..
112 and subsequently post-fixing the group with:<strong><pre>endgroup	groupname</pre></strong>Feature
113 grouping was introduced in version 2.08, and used to control whether a
114 set of features are either hidden or shown together in the <a
115 href="seqfeatures.html">sequence Feature settings dialog box</a>.</p>
116 <p>A complete example is shown below :
119 metal ion-binding site	00ff00
120 transit peptide	0,105,215
122 modified residue	105,225,35
123 signal peptide	0,155,165
127 Your Own description here	FER_CAPAA	-1	3	93	domain
128 Your Own description here	FER_CAPAN	-1	48	144	chain
129 Your Own description here	FER_CAPAN	-1	50	140	domain
130 Your Own description here	FER_CAPAN	-1	136	136	modified residue
131 Your Own description here	FER1_LYCES	-1	1	47	transit peptide
132 Your Own description here	Q93XJ9_SOLTU	-1	1	48	signal peptide
133 Your Own description here	Q93XJ9_SOLTU	-1	49	144	chain
134 startgroup	secondarystucture
135 PDB secondary structure annotation	FER1_SPIOL	-1	52	59	strand
136 PDB secondary structure annotation	FER1_SPIOL	-1	74	80	helix
137 endgroup	secondarystructure