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