JAL-2416 score matrix gap symbol (if any) dynamically determined
[jalview.git] / 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   <p>
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>
37
38   <p>
39     Features files are imported into Jalview in the following ways:<br>
40   <ul>
41     <li>from the command line <pre>
42 <strong> -features &lt;<em>Features filename</em>&gt;</strong>
43 </pre>
44     </li>
45
46     <li>Dragging a features file onto an alignment window</li>
47
48     <li>Via the &quot;Load Features / Annotations&quot; entry in
49       the <strong>File</strong> menu of an alignment window.
50     </li>
51   </ul>
52
53   </p>
54
55   <p>
56     <strong>Sequence Features File Format</strong>
57   </p>
58   <p>
59     A features file is a simple ASCII text file, where each line
60     contains tab separated text fields. <strong>No comments are
61       allowed</strong>.
62   </p>
63   <p>The first set of lines contain type definitions:
64   <pre>
65 <strong><em>Feature label</em>&#9;<em>Feature Colour</em>
66 <!-- &#9;<em>Feature links</em>  --></strong>
67 </pre>
68
69   A feature type has a text label, and a colour specification. This can
70   be either:
71
72   <ul>
73     <li>A single colour specified as either a red,green,blue 24 bit
74       triplet in hexadecimal (eg. 00ff00) or as comma separated numbers
75       (ranging from 0 to 255))</li>
76
77     <li>A <a href="featureschemes.html">graduated colourscheme</a>
78       specified as a "|" separated list of fields: <pre>
79 [label|]&lt;mincolor&gt;|&lt;maxcolor&gt;|[absolute|]&lt;minvalue&gt;|&lt;maxvalue&gt;[|&lt;thresholdtype&gt;|[&lt;threshold value&gt;]]
80 </pre> The fields are as follows:
81
82       <ul>
83         <li><em>label</em><br> Indicate that the feature
84           description should be used to create a colour for features of
85           this type.<br> <em>Note: if no threshold value is
86             needed then the final '|' may be omitted.<br> This
87             keyword was added in Jalview 2.6
88         </em></li>
89
90         <li><em>mincolor</em> and <em>maxcolor</em><br> Colour
91           triplets specified as hexadecimal or comma separated values
92           (may be left blank for a <em>label</em> style colourscheme,
93           but remember to specify the remaining fields)</li>
94
95         <li><em>absolute</em><br> An optional switch
96           indicating that the <em>minvalue</em> and <em>maxvalue</em>
97           parameters should be left as is, rather than rescaled
98           according to the range of scores for this feature type.</li>
99
100         <li><em>minvalue</em> and <em>maxvalue</em><br>
101           Minimum and maximum values defining the range of scores for
102           which the colour range will be defined over. If minvalue is
103           greater than maxvalue then the linear mapping will have
104           negative gradient.</li>
105
106         <li><em>thresholdtype</em><br> Either
107           &quot;none&quot;, &quot;below&quot;, or &quot;above&quot;. <em>below</em>
108           and <em>above</em> require an additional <em>threshold
109             value</em> which is used to control the display of features with
110           a score either below or above the value.</li>
111       </ul>
112     </li>
113   </ul>
114   </p>
115
116   <p>The remaining lines in the file are the sequence annotation
117     definitions, where the now defined features are attached to regions
118     on particular sequences. Each feature can optionally include some
119     descriptive text which is displayed in a tooltip when the mouse is
120     near the feature on that sequence (and can also be used to generate
121     a colour the feature).</p>
122
123   <p>
124     If your sequence annotation is already available in <a href="http://gmod.org/wiki/GFF2">GFF2</a> (http://gmod.org/wiki/GFF2) or
125     <a href="https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md">GFF3</a> 
126     (http://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md) format, 
127     then you can leave it as is, after first adding a line containing only
128     'GFF' after any Jalview feature colour definitions (<em>this
129     mixed format capability was added in Jalview 2.6</em>). Alternately,
130     you can use Jalview's own sequence feature annotation format, which
131     additionally allows HTML and URLs to be directly attached to each
132     piece of annotation.
133   </p>
134
135   <p>
136     <strong>Jalview's sequence feature annotation format</strong>
137   </p>
138   <p>Each feature is specified as a tab-separated series of columns
139     as defined below:
140   <pre>
141 <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>
142 </pre>
143
144   This format allows two alternate ways of referring to a sequence,
145   either by its text ID, or its index (base 0) in an associated
146   alignment. Normally, sequence features are associated with sequences
147   rather than alignments, and the sequenceIndex field is given as
148   &quot;-1&quot;. In order to specify a sequence by its index in a
149   particular alignment, the sequenceId should be given as
150   &quot;ID_NOT_SPECIFIED&quot;, otherwise the sequenceId field will be
151   used in preference to the sequenceIndex field.
152   </p>
153
154
155   <p>
156     The description may contain simple HTML document body tags if
157     enclosed by &quot;&lt;html&gt;&lt;/html&gt;&quot; and these will be
158     rendered as formatted tooltips in the Jalview Application (the
159     Jalview applet is not capable of rendering HTML tooltips, so all
160     formatting tags will be removed).<br> <em>Attaching Links
161       to Sequence Features</em><br> Any anchor tags in an html formatted
162     description line will be translated into URL links. A link symbol
163     will be displayed adjacent to any feature which includes links, and
164     these are made available from the <a
165       href="../menus/popupMenu.html#sqid.popup">links submenu</a>
166     of the popup menu which is obtained by right-clicking when a link
167     symbol is displayed in the tooltip.<br> <em>Non-positional
168       features</em><br> Specify the <em>start</em> and <em>end</em> for
169     a feature to be <strong>0</strong> in order to attach it to the
170     whole sequence. Non-positional features are shown in a tooltip when
171     the mouse hovers over the sequence ID panel, and any embedded links
172     can be accessed from the popup menu.<br /> <em>Scores</em><br>
173     Scores can be associated with sequence features, and used to sort
174     sequences or shade the alignment (this was added in Jalview 2.5).
175     The score field is optional, and malformed scores will be ignored.
176   </p>
177
178   <p>Feature annotations can be collected into named groups by
179     prefixing definitions with lines of the form:
180   <pre>
181 <strong>startgroup      groupname</strong>
182 </pre>
183
184   .. and subsequently post-fixing the group with:
185
186   <pre>
187 <strong>endgroup        groupname</strong>
188 </pre>
189
190   Feature grouping was introduced in version 2.08, and used to control
191   whether a set of features are either hidden or shown together in the
192   <a href="seqfeatures.html">sequence Feature settings dialog box</a>.
193   </p>
194
195
196   <p>A complete example is shown below :
197   <pre>
198 domain&#9;red
199 metal ion-binding site&#9;00ff00
200 transit peptide&#9;0,105,215
201 chain&#9;225,105,0
202 modified residue&#9;105,225,35
203 signal peptide&#9;0,155,165
204 helix&#9;ff0000
205 strand&#9;00ff00
206 coil&#9;cccccc
207 Your Own description here&#9;FER_CAPAA&#9;-1&#9;3&#9;93&#9;domain
208 Your Own description here&#9;FER_CAPAN&#9;-1&#9;48&#9;144&#9;chain
209 Your Own description here&#9;FER_CAPAN&#9;-1&#9;50&#9;140&#9;domain
210 Your Own description here&#9;FER_CAPAN&#9;-1&#9;136&#9;136&#9;modified residue
211 Your Own description here&#9;FER1_LYCES&#9;-1&#9;1&#9;47&#9;transit peptide
212 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;1&#9;48&#9;signal peptide
213 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;49&#9;144&#9;chain
214 startgroup&#9;secondarystucture
215 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;52&#9;59&#9;strand
216 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;74&#9;80&#9;helix
217 endgroup&#9;secondarystructure
218 GFF
219 FER_CAPAA&#9;GffGroup&#9;domain&#9;3&#9;93&#9;.&#9;.
220 </pre>
221 </body>
222 </html>
223