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>