JAL-3224 JAL-3225 Fixed help image mangling, moved help to help/help and added this...
[jalview.git] / help / help / html / features / structurechooser.html
diff --git a/help/help/html/features/structurechooser.html b/help/help/html/features/structurechooser.html
new file mode 100644 (file)
index 0000000..785c429
--- /dev/null
@@ -0,0 +1,138 @@
+<html>
+<!--
+ * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
+ * Copyright (C) $$Year-Rel$$ The Jalview Authors
+ * 
+ * This file is part of Jalview.
+ * 
+ * Jalview is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License 
+ * as published by the Free Software Foundation, either version 3
+ * of the License, or (at your option) any later version.
+ *  
+ * Jalview is distributed in the hope that it will be useful, but 
+ * WITHOUT ANY WARRANTY; without even the implied warranty 
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
+ * PURPOSE.  See the GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
+ * The Jalview Authors are detailed in the 'AUTHORS' file.
+ -->
+<head>
+<title>Structure Chooser</title>
+</head>
+
+<body>
+  <p>
+    <strong>Structure Chooser Dialog Box</strong>
+  </p>
+
+  <p>
+    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
+    provides:
+  </p>
+  <ul>
+    <li>Automatic discovery, retrieval and association of PDB
+      entries for sequences</li>
+    <li>Exploration of meta-data for available 3D structures</li>
+    <li>Automatic selection of the 'best structure' to display for
+      each sequence</li>
+    <li>Manual association of PDB entries by entering a PDB Id</li>
+    <li>Association of structure data from a local file (in mmCIF
+      or PDB format)</li>
+  </ul>
+  <p>
+    <strong>Selecting and Viewing Structures</strong>
+  </p>
+  <p>The drop-down menu offers different options for structure
+    discovery; the 'Cached' view is shown automatically if existing
+    structure data has been imported for the selected sequences, and if
+    none is available, the import PDB/mmCIF file options are shown.</p>
+  <p>
+    Once one or more structures have been selected, pressing the <strong>View</strong>
+    or <strong>Add</strong> button will import them <a
+      href="viewingpdbs.html#afterviewbutton">a new or existing
+      structure view</a>. When multiple views are available, use the
+    drop-down menu to pick the target viewer for the structures.
+  </p>
+  <p>
+    <strong>Automated discovery of structure data</strong>
+  </p>
+  <p>
+    After selecting "3D Structure Data ..", Jalview queries 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>
+    <strong><a name="cachedstructview">Viewing existing
+        structures for your sequences</a></strong>
+  </p>
+  <p>
+    If you have already loaded 3D structure data for the selected
+    sequences, the structure chooser will first open with the <strong>Cached
+      Structures View</strong>. This view shows associations between each
+    sequence, and chains for 3D structure files already in memory. If
+    you want to download additional structures, select one of the other
+    options from the drop down menu.
+  </p>
+  <p>
+    <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
+    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;">
+    <!-- <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; ">
+       <p><img src="schooser_from-file.png" style="width: 468px; height: 370px; ">
+       <p><img src="schooser_cached.png"> -->
+    <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>
+  </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>
+  </p>
+  <p>To manually associate PDB files with a sequence, select 'From
+    File', or 'Enter PDB Id' from the drop-down menu:
+  <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>
+  </ul>
+
+  <p>
+    <em>The Structure Chooser interface was introduced in Jalview
+      2.9. </em>
+  </p>
+</body>
+</html>
\ No newline at end of file