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, 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&#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       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
  58         file</a>.</li>
  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>
  66   </ul>
  67   <p>
  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.
  74   </p>
  75   <p>
  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.
  89   </p>
  90   <p>
  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>
  92   <p>
  93     <strong>Sequence Highlighting and Selection from Annotation</strong>
  94   </p>
  95   <p>
  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.
 104   <p>
 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.
 107     <ul>
 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>
 111     </ul>
 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.
 113   <p>
 114     <strong>Interactive Alignment Annotation</strong>
 115   </p>
 116   <p>
 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).
 120   </p>
 121   <ul>
 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
 131         menu.</em></li>
 132     <li><strong>Hide All <em>&lt;label&gt;</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
 136         2.8.2.)</em></li>
 137     <li><strong>Delete This Row</strong><br> <em>Deletes
 138         the annotation row whose label was clicked in order to bring up
 139         the menu.</em></li>
 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>
 146     </li>
 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
 152         analysis.</em></li>
 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>
 163
 164   </ul>
 165   <p>
 166     <strong>Editing labels and secondary structure annotation
 167       rows</strong>
 168   </p>
 169   <p>
 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.
 175   </p>
 176   <p>
 177     Once positions have been selected, use the <strong>right
 178       mouse button</strong> and select one of the following from the <strong>annotation
 179       menu</strong>:
 180   </p>
 181   <ul>
 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>
 186     </li>
 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>
 192     </li>
 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 '&lt;' and '&gt;'), 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
 204         found not to match.
 205     </em></li>
 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>
 210     </li>
 211     <li>Colour<br> <em>Changes the colour of the
 212         annotation text label.</em>
 213     </li>
 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>
 217     </em>
 218     </li>
 219   </ul>
 220   <p>
 221     User defined annotation is stored and retrieved using <a
 222       href="../features/jalarchive.html">Jalview Archives</a>.
 223   </p>
 224   <p>
 225     <em>Current Limitations</em>
 226   </p>
 227   <p>
 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
 235       file</a>.<br>
 236   </p>
 237 </body>
 238 </html>