From 69e9cb3c4b9297c19411876e32604822f7f909de Mon Sep 17 00:00:00 2001 From: Jim Procter Date: Mon, 2 Sep 2024 17:34:02 +0100 Subject: [PATCH] JAL-4418 first pass at updating docs with pasimap, ssconservation, etc --- help/help/help.jhm | 3 + help/help/helpTOC.xml | 9 +- help/help/html/calculations/calculations.html | 8 +- help/help/html/calculations/pasimap.html | 161 ++++++++++++++++++++++ help/help/html/calculations/protssconsensus.html | 57 ++++++++ help/help/html/calculations/tree.html | 4 +- help/help/html/menus/alignmentMenu.html | 34 +++-- help/help/html/menus/alwannotation.html | 5 + help/help/html/menus/alwannotationpanel.html | 34 ++++- help/help/html/menus/alwcalculate.html | 16 +-- help/help/html/menus/alwcolour.html | 4 +- help/help/html/menus/alwformat.html | 8 +- help/help/html/menus/desktopMenu.html | 13 +- help/help/html/menus/wsmenu.html | 10 ++ help/markdown/whatsnew/whatsnew-2_11_4_0.md | 22 ++- 15 files changed, 349 insertions(+), 39 deletions(-) create mode 100755 help/help/html/calculations/pasimap.html create mode 100755 help/help/html/calculations/protssconsensus.html diff --git a/help/help/help.jhm b/help/help/help.jhm index 5fb7901..f69547f 100755 --- a/help/help/help.jhm +++ b/help/help/help.jhm @@ -89,6 +89,9 @@ + + + diff --git a/help/help/helpTOC.xml b/help/help/helpTOC.xml index 6d7c948..66d3787 100755 --- a/help/help/helpTOC.xml +++ b/help/help/helpTOC.xml @@ -24,9 +24,9 @@ - - - + + + @@ -111,9 +111,10 @@ - + + diff --git a/help/help/html/calculations/calculations.html b/help/help/html/calculations/calculations.html index c194cd9..c897cdd 100644 --- a/help/help/html/calculations/calculations.html +++ b/help/help/html/calculations/calculations.html @@ -27,16 +27,16 @@ The Alignment Calculations Dialog

Alignment Calculations dialog box - opened via Calculations->Tree or PCA...

The Calculations Dialog (shown above) is opened via - the Calculations→Calculate Tree or PCA... + the Calculations→Calculate Tree, PCA or PaSiMap... menu entry.

- It allows you to select the type of alignment analysis calculation (PCA or Tree), and the + It allows you to select the type of analysis (PCA, Tree, PaSiMap or Pairwise Alignment), and below, the sequence similarity score model that will be used to perform the analysis.

diff --git a/help/help/html/calculations/pasimap.html b/help/help/html/calculations/pasimap.html new file mode 100755 index 0000000..b24377a --- /dev/null +++ b/help/help/html/calculations/pasimap.html @@ -0,0 +1,161 @@ + + + +PaSiMap Sequence Similarity Analysis + + +

+ PaSiMap Sequence Similarity Analysis +

+

+ PaSiMap analyses are performed via the calculations dialog, accessed + by selecting Calculate→Calculate Tree, + PCA or PaSiMap.... +

+

Like the PCA function in Jalview, PaSiMap + analysis creates a spatial representation of + how similar sequences are 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.

+

Similarities in the PaSiMap calculation are calculated from + pairwise alignments of all pairs of input sequences. Since this can be + very time consuming, the maximum number sequences that can be used to + calculate a PaSiMap is limited by available time. Jalview will provide + an estimate of how long the calculation will take, and a 'Cancel' button + allows it to be stopped if desired. +

+

+ About PaSiMap +

+

+ + Principal components analysis is a technique for examining the + structure of complex data sets. The components are a set of + dimensions formed from the measured values in the data set, and the + principal component is the one with the greatest magnitude, or + length. The sets of measurements that differ the most should lie at + either end of this principal axis, and the other axes correspond to + less extreme patterns of variation in the data set.

+ +

+ Calculating PCAs for aligned sequences
Jalview can + perform PCA analysis on both proteins and nucleotide sequence + alignments. In both cases, components are generated by an + eigenvector decomposition of the matrix formed from pairwise similarity + scores between each pair of sequences. The similarity score model is + selected on the calculations dialog, and + may use one of the available score matrices, such as + BLOSUM62, + PAM250, or the simple single + nucleotide substitution matrix, or by sequence percentage identity, + or sequence feature similarity. +

+ +

+ The PCA Viewer +

+

