3 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4 * Copyright (C) $$Year-Rel$$ The Jalview Authors
6 * This file is part of Jalview.
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.
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.
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.
23 <title>Structure Chooser</title>
28 <strong>Structure Chooser Dialog Box</strong>
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"/>
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
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
53 <strong>Selecting and Viewing Structures</strong>
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>
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.
67 <strong>Automated discovery of structure data</strong>
70 After selecting "3D Structure Data ..", Jalview queries 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 />
75 Since Jalview 2.11.2, you can also <a href="#3dbeaconssearch">initiate a search
76 of the 3D-Beacons Network</a>.
79 <strong><a name="cachedstructview">Viewing existing
80 structures for your sequences</a></strong>
83 If you have already loaded 3D structure data for the selected
84 sequences, the structure chooser will first open with the <strong>Cached
85 Structures View</strong>. This view shows associations between each
86 sequence, and chains for 3D structure files already in memory. If
87 you want to download additional structures, select one of the other
88 options from the drop down menu.
91 <strong>Selection of the best structure for each sequence</strong>
93 <p>Jalview can automatically select the best structures according
94 to meta-data provided by the search service. The 'PDBe Best Quality' structure for each sequence will
95 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.
96 <br/><br/>Clicking on the drop down menu allows
97 other criteria to be chosen. For the PDBe, these include including Resolution (only defined for
98 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/>
100 selected, structures are selected in reverse order for the current
101 criteria (e.g. worst quality rather than best).</p>
104 <img src="schooser_main.png" style="width: 820px; height: 458px;">
105 <!-- <p><img src="schooser_config.png" style="width: 463px; height: 369px; ">
106 <p><img src="schooser_drop-down.png" style="width: 464px; height: 368px; ">
107 <p><img src="schooser_enter-id.png" style="width: 467px; height: 373px; ">
108 <p><img src="schooser_from-file.png" style="width: 468px; height: 370px; ">
109 <p><img src="schooser_cached.png"> -->
110 <br>The screenshot above shows the Structure Chooser displayed after
111 selecting all the sequences in the Jalview example project. If no
112 structures were auto-discovered, options for manually associating
113 PDB records will be shown (see below).
116 <strong><a name="3dbeaconssearch">3D-Beacons Network Search</a></strong>
119 To initiate a search of the 3D-Beacons Network—which searches
120 across experimentally determined and predicted structure models from
121 several resources including PDBe, AlphaFold DB, SWISS-MODEL, PED, SASDB, Genome3D and
122 PDBe-KB—click on the <strong>3D-Beacons Search</strong> button at the top of the
123 Structure Chooser window.
125 <img src="3dbeacons_button.png"/>
127 The 3D-Beacons Network search requires UniProt references and Jalview will ask
128 to attempt to fetch these references for the selected sequences.
129 If no UniProt references are found, Jalview will still search the PDB for potential matches for the sequence's ID string.
131 <img src="3dbeacons_structurechooser.png"/>
133 Structures found through the 3D-Beacons network can be filtered using the drop-down filter at the top of the Structure Chooser window.
134 You can view information about each related model, such as the resource providing
135 each model, in the displayed columns, and models can be reordered by clicking on
138 Select and view the structures in the usual way using the <a href="viewingpdbs.html#afterviewbutton">open structure options</a> at
139 the bottom of the Structure Chooser window.
143 <strong>Exploration of meta-data for available structures</strong>
145 <p>Information on each structure available is displayed in columns
146 in the dialog box. By default, only the title, resolution and PDB
147 identifier are shown, but many more are provided by the PDBe.
148 3D-Beacons structures have different data, including a quality score
149 (such as Qmeans_DISCO). To configure which ones are displayed,
150 select the 'Configure Displayed Columns' tab and tick the columns
151 which you want to see.</p>
153 <img src="schooser_enter-id.png"
154 style="width: 464px; height: 173px;"> <br /> <strong>Manual
155 selection/association of PDB files with Sequences</strong>
157 <p>To manually associate PDB files with a sequence, select 'From
158 File', or 'Enter PDB Id' from the drop-down menu:
160 <li><strong>From File</strong> - allows you to load a PDB file
161 from the local machine or network and associate it with the
162 selected sequence. PDB files associated in this way will also be
163 saved in the <a href="jalarchive.html">Jalview Archive file</a>.<br></li>
164 <li><strong>Enter PDB Id</strong> - allows you specify a PDB ID
165 for your sequence. The PDB Rest API, provided by EMBL-EBI, is used
166 to validate and fetch structure data.<br></li>
170 <em>The Structure Chooser interface was introduced in Jalview