JAL-1551 spotlessApply
[jalview.git] / help / help / html / features / annotation.html
1 <html>
2 <!--
3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
5  * 
6  * This file is part of Jalview.
7  * 
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.
12  *  
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.
17  * 
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.
21  -->
22 <head>
23 <title>Alignment Annotation</title>
24 </head>
25 <body>
26   <p>
27     <strong>Alignment Annotation</strong>
28   </p>
29
30   <p>
31     In addition to the definition of groups and sequence features,
32     Jalview can display symbols and graphs 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&#8594;Show Annotation</strong>
36     option.
37   </p>
38   <p>
39     <strong>Types of annotation</strong>
40   <ul>
41     <li><a name="seqannots"><strong>Sequence
42           associated annotation.</strong></a><br />Data displayed on sequence
43       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 annotation is available for a the currently selected
49       sequences, it can be shown by selecting the <strong>Add
50         Reference Annotation</strong> option in the sequence or selection popup
51       menu.</li>
52     <li><strong>Group associated annotation.</strong><br />Data can
53       be associated with groups defined on the alignment. If sequence
54       groups are defined, <a href="../calculations/conservation.html">Conservation</a>
55       and <a href="../calculations/consensus.html">Consensus</a>
56       annotation can be enabled for each group from the <a
57       href="../menus/alwannotation.html">Annotations menu</a>, or can be
58       imported from a Jalview <a href="annotationsFormat.html">Annotations
59         file</a>.</li>
60     <li><strong>Alignment associated annotation.</strong><br />Annotation
61       rows associated with columns on the alignment are simply
62       'alignment annotation'. Controls allow you to <a href="#iaannot">interactively
63         create alignment annotation</a> to add labels and symbols to
64       alignment columns. Jalview's consensus, conservation and quality
65       calculations also create histogram and sequence logo annotations
66       on the alignment.</li>
67   </ul>
68   <p>
69     <strong>Importing and exporting annotation</strong><br />
70     Annotations on an alignment view are saved in Jalview project files.
71     You can also load <a href="annotationsFormat.html">Annotations
72       Files</a> in order to add any kind of quantitative and symbolic
73     annotations to an alignment. To see an example, use the <strong>Export
74       Features/Annotation</strong> option from an alignment window's File menu.
75   </p>
76   <p>
77     <strong>Layout and display controls</strong><br /> Individual and
78     groups of annotation rows can be shown or hidden using the pop-up
79     menu obtained by right-clicking the label. You can also reorder them
80     by dragging the label to a new position with the left mouse button.
81     The <strong>Annotations</strong> menu provides settings controlling
82     the ordering and display of sequence, group and alignment associated
83     annotation. The <strong>Colour by annotation</strong> option in the
84     colour menu allows annotation to be used to <a
85       href="../colourSchemes/annotationColouring.html">shade the
86       alignment</a>. Annotations can also be used to <a
87       href="../features/columnFilterByAnnotation.html">select or
88       hide columns</a> via the dialog opened from the <strong>Selection</strong>
89     menu.
90   </p>
91   <p>
92     <strong>Sequence Highlighting and Selection from Annotation</strong>
93   </p>
94   <p>
95     A <strong>single click</strong> on the label of an annotation row
96     associated with sequences and sequence groups will cause the
97     associated sequences to be highlighted in the alignment view. <strong>Double
98       clicking</strong> the label will select the associated sequences, replacing
99     any existing selection. Like with other kinds of selection, <strong>shift
100       double-click</strong> will add associated sequences, and <strong>Ctrl
101       (Mac CMD) double-click</strong> will toggle inclusion of associated
102     sequences in the selection.
103   <p>
104     <strong>Interactive Alignment Annotation</strong>
105   </p>
106   <p>
107     <a name="iaannot"> Annotation rows</a> are added using the <strong>Annotation
108       Label</strong> menu, which is obtained by clicking anywhere on the
109     annotation row labels area (below the sequence ID area).
110   </p>
111   <ul>
112     <li><strong>Add New Row</strong><br> <em>Adds a new,
113         named annotation row (a dialog box will pop up for you to enter
114         the label for the new row). </em></li>
115     <li><strong>Edit Label/Description</strong><br> <em>This
116         opens a dialog where you can change the name (displayed label),
117         or the description (as shown on the label tooltip) of the
118         clicked annotation. </em></li>
119     <li><strong>Hide This Row</strong><br> <em>Hides the
120         annotation row whose label was clicked in order to bring up the
121         menu.</em></li>
122     <li><strong>Hide All <em>&lt;label&gt;</em></strong><br> <em>Hides
123         all annotation rows whose label matches the one clicked. (This
124         option is only shown for annotations that relate to individual
125         sequences, not for whole alignment annotations. Since Jalview
126         2.8.2.)</em></li>
127     <li><strong>Delete This Row</strong><br> <em>Deletes
128         the annotation row whose label was clicked in order to bring up
129         the menu.</em></li>
130     <li><strong>Show All Hidden Rows</strong><br> <em>Shows
131         all hidden annotation rows.</em></li>
132     <li><strong>Export Annotation</strong> <em>(Application
133         only)</em><br> <em>Annotations can be saved to file or
134         output to a text window in either the Jalview annotations format
135         or as a spreadsheet style set of comma separated values (CSV). </em>
136     </li>
137     <li><strong>Show Values in Text Box</strong> <em>(applet
138         only)</em><br> <em>Opens a text box with a list of
139         comma-separated values corresponding to the annotation
140         (numerical or otherwise) at each position in the row. This is
141         useful to export alignment quality measurements for further
142         analysis.</em></li>
143     <li><strong>Scale Label To Column</strong><em>(introduced
144         in 2.5)</em><br> <em>Selecting this toggles whether column
145         labels will be shrunk to fit within each column, or displayed
146         using the view's standard font size.</em></li>
147   </ul>
148   <p>
149     <strong>Editing labels and secondary structure annotation
150       rows</strong>
151   </p>
152   <p>
153     Use the <strong>left mouse button</strong> to select a position
154     along the row that are to be annotated - these regions will be
155     coloured red. Press <strong>Control</strong> or <strong>shift</strong>
156     in combination with the left-click to either select an additional
157     position, or a range of positions on the alignment.
158   </p>
159   <p>
160     Once positions have been selected, use the <strong>right
161       mouse button</strong> and select one of the following from the <strong>annotation
162       menu</strong>:
163   </p>
164   <ul>
165     <li>Helix<br> <em>Marks selected positions with a
166         helix glyph (a red oval), and optional text label (see below). A
167         dialog box will open for you to enter the text. Consecutive
168         ovals will be rendered as an unbroken red line.</em>
169     </li>
170     <li>Sheet<br> <em>Marks selected positions with a
171         sheet glyph (a green arrow oriented from left to right), and
172         optional text label (see below). A dialog box will open for you
173         to enter the text. Consecutive arrows will be joined together to
174         form a single green arrow.</em>
175     </li>
176     <li><a name="rna">RNA Helix</a> (only shown when working with
177       nucleotide sequences)<br> <em>Marks selected positions
178         as participating in a base pair either upstream or downstream.
179         When the dialog box opens, enter a '(' to indicate these bases
180         pair with columns upstream (to right), and ')' to indicate this
181         region pairs with bases to the left of the highlighted columns.
182         Other kinds of base-pair annotation are also supported (e.g. 'A'
183         and 'a', or '&lt;' and '&gt;'), and Jalview will suggest an
184         appropriate symbol based on the closest unmatched parenthesis to
185         the left.<br />If any brackets do not match up, then an orange
186         square will highlight the first position where a bracket was
187         found not to match.
188     </em></li>
189     <li>Label<br> <em>Set the text label at the selected
190         positions. A dialog box will open for you to enter the text. If
191         more than one consecutive position is marked with the same
192         label, only the first position's label will be rendered.</em>
193     </li>
194     <li>Colour<br> <em>Changes the colour of the
195         annotation text label.</em>
196     </li>
197     <li>Remove Annotation<br> <em>Blanks any annotation
198         at the selected positions on the row. Note: <strong>This
199           cannot be undone</strong>
200     </em>
201     </li>
202   </ul>
203   <p>
204     User defined annotation is stored and retrieved using <a
205       href="../features/jalarchive.html">Jalview Archives</a>.
206   </p>
207   <p>
208     <em>Current Limitations</em>
209   </p>
210   <p>
211     The Jalview user interface does not support interactive creation and
212     editing of quantitative annotation (histograms and line graphs), or
213     to create annotation associated with a specific sequence or group.
214     It is also incapable of annotation grouping or changing the style of
215     existing annotation (e.g. to change between line or bar charts, or
216     to make multiple line graphs). These annotation capabilities are
217     only possible by the import of an <a href="annotationsFormat.html">Annotation
218       file</a>.<br>
219   </p>
220 </body>
221 </html>