JAL-2738 copy to spikes/mungo
[jalview.git] / help / html / calculations / pca.html
index c38d9ac..0104078 100755 (executable)
   <p>
     <strong>Principal Component Analysis</strong>
   </p>
+  <p>
+    A principal component analysis can be performed via the <a
+      href="calculations.html">calculations dialog</a> which is accessed
+    by selecting <strong>Calculate&#8594;Calculate Tree or
+      PCA...</strong>.
+  </p>
   <p>This calculation creates a spatial representation of the
     similarities within a selected group, or all of the sequences in an
     alignment. After the calculation finishes, a 3D viewer displays the
     set of sequences as points in 'similarity space', and similar
     sequences tend to lie near each other in the space.</p>
   <p>
-    <em>Caveats</em><br />The calculation is computationally expensive,
-    and may fail for very large sets of sequences - usually because the
-    JVM has run out of memory. A future release of Jalview will be able
-    to avoid this by executing the calculation via a web service.
+    <em>Caveats</em><br />The calculation can be computationally
+    expensive, and may fail for very large sets of sequences - usually
+    because the JVM has run out of memory. However, the PCA
+    implementation in Jalview 2.10.2 employs more memory efficient
+    matrix storage structures, allowing larger PCAs to be performed.
   </p>
 
   <p>
     calculation are given in the <strong><em>Change
         Parameters</em></strong> menu.
   </p>
-  <p>
-    <em>PCA Calculation modes</em><br /> The default Jalview
-    calculation mode (indicated when <em><strong>Jalview
-        PCA Calculation</strong></em> is ticked in the <strong><em>Change
-        Parameters</em></strong> menu) is to perform a PCA on a matrix where elements
-    in the upper diagonal give the sum of scores for mutating in one
-    direction, and the lower diagonal is the sum of scores for mutating
-    in the other. For protein substitution models like BLOSUM62, this
-    gives an asymmetric matrix, and a different PCA to a matrix produced
-    with the method described in the paper by G. Casari, C. Sander and
-    A. Valencia. Structural Biology volume 2, no. 2, February 1995 (<a
-      href="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?cmd=Retrieve&db=pubmed&dopt=Abstract&list_uids=7749921">pubmed</a>)
-    and implemented at the SeqSpace server at the EBI. This method
-    preconditions the matrix by multiplying it with its transpose, and
-    can be employed in the PCA viewer by unchecking the <strong><em>Jalview
-        PCA Calculation</em></strong> option in the <strong><em>Change
-        Parameters</em></strong> menu.
-  </p>
   <img src="pcaviewer.gif">
   <p>
     <strong>The PCA Viewer</strong>
@@ -141,5 +130,26 @@ left-clicking and dragging the mouse over the display. -->
       added to the Jalview desktop in v2.7.</em> <em>The Reset button
       and Change Parameters menu were added in Jalview 2.8.</em> <em>Support
       for PAM250 based PCA was added in Jalview 2.8.1.</em>
+  </p>
+  <p>
+    <strong>Reproducing PCA calculations performed with older
+      Jalview releases</strong> Jalview 2.10.2 included a revised PCA
+    implementation which treated Gaps and non-standard residues in the
+    same way as a matrix produced with the method described in the paper
+    by G. Casari, C. Sander and A. Valencia. Structural Biology volume
+    2, no. 2, February 1995 (<a
+      href="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?cmd=Retrieve&db=pubmed&dopt=Abstract&list_uids=7749921">pubmed</a>)
+    and implemented at the SeqSpace server at the EBI. To reproduce
+    calculations performed with earlier Jalview releases it is necessary
+    to execute the following Groovy script:
+  <pre>
+    jalview.analysis.scoremodels.ScoreMatrix.scoreGapAsAny=true
+    jalview.analysis.scoremodels.ScoreModels.instance.BLOSUM62.@matrix[4][1]=3
+    </pre>
+  This script enables the legacy PCA mode where gaps were treated as
+  'X', and to modify the BLOSUM62 matrix so it is asymmetric for
+  mutations between C to R (this was a typo in the original Jalview
+  BLOSUM62 matrix which was fixed in 2.10.2).
+  </p>
 </body>
 </html>