From: jprocter <jprocter@dundee.ac.uk>
Date: Mon, 2 Oct 2023 19:33:59 +0000 (+0100)
Subject: JAL-4090 more JAL-3858 docs
X-Git-Tag: Release_2_11_3_0~5^2^2~5
X-Git-Url: http://source.jalview.org/gitweb/?p=jalview.git;a=commitdiff_plain;h=000cc06fab20d9dd0a5163f8b1d388933eae7218

JAL-4090 more JAL-3858 docs
---

diff --git a/help/help/html/features/annotation.html b/help/help/html/features/annotation.html
index b63d20b..76b23eb 100755
--- a/help/help/html/features/annotation.html
+++ b/help/help/html/features/annotation.html
@@ -29,7 +29,7 @@
 
   <p>
     In addition to the definition of groups and sequence features,
-    Jalview can display symbols and graphs under the columns of an
+    Jalview can display symbols, line graphs, histograms and heatmaps under the columns of an
     alignment. These annotation tracks are displayed in the annotation
     area below the alignment. The annotation area's visibility is
     controlled with the <strong>View&#8594;Show Annotation</strong>
@@ -40,15 +40,14 @@
   <ul>
     <li><a name="seqannots"><strong>Sequence
           associated annotation.</strong></a><br />Data displayed on sequence
-      annotation rows are associated with the positions of a sequence.
+      associated annotation rows are associated with the positions of a sequence.
       Often this is 'Reference annotation' such as secondary structure
       information derived from 3D structure data, or from the results of
       sequence based prediction of <a href="../webServices/jnet.html">secondary
         structure</a> and <a href="../webServices/proteinDisorder.html">disorder</a>.
-      If reference annotation is available for a the currently selected
-      sequences, it can be shown by selecting the <strong>Add
+      If reference annotations are available for a particular sequence or the current selections, they can be shown by selecting the <strong>Add
         Reference Annotation</strong> option in the sequence or selection popup
-      menu.</li>
+      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>
     <li><strong>Group associated annotation.</strong><br />Data can
       be associated with groups defined on the alignment. If sequence
       groups are defined, <a href="../calculations/conservation.html">Conservation</a>
@@ -86,9 +85,11 @@
       alignment</a>. Annotations can also be used to <a
       href="../features/columnFilterByAnnotation.html">select or
       hide columns</a> via the dialog opened from the <strong>Selection</strong>
-    menu.
+    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.
   </p>
   <p>
+    <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>
+  <p>
     <strong>Sequence Highlighting and Selection from Annotation</strong>
   </p>
   <p>
@@ -101,6 +102,15 @@
       (Mac CMD) double-click</strong> will toggle inclusion of associated
     sequences in the selection.
   <p>
+    <strong>Selecting, analysing and exploring heatmap annotation</strong>
+  </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.
+    <ul>
+      <li>Rows and columns in the heatmap corresponding to currently selected columns in the alignment are shown as red horizontal and vertical bands.</li>
+      <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>
+      <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>
+    </ul>
+    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.
+  <p>
     <strong>Interactive Alignment Annotation</strong>
   </p>
   <p>
@@ -144,6 +154,13 @@
         in 2.5)</em><br> <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>
+    <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
+    <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
+    <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
+    <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
+    <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
+    <li><strong></strong><em>(introduced in 2.11.3)</em><br/><em></em></li>
+    
   </ul>
   <p>
     <strong>Editing labels and secondary structure annotation
diff --git a/help/help/html/features/paematrices.html b/help/help/html/features/paematrices.html
index efadf91..8d72573 100644
--- a/help/help/html/features/paematrices.html
+++ b/help/help/html/features/paematrices.html
@@ -80,8 +80,23 @@
 		Reference Annotation' entry in the Sequence ID submenu, or select all
 		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>
+	  associated PAE data appears.</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>Moving the mouse over any part of the heatmap highlights the corresponding regions of the 3D structure the PAE data is associated with, in addition to a tooltip being displayed giving information on the range of values under the mouse.</li>
+	      <li>Clicking to select positions in the matrix results in columns of the alignment corresponding to the row and columns selected in the matrix.</li>
+	</ul>
 	<p></p>
+	    <p><strong><a name="clustering">Clustering PAE Matrices</a></strong></p>
+	    <p>
+	      
+	</p>
 	<p>
 		<em>Support for visualision and analysis of predicted alignment
 			error matrices was added in Jalview 2.11.3. </em>
diff --git a/help/help/html/menus/alwannotationpanel.html b/help/help/html/menus/alwannotationpanel.html
index cd09693..ff53d0b 100755
--- a/help/help/html/menus/alwannotationpanel.html
+++ b/help/help/html/menus/alwannotationpanel.html
@@ -86,6 +86,7 @@
             highly variable regions.</em></li>
 
         <li>
+	</li>
         <li><strong>Copy Consensus Sequence</strong><br>
           Copies the consensus sequence to the clipboard in Fasta
           format, to allow the consensus sequence to be added to an