<html>
<!--
- * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
- * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, G Barton, M Clamp, S Searle
+ * 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.
+ * 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/>.
--->
+ * 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>PDB Viewing</title>
</head>
<body>
-<p><strong>Viewing PDB Structures</strong></p>
+ <p>
+ <strong>Discovering and Viewing PDB Structures</strong>
+ </p>
+ Jalview can be used to explore the 3D structures of sequences in an
+ alignment by following the steps below:
+ <ol>
+ <li>Select the <strong>"3D Structure Data..."</strong> option
+ from a sequence's <a href="../menus/popupMenu.html">pop-up
+ menu</a> to open the <a href="structurechooser.html">Structure
+ Chooser</a> dialog box.
+ <ul>
+ <li>If one or more structures exists for the given
+ sequence, the <a href="structurechooser.html">Structure
+ Chooser</a> dialog will open with them listed in the results
+ pane.
+ </li>
+ <li>However, if no structure was found, the <a
+ href="structurechooser.html">Structure Chooser</a> interface
+ will present options for manual association of PDB structures.
+ </li>
+ </ul>
+ </li>
+ <li><strong>Selecting Structures</strong><br />You can select
+ the structures that you want to open and view by selecting them
+ with the mouse and keyboard.<br />By default, if structures were
+ discovered, then some will already be selected according to the
+ criteria shown in the drop-down menu. The default criteria is
+ 'highest resolution', simply choose another to pick structures in
+ a different way.<br />
+ <ul>
+ <li><strong>Viewing Cached Structures</strong><br />If
+ previously downloaded structures are available for your
+ sequences, the structure chooser will automatically offer them
+ via the <strong>Cached Structures</strong> view. If you wish
+ to download new structures, select one of the PDBe selection
+ criteria from the drop-down menu.</li>
+ </ul></li>
+ <li><strong>To view selected structures, click the <strong>"View"</strong>
+ button.
+ </strong><br />
+ <ul>
+ <li>Additional structure data will be downloaded with the
+ EMBL-EBI's dbfetch service</li>
+ <li><a href="siftsmapping.html">SIFTS</a> records will also
+ be downloaded for mapping UniProt protein sequence data to PDB
+ coordinates.</li>
+ <li>A new structure viewer will open, or you will be
+ prompted to add structures to existing viewers (see <a
+ href="#afterviewbutton">below</a> for details).
+ </li>
+ </ul></li>
+ </ol>
+ <p>
+ <strong>Structure Viewers in the Jalview Desktop</strong><br /> The
+ <a href="jmol.html">Jmol viewer</a> has been included since Jalview
+ 2.3. Jalview 2.8.2 included support for <a href="chimera.html">Chimera</a>,
+ provided it is installed and can be launched by Jalview. The default
+ viewer can be configured in the <a href="preferences.html#structure">Structure
+ tab</a> in the <strong>Tools→Preferences</strong> dialog box.
+
+ <p>
+ Structure data imported into Jalview can also be processed to
+ display secondary structure and temperature factor annotation. See
+ the <a href="xsspannotation.html">Annotation from Structure</a> page
+ for more information.
+ </p>
+ <p>
+ <img src="schooser_viewbutton.png"
+ style="width: 465px; height: 81px" /><br/> <strong><a
+ name="afterviewbutton">Controlling where the new structures
+ will be shown</a></strong>
+ <br />The Structure Chooser offers several options
+ for viewing a structure. <br/><strong>New View</strong> will open a new
+ structure viewer for the selected structures, but if there are views
+ already open, you can select which one to use, and press the <strong>Add</strong>
+ button. Jalview can automatically superimpose new structures based
+ on the linked alignments - but if this is not desirable, simple
+ un-tick the <strong>Superpose Structures</strong> checkbox.
-<p>Jalview can view protein structures associated with a sequence
-via the <strong>"Structure→View PDB entry:"</strong> entries from a
-sequence's <a href="../menus/popupMenu.html">pop-up menu</a>. Once a pdb
-structure is selected, one of the following will happen:</p>
+ </p>
+ <p>
+ <em>Superposing structures</em><br/>Jalview superposes structures using
+ the visible portions of any associated sequence alignments. A
+ message in the structure viewer's status bar will be shown if not
+ enough aligned columns were available to perform a superposition.
+ </p>
+ <p>
+ See the <a href="jmol.html">Jmol
+ </a> and <a href="chimera.html">Chimera</a> help pages for
+ more information about their capabilities.</p>
+
-<ul>
- <li>If no structures are open, then an interactive display of the
- structure will be opened in a new window</li>
+ <p>
+ <strong>Retrieving sequences from the PDB</strong><br>You can
+ retrieve sequences from the PDB using the <a
+ href="pdbsequencefetcher.html">Sequence Fetcher</a>. The sequences
+ retrieved with this service are derived directly from the PDB 3D
+ structure data, which can be viewed in the same way above. Secondary
+ structure and temperature factor annotation can also be added. <br />
- <li>If another structure is already shown for the current
- alignment, then you will be asked if you want to add and <a
- href="jmol.html#align">align this structure</a> to the structure in
- the existing view. (<em>new feature in Jalview 2.6</em>)</li>
+ <br>Jalview will also read PDB files directly - either in PDB
+ format, or <a href="mmcif.html">mmCIF</a>. Simply load in the file
+ as you would an alignment file. The sequences of any protein or
+ nucleotide chains will be extracted from the file and viewed in the
+ alignment window.
+ </p>
- <li>If the structure is already shown, then you will be prompted
- to associate the sequence with an existing view of the selected
- structure. This is useful when working with multi-domain or multi-chain PDB files.</li>
+ <p>
+ <strong>Associating a large number of PDB files to
+ sequences in an alignment</strong><br /> It is often the case when working
+ with structure alignments that you will have a directory of PDB
+ files, and an alignment involving one or more of the structures. If
+ you drag a number of PDB files onto an alignment in the Jalview
+ desktop, Jalview will give you the option of associating PDB files
+ with sequences that have the same filename. This means, for example,
+ you can automatically associate PDB files with names like '1gaq.pdb'
+ with sequences that have an ID like '1gaq'. <br /> <em>Note:
+ This feature was added in Jalview 2.7</em>
+ </p>
+ <p>
+ <em>Note for Jalview applet users:<br> Due to the applet
+ security constraints, PDB Files can currently only be imported by
+ cut and paste of the PDB file text into the text box opened by the
+ 'From File' entry of the structure menu.
+ </em>
+ </p>
- <li style="list-style: none">See the <a href="jmol.html">Jmol
- PDB viewer</a> help page for more information about the display.</li>
-</ul>
- <p>
- <em>Opening structures associated with the current selection</em><br />
- If one or more of the sequences in the alignment are selected, then
- the Structure submenu of the <a href="../menus/popupMenu.html">Sequence
- ID popup menu</a> will contain will include either a 'View all <em>X</em>
- structures' entry in the submenu or a 'View structure for <em>Sequence</em>'
- entry. Both these options will open a new Jmol view containing one, or
- all the structures available for all selected sequences, superimposed
- using the currently selected region of the alignment. (<em>This
- capability was added in Jalview 2.7</em>)
- </p>
- <p><strong>Associating PDB files with Sequences</strong></p>
- <p>To associate PDB files with a sequence, right click on a sequence
-ID and select "Structure<strong>→</strong> Associate Structure with
-Sequence", and one of the submenus:</p>
+ <p>
+ <strong>Viewing the PDB Residue Numbering</strong><br>
+ Sequences which have PDB entry or PDB file associations are
+ annotated with sequence features from a group named with the
+ associated PDB accession number or file name. Each feature gives the
+ corresponding PDB Residue Number for each mapped residue in the
+ sequence. The display of these features is controlled through the <strong>"View→Sequence
+ Features"</strong> menu item and the <a href="featuresettings.html">Feature
+ Settings dialog box</a>.
+ </p>
+ <br />
+ <hr>
+ <p>
+ <strong>Switching between mmCIF and PDB format for
+ downloading files from the PDB</strong><br /> Jalview now employs the <a
+ href="mmcif.html">mmCIF format</a> for importing 3D structure data
+ from flat file and EMBL-PDBe web-service, as recommended by the
+ wwwPDB. If you prefer (for any reason) to download data as PDB files
+ instead, then first close Jalview, and add the following line to
+ your .jalview_properties file:<br />
+ <code> PDB_DOWNLOAD_FORMAT=PDB </code>
+ <br /> When this setting is configured, Jalview will only request
+ PDB format files from EMBL-EBI's PDBe.<br /> <em>mmCIF format
+ file support was added in Jalview 2.10.</em>
+ </p>
-<ul>
- <li>From File - You can 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>
+ <p>
+ <em><strong>Outstanding problem with cut'n'pasted
+ files in Jalview 2.6 and Jalview 2.7</strong><br>Structures imported
+ via the cut'n'paste dialog box will not be correctly highlighted
+ or coloured when they are displayed in structure views, especially
+ if they contain more than one PDB structure. See the bug report at
+ http://issues.jalview.org/browse/JAL-623 for news on this problem.</em>
+ </p>
- <li>Enter PDB Id - Jalview will use WSDBFetch, provided by the
- EBI, to fetch the PDB file with the entered Id.<br>
- </li>
-
- <li>Discover PDB Ids - Jalview uses the sequence's ID to query WSDBFetch, provided by the
- EBI, and any enabled DAS servers, to discover PDB ids associated with the sequence.</li>
-</ul>
-
-<p><strong>Importing PDB Entries or files in PDB format</strong><br>
-You can retrieve sequences from the PDB using the <a
- href="seqfetch.html">Sequence Fetcher</a>. Any sequences retrieved with
-this service are automatically associated with their source database
-entry. For PDB sequences, simply select PDB as the database and enter
-your known PDB id (appended with ':' and a chain code, if desired).<br>
-Jalview will also read PDB files directly. Simply load in the file as
-you would an alignment file. The sequences of any peptide chains will be
-extracted from the file and viewed in the alignment window.</p>
-
-<p>
-<strong>Associating a large number of PDB files to sequences
-in an alignment</strong><br /> It is often the case when working with
-structure alignments that you will have a directory of PDB files, and
-an alignment involving one or more of the structures. If you drag a
-number of PDB files onto an alignment in the Jalview desktop, Jalview
-will give you the option of associating PDB files with sequences that
-have the same filename. This means, for example, you can automatically
-associate PDB files with names like '1gaq.pdb' with sequences that
-have an ID like '1gaq'.
-<br/><em>Note: This feature was added in Jalview 2.7</em>
-</p>
-<p><em>Note for jalview applet users:<br>
-Due to the applet security constraints, PDB Files can currently only be
-imported by cut and paste of the PDB file text into the text box opened
-by the 'From File' entry of the structure menu.</em></p>
-
-<p><strong>Viewing the PDB Residue Numbering</strong><br>
-Sequences which have PDB entry or PDB file associations are annotated
-with sequence features from a group named with the associated PDB
-accession number or file name. Each feature gives the corresponding PDB
-Residue Number for each mapped residue in the sequence. The display of
-these features is controlled through the <strong>"View→Sequence
-Features"</strong> menu item and the <a href="featuresettings.html">Feature
-Settings dialog box</a>.</p>
-
-<p><em><strong>Outstanding problem with cut'n'pasted
-files in Jalview 2.6 and Jalview 2.7</strong><br>
-Structures imported via the cut'n'paste dialog box will not be correctly
-highlighted or coloured when they are displayed in structure views,
-especially if they contain more than one PDB structure. See the bug
-report at http://issues.jalview.org/browse/JAL-623 for news on this problem.</em></p>
</body>
</html>