JAL-1551 spotlessApply
[jalview.git] / help / help / html / features / chimera.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 Chimera PDB Viewer</title>
24 </head>
25 <body>
26   <p>
27     <strong>The Chimera and ChimeraX Viewers</strong>
28   </p>
29   <p>
30     Since Jalview 2.8.2, <a href="http://www.cgl.ucsf.edu/chimera/">Chimera</a>
31     (http://www.cgl.ucsf.edu/chimera/) can be used for viewing
32     structures opened via the <a href="structurechooser.html"><strong>&quot;View
33     Structure Data..&quot;</strong> dialog</a>. In Jalview 2.11.2, support 
34     was also added for ChimeraX, and <a href="pymol.html">Pymol</a>.
35   </p>
36   <p>
37     You can set a default choice of Jmol or Chimera structure viewer in
38     <a href="preferences.html#structure"> Preferences</a>. You can also
39     optionally specify the path to the Chimera program here (if it
40     differs from the standard paths searched by Jalview).<br /> <strong>Please
41       make sure your version of Chimera is up to date. Jalview requires
42       at least Chimera version 1.11.1</strong>
43   </p>
44   <p>
45     If you save your Jalview session as a project file, the state of any
46     open Chimera windows will also be saved, and can be reopened by
47     loading the project file on any machine with Chimera installed. <em>Since
48       Jalview 2.9.</em>
49   <p>
50     <a name="align"><strong>Superposing structures based on
51         their aligned sequences</strong></a><br> If several structures are
52     available on the alignment, you may add additional structures to an
53     existing Chimera view by selecting their entry in the appropriate
54     pop-up menu. Jalview will ask you if you wish to add the structure
55     to the existing alignment, and if you do, it will import and
56     superimpose the new PDB file using the corresponding positions from
57     the alignment. If the alignment is subsequently edited, you can use
58     the <a href="#sAlign"><em>Chimera&#8594;Align</em></a> menu option
59     from the menu bar of the structure view window to superpose the
60     structures using the updated alignment.<br>
61   </p>
62   <p>
63     <strong>Chimera Controls</strong><br> The structure is by
64     default rendered as a ribbon diagram. Moving the mouse over the
65     structure brings up tooltips giving the residue name, PDB residue
66     number and chain code ([RES]Num:Chain). Moving the mouse over an
67     associated residue in an alignment window highlights the associated
68     atoms in the displayed structures. When residues are selected in the
69     Chimera window, they are highlighted on the alignment.
70   <p>For comprehensive details of Chimera's commands, refer to the
71     tool's Help menu.</p>
72   <p>
73     <strong>Selecting residues in Jalview from Chimera</strong><br />
74     When a selection is highlighted in a Jalview window, use the
75     <em>Select&#8594;Select Highlighted Region</em> or press <em>B</em>
76     to add the mapped positions to the alignment window's column
77     selection.<br /> <em>Hint: Use your machine's 'switch
78       application' key combination (Alt-Tab on Windows and Linux,
79       Cmd-Tab on OSX) to quickly switch between UCSF Chimera and Jalview
80       before pressing 'B' to select highlighted regions.</em>
81   </p>
82   <p>
83     Basic screen operations (see <a
84       href="http://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/mouse.html">Chimera
85       help</a> at
86     http://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/mouse.html
87     for full details).
88   <table border="1">
89     <tr>
90       <td><strong>Action</strong></td>
91       <td><strong>Windows</strong></td>
92       <td><strong>Unix</strong></td>
93       <td><strong>Mac/OSX</strong></td>
94     </tr>
95     <tr>
96       <td>Rotate View</td>
97       <td>Left Click and Drag</td>
98       <td>Left Click and Drag</td>
99       <td>Left Click and Drag</td>
100     </tr>
101     <tr>
102       <td>Zoom</td>
103       <td>Right Click<br> drag mouse up or down
104       </td>
105       <td>Right Click<br>drag mouse up or down
106       </td>
107       <td>cmd or Right + Click and drag mouse up or down, <br>or
108         use mouse scroll button
109       </td>
110     </tr>
111     <tr>
112       <td>Move Origin</td>
113       <td>Middle Button + Drag</td>
114       <td>Middle Button and drag</td>
115       <td>alt + Click<br> and drag
116       </td>
117     </tr>
118     <tr>
119       <td>Select Residues</td>
120       <td>Ctrl + Click (and drag to select a region)</td>
121       <td>Ctrl + Click (and drag)</td>
122       <td>Ctrl + Click (and drag)</td>
123     </tr>
124   </table>
125   </p>
126   <p>
127     <strong>Jalview Controls</strong>
128   <p>The Jalview Chimera View window has up to five menus:</p>
129   <ul>
130     <li><Strong>File<br>
131     </strong>
132       <ul>
133         <li><strong>View Mapping<br>
134         </strong><em> Opens a text window showing the alignment between the
135             residues corresponding to alpha-carbon atoms in the PDB
136             structure and the residues in the associated sequence.</em></li>
137       </ul></li>
138     <li><strong>View</strong>
139       <ul>
140         <li><strong>Show Chains<br>
141         </strong><em>Select which of the PDB file's chains (if more than
142             one) are to be displayed.</em></li>
143         <li><strong>Colour by ..<br></strong><em>Submenu
144             allowing specific alignment views to be selected for
145             colouring associated chains in the structure display. This
146             menu contains all the alignment views associated with the
147             structure view, with those used to colour the view indicated
148             by ticks. Addditionally, it contains the following menu
149             entries:</em>
150           <ul>
151             <li><strong>Select many views<br></strong><em>When
152                 this option is enabled, selecting an alignment view adds
153                 it to the set used to colour the structures. Use this
154                 when colouring structures related to a number of
155                 alignments involving different domains or chains which
156                 are shown in the same structure view.</em></li>
157             <li><strong>Select all views<br></strong><em>This
158                 is only enabled when </em><strong>Select many views</strong><em>
159                 is also enabled, and will add all associated views to
160                 the set used to colour the structure display.</em></li>
161             <li><strong>Invert selection<br></strong><em>This
162                 is only enabled when </em><strong>Select many views</strong><em>
163                 is also enabled, and will replace the current set of
164                 views with any remaining views not currently used to
165                 colour the structure display.</em></li>
166           </ul></li>
167       </ul>
168     <li><strong>Colours<br>
169     </strong>
170       <ul>
171         <li><strong>By Sequence<br>
172         </strong><em> Colours each residue in the structure with the colour
173             of its corresponding residue in the associated sequence as
174             rendered in the associated alignment views, including any
175             UniProt sequence features or region colourings.<br />Pick
176             which of the associated alignment views are used to colour
177             the structures using the <strong>View&#8594;Colour
178               by ..</strong> sub menu.
179         </em><br> Residues which only exist in the PDB structure are
180           coloured white if they are insertions (relative to the
181           associated sequence in the alignment) and grey if they are N
182           or C terminal flanks outside the region mapped to the
183           alignment window's sequence.</em></li>
184         <li><strong>By Chain<br>
185         </strong><em>Uses the Chimera 'rainbow chain' command to apply a
186             different colour to each chain.</em></li>
187         <li><strong>Charge &amp; Cysteine<br>
188         </strong><em> Highlights cysteines in yellow, anionic (Aspartic Acid
189             or Glutamic Acid) residues in red, and cationic (Lysine or
190             Arginine) residues in blue.</em></li>
191         <li><strong>Colour with Chimera<br></strong><em>Defers
192             any colouring operations to Chimera. Select this if you want
193             to use the Chimera scripting interface or menu to modify the
194             view directly.</em></li>
195         <li><strong>Standard and User Defined Jalview
196             colourschemes.<br>
197         </strong><em>The remaining entries apply the colourschemes available
198             from the standard and user defined <a
199             href="../colourSchemes/index.html">amino acid
200               colours</a>.
201         </em></li>
202       </ul></li>
203     <li><strong>Chimera<br>
204     </strong><em>This pulldown menu is only displayed if there are multiple
205         structures shown in the Chimera window, and Jalview can also
206         locate at least two of the structures in the currently
207         associated alignment view.</em>
208       <ul>
209         <li><strong><a name="sAlign">Align</a> <br> </strong><em>
210             When selected, the associated alignment will be used to
211             superimpose all the structures in the view onto the first
212             structure in the alignment. The regions used to calculate
213             the superposition will be highlighted using the 'Cartoon'
214             rendering style, and the remaining data shown as a chain
215             trace.<br />
216           <br />
217         </em></li>
218         <li><a name="annotxfer"><strong>Write Jalview
219               features</strong></a><br /> <em>Selecting this option will create
220             new residue attributes for any features currently visible in
221             the associated alignment views, allowing those positions to
222             be selected and analysed with via Chimera's 'Render by
223             Attribute' tool (found in the Tools submenu called Structure
224             Analysis).<br /> <br />If you use this option, please
225             remember to select the <em>Refresh Menus</em> option in
226             Chimera's Render by Attribute dialog box in order to see the
227             attributes derived from Jalview sequence features.
228         </em></li>
229         <li><strong>Fetch Chimera Attributes</strong><br /> <em>This
230             submenu lists available Chimera residue attributes that can
231             be imported as Jalview features on associated sequences.<br />This
232             is particularly useful for transferring quantitative
233             positional annotation. For example, structure similarity for
234             an alignment can be visualised by transferring the local
235             RMSD attributes generated by Chimera's Match->Align tool
236             onto aligned sequences and displayed with a <a
237             href="featureschemes.html">Graduated feature colour
238               scheme</a>. </li>
239       </ul></li>
240     <li><strong>Help<br>
241     </strong>
242       <ul>
243         <li><strong>Chimera Help<br>
244         </strong><em>Access the Chimera Help documentation in a new browser
245             window.</em></li>
246       </ul></li>
247   </ul>
248   <p>
249     <strong>Chimera and Windows Firewall</strong>
250   </p>
251   Jalview and Chimera communicate using Chimera's
252   <a
253     href="http://www.cgl.ucsf.edu/chimera/current/docs/ContributedSoftware/restserver/restserver.html">REST
254     service</a>
255   (http://www.cgl.ucsf.edu/chimera/current/docs/ContributedSoftware/restserver/restserver.html).
256   <br> Technically this requires both Chimera and Jalview to open
257   ports on the local network, and this may be blocked by Windows
258   Firewall with a warning message such as
259   <br /> "Windows Firewall has blocked some features of this program"
260   (where the program may be jp2launcher.exe for Jalview Webstart, or
261   java.exe or javaw.exe for the InstallAnywhere version).
262   <br /> To allow Jalview and Chimera to interact, you may need to add
263   permission for the program to communicate over the network. This can
264   be done from the warning dialogue, or in Control Panel, Firewall
265   settings.
266 </body>
267 </html>