X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=help%2Fhtml%2Ffeatures%2FannotationsFormat.html;h=4c8ad39f1bc5dc385c804dd537577ecc41f9da0c;hb=a49ce69b89678b3e6ba3c1a61b62d61cc9ee7342;hp=ba9bc9953fdd9904d07d9741aacea6b6f9d6dc19;hpb=90255554ddb63f5474c11afcaba96d23ffd88a46;p=jalview.git diff --git a/help/html/features/annotationsFormat.html b/help/html/features/annotationsFormat.html index ba9bc99..4c8ad39 100755 --- a/help/html/features/annotationsFormat.html +++ b/help/html/features/annotationsFormat.html @@ -1,82 +1,283 @@ - - -
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.
-Alignment annotations files are imported into Jalview in the
-following ways:
-
- -annotations <Annotations filename>
Annotations File Format
-The File consists of lines containing an instruction followed by
- tab delimited fields, and any lines starting with "#" are
- ignored. The first non-commented out line of a valid Annotations file must begin with :JALVIEW_ANNOTATION
A row of annotation is added with a line like
-GRAPH_TYPE Label Values
-
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
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
-
An example Annotation file is given below: -
#Comment lines follow the hash symbol -JALVIEW_ANNOTATION -SEQUENCE_REF FER1_MESCR 5 -BAR_GRAPH Bar Graph 1 ||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+ -LINE_GRAPH Green Values 1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2 -LINE_GRAPH Red Values 2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2 -BAR_GRAPH Bar Graph 2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4 -NO_GRAPH Icons ||||E,Sheet1|E|E||||H,Sheet 2|H|H|H|||||| -NO_GRAPH Purple Letters m|y|p|r|o|t|e|i|n -COLOUR Bar Graph 2 blue -COLOUR Red Values 255,0,0 -COLOUR Green Values green -COLOUR Purple Letters 151,52,228 -COMBINE Green Values Red Values -GRAPHLINE Red Values 2.6 threshold black -- - + + + +
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:
+
+ -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 +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 ++
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. + +
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
+ Annotations file has also supported the definition of reference
+ sequences and hidden regions for an alignment view.
+
+ 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.
+
+ HIDE_INSERTIONS
This command hides all gapped
+ positions in the current target sequence. Any columns already hidden
+ will be re-displayed.
The current target sequence is
+ either the one specified by the most recent SEQUENCE_REF
+ statement, the alignment's reference sequence, or the first sequence
+ in the alignment.
+
+ VIEW_HIDECOLS
Modifies the visibility of columns in
+ the view. The statement is followed by a single argument consisting
+ of a comma separated series of single integers or integer pairs
+ (like 3-4). These define columns (starting from the
+ left-hand column 0) that should be marked as hidden in the alignment
+ view.
+
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 +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,+ +LINE_GRAPH Green Values 1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2 +LINE_GRAPH Red Values 2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2 +BAR_GRAPH Bar Graph 2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4 +NO_GRAPH Icons ||||E,Sheet1|E|E||||H,Sheet 2|H|H|H|||||| +NO_GRAPH Purple Letters m|y|p|r|o|t|e|i|n +COLOUR Bar Graph 2 blue +COLOUR Red Values 255,0,0 +COLOUR Green Values green +COLOUR Purple Letters 151,52,228 +COMBINE Green Values Red Values +GRAPHLINE Red Values 2.6 threshold black + +SEQUENCE_GROUP Group_A 30 50 * +SEQUENCE_GROUP Group_B 1 351 2-5 +SEQUENCE_GROUP Group_C 12 14 -1 seq1 seq2 seq3 +PROPERTIES Group_A description=This is the description colour=Helix Propensity pidThreshold=0 outlineColour=red displayBoxes=true displayText=false colourText=false textCol1=black textCol2=black textColThreshold=0 +PROPERTIES Group_B outlineColour=red +PROPERTIES Group_C colour=Clustal ++ + +