Merge branch 'bug/JAL-2034_fix' into develop
[jalview.git] / help / html / features / viewingpdbs.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>PDB Viewing</title>
24 </head>
25 <body>
26   <p>
27     <strong>Viewing PDB Structures</strong>
28   </p>
29   Jalview can be used to view protein structures by following the steps
30   below:
31   <ol>
32     <li>Select the <strong>"3D Structure Data..."</strong> option
33       from a sequence's <a href="../menus/popupMenu.html">pop-up
34         menu</a> to open the <a href="structurechooser.html">Structure
35         Chooser</a> dialog box.
36       <ul>
37         <li>If one or more structures exists for the given
38           sequence, the <a href="structurechooser.html">Structure
39             Chooser</a> dialog will open with them listed in the results
40           pane.
41         </li>
42         <li>However, if no structure was found, the <a
43           href="structurechooser.html"
44         >Structure Chooser</a> interface will present options for manual
45           association of PDB structures.
46         </li>
47       </ul>
48     </li>
49     <li><strong>Selecting Structures</strong><br /> If structures
50       have been discovered, then some will already be selected according
51       to predefined selection criteria, such as structures with the
52       highest resolution. Use the drop down menu to select structures
53       according to different criteria, or, alternatively, choose
54       structures manually by selecting with the keyboard and mouse.
55       <ul>
56         <li><strong>Viewing Cached Structures</strong><br />If you
57           have previously downloaded structures for your sequences, they
58           can be viewed by selecting the <strong>Cached PDB
59             Entries</strong> option from the drop down menu at the top of the
60           dialog box.</li>
61       </ul></li>
62     <li>To view selected structures, click the <strong>"View"</strong>
63       button.
64     </li>
65   </ol>
66
67   The
68   <a href="jmol.html">Jmol viewer</a> has been included since Jalview
69   2.3. Jalview 2.8.2 included support for
70   <a href="chimera.html">Chimera</a>, provided it is installed and can
71   be launched by Jalview. The default viewer can be configured in the
72   <a href="preferences.html#structure">Structure tab</a> in the
73   <strong>Tools&rarr;Preferences</strong> dialog box.
74   <p>
75     Structure data imported into Jalview can also be processed to
76     display secondary structure and temperature factor annotation. See
77     the <a href="xsspannotation.html">Annotation from Structure</a> page
78     for more information.
79   </p>
80
81   <p>
82     If a <strong>single</strong> PDB structure is selected, one of the
83     following will happen:
84   </p>
85
86   <ul>
87     <li>If no structures are open, then an interactive display of
88       the structure will be opened in a new window.</li>
89
90     <li>If another structure is already shown for the current
91       alignment, then you will be asked if you want to add and <a
92       href="jmol.html#align"
93     >align this structure</a> to the structure in the existing view. (<em>new
94         feature in Jalview 2.6</em>).
95     </li>
96
97     <li>If the structure is already shown, then you will be
98       prompted to associate the sequence with an existing view of the
99       selected structure. This is useful when working with multi-domain
100       or multi-chain PDB files.</li>
101
102     <li style="list-style: none">See the <a href="jmol.html">Jmol
103     </a> and <a href="chimera.html">Chimera</a> PDB viewer help pages for
104       more information about the display.
105     </li>
106   </ul>
107
108
109   <p>
110     <strong>Importing PDB Entries or files in PDB format</strong><br>
111     You can retrieve sequences from the PDB using the <a
112       href="pdbsequencefetcher.html"
113     >Sequence Fetcher</a>. Any sequences retrieved with this service are
114     automatically associated with their source database entry. For PDB
115     sequences, simply select PDB as the database and enter your known
116     PDB id (appended with ':' and a chain code, if desired).<br>
117     Jalview will also read PDB files directly. Simply load in the file
118     as you would an alignment file. The sequences of any protein or
119     nucleotide chains will be extracted from the file and viewed in the
120     alignment window.
121   </p>
122
123   <p>
124     <strong>Importing PDB Entries or files in mmCIF format</strong><br>
125     <a href="mmcif.html">mmCIF file format</a> provides an alternative means for 
126     importing 3D structure data from flat file and EMBL-PDBe 
127     web-service. To enable mmCIF as the default format for 
128     importing PBD sequences from the PDB sequence fetcher, add or modify the 
129     property  
130     <code>DEFAULT_STRUCTURE_FORMAT=mmCIF</code> in Jalview properties file. 
131     Once this is done, the steps followed in retrieving PDB format files above can 
132     be followed to obtain the same data with mmCIF. <em>mmCIF format file support was added in Jalview 2.9.1.</em></p>
133     
134    
135
136   <p>
137     <strong>Associating a large number of PDB files to
138       sequences in an alignment</strong><br /> It is often the case when working
139     with structure alignments that you will have a directory of PDB
140     files, and an alignment involving one or more of the structures. If
141     you drag a number of PDB files onto an alignment in the Jalview
142     desktop, Jalview will give you the option of associating PDB files
143     with sequences that have the same filename. This means, for example,
144     you can automatically associate PDB files with names like '1gaq.pdb'
145     with sequences that have an ID like '1gaq'. <br />
146     <em>Note: This feature was added in Jalview 2.7</em>
147   </p>
148   <p>
149     <em>Note for Jalview applet users:<br> Due to the applet
150       security constraints, PDB Files can currently only be imported by
151       cut and paste of the PDB file text into the text box opened by the
152       'From File' entry of the structure menu.
153     </em>
154   </p>
155
156   <p>
157     <strong>Viewing the PDB Residue Numbering</strong><br>
158     Sequences which have PDB entry or PDB file associations are
159     annotated with sequence features from a group named with the
160     associated PDB accession number or file name. Each feature gives the
161     corresponding PDB Residue Number for each mapped residue in the
162     sequence. The display of these features is controlled through the <strong>"View&rarr;Sequence
163       Features"</strong> menu item and the <a href="featuresettings.html">Feature
164       Settings dialog box</a>.
165   </p>
166
167   <p>
168     <em><strong>Outstanding problem with cut'n'pasted
169         files in Jalview 2.6 and Jalview 2.7</strong><br> Structures
170       imported via the cut'n'paste dialog box will not be correctly
171       highlighted or coloured when they are displayed in structure
172       views, especially if they contain more than one PDB structure. See
173       the bug report at http://issues.jalview.org/browse/JAL-623 for
174       news on this problem.</em>
175   </p>
176 </body>
177 </html>
178