Merge branch 'develop' into features/JAL-2094_colourInterface
[jalview.git] / 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><title>Alignment Annotation</title></head>
23 <body>
24 <p><strong>Alignment Annotation</strong></p>
25
26 <p>In addition to the definition of groups and sequence features,
27   Jalview can display symbols and graphs under the columns of an
28   alignment, and allow you to mark particular columns of an alignment and add symbols and text 
29   in the annotation area shown below the alignment (which may be hidden if <strong>View&#8594;Show 
30   Annotation</strong> is not ticked). Any displayed annotation row can be hidden (using the pop-up 
31   menu obtained by right-clicking the label), or re-ordered by dragging the label to a new 
32   position with the left mouse button.</p>
33 <p>
34 Web services can also add annotation to an alignment (see the <a
35 href="../webServices/jnet.html">JNet</a> and <a
36 href="../webServices/proteinDisorder.html">Disorder</a> protein
37 structure prediction services), and as of Jalview 2.08 quantitative
38 and symbolic annotations can be added to an alignment via an <a
39 href="annotationsFormat.html">Annotations File</a> dragged into the
40 alignment window or loaded from the alignment's file menu.
41 </p>
42 <p><a name="seqannots"/><strong>Sequence Reference Annotation</strong>
43 </p>
44 <p>
45                 Sequence reference annotation is created from 3D structure
46                 data, and from the results of sequence based prediction of
47                 <a href="../webServices/jnet.html">secondary structure</a> and <a
48                         href="../webServices/proteinDisorder.html">disordered region</a>
49                 prediction methods. 
50 </p>
51 <p><strong>Sequence Group Annotation</strong>
52 </p>
53 <p>
54         If sequence groups are defined, <a href="../calculations/conservation.html">Conservation</a>
55          and <a href="../calculations/consensus.html">Consensus</a> annotation can be enabled
56         for each group from the <a href="../menus/alwannotation.html">Annotations menu</a>, or can
57         be imported from a Jalview <a href="annotationsFormat.html">Annotations file</a>.
58 </p>
59 <p><strong>Sequence Selection from Annotation</strong>
60 </p>
61 <p>
62     Sequences associated with sequence (or sequence group) annotations can be selected by
63     double-clicking the annotation label with these key combinations:
64     <ul>
65     <li>double-click - Select associated sequences (replaces current selection)</li>
66     <li>shift double-click - add  sequences to selection</li>
67     <li>Ctrl (Mac CMD) double-click - toggles inclusion of associated sequences in the current selection</li>
68     </ul>
69     Note this also works in combination with manual sequence selection in the alignment.
70 <p><strong>Interactive Alignment Annotation</strong></p>
71 <p>
72 Annotation rows are added using the <strong>Annotation Label</strong>
73 menu, which is obtained by clicking anywhere on the annotation row labels
74 area (below the sequence ID area).
75 </p>
76 <ul>
77   <li><strong>Add New Row</strong><br>
78     <em>Adds a new, named annotation row (a dialog box will pop up for you to 
79     enter the label for the new row). </em> </li>
80   <li><strong>Edit Label/Description</strong><br>
81     <em>This opens a dialog where you can change the name (displayed label), or the description
82     (as shown on the label tooltip) of the clicked annotation. </em> </li>
83   <li><strong>Hide This Row</strong><br>
84     <em>Hides the annotation row whose label was clicked in order to bring up 
85     the menu.</em> </li>
86   <li><strong>Hide All <em>&lt;label&gt;</em></strong><br>
87     <em>Hides all annotation rows whose label matches the one clicked. 
88     (This option is only shown for annotations that relate to individual sequences, 
89     not for whole alignment annotations. Since Jalview 2.8.2.)</em> </li>
90   <li><strong>Delete This Row</strong><br>
91     <em>Deletes the annotation row whose label was clicked in order to bring up 
92     the menu.</em> </li>
93   <li><strong>Show All Hidden Rows</strong><br>
94     <em>Shows all hidden annotation rows.</em> </li>
95           <li><strong>Export Annotation</strong> <em>(Application only)</em><br>
96        <em>Annotations can be saved to file or output to a text window in either the 
97         Jalview annotations format or as a spreadsheet style set of comma separated values (CSV). </em> </li>
98       <li><strong>Show Values in Text Box</strong> <em>(applet only)</em><br>
99         <em>Opens a text box with a list of comma-separated values corresponding 
100         to the annotation (numerical or otherwise) at each position in the row. 
101         This is useful to export alignment quality measurements for further analysis.</em> 
102       </li>
103       <li><strong>Scale Label To Column</strong><em>(introduced in 2.5)</em><br>
104       <em>Selecting this toggles whether column labels will be shrunk to fit within each column, or displayed using the view's standard font size.</em></li>
105 </ul>
106 <p>
107 <strong>Editing Label and secondary structure Annotation</strong></p>
108 <p>
109 Use the <strong>left mouse button</strong> to select a position along the row that are to
110 be annotated - these regions will be coloured red. <strong>Control</strong> and <strong>shift</strong> in combination
111 with the left-click will select more than one position, or a range of
112 positions on the alignment.
113 </p>
114 <p>Once the desired position has been selected, use the <strong>right mouse
115 button</strong> to open the <strong>annotation menu</strong>:</p>
116 <ul>
117 <li>Helix<br><em>Mark selected positions with a helix glyph (a red
118 oval), and optional text label (see below). A
119 dialog box will open for you to enter the text. Consecutive ovals
120 will be rendered as an unbroken red line.</em>
121 </li>
122 <li>Sheet<br><em>Mark selected positions with a sheet glyph (a green
123 arrow oriented from left to right), and optional text label (see
124 below). A dialog box will open for you to enter the text. Consecutive
125 arrows will be joined together to form a single green arrow.</em>
126 </li>
127 <li><a name="rna">RNA Helix</a> (only shown when working with nucleotide sequences)<br>
128 <em>Mark selected positions as participating in a base pair
129 either upstream or downstream. When the dialog box opens, enter a
130 '(' to indicate these bases pair with columns upstream (to right),
131 and ')' to indicate this region pairs with bases to the left of the
132 highlighted columns.<br />If any brackets do not match up, then an
133 orange square will highlight the first position where a bracket was
134 found not to match.
135 </em>
136 </li>
137 <li>Label<br><em>Set the text label at the selected positions. A
138 dialog box will open for you to enter the text.  If
139 more than one consecutive position is marked with the same label, only
140 the first position's label will be rendered.</em>
141 </li>
142 <li>Colour<br><em>Changes the colour of the annotation text label.</em>
143 </li>
144 <li>Remove Annotation<br><em>Blanks any annotation at the selected positions on
145 the row. Note: <strong>This cannot be undone</strong></em>
146 </li>
147 </ul>
148 <p>
149 User defined annotation is stored and retrieved using <a
150 href="../features/jalarchive.html">Jalview Archives</a>.
151 </p>
152 <p><em>Current Limitations</em></p>
153 <p>As of version 2.5, the Jalview user interface does not support the 
154 creation and editing of quantitative annotation (histograms and line graphs), or 
155 to create annotation associated with a specific sequence. It is also incapable of
156 annotation grouping or changing the style of existing annotation (to change between line or bar charts, or to make multiple line graphs). These annotation capabilities are only possible by the import of an 
157 <a href="annotationsFormat.html">Annotation file</a>.<br>
158 </p>
159 </body>
160 </html>