help/html/features/featuresFormat.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.9)
   4  * Copyright (C) 2015 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 ommitted.<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 GFF Format (see
 125     <a href="http://www.sanger.ac.uk/resources/software/gff/spec.html">http://www.sanger.ac.uk/resources/software/gff/spec.html</a>),
 126     then you can leave it as is, after first adding a line containing
 127     only 'GFF' after any Jalview feature colour definitions (<em>this
 128       mixed format capability was added in Jalview 2.6</em>). Alternately,
 129     you can use Jalview's own sequence feature annotation format, which
 130     additionally allows HTML and URLs to be directly attached to each
 131     piece of annotation.
 132   </p>
 133
 134   <p>
 135     <strong>Jalview's sequence feature annotation format</strong>
 136   </p>
 137   <p>Each feature is specified as a tab-separated series of columns
 138     as defined below:
 139   <pre>
 140 <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>
 141 </pre>
 142
 143   This format allows two alternate ways of referring to a sequence,
 144   either by its text ID, or its index in an associated alignment.
 145   Normally, sequence features are associated with sequences rather than
 146   alignments, and the sequenceIndex field is given as &quot;-1&quot;. In
 147   order to specify a sequence by its index in a particular alignment,
 148   the sequenceId should be given as &quot;ID_NOT_SPECIFIED&quot;,
 149   otherwise the sequenceId field will be used in preference to the
 150   sequenceIndex field.
 151   </p>
 152
 153
 154   <p>
 155     The description may contain simple HTML document body tags if
 156     enclosed by &quot;&lt;html&gt;&lt;/html&gt;&quot; and these will be
 157     rendered as formatted tooltips in the Jalview Application (the
 158     Jalview applet is not capable of rendering HTML tooltips, so all
 159     formatting tags will be removed).<br> <em>Attaching Links
 160       to Sequence Features</em><br> Any anchor tags in an html formatted
 161     description line will be translated into URL links. A link symbol
 162     will be displayed adjacent to any feature which includes links, and
 163     these are made available from the <a
 164       href="../menus/popupMenu.html#sqid.popup"
 165     >links submenu</a> of the popup menu which is obtained by
 166     right-clicking when a link symbol is displayed in the tooltip.<br>
 167     <em>Non-positional features</em><br> Specify the <em>start</em>
 168     and <em>end</em> for a feature to be <strong>0</strong> in order to
 169     attach it to the whole sequence. Non-positional features are shown
 170     in a tooltip when the mouse hovers over the sequence ID panel, and
 171     any embedded links can be accessed from the popup menu.<br /> <em>Scores</em><br>
 172     Scores can be associated with sequence features, and used to sort
 173     sequences or shade the alignment (this was added in Jalview 2.5).
 174     The score field is optional, and malformed scores will be ignored.
 175   </p>
 176
 177   <p>Feature annotations can be collected into named groups by
 178     prefixing definitions with lines of the form:
 179   <pre>
 180 <strong>startgroup      groupname</strong>
 181 </pre>
 182
 183   .. and subsequently post-fixing the group with:
 184
 185   <pre>
 186 <strong>endgroup        groupname</strong>
 187 </pre>
 188
 189   Feature grouping was introduced in version 2.08, and used to control
 190   whether a set of features are either hidden or shown together in the
 191   <a href="seqfeatures.html">sequence Feature settings dialog box</a>.
 192   </p>
 193
 194
 195   <p>A complete example is shown below :
 196   <pre>
 197 domain&#9;red
 198 metal ion-binding site&#9;00ff00
 199 transit peptide&#9;0,105,215
 200 chain&#9;225,105,0
 201 modified residue&#9;105,225,35
 202 signal peptide&#9;0,155,165
 203 helix&#9;ff0000
 204 strand&#9;00ff00
 205 coil&#9;cccccc
 206 Your Own description here&#9;FER_CAPAA&#9;-1&#9;3&#9;93&#9;domain
 207 Your Own description here&#9;FER_CAPAN&#9;-1&#9;48&#9;144&#9;chain
 208 Your Own description here&#9;FER_CAPAN&#9;-1&#9;50&#9;140&#9;domain
 209 Your Own description here&#9;FER_CAPAN&#9;-1&#9;136&#9;136&#9;modified residue
 210 Your Own description here&#9;FER1_LYCES&#9;-1&#9;1&#9;47&#9;transit peptide
 211 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;1&#9;48&#9;signal peptide
 212 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;49&#9;144&#9;chain
 213 startgroup&#9;secondarystucture
 214 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;52&#9;59&#9;strand
 215 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;74&#9;80&#9;helix
 216 endgroup&#9;secondarystructure
 217 GFF
 218 FER_CAPAA&#9;GffGroup&#9;domain&#9;3&#9;93&#9;.&#9;.
 219 </pre>
 220 </body>
 221 </html>
 222