From: Jim Procter Date: Wed, 3 Jul 2019 12:58:20 +0000 (+0100) Subject: Merge branch 'documentation/JAL-2843_featureFiltersFormat' into develop X-Git-Tag: Release_2_11_0~2^2~4 X-Git-Url: http://source.jalview.org/gitweb/?p=jalview.git;a=commitdiff_plain;h=fca7d6a803e4edc9aeee0ee39ca980d11ca13346;hp=-c Merge branch 'documentation/JAL-2843_featureFiltersFormat' into develop --- fca7d6a803e4edc9aeee0ee39ca980d11ca13346 diff --combined help/help/html/features/featuresFormat.html index 4d13dcd,0226175..0226175 --- a/help/help/html/features/featuresFormat.html +++ b/help/help/html/features/featuresFormat.html @@@ -26,17 -26,20 +26,20 @@@

Sequence Features File +

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.

+ +

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.

Features files are imported into Jalview in the following ways:
+

from the command line

   -features <Features filename>
@@@ -50,95 -53,102 +53,102 @@@

Sequence Features File Format

A features file is a simple ASCII text file, where each line contains tab separated text fields. No comments are - allowed. + allowed. Its structure consists of three blocks:

Feature Colour Specifications + define how features of a particular type are rendered.
Feature Filters provide a way of + excluding features of a particular type from display and analysis. + (new in Jalview 2.11)
Sequence Feature definitions - + tab separated fields that describe groups of positional and + non-positional features. Data can also be provided as GFF

- Feature Colours + Feature Colours

The first set of lines contain feature type definitions and their colours:

- Feature label	Feature Colour
+ <Feature Type>	<Feature Style>

- A feature type has a text label, and a colour specification. This can - be either: - -
-
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 Graduated Colour Scheme that shades features according to their description, score, or other attributes. +
+ Assigning a colour for a <Feature Type>
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))
- (For help with colour values, see https://www.w3schools.com/colors/colors_converter.asp.)
- -
A graduated colourscheme - specified as a "|" separated list of fields:
- [label or score or attribute|attName|]<mincolor>|<maxcolor>|[absolute|]<minvalue>|<maxvalue>[|<novalue>][|<thresholdtype>|[<threshold value>]] -
The fields are as follows: - -
-
label
Indicates that the feature - description should be used to create a colour for features of - this type.
Note: if no threshold value is - needed then only 'label' is required.
This - keyword was added in Jalview 2.6 -
- -
score
Indicates that the feature - score should be used to create a graduated colour for features of - this type, in conjunction with mincolor, maxcolor.
This keyword was added in Jalview 2.11. - It may be omitted (score is the default) if mincolor and maxcolor are specified. -
- -
attribute|attName
Indicates that the value of feature - attribute 'attName' should be used to create a colour for features of - this type. -
For example, attribute|clinical_significance to colour by clinical_significance. -
To colour by range of a numeric attribute, include mincolor and maxcolor, or omit to colour by text (category). -
(Note: the value of the attribute used for colouring will also be shown in the tooltip as you mouse over features.) -
A sub-attribute should be written as, for example, CSQ:IMPACT. -
This keyword was added in Jalview 2.11
- -
mincolor and maxcolor
Colour - triplets specified as hexadecimal or comma separated values - (may be left blank for a label style colourscheme, - but remember to specify the remaining fields)
- -
absolute
An optional switch - indicating that the minvalue and maxvalue - parameters should be left as is, rather than rescaled - according to the range of scores for this feature type.
- -
minvalue and maxvalue
- Minimum and maximum values defining the range of scores for - which the colour range will be defined over.
If minvalue is - greater than maxvalue then the linear mapping will have - negative gradient.
- -
novalue
- Specifies the colour to use if colouring by attribute, when the attribute is absent. - Valid options are novaluemin, novaluemax, novaluenone, to use mincolor, maxcolor, or no colour. -
If not specified this will default to novaluemin.
- -
thresholdtype
Either - "none", "below", or "above". below - and above require an additional threshold - value which is used to control the display of features with - a score either below or above the value.
-
-
+ (For help with colour values, see https://www.w3schools.com/colors/colors_converter.asp.)
+
Specifying a Graduated Colourscheme
+ Data dependent feature colourschemes are defined by a series of "|" separated fields:
+ [label or score or attribute|<attName>|]<mincolor>|<maxcolor>|[absolute|]<minvalue>|<maxvalue>[|<novalue>][|<thresholdtype>|[<threshold value>]] +

The fields are interpreted follows: + +
+
label
Indicates that the feature + description should be used to create a colour for features of this + type.
Note: if no threshold value is needed then + only 'label' is required.
This keyword was added in + Jalview 2.6 +
+ +
score
Indicates that the feature score + should be used to create a graduated colour for features of this + type, in conjunction with mincolor, maxcolor.
+ This keyword was added in Jalview 2.11. It may be omitted + (score is the default) if mincolor and maxcolor are specified.
+ +
attribute|<attName>
Indicates that + the value of feature attribute 'attName' should be used to create + a colour for features of this type.
For example, attribute|clinical_significance + to colour by "clinical_significance".
To colour by range + of a numeric attribute, include mincolor and maxcolor, + or omit to colour by text (category).
(Note: the value of + the attribute used for colouring will also be shown in the tooltip + as you mouse over features.)
A sub-attribute should be + written as, for example, CSQ:IMPACT.
+ This keyword was added in Jalview 2.11
+ +
mincolor and maxcolor
Colour + triplets specified as hexadecimal or comma separated values (may + be left blank for a label style colourscheme, but + remember to specify the remaining fields)
+ +
absolute
An optional switch indicating + that the minvalue and maxvalue parameters should + be left as is, rather than rescaled according to the range of + scores for this feature type.
This also enables + the 'Threshold is Min/Max' option for this type's feature + shading style dialog.
+ +
minvalue and maxvalue
Minimum + and maximum values defining the range of scores for which the + colour range will be defined over.
If minvalue is greater + than maxvalue then the linear mapping will have negative gradient.
+ +
novalue
Specifies the colour to use if + colouring by attribute, when the attribute is absent. Valid + options are novaluemin, novaluemax, novaluenone, to use + mincolor, maxcolor, or no colour.
If not specified this + will default to novaluemin.
+ +
thresholdtype
Either "none", + "below", or "above". below and above + require an additional threshold value which is used to + control the display of features with a score either below or above + the value.

-

- Feature Filters + Feature Filters

This section is optional, and allows one or more filters to be defined for each feature type.
Only features that satisfy the filter conditions will be displayed. @@@ -168,30 -178,33 +178,33 @@@

- Feature Instances + Feature Definitions
-
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).
+
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.
+ Importing Generalised Feature Format (GFF) feature data
- If your sequence annotation is already available in GFF2 (http://gmod.org/wiki/GFF2) or - GFF3 - (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 (this - mixed format capability was added in Jalview 2.6). 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 GFF2 + (http://gmod.org/wiki/GFF2) or GFF3 + (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 (this mixed format capability was added in Jalview + 2.6).

- Jalview's sequence feature annotation format + Jalview's sequence feature format

Each feature is specified as a tab-separated series of columns as defined below: