JAL-2416 score matrix gap symbol (if any) dynamically determined
[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>Discovering and Viewing PDB Structures</strong>
28   </p>
29   Jalview can be used to explore the 3D structures of sequences in an
30   alignment by following the steps 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">Structure Chooser</a> interface
44           will present options for manual association of PDB structures.
45         </li>
46       </ul>
47     </li>
48     <li><strong>Selecting Structures</strong><br />You can select
49       the structures that you want to open and view by selecting them
50       with the mouse and keyboard.<br />By default, if structures were
51       discovered, then some will already be selected according to the
52       criteria shown in the drop-down menu. The default criteria is
53       'highest resolution', simply choose another to pick structures in
54       a different way.<br />
55       <ul>
56         <li><strong>Viewing Cached Structures</strong><br />If
57           previously downloaded structures are available for your
58           sequences, the structure chooser will automatically offer them
59           via the <strong>Cached PDB Entries</strong> view. If you wish
60           to download new structures, select one of the PDBe selection
61           criteria from the drop-down menu.</li>
62       </ul></li>
63     <li><strong>To view selected structures, click the <strong>"View"</strong>
64         button.
65     </strong><br />
66       <ul>
67         <li>Additional structure data will be downloaded with the
68           EMBL-EBI's dbfetch service</li>
69         <li><a href="siftsmapping.html">SIFTS</a> records will also
70           be downloaded for mapping UniProt protein sequence data to PDB
71           coordinates.</li>
72         <li>A new structure viewer will open, or you will be
73           prompted to add structures to existing viewers (see <a
74           href="#afterviewbutton">below</a> for details).
75         </li>
76       </ul></li>
77   </ol>
78   <p>
79   <strong>Structure Viewers in the Jalview Desktop</strong><br/>
80   The
81   <a href="jmol.html">Jmol viewer</a> has been included since Jalview
82   2.3. Jalview 2.8.2 included support for
83   <a href="chimera.html">Chimera</a>, provided it is installed and can
84   be launched by Jalview. The default viewer can be configured in the
85   <a href="preferences.html#structure">Structure tab</a> in the
86   <strong>Tools&rarr;Preferences</strong> dialog box.
87   <p>
88     Structure data imported into Jalview can also be processed to
89     display secondary structure and temperature factor annotation. See
90     the <a href="xsspannotation.html">Annotation from Structure</a> page
91     for more information.
92   </p>
93   <p>
94     <strong><a name="afterviewbutton">After pressing the
95         'View' button in the Structure Chooser</a></strong><br /> The behaviour of
96     the 'View' button depends on the number of structures selected, and
97     whether structure views already exist for the selected structures or
98     aligned sequences.
99   </p>
100   <p>
101     If multiple structures are selected, then Jalview will always create
102     a new structure view. The selected structures will be imported into
103     this view, and superposed with the matched positions from the
104     aligned sequences.<br /> If a <strong>single</strong> PDB structure
105     is selected, one of the following will happen:
106   </p>
107
108   <ul>
109     <li>If no structures are open, then an interactive display of
110       the structure will be opened in a new window.</li>
111
112     <li>If another structure is already shown for the current
113       alignment, then you will be asked if you want to add and <a
114       href="jmol.html#align"></a> to
115     the structure in the existing view. (<em>new feature in Jalview
116       2.6</em>).
117   </li>
118
119     <li>If the structure is already shown, then you will be
120       prompted to associate the sequence with an existing view of the
121       selected structure. This is useful when working with multi-domain
122       or multi-chain PDB files.</li>
123
124     <li style="list-style: none">See the <a href="jmol.html">Jmol
125     </a> and <a href="chimera.html">Chimera</a> PDB viewer help pages for
126       more information about the display.
127     </li>
128   </ul>
129
130
131   <p>
132     <strong>Retrieving sequences from the PDB</strong><br>You can
133     retrieve sequences from the PDB using the <a
134       href="pdbsequencefetcher.html">Sequence Fetcher</a>. The sequences
135     retrieved with this service are derived directly from the PDB 3D
136     structure data, which can be viewed in the same way above. Secondary
137     structure and temperature factor annotation can also be added. <br />
138
139     <br>Jalview will also read PDB files directly - either in PDB
140     format, or <a href="mmcif.html">mmCIF</a>. Simply load in the file
141     as you would an alignment file. The sequences of any protein or
142     nucleotide chains will be extracted from the file and viewed in the
143     alignment window.
144   </p>
145
146   <p>
147     <strong>Associating a large number of PDB files to
148       sequences in an alignment</strong><br /> It is often the case when working
149     with structure alignments that you will have a directory of PDB
150     files, and an alignment involving one or more of the structures. If
151     you drag a number of PDB files onto an alignment in the Jalview
152     desktop, Jalview will give you the option of associating PDB files
153     with sequences that have the same filename. This means, for example,
154     you can automatically associate PDB files with names like '1gaq.pdb'
155     with sequences that have an ID like '1gaq'. <br /> <em>Note:
156       This feature was added in Jalview 2.7</em>
157   </p>
158   <p>
159     <em>Note for Jalview applet users:<br> Due to the applet
160       security constraints, PDB Files can currently only be imported by
161       cut and paste of the PDB file text into the text box opened by the
162       'From File' entry of the structure menu.
163     </em>
164   </p>
165
166   <p>
167     <strong>Viewing the PDB Residue Numbering</strong><br>
168     Sequences which have PDB entry or PDB file associations are
169     annotated with sequence features from a group named with the
170     associated PDB accession number or file name. Each feature gives the
171     corresponding PDB Residue Number for each mapped residue in the
172     sequence. The display of these features is controlled through the <strong>"View&rarr;Sequence
173       Features"</strong> menu item and the <a href="featuresettings.html">Feature
174       Settings dialog box</a>.
175   </p>
176   <br />
177   <hr>
178   <p>
179     <strong>Switching between mmCIF and PDB format for
180       downloading files from the PDB</strong><br /> Jalview now employs the <a
181       href="mmcif.html">mmCIF format</a> for importing 3D structure data
182     from flat file and EMBL-PDBe web-service, as recommended by the
183     wwwPDB. If you prefer (for any reason) to download data as PDB files
184     instead, then first close Jalview, and add the following line to
185     your .jalview_properties file:<br />
186     <code> PDB_DOWNLOAD_FORMAT=PDB </code>
187     <br /> When this setting is configured, Jalview will only request
188     PDB format files from EMBL-EBI's PDBe.<br /> <em>mmCIF format
189       file support was added in Jalview 2.10.</em>
190   </p>
191
192   <p>
193     <em><strong>Outstanding problem with cut'n'pasted
194         files in Jalview 2.6 and Jalview 2.7</strong><br>Structures imported
195       via the cut'n'paste dialog box will not be correctly highlighted
196       or coloured when they are displayed in structure views, especially
197       if they contain more than one PDB structure. See the bug report at
198       http://issues.jalview.org/browse/JAL-623 for news on this problem.</em>
199   </p>
200
201 </body>
202 </html>
203