X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=help%2Fhelp%2Fhtml%2Ffeatures%2Fpaematrices.html;h=2f00e19f047da6d3f3509f907bdccf6c6e39e6cc;hb=56ce5cb6fd0b54f831cf35859886cd69a7f522a3;hp=d22925179d438aa8442dd76b16c0d4cb1e6a66d0;hpb=985903ad810d9ef6ba0d09ff2b29d24e22c0708d;p=jalview.git

diff --git a/help/help/html/features/paematrices.html b/help/help/html/features/paematrices.html
index d229251..2f00e19 100644
--- a/help/help/html/features/paematrices.html
+++ b/help/help/html/features/paematrices.html
@@ -43,6 +43,23 @@
 			href="https://alphafold.ebi.ac.uk/entry/O04090">O04090 3D model</a>
 		at EBI-AlphaFoldDB).
 	</p>
+	<div style="display: flex; flex-wrap: wrap;" align="center"
+		width="100%">
+		<figure>
+			<img src="../structures/epas1_annotdetail.png" height="300" />
+			<figcaption>
+				Alignment of EPAS1 homologs from Human, Rat and Cow<br />with
+				predicted alignment error shown for Human
+			</figcaption>
+		</figure>
+		<figure>
+			<img src="../structures/epas1_pae_ebiaf.png" height="300" />
+			<figcaption>
+				Predicted Alignment Error for Human EPAS1<br />from <a
+					href="https://alphafold.ebi.ac.uk/entry/Q99814">https://alphafold.ebi.ac.uk/entry/Q99814</a>
+			</figcaption>
+		</figure>
+	</div>
 	<p>
 		<strong>Importing PAE Matrices</strong>
 	</p>
@@ -54,8 +71,8 @@
 		PAE matrices using a pipeline such as ColabFold, then you can load
 		them both together via the <a
 			href="../features/structurechooser.html#loadpdbfile">Load PDB
-			File</a> dropdown menu in the 3D structure chooser. in a <a
-			href="../io/paematrixformat.html">supported PAE format</a>.
+			File</a> dropdown menu in the 3D structure chooser, providing it is in a
+		<a href="../io/paematrixformat.html">supported PAE format</a>.
 	</p>
 	<p>
 		The <a href="../features/clarguments-basic.html">Command Line
@@ -77,7 +94,92 @@
 		sequences and locate the option in the Selection submenu. You can do
 		this in any alignment window (or view) where a sequence with
 		associated PAE data appears.</p>
-	<p></p>
+	<p>
+		<strong>Adjusting the height of PAE matrix annotations</strong>
+	</p>
+	<p>
+		PAE annotations behave in the same way as Jalview's line graph and
+		histogram tracks. Click+dragging up and down with the left (select)
+		mouse button held down will increase or decrease the height of the
+		annotation. You can also hold down <strong><em>SHIFT</em></strong>
+		whilst doing this to adjust the height of all PAE rows at once.
+	</p>
+	<p>PAE matrix annotation rows behave like any other sequence
+		associated annotation, with the following additional features:</p>
+	<ul>
+		<li>The vertical axis of the PAE heatmap is mapped to positions
+			on the linked 3D structure.
+			<ul>
+				<li>Mousing over the matrix shows a tooltip giving information
+					on the range of values under the mouse.<br />Positions in the
+					associated 3D structure are also highlighted in any linked views.
+				</li>
+				<li>Clicking on positions in the matrix selects columns of the
+					alignment corresponding to the row and column in the matrix.</li>
+			</ul>
+		</li>
+		<li>Rectangular selections (created by Cmd (or Alt)+Click
+			dragging on the matrix) can be created to select multiple ranges of
+			columns at once.</li>
+		<li>Columns corresponding to adjacent regions with similarly low
+			levels of predicted alignment error can be selected by Ctrl+Clicking
+			on a region in the matrix.</li>
+		<li>Columns of an alignment showing a PAE matrix can be grouped
+			and selected by clustering the matrix.</li>
+	</ul>
+	<p>
+		<strong><a name="clustering">Clustering PAE Matrices</a></strong>
+	</p>
+	<p>PAE matrices are useful for identifying regions of 3D structure
+		predictions that are likely to be positioned in space in the same or
+		similar way as shown in the predicted structure data. Regions of low
+		PAE often correlate with high alphafold reliability (PLDDT) scores,
+		but also complement them since they highlight well-folded regions such
+		as domains, and how well those regions have been predicted to be
+		positioned relative to eachother, which is important when evaluating
+		whether domain-domain interactions or other contacts can be trusted.</p>
+	<p>To make it more easy to identify regions of low PAE, Jalview can
+		cluster the PAE matrix, allowing columns of the matrix to be grouped
+		according to their similarity, using an Average Distance (UPGMA) tree
+		algorithm and the sum of differences between each column's PAE values.</p>
+	<p>
+		<strong><em>dist<sub>ij</sub></em> = &#8741; <em><u>p</u><sub>i</sub>-<u>p</u><sub>j</sub></em>
+			&#8741;</strong>
+	</p>
+	<p>
+		To create a PAE matrix tree, right click on a PAE annotation's label
+		to open the annotation popup menu, and select <strong><em>Cluster
+				Matrix</em></strong>. Once the calculation has finished, a tree viewer will open,
+		and columns of the matrix are then partitioned into groups such that
+		the third left-most node from the root is placed in its own group.
+		Colours are randomly assigned to each group, and by default these will
+		also be overlaid on the matrix annotation row.
+	<p>
+	<ul>
+		<li>The PAE matrix tree viewer behaves like other tree views in
+			Jalview, except selecting nodes or groups of nodes in the tree select
+			columns in the alignment rather than sequences, and clicking adjust
+			the matrix's partition.</li>
+		<li>Only one tree and clustering can be defined for a PAE matrix,
+			regardless of whether it is displayed in different views or
+			alignments.</li>
+		<li>Double clicking on a position in the PAE annotation where a
+			clustering has been defined will select both the row and column
+			clusters for the clicked position. This makes it easy to select
+			clusters corresponding to pairs of interacting regions.</li>
+		<li>Cluster colours for a PAE matrix can be used to colour
+			sequences or columns of the alignment via the <strong><em><a
+					href="../colourSchemes/annotationColouring.html">Colour by
+						Annotation.. dialog</a></em></strong>
+						(opened by right-clicking the annotation label
+			and selecting from the popup menu).
+		</li>
+	</ul>
+	<p>
+		<strong>PAE matrices and Jalview Projects</strong>
+	</p>
+	<p>Any PAE matrices imported to Jalview are saved along side any
+		trees and clustering defined on them in Jalview Projects.</p>
 	<p>
 		<em>Support for visualision and analysis of predicted alignment
 			error matrices was added in Jalview 2.11.3. </em>