help/html/features/featuresFormat.html

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