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|Score|AttributeName condition [value]</pre>
 152      where <em>condition</em> is not case sensitive, and should be one of
 153      <ul>
 154      <li><em>Contains</em> - value should contain the given text (not case sensitive); example <em>clinical_significance contains Pathogenic</em></li>
 155      <li><em>NotContains</em> - value should not contain the given text</li>
 156      <li><em>Matches</em> - value should match the given text (not case sensitive)</li>
 157      <li><em>NotMatches</em> - value should not match the given text (not case sensitive)</li>
 158      <li><em>Present</em> - specified attribute is present on the feature (no value required); example <em>CSQ:SIFT present</em></li>
 159      <li><em>NotPresent</em> - specified attribute is not present on the feature (no value required)</li>
 160      <li><em>EQ</em> - feature score, or specified attribute, is equal to the (numeric) value</li>
 161      <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>
 162      </ul>
 163      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:
 164      <em>'mutagenesis site' contains 'decreased affinity'</em>
 165      <br>Tip: to see examples of valid syntax, first configure colours and filters in Jalview, then <em>File | Export Features</em> to Textbox in Jalview Format.
 166      <br><em>Feature filters were added in Jalview 2.11</em>
 167   </p>
 168
 169   <p>
 170     <strong>Feature Instances</strong>
 171   </p>
 172
 173   <p>The remaining lines in the file are the sequence annotation
 174     definitions, where the now defined features are attached to regions
 175     on particular sequences. Each feature can optionally include some
 176     descriptive text which is displayed in a tooltip when the mouse is
 177     near the feature on that sequence (and may also be used to generate
 178     a colour for the feature).</p>
 179
 180   <p>
 181     If your sequence annotation is already available in <a href="http://gmod.org/wiki/GFF2">GFF2</a> (http://gmod.org/wiki/GFF2) or
 182     <a href="https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md">GFF3</a>
 183     (http://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md) format,
 184     then you can leave it as is, after first adding a line containing only
 185     'GFF' after any Jalview feature colour definitions (<em>this
 186     mixed format capability was added in Jalview 2.6</em>). Alternately,
 187     you can use Jalview's own sequence feature annotation format, which
 188     additionally allows HTML and URLs to be directly attached to each
 189     piece of annotation.
 190   </p>
 191
 192   <p>
 193     <strong>Jalview's sequence feature annotation format</strong>
 194   </p>
 195   <p>Each feature is specified as a tab-separated series of columns
 196     as defined below:
 197   <pre>
 198 <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>
 199 </pre>
 200
 201   This format allows two alternate ways of referring to a sequence,
 202   either by its text ID, or its index (base 0) in an associated
 203   alignment. Normally, sequence features are associated with sequences
 204   rather than alignments, and the sequenceIndex field is given as
 205   &quot;-1&quot;. In order to specify a sequence by its index in a
 206   particular alignment, the sequenceId should be given as
 207   &quot;ID_NOT_SPECIFIED&quot;, otherwise the sequenceId field will be
 208   used in preference to the sequenceIndex field.
 209   </p>
 210
 211
 212   <p>
 213     The description may contain simple HTML document body tags if
 214     enclosed by &quot;&lt;html&gt;&lt;/html&gt;&quot; and these will be
 215     rendered as formatted tooltips in the Jalview Application (the
 216     Jalview applet is not capable of rendering HTML tooltips, so all
 217     formatting tags will be removed).<br> <em>Attaching Links
 218       to Sequence Features</em><br> Any anchor tags in an html formatted
 219     description line will be translated into URL links. A link symbol
 220     will be displayed adjacent to any feature which includes links, and
 221     these are made available from the <a
 222       href="../menus/popupMenu.html#sqid.popup">links submenu</a>
 223     of the popup menu which is obtained by right-clicking when a link
 224     symbol is displayed in the tooltip.<br> <em>Non-positional
 225       features</em><br> Specify the <em>start</em> and <em>end</em> for
 226     a feature to be <strong>0</strong> in order to attach it to the
 227     whole sequence. Non-positional features are shown in a tooltip when
 228     the mouse hovers over the sequence ID panel, and any embedded links
 229     can be accessed from the popup menu.<br /> <em>Scores</em><br>
 230     Scores can be associated with sequence features, and used to sort
 231     sequences or shade the alignment (this was added in Jalview 2.5).
 232     The score field is optional, and malformed scores will be ignored.
 233   </p>
 234
 235   <p>Feature annotations can be collected into named groups by
 236     prefixing definitions with lines of the form:
 237   <pre>
 238 <strong>startgroup      groupname</strong>
 239 </pre>
 240
 241   .. and subsequently post-fixing the group with:
 242
 243   <pre>
 244 <strong>endgroup        groupname</strong>
 245 </pre>
 246
 247   Feature grouping was introduced in version 2.08, and used to control
 248   whether a set of features are either hidden or shown together in the
 249   <a href="seqfeatures.html">sequence Feature settings dialog box</a>.
 250   </p>
 251
 252
 253   <p>A complete example is shown below :
 254   <pre>
 255 domain&#9;red
 256 metal ion-binding site&#9;00ff00
 257 transit peptide&#9;0,105,215
 258 chain&#9;225,105,0
 259 modified residue&#9;105,225,35
 260 signal peptide&#9;0,155,165
 261 helix&#9;ff0000
 262 strand&#9;00ff00
 263 coil&#9;cccccc
 264 kdHydrophobicity&#9;ccffcc|333300|-3.9|4.5|above|-2.0
 265
 266 STARTFILTERS
 267 metal ion-binding site&#9;Label Contains sulfur
 268 kdHydrophobicity&#9;(Score LT 1.5) OR (Score GE 2.8)
 269 ENDFILTERS
 270
 271 Your Own description here&#9;FER_CAPAA&#9;-1&#9;3&#9;93&#9;domain
 272 Your Own description here&#9;FER_CAPAN&#9;-1&#9;48&#9;144&#9;chain
 273 Your Own description here&#9;FER_CAPAN&#9;-1&#9;50&#9;140&#9;domain
 274 Your Own description here&#9;FER_CAPAN&#9;-1&#9;136&#9;136&#9;modified residue
 275 Your Own description here&#9;FER1_LYCES&#9;-1&#9;1&#9;47&#9;transit peptide
 276 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;1&#9;48&#9;signal peptide
 277 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;49&#9;144&#9;chain
 278
 279 STARTGROUP&#9;secondarystucture
 280 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;52&#9;59&#9;strand
 281 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;74&#9;80&#9;helix
 282 ENDGROUP&#9;secondarystructure
 283
 284 STARTGROUP&#9;kd
 285 Hydrophobicity score by kD      Q93XJ9_SOLTU    -1      48      48      kdHydrophobicity        1.8
 286 ENDGROUP&#9;kd
 287
 288 GFF
 289 FER_CAPAA&#9;GffGroup&#9;domain&#9;3&#9;93&#9;.&#9;.
 290 </pre>
 291 </body>
 292 </html>
 293