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