X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=help%2Fhelp%2Fhtml%2Ffeatures%2Fstructurechooser.html;h=f91b1dd58cc2038337f5df6b96964f89d50d1780;hb=893f21fe8df6a9d47ced8140e3ba75f03407be00;hp=785c42978170887d5250aaa472945b1b8c421cb5;hpb=44d68d55d9c85bf7b28853feeebc4b901c4a8392;p=jalview.git

diff --git a/help/help/html/features/structurechooser.html b/help/help/html/features/structurechooser.html
index 785c429..f91b1dd 100644
--- a/help/help/html/features/structurechooser.html
+++ b/help/help/html/features/structurechooser.html
@@ -32,8 +32,11 @@
     The Structure Chooser allows you to select
     3D structures to view for the currently selected set of
     sequences. It is opened by selecting the <strong>"3D
-      Structure Data..."</strong> option from the Sequence ID panel's <a
-      href="../menus/popupMenu.html">pop-up menu</a>. The dialog
+      Structure Data..."</strong> option from the Sequence ID panel's
+      <a href="../menus/popupMenu.html">pop-up menu</a>. <br/>
+      <img src="3dstructuredata_popupmenu.png" alt="pop-up menu"/>
+      <br/>
+      The dialog
     provides:
   </p>
   <ul>
@@ -64,11 +67,11 @@
     <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 />
+  </p>
   <p>
     <strong><a name="cachedstructview">Viewing existing
         structures for your sequences</a></strong>
@@ -85,16 +88,17 @@
     <strong>Selection of the best structure for each sequence</strong>
   </p>
   <p>Jalview can automatically select the best structures according
-    to meta-data provided by the PDB. For alignments with no existing
-    structure data, the 'Best Quality' structure for each sequence will
-    by default be selected, but clicking on the drop down menu allows
-    other criteria to be chosen, including Resolution (only defined for
-    X-Ray structures), Highest Protein Chain etc. When 'Invert' is
+    to meta-data provided by the search service. The 'PDBe Best Quality' structure for each sequence will
+    by default be selected when no other structure data is available. If 3D-models from other sources are also available, then 'Best 3D Beacons coverage' will be show.
+    <br/><br/>Clicking on the drop down menu allows
+    other criteria to be chosen. For the PDBe, these include including Resolution (only defined for
+    X-Ray structures), Highest Protein Chain etc. When 3D-Beacons results are available, structures can be selected based on their specific provider, or by their coverage of the aligned sequences.<br/>
+    <br/>When 'Invert' is
     selected, structures are selected in reverse order for the current
     criteria (e.g. worst quality rather than best).</p>
   <p>
 
-    <img src="schooser_main.png" style="width: 499px; height: 437px;">
+    <img src="schooser_main.png" style="width: 820px; height: 458px;">
     <!-- <p><img src="schooser_config.png" style="width: 463px; height: 369px; ">
 	<p><img src="schooser_drop-down.png" style="width: 464px; height: 368px; ">
 	<p><img src="schooser_enter-id.png" style="width: 467px; height: 373px; ">
@@ -103,36 +107,116 @@
     <br>The screenshot above shows the Structure Chooser displayed after
     selecting all the sequences in the Jalview example project. If no
     structures were auto-discovered, options for manually associating
-    PDB records will be shown (see below).<p>
-    <strong>Exploration of meta-data for available structures</strong>
+    PDB records will be shown (see below).
+
+  <p>
+    <strong><a name="3dbeaconssearch">3D-Beacons Network Search</a></strong>
   </p>
-  <p>Information on each structure available is displayed in columns
-    in the dialog box. By default, only the title, resolution and PDB
-    identifier are shown, but many more are provided by the PDBe. To
-    configure which ones are displayed, select the 'Configure Displayed
-    Columns' tab and tick the columns which you want to see.</p>
   <p>
-    <img src="schooser_enter-id.png"
-      style="width: 464px; height: 173px;">
-      <br/>
-    <strong>Manual selection/association of PDB files with
-      Sequences</strong>
+    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>
-  <p>To manually associate PDB files with a sequence, select 'From
-    File', or 'Enter PDB Id' from the drop-down menu:
+
+  <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>From File</strong> - allows you to load a PDB file
-      from the local machine or network and associate it with the
-      selected sequence. PDB files associated in this way will also be
-      saved in the <a href="jalarchive.html">Jalview Archive file</a>.<br></li>
-    <li><strong>Enter PDB Id</strong> - allows you specify a PDB ID
-      for your sequence. The PDB Rest API, provided by EMBL-EBI, is used
-      to validate and fetch structure data.<br></li>
+    <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>
+  <p>Information on each structure available is displayed in columns
+    in the dialog box. By default, only the title, resolution and PDB
+    identifier are shown, but many more are provided by the PDBe.
+    3D-Beacons structures have different data, including a quality score
+    (such as Qmeans_DISCO). To configure which ones are displayed,
+    select the 'Configure Displayed Columns' tab and tick the columns
+    which you want to see.</p>
   <p>
-    <em>The Structure Chooser interface was introduced in Jalview
-      2.9. </em>
+    <img src="schooser_enter-id.png"
+      style="width: 464px; height: 173px;"> <br /> <strong>Manual
+      selection/association of PDB files with Sequences</strong>
   </p>
+	<p>
+		<strong>Manual Association of PDBe accessions with sequences</strong>
+	</p>
+	<p>If for some reason the PDBe and 3D beacons search fail to
+		automatically the PDB structure or model you wish to import, you can
+		select 'Enter PDB Id' from the drop-down menu to manually specify PDB
+		identifiers for one or more selected sequences. The PDB Rest API,
+		provided by EMBL-EBI, is used to validate accessions exist, and fetch
+		structure data.</p>
+	<p>
+		<strong><a name="loadpdbfile">Import structure models
+				and metadata from file</a></strong>
+	</p>
+	<p>
+		Selecting the <strong>From File</strong> option from the drop down
+		menu allows 3D structure data to be imported from your own computer.
+		PDB or mmCIF files associated in this way are also saved in <a
+			href="jalarchive.html">Jalview Projects</a>. <br /> <img
+			src="local-pdb-import.png" style="width: 330px; height: 321px;"><br />
+		The 'From File' dialog provides a drop down menu which allows you to
+		specify how the Temperature Factor metadata for each residue in the 3D
+		structure data file is interpreted:
+	
+	<ul>
+		<li>Default - Jalview will try to automatically determine whether
+			to show as 'Temperature Factor', 'AlphaFold Reliability' or 'Model
+			Quality'</li>
+		<li>PLDDT - Model has PLDDT scores in the temperature factor
+			column.</li>
+	</ul>
+	<p>
+		An additional <em>Predicted Alignment Error</em> file can also be
+		provided when importing 3D structure data. Jalview supports import of
+		PAE Matrices provided as <a href="../io/paematrixformat.html">AlphaFold
+			format JSON files</a> - which are also produced by ColabFold. See <a
+			href="paematrices.html">Working with PAE Matrices</a> for details on
+		what Jalview allows you to do with associated PAE matrix data.
+	</p>
+	<p>
+		<em>The Structure Chooser interface was introduced in Jalview
+			2.9. </em>
+	</p>
 </body>
-</html>
\ No newline at end of file
+</html>