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:

- from the command line

       -annotations <Annotations filename>

- Dragging an annotations file onto an alignment window
- Via the "Load Features / Annotations" entry in the File menu of an alignment window.

### Format of an Annotations File

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	Description (optional)	Values

The GRAPH_TYPE field, which appears first, 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 in the same way as a sequence feature's label, providing the html is enclosed in an <html/> tag.

Please note: URL links embedded in HTML descriptions will be supported in a future release of Jalview

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 the format of their respective value fields (with the trailing "|" symbol) are shown below:

- BAR_GRAPH
  Plots a histogram with labels below each bar.
  number,text character,Tooltip text
- LINE_GRAPH
  Draws a line between values on the annotation row.
  number
- NO_GRAPH
  For a row consisting of text labels and/or secondary structure symbols.
  {Secondary Structure Symbol},text label,Tooltip text
  Currently supported secondary structure structure symbols are H (for helix) and E (for strand)

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.

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

### LINE_GRAPH Grouping

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

### (Since Jalview 2.5) 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:

- centrelabs Centre each label on its column.
- showalllabs Show every column label rather than only the first of a run of identical labels (setting this to true can have a drastic effect on secondary structure rows).
- scaletofit Shrink each label's font size so that the label fits within the column. Useful when annotating an alignment with a specific column numbering system. (Not available in Jalview applet due to AWT 1.1 limitations)

### (Since Jalview 2.2.1) SEQUENCE_GROUP

Groups of sequences can be defined using the tab delimited line

    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.

If the alignment indices are not known, enter -1 then a tab delimited list of sequence ids.

If the SEQUENCE_REF has been defined, the group_start and group_end will be relative to the sequence residue numbering, otherwise the group_start and group_end will be the alignment column indices.

The group can (optionally) be assigned various visualisation properties via another tab delimited line thus:

    PROPERTIES	Group_name	tab_delimited_key_value_pairs

The key_value_pairs allow you to define a description and to colour the group in various ways. All, none or some of the following values could be used for a group:

description=Text
colour=Helix Propensity
pidThreshold=0
consThreshold=0
outlineColour=red
displayBoxes=true
displayText=false
colourText=false
textCol1=black
textCol2=black
textColThreshold=0
idColour=ff3322
showunconserved=false

- New Features in 2.4:
  if the idColour property is given without specifying a colour scheme with the colour property, then the idColour will also be used to colour the sequence.
- 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 associated Groups
  If a group is defined after a valid SEQUENCE_REF sequence reference statement, the sequence representative for the group will be set to the referenced sequence.

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