help/help/html/features/structurechooser.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3
  11  * of the License, or (at your option) any later version.
  12  *
  13  * Jalview is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty
  15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  16  * PURPOSE.  See the GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  20  * The Jalview Authors are detailed in the 'AUTHORS' file.
  21  -->
  22 <head>
  23 <title>Structure Chooser</title>
  24 </head>
  25
  26 <body>
  27   <p>
  28     <strong>Structure Chooser Dialog Box</strong>
  29   </p>
  30
  31   <p>
  32     The Structure Chooser allows you to select
  33     3D structures to view for the currently selected set of
  34     sequences. It is opened by selecting the <strong>"3D
  35       Structure Data..."</strong> option from the Sequence ID panel's
  36       <a href="../menus/popupMenu.html">pop-up menu</a>. <br/>
  37       <img src="3dstructuredata_popupmenu.png" alt="pop-up menu"/>
  38       <br/>
  39       The dialog
  40     provides:
  41   </p>
  42   <ul>
  43     <li>Automatic discovery, retrieval and association of PDB
  44       entries for sequences</li>
  45     <li>Exploration of meta-data for available 3D structures</li>
  46     <li>Automatic selection of the 'best structure' to display for
  47       each sequence</li>
  48     <li>Manual association of PDB entries by entering a PDB Id</li>
  49     <li>Association of structure data from a local file (in mmCIF
  50       or PDB format)</li>
  51   </ul>
  52   <p>
  53     <strong>Selecting and Viewing Structures</strong>
  54   </p>
  55   <p>The drop-down menu offers different options for structure
  56     discovery; the 'Cached' view is shown automatically if existing
  57     structure data has been imported for the selected sequences, and if
  58     none is available, the import PDB/mmCIF file options are shown.</p>
  59   <p>
  60     Once one or more structures have been selected, pressing the <strong>View</strong>
  61     or <strong>Add</strong> button will import them <a
  62       href="viewingpdbs.html#afterviewbutton">a new or existing
  63       structure view</a>. When multiple views are available, use the
  64     drop-down menu to pick the target viewer for the structures.
  65   </p>
  66   <p>
  67     <strong>Automated discovery of structure data</strong>
  68   </p>
  69   <p>
  70     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
  71     the PDBe SOLR Rest API provided by EMBL-EBI to discover PDB IDs
  72     associated with the sequence. It does this based on the sequence's
  73     ID string, and any other associated database IDs. <br />
  74   </p>
  75   <p>
  76     <strong><a name="cachedstructview">Viewing existing
  77         structures for your sequences</a></strong>
  78   </p>
  79   <p>
  80     If you have already loaded 3D structure data for the selected
  81     sequences, the structure chooser will first open with the <strong>Cached
  82       Structures View</strong>. This view shows associations between each
  83     sequence, and chains for 3D structure files already in memory. If
  84     you want to download additional structures, select one of the other
  85     options from the drop down menu.
  86   </p>
  87   <p>
  88     <strong>Selection of the best structure for each sequence</strong>
  89   </p>
  90   <p>Jalview can automatically select the best structures according
  91     to meta-data provided by the search service. The 'PDBe Best Quality' structure for each sequence will
  92     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.
  93     <br/><br/>Clicking on the drop down menu allows
  94     other criteria to be chosen. For the PDBe, these include including Resolution (only defined for
  95     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/>
  96     <br/>When 'Invert' is
  97     selected, structures are selected in reverse order for the current
  98     criteria (e.g. worst quality rather than best).</p>
  99   <p>
 100
 101     <img src="schooser_main.png" style="width: 820px; height: 458px;">
 102     <!-- <p><img src="schooser_config.png" style="width: 463px; height: 369px; ">
 103         <p><img src="schooser_drop-down.png" style="width: 464px; height: 368px; ">
 104         <p><img src="schooser_enter-id.png" style="width: 467px; height: 373px; ">
 105         <p><img src="schooser_from-file.png" style="width: 468px; height: 370px; ">
 106         <p><img src="schooser_cached.png"> -->
 107     <br>The screenshot above shows the Structure Chooser displayed after
 108     selecting all the sequences in the Jalview example project. If no
 109     structures were auto-discovered, options for manually associating
 110     PDB records will be shown (see below).
 111
 112   <p>
 113     <strong><a name="3dbeaconssearch">3D-Beacons Network Search</a></strong>
 114   </p>
 115   <p>
 116     3D beacons searches across experimentally determined and predicted
 117     structure models from several resources including PDBe, AlphaFold
 118     DB, SWISS-MODEL, PED, SASDB, Genome3D and PDBe-KB.<br /> If your
 119     sequences have Uniprot identifiers, Jalview will query the
 120     3D-Beacons network to discover relevant 3D structures and models.
 121     When no uniprot identifiers are available you can initiate Uniprot
 122     identifier discovery and a subsequent search of the 3D-Beacons
 123     Network by pressing the <strong>3D-Beacons Search</strong> button at
 124     the top of the Structure Chooser window. <br /> <img
 125       src="3dbeacons_button.png" /> <br />When the search button is
 126     pressed, Jalview will ask to attempt to fetch any additional uniprot
 127     references for the selected sequences - we do this because fetching
 128     large numbers of Uniprot references can take some time. For
 129     sequences without Uniprot accessions, Jalview will still search the
 130     PDB for potential matches for the sequence's ID string. <br />
 131        <br /> <img src="3dbeacons_structurechooser.png" /> <br /> <br />
 132     3D Beacons provides some additional information for each model,
 133     including what positions on the Uniprot sequence have structure
 134     data. These metadata (described below) are shown in the columns of
 135     the table and used to provide additional filter options.<br />Use
 136     the drop-down filter menu and table to browse and select structures,
 137     and finally view them using the
 138     <a href="viewingpdbs.html#afterviewbutton">open structure
 139       options</a> at the bottom of the Structure Chooser window.
 140   </p>
 141
 142   <strong>Options for selecting structures from 3D Beacons</strong><br />
 143     Structures found through the 3D-Beacons network can be filtered
 144     using the drop-down filter at the top of the Structure Chooser
 145     window. The options usually available are:
 146
 147   <ul>
 148     <li><strong>Best 3D Beacons Coverage</strong> - selects one
 149       structure for each sequence from available structures those that
 150       are the highest quality (ie experimental structures, or highly
 151       accurate predictions) and cover the most number of residues in the
 152       alignment.</li>
 153     <li><strong>3DB Provider - ...</strong> selects the best
 154       quality structure for each sequence provided by a specific source
 155       (e.g. PDB, EBI-AlphaFold, SwissModel).</li>
 156     <li><strong>Multiple 3D-Beacons Coverage</strong> - employs a
 157       heuristic to identify structures providing the best quality
 158       structure data for every position in each sequence.<br /> <em>Note:
 159         structure superpositions may fail when this option is used
 160         because the best covering structure set for a sequence often do
 161         not overlap.</em></li>
 162   </ul>
 163
 164   <p>
 165     <strong>Exploration of meta-data for available structures</strong>
 166   </p>
 167   <p>Information on each structure available is displayed in columns
 168     in the dialog box. By default, only the title, resolution and PDB
 169     identifier are shown, but many more are provided by the PDBe.
 170     3D-Beacons structures have different data, including a quality score
 171     (such as Qmeans_DISCO). To configure which ones are displayed,
 172     select the 'Configure Displayed Columns' tab and tick the columns
 173     which you want to see.</p>
 174   <p>
 175     <img src="schooser_enter-id.png"
 176       style="width: 464px; height: 173px;"> <br /> <strong>Manual
 177       selection/association of PDB files with Sequences</strong>
 178   </p>
 179         <p>
 180                 <strong>Manual Association of PDBe accessions with sequences</strong>
 181         </p>
 182         <p>If for some reason the PDBe and 3D beacons search fail to
 183                 automatically the PDB structure or model you wish to import, you can
 184                 select 'Enter PDB Id' from the drop-down menu to manually specify PDB
 185                 identifiers for one or more selected sequences. The PDB Rest API,
 186                 provided by EMBL-EBI, is used to validate accessions exist, and fetch
 187                 structure data.</p>
 188         <p>
 189                 <strong><a name="loadpdbfromfile">Import structure models
 190                                 and metadata from file</a></strong>
 191         </p>
 192         <p>
 193                 Selecting the <strong>From File</strong> option from the drop down
 194                 menu allows 3D structure data to be imported from your own computer.
 195                 PDB or mmCIF files associated in this way are also saved in <a
 196                         href="jalarchive.html">Jalview Projects</a>. <br /> <img
 197                         src="local-pdb-import.png" style="width: 496px; height: 482px;"><br />
 198                 The 'From File' dialog provides a drop down menu which allows you to
 199                 specify how the Temperature Factor metadata for each residue in the 3D
 200                 structure data file is interpreted:
 201
 202         <ul>
 203                 <li>Default - Jalview will try to automatically determine whether
 204                         to show as 'Temperature Factor', 'AlphaFold Reliability' or 'Model
 205                         Quality'</li>
 206                 <li>PLDDT - Model has PLDDT scores in the temperature factor
 207                         column.</li>
 208         </ul>
 209         <p>
 210                 An additional <em>Predicted Alignment Error</em> file can also be
 211                 provided when importing 3D structure data. Jalview supports import of
 212                 PAE Matrices provided as <a href="../io/paematrixformat.html">AlphaFold
 213                         format JSON files</a> - which are also produced by ColabFold. See <a
 214                         href="paematrices.html">Working with PAE Matrices</a> for details on
 215                 what Jalview allows you to do with associated PAE matrix data.
 216         </p>
 217         <p>
 218                 <em>The Structure Chooser interface was introduced in Jalview
 219                         2.9. </em>
 220         </p>
 221 </body>
 222 </html>