3 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4 * Copyright (C) $$Year-Rel$$ The Jalview Authors
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
11 * of the License, or (at your option) any later version.
13 * Jalview is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty
15 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
16 * PURPOSE. See the GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
20 * The Jalview Authors are detailed in the 'AUTHORS' file.
23 <meta name="generator" content="HTML Tidy, see www.w3.org">
24 <title>Sequence Features File</title>
28 <strong>Sequence Features File</strong>
30 <p>The Sequence features file (which used to be known as the
31 "Groups file" prior to version 2.08) is a simple way of getting your
32 own sequence annotations into Jalview. It was introduced to allow
33 sequence features to be rendered in the Jalview applet, and so is
34 intentionally lightweight and minimal because the applet is often
35 used in situations where data file size must be kept to a minimum,
36 and no XML parser is available.</p>
39 Features files are imported into Jalview in the following ways:<br>
41 <li>from the command line <pre>
42 <strong> -features <<em>Features filename</em>></strong>
46 <li>Dragging a features file onto an alignment window</li>
48 <li>Via the "Load Features / Annotations" entry in
49 the <strong>File</strong> menu of an alignment window.
56 <strong>Sequence Features File Format</strong>
59 A features file is a simple ASCII text file, where each line
60 contains tab separated text fields. <strong>No comments are
64 <strong>Feature Colours</strong>
66 <p>The first set of lines contain feature type definitions and their colours:
68 <strong><em>Feature label</em>	<em>Feature Colour</em>
69 <!-- 	<em>Feature links</em> --></strong>
72 A feature type has a text label, and a colour specification. This can
76 <li>A single colour specified as either a red,green,blue 24 bit
77 triplet in hexadecimal (eg. 00ff00) or as comma separated numbers
78 (ranging from 0 to 255))<br>
79 (For help with colour values, see <a href="https://www.w3schools.com/colors/colors_converter.asp">https://www.w3schools.com/colors/colors_converter.asp</a>.)</li>
81 <li>A <a href="featureschemes.html">graduated colourscheme</a>
82 specified as a "|" separated list of fields: <pre>
83 [label <em>or</em> score<em> or</em> attribute|attName|]<mincolor>|<maxcolor>|[absolute|]<minvalue>|<maxvalue>[|<novalue>][|<thresholdtype>|[<threshold value>]]
84 </pre> The fields are as follows:
87 <li><em>label</em><br> Indicates that the feature
88 description should be used to create a colour for features of
89 this type.<br> <em>Note: if no threshold value is
90 needed then only 'label' is required.<br> This
91 keyword was added in Jalview 2.6
94 <li><em>score</em><br> Indicates that the feature
95 score should be used to create a graduated colour for features of
96 this type, in conjunction with mincolor, maxcolor.<br><em>This keyword was added in Jalview 2.11.
97 It may be omitted (score is the default) if mincolor and maxcolor are specified.
100 <li><em>attribute|attName</em><br> Indicates that the value of feature
101 attribute 'attName' should be used to create a colour for features of
103 <br>For example, <em>attribute|clinical_significance</em> to colour by clinical_significance.
104 <br>To colour by range of a numeric attribute, include <em>mincolor</em> and <em>maxcolor</em>, or omit to colour by text (category).
105 <br>(Note: the value of the attribute used for colouring will also be shown in the tooltip as you mouse over features.)
106 <br>A sub-attribute should be written as, for example, CSQ:IMPACT.
107 <br><em>This keyword was added in Jalview 2.11</em></li>
109 <li><em>mincolor</em> and <em>maxcolor</em><br> Colour
110 triplets specified as hexadecimal or comma separated values
111 (may be left blank for a <em>label</em> style colourscheme,
112 but remember to specify the remaining fields)</li>
114 <li><em>absolute</em><br> An optional switch
115 indicating that the <em>minvalue</em> and <em>maxvalue</em>
116 parameters should be left as is, rather than rescaled
117 according to the range of scores for this feature type.</li>
119 <li><em>minvalue</em> and <em>maxvalue</em><br>
120 Minimum and maximum values defining the range of scores for
121 which the colour range will be defined over.<br>If minvalue is
122 greater than maxvalue then the linear mapping will have
123 negative gradient.</li>
125 <li><em>novalue</em> <br>
126 Specifies the colour to use if colouring by attribute, when the attribute is absent.
127 Valid options are <em>novaluemin, novaluemax, novaluenone</em>, to use mincolor, maxcolor, or no colour.
128 <br>If not specified this will default to novaluemin.</li>
130 <li><em>thresholdtype</em><br> Either
131 "none", "below", or "above". <em>below</em>
132 and <em>above</em> require an additional <em>threshold
133 value</em> which is used to control the display of features with
134 a score either below or above the value.</li>
141 <strong>Feature Filters</strong>
143 <p>This section is optional, and allows one or more filters to be defined for each feature type.
144 <br>Only features that satisfy the filter conditions will be displayed.
145 <br>Begin with a line which is just STARTFILTERS, and end with a line which is just ENDFILTERS.
146 <br>Each line has the format:
147 <pre>featureType <em><tab></em> (filtercondition1) [and|or] (filtercondition2) [and|or]...<br></pre>
148 The parentheses are not needed if there is only one condition.
149 Combine multiple conditions with either <em>and</em> or <em>or</em> (but not a mixture).
150 <br>Each condition is written as:
151 <pre>Label <em>or</em> Score <em>or</em> AttributeName condition [value]</pre>
152 where either the label (description), (numeric) score, or (text or numeric) attribute is tested against the condition.
153 <br><em>condition</em> is not case sensitive, and should be one of
155 <li><em>Contains</em> - description (or attribute) should contain the given value (not case sensitive); example <em>clinical_significance contains Pathogenic</em></li>
156 <li><em>NotContains</em> - description (or attribute) should not contain the given value</li>
157 <li><em>Matches</em> - description (or attribute) should match the given value (not case sensitive)</li>
158 <li><em>NotMatches</em> - description (or attribute) should not match the given value (not case sensitive)</li>
159 <li><em>Present</em> - attribute is present on the feature (no value required); example <em>CSQ:SIFT present</em></li>
160 <li><em>NotPresent</em> - attribute is not present on the feature (no value required)</li>
161 <li><em>EQ</em> - feature score, or specified attribute, is equal to the (numeric) value</li>
162 <li><em>NE, LT, LE, GT, GE</em> - tests for not equal to / less than / less than or equal to / greater than / greater than or equal to the value</li>
164 A non-numeric value always fails a numeric test.<br>If either attribute name, or value to compare, contains spaces, then enclose in single quotes:
165 <em>'mutagenesis site' contains 'decreased affinity'</em>
166 <br>Tip: some examples of filter syntax are given below; or to see more, first configure colours and filters in Jalview, then <em>File | Export Features</em> to Textbox in Jalview Format.
167 <br><em>Feature filters were added in Jalview 2.11</em>
171 <strong>Feature Instances</strong>
174 <p>The remaining lines in the file are the sequence annotation
175 definitions, where the now defined features are attached to regions
176 on particular sequences. Each feature can optionally include some
177 descriptive text which is displayed in a tooltip when the mouse is
178 near the feature on that sequence (and may also be used to generate
179 a colour for the feature).</p>
182 If your sequence annotation is already available in <a href="http://gmod.org/wiki/GFF2">GFF2</a> (http://gmod.org/wiki/GFF2) or
183 <a href="https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md">GFF3</a>
184 (http://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md) format,
185 then you can leave it as is, after first adding a line containing only
186 'GFF' after any Jalview feature colour definitions (<em>this
187 mixed format capability was added in Jalview 2.6</em>). Alternately,
188 you can use Jalview's own sequence feature annotation format, which
189 additionally allows HTML and URLs to be directly attached to each
194 <strong>Jalview's sequence feature annotation format</strong>
196 <p>Each feature is specified as a tab-separated series of columns
199 <em>description</em>	<em>sequenceId</em>	<em>sequenceIndex</em>	<em>start</em>	<em>end</em>	<em>featureType</em>	<em>score (optional)</em>
202 This format allows two alternate ways of referring to a sequence,
203 either by its text ID, or its index (base 0) in an associated
204 alignment. Normally, sequence features are associated with sequences
205 rather than alignments, and the sequenceIndex field is given as
206 "-1". In order to specify a sequence by its index in a
207 particular alignment, the sequenceId should be given as
208 "ID_NOT_SPECIFIED", otherwise the sequenceId field will be
209 used in preference to the sequenceIndex field.
214 The description may contain simple HTML document body tags if
215 enclosed by "<html></html>" and these will be
216 rendered as formatted tooltips in the Jalview Application (the
217 Jalview applet is not capable of rendering HTML tooltips, so all
218 formatting tags will be removed).<br> <em>Attaching Links
219 to Sequence Features</em><br> Any anchor tags in an html formatted
220 description line will be translated into URL links. A link symbol
221 will be displayed adjacent to any feature which includes links, and
222 these are made available from the <a
223 href="../menus/popupMenu.html#sqid.popup">links submenu</a>
224 of the popup menu which is obtained by right-clicking when a link
225 symbol is displayed in the tooltip.<br> <em>Non-positional
226 features</em><br> Specify the <em>start</em> and <em>end</em> for
227 a feature to be <strong>0</strong> in order to attach it to the
228 whole sequence. Non-positional features are shown in a tooltip when
229 the mouse hovers over the sequence ID panel, and any embedded links
230 can be accessed from the popup menu.<br /> <em>Scores</em><br>
231 Scores can be associated with sequence features, and used to sort
232 sequences or shade the alignment (this was added in Jalview 2.5).
233 The score field is optional, and malformed scores will be ignored.
236 <p>Feature annotations can be collected into named groups by
237 prefixing definitions with lines of the form:
239 <strong>startgroup groupname</strong>
242 .. and subsequently post-fixing the group with:
245 <strong>endgroup groupname</strong>
248 Feature grouping was introduced in version 2.08, and used to control
249 whether a set of features are either hidden or shown together in the
250 <a href="seqfeatures.html">sequence Feature settings dialog box</a>.
254 <p>A complete example is shown below :
257 metal ion-binding site	00ff00
258 transit peptide	0,105,215
260 modified residue	105,225,35
261 signal peptide	0,155,165
265 kdHydrophobicity	ccffcc|333300|-3.9|4.5|above|-2.0
268 metal ion-binding site	Label Contains sulfur
269 kdHydrophobicity	(Score LT 1.5) OR (Score GE 2.8)
272 Your Own description here	FER_CAPAA	-1	3	93	domain
273 Your Own description here	FER_CAPAN	-1	48	144	chain
274 Your Own description here	FER_CAPAN	-1	50	140	domain
275 Your Own description here	FER_CAPAN	-1	136	136	modified residue
276 Your Own description here	FER1_LYCES	-1	1	47	transit peptide
277 Your Own description here	Q93XJ9_SOLTU	-1	1	48	signal peptide
278 Your Own description here	Q93XJ9_SOLTU	-1	49	144	chain
280 STARTGROUP	secondarystucture
281 PDB secondary structure annotation	FER1_SPIOL	-1	52	59	strand
282 PDB secondary structure annotation	FER1_SPIOL	-1	74	80	helix
283 ENDGROUP	secondarystructure
286 Hydrophobicity score by kD Q93XJ9_SOLTU -1 48 48 kdHydrophobicity 1.8
290 FER_CAPAA	GffGroup	domain	3	93	.	.