X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=help%2Fhtml%2Ffeatures%2FannotationsFormat.html;h=fcdb90802df39a161304463cf9209768b1d99ae4;hb=37de9310bec3501cbc6381e0c3dcb282fcaad812;hp=2f030fc5ef6e4635a617943e0246b8702e82fd48;hpb=0762fd5ba34bf672805577223f80bf3bed157c3e;p=jalview.git diff --git a/help/html/features/annotationsFormat.html b/help/html/features/annotationsFormat.html index 2f030fc..fcdb908 100755 --- a/help/html/features/annotationsFormat.html +++ b/help/html/features/annotationsFormat.html @@ -24,224 +24,383 @@ -

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:
-

+

+

+ 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: + + + +

+ Any or all value fields may be left empty, as well as the BAR_GRAPH's + text character field, and either or both of the text-label and + secondary structure symbol fields of the NO_GRAPH type annotation + rows. +

+

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 :

- - - - - - - - - - - - - - - - - -
KeyValue
descriptionText - may include simple HTML tags
colourA string resolving to a valid Jalview colourscheme (e.g. Helix Propensity)
pidThresholdA number from 0-100 specifying the Percent Identity Threshold for colouring columns in the group or alignment
consThresholdA number from 0-100 specifying the degree of bleaching applied for conservation colouring
outlineColourLine colour used for outlining the group (default is red)
displayBoxesBoolean (default true) controlling display of shaded box for each alignment position
displayTextBoolean (default true) controlling display of text for each alignment position
colourTextBoolean (default false) specifying whether text should be shaded by applied colourscheme
textCol1Colour for text when shown on a light background
textCol2Colour for text when shown on a dark background
textColThresholdNumber from 0-100 specifying switching threshold between light and dark background
idColourColour 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.
showunconservedBoolean (default false) indicating whether residues should only be shown that are different from current reference or consensus sequence
hideBoolean (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 :

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyValue
descriptionText - may include simple HTML tags
colourA string resolving to a valid Jalview colourscheme + (e.g. Helix Propensity)
pidThresholdA number from 0-100 specifying the Percent Identity + Threshold for colouring columns in the group or alignment
consThresholdA number from 0-100 specifying the degree of bleaching + applied for conservation colouring
outlineColourLine colour used for outlining the group (default is + red)
displayBoxesBoolean (default true) controlling display of shaded + box for each alignment position
displayTextBoolean (default true) controlling display of text for + each alignment position
colourTextBoolean (default false) specifying whether text should + be shaded by applied colourscheme
textCol1Colour for text when shown on a light background
textCol2Colour for text when shown on a dark background
textColThresholdNumber from 0-100 specifying switching threshold + between light and dark background
idColourColour 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. +
showunconservedBoolean (default false) indicating whether residues + should only be shown that are different from current reference + or consensus sequence
hideBoolean (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
-

-
-

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 takes either a single sequence ID string, or a - numeric index (second argument), and attempts to assign a - corresponding sequence as the reference - sequence for the alignment. -

- VIEW_HIDECOLS takes either a single argument consisting of a - comma separated series of integer pairs like - 3-4. These integer pairs define columns (starting from the - left-hand column 0) that should be marked as hidden in the alignment - view. -

-

- HIDE_INSERTIONS takes a either a single sequence ID or a - numeric index, or no arguments. This command marks all gapped - positions in a specified sequence (either the one located by the - arguments, the current SEQUENCE_REF, or the reference sequence for the - 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.

-
+

+ 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
+  

+ 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,+
@@ -264,6 +423,6 @@ PROPERTIES	Group_A	description=This is the description	colour=Helix Pro
 PROPERTIES	Group_B	outlineColour=red
 PROPERTIES	Group_C	colour=Clustal
 
-

+