help/html/features/featuresFormat.html

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