X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=help%2Fhtml%2Ffeatures%2FannotationsFormat.html;h=fcdb90802df39a161304463cf9209768b1d99ae4;hb=78d33c82e8371198bee7751731095d65aa1fc07c;hp=4c8ad39f1bc5dc385c804dd537577ecc41f9da0c;hpb=de255c8c87707a2cd2a2a15f5ad04ed10fe5846d;p=jalview.git diff --git a/help/html/features/annotationsFormat.html b/help/html/features/annotationsFormat.html index 4c8ad39..fcdb908 100755 --- a/help/html/features/annotationsFormat.html +++ b/help/html/features/annotationsFormat.html @@ -24,193 +24,332 @@
-The Alignment Annotations File
-Alignment annotations can be imported onto an alignment since -version 2.08 of Jalview, via an annotations file. It is a simple ASCII -text file consisting of tab delimited records similar to the Sequence Features File, and introduced -primarily for use with the Jalview applet.
++ The Alignment Annotations File +
++ Alignment annotations can be imported onto an alignment since + version 2.08 of Jalview, via an annotations file. It is a simple + ASCII text file consisting of tab delimited records similar to the Sequence Features File, and + introduced primarily for use with the Jalview applet. +
-Importing annotation files
-Alignment annotations files are imported into Jalview in the
-following ways:
-
++ Importing annotation files
Alignment + annotations files are imported into Jalview in the following ways:
+
-annotations <Annotations filename>
- Exporting annotation files
An annotation file
- can be created for any alignment view from the "Export
- Annotations ..." entry in the File menu of an
- alignment window.
-
THE ANNOTATION FILE FORMAT
-
An annotation file consists of lines containing an instruction followed by
-tab delimited fields. Any lines starting with "#" are considered comments, and
-ignored. The sections below describe the structure of an annotation file.
-
- At the end of this document, you can also find notes on compatibility of annotation files across - different versions of Jalview. An example - annotation file is also provided along with instructions on how to - import it to Jalview. -
-Header line
The first non-commented out line of a valid Annotations file
-must begin with :JALVIEW_ANNOTATION
LINE_GRAPH, BAR_GRAPH and NO_GRAPH
-Labels, secondary structure, histograms and line graphs are added with a line like GRAPH_TYPE Label Description (optional) Values
- Here, the GRAPH_TYPE field in the first column defines the - appearance of the annotation row when rendered by Jalview. The next - field is the row label for the annotation. This may be - followed by a description for the row, which is shown in a - tooltip when the user mouses over the annotation row's label. Since - Jalview 2.7, the description field may also contain HTML tags (in the same - way as a sequence feature's label), - providing the text is enclosed in an <html/> tag. - -
- The final Values field contains a series of "|" - separated value fields. Each value field is itself a comma separated - list of fields of a particular type defined by the annotation row's GRAPH_TYPE. - The allowed values of GRAPH_TYPE and corresponding - interpretation of each Value are shown below: - -
Color strings can be embedded in a value field by enclosing an RGB triplet in square brackets to colour that position in an annotation row. -
-COMBINE, COLOUR and GRAPHLINE for line graphs
-LINE_GRAPH type annotations can be given a colour
-(specified as 24 bit RGB triplet in hexadecimal or comma separated
-values), combined onto the same vertical axis, and have ordinate lines
-(horizontal lines at a particular vertical axis value) using the
-following commands (respectively):
-
COLOUR graph_name colour +
+ Exporting annotation files
An annotation
+ file can be created for any alignment view from the "Export
+ Annotations ..." entry in the File menu of an
+ alignment window.
+
+ THE ANNOTATION FILE FORMAT
An annotation
+ file consists of lines containing an instruction followed by tab
+ delimited fields. Any lines starting with "#" are
+ considered comments, and ignored. The sections below describe the
+ structure of an annotation file.
+
+ At the end of this document, you can also find notes on compatibility of annotation files + across different versions of Jalview. An example + annotation file is also provided along with instructions on how to + import it to Jalview. +
+
+ Header line
The
+ first non-commented out line of a valid Annotations file must begin
+ with :JALVIEW_ANNOTATION
+
+ LINE_GRAPH,
+ BAR_GRAPH and NO_GRAPH
Labels, secondary structure,
+ histograms and line graphs are added with a line like
+ GRAPH_TYPE Label Description (optional) Values
+
+
+ Here, the GRAPH_TYPE field in the first column defines the + appearance of the annotation row when rendered by Jalview. The next + field is the row label for the annotation. This may be + followed by a description for the row, which is shown in a + tooltip when the user mouses over the annotation row's label. Since + Jalview 2.7, the description field may also contain HTML tags (in + the same way as a sequence + feature's label), providing the text is enclosed in an + <html/> tag. +
+ The final Values field contains a series of "|" + separated value fields. Each value field is itself a comma separated + list of fields of a particular type defined by the annotation row's + GRAPH_TYPE. The allowed values of GRAPH_TYPE and + corresponding interpretation of each Value are shown below: + + + +
Color strings can be embedded in a value field by enclosing an + RGB triplet in square brackets to colour that position in an + annotation row.
+
+ COMBINE, COLOUR and GRAPHLINE
+ for line graphs
LINE_GRAPH type annotations can be
+ given a colour (specified as 24 bit RGB triplet in hexadecimal or
+ comma separated values), combined onto the same vertical axis, and
+ have ordinate lines (horizontal lines at a particular vertical axis
+ value) using the following commands (respectively):
+
COLOUR graph_name colour COMBINE graph_1_name graph_2_name GRAPHLINE graph_name value label colour -- -
ROWPROPERTIES
-The visual display properties for a set of annotation rows can be modified using the following tab-delimited line:
ROWPROPERTIES Row label centrelabs=true( or false) showalllabs=true(default is false) scaletofit=true (default is false)-
This sets the visual display properties according to the given values for all the annotation rows with labels matching Row label. The properties mostly affect the display of multi-character column labels, and are as follows: -
SEQUENCE_GROUP
-Groups of sequences and column ranges can be defined using a tab delimited statement like:
SEQUENCE_GROUP Group_Name Group_Start Group_End Sequences-
The sequences can be defined by alignment index and a range of sequences can - be defined in a comma delimited field such as
-2-5,8-15,20,22
-Enter * to select all groups.
-Note: If the alignment indices are not known, enter -1, followed by a tab and then a tab delimited list -of sequence IDs.
-If a SEQUENCE_REF has been defined, then group_start and group_end will be - relative to the sequence residue numbering, otherwise the group_start and group_end - will be alignment column indices.
-PROPERTIES
This statement allows various visualisation properties to be assigned to a named group. This takes a series of tab-delimited key=value pairs:
PROPERTIES Group_name tab_delimited_key_value_pairs + ++ +
+ ROWPROPERTIES
The
+ visual display properties for a set of annotation rows can be
+ modified using the following tab-delimited line:
+
ROWPROPERTIES Row label centrelabs=true( or false) showalllabs=true(default is false) scaletofit=true (default is false) ++
+ This sets the visual display properties according to the given + values for all the annotation rows with labels matching Row + label. The properties mostly affect the display of multi-character + column labels, and are as follows: +
+ SEQUENCE_GROUP
+ Groups of sequences and column ranges can be defined using a tab
+ delimited statement like:
+
SEQUENCE_GROUP Group_Name Group_Start Group_End Sequences ++
The sequences can be defined by alignment index and a range of + sequences can be defined in a comma delimited field such as
+2-5,8-15,20,22
+Enter * to select all groups.
++ Note: If the alignment indices are not known, enter + -1, followed by a tab and then a tab delimited list of sequence IDs. +
++ If a SEQUENCE_REF has + been defined, then group_start and group_end will + be relative to the sequence residue numbering, otherwise the group_start + and group_end will be alignment column indices. +
+
+ PROPERTIES
This
+ statement allows various visualisation properties to be assigned to
+ a named group. This takes a series of tab-delimited key=value
+ pairs:
+
PROPERTIES Group_name tab_delimited_key_value_pairs-
The currently supported set of sequence group key-value pairs that can be provided here are :
-Key | Value |
description | Text - may include simple HTML tags |
colour | A string resolving to a valid Jalview colourscheme (e.g. Helix Propensity) |
pidThreshold | A number from 0-100 specifying the Percent Identity Threshold for colouring columns in the group or alignment |
consThreshold | A number from 0-100 specifying the degree of bleaching applied for conservation colouring |
outlineColour | Line colour used for outlining the group (default is red) |
displayBoxes | Boolean (default true) controlling display of shaded box for each alignment position |
displayText | Boolean (default true) controlling display of text for each alignment position |
colourText | Boolean (default false) specifying whether text should be shaded by applied colourscheme |
textCol1 | Colour for text when shown on a light background |
textCol2 | Colour for text when shown on a dark background |
textColThreshold | Number from 0-100 specifying switching threshold between light and dark background |
idColour | Colour for highlighting the Sequence ID labels for this group If idColour is given but colour is not, then idColor will also be used for the group background colour. |
showunconserved | Boolean (default false) indicating whether residues should only be shown that are different from current reference or consensus sequence |
hide | Boolean (default false) indicating whether the rows in this group should be marked as hidden. Note: if the group is sequence associated (specified by SEQUENCE_REF), then all members will be hidden and marked as represented by the reference sequence. |
The currently supported set of sequence group key-value pairs + that can be provided here are :
+Key | +Value | +
description | +Text - may include simple HTML tags | +
colour | +A string resolving to a valid Jalview colourscheme + (e.g. Helix Propensity) | +
pidThreshold | +A number from 0-100 specifying the Percent Identity + Threshold for colouring columns in the group or alignment | +
consThreshold | +A number from 0-100 specifying the degree of bleaching + applied for conservation colouring | +
outlineColour | +Line colour used for outlining the group (default is + red) | +
displayBoxes | +Boolean (default true) controlling display of shaded + box for each alignment position | +
displayText | +Boolean (default true) controlling display of text for + each alignment position | +
colourText | +Boolean (default false) specifying whether text should + be shaded by applied colourscheme | +
textCol1 | +Colour for text when shown on a light background | +
textCol2 | +Colour for text when shown on a dark background | +
textColThreshold | +Number from 0-100 specifying switching threshold + between light and dark background | +
idColour | +Colour for highlighting the Sequence ID labels for this
+ group If idColour is given but colour + is not, then idColor will also be used for the group + background colour. + |
+
showunconserved | +Boolean (default false) indicating whether residues + should only be shown that are different from current reference + or consensus sequence | +
hide | +Boolean (default false) indicating whether the rows in
+ this group should be marked as hidden. Note: + if the group is sequence associated (specified by + SEQUENCE_REF), then all members will be hidden and marked as + represented by the reference sequence. + |
+
Specifying colours in PROPERTIES key-value pairs
-The colour property can take either a colour scheme name,
- or a single colour specification (either a colour name like 'red' or an RGB
- triplet like 'ff0066'). If a single colour is specified, then the group
- will be coloured with that colour.
SEQUENCE_REF and GROUP_REF
- By
- default, annotation is associated with the alignment as a whole.
- However, it is also possible to have an annotation row associated with
- a specific sequence, or a sequence group. Clicking the annotation
- label for sequence or group associated annotation will highlight the
- associated rows in the alignment, and double clicking will select
- those rows, allowing further analysis. While group associated
- annotation remains associated with a particular alignment, sequence
- associated annotation can move with a sequence - so copying a sequence
- to another alignment will also copy its associated annotation.
-
You can associate an annotation with a sequence by preceding its -definition with the line: -
SEQUENCE_REF seq_name [startIndex]-All Annotations defined after a SEQUENCE_REF command will then be -associated with that sequence, and the first field in the Value field -list will (optionally) be placed at the startIndex'th column. +
+ Specifying colours in PROPERTIES key-value pairs
+ The colour property can take either a colour scheme
+ name, or a single colour specification (either a colour name like
+ 'red' or an RGB triplet like 'ff0066'). If a single colour is
+ specified, then the group will be coloured with that colour.
+
+ SEQUENCE_REF and GROUP_REF
+ By default, annotation is associated with the alignment as a whole.
+ However, it is also possible to have an annotation row associated
+ with a specific sequence, or a sequence group. Clicking the
+ annotation label for sequence or group associated annotation will
+ highlight the associated rows in the alignment, and double clicking
+ will select those rows, allowing further analysis. While group
+ associated annotation remains associated with a particular
+ alignment, sequence associated annotation can move with a sequence -
+ so copying a sequence to another alignment will also copy its
+ associated annotation.
+
You can associate an annotation with a sequence by preceding + its definition with the line: +
SEQUENCE_REF seq_name [startIndex] ++ All Annotations defined after a SEQUENCE_REF command will then be + associated with that sequence, and the first field in the Value field + list will (optionally) be placed at the + startIndex'th column. + -
Sequence associations are turned off for subsequent annotation -definitions by: -
SEQUENCE_REF ALIGNMENT- -
Similarly, since Jalview 2.5, group associated annotation can be defined by preceding the row definitions with the line: -
GROUP_REF group_name-Group association is turned off for subsequent annotation rows by: -
GROUP_REF ALIGNMENT- -
Sequence associations are turned off for subsequent annotation + definitions by: +
SEQUENCE_REF ALIGNMENT+ +
Similarly, since Jalview 2.5, group associated annotation can + be defined by preceding the row definitions with the line: +
GROUP_REF group_name ++ Group association is turned off for subsequent annotation rows by: +
GROUP_REF ALIGNMENT ++ +
VIEW_SETREF,
VIEW_HIDECOL and HIDE_INSERTIONS
Since Jalview 2.9, the
@@ -224,8 +363,8 @@ Group association is turned off for subsequent annotation rows by:
properties.
- VIEW_SETREF
Marks the first sequence in the alignment,
- or alternately, the one specified by the most recent SEQUENCE_REF
+ VIEW_SETREF
Marks the first sequence in the
+ alignment, or alternately, the one specified by the most recent SEQUENCE_REF
statement, as the reference
sequence for the alignment.
COMPATIBILITY NOTES
- The interpretation of the COMBINE statement in Version 2.8.1 was refined
- so that only annotation line graphs with the given names ands the same
- SEQUENCE_REF and GROUP_REF scope are grouped.
+ COMPATIBILITY NOTES
+ The interpretation of the COMBINE statement in Version
+ 2.8.1 was refined so that only annotation line graphs with the
+ given names ands the same SEQUENCE_REF and GROUP_REF
+ scope are grouped.
+
EXAMPLES
-An example Annotation file is given below. Copy and paste the contents into a text file and load it onto the Jalview example protein alignment.
#Comment lines follow the hash symbol ++ EXAMPLES
+
An example + Annotation file is given below. Copy and paste the contents into a + text file and load it onto the Jalview example protein alignment. +#Comment lines follow the hash symbol JALVIEW_ANNOTATION SEQUENCE_REF FER1_MESCR 5 BAR_GRAPH Bar Graph 1 <html>an <em>html tooltip</em> for Bar graph 1.</html> ||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+ @@ -278,6 +423,6 @@ PROPERTIES Group_A description=This is the description colour=Helix Pro PROPERTIES Group_B outlineColour=red PROPERTIES Group_C colour=Clustal- +