This is an interactive display of the sequences positioned + within the similarity space, as points in a rotateable 3D + scatterplot. The colour of each sequence point is the same as the + sequence group colours, white if no colour has been defined for the + sequence, and grey if the sequence is part of the currently selected + group. The viewer also employs depth cueing, so points appear darker + the farther away they are, and become brighter as they are rotated + towards the front of the view.

+

+ The 3d view can be rotated by dragging the mouse with the left + mouse button pressed, or with the arrow + keys when SHIFT is pressed. The + view can also be zoomed in and out with + the up and down arrow keys (and the roll bar of the + mouse if present). Labels will be shown for each sequence if the + entry in the View menu is checked, and the plot background colour + changed from the View→Background Colour.. dialog box. The File + menu allows the view to be saved (File→Save + submenu) as an EPS or PNG image or printed, and the original + alignment data and matrix resulting from its PCA analysis to be + retrieved. The coordinates for the whole PCA space, or just the + current view may also be exported as CSV files for visualization in + another program or further analysis. +

+

Options for coordinates export are:

+
    +
  • Output Values - complete dump of analysis (TxT* matrix + computed from sum of scores for all pairs of aligned residues from + from i->j and j->i, conditioned matrix to be diagonalised, + tridiagonal form, major eigenvalues found)
    • +
  • Output Points - The eigenvector matrix - rows correspond to + sequences, columns correspond to each dimension in the PCA
    • +
  • Transformed Points - The 3D coordinates for each sequence + as shown in the PCA plot
    • +
+ +

+ A tool tip gives the sequence ID corresponding to a point in the + space, and clicking a point toggles the selection of the + corresponding sequence in the associated alignment window views. + + By default, points are only associated with the alignment view from + which the PCA was calculated, but this may be changed via the View→Associate + Nodes sub-menu. +

+

+ Initially, the display shows the first three components of the + similarity space, but any eigenvector can be used by changing the + selected dimension for the x, y, or z axis through each one's menu + located below the 3d display. The Reset + button will reset axis and rotation settings to their defaults. +

+

+

+ The output of points and transformed point coordinates was + added to the Jalview desktop in v2.7. The Reset button + and Change Parameters menu were added in Jalview 2.8. Support + for PAM250 based PCA was added in Jalview 2.8.1.In Jalview 2.11, support for saving and restoring PCAs in Project files was added, and the Change parameters menu removed. +

+

+ Reproducing PCA calculations performed with older + Jalview releases 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 (pubmed) + 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: + 

+    jalview.analysis.scoremodels.ScoreMatrix.scoreGapAsAny=true
+    jalview.analysis.scoremodels.ScoreModels.instance.BLOSUM62.@matrix[4][1]=3
+
+ 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). +

+ + diff --git a/help/help/html/calculations/protssconsensus.html b/help/help/html/calculations/protssconsensus.html new file mode 100755 index 0000000..e98fb48 --- /dev/null +++ b/help/help/html/calculations/protssconsensus.html @@ -0,0 +1,57 @@ + + + +Protein Secondary Structure Consensus Annotation + + +

+ Protein Secondary Structure Consensus Annotation +

+ +

Since version 2.11.4.0, Jalview can automatically calculate consensus + secondary structure for an alignment of protein sequences where one or + more sequences have secondary structure annotation, in the same way + as is done with the sequence consensus.

+

+ Sources of secondary structure data

+

Sequences can have several different secondary structure + annotations, including those provided by + observed or computationally + determined 3D structures, or predicted by + JPred. Sequence associated + secondary structure annotations can also be imported as + Jalview Annotation + files. Secondary structure annotations for a particular source can + be shown or hidden via Annotations→Show Secondary + Structure menu option in the alignment window.

+

Consensus Secondary Structure

+

The secondary structure consensus can be shown as a histogram, + reflecting the proportion of the most frequent conformation observed + in a column, optionally overlaid with a logo to reflect the + distribution of observed structure. The Alignment window's + Annotations→Autocalculated Annotation includes + options for controlling the appearance of the secondary structure + consensus row, and whether rows should be shown for groups defined + on the alignment. +

