help/help/html/features/pymol.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>The Pymol PDB Viewer</title>
  24 </head>
  25 <body>
  26   <p>
  27     <strong>The Pymol Viewer</strong>
  28   </p>
  29   <p>
  30     In Jalview 2.11.2, support was added for <a href="https://pymol.org/2/">Pymol</a>
  31     (https://pymol.org/2/) to be used for viewing
  32     structures opened via the <a href="structurechooser.html"><strong>&quot;View
  33         Structure Data..&quot;</strong> dialog</a>.
  34   </p>
  35   <p>
  36                 You can configure Pymol as your preferred structure viewer in
  37                 <a href="preferences.html#structure"> Preferences</a>. You can also
  38                 optionally specify the path to the Pymol program here (if it differs
  39                 from the standard paths searched by Jalview).<br /> <strong>Jalview
  40                         requires Pymol's RPC interface, which is not available in older
  41                         versions of the Pymol community edition.<br />Please make sure your
  42                         version of Pymol is up to date.
  43                 </strong>
  44         </p>
  45   <p>
  46     If you save your Jalview session as a project file, the state of any
  47     open Pymol windows will also be saved, and can be reopened by
  48     loading the project file on any machine with Pymol installed.
  49     </p>
  50         <p>
  51                 <strong>Known Limitations</strong><br /> Jalview provides an easy way
  52                 to employ Pymol for linked analysis of sequences and structures in the
  53                 same way as <a href="chimera.html">Chimera and ChimeraX</a>. There are
  54                 some limitations, however:
  55         </p>
  56         <ul>
  57                 <li>Pymol does not support some forms of legacy structural data
  58                         (e.g. the 1A70 C-alpha only PDB file included in the Jalview example
  59                         project).</li>
  60                 <li>Pymol to Jalview communication does not support transfer of
  61                         properties or highlighting sequence regions corresponding to
  62                         structure selections or mouse-overs in Pymol.</li>
  63         </ul>
  64   <p>
  65     Basic screen operations (see <a
  66       href="https://pymol.org/dokuwiki/doku.php?id=mouse">Pymol Wiki</a> at
  67     https://pymol.org/dokuwiki/doku.php?id=mouse
  68     for full details).
  69   <table border="1">
  70     <tr>
  71       <td><strong>Action</strong></td>
  72       <td><strong>Windows</strong></td>
  73       <td><strong>Unix</strong></td>
  74       <td><strong>Mac/OSX</strong></td>
  75     </tr>
  76     <tr>
  77       <td>Rotate View</td>
  78       <td>Left Click and Drag</td>
  79       <td>Left Click and Drag</td>
  80       <td>Left Click and Drag</td>
  81     </tr>
  82     <tr>
  83       <td>Zoom</td>
  84       <td>Right Click<br> drag mouse up or down
  85       </td>
  86       <td>Right Click<br>drag mouse up or down
  87       </td>
  88       <td>cmd or Right + Click and drag mouse up or down, <br>or
  89         use mouse scroll button
  90       </td>
  91     </tr>
  92     <tr>
  93       <td>Move Origin</td>
  94       <td>Middle Button + Drag</td>
  95       <td>Middle Button and drag</td>
  96       <td>alt + Click<br> and drag
  97       </td>
  98     </tr>
  99     <tr>
 100       <td>Select Residues</td>
 101       <td>Ctrl + Click (and drag to select a region)</td>
 102       <td>Ctrl + Click (and drag)</td>
 103       <td>Ctrl + Click (and drag)</td>
 104     </tr>
 105   </table>
 106   </p>
 107   <p>
 108     <strong>Jalview Controls</strong>
 109   <p>The Jalview Pymol View window has up to five menus:</p>
 110   <ul>
 111     <li><Strong>File<br>
 112     </strong>
 113       <ul>
 114         <li><strong>View Mapping<br>
 115         </strong><em> Opens a text window showing the alignment between the
 116             residues corresponding to alpha-carbon atoms in the PDB
 117             structure and the residues in the associated sequence.</em></li>
 118       </ul></li>
 119     <li><strong>View</strong>
 120       <ul>
 121         <li><strong>Show Chains<br>
 122         </strong><em>Select which of the PDB file's chains (if more than
 123             one) are to be displayed.</em></li>
 124         <li><strong>Colour by ..<br></strong><em>Submenu
 125             allowing specific alignment views to be selected for
 126             colouring associated chains in the structure display. This
 127             menu contains all the alignment views associated with the
 128             structure view, with those used to colour the view indicated
 129             by ticks. Addditionally, it contains the following menu
 130             entries:</em>
 131           <ul>
 132             <li><strong>Select many views<br></strong><em>When
 133                 this option is enabled, selecting an alignment view adds
 134                 it to the set used to colour the structures. Use this
 135                 when colouring structures related to a number of
 136                 alignments involving different domains or chains which
 137                 are shown in the same structure view.</em></li>
 138             <li><strong>Select all views<br></strong><em>This
 139                 is only enabled when </em><strong>Select many views</strong><em>
 140                 is also enabled, and will add all associated views to
 141                 the set used to colour the structure display.</em></li>
 142             <li><strong>Invert selection<br></strong><em>This
 143                 is only enabled when </em><strong>Select many views</strong><em>
 144                 is also enabled, and will replace the current set of
 145                 views with any remaining views not currently used to
 146                 colour the structure display.</em></li>
 147           </ul></li>
 148       </ul>
 149     <li><strong>Colours<br>
 150     </strong>
 151       <ul>
 152         <li><strong>By Sequence<br>
 153         </strong><em> Colours each residue in the structure with the colour
 154             of its corresponding residue in the associated sequence as
 155             rendered in the associated alignment views, including any
 156             UniProt sequence features or region colourings.<br />Pick
 157             which of the associated alignment views are used to colour
 158             the structures using the <strong>View&#8594;Colour
 159               by ..</strong> sub menu.
 160         </em><br> Residues which only exist in the PDB structure are
 161           coloured white if they are insertions (relative to the
 162           associated sequence in the alignment) and grey if they are N
 163           or C terminal flanks outside the region mapped to the
 164           alignment window's sequence.</em></li>
 165         <li><strong>By Chain<br>
 166         </strong><em>Uses Pymol's 'spectrum(chain)' command to apply a
 167             different colour to each chain.</em></li>
 168         <li><strong>Charge &amp; Cysteine<br>
 169         </strong><em> Highlights cysteines in yellow, anionic (Aspartic Acid
 170             or Glutamic Acid) residues in red, and cationic (Lysine or
 171             Arginine) residues in blue.</em></li>
 172         <li><strong>Colour with Pymol<br></strong><em>Defers
 173             any colouring operations to Pymol. Select this if you want
 174             to use the Pymol scripting interface or menu to modify the
 175             view directly.</em></li>
 176         <li><strong>Standard and User Defined Jalview
 177             colourschemes.<br>
 178         </strong><em>The remaining entries apply the colourschemes available
 179             from the standard and user defined <a
 180             href="../colourSchemes/index.html">amino acid
 181               colours</a>.
 182         </em></li>
 183       </ul></li>
 184     <li><strong>Pymol<br>
 185     </strong><em>This pulldown menu provides access to Pymol's capabilities from Jalview.</em>
 186       <ul>
 187         <li><strong><a name="sAlign">Align</a> <br> </strong><em>
 188             When selected, the associated alignment will be used to
 189             superimpose all the structures in the view onto the first
 190             structure in the alignment. The regions used to calculate
 191             the superposition will be highlighted using the 'Cartoon'
 192             rendering style, and the remaining data shown as a chain
 193             trace.<br />
 194           <br />
 195         </em></li>
 196         <li><a name="annotxfer"><strong>Write Jalview
 197               features</strong></a><br /> <em>Selecting this option will create
 198             new atom properties for any features currently visible in
 199             the associated alignment views. This allows those atoms to
 200             be selected and analysed in Pymol directly.
 201         </em><br>
 202         <ul><li>Feature transfer in Pymol is experimental.</li><li>To select by a particular feature use the string matching syntax:<br>
 203         select foo,p.jv_helix in helix
 204         </li>
 205         <li>To view transferred properties use Pymol's Properties Inspector</li><li>
 206         For more information see <a href="https://pymol.org/dokuwiki/doku.php?id=properties#selection_language">Property based selection in Pymol's Documentation</a>.
 207         </li>
 208         </ul>
 209         </li>
 210       </ul></li>
 211     <li><strong>Help<br>
 212     </strong>
 213       <ul>
 214         <li><strong>Pymol Help<br>
 215         </strong><em>Access the Pymol Help documentation in a new browser window.
 216             window.</em></li>
 217       </ul></li>
 218   </ul>
 219   <p>
 220     <strong>Pymol and Windows Firewall</strong>
 221   </p>
 222   Jalview and Pymol communicate using the <a href="https://pymolwiki.org/index.php/RPC">Pymol's XML-RPC over HTTP interface</a>(https://pymolwiki.org/index.php/RPC).
 223
 224 <br> Technically this requires both Pymol and Jalview to open
 225   ports on the local network, and this may be blocked by Windows
 226   Firewall with a warning message such as
 227   <br /> "Windows Firewall has blocked some features of this program"
 228   (where the program may be java.exe or javaw.exe).
 229   <br /> To allow Jalview and Pymol to interact, you may need to add
 230   permission for the program to communicate over the network. This can
 231   be done from the warning dialogue, or in Control Panel, Firewall
 232   settings.
 233 </body>
 234 </html>