Scene authoring tools

From Proteopedia

proteopedia linkproteopedia link

The Scene authoring tool (SAT) is used to create and edit molecular scenes. Scenes created using the Scene authoring tool can then be inserted into Proteopedia pages. This is a reference page explaining the details once you are familiar with the basics. For a tutorial introduction, see Instructions for creating a molecular scene with Proteopedia's Scene Authoring Tools, and watch the introductory videos, e.g. [1].

Contents 1 Where are the Scene authoring tools? 2 Overview 3 'load molecule' tab 4 'load scene' tab 5 Controls below the Jmol window 5.1 Advanced controls 6 'selections' tab 6.1 build your selection 6.2 invert and center 6.3 select within distance 6.4 mouse click selects 7 'representations' tab 7.1 set selection representation 7.2 disulfide and hydrogen bonds 8 'colors' tab 8.1 color 8.2 transparency 9 'labels' tab 9.1 mouse click selects 9.2 label selected atoms 9.3 measurements 10 'save scene' tab 10.1 'advanced options' : choosing a non-standard scene transition 11 Manipulating Jmol with your mouse 12 Using Jmol's Command Language 13 Notes

Where are the Scene authoring tools?

The Scene authoring tools are accessible when you are editing a page. Click the tab edit this page at the top of the page where you wish to create a molecular scene. On the edit page, near the top, you'll see a big box where all the wikitext of the page lives--here you can change the text of the page. If you scroll down some, near the bottom, you'll find in bold letters SAT (Scene authoring tools) [show]. Click on show to expand and open the Scene authoring tools. If, however, the page does not contain a Jmol window yet (no <Structure> or <StructureSection> tags), the page will lack access to the SAT. In this case, first edit the page to include a Jmol window (using the buttons above the text-editing area), save and then edit again to see the link to the SAT. New pages have placeholder content that includes these tags, but this page for example does not.

Overview

A good place to start is the Video on Adding Scenes. Next you may want to look at the Instructions for creating a molecular scene with Proteopedia's Scene Authoring Tools for tutorial examples.

The Scene authoring tools are meant to make scene management easier and to make scene creation easier. Scenes are 3D representations of molecules that someone viewing the page can load into the Jmol viewer by clicking on green links. A scene stores viewpoint, representations, colors, labels, and generally everything that is necessary to recreate the way things looked when the scene was saved.

The steps of using the Scene authoring tools are as follows, with one or more tabs in the user interface for every step:

1. Either load an existing scene using the 'load scene' tab, or start fresh with the 'load molecule' tab.
2. Select parts of the structure.
3. For the selected parts of the structure, choose how to represent it, colors and labels
4. Manipulate the scene view using the mouse to get a good initial view. Make sure it is centered in a way to make it easy for the viewer to explore.
5. Provide a figure caption, decide on whether the scene will be displayed, and save the scene with a meaningful name.
6. Inserting the scene into the Proteopedia page.

Creating the 3D scene is mostly done with the controls available via the tabs, while the right side of the user interface is a Jmol viewer to preview the scene as it is built.

There is a printable cheat sheet available giving an overview of the workflow and of the available choices Image:SAT overview.pdf.

'load molecule' tab

The load molecule tab is used to load molecules into Jmol.

To load a file that has a PDB ID, input the ID into the first input area and click the load button. The file will be fetched from the PDB database.

To load a file that is not part of the PDB, first upload the file to Proteopedia at Special:Upload (you can get there also by using the link called 'upload file' on the left hand column-toolbar of Proteopedia). Once a file has been uploaded, you can specify its name in the input area next to the words "From Proteopedia uploaded file" and click load.

Uploaded file can have various formats recognized by Jmol's "load" command. For example, you can load a .PNGJ file to load coordinates and a 3D scene in one step.

There is a checkbox to add calculated positions of hydrogen atoms to the structure as it is loaded. This allows to show the multiplicity of bonds (i.e. whether a bond is a single, double or triple bond) in the 3D scenes.

Another optional field allows to enter instructions that will be used to filter which atoms of the original model will be either loaded or ignored. For example, to load just the alpha carbons, to exclude water, include or exclude other hetero groups (ligands), load a specified biomolecule (biological unit), etc. See Biological Unit: Showing for instructions. You can also check the Jmol Scripting Documentation for details about the syntax of such filter specifications (in that page, search for load "filename" FILTER).

'load scene' tab