+ + diff --git a/help/help/html/calculations/tree.html b/help/help/html/calculations/tree.html index cc5ca2c..a5a4f6c 100755 --- a/help/help/html/calculations/tree.html +++ b/help/help/html/calculations/tree.html @@ -80,9 +80,9 @@ same type will be grouped together in trees computed with this metric. This measure was introduced in Jalview 2.9 -
  • Secondary Structure Similarity
    Trees are +
  • Secondary Structure Similarity
    Trees are generated using a distance matrix, which is constructed from Jaccard - distances that specifically consider the secondary structure features + distances that specifically consider the secondary structure annotation observed at each column of the alignment.
    • -
  • Calculate Tree or PCA ...
    Opens the - calculations dialog for - for calculating trees or - principal component analysis - plots on the alignment or the currently selected - region. +
  • Calculate Tree, PCA or PaSiMap...
    Opens the + calculations dialog which allows calculation of
  • Pairwise Alignments
    Applies Smith and Waterman algorithm to selected sequences. See
    • +
  • Protein Disorder Prediction
    + Allows access to a range of     protein disorder predictors + provided by JABAWS 2.2. +
  • Analysis
    • Multi-Harmony
      Performs diff --git a/help/help/html/menus/alwannotation.html b/help/help/html/menus/alwannotation.html index 8ac116b..7e10457 100755 --- a/help/help/html/menus/alwannotation.html +++ b/help/help/html/menus/alwannotation.html @@ -54,6 +54,9 @@ sequence order). If neither sort order is selected, no sorting is applied, allowing you to make a manual ordering of the annotations.
      • +
    • Show Secondary Structure (since 2.11.4.0) +
      All and None control display of secondary structure annotations on the alignment. + Additional options allow just a specific source of Protein secondary structure to be shown.
    • Autocalculated Annotation
      Settings for the display of autocalculated annotation.
        @@ -74,6 +77,8 @@
      • Show Consensus Logo
         Enable or disable the display of the Consensus Logo above the consensus sequence.
        • +
      • Show SS Consensus Histogram
        +         Enable or disable the display of histogram for Secondary Structure Consensus.
      • Normalise Consensus Logo
        When enabled, scales all logo stacks to the same height, making it easier to compare symbol diversity in diff --git a/help/help/html/menus/alwannotationpanel.html b/help/help/html/menus/alwannotationpanel.html index ff53d0b..12f1242 100755 --- a/help/help/html/menus/alwannotationpanel.html +++ b/help/help/html/menus/alwannotationpanel.html @@ -66,6 +66,20 @@ (numerical or otherwise) at each position in the row. This is useful to export alignment quality measurements for further analysis.
        • +
      • Colour by Annotation
        + Open's the + Colour by Annotation dialog, already configured + for this annotation row. +
        + Colour by Annotation (Per-Sequence) may also be + available for sequence associated annotations, such as secondary structure + or AlphaFold PLDDT score annotation tracks. +
        • +
      • Select/Hide columns by annotation...
        + Open's the + select/hide by annotation dialog, already configured + for this annotation row. +
      The following additional entries are available when the popup menu is opened on a consensus sequence annotation row:
        @@ -92,7 +106,25 @@ format, to allow the consensus sequence to be added to an alignment. Note the copied sequence is not accessible to other programs if Jalview is running as an applet in a web page. -
      • +
    + + Predicted Alignment Error annotation + tracks have the following additional options (see + working with + PAE Matrices for full details): +
      +
    • Show Groups on Matrix
      When ticked, + colour the columns of the matrix by the clusters on it tree.
      • +
    • Cluster Matrix
      Select this to calculate + a tree for the PAE matrix, allowing identification of reliably + positioned regions of structure.
      • +
    • Show Matrix or Show Tree for + Matrix
      Select this to either calculate + or show the tree calculated for the PAE matrix, allowing columns + of the alignment to be clustered in order to identify reliably + positioned regions of structure.
      • +
    +
  • Annotation Popup Menu
    This menu is opened when right-clicking on the selected positions of an annotation. diff --git a/help/help/html/menus/alwcalculate.html b/help/help/html/menus/alwcalculate.html index 3804538..9dbe06a 100755 --- a/help/help/html/menus/alwcalculate.html +++ b/help/help/html/menus/alwcalculate.html @@ -53,18 +53,16 @@ window.
    • -
  • Calculate Tree or PCA ...
    Opens the - calculations dialog for - for calculating trees or - principal component analysis - plots on the alignment or the currently selected - region. -
    -
    • +
  • Calculate Tree, PCA or PaSiMap...
    Opens the + Calculations dialog which allows calculation of +
  • Pairwise Alignments
    Applies Smith and Waterman algorithm to selected sequences. See     pairwise - alignments. + alignments. Also available via the + Calculations dialog.
  • Extract Scores ... (optional)
    This option is only visible if Jalview detects one or more diff --git a/help/help/html/menus/alwcolour.html b/help/help/html/menus/alwcolour.html index 33da749..1257ee1 100755 --- a/help/help/html/menus/alwcolour.html +++ b/help/help/html/menus/alwcolour.html @@ -32,8 +32,8 @@     If this is selected, any changes made to the background colour will be applied to all currently defined groups.
    • -
  • Colour - Text ...
    Opens the Colour Text dialog box to +
  • Text + Colour...
    Opens the foreground text colour dialog box to set a different text colour for light and dark background, and the intensity threshold for transition between them.
  • Colour Scheme options: None, ClustalX, diff --git a/help/help/html/menus/alwformat.html b/help/help/html/menus/alwformat.html index 092e623..4aaa62d 100644 --- a/help/help/html/menus/alwformat.html +++ b/help/help/html/menus/alwformat.html @@ -79,11 +79,15 @@
  • Centre Column Labels
    When this is selected, the text labels within each annotation row will be centred on the column that they are associated with.
    • -
  • Show Unconserved
    +
  • Show Nonconserved
    When this is selected, all consensus sequence symbols will be rendered as a '.', highlighting mutations in highly conserved alignments.
    • - +
  • Copy format from
    +     When available, the submenu allows + the format and layout from one of the listed alignment views + to be copied to the current view. +
    • diff --git a/help/help/html/menus/desktopMenu.html b/help/help/html/menus/desktopMenu.html index 49fbec3..7068bad 100755 --- a/help/help/html/menus/desktopMenu.html +++ b/help/help/html/menus/desktopMenu.html @@ -54,16 +54,19 @@
  • Load Project
    Loads Jalview archives only.
    • -
  • Quit
    Close Jalview. -
    Note - any annotation you have +
  • Quit
    Close Jalview. +
    Under the Jalview dropdown on Macs +
    + Jalview will try to check if you have any unsaved + data and warn you, but please remember that any annotation you have made on alignments will be lost unless you Save your work before quitting. -
    • +
  • Tools
    • Preferences
      -       Change the default visual settings for opening new +       Under the Jalview menu on OSX
      Change the default visual settings for opening new alignment windows.
    • Show Memory Usage
       When ticked, the currently available memory will be displayed in @@ -86,7 +89,7 @@ the Groovy Console for interactive scripting.
      • - + Enable Experimental Features Enable or disable features still under development in Jalview's user interface. This setting is remembered in your preferences.
  • Help diff --git a/help/help/html/menus/wsmenu.html b/help/help/html/menus/wsmenu.html index b8b357e..7c99081 100755 --- a/help/help/html/menus/wsmenu.html +++ b/help/help/html/menus/wsmenu.html @@ -64,6 +64,7 @@ information.
  • Secondary Structure Prediction +
    Provides access to protein and RNA secondary structure prediction tools.
    • JPred Secondary Structure Prediction
      Secondary structure prediction by network consensus. @@ -88,7 +89,16 @@
    +
    • RNAAliFold Prediction
    Submit the + alignment to the + JABAWS RNAAliFold + service for consensus RNA base pair prediction. The + prediction will be updated if the alignment is edited. +
  • Protein Disorder Prediction
    + Allows access to a range of protein disorder predictors + provided by JABAWS 2.2. +
  • Analysis
    • Multi-Harmony
      Performs diff --git a/help/markdown/whatsnew/whatsnew-2_11_4_0.md b/help/markdown/whatsnew/whatsnew-2_11_4_0.md index b04074c..7643afa 100644 --- a/help/markdown/whatsnew/whatsnew-2_11_4_0.md +++ b/help/markdown/whatsnew/whatsnew-2_11_4_0.md @@ -1,5 +1,25 @@ The 2.11.4 series is the fourth in the minor-release trilogy planned for Jalview's 2.11 series. -This release adds new capabilities for consensus and clustering of protein secondary structure, along with enhanced control of the display and analysis of secondary structure from different sources of 3D structure and prediction, and also features a new implementation of the PASiMap method for sequence clustering ([Su et al. 2022 Comp. Struc. Biotech.](https://doi.org/10.1016/j.csbj.2022.09.034)). +This release adds new capabilities for visualisation and clustering of protein secondary structure annotations, +along with enhanced control of the display and analysis of secondary structure from different +sources of 3D structure and prediction. +The Calculations dialog has also been revised to accommodate a new implementation of +the spatial clustering method PASiMap +([Su et al. 2022 Comp. Struc. Biotech.](https://doi.org/10.1016/j.csbj.2022.09.034)) +which was added to Jalview by Thomas Morrell and Jen Christianson. +Jalview 2.11.4 also has new installers and command line scripts that bring several +minor improvements, and also makes it easier for IT admins to manage Jalview installations +on computers used by many different people. New installations of Jalview will by default +store updates in user's home directories, Automatic updates can also be disabled, and +updates instead carried out using a new jalview_admin command line tool. + + +## Experimental features + +This release includes experimental support (enabled in the Tools menu) for +handling drag'n'drop of alignment, tree, annotations and feature file(s) +onto the Jalview Desktop. They can also be dragged onto the Jalview icon. + + \ No newline at end of file -- 1.7.10.2