JAL-1551 spotlessApply
[jalview.git] / 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>