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