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
 206   <p>
 207     <em>Jalview's sequence feature format</em>
 208   </p>
 209   <p>Each feature is specified as a tab-separated series of columns
 210     as defined below:
 211   <pre>
 212 <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>
 213 </pre>
 214
 215   This format allows two alternate ways of referring to a sequence,
 216   either by its text ID, or its index (base 0) in an associated
 217   alignment. Normally, sequence features are associated with sequences
 218   rather than alignments, and the sequenceIndex field is given as
 219   &quot;-1&quot;. In order to specify a sequence by its index in a
 220   particular alignment, the sequenceId should be given as
 221   &quot;ID_NOT_SPECIFIED&quot;, otherwise the sequenceId field will be
 222   used in preference to the sequenceIndex field.
 223   </p>
 224
 225
 226   <p>
 227     The description may contain simple HTML document body tags if
 228     enclosed by &quot;&lt;html&gt;&lt;/html&gt;&quot; and these will be
 229     rendered as formatted tooltips in the Jalview Application (the
 230     Jalview applet is not capable of rendering HTML tooltips, so all
 231     formatting tags will be removed).<br> <em>Attaching Links
 232       to Sequence Features</em><br> Any anchor tags in an html formatted
 233     description line will be translated into URL links. A link symbol
 234     will be displayed adjacent to any feature which includes links, and
 235     these are made available from the <a
 236       href="../menus/popupMenu.html#sqid.popup">links submenu</a>
 237     of the popup menu which is obtained by right-clicking when a link
 238     symbol is displayed in the tooltip.<br> <em>Non-positional
 239       features</em><br> Specify the <em>start</em> and <em>end</em> for
 240     a feature to be <strong>0</strong> in order to attach it to the
 241     whole sequence. Non-positional features are shown in a tooltip when
 242     the mouse hovers over the sequence ID panel, and any embedded links
 243     can be accessed from the popup menu.<br /> <em>Scores</em><br>
 244     Scores can be associated with sequence features, and used to sort
 245     sequences or shade the alignment (this was added in Jalview 2.5).
 246     The score field is optional, and malformed scores will be ignored.
 247   </p>
 248
 249   <p>Feature annotations can be collected into named groups by
 250     prefixing definitions with lines of the form:
 251   <pre>
 252 <strong>startgroup      groupname</strong>
 253 </pre>
 254
 255   .. and subsequently post-fixing the group with:
 256
 257   <pre>
 258 <strong>endgroup        groupname</strong>
 259 </pre>
 260
 261   Feature grouping was introduced in version 2.08, and used to control
 262   whether a set of features are either hidden or shown together in the
 263   <a href="seqfeatures.html">sequence Feature settings dialog box</a>.
 264   </p>
 265
 266
 267   <p>A complete example is shown below :
 268   <pre>
 269 domain&#9;red
 270 metal ion-binding site&#9;00ff00
 271 transit peptide&#9;0,105,215
 272 chain&#9;225,105,0
 273 modified residue&#9;105,225,35
 274 signal peptide&#9;0,155,165
 275 helix&#9;ff0000
 276 strand&#9;00ff00
 277 coil&#9;cccccc
 278 kdHydrophobicity&#9;ccffcc|333300|-3.9|4.5|above|-2.0
 279
 280 STARTFILTERS
 281 metal ion-binding site&#9;Label Contains sulfur
 282 kdHydrophobicity&#9;(Score LT 1.5) OR (Score GE 2.8)
 283 ENDFILTERS
 284
 285 Your Own description here&#9;FER_CAPAA&#9;-1&#9;3&#9;93&#9;domain
 286 Your Own description here&#9;FER_CAPAN&#9;-1&#9;48&#9;144&#9;chain
 287 Your Own description here&#9;FER_CAPAN&#9;-1&#9;50&#9;140&#9;domain
 288 Your Own description here&#9;FER_CAPAN&#9;-1&#9;136&#9;136&#9;modified residue
 289 Your Own description here&#9;FER1_LYCES&#9;-1&#9;1&#9;47&#9;transit peptide
 290 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;1&#9;48&#9;signal peptide
 291 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;49&#9;144&#9;chain
 292
 293 STARTGROUP&#9;secondarystucture
 294 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;52&#9;59&#9;strand
 295 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;74&#9;80&#9;helix
 296 ENDGROUP&#9;secondarystructure
 297
 298 STARTGROUP&#9;kd
 299 Hydrophobicity score by kD      Q93XJ9_SOLTU    -1      48      48      kdHydrophobicity        1.8
 300 ENDGROUP&#9;kd
 301
 302 GFF
 303 FER_CAPAA&#9;GffGroup&#9;domain&#9;3&#9;93&#9;.&#9;.
 304 </pre>
 305 </body>
 306 </html>
 307