JAL-3746 release notes JAL-3391 JAL-3829 improved 3dbeacons docs, including documenti...

[jalview.git] / help / help / html / features / structurechooser.html

diff --git a/help/help/html/features/structurechooser.html b/help/help/html/features/structurechooser.html
index 512b68f..2c77049 100644 (file)
--- a/help/help/html/features/structurechooser.html
+++ b/help/help/html/features/structurechooser.html
@@ -67,13 +67,10 @@
     <strong>Automated discovery of structure data</strong>
   </p>
   <p>
-    After selecting "3D Structure Data ..", Jalview queries the PDB via
+    After selecting "3D Structure Data ..", Jalview queries its available structure data providers. When Uniprot identifiers are available, it queries the <a href="#3dbeaconssearch">3D-Beacons network</a> (since Jalview 2.11.2), otherwise it searches the PDB via
     the PDBe SOLR Rest API provided by EMBL-EBI to discover PDB IDs
     associated with the sequence. It does this based on the sequence's
     ID string, and any other associated database IDs. <br />
-    <br />
-    Since Jalview 2.11.2, you can also <a href="#3dbeaconssearch">initiate a search
-    of the 3D-Beacons Network</a>.
   </p>
   <p>
     <strong><a name="cachedstructview">Viewing existing
@@ -116,29 +113,54 @@
     <strong><a name="3dbeaconssearch">3D-Beacons Network Search</a></strong>
   </p>
   <p>
-    To initiate a search of the 3D-Beacons Network&mdash;which searches
-    across experimentally determined and predicted structure models from
-    several resources including PDBe, AlphaFold DB, SWISS-MODEL, PED, SASDB, Genome3D and
-    PDBe-KB&mdash;click on the <strong>3D-Beacons Search</strong> button at the top of the
-    Structure Chooser window.
-    <br/>
-    <img src="3dbeacons_button.png"/>
-    <br/>
-    The 3D-Beacons Network search requires UniProt references and Jalview will ask
-    to attempt to fetch these references for the selected sequences.
-    If no UniProt references are found, Jalview will still search the PDB for potential matches for the sequence's ID string.
-    <br/>
-    <img src="3dbeacons_structurechooser.png"/>
-    <br/>
-    Structures found through the 3D-Beacons network can be filtered using the drop-down filter at the top of the Structure Chooser window. 
-    You can view information about each related model, such as the resource providing
-    each model, in the displayed columns, and models can be reordered by clicking on
-    column headings.
-    <br/>
-    Select and view the structures in the usual way using the <a href="viewingpdbs.html#afterviewbutton">open structure options</a> at
-    the bottom of the Structure Chooser window.
+    3D beacons searches across experimentally determined and predicted
+    structure models from several resources including PDBe, AlphaFold
+    DB, SWISS-MODEL, PED, SASDB, Genome3D and PDBe-KB.<br /> If your
+    sequences have Uniprot identifiers, Jalview will query the
+    3D-Beacons network to discover relevant 3D structures and models.
+    When no uniprot identifiers are available you can initiate Uniprot
+    identifier discovery and a subsequent search of the 3D-Beacons
+    Network by pressing the <strong>3D-Beacons Search</strong> button at
+    the top of the Structure Chooser window. <br /> <img
+      src="3dbeacons_button.png" /> <br />When the search button is
+    pressed, Jalview will ask to attempt to fetch any additional uniprot
+    references for the selected sequences - we do this because fetching
+    large numbers of Uniprot references can take some time. For
+    sequences without Uniprot accessions, Jalview will still search the
+    PDB for potential matches for the sequence's ID string. <br /> 
+       <br /> <img src="3dbeacons_structurechooser.png" /> <br /> <br />
+    3D Beacons provides some additional information for each model,
+    including what positions on the Uniprot sequence have structure
+    data. These metadata (described below) are shown in the columns of
+    the table and used to provide additional filter options.<br />Use
+    the drop-down filter menu and table to browse and select structures,
+    and finally view them using the
+    <a href="viewingpdbs.html#afterviewbutton">open structure
+      options</a> at the bottom of the Structure Chooser window.
   </p>
 
+  <strong>Options for selecting structures from 3D Beacons</strong><br />
+    Structures found through the 3D-Beacons network can be filtered
+    using the drop-down filter at the top of the Structure Chooser
+    window. The options usually available are:
+  
+  <ul>
+    <li><strong>Best 3D Beacons Coverage</strong> - selects one
+      structure for each sequence from available structures those that
+      are the highest quality (ie experimental structures, or highly
+      accurate predictions) and cover the most number of residues in the
+      alignment.</li>
+    <li><strong>3DB Provider - ...</strong> selects the best
+      quality structure for each sequence provided by a specific source
+      (e.g. PDB, EBI-AlphaFold, SwissModel).</li>
+    <li><strong>Multiple 3D-Beacons Coverage</strong> - employs a
+      heuristic to identify structures providing the best quality
+      structure data for every position in each sequence.<br /> <em>Note:
+        structure superpositions may fail when this option is used
+        because the best covering structure set for a sequence often do
+        not overlap.</em></li>
+  </ul>
+ 
   <p>
     <strong>Exploration of meta-data for available structures</strong>
   </p>