help/help/html/features/paematrices.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>Working with PAE Matrices in Jalview</title>
  24 </head>
  25
  26 <body>
  27         <p>
  28                 <strong>Working with Predicted Alignment Error Matrices in
  29                         Jalview</strong>
  30         </p>
  31
  32   <p>Predicted Alignment Error (PAE) matrices are produced by
  33     deep-learning based 3D-structure prediction pipelines such as
  34     AlphaFold. They reflect how reliably two parts of a model have been
  35     positioned in space. Each column in a PAE matrix corresponds to a
  36     residue in the model, and each gives the likely RMS error (in
  37     &Aring;ngstroms) between that residue and every other modelled
  38     position the pair of residues' real relative position, if the model
  39     and real 3D structure were superimposed at that residue.</p>
  40         <p>
  41                 Jalview visualises PAE matrices as an alignment annotation track,
  42                 shaded from dark green to white, similar to the encoding used on the
  43                 EBI-AlphaFold website (see <a
  44                         href="https://alphafold.ebi.ac.uk/entry/O04090">O04090 3D model</a>
  45                 at EBI-AlphaFoldDB).
  46         </p>
  47   <img src="../structures/epas1_annotdetail.png" width="450" />
  48   <br/><em>
  49                                 Alignment of EPAS1 homologs from Human, Rat and Cow shaded by PLDDT, with
  50                                 Predicted Alignment Error and secondary structure annotation shown for Human.
  51                                 </em>
  52         <!--</div>
  53   <div width="35%">
  54                 <figure>
  55                         <img src="../structures/epas1_pae_ebiaf.png" />
  56                         <figcaption>
  57                                 Predicted Alignment Error for Human EPAS1<br />from <a
  58                                         href="https://alphafold.ebi.ac.uk/entry/Q99814">https://alphafold.ebi.ac.uk/entry/Q99814</a>
  59                         </figcaption>
  60                 </figure>
  61                 </div>
  62         </div> -->
  63         <p>
  64                 <strong>Importing PAE Matrices</strong>
  65         </p>
  66         <p>
  67                 Jalview retrieves PAE matrices when importing predicted 3D structures
  68                 from the EBI-AlphaFold database via <a
  69                         href="../features/structurechooser.html">Jalview's structure
  70                         chooser</a> GUI. If you have produced your own models and accompanying
  71                 PAE matrices using a pipeline such as ColabFold, then you can load
  72                 them both together via the <a
  73                         href="../features/structurechooser.html#loadpdbfile">Load PDB
  74                         File</a> dropdown menu in the 3D structure chooser, providing it is in a
  75                 <a href="../io/paematrixformat.html">supported PAE format</a>.
  76         </p>
  77         <p>
  78                 The <a href="../features/clarguments-basic.html">Command Line
  79                         Interface</a> also provides the option to import a PAE matrix alongside
  80                         a 3D structure file, enabling the automated production of alignment figures
  81                   annotated with PAE matrices and PLDDT scores.
  82         </p>
  83         <p>
  84                 <strong>Showing PAE Matrix Annotations </strong>
  85         </p>
  86         <p>
  87                 When viewing 3D structures from the EBI-AlphaFold database or local 3D
  88                 structures with an associated PAE file, the PAE is imported as <i>Reference
  89                         Annotation</i>, and is not always automatically added to the alignment
  90                 view.
  91         </p>
  92         <p>To show the PAE, right click the sequence and locate the 'Add
  93                 Reference Annotation' entry in the Sequence ID submenu, or select all
  94                 sequences and locate the option in the Selection submenu. You can do
  95                 this in any alignment window (or view) where a sequence with
  96                 associated PAE data appears.</p>
  97         <p>
  98                 <strong>Adjusting the height of PAE matrix annotations</strong>
  99         </p>
 100         <p>
 101                 PAE annotations behave in the same way as Jalview's line graph and
 102                 histogram tracks. Click+dragging up and down with the left (select)
 103                 mouse button held down will increase or decrease the height of the
 104                 annotation. You can also hold down <strong><em>SHIFT</em></strong>
 105                 whilst doing this to adjust the height of all PAE rows at once.
 106         </p>
 107         <p>PAE matrix annotation rows behave like any other sequence
 108                 associated annotation, with the following additional features:</p>
 109         <ul>
 110                 <li>The vertical axis of the PAE heatmap is mapped to positions
 111                         on the linked 3D structure.
 112                         <ul>
 113                                 <li>Mousing over the matrix shows a tooltip giving information
 114                                         on the range of values under the mouse.<br />Positions in the
 115                                         associated 3D structure are also highlighted in any linked views.
 116                                 </li>
 117                                 <li>Clicking on positions in the matrix selects columns of the
 118                                         alignment corresponding to the row and column in the matrix.</li>
 119                         </ul>
 120                 </li>
 121                 <li>Rectangular selections (created by Cmd (or Alt)+Click
 122                         dragging on the matrix) can be created to select multiple ranges of
 123                         columns at once.</li>
 124                 <li>Columns corresponding to adjacent regions with similarly low
 125                         levels of predicted alignment error can be selected by Ctrl+Clicking
 126                         on a region in the matrix.</li>
 127                 <li>Columns of an alignment showing a PAE matrix can be grouped
 128                         and selected by clustering the matrix.</li>
 129         </ul>
 130         <p>
 131                 <strong><a name="clustering">Clustering PAE Matrices</a></strong>
 132         </p>
 133         <p>PAE matrices are useful for identifying regions of 3D structure
 134                 predictions that are likely to be positioned in space in the same or
 135                 similar way as shown in the predicted structure data. Regions of low
 136                 PAE often correlate with high alphafold reliability (PLDDT) scores,
 137                 but also complement them since they highlight well-folded regions such
 138                 as domains, and how well those regions have been predicted to be
 139                 positioned relative to each other, which is important when evaluating
 140                 whether domain-domain interactions or other contacts can be trusted.</p>
 141         <p>To make it easy to identify regions of low PAE, Jalview can
 142                 cluster the PAE matrix, allowing columns of the matrix to be grouped
 143                 according to their similarity, using an Average Distance (UPGMA) tree
 144                 algorithm and the sum of differences between each column's PAE values.</p>
 145         <p>
 146                 <strong><em>dist<sub>ij</sub></em> = &#8741; <em><u>p</u><sub>i</sub>-<u>p</u><sub>j</sub></em>
 147                         &#8741;</strong>
 148         </p>
 149         <p>
 150                 <em>Creating a PAE matrix tree</em><br/>Right click on a PAE annotation's label
 151                 to open the annotation popup menu, and select <strong><em>Cluster
 152                                 Matrix</em></strong>. Once the calculation has finished, a tree viewer will open,
 153                 and columns of the matrix are then partitioned into groups such that
 154                 the third left-most node from the root is placed in its own group.
 155                 Colours are randomly assigned to each group. By default column group colours will
 156                 also be overlaid on the matrix annotation row - this can be turned off
 157                 via the PAE annotation row menu (by unticking <em>Show groups on matrix</em>).</p>
 158         <p>
 159   The PAE matrix tree viewer behaves like other tree views, except:
 160         <ul>
 161                 <li>Selecting nodes or groups of nodes in the tree select
 162                         columns in the alignment, and clicking in the tree window adjust
 163                         the matrix's partition.</li>
 164                 <li>Only one tree and clustering can be defined for a PAE matrix,
 165                         regardless of whether it is displayed in different views or
 166                         alignments.</li>
 167         </ul>
 168         Once the PAE annotation has clustering defined:
 169         <ul><li>Double clicking on a position in the PAE annotation where a
 170                         clustering has been defined will select both the row and column
 171                         clusters for the clicked position. <br/><br/>This makes it easy to select
 172                         clusters corresponding to pairs of interacting regions.</li>
 173                 <li>Cluster colours for a PAE matrix can be used to colour
 174                         sequences or columns of the alignment via the <strong><em><a
 175                                         href="../colourSchemes/annotationColouring.html">Colour by
 176                                                 Annotation.. dialog</a></em></strong>
 177                                                 (opened by right-clicking the annotation label
 178                         and selecting from the popup menu).
 179                 </li>
 180         </ul>
 181         <p>
 182                 <strong>PAE matrices and Jalview Projects</strong>
 183         </p>
 184         <p>Any PAE matrices imported to Jalview are saved along side any
 185                 trees and clustering defined on them in Jalview Projects.</p>
 186         <p>
 187                 <em>Support for visualision and analysis of predicted alignment
 188                         error matrices was added in Jalview 2.11.3. </em>
 189         </p>
 190 </body>
 191 </html>