3 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4 * Copyright (C) $$Year-Rel$$ The Jalview Authors
6 * This file is part of Jalview.
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.
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.
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.
23 <title>The Pymol PDB Viewer</title>
27 <strong>The Pymol Viewer</strong>
30 In Jalview 2.11.2, support was added for viewing structures opened
31 via the <a href="structurechooser.html"><strong>"View
32 Structure Data.."</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.
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.
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.
54 <strong>Known Limitations</strong><br />
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
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).
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>
80 <td>Left Click and Drag</td>
81 <td>Left Click and Drag</td>
82 <td>Left Click and Drag</td>
86 <td>Right Click<br> drag mouse up or down
88 <td>Right Click<br>drag mouse up or down
90 <td>cmd or Right + Click and drag mouse up or down, <br>or
91 use mouse scroll button
96 <td>Middle Button + Drag</td>
97 <td>Middle Button and drag</td>
98 <td>alt + Click<br> and drag
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>
110 <strong>Jalview Controls</strong>
111 <p>The Jalview Pymol View window has up to five menus:</p>
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>
121 <li><strong>View</strong>
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
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>
151 <li><strong>Colours<br>
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→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 & 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
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>.
185 <li><strong>Pymol<br>
186 </strong><em>This pulldown menu provides access to Pymol's capabilities
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 />
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>
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
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>.
218 <li><strong>Pymol Help<br>
219 </strong><em>Access the Pymol Help documentation in a new browser
220 window. window.</em></li>
224 <strong>Pymol and Windows Firewall</strong>
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).
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