The first box shows the current page name. First, you proceed to choose the scene name using the drop-down selector. All scenes associated with the scenes inserted in the page you edit will be listed (see remixing scenes) . Once a scene is selected, all of its versions are available for selection using the drop-down version number menu. When a version number is selected, that version of the scene is loaded onto the Jmol applet that is part of the Scene authoring tools and the description and caption that were given to the scene are also recalled. At the same time, the wikitext that is needed for insertion of the scene into the page is displayed.

Each distinct scene has 4 parameters to distinguish it from all other scenes: domain, pageId, scenename, and versionnumber (e.g. 77/778341/Ballstick/1). The domain are the first two digits of the pageId, and the pageId is the unique internal identifier of the Proteopedia page on which the scene was initially created. The scenename is given by the user. The versionnumber is incremental: If no scene by the given name exists for the given page, then the first version will be version 1. If there exist previous versions of the same scenename on the same pagename, then the newest saved version will not overwrite older versions of the scene, but will instead be automatically saved as the newest version (by incrementing the versionnumber by one). To find out which page is associated with a scene, create the URL of the script by prepending "proteopedia.org/wiki/scripts/" and appending ".spt". e.g. the scene called 77/778341/Ballstick/1 is stored at [2]. Inspection of the first couple of lines of the file shows, after the keyword "documentBase", that it originated from a user page.

Controls below the Jmol window

These controls are available no matter which tab is open. The first line is informational, only; the "currently loaded" text area displays the name of the currently loaded file and its datestamp. Below that, you can select "ALL" or "NONE" to quickly select all or no atoms. To see which atoms are selected, use the controls next to "Show Selected with Halos". If you have something selected, you will see your selection highlighted by yellow halos. These halos are NOT part of your scene and have no impact other than to indicate to you what atoms are currently selected.

The "<-Undo" and "Redo->" controls allow you to quickly correct mistakes, or to compare before and after changing the scene.

Advanced controls

Opening the JSmol console allows you to get more information from Jmol (e.g. the command "show sequence" shows all the residues/groups that contain selected atoms). For one-line commands (e.g. "set zshade on") without feedback from the console, you can use the text input field and the "execute" button. More usage examples are at Jmol/Using the console and Jmol/Useful one-liners.

'selections' tab

It is advised that you use selection halos while creating or modifying a selection to make sure your selection is the one you want before you change the scene.

The selections tab is used to select particular groups of atoms so that you can later change that group's color, representations, or labels. When you choose a representation, a color, or a label using the Scene authoring tools other tabs, the change is almost always applied ONLY to the currently selected atoms. That is why it is important to be aware of what atoms are selected at any given time.

build your selection

In the "build your selection" box, you can select by group, sites, chains, residue types, residue numbers and chemical elements. For example, you could select all sulfur atoms in cysteine residues of chain B of the model by entering those specifications (see input in picture above). The buttons below determine what happens to the selection you just built. You can use it as your new selection ("replace selection") or you can combine it with the current selection in different ways ("add to selection", "remove from selection").

