help/html/features/jmol.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.2b1)
   4  * Copyright (C) 2014 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>The Jmol PDB Viewer</title>
  24 </head>
  25 <body>
  26 <p><strong>The Jmol PDB Viewer</strong></p>
  27 <p>Since Jalview 2.3, <a href="http://jmol.sourceforge.net/">Jmol</a>
  28 has been integrated into Jalview for interactively viewing structures
  29 opened by entries in the <strong>&quot;Structure&quot;</strong> submenu in the <a href="../menus/popupMenu.html">sequence
  30 id pop-up menu</a> (if you can't see this, then you need to <a
  31         href="viewingpdbs.html">associate a PDB structure</a> with the
  32 sequence). Jmol is available from the Jalview desktop and should also
  33 run in the JalviewLite applet, providing the browser supports Java 1.5.
  34 If Jmol is not available, then the original <a href="pdbviewer.html">internal
  35 pdb viewer</a> will be used as a fallback.</p>
  36 <p>The following menu entries are provided for viewing structure data<br>
  37   <ul>
  38     <li>The <strong>&quot;Structure&#8594;View
  39         Structure&#8594;</strong> submenu allows a single PDB structure to be chosen
  40       for display from the available structures for a sequence.
  41     </li>
  42     <li>The <strong>&quot;Structure&#8594;View all <em>N</em>
  43         structures
  44     </strong> option will open a new window containing all structures associated
  45       with the current selection.
  46     </li>
  47     <li>The <strong>&quot;Structure&#8594;View all <em>N</em>
  48         representative structures
  49     </strong> option will open a new window containing exactly one structure per
  50       currently selected sequence.<br />
  51     <em>The View representative structures option was introduced in
  52         Jalview 2.8.1</em></li>
  53   </ul>
  54   <br>
  55 </p>
  56 <p><a name="align"><strong>Superposing structures based
  57 on their aligned sequences</strong></a><br>
  58 If several structures are available on the alignment, you may add
  59 additional structures to an existing Jmol view by selecting their entry
  60 in the appropriate pop-up menu. Jalview will ask you if you wish to add
  61 the structure to the existing alignment, and if you do, it will import
  62 and superimpose the new PDB file using the corresponding positions from
  63 the alignment. If the alignment is subsequently edited, you can use the
  64 <a href="#sAlign"><em>Jmol&#8594;Align</em></a> menu option from the
  65 menu bar of the structure view window to superpose the structures using
  66 the updated alignment.<br>
  67 <em>Sequence based structure superposition was added in Jalview 2.6</em>
  68 </p>
  69 <p><strong>Controls</strong><br>
  70 The structure is by default rendered as a ribbon diagram. Moving the
  71 mouse over the structure brings up tooltips giving the residue name, PDB
  72 residue number and chain code, atom name and number
  73 ([RES]Num:Chain.AtomName#AtomNumber). If a mapping exists to a residue
  74 in any associated sequences, then this will be highlighted in each one's
  75 alignment window. The converse also occurs - moving the mouse over an
  76 associated residue in an alignment window highlights the associated
  77 atoms in the displayed structures.</p>
  78 <p>Selecting a residue highlights its associated sequence residue
  79 and alpha carbon location. Double clicking an atom allows distances to
  80 be measured from it to any other atom in the structure.</p>
  81 <p>
  82 <table border="1">
  83         <tr>
  84                 <td><strong>Action</strong></td>
  85                 <td><strong>Windows</strong></td>
  86                 <td><strong>Unix</strong></td>
  87                 <td><strong>Mac/OSX</strong></td>
  88         </tr>
  89         <tr>
  90                 <td>Rotate View</td>
  91                 <td>Left Click and Drag</td>
  92                 <td>Left Click and Drag</td>
  93                 <td>Click and Drag</td>
  94         </tr>
  95         <tr>
  96                 <td>Zoom</td>
  97                 <td>Shift + Left Click<br>
  98                 drag mouse up or down</td>
  99                 <td>Shift + Left Click<br>
 100                 or middle button<br>
 101                 drag mouse up or down</td>
 102                 <td>Left-Alt + Click and drag mouse up or down</td>
 103         </tr>
 104         <tr>
 105                 <td>Select/<br>
 106                 Deselect<br>
 107                 Residue</td>
 108                 <td>Left Click</td>
 109                 <td>Left Click</td>
 110                 <td>Click</td>
 111         </tr>
 112         <tr>
 113                 <td>Roll View</td>
 114                 <td>Shift + Left Click<br>
 115                 drag mouse to left or right</td>
 116                 <td>Shift + Left Click<br>
 117                 or middle button<br>
 118                 drag mouse to left or right</td>
 119                 <td>Left-Alt + Click and drag mouse to left or right</td>
 120         </tr>
 121         <tr>
 122                 <td>Move Origin</td>
 123                 <td>Shift+Control+Left Click<br>
 124                 or Middle Button<br>
 125                 + Drag</td>
 126                 <td>Middle-Button<br>
 127                 and<br>
 128                 drag</td>
 129                 <td>Shift+Control+Left Click<br>
 130                 or Middle Button<br>
 131                 and drag</td>
 132         </tr>
 133         <tr>
 134                 <td>Jmol Menu</td>
 135                 <td>Right-Click</td>
 136                 <td>Right-Click</td>
 137                 <td>Apple-Click</td>
 138         </tr>
 139 </table>
 140 </p>
 141 <p>The window has up to five menus:
 142 <ul>
 143         <li><Strong>File<br>
 144         </strong>
 145         <ul>
 146                 <li><strong>Save As<br>
 147                 </strong><em>Save the displayed PDB File, or the current view as an EPS or
 148                 PNG file.</em></li>
 149                 <li><strong>View Mapping<br>
 150                 </strong><em> Opens a text window showing the alignment between the
 151                 residues corresponding to alpha-carbon atoms in the PDB structure and
 152                 the residues in the associated sequence.</em></li>
 153         </ul>
 154         </li>
 155         <li><strong>View</strong>
 156         <ul>
 157                 <li><strong>Show Chains<br>
 158                 </strong><em>Select which of the PDB file's chains are to be displayed.</em></li>
 159                 <li><strong>Colour by ..<br></strong><em>Submenu allowing specific alignment views to be selected for colouring associated chains in the structure display. This menu contains all the alignment views associated with the structure view, with those used to colour the view indicated by ticks. Addditionally, it contains the following menu entries:</em>
 160                 <ul><li><strong>Select many views<br></strong><em>When this option is enabled, selecting an alignment view adds it to the set used to colour the structures. Use this when colouring structures related to a number of alignments involving different domains or chains which are shown in the same structure view.</em>
 161                 </li>
 162     <li><strong>Select all views<br></strong><em>This is only enabled when </em><strong>Select many views</strong><em> is also enabled, and will add all associated views to the set used to colour the structure display.</em>
 163   </li>
 164     <li><strong>Invert selection<br></strong><em>This is only enabled when </em><strong>Select many views</strong><em> is also enabled, and will replace the current set of views with any remaining views not currently used to colour the structure display.</em>
 165   </li></ul></li></ul>
 166         <li><strong>Colours<br>
 167         </strong>
 168         <ul>
 169                 <li><strong>By Sequence<br>
 170                 </strong><em> Colours each residue in the structure with the colour of its
 171                 corresponding residue in the associated sequence as rendered in the
 172                 associated alignment views, including any Uniprot sequence features or
 173                 region colourings.<br/>Pick which of the associated alignment views are used to colour the structures using the <strong>View&#8594;Colour by ..</strong> sub menu.</em><br>
 174                 Residues which only exist in the PDB structure are coloured white if
 175                 they are insertions (relative to the associated sequence in the
 176                 alignment) and grey if they are N or C terminal flanks outside the
 177                 region mapped to the alignment window's sequence.</em></li>
 178                 <li><strong>By Chain<br>
 179                 </strong><em> Assigns a random colour to each PDB chain.</em>
 180                 <li><strong>Charge &amp; Cysteine<br>
 181                 </strong><em> Highlights cysteines in yellow, anionic (Aspartic Acid or
 182                 Glutamic Acid) residues in red, and cationic (Lysine or Arginine)
 183                 residues in blue.</em></li>
 184                 <li><strong>Colour with Jmol<br></strong><em>Defers any colouring operations to Jmol. Select this if you want to use the Jmol scripting interface or menu to modify the view directly.</em></li>
 185                 <li><strong>Standard and User Defined Jalview
 186                 colourschemes.<br>
 187                 </strong><em>The remaining entries apply the colourschemes available from
 188                 the standard and user defined <a href="../colourSchemes/index.html">amino
 189                 acid colours</a>.</em></li>
 190         </ul>
 191         </li>
 192         <li><strong>Jmol<br>
 193         </strong><em>This pulldown menu is only displayed if there are multiple
 194         structures shown in the Jmol window, and Jalview can also locate at
 195         least two of the structures in the currently associated alignment view.</em>
 196         <ul>
 197                 <li><strong><a name="sAlign">Align</a> <br>
 198                 </strong><em> When selected, the associated alignment will be used to
 199                 superimpose all the structures in the view onto the first structure in
 200                 the alignment. The regions used to calculate the superposition will be
 201                 highlighted using the 'Cartoon' rendering style, and the remaining
 202                 data shown as a chain trace.<br>
 203                 (This option was introduced in Jalview 2.6)</em></li>
 204         </ul>
 205         </li>
 206         <li><strong>Help<br>
 207         </strong>
 208         <ul>
 209                 <li><strong>Jmol Help<br>
 210                 </strong><em>Access the Jmol Help documentation in a new browser window.</em></li>
 211         </ul>
 212         </li>
 213 </ul>
 214 </p>
 215 <p><strong>Functionality provided by Jmol</strong></p>
 216 <p>Jmol's own functions are accessed by clicking the 'Jmol' logo or
 217 right-clicking in the structure display area. Either way will open the
 218 Jmol pop-up menu, which provides access to a number of features for
 219 controlling the colour and display of molecules, adding measurements and
 220 labels, plotting surfaces, and display animation. The 'Set Picking' menu
 221 controls the behaviour of single and double mouse clicking on the
 222 structure, and the 'Console' option opens the Jmol scripting console.</p>
 223 <p>The state of each Jmol display is stored within <a
 224         href="jalarchive.html">jalview archives</a> as a Jmol state recovery
 225 script file. This means that any Jmol visualization effects that you add
 226 beyond those provided by Jalview will be able to be stored and recovered
 227 along with the displayed alignments in Jalview.</p>
 228 <p><strong>More Information</strong></p>
 229 <p>Jmol is a sophisticated program in its own right, with its own
 230 command console and scripting language. Only the essentials have been
 231 described here - the interested reader is referred to <a
 232         href="http://jmol.sourceforge.net/docs/">Jmol's own comprehensive
 233 online documentation</a>.</p>
 234 </p>
 235 </body>
 236 </html>