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