3 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.9.0b1)
4 * Copyright (C) 2015 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"
36 >associate a PDB structure</a> with the sequence). Jmol is available
37 from the Jalview desktop and should also run in the JalviewLite
38 applet, providing the browser supports Java 1.5. If Jmol is not
39 available, then the original <a href="pdbviewer.html">internal
40 pdb viewer</a> will be used as a fallback.
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
65 available on the alignment, you may add additional structures to an
66 existing Jmol view by selecting their entry in the appropriate
67 pop-up menu. Jalview will ask you if you wish to add the structure
68 to the existing alignment, and if you do, it will import and
69 superimpose the new PDB file using the corresponding positions from
70 the alignment. If the alignment is subsequently edited, you can use
71 the <a href="#sAlign"><em>Jmol→Align</em></a> menu option from
72 the menu bar of the structure view window to superpose the
73 structures using the updated alignment.<br> <em>Sequence
74 based structure superposition was added in Jalview 2.6</em>
77 <strong>Controls</strong><br> The structure is by default
78 rendered as a ribbon diagram. Moving the mouse over the structure
79 brings up tooltips giving the residue name, PDB residue number and
80 chain code, atom name and number
81 ([RES]Num:Chain.AtomName#AtomNumber). If a mapping exists to a
82 residue in any associated sequences, then this will be highlighted
83 in each one's alignment window. The converse also occurs - moving
84 the mouse over an associated residue in an alignment window
85 highlights the associated atoms in the displayed structures.
87 <p>Selecting a residue highlights its associated sequence residue
88 and alpha carbon location. Double clicking an atom allows distances
89 to be measured from it to any other atom in the structure.</p>
93 <td><strong>Action</strong></td>
94 <td><strong>Windows</strong></td>
95 <td><strong>Unix</strong></td>
96 <td><strong>Mac/OSX</strong></td>
100 <td>Left Click and Drag</td>
101 <td>Left Click and Drag</td>
102 <td>Click and Drag</td>
106 <td>Shift + Left Click<br> drag mouse up or down
108 <td>Shift + Left Click<br> or middle button<br>
109 drag mouse up or down
111 <td>Left-Alt + Click and drag mouse up or down</td>
114 <td>Select/<br> Deselect<br> Residue
122 <td>Shift + Left Click<br> drag mouse to left or right
124 <td>Shift + Left Click<br> or middle button<br>
125 drag mouse to left or right
127 <td>Left-Alt + Click and drag mouse to left or right</td>
131 <td>Shift+Control+Left Click<br> or Middle Button<br>
134 <td>Middle-Button<br> and<br> drag
136 <td>Shift+Control+Left Click<br> or Middle Button<br>
148 <p>The window has up to five menus:
153 <li><strong>Save As<br>
154 </strong><em>Save the displayed PDB File, or the current view as an
155 EPS or PNG file.</em></li>
156 <li><strong>View Mapping<br>
157 </strong><em> Opens a text window showing the alignment between the
158 residues corresponding to alpha-carbon atoms in the PDB
159 structure and the residues in the associated sequence.</em></li>
161 <li><strong>View</strong>
163 <li><strong>Show Chains<br>
164 </strong><em>Select which of the PDB file's chains are to be
166 <li><strong>Colour by ..<br></strong><em>Submenu
167 allowing specific alignment views to be selected for
168 colouring associated chains in the structure display. This
169 menu contains all the alignment views associated with the
170 structure view, with those used to colour the view indicated
171 by ticks. Addditionally, it contains the following menu
174 <li><strong>Select many views<br></strong><em>When
175 this option is enabled, selecting an alignment view adds
176 it to the set used to colour the structures. Use this
177 when colouring structures related to a number of
178 alignments involving different domains or chains which
179 are shown in the same structure view.</em></li>
180 <li><strong>Select all views<br></strong><em>This
181 is only enabled when </em><strong>Select many views</strong><em>
182 is also enabled, and will add all associated views to
183 the set used to colour the structure display.</em></li>
184 <li><strong>Invert selection<br></strong><em>This
185 is only enabled when </em><strong>Select many views</strong><em>
186 is also enabled, and will replace the current set of
187 views with any remaining views not currently used to
188 colour the structure display.</em></li>
191 <li><strong>Colours<br>
194 <li><strong>By Sequence<br>
195 </strong><em> Colours each residue in the structure with the colour
196 of its corresponding residue in the associated sequence as
197 rendered in the associated alignment views, including any
198 Uniprot sequence features or region colourings.<br />Pick
199 which of the associated alignment views are used to colour
200 the structures using the <strong>View→Colour
201 by ..</strong> sub menu.
202 </em><br> Residues which only exist in the PDB structure are
203 coloured white if they are insertions (relative to the
204 associated sequence in the alignment) and grey if they are N
205 or C terminal flanks outside the region mapped to the
206 alignment window's sequence.</em></li>
207 <li><strong>By Chain<br>
208 </strong><em> Assigns a random colour to each PDB chain.</em>
209 <li><strong>Charge & Cysteine<br>
210 </strong><em> Highlights cysteines in yellow, anionic (Aspartic Acid
211 or Glutamic Acid) residues in red, and cationic (Lysine or
212 Arginine) residues in blue.</em></li>
213 <li><strong>Colour with Jmol<br></strong><em>Defers
214 any colouring operations to Jmol. Select this if you want to
215 use the Jmol scripting interface or menu to modify the view
217 <li><strong>Standard and User Defined Jalview
219 </strong><em>The remaining entries apply the colourschemes available
220 from the standard and user defined <a
221 href="../colourSchemes/index.html"
222 >amino acid colours</a>.
226 </strong><em>This pulldown menu is only displayed if there are multiple
227 structures shown in the Jmol window, and Jalview can also locate
228 at least two of the structures in the currently associated
231 <li><strong><a name="sAlign">Align</a> <br> </strong><em>
232 When selected, the associated alignment will be used to
233 superimpose all the structures in the view onto the first
234 structure in the alignment. The regions used to calculate
235 the superposition will be highlighted using the 'Cartoon'
236 rendering style, and the remaining data shown as a chain
237 trace.<br> (This option was introduced in Jalview 2.6)
243 <li><strong>Jmol Help<br>
244 </strong><em>Access the Jmol Help documentation in a new browser
250 <strong>Functionality provided by Jmol</strong>
252 <p>Jmol's own functions are accessed by clicking the 'Jmol' logo
253 or right-clicking in the structure display area. Either way will
254 open the Jmol pop-up menu, which provides access to a number of
255 features for controlling the colour and display of molecules, adding
256 measurements and labels, plotting surfaces, and display animation.
257 The 'Set Picking' menu controls the behaviour of single and double
258 mouse clicking on the structure, and the 'Console' option opens the
259 Jmol scripting console.</p>
261 The state of each Jmol display is stored within <a
262 href="jalarchive.html"
263 >Jalview archives</a> as a Jmol state recovery script file. This means
264 that any Jmol visualization effects that you add beyond those
265 provided by Jalview will be able to be stored and recovered along
266 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/"
276 >Jmol's own comprehensive online documentation</a>.