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
  30   <p>
  31
  32   <p>The Sequence features File provides a simple way of getting
  33     your own sequence features into Jalview. It also allows feature
  34     display styles and filters to be saved and imported to another
  35     alignment. Users familiar with the earliest versions of Jalview will
  36     know that features files were originally termed 'groups' files, and
  37     that the format was was designed as a space efficient format to
  38     allow sequence features to be rendered in the Jalview applet.</p>
  39
  40   <p>
  41     Features files are imported into Jalview in the following ways:<br>
  42
  43   <ul>
  44     <li>from the command line <pre>
  45 <strong> --features &lt;<em>Features filename</em>&gt;</strong>
  46 </pre>
  47     </li>
  48
  49     <li>Dragging a features file onto an alignment window</li>
  50
  51     <li>Via the &quot;Load Features / Annotations&quot; entry in
  52       the <strong>File</strong> menu of an alignment window.
  53     </li>
  54   </ul>
  55
  56   <p>
  57     <strong>Sequence Features File Format</strong>
  58   </p>
  59   <p>
  60     A features file is a simple ASCII text file, where each line
  61     contains tab separated text fields. <strong>No comments are
  62       allowed</strong>. Its structure consists of three blocks:
  63   </p>
  64   <ul>
  65     <li><a href="#colourdefs">Feature Colour Specifications</a>
  66       define how features of a particular type are rendered.</li>
  67     <li><a href="#filterdefs">Feature Filters</a> provide a way of
  68       excluding features of a particular type from display and analysis.
  69       (new in Jalview 2.11)</li>
  70     <li><a href="#featuredef">Sequence Feature definitions</a> -
  71       tab separated fields that describe groups of positional and
  72       non-positional features. Data can also be provided as <a href="#gff">GFF</a></li>
  73   </ul>
  74
  75   <p>
  76     <strong><a name="colourdefs">Feature Colours</a></strong>
  77   </p>
  78   <p>The first set of lines contain feature type definitions and their colours:
  79   <pre>
  80 <strong><em>&lt;Feature Type&gt;</em>&#9;<em>&lt;Feature Style&gt;</em>
  81 <!-- &#9;<em>Feature links</em>  --></strong>
  82 </pre>
  83
  84   Each feature type definition assigns a style to features of the given type. &lt;Feature Style&gt; can be either a simple colour, or a more complex <a href="featureschemes.html">Graduated Colour Scheme</a> that shades features according to their description, score, or other attributes.
  85 <p>
  86   <em>Assigning a colour for a &lt;Feature Type&gt;</em><br/>A single colour specified as either a red,green,blue 24 bit
  87       triplet in hexadecimal (eg. 00ff00) or as comma separated numbers
  88       (ranging from 0 to 255))<br>
  89       (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>.)</p>
  90       <p><em>Specifying a <a href="featureschemes.html">Graduated Colourscheme</a></em><br/>
  91       Data dependent feature colourschemes are defined by a series of "|" separated fields: <pre>
  92 [label <em>or</em> score<em> or</em> attribute|&lt;attName&gt;|]&lt;mincolor&gt;|&lt;maxcolor&gt;|[absolute|]&lt;minvalue&gt;|&lt;maxvalue&gt;[|&lt;novalue&gt;][|&lt;thresholdtype&gt;|[&lt;threshold value&gt;]]
  93 </pre><br/>The fields are interpreted follows:
  94
  95   <ul>
  96     <li><em>label</em><br> Indicates that the feature
  97       description should be used to create a colour for features of this
  98       type.<br> <em>Note: if no threshold value is needed then
  99         only 'label' is required.<br> This keyword was added in
 100         Jalview 2.6
 101     </em></li>
 102
 103     <li><em>score</em><br> Indicates that the feature score
 104       should be used to create a graduated colour for features of this
 105       type, in conjunction with mincolor, maxcolor.<br>
 106     <em>This keyword was added in Jalview 2.11. It may be omitted
 107         (score is the default) if mincolor and maxcolor are specified. </em></li>
 108
 109     <li><em>attribute|&lt;attName&gt;</em><br> Indicates that
 110       the value of feature attribute 'attName' should be used to create
 111       a colour for features of this type. <br>For example, <em>attribute|clinical_significance</em>
 112       to colour by "clinical_significance". <br>To colour by range
 113       of a numeric attribute, include <em>mincolor</em> and <em>maxcolor</em>,
 114       or omit to colour by text (category). <br>(Note: the value of
 115       the attribute used for colouring will also be shown in the tooltip
 116       as you mouse over features.) <br>A sub-attribute should be
 117       written as, for example, CSQ:IMPACT. <br>
 118     <em>This keyword was added in Jalview 2.11</em></li>
 119
 120     <li><em>mincolor</em> and <em>maxcolor</em><br> Colour
 121       triplets specified as hexadecimal or comma separated values (may
 122       be left blank for a <em>label</em> style colourscheme, but
 123       remember to specify the remaining fields)</li>
 124
 125     <li><em>absolute</em><br> An optional switch indicating
 126       that the <em>minvalue</em> and <em>maxvalue</em> parameters should
 127       be left as is, rather than rescaled according to the range of
 128       scores for this feature type.<br /> <em>This also enables
 129         the 'Threshold is Min/Max' option for this type's feature
 130         shading style dialog.</em></li>
 131
 132     <li><em>minvalue</em> and <em>maxvalue</em><br> Minimum
 133       and maximum values defining the range of scores for which the
 134       colour range will be defined over.<br>If minvalue is greater
 135       than maxvalue then the linear mapping will have negative gradient.</li>
 136
 137     <li><em>novalue</em> <br> Specifies the colour to use if
 138       colouring by attribute, when the attribute is absent. Valid
 139       options are <em>novaluemin, novaluemax, novaluenone</em>, to use
 140       mincolor, maxcolor, or no colour. <br>If not specified this
 141       will default to novaluemin.</li>
 142
 143     <li><em>thresholdtype</em><br> Either &quot;none&quot;,
 144       &quot;below&quot;, or &quot;above&quot;. <em>below</em> and <em>above</em>
 145       require an additional <em>threshold value</em> which is used to
 146       control the display of features with a score either below or above
 147       the value.</li>
 148   </ul>
 149
 150   <p>
 151     <strong><a name="filterdefs">Feature Filters</a></strong>
 152   </p>
 153   <p>This section is optional, and allows one or more filters to be defined for each feature type.
 154      <br>Only features that satisfy the filter conditions will be displayed.
 155      <br>Begin with a line which is just STARTFILTERS, and end with a line which is just ENDFILTERS.
 156      <br>Each line has the format:
 157      <pre>featureType <em>&lt;tab&gt;</em> (filtercondition1) [and|or] (filtercondition2) [and|or]...<br></pre>
 158      The parentheses are not needed if there is only one condition.
 159      Combine multiple conditions with either <em>and</em> or <em>or</em> (but not a mixture).
 160      <br>Each condition is written as:
 161      <pre>Label <em>or</em> Score <em>or</em> AttributeName condition [value]</pre>
 162      where either the label (description), (numeric) score, or (text or numeric) attribute is tested against the condition.
 163      <br><em>condition</em> is not case sensitive, and should be one of
 164      <ul>
 165      <li><em>Contains</em> - description (or attribute) should contain the given value (not case sensitive); example <em>clinical_significance contains Pathogenic</em></li>
 166      <li><em>NotContains</em> - description (or attribute) should not contain the given value</li>
 167      <li><em>Matches</em> - description (or attribute)  should match the given value (not case sensitive)</li>
 168      <li><em>NotMatches</em> - description (or attribute) should not match the given value (not case sensitive)</li>
 169      <li><em>Present</em> - attribute is present on the feature (no value required); example <em>CSQ:SIFT present</em></li>
 170      <li><em>NotPresent</em> - attribute is not present on the feature (no value required)</li>
 171      <li><em>EQ</em> - feature score, or specified attribute, is equal to the (numeric) value</li>
 172      <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>
 173      </ul>
 174      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:
 175      <em>'mutagenesis site' contains 'decreased affinity'</em>
 176      <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.
 177      <br><em>Feature filters were added in Jalview 2.11</em>
 178   </p>
 179
 180   <p>
 181     <strong><a name="featuredef">Feature Definitions</a></strong>
 182   </p>
 183
 184   <p>The remaining lines in the file are sequence feature data.
 185     Features are either non-positional - attached to a whole sequence
 186     (as specified by its ID), or positional, so attached to a specific
 187     range on a sequence. In addition to a type, features can also
 188     include descriptive text and a score, and depending on the format
 189     used, many additional attributes.</p>
 190
 191   <em><a name="gff">Importing Generalised Feature Format (GFF) feature data</a></em>
 192   <p>
 193     Jalview has its own tabular format (described below) for describing
 194     sequence features, which allows HTML descriptions (including URLs)
 195     to be defined for each feature. However, sequence feature
 196     definitions can also be provided in <a
 197       href="http://gmod.org/wiki/GFF2">GFF2</a>
 198     (http://gmod.org/wiki/GFF2) or <a
 199       href="https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md">GFF3</a>
 200     (http://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md)
 201     format. To do this, a line containing only 'GFF' should precede any
 202     GFF data (<em>this mixed format capability was added in Jalview
 203       2.6</em>).
 204   </p>
 205   <p>Feature attributes can be included as <code>name=value</code> pairs in GFF3 column 9, including <em>(since Jalview 2.11.1.0)</em> 'nested' sub-attributes, for example:
 206   <br><code>alleles=G,A,C;AF=6;CSQ=SIFT=deleterious,tolerated,PolyPhen=possibly_damaging(0.907)</code>
 207   <br>where <code>SIFT</code> and <code>PolyPhen</code> are sub-attributes of <code>CSQ</code>. This data is preserved if features are exported in GFF format (but not, currently,
 208   in Jalview format).
 209   </p>
 210   <p>
 211     <em>Jalview's sequence feature format</em>
 212   </p>
 213   <p>Each feature is specified as a tab-separated series of columns
 214     as defined below:
 215   <pre>
 216 <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>
 217 </pre>
 218
 219   This format allows two alternate ways of referring to a sequence,
 220   either by its text ID, or its index (base 0) in an associated
 221   alignment. Normally, sequence features are associated with sequences
 222   rather than alignments, and the sequenceIndex field is given as
 223   &quot;-1&quot;. In order to specify a sequence by its index in a
 224   particular alignment, the sequenceId should be given as
 225   &quot;ID_NOT_SPECIFIED&quot;, otherwise the sequenceId field will be
 226   used in preference to the sequenceIndex field.
 227   </p>
 228
 229
 230   <p>
 231     The description may contain simple HTML document body tags if
 232     enclosed by &quot;&lt;html&gt;&lt;/html&gt;&quot; and these will be
 233     rendered as formatted tooltips in the Jalview Application (the
 234     Jalview applet is not capable of rendering HTML tooltips, so all
 235     formatting tags will be removed).<br> <em>Attaching Links
 236       to Sequence Features</em><br> Any anchor tags in an html formatted
 237     description line will be translated into URL links. A link symbol
 238     will be displayed adjacent to any feature which includes links, and
 239     these are made available from the <a
 240       href="../menus/popupMenu.html#sqid.popup">links submenu</a>
 241     of the popup menu which is obtained by right-clicking when a link
 242     symbol is displayed in the tooltip.<br> <em>Non-positional
 243       features</em><br> Specify the <em>start</em> and <em>end</em> for
 244     a feature to be <strong>0</strong> in order to attach it to the
 245     whole sequence. Non-positional features are shown in a tooltip when
 246     the mouse hovers over the sequence ID panel, and any embedded links
 247     can be accessed from the popup menu.<br /> <em>Scores</em><br>
 248     Scores can be associated with sequence features, and used to sort
 249     sequences or shade the alignment (this was added in Jalview 2.5).
 250     The score field is optional, and malformed scores will be ignored.
 251   </p>
 252
 253   <p>Feature annotations can be collected into named groups by
 254     prefixing definitions with lines of the form:
 255   <pre>
 256 <strong>startgroup      groupname</strong>
 257 </pre>
 258
 259   .. and subsequently post-fixing the group with:
 260
 261   <pre>
 262 <strong>endgroup        groupname</strong>
 263 </pre>
 264
 265   Feature grouping was introduced in version 2.08, and used to control
 266   whether a set of features are either hidden or shown together in the
 267   <a href="seqfeatures.html">sequence Feature settings dialog box</a>.
 268   </p>
 269
 270
 271   <p>A complete example is shown below :
 272   <pre>
 273 domain&#9;red
 274 metal ion-binding site&#9;00ff00
 275 transit peptide&#9;0,105,215
 276 chain&#9;225,105,0
 277 modified residue&#9;105,225,35
 278 signal peptide&#9;0,155,165
 279 helix&#9;ff0000
 280 strand&#9;00ff00
 281 coil&#9;cccccc
 282 kdHydrophobicity&#9;ccffcc|333300|-3.9|4.5|above|-2.0
 283
 284 STARTFILTERS
 285 metal ion-binding site&#9;Label Contains sulfur
 286 kdHydrophobicity&#9;(Score LT 1.5) OR (Score GE 2.8)
 287 ENDFILTERS
 288
 289 Your Own description here&#9;FER_CAPAA&#9;-1&#9;3&#9;93&#9;domain
 290 Your Own description here&#9;FER_CAPAN&#9;-1&#9;48&#9;144&#9;chain
 291 Your Own description here&#9;FER_CAPAN&#9;-1&#9;50&#9;140&#9;domain
 292 Your Own description here&#9;FER_CAPAN&#9;-1&#9;136&#9;136&#9;modified residue
 293 Your Own description here&#9;FER1_LYCES&#9;-1&#9;1&#9;47&#9;transit peptide
 294 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;1&#9;48&#9;signal peptide
 295 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;49&#9;144&#9;chain
 296
 297 STARTGROUP&#9;secondarystucture
 298 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;52&#9;59&#9;strand
 299 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;74&#9;80&#9;helix
 300 ENDGROUP&#9;secondarystructure
 301
 302 STARTGROUP&#9;kd
 303 Hydrophobicity score by kD      Q93XJ9_SOLTU    -1      48      48      kdHydrophobicity        1.8
 304 ENDGROUP&#9;kd
 305
 306 GFF
 307 FER_CAPAA&#9;GffGroup&#9;domain&#9;3&#9;93&#9;.&#9;.
 308 </pre>
 309 </body>
 310 </html>
 311