help/html/features/jmol.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.9)
   4  * Copyright (C) 2015 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>
  27     <strong>The Jmol PDB Viewer</strong>
  28   </p>
  29   <p>
  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>&quot;Structure&quot;</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.
  41   </p>
  42   <!-- <p>The following menu entries are provided for viewing structure data<br>
  43   <ul>
  44     <li>The <strong>&quot;Structure&#8594;View
  45         Structure&#8594;</strong> submenu allows a single PDB structure to be chosen
  46       for display from the available structures for a sequence.
  47     </li>
  48     <li>The <strong>&quot;Structure&#8594;View all <em>N</em>
  49         structures
  50     </strong> option will open a new window containing all structures associated
  51       with the current selection.
  52     </li>
  53     <li>The <strong>&quot;Structure&#8594;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>
  59   </ul>
  60   <br>
  61 </p> -->
  62   <p>
  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&#8594;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>
  75   </p>
  76   <p>
  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.
  86   </p>
  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>
  90   <p>
  91   <table border="1">
  92     <tr>
  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>
  97     </tr>
  98     <tr>
  99       <td>Rotate View</td>
 100       <td>Left Click and Drag</td>
 101       <td>Left Click and Drag</td>
 102       <td>Click and Drag</td>
 103     </tr>
 104     <tr>
 105       <td>Zoom</td>
 106       <td>Shift + Left Click<br> drag mouse up or down
 107       </td>
 108       <td>Shift + Left Click<br> or middle button<br>
 109         drag mouse up or down
 110       </td>
 111       <td>Left-Alt + Click and drag mouse up or down</td>
 112     </tr>
 113     <tr>
 114       <td>Select/<br> Deselect<br> Residue
 115       </td>
 116       <td>Left Click</td>
 117       <td>Left Click</td>
 118       <td>Click</td>
 119     </tr>
 120     <tr>
 121       <td>Roll View</td>
 122       <td>Shift + Left Click<br> drag mouse to left or right
 123       </td>
 124       <td>Shift + Left Click<br> or middle button<br>
 125         drag mouse to left or right
 126       </td>
 127       <td>Left-Alt + Click and drag mouse to left or right</td>
 128     </tr>
 129     <tr>
 130       <td>Move Origin</td>
 131       <td>Shift+Control+Left Click<br> or Middle Button<br>
 132         + Drag
 133       </td>
 134       <td>Middle-Button<br> and<br> drag
 135       </td>
 136       <td>Shift+Control+Left Click<br> or Middle Button<br>
 137         and drag
 138       </td>
 139     </tr>
 140     <tr>
 141       <td>Jmol Menu</td>
 142       <td>Right-Click</td>
 143       <td>Right-Click</td>
 144       <td>Apple-Click</td>
 145     </tr>
 146   </table>
 147   </p>
 148   <p>The window has up to five menus:
 149   <ul>
 150     <li><Strong>File<br>
 151     </strong>
 152       <ul>
 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>
 160       </ul></li>
 161     <li><strong>View</strong>
 162       <ul>
 163         <li><strong>Show Chains<br>
 164         </strong><em>Select which of the PDB file's chains are to be
 165             displayed.</em></li>
 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
 172             entries:</em>
 173           <ul>
 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>
 189           </ul></li>
 190       </ul>
 191     <li><strong>Colours<br>
 192     </strong>
 193       <ul>
 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&#8594;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 &amp; 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
 216             directly.</em></li>
 217         <li><strong>Standard and User Defined Jalview
 218             colourschemes.<br>
 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>.
 223         </em></li>
 224       </ul></li>
 225     <li><strong>Jmol<br>
 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
 229         alignment view.</em>
 230       <ul>
 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)
 238         </em></li>
 239       </ul></li>
 240     <li><strong>Help<br>
 241     </strong>
 242       <ul>
 243         <li><strong>Jmol Help<br>
 244         </strong><em>Access the Jmol Help documentation in a new browser
 245             window.</em></li>
 246       </ul></li>
 247   </ul>
 248   </p>
 249   <p>
 250     <strong>Functionality provided by Jmol</strong>
 251   </p>
 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>
 260   <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.
 267   </p>
 268   <p>
 269     <strong>More Information</strong>
 270   </p>
 271   <p>
 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>.
 277   </p>
 278   </p>
 279 </body>
 280 </html>