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 <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>"View
33 Structure Data.."</strong> dialog</a>.
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.
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.
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:
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
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>
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
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>
78 <td>Left Click and Drag</td>
79 <td>Left Click and Drag</td>
80 <td>Left Click and Drag</td>
84 <td>Right Click<br> drag mouse up or down
86 <td>Right Click<br>drag mouse up or down
88 <td>cmd or Right + Click and drag mouse up or down, <br>or
89 use mouse scroll button
94 <td>Middle Button + Drag</td>
95 <td>Middle Button and drag</td>
96 <td>alt + Click<br> and drag
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>
108 <strong>Jalview Controls</strong>
109 <p>The Jalview Pymol View window has up to five menus:</p>
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>
119 <li><strong>View</strong>
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
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>
149 <li><strong>Colours<br>
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→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 & 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
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
184 <li><strong>Pymol<br>
185 </strong><em>This pulldown menu provides access to Pymol's capabilities from Jalview.</em>
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
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.
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
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>.
214 <li><strong>Pymol Help<br>
215 </strong><em>Access the Pymol Help documentation in a new browser window.
220 <strong>Pymol and Windows Firewall</strong>
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).
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