help/html/features/featuresFormat.html

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