help/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>
  64     <strong>Feature Colours</strong>
  65   </p>
  66   <p>The first set of lines contain feature type definitions and their colours:
  67   <pre>
  68 <strong><em>Feature label</em>&#9;<em>Feature Colour</em>
  69 <!-- &#9;<em>Feature links</em>  --></strong>
  70 </pre>
  71
  72   A feature type has a text label, and a colour specification. This can
  73   be either:
  74
  75   <ul>
  76     <li>A single colour specified as either a red,green,blue 24 bit
  77       triplet in hexadecimal (eg. 00ff00) or as comma separated numbers
  78       (ranging from 0 to 255))<br>
  79       (For help with colour values, see <a href="https://www.w3schools.com/colors/colors_converter.asp">https://www.w3schools.com/colors/colors_converter.asp</a>.)</li>
  80
  81     <li>A <a href="featureschemes.html">graduated colourscheme</a>
  82       specified as a "|" separated list of fields: <pre>
  83 [label <em>or</em> score<em> or</em> attribute|attName|]&lt;mincolor&gt;|&lt;maxcolor&gt;|[absolute|]&lt;minvalue&gt;|&lt;maxvalue&gt;[|&lt;novalue&gt;][|&lt;thresholdtype&gt;|[&lt;threshold value&gt;]]
  84 </pre> The fields are as follows:
  85
  86       <ul>
  87         <li><em>label</em><br> Indicates that the feature
  88           description should be used to create a colour for features of
  89           this type.<br> <em>Note: if no threshold value is
  90             needed then only 'label' is required.<br> This
  91             keyword was added in Jalview 2.6
  92         </em></li>
  93
  94         <li><em>score</em><br> Indicates that the feature
  95           score should be used to create a graduated colour for features of
  96           this type, in conjunction with mincolor, maxcolor.<br><em>This keyword was added in Jalview 2.11.
  97           It may be omitted (score is the default) if mincolor and maxcolor are specified.
  98         </em></li>
  99
 100         <li><em>attribute|attName</em><br> Indicates that the value of feature
 101           attribute 'attName' should be used to create a colour for features of
 102           this type.
 103           <br>For example, <em>attribute|clinical_significance</em> to colour by clinical_significance.
 104           <br>To colour by range of a numeric attribute, include <em>mincolor</em> and <em>maxcolor</em>, or omit to colour by text (category).
 105           <br>(Note: the value of the attribute used for colouring will also be shown in the tooltip as you mouse over features.)
 106           <br>A sub-attribute should be written as, for example, CSQ:IMPACT.
 107           <br><em>This keyword was added in Jalview 2.11</em></li>
 108
 109         <li><em>mincolor</em> and <em>maxcolor</em><br> Colour
 110           triplets specified as hexadecimal or comma separated values
 111           (may be left blank for a <em>label</em> style colourscheme,
 112           but remember to specify the remaining fields)</li>
 113
 114         <li><em>absolute</em><br> An optional switch
 115           indicating that the <em>minvalue</em> and <em>maxvalue</em>
 116           parameters should be left as is, rather than rescaled
 117           according to the range of scores for this feature type.</li>
 118
 119         <li><em>minvalue</em> and <em>maxvalue</em><br>
 120           Minimum and maximum values defining the range of scores for
 121           which the colour range will be defined over.<br>If minvalue is
 122           greater than maxvalue then the linear mapping will have
 123           negative gradient.</li>
 124
 125         <li><em>novalue</em> <br>
 126           Specifies the colour to use if colouring by attribute, when the attribute is absent.
 127           Valid options are <em>novaluemin, novaluemax, novaluenone</em>, to use mincolor, maxcolor, or no colour.
 128           <br>If not specified this will default to novaluemin.</li>
 129
 130         <li><em>thresholdtype</em><br> Either
 131           &quot;none&quot;, &quot;below&quot;, or &quot;above&quot;. <em>below</em>
 132           and <em>above</em> require an additional <em>threshold
 133             value</em> which is used to control the display of features with
 134           a score either below or above the value.</li>
 135       </ul>
 136     </li>
 137   </ul>
 138   </p>
 139
 140   <p>
 141     <strong>Feature Filters</strong>
 142   </p>
 143   <p>This section is optional, and allows one or more filters to be defined for each feature type.
 144      <br>Only features that satisfy the filter conditions will be displayed.
 145      <br>Begin with a line which is just STARTFILTERS, and end with a line which is just ENDFILTERS.
 146      <br>Each line has the format:
 147      <pre>featureType <em>&lt;tab&gt;</em> (filtercondition1) [and|or] (filtercondition2) [and|or]...<br></pre>
 148      The parentheses are not needed if there is only one condition.
 149      Combine multiple conditions with either <em>and</em> or <em>or</em> (but not a mixture).
 150      <br>Each condition is written as:
 151      <pre>Label <em>or</em> Score <em>or</em> AttributeName condition [value]</pre>
 152      where either the label (description), (numeric) score, or (text or numeric) attribute is tested against the condition.
 153      <br><em>condition</em> is not case sensitive, and should be one of
 154      <ul>
 155      <li><em>Contains</em> - description (or attribute) should contain the given value (not case sensitive); example <em>clinical_significance contains Pathogenic</em></li>
 156      <li><em>NotContains</em> - description (or attribute) should not contain the given value</li>
 157      <li><em>Matches</em> - description (or attribute)  should match the given value (not case sensitive)</li>
 158      <li><em>NotMatches</em> - description (or attribute) should not match the given value (not case sensitive)</li>
 159      <li><em>Present</em> - attribute is present on the feature (no value required); example <em>CSQ:SIFT present</em></li>
 160      <li><em>NotPresent</em> - attribute is not present on the feature (no value required)</li>
 161      <li><em>EQ</em> - feature score, or specified attribute, is equal to the (numeric) value</li>
 162      <li><em>NE, LT, LE, GT, GE</em> - tests for not equal to / less than / less than or equal to / greater than / greater than or equal to the value</li>
 163      </ul>
 164      A non-numeric value always fails a numeric test.<br>If either attribute name, or value to compare, contains spaces, then enclose in single quotes:
 165      <em>'mutagenesis site' contains 'decreased affinity'</em>
 166      <br>Tip: some examples of filter syntax are given below; or to see more, first configure colours and filters in Jalview, then <em>File | Export Features</em> to Textbox in Jalview Format.
 167      <br><em>Feature filters were added in Jalview 2.11</em>
 168   </p>
 169
 170   <p>
 171     <strong>Feature Instances</strong>
 172   </p>
 173
 174   <p>The remaining lines in the file are the sequence annotation
 175     definitions, where the now defined features are attached to regions
 176     on particular sequences. Each feature can optionally include some
 177     descriptive text which is displayed in a tooltip when the mouse is
 178     near the feature on that sequence (and may also be used to generate
 179     a colour for the feature).</p>
 180
 181   <p>
 182     If your sequence annotation is already available in <a href="http://gmod.org/wiki/GFF2">GFF2</a> (http://gmod.org/wiki/GFF2) or
 183     <a href="https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md">GFF3</a>
 184     (http://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md) format,
 185     then you can leave it as is, after first adding a line containing only
 186     'GFF' after any Jalview feature colour definitions (<em>this
 187     mixed format capability was added in Jalview 2.6</em>). Alternately,
 188     you can use Jalview's own sequence feature annotation format, which
 189     additionally allows HTML and URLs to be directly attached to each
 190     piece of annotation.
 191   </p>
 192
 193   <p>
 194     <strong>Jalview's sequence feature annotation format</strong>
 195   </p>
 196   <p>Each feature is specified as a tab-separated series of columns
 197     as defined below:
 198   <pre>
 199 <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>
 200 </pre>
 201
 202   This format allows two alternate ways of referring to a sequence,
 203   either by its text ID, or its index (base 0) in an associated
 204   alignment. Normally, sequence features are associated with sequences
 205   rather than alignments, and the sequenceIndex field is given as
 206   &quot;-1&quot;. In order to specify a sequence by its index in a
 207   particular alignment, the sequenceId should be given as
 208   &quot;ID_NOT_SPECIFIED&quot;, otherwise the sequenceId field will be
 209   used in preference to the sequenceIndex field.
 210   </p>
 211
 212
 213   <p>
 214     The description may contain simple HTML document body tags if
 215     enclosed by &quot;&lt;html&gt;&lt;/html&gt;&quot; and these will be
 216     rendered as formatted tooltips in the Jalview Application (the
 217     Jalview applet is not capable of rendering HTML tooltips, so all
 218     formatting tags will be removed).<br> <em>Attaching Links
 219       to Sequence Features</em><br> Any anchor tags in an html formatted
 220     description line will be translated into URL links. A link symbol
 221     will be displayed adjacent to any feature which includes links, and
 222     these are made available from the <a
 223       href="../menus/popupMenu.html#sqid.popup">links submenu</a>
 224     of the popup menu which is obtained by right-clicking when a link
 225     symbol is displayed in the tooltip.<br> <em>Non-positional
 226       features</em><br> Specify the <em>start</em> and <em>end</em> for
 227     a feature to be <strong>0</strong> in order to attach it to the
 228     whole sequence. Non-positional features are shown in a tooltip when
 229     the mouse hovers over the sequence ID panel, and any embedded links
 230     can be accessed from the popup menu.<br /> <em>Scores</em><br>
 231     Scores can be associated with sequence features, and used to sort
 232     sequences or shade the alignment (this was added in Jalview 2.5).
 233     The score field is optional, and malformed scores will be ignored.
 234   </p>
 235
 236   <p>Feature annotations can be collected into named groups by
 237     prefixing definitions with lines of the form:
 238   <pre>
 239 <strong>startgroup      groupname</strong>
 240 </pre>
 241
 242   .. and subsequently post-fixing the group with:
 243
 244   <pre>
 245 <strong>endgroup        groupname</strong>
 246 </pre>
 247
 248   Feature grouping was introduced in version 2.08, and used to control
 249   whether a set of features are either hidden or shown together in the
 250   <a href="seqfeatures.html">sequence Feature settings dialog box</a>.
 251   </p>
 252
 253
 254   <p>A complete example is shown below :
 255   <pre>
 256 domain&#9;red
 257 metal ion-binding site&#9;00ff00
 258 transit peptide&#9;0,105,215
 259 chain&#9;225,105,0
 260 modified residue&#9;105,225,35
 261 signal peptide&#9;0,155,165
 262 helix&#9;ff0000
 263 strand&#9;00ff00
 264 coil&#9;cccccc
 265 kdHydrophobicity&#9;ccffcc|333300|-3.9|4.5|above|-2.0
 266
 267 STARTFILTERS
 268 metal ion-binding site&#9;Label Contains sulfur
 269 kdHydrophobicity&#9;(Score LT 1.5) OR (Score GE 2.8)
 270 ENDFILTERS
 271
 272 Your Own description here&#9;FER_CAPAA&#9;-1&#9;3&#9;93&#9;domain
 273 Your Own description here&#9;FER_CAPAN&#9;-1&#9;48&#9;144&#9;chain
 274 Your Own description here&#9;FER_CAPAN&#9;-1&#9;50&#9;140&#9;domain
 275 Your Own description here&#9;FER_CAPAN&#9;-1&#9;136&#9;136&#9;modified residue
 276 Your Own description here&#9;FER1_LYCES&#9;-1&#9;1&#9;47&#9;transit peptide
 277 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;1&#9;48&#9;signal peptide
 278 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;49&#9;144&#9;chain
 279
 280 STARTGROUP&#9;secondarystucture
 281 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;52&#9;59&#9;strand
 282 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;74&#9;80&#9;helix
 283 ENDGROUP&#9;secondarystructure
 284
 285 STARTGROUP&#9;kd
 286 Hydrophobicity score by kD      Q93XJ9_SOLTU    -1      48      48      kdHydrophobicity        1.8
 287 ENDGROUP&#9;kd
 288
 289 GFF
 290 FER_CAPAA&#9;GffGroup&#9;domain&#9;3&#9;93&#9;.&#9;.
 291 </pre>
 292 </body>
 293 </html>
 294