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