Each input box allows you to specify certain parameters in order to best choose what to add or remove to/from your selection. There is an imaginary 'AND' (or intersection) connecting each input box (a Boolean AND), but an 'OR' (or union) connecting the chosen elements within each input box. What this means is that if you choose in the 'groups' box the items 'all protein' and 'dna' and in the 'limit to elements' box you type in 'C,O' and click "add to selection", then you will add to your selection all the carbon and oxygen atoms that are part of either the protein or the dna in your loaded file (it's like saying "(all protein OR dna) AND (carbon OR oxygen)" )

The 'groups' selector lists various pre-defined groups of atoms by name. You can select more than one item by pressing the <ctrl> key while selecting items. The 'limit to chains' box allows you to choose specific chains by the names they are given in the loaded file (ex: A,C,D). The 'limit to resi types' allows specification of residues by their 3-letter codes (ex: PHE,ALA,GLY). The 'limit to residue nos' box allows specification of residues by their number (ex: 18,23-25,32). The 'limit to elements' box allows choosing specific elements or even specific isotopes (ex: Fe,2H,31P). The 'limit to atom nos' box allows specifying atoms by their number. The 'sites' box appears only if your file is a PDB file that has predefined sites that the authors defined when they submitted the file to the Protein Data Bank.

The button 'add to selection' checks the information that was specified by you in the boxes in the 'add to or remove from selection' area and then adds what you specified into the current selection. The 'remove from selection' does the same, but rather than adding to the current selection, it removes from the current selection.

invert and center

The "invert current selection" button selects everything that was not selected. The "center on current selection" places the center of rotation (when you or the reader of the page changes the orientation of the displayed structure with the mouse, or when spinning is on) on the currently selected atoms.

select within distance

The "select within distance" box allows you to select atoms within a specified distance form the currently selected atoms (these will remain selected). For example, if you had a ligand selected, and then specify a distance of 4 A and hit 'go', then all atoms within 4 Angstroms of that ligand would be added to your selection. Your selection would then be composed of the ligand as well as all atoms within 4 Angstroms of it.It also allows you to expand the selection to entire residues (or more generally "groups", i.e entire ligand, or building block of nucleic acids and carbohydrates).

mouse click selects

The "mouse click selects" allows you to change the effect of a mouse click from nothing to centering on the atom, or selecting all atoms of the same chemical elements by clicking on one of them, or selecting an entire group("residue/ligand") or an entire chain by clicking on one atom in it.

Choosing 'default' sets it so that mouse clicks on the Jmol applet are set to their default setting in Jmol. In the default setting, clicking does not select or deselect any atoms, but clicking to create measurements is enabled. Choosing 'center' makes it so that any click on an atom, centers both the view and the axis of rotation on the atom. Choosing 'atom' is perhaps the most useful setting for creating selections as each click on an atom either adds it to the selection, or if it is already part of the selection, removes it from the selection. Choosing 'element' makes it so that clicking on an atom will select all other atoms of the same element. Choosing 'molecule' makes it so that clicking on an atom selects all other atoms of the same molecule.

'representations' tab

This contains commands to draw selected parts of the structure, using different representations.

set selection representation

The 'set selection representation' box provides a variety of choices for setting the representation of the current selection. Multiple representations can be turned on for the same selection of atoms (for instance using both wireframe and spacefill can create a 'ball and stick' scheme). Click on the representations that you would like to turn on for your current selection and then press 'set representation'. Every representation that has been checked off (to the left of the representation's name) will be displayed. Some representations have an input field to their direct right. If they do, then you may enter values in order to change the form of the representation, usually its size. If you leave the input field blank, the default will be used.

Clicking on 'hide selection' turns off all representations for the selection.

disulfide and hydrogen bonds

This box allows you to choose how (covalent) disulfide bonds and (non-covalent) hydrogen bonds are drawn between the selected atoms. For disulfide bonds, you can use a schematic connecting the C-alpha carbon atoms of the backbone (appropriate when showing a backbone representation such as a cartoon) or the actual bonds between two sulfur atoms (appropriate when showing the side chain atoms, e.g. as ball-and-stick).

'colors' tab

Here, you can color the current selection, the background and surfaces.

color

The 'color' area first lets you choose whether you would like to change the color of the current selection, or of the background. The color palette is clickable and as soon as you click on a color, either your selection or the background (as was previously selected) will change to the clicked color. Hover over a color to view its name. There is a series of buttons below the color palette, each representing a specific color scheme.

CPK is the standard CPK coloring scheme. Amino and amino2 color each amino acid as a different color. Chain colors each chain different colors. Spectrum colors protein and nucleic acids from blue to red on a spectrum with the N or 5' terminus as blue and the C or 3' terminus as red. Structure colors according to secondary structure. Fixed and relative temperature color according to temperature and formal and partial charge according to charge. DRuMS composition colors according to the DRuMS scheme (http://www.umass.edu/molvis/drums/). Hydrophobic/polar colors hydrophobic amino acids grey and polar (charged or uncharged) residues pink. Charge colors hydrophobic residues grey, polar-uncharged residues pink, cationic residues blue, anionic residues red, and backbone atoms purple whether charged or uncharged. More information on Jmol colors is available at http://jmol.sourceforge.net/jscolors/.

transparency

The 'transparency' area allows you to render your selection transparent. Zero percent transparent will be opaque, 100 percent transparent will be invisible, and anywhere in between will be transparent to a degree.

'labels' tab

This tab allows you to add labels to atoms that move with the atom as the structure is rotated and moved. It also also you to choose styles for measurements of distances and angles.

mouse click selects

The 'mouse click selects' area is similar to the 'mouse click selects' area in the 'selections' tab and allows changing between the 'nothing' mouse picking style and the 'atom' mouse picking style. See the 'selections' tab section above for an explanation about the different mouse picking styles.

label selected atoms

The 'label atoms' area is used to label atoms. First, an atom must be selected. Next, you choose how the label should look by choosing between entering text, displaying the atom name, the element, the 3-letter residue code, the residue number, and the chain letter of the atom being labeled (you can combine all of these options however you want). When you are ready to create the label, click on 'set label'. Note that if you have a selection of atoms when you assign a label by clicking 'set label', then each atom in the selection will get a label. 'Clear labels from selection' will clear all the labels from the current selection. To delete all labels, first 'select all' and then 'clear labels from selection'.

To change the label properties, you can choose label color, label size, and an optional pointer from the label to the atom.

measurements

The 'measurements' area allows control over the appearance of measurements. Measurements can be created by a combination of double and single clicking on atoms while in the 'default' mouse picking setting. Measurements are explained in the 'how to' tab of the Scene authoring tools. Here in the 'measurements' area, you can control the color, size, and units of the measurements. Changing the color or the size will affect all existing and future measurements but changing the units will only affect future measurements. The labels on the measurements can also be turned off or on.

'save scene' tab

Once you have created your scene, you can save it here.

You must choose a name for your scene, and enter a description and a caption. The caption is displayed under the Jmol window when the scene is loaded. If you started by loading a scene, then by default, its name will appear as a suggested name for the scene you are about to save because Proteopedia assumes you might be editing a scene to save an updated version. If you specify the name of a scene that already exists, then your scene will be saved as the newest version (i.e. if versions 1 through 5 for that scene already exist, then your scene will be saved as version 6).

After saving, wikitext for inserting your scene into the Proteopedia page will appear in the 'Wikitext' area, and a button for turning a selected word into a green link.

'advanced options' : choosing a non-standard scene transition

If you select the checkbox entitled 'advanced options', you get two choices for non-standard transitions. This means you can choose different transitions for how your scene will be recalled when the user clicks on the green scene link. Here's the breakdown of transition options:

1. If you don't select any checkbox (i.e. do not select the checkbox next to "show advanced options") then the most basic and standard transition will be used : when the scene is recalled, the molecule will zoom out to 100% zoom, rotate to the new scene's orientation, and then zoom to the new scene's correct zoom.
2. If you select the checkbox next to "show advanced options" you then have two advanced options to choose from:
   1. If you choose "yes" from the drop-down menu next to "skip the zoom-out when this scene loads" then the transition will be the same as the basic transition except the zoom-out to 100% zoom will be skipped : when the scene is recalled, the molecule will rotate to the new scene's orientation and zoom simultaneously.
   2. If instead you choose "yes" from the drop-down menu next to "skip the transition between scenes when this scene loads" then the new scene will just immediately load, without any transition from the previous scene.

Option 1 is the standard. Option 2.1 is helpful when the view is not changing much and you don't want the scene to zoom out completely when transitioning between scenes. Option 1 is helpful when zooming out completely is necessary to give the user proper spatial comprehension when transitioning between two scenes. Option 2.2 is helpful when you really need to have no transition at all (although it should be rarely used except for extreme cases where you really need no transition).

Manipulating Jmol with your mouse

• Rotate: left click
• Zoom: scroll button or left click + shift
• Drag: right click + ctrl
• Measure distance: dbl click on 1st atom, dbl click on 2nd atom
• Measure angle: dbl click on 1st atom, click on 2nd atom, dbl click on 3rd atom
• Measure dihedral angle:' dbl click on 1st atom, click on 2nd and 3rd atoms, dbl click on 4th atom

Using Jmol's Command Language

Jmol has an extensive and powerful command language^[1]. Users interested in learning the command language can use it within the Scene Authoring Tools.

• Edit the page, and Show the Molecular Scene Authoring Tools.
• Click on the Jmol frank within the Jmol applet (lower right from the molecule).
• In Jmol's Main Menu, click on Console.

You can enter commands in the bottom portion of the Console. Once you get a scene that you like, save it in the normal way. It doesn't matter how a scene is obtained in Jmol -- it is saved as a state script which reflects the state of Jmol regardless of the path used to arrive at that state.

The Undo button below Jmol in the Scene Authoring Tools is very useful when you want to undo a command entered via Jmol's Console.

It is also possible to import scenes from other Jmol websites, using a state script. See, for example, Help:Copying FirstGlance Scenes into Proteopedia. Or you might develop a scene in the Jmol Application (as distinct from the Applet) and then transfer the state script.

Notes

1. ↑ Documentation for Jmol's command language is available from Jmol.Org. An overview is at jmol.org/docs, and additional coverage of specific topics is at the Jmol Wiki. The command reference manual is at Jmol Scripting Documentation.