3 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4 * Copyright (C) $$Year-Rel$$ The Jalview Authors
6 * This file is part of Jalview.
8 * Jalview is free software: you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License
10 * as published by the Free Software Foundation, either version 3
11 * of the License, or (at your option) any later version.
13 * Jalview is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty
15 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
16 * PURPOSE. See the GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
20 * The Jalview Authors are detailed in the 'AUTHORS' file.
23 <title>Alignment Annotation</title>
27 <strong>Alignment Annotation</strong>
31 In addition to the definition of groups and sequence features,
32 Jalview can display symbols, line graphs, histograms and heatmaps under the columns of an
33 alignment. These annotation tracks are displayed in the annotation
34 area below the alignment. The annotation area's visibility is
35 controlled with the <strong>View→Show Annotation</strong>
39 <strong>Types of annotation</strong>
41 <li><a name="seqannots"><strong>Sequence
42 associated annotation.</strong></a><br />Data displayed on sequence
43 associated annotation rows are associated with the positions of a sequence.
44 Often this is 'Reference annotation' such as secondary structure
45 information derived from 3D structure data, or from the results of
46 sequence based prediction of <a href="../webServices/jnet.html">secondary
47 structure</a> and <a href="../webServices/proteinDisorder.html">disorder</a>.
48 If reference annotations are available for a particular sequence or the current selections, they can be shown by selecting the <strong>Add
49 Reference Annotation</strong> option in the sequence or selection popup
50 menu.<br/>Jalview currently supports the following sources of sequence associated annotation:<ul><li>Protein and RNA Secondary Structure<br/>These can be obtained from JPred and RNAAliFold secondary structure prediction services, and also for imported 3D Structure data.</li><li>Temperature factor, Model Quality or AlphaFold Reliability</br>Jalview extracts and displays values from the 'Temperature Factor' column of PDB and mmCIF files, interpreted in various ways. For regular PDB files, these are imported directly as 'Temperature Factor', but for structures from computational methods such as EBI-AlphaFold, these values are interpreted and shown as 'AlphaFold Reliability' or 'Model Quality' according to the source.</li><li><a href="paematrices.html">Predicted Alignment Error</a> heatmaps<br/>These are displayed for models retrieved from EBI-AlphaFold or when a supported JSON format PAE file is provided when importing a <a href="structurechooser.html#loadpdbfile">local 3D structure file</a>.</li></ul></li>
51 <li><strong>Group associated annotation.</strong><br />Data can
52 be associated with groups defined on the alignment. If sequence
53 groups are defined, <a href="../calculations/conservation.html">Conservation</a>
54 and <a href="../calculations/consensus.html">Consensus</a>
55 annotation can be enabled for each group from the <a
56 href="../menus/alwannotation.html">Annotations menu</a>, or can be
57 imported from a Jalview <a href="annotationsFormat.html">Annotations
59 <li><strong>Alignment associated annotation.</strong><br />Annotation
60 rows associated with columns on the alignment are simply
61 'alignment annotation'. Controls allow you to <a href="#iaannot">interactively
62 create alignment annotation</a> to add labels and symbols to
63 alignment columns. Jalview's consensus, conservation and quality
64 calculations also create histogram and sequence logo annotations
65 on the alignment.</li>
68 <strong>Importing and exporting annotation</strong><br />
69 Annotations on an alignment view are saved in Jalview project files.
70 You can also load <a href="annotationsFormat.html">Annotations
71 Files</a> in order to add any kind of quantitative and symbolic
72 annotations to an alignment. To see an example, use the <strong>Export
73 Features/Annotation</strong> option from an alignment window's File menu.
76 <strong>Layout and display controls</strong><br /> Individual and
77 groups of annotation rows can be shown or hidden using the pop-up
78 menu obtained by right-clicking the label. You can also reorder them
79 by dragging the label to a new position with the left mouse button.
80 The <strong>Annotations</strong> menu provides settings controlling
81 the ordering and display of sequence, group and alignment associated
82 annotation. The <strong>Colour by annotation</strong> option in the
83 colour menu allows annotation to be used to <a
84 href="../colourSchemes/annotationColouring.html">shade the
85 alignment</a>. Annotations can also be used to <a
86 href="../features/columnFilterByAnnotation.html">select or
87 hide columns</a> via the dialog opened from the <strong>Selection</strong>
88 menu. You can also colour, select or hide columns of the alignment using any displayed annotation row by right-clicking its label and selecting the option from the displayed pop-up menu.
91 <strong>Adjusting the height of histograms, line graphs and heatmaps</strong><br/>The height of line graphs, bar charts and <a href="paematrices.html">predicted alignment error (PAE) matrix heatmaps</a> can be adjusted simply by click-dragging them up or down to increase or decrease the height. Hold down <em><strong>SHIFT</strong></em> to adjust the height of all instances of a particular type of annotation row.</p>
93 <strong>Sequence Highlighting and Selection from Annotation</strong>
96 A <strong>single click</strong> on the label of an annotation row
97 associated with sequences and sequence groups will cause the
98 associated sequences to be highlighted in the alignment view. <strong>Double
99 clicking</strong> the label will select the associated sequences, replacing
100 any existing selection. Like with other kinds of selection, <strong>shift
101 double-click</strong> will add associated sequences, and <strong>Ctrl
102 (Mac CMD) double-click</strong> will toggle inclusion of associated
103 sequences in the selection.
105 <strong>Selecting, analysing and exploring heatmap annotation</strong>
106 </p><p>Mouseovers on heap annotation tracks result in a tooltip displaying information about the range of values under the mouse, and their associated row and column in the heatmap.<br/>For <a href="paematrices.html">Predicted Alignment Error (PAE) matrices</a>, the only form of heatmap annotation currently supported by Jalview, both the vertical and horizontal positions in the heatmap correspond to positions in linked 3D structures and the associated sequence in the alignment - so clicking any position in a heatmap will select columns in the alignment corresponding to the selected row(s) and column under the mouse.
108 <li>Rows and columns in the heatmap corresponding to currently selected columns in the alignment are shown as red horizontal and vertical bands.</li>
109 <li><em>Rectangular Selections</em> can be created by pressing <em>CMD (or Window/Meta key)</em> whilst click-dragging across an area of the annotation.</li>
110 <li><em>Data driven selections</em> - e.g. selecting regions of low values of Predicted Alignment Error in a heatmap can be dome by pressing <em>CTRL</em> whilst clicking a region of an alignment.</li>
112 Heatmap annotations can also be clustered, enabling columns of the alignment to be grouped based on similarity of the sets of values in the heatmap. <em>Double clicking</em> a region of a clustered heatmap annotation will select both the row and columns of the alignment grouped by the clustering. See <a href="paematrices.html#clustering">clustering PAE matrices</a> for more information.
114 <strong>Interactive Alignment Annotation</strong>
117 <a name="iaannot"> Annotation rows</a> are added using the <strong>Annotation
118 Label</strong> menu, which is obtained by clicking anywhere on the
119 annotation row labels area (below the sequence ID area).
122 <li><strong>Add New Row</strong><br> <em>Adds a new,
123 named annotation row (a dialog box will pop up for you to enter
124 the label for the new row). </em></li>
125 <li><strong>Edit Label/Description</strong><br> <em>This
126 opens a dialog where you can change the name (displayed label),
127 or the description (as shown on the label tooltip) of the
128 clicked annotation. </em></li>
129 <li><strong>Hide This Row</strong><br> <em>Hides the
130 annotation row whose label was clicked in order to bring up the
132 <li><strong>Hide All <em><label></em></strong><br> <em>Hides
133 all annotation rows whose label matches the one clicked. (This
134 option is only shown for annotations that relate to individual
135 sequences, not for whole alignment annotations. Since Jalview
137 <li><strong>Delete This Row</strong><br> <em>Deletes
138 the annotation row whose label was clicked in order to bring up
140 <li><strong>Show All Hidden Rows</strong><br> <em>Shows
141 all hidden annotation rows.</em></li>
142 <li><strong>Export Annotation</strong> <em>(Application
143 only)</em><br> <em>Annotations can be saved to file or
144 output to a text window in either the Jalview annotations format
145 or as a spreadsheet style set of comma separated values (CSV). </em>
147 <li><strong>Show Values in Text Box</strong> <em>(applet
148 only)</em><br> <em>Opens a text box with a list of
149 comma-separated values corresponding to the annotation
150 (numerical or otherwise) at each position in the row. This is
151 useful to export alignment quality measurements for further
153 <li><strong>Scale Label To Column</strong><em>(introduced
154 in 2.5)</em><br> <em>Selecting this toggles whether column
155 labels will be shrunk to fit within each column, or displayed
156 using the view's standard font size.</em></li>
157 <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
158 <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
159 <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
160 <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
161 <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
162 <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
166 <strong>Editing labels and secondary structure annotation
170 Use the <strong>left mouse button</strong> to select a position
171 along the row that are to be annotated - these regions will be
172 coloured red. Press <strong>Control</strong> or <strong>shift</strong>
173 in combination with the left-click to either select an additional
174 position, or a range of positions on the alignment.
177 Once positions have been selected, use the <strong>right
178 mouse button</strong> and select one of the following from the <strong>annotation
182 <li>Helix<br> <em>Marks selected positions with a
183 helix glyph (a red oval), and optional text label (see below). A
184 dialog box will open for you to enter the text. Consecutive
185 ovals will be rendered as an unbroken red line.</em>
187 <li>Sheet<br> <em>Marks selected positions with a
188 sheet glyph (a green arrow oriented from left to right), and
189 optional text label (see below). A dialog box will open for you
190 to enter the text. Consecutive arrows will be joined together to
191 form a single green arrow.</em>
193 <li><a name="rna">RNA Helix</a> (only shown when working with
194 nucleotide sequences)<br> <em>Marks selected positions
195 as participating in a base pair either upstream or downstream.
196 When the dialog box opens, enter a '(' to indicate these bases
197 pair with columns upstream (to right), and ')' to indicate this
198 region pairs with bases to the left of the highlighted columns.
199 Other kinds of base-pair annotation are also supported (e.g. 'A'
200 and 'a', or '<' and '>'), and Jalview will suggest an
201 appropriate symbol based on the closest unmatched parenthesis to
202 the left.<br />If any brackets do not match up, then an orange
203 square will highlight the first position where a bracket was
206 <li>Label<br> <em>Set the text label at the selected
207 positions. A dialog box will open for you to enter the text. If
208 more than one consecutive position is marked with the same
209 label, only the first position's label will be rendered.</em>
211 <li>Colour<br> <em>Changes the colour of the
212 annotation text label.</em>
214 <li>Remove Annotation<br> <em>Blanks any annotation
215 at the selected positions on the row. Note: <strong>This
216 cannot be undone</strong>
221 User defined annotation is stored and retrieved using <a
222 href="../features/jalarchive.html">Jalview Archives</a>.
225 <em>Current Limitations</em>
228 The Jalview user interface does not support interactive creation and
229 editing of quantitative annotation (histograms and line graphs), or
230 to create annotation associated with a specific sequence or group.
231 It is also incapable of annotation grouping or changing the style of
232 existing annotation (e.g. to change between line or bar charts, or
233 to make multiple line graphs). These annotation capabilities are
234 only possible by the import of an <a href="annotationsFormat.html">Annotation