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>The Jmol PDB Viewer</title>
27 <strong>The Jmol PDB Viewer</strong>
30 Since Jalview 2.3, <a href="http://jmol.sourceforge.net/">Jmol</a>
31 has been integrated into Jalview for interactively viewing
32 structures opened by entries in the <strong>"Structure"</strong>
33 submenu in the <a href="../menus/popupMenu.html">sequence id
34 pop-up menu</a> (if you can't see this, then you need to <a
35 href="viewingpdbs.html">associate a PDB structure</a> with
36 the sequence). Jmol is available from the Jalview desktop and should
37 also run in the JalviewLite applet, providing the browser supports
38 Java 1.5. If Jmol is not available, then the original <a
39 href="pdbviewer.html">internal pdb viewer</a> will be used as a
42 <!-- <p>The following menu entries are provided for viewing structure data<br>
44 <li>The <strong>"Structure→View
45 Structure→</strong> submenu allows a single PDB structure to be chosen
46 for display from the available structures for a sequence.
48 <li>The <strong>"Structure→View all <em>N</em>
50 </strong> option will open a new window containing all structures associated
51 with the current selection.
53 <li>The <strong>"Structure→View all <em>N</em>
54 representative structures
55 </strong> option will open a new window containing exactly one structure per
56 currently selected sequence.<br />
57 <em>The View representative structures option was introduced in
58 Jalview 2.8.1</em></li>
63 <a name="align"><strong>Superposing structures based on
64 their aligned sequences</strong></a><br> If several structures are shown
65 in a view, you can superimpose them using the corresponding
66 positions from the alignment via the <a href="#sAlign"><em>Jmol→Align</em></a>
67 menu option from the menu bar of the structure view window. <br> <em>Sequence
68 based structure superposition was added in Jalview 2.6</em>
71 <strong>Controls</strong><br> The structure is by default rendered
72 as a ribbon diagram. Moving the mouse over the structure brings up
73 tooltips giving the residue name, PDB residue number and chain code,
74 atom name and number ([RES]Num:Chain.AtomName#AtomNumber). If a
75 mapping exists to a residue in any associated sequences, then this
76 will be highlighted in each one's alignment window. The converse
77 also occurs - moving the mouse over an associated residue in an
78 alignment window highlights the associated atoms in the displayed
79 structures. Press B or use
80 <em>Select→Select Highlighted columns</em> from any linked
81 alignment window to mark the columns highlighted after mousing over
84 <p>Selecting a residue highlights its associated sequence residue
85 and alpha carbon location. Double clicking an atom allows distances
86 to be measured from it to any other atom in the structure.</p>
90 <td><strong>Action</strong></td>
91 <td><strong>Windows</strong></td>
92 <td><strong>Unix</strong></td>
93 <td><strong>Mac/OSX</strong></td>
97 <td>Left Click and Drag</td>
98 <td>Left Click and Drag</td>
99 <td>Click and Drag</td>
103 <td>Shift + Left Click<br> drag mouse up or down
105 <td>Shift + Left Click<br> or middle button<br>
106 drag mouse up or down
108 <td>Left-Alt + Click and drag mouse up or down</td>
111 <td>Select/<br> Deselect<br> Residue
119 <td>Shift + Left Click<br> drag mouse to left or right
121 <td>Shift + Left Click<br> or middle button<br>
122 drag mouse to left or right
124 <td>Left-Alt + Click and drag mouse to left or right</td>
128 <td>Shift+Control+Left Click<br> or Middle Button<br>
131 <td>Middle-Button<br> and<br> drag
133 <td>Shift+Control+Left Click<br> or Middle Button<br>
145 <p>The window has up to five menus:
150 <li><strong>Save As<br>
151 </strong><em>Save the displayed PDB File, or the current view as an
152 EPS or PNG file.</em></li>
153 <li><strong>View Mapping<br>
154 </strong><em> Opens a text window showing the alignment between the
155 residues corresponding to alpha-carbon atoms in the PDB
156 structure and the residues in the associated sequence.</em></li>
158 <li><strong>View</strong>
160 <li><strong>Show Chains<br>
161 </strong><em>Select which of the PDB file's chains are to be
163 <li><strong>Ligands<br>
164 </strong><em>When available, allows the display of all, none or specific
165 ligands (also known as HETATM groups) in the Jmol view, using CPK
166 spacefilling.</em></li>
167 <li><strong>Colour by ..<br></strong><em>Submenu
168 allowing specific alignment views to be selected for
169 colouring associated chains in the structure display. This
170 menu contains all the alignment views associated with the
171 structure view, with those used to colour the view indicated
172 by ticks. Addditionally, it contains the following menu
175 <li><strong>Select many views<br></strong><em>When
176 this option is enabled, selecting an alignment view adds
177 it to the set used to colour the structures. Use this
178 when colouring structures related to a number of
179 alignments involving different domains or chains which
180 are shown in the same structure view.</em></li>
181 <li><strong>Select all views<br></strong><em>This
182 is only enabled when </em><strong>Select many views</strong><em>
183 is also enabled, and will add all associated views to
184 the set used to colour the structure display.</em></li>
185 <li><strong>Invert selection<br></strong><em>This
186 is only enabled when </em><strong>Select many views</strong><em>
187 is also enabled, and will replace the current set of
188 views with any remaining views not currently used to
189 colour the structure display.</em></li>
192 <li><strong>Colours<br>
195 <li><strong>By Sequence<br>
196 </strong><em> Colours each residue in the structure with the colour
197 of its corresponding residue in the associated sequence as
198 rendered in the associated alignment views, including any
199 UniProt sequence features or region colourings.<br />Pick
200 which of the associated alignment views are used to colour
201 the structures using the <strong>View→Colour
202 by ..</strong> sub menu.
203 </em><br> Residues which only exist in the PDB structure are
204 coloured white if they are insertions (relative to the
205 associated sequence in the alignment) and grey if they are N
206 or C terminal flanks outside the region mapped to the
207 alignment window's sequence.</em></li>
208 <li><strong>By Chain<br>
209 </strong><em> Assigns a random colour to each PDB chain.</em>
210 <li><strong>Charge & Cysteine<br>
211 </strong><em> Highlights cysteines in yellow, anionic (Aspartic Acid
212 or Glutamic Acid) residues in red, and cationic (Lysine or
213 Arginine) residues in blue.</em></li>
214 <li><strong>Colour with Jmol<br></strong><em>Defers
215 any colouring operations to Jmol. Select this if you want to
216 use the Jmol scripting interface or menu to modify the view
218 <li><strong>Standard and User Defined Jalview
220 </strong><em>The remaining entries apply the colourschemes available
221 from the standard and user defined <a
222 href="../colourSchemes/index.html">amino acid
227 </strong><em>This pulldown menu is only displayed if there are multiple
228 structures shown in the Jmol window, and Jalview can also locate
229 at least two of the structures in the currently associated
232 <li><strong><a name="sAlign">Align</a> <br> </strong><em>
233 When selected, the associated alignment will be used to
234 superimpose all the structures in the view onto the first
235 structure in the alignment. The regions used to calculate
236 the superposition will be highlighted using the 'Cartoon'
237 rendering style, and the remaining data shown as a chain
238 trace.<br> (This option was introduced in Jalview 2.6)
244 <li><strong>Jmol Help<br>
245 </strong><em>Access the Jmol Help documentation in a new browser
251 <strong>Functionality provided by Jmol</strong>
253 <p>Jmol's own functions are accessed by clicking the 'Jmol' logo
254 or right-clicking in the structure display area. Either way will
255 open the Jmol pop-up menu, which provides access to a number of
256 features for controlling the colour and display of molecules, adding
257 measurements and labels, plotting surfaces, and display animation.
258 The 'Set Picking' menu controls the behaviour of single and double
259 mouse clicking on the structure, and the 'Console' option opens the
260 Jmol scripting console.</p>
262 The state of each Jmol display is stored within <a
263 href="jalarchive.html">Jalview archives</a> as a Jmol state
264 recovery script file. This means that any Jmol visualization effects
265 that you add beyond those provided by Jalview will be able to be
266 stored and recovered along with the displayed alignments in Jalview.
269 <strong>More Information</strong>
272 Jmol is a sophisticated program in its own right, with its own
273 command console and scripting language. Only the essentials have
274 been described here - the interested reader is referred to <a
275 href="http://jmol.sourceforge.net/docs/">Jmol's own
276 comprehensive online documentation</a>.