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:

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

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.

• JALVIEW_ANNOTATION mandatory header
• LINE_GRAPH, BAR_GRAPH and NO_GRAPH to create annotation rows
• COMBINE, COLOUR and GRAPHLINE for thresholds and complex line graphs
• ROWPROPERTIES control the display of individual annotation rows
• SEQUENCE_GROUP to define groups of sequences for further annotation
• PROPERTIES to set visualisation properties for sequence groups
• SEQUENCE_REF and GROUP_REF for specifying target sequences and groups for annotation, reference sequence and column visibilty commands.
• VIEW_SETREF, VIEW_HIDECOLS and HIDE_INSERTIONS for assigning the reference sequence on the alignment and hiding columns.

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.

Please note: URL links embedded in HTML descriptions are not yet supported.

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:

• 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
  
  The type of secondary structure symbol depends on the alignment being annotated being either Protein or RNA.
  For proteins, structure symbols are H (for helix) and E (for strand)
  
  For RNA structures, VIENNA, WUSS, and extended notations can be used to specify paired positions.
  e.g. "(|(||)|)" or "|A|A|A|(|a|a|a|)")

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:

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

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

Set both Group_Start and Group_End to * to include the full sequence(s) range.

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 :

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]
  

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