<body>
<p>
<strong>Sequence Features File</strong>
+
<p>
- <p>The Sequence features file (which used to be known as the
- "Groups file" prior to version 2.08) is a simple way of getting your
- own sequence annotations into Jalview. It was introduced to allow
- sequence features to be rendered in the Jalview applet, and so is
- intentionally lightweight and minimal because the applet is often
- used in situations where data file size must be kept to a minimum,
- and no XML parser is available.</p>
+
+ <p>The Sequence features File provides a simple way of getting
+ your own sequence features into Jalview. It also allows feature
+ display styles and filters to be saved and imported to another
+ alignment. Users familiar with the earliest versions of Jalview will
+ know that features files were originally termed 'groups' files, and
+ that the format was was designed as a space efficient format to
+ allow sequence features to be rendered in the Jalview applet.</p>
<p>
Features files are imported into Jalview in the following ways:<br>
+
<ul>
<li>from the command line <pre>
<strong> -features <<em>Features filename</em>></strong>
</li>
</ul>
- </p>
-
<p>
<strong>Sequence Features File Format</strong>
</p>
<p>
A features file is a simple ASCII text file, where each line
contains tab separated text fields. <strong>No comments are
- allowed</strong>.
+ allowed</strong>. Its structure consists of three blocks:
</p>
+ <ul>
+ <li><a href="#colourdefs">Feature Colour Specifications</a>
+ define how features of a particular type are rendered.</li>
+ <li><a href="#filterdefs">Feature Filters</a> provide a way of
+ excluding features of a particular type from display and analysis.
+ (new in Jalview 2.11)</li>
+ <li><a href="#featuredef">Sequence Feature definitions</a> -
+ tab separated fields that describe groups of positional and
+ non-positional features. Data can also be provided as <a href="#gff">GFF</a></li>
+ </ul>
+
<p>
- <strong>Feature Colours</strong>
+ <strong><a name="colourdefs">Feature Colours</a></strong>
</p>
<p>The first set of lines contain feature type definitions and their colours:
<pre>
-<strong><em>Feature label</em>	<em>Feature Colour</em>
+<strong><em><Feature Type></em>	<em><Feature Style></em>
<!-- 	<em>Feature links</em> --></strong>
</pre>
- A feature type has a text label, and a colour specification. This can
- be either:
-
- <ul>
- <li>A single colour specified as either a red,green,blue 24 bit
+ Each feature type definition assigns a style to features of the given type. <Feature Style> 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.
+<p>
+ <em>Assigning a colour for a <Feature Type></em><br/>A single colour specified as either a red,green,blue 24 bit
triplet in hexadecimal (eg. 00ff00) or as comma separated numbers
(ranging from 0 to 255))<br>
- (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>
-
- <li>A <a href="featureschemes.html">graduated colourscheme</a>
- specified as a "|" separated list of fields: <pre>
-[label <em>or</em> score<em> or</em> attribute|attName|]<mincolor>|<maxcolor>|[absolute|]<minvalue>|<maxvalue>[|<novalue>][|<thresholdtype>|[<threshold value>]]
-</pre> The fields are as follows:
-
- <ul>
- <li><em>label</em><br> Indicates that the feature
- description should be used to create a colour for features of
- this type.<br> <em>Note: if no threshold value is
- needed then only 'label' is required.<br> This
- keyword was added in Jalview 2.6
- </em></li>
-
- <li><em>score</em><br> Indicates that the feature
- score should be used to create a graduated colour for features of
- this type, in conjunction with mincolor, maxcolor.<br><em>This keyword was added in Jalview 2.11.
- It may be omitted (score is the default) if mincolor and maxcolor are specified.
- </em></li>
-
- <li><em>attribute|attName</em><br> Indicates that the value of feature
- attribute 'attName' should be used to create a colour for features of
- this type.
- <br>For example, <em>attribute|clinical_significance</em> to colour by clinical_significance.
- <br>To colour by range of a numeric attribute, include <em>mincolor</em> and <em>maxcolor</em>, or omit to colour by text (category).
- <br>(Note: the value of the attribute used for colouring will also be shown in the tooltip as you mouse over features.)
- <br>A sub-attribute should be written as, for example, CSQ:IMPACT.
- <br><em>This keyword was added in Jalview 2.11</em></li>
-
- <li><em>mincolor</em> and <em>maxcolor</em><br> Colour
- triplets specified as hexadecimal or comma separated values
- (may be left blank for a <em>label</em> style colourscheme,
- but remember to specify the remaining fields)</li>
-
- <li><em>absolute</em><br> An optional switch
- indicating that the <em>minvalue</em> and <em>maxvalue</em>
- parameters should be left as is, rather than rescaled
- according to the range of scores for this feature type.</li>
-
- <li><em>minvalue</em> and <em>maxvalue</em><br>
- Minimum and maximum values defining the range of scores for
- which the colour range will be defined over.<br>If minvalue is
- greater than maxvalue then the linear mapping will have
- negative gradient.</li>
-
- <li><em>novalue</em> <br>
- Specifies the colour to use if colouring by attribute, when the attribute is absent.
- Valid options are <em>novaluemin, novaluemax, novaluenone</em>, to use mincolor, maxcolor, or no colour.
- <br>If not specified this will default to novaluemin.</li>
-
- <li><em>thresholdtype</em><br> Either
- "none", "below", or "above". <em>below</em>
- and <em>above</em> require an additional <em>threshold
- value</em> which is used to control the display of features with
- a score either below or above the value.</li>
- </ul>
- </li>
+ (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>
+ <p><em>Specifying a <a href="featureschemes.html">Graduated Colourscheme</a></em><br/>
+ Data dependent feature colourschemes are defined by a series of "|" separated fields: <pre>
+[label <em>or</em> score<em> or</em> attribute|<attName>|]<mincolor>|<maxcolor>|[absolute|]<minvalue>|<maxvalue>[|<novalue>][|<thresholdtype>|[<threshold value>]]
+</pre><br/>The fields are interpreted follows:
+
+ <ul>
+ <li><em>label</em><br> Indicates that the feature
+ description should be used to create a colour for features of this
+ type.<br> <em>Note: if no threshold value is needed then
+ only 'label' is required.<br> This keyword was added in
+ Jalview 2.6
+ </em></li>
+
+ <li><em>score</em><br> Indicates that the feature score
+ should be used to create a graduated colour for features of this
+ type, in conjunction with mincolor, maxcolor.<br>
+ <em>This keyword was added in Jalview 2.11. It may be omitted
+ (score is the default) if mincolor and maxcolor are specified. </em></li>
+
+ <li><em>attribute|<attName></em><br> Indicates that
+ the value of feature attribute 'attName' should be used to create
+ a colour for features of this type. <br>For example, <em>attribute|clinical_significance</em>
+ to colour by "clinical_significance". <br>To colour by range
+ of a numeric attribute, include <em>mincolor</em> and <em>maxcolor</em>,
+ or omit to colour by text (category). <br>(Note: the value of
+ the attribute used for colouring will also be shown in the tooltip
+ as you mouse over features.) <br>A sub-attribute should be
+ written as, for example, CSQ:IMPACT. <br>
+ <em>This keyword was added in Jalview 2.11</em></li>
+
+ <li><em>mincolor</em> and <em>maxcolor</em><br> Colour
+ triplets specified as hexadecimal or comma separated values (may
+ be left blank for a <em>label</em> style colourscheme, but
+ remember to specify the remaining fields)</li>
+
+ <li><em>absolute</em><br> An optional switch indicating
+ that the <em>minvalue</em> and <em>maxvalue</em> parameters should
+ be left as is, rather than rescaled according to the range of
+ scores for this feature type.<br /> <em>This also enables
+ the 'Threshold is Min/Max' option for this type's feature
+ shading style dialog.</em></li>
+
+ <li><em>minvalue</em> and <em>maxvalue</em><br> Minimum
+ and maximum values defining the range of scores for which the
+ colour range will be defined over.<br>If minvalue is greater
+ than maxvalue then the linear mapping will have negative gradient.</li>
+
+ <li><em>novalue</em> <br> Specifies the colour to use if
+ colouring by attribute, when the attribute is absent. Valid
+ options are <em>novaluemin, novaluemax, novaluenone</em>, to use
+ mincolor, maxcolor, or no colour. <br>If not specified this
+ will default to novaluemin.</li>
+
+ <li><em>thresholdtype</em><br> Either "none",
+ "below", or "above". <em>below</em> and <em>above</em>
+ require an additional <em>threshold value</em> which is used to
+ control the display of features with a score either below or above
+ the value.</li>
</ul>
- </p>
<p>
- <strong>Feature Filters</strong>
+ <strong><a name="filterdefs">Feature Filters</a></strong>
</p>
<p>This section is optional, and allows one or more filters to be defined for each feature type.
<br>Only features that satisfy the filter conditions will be displayed.
</p>
<p>
- <strong>Feature Instances</strong>
+ <strong><a name="featuredef">Feature Definitions</a></strong>
</p>
- <p>The remaining lines in the file are the sequence annotation
- definitions, where the now defined features are attached to regions
- on particular sequences. Each feature can optionally include some
- descriptive text which is displayed in a tooltip when the mouse is
- near the feature on that sequence (and may also be used to generate
- a colour for the feature).</p>
+ <p>The remaining lines in the file are sequence feature data.
+ Features are either non-positional - attached to a whole sequence
+ (as specified by its ID), or positional, so attached to a specific
+ range on a sequence. In addition to a type, features can also
+ include descriptive text and a score, and depending on the format
+ used, many additional attributes.</p>
+ <em><a name="gff">Importing Generalised Feature Format (GFF) feature data</a></em>
<p>
- If your sequence annotation is already available in <a href="http://gmod.org/wiki/GFF2">GFF2</a> (http://gmod.org/wiki/GFF2) or
- <a href="https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md">GFF3</a>
- (http://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md) format,
- then you can leave it as is, after first adding a line containing 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 annotation format, which
- additionally allows HTML and URLs to be directly attached to each
- piece of annotation.
+ Jalview has its own tabular format (described below) for describing
+ sequence features, which allows HTML descriptions (including URLs)
+ to be defined for each feature. However, sequence feature
+ definitions can also be provided in <a
+ href="http://gmod.org/wiki/GFF2">GFF2</a>
+ (http://gmod.org/wiki/GFF2) or <a
+ href="https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md">GFF3</a>
+ (http://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md)
+ format. To do this, a line containing only 'GFF' should precede any
+ GFF data (<em>this mixed format capability was added in Jalview
+ 2.6</em>).
</p>
<p>
- <strong>Jalview's sequence feature annotation format</strong>
+ <em>Jalview's sequence feature format</em>
</p>
<p>Each feature is specified as a tab-separated series of columns
as defined below:
git://source.jalview.org / jalview.git / commitdiff