JAL-1551 spotlessApply
[jalview.git] / help / help / html / features / featuresFormat.html
1 <html>
2 <!--
3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
5  * 
6  * This file is part of Jalview.
7  * 
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.
12  *  
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.
17  * 
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.
21  -->
22 <head>
23 <meta name="generator" content="HTML Tidy, see www.w3.org">
24 <title>Sequence Features File</title>
25 </head>
26 <body>
27   <p>
28     <strong>Sequence Features File</strong>
29   
30   <p>
31   
32   <p>The Sequence features File provides a simple way of getting
33     your own sequence features into Jalview. It also allows feature
34     display styles and filters to be saved and imported to another
35     alignment. Users familiar with the earliest versions of Jalview will
36     know that features files were originally termed 'groups' files, and
37     that the format was was designed as a space efficient format to
38     allow sequence features to be rendered in the Jalview applet.</p>
39
40   <p>
41     Features files are imported into Jalview in the following ways:<br>
42   
43   <ul>
44     <li>from the command line <pre>
45 <strong> --features &lt;<em>Features filename</em>&gt;</strong>
46 </pre>
47     </li>
48
49     <li>Dragging a features file onto an alignment window</li>
50
51     <li>Via the &quot;Load Features / Annotations&quot; entry in
52       the <strong>File</strong> menu of an alignment window.
53     </li>
54   </ul>
55
56   <p>
57     <strong>Sequence Features File Format</strong>
58   </p>
59   <p>
60     A features file is a simple ASCII text file, where each line
61     contains tab separated text fields. <strong>No comments are
62       allowed</strong>. Its structure consists of three blocks:
63   </p>
64   <ul>
65     <li><a href="#colourdefs">Feature Colour Specifications</a>
66       define how features of a particular type are rendered.</li>
67     <li><a href="#filterdefs">Feature Filters</a> provide a way of
68       excluding features of a particular type from display and analysis.
69       (new in Jalview 2.11)</li>
70     <li><a href="#featuredef">Sequence Feature definitions</a> -
71       tab separated fields that describe groups of positional and
72       non-positional features. Data can also be provided as <a href="#gff">GFF</a></li>
73   </ul>
74
75   <p>
76     <strong><a name="colourdefs">Feature Colours</a></strong>
77   </p>
78   <p>The first set of lines contain feature type definitions and their colours:
79   <pre>
80 <strong><em>&lt;Feature Type&gt;</em>&#9;<em>&lt;Feature Style&gt;</em>
81 <!-- &#9;<em>Feature links</em>  --></strong>
82 </pre>
83
84   Each feature type definition assigns a style to features of the given type. &lt;Feature Style&gt; can be either a simple colour, or a more complex <a href="featureschemes.html">Graduated Colour Scheme</a> that shades features according to their description, score, or other attributes.
85 <p>
86   <em>Assigning a colour for a &lt;Feature Type&gt;</em><br/>A single colour specified as either a red,green,blue 24 bit
87       triplet in hexadecimal (eg. 00ff00) or as comma separated numbers
88       (ranging from 0 to 255))<br>
89       (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>.)</p>
90       <p><em>Specifying a <a href="featureschemes.html">Graduated Colourscheme</a></em><br/>
91       Data dependent feature colourschemes are defined by a series of "|" separated fields: <pre>
92 [label <em>or</em> score<em> or</em> attribute|&lt;attName&gt;|]&lt;mincolor&gt;|&lt;maxcolor&gt;|[absolute|]&lt;minvalue&gt;|&lt;maxvalue&gt;[|&lt;novalue&gt;][|&lt;thresholdtype&gt;|[&lt;threshold value&gt;]]
93 </pre><br/>The fields are interpreted follows:
94
95   <ul>
96     <li><em>label</em><br> Indicates that the feature
97       description should be used to create a colour for features of this
98       type.<br> <em>Note: if no threshold value is needed then
99         only 'label' is required.<br> This keyword was added in
100         Jalview 2.6
101     </em></li>
102
103     <li><em>score</em><br> Indicates that the feature score
104       should be used to create a graduated colour for features of this
105       type, in conjunction with mincolor, maxcolor.<br>
106     <em>This keyword was added in Jalview 2.11. It may be omitted
107         (score is the default) if mincolor and maxcolor are specified. </em></li>
108
109     <li><em>attribute|&lt;attName&gt;</em><br> Indicates that
110       the value of feature attribute 'attName' should be used to create
111       a colour for features of this type. <br>For example, <em>attribute|clinical_significance</em>
112       to colour by "clinical_significance". <br>To colour by range
113       of a numeric attribute, include <em>mincolor</em> and <em>maxcolor</em>,
114       or omit to colour by text (category). <br>(Note: the value of
115       the attribute used for colouring will also be shown in the tooltip
116       as you mouse over features.) <br>A sub-attribute should be
117       written as, for example, CSQ:IMPACT. <br>
118     <em>This keyword was added in Jalview 2.11</em></li>
119
120     <li><em>mincolor</em> and <em>maxcolor</em><br> Colour
121       triplets specified as hexadecimal or comma separated values (may
122       be left blank for a <em>label</em> style colourscheme, but
123       remember to specify the remaining fields)</li>
124
125     <li><em>absolute</em><br> An optional switch indicating
126       that the <em>minvalue</em> and <em>maxvalue</em> parameters should
127       be left as is, rather than rescaled according to the range of
128       scores for this feature type.<br /> <em>This also enables
129         the 'Threshold is Min/Max' option for this type's feature
130         shading style dialog.</em></li>
131
132     <li><em>minvalue</em> and <em>maxvalue</em><br> Minimum
133       and maximum values defining the range of scores for which the
134       colour range will be defined over.<br>If minvalue is greater
135       than maxvalue then the linear mapping will have negative gradient.</li>
136
137     <li><em>novalue</em> <br> Specifies the colour to use if
138       colouring by attribute, when the attribute is absent. Valid
139       options are <em>novaluemin, novaluemax, novaluenone</em>, to use
140       mincolor, maxcolor, or no colour. <br>If not specified this
141       will default to novaluemin.</li>
142
143     <li><em>thresholdtype</em><br> Either &quot;none&quot;,
144       &quot;below&quot;, or &quot;above&quot;. <em>below</em> and <em>above</em>
145       require an additional <em>threshold value</em> which is used to
146       control the display of features with a score either below or above
147       the value.</li>
148   </ul>
149
150   <p>
151     <strong><a name="filterdefs">Feature Filters</a></strong>
152   </p>
153   <p>This section is optional, and allows one or more filters to be defined for each feature type.
154      <br>Only features that satisfy the filter conditions will be displayed.
155      <br>Begin with a line which is just STARTFILTERS, and end with a line which is just ENDFILTERS.
156      <br>Each line has the format:
157      <pre>featureType <em>&lt;tab&gt;</em> (filtercondition1) [and|or] (filtercondition2) [and|or]...<br></pre>
158      The parentheses are not needed if there is only one condition. 
159      Combine multiple conditions with either <em>and</em> or <em>or</em> (but not a mixture).
160      <br>Each condition is written as:
161      <pre>Label <em>or</em> Score <em>or</em> AttributeName condition [value]</pre>
162      where either the label (description), (numeric) score, or (text or numeric) attribute is tested against the condition.
163      <br><em>condition</em> is not case sensitive, and should be one of
164      <ul>
165      <li><em>Contains</em> - description (or attribute) should contain the given value (not case sensitive); example <em>clinical_significance contains Pathogenic</em></li> 
166      <li><em>NotContains</em> - description (or attribute) should not contain the given value</li> 
167      <li><em>Matches</em> - description (or attribute)  should match the given value (not case sensitive)</li> 
168      <li><em>NotMatches</em> - description (or attribute) should not match the given value (not case sensitive)</li> 
169      <li><em>Present</em> - attribute is present on the feature (no value required); example <em>CSQ:SIFT present</em></li> 
170      <li><em>NotPresent</em> - attribute is not present on the feature (no value required)</li> 
171      <li><em>EQ</em> - feature score, or specified attribute, is equal to the (numeric) value</li> 
172      <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> 
173      </ul>
174      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:
175      <em>'mutagenesis site' contains 'decreased affinity'</em>
176      <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.
177      <br><em>Feature filters were added in Jalview 2.11</em>
178   </p>
179
180   <p>
181     <strong><a name="featuredef">Feature Definitions</a></strong>
182   </p>
183
184   <p>The remaining lines in the file are sequence feature data.
185     Features are either non-positional - attached to a whole sequence
186     (as specified by its ID), or positional, so attached to a specific
187     range on a sequence. In addition to a type, features can also
188     include descriptive text and a score, and depending on the format
189     used, many additional attributes.</p>
190
191   <em><a name="gff">Importing Generalised Feature Format (GFF) feature data</a></em>
192   <p>
193     Jalview has its own tabular format (described below) for describing
194     sequence features, which allows HTML descriptions (including URLs)
195     to be defined for each feature. However, sequence feature
196     definitions can also be provided in <a
197       href="http://gmod.org/wiki/GFF2">GFF2</a>
198     (http://gmod.org/wiki/GFF2) or <a
199       href="https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md">GFF3</a>
200     (http://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md)
201     format. To do this, a line containing only 'GFF' should precede any
202     GFF data (<em>this mixed format capability was added in Jalview
203       2.6</em>).
204   </p>
205   <p>Feature attributes can be included as <code>name=value</code> pairs in GFF3 column 9, including <em>(since Jalview 2.11.1.0)</em> 'nested' sub-attributes, for example:
206   <br><code>alleles=G,A,C;AF=6;CSQ=SIFT=deleterious,tolerated,PolyPhen=possibly_damaging(0.907)</code>
207   <br>where <code>SIFT</code> and <code>PolyPhen</code> are sub-attributes of <code>CSQ</code>. This data is preserved if features are exported in GFF format (but not, currently,
208   in Jalview format).
209   </p>
210   <p>
211     <em>Jalview's sequence feature format</em>
212   </p>
213   <p>Each feature is specified as a tab-separated series of columns
214     as defined below:
215   <pre>
216 <em>description</em>&#9;<em>sequenceId</em>&#9;<em>sequenceIndex</em>&#9;<em>start</em>&#9;<em>end</em>&#9;<em>featureType</em>&#9;<em>score (optional)</em>
217 </pre>
218
219   This format allows two alternate ways of referring to a sequence,
220   either by its text ID, or its index (base 0) in an associated
221   alignment. Normally, sequence features are associated with sequences
222   rather than alignments, and the sequenceIndex field is given as
223   &quot;-1&quot;. In order to specify a sequence by its index in a
224   particular alignment, the sequenceId should be given as
225   &quot;ID_NOT_SPECIFIED&quot;, otherwise the sequenceId field will be
226   used in preference to the sequenceIndex field.
227   </p>
228
229
230   <p>
231     The description may contain simple HTML document body tags if
232     enclosed by &quot;&lt;html&gt;&lt;/html&gt;&quot; and these will be
233     rendered as formatted tooltips in the Jalview Application (the
234     Jalview applet is not capable of rendering HTML tooltips, so all
235     formatting tags will be removed).<br> <em>Attaching Links
236       to Sequence Features</em><br> Any anchor tags in an html formatted
237     description line will be translated into URL links. A link symbol
238     will be displayed adjacent to any feature which includes links, and
239     these are made available from the <a
240       href="../menus/popupMenu.html#sqid.popup">links submenu</a>
241     of the popup menu which is obtained by right-clicking when a link
242     symbol is displayed in the tooltip.<br> <em>Non-positional
243       features</em><br> Specify the <em>start</em> and <em>end</em> for
244     a feature to be <strong>0</strong> in order to attach it to the
245     whole sequence. Non-positional features are shown in a tooltip when
246     the mouse hovers over the sequence ID panel, and any embedded links
247     can be accessed from the popup menu.<br /> <em>Scores</em><br>
248     Scores can be associated with sequence features, and used to sort
249     sequences or shade the alignment (this was added in Jalview 2.5).
250     The score field is optional, and malformed scores will be ignored.
251   </p>
252
253   <p>Feature annotations can be collected into named groups by
254     prefixing definitions with lines of the form:
255   <pre>
256 <strong>startgroup      groupname</strong>
257 </pre>
258
259   .. and subsequently post-fixing the group with:
260
261   <pre>
262 <strong>endgroup        groupname</strong>
263 </pre>
264
265   Feature grouping was introduced in version 2.08, and used to control
266   whether a set of features are either hidden or shown together in the
267   <a href="seqfeatures.html">sequence Feature settings dialog box</a>.
268   </p>
269
270
271   <p>A complete example is shown below :
272   <pre>
273 domain&#9;red
274 metal ion-binding site&#9;00ff00
275 transit peptide&#9;0,105,215
276 chain&#9;225,105,0
277 modified residue&#9;105,225,35
278 signal peptide&#9;0,155,165
279 helix&#9;ff0000
280 strand&#9;00ff00
281 coil&#9;cccccc
282 kdHydrophobicity&#9;ccffcc|333300|-3.9|4.5|above|-2.0
283
284 STARTFILTERS
285 metal ion-binding site&#9;Label Contains sulfur
286 kdHydrophobicity&#9;(Score LT 1.5) OR (Score GE 2.8)
287 ENDFILTERS
288
289 Your Own description here&#9;FER_CAPAA&#9;-1&#9;3&#9;93&#9;domain
290 Your Own description here&#9;FER_CAPAN&#9;-1&#9;48&#9;144&#9;chain
291 Your Own description here&#9;FER_CAPAN&#9;-1&#9;50&#9;140&#9;domain
292 Your Own description here&#9;FER_CAPAN&#9;-1&#9;136&#9;136&#9;modified residue
293 Your Own description here&#9;FER1_LYCES&#9;-1&#9;1&#9;47&#9;transit peptide
294 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;1&#9;48&#9;signal peptide
295 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;49&#9;144&#9;chain
296
297 STARTGROUP&#9;secondarystucture
298 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;52&#9;59&#9;strand
299 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;74&#9;80&#9;helix
300 ENDGROUP&#9;secondarystructure
301
302 STARTGROUP&#9;kd
303 Hydrophobicity score by kD      Q93XJ9_SOLTU    -1      48      48      kdHydrophobicity        1.8
304 ENDGROUP&#9;kd
305
306 GFF
307 FER_CAPAA&#9;GffGroup&#9;domain&#9;3&#9;93&#9;.&#9;.
308 </pre>
309 </body>
310 </html>
311