jmol enhanced figure toolkit

Previous

Top

Next

Introduction Why Jmol? When to use an enhanced figure How to submit an enhanced figure An introductory tutorial Tutorial 2: an inorganic crystal lattice Tutorial 3: a small metal-organic molecule Tutorial 4: a biological macromolecule molecule Toolkit options reference Some Jmol resources Acknowledgements Appendix: useful Jmol commands

Tutorial 2: an inorganic crystal lattice

Lesson 1: using the standard palette functions

In this second tutorial, we revisit the inorganic structure sk3182 and use it to develop a number of new skills, from the perspective of an author who is not familiar with Jmol.

Begin again with Fig. 5, representing a structure that has just been uploaded. The first option that you see, just below the visualization window, allows you to change the size of the applet. The default size (640 x 512 pixels) is a standard size used in the online journals, and should be used unless there is a good reason not to. Suppose in this case that the Co-editor agrees that a square format figure better displays the symmetry down the c axis of the tetragonal lattice, and so change the height to 640 pixels. (In general, changes to the width should only be made with the agreement of the Co-editor.) You should now save the figure before doing anything else. (Again, use the primary save button at this stage.)

Now consider the tabs allowing you to switch between different editing palettes. The tabs that are present (and their contents) depend on the type of structure. For inorganic structures, as in this example, the tabs that provide particular Jmol functions are entitled

• preview: allows testing of any scripts used in the enhanced figure
• general: for overall aspects of style or representation
• crystallography: for illustrating aspects of the structure arising from crystallographic symmetry
• select/label: for selecting and labelling individual atoms or groups of atoms
• ellipsoids: for drawing atomic displacement ellipsoids
• polyhedra: for drawing coordination polyhedra
• special: for some special effects

For biological macromolecules, a structure tab allowing different stylised representations of secondary structure replaces the polyhedra tab; for small-molecule structures both of these are absent.

In general it is useful to work along the tabs from left to right, but you may always switch between them at any time, as appropriate.

For this example, start with the general tab. Select a black background to show the differently coloured atoms with higher contrast; then choose 'ionic radii' in the drop-down menu of atom radii.

Now move on to the crystallography tab. In the first tutorial, we selected '3 x 3 x 1' in the 'Cell packing' menu, which nicely demonstrates the symmetrical packing in the ab plane. However, in this crystal structure the novel feature is the interpenetrating sheets along the c axis, which are difficult to visualize in a single unit-cell depth. Therefore select 3 x 3 x 3 as the cell-packing option, to allow the reader to appreciate the variation with depth as the crystal structure is viewed from different angles. Zoom out (using the mouse scroll wheel, or SHIFT + left mouse button) until the image just fills the applet.

Notice that the atom radii have reverted to their default sizes. This is because the commands to generate the space-filling diagram override the existing specifications for atom sizes. You can fix this by returning to the general tab and re-selecting the required option in the 'atom radii' menu.

Now label the K ions, which have been singled out for comment in the caption. Go to the select/label tab. Jmol provides a very rich set of scripting commands to select individual atoms or groups of atoms. The buttons on this page provide access to many of these commands, but their interactions with each other are not always intuitive. The first thing that you should do, therefore, is activate the option 'selection haloes on'. This will draw a translucent yellow sphere around each atom that has been selected - initially, all of them. Now click 'none' in the main set of buttons in the 'Select items' section, and then 'by element' to restrict the selection to an individual element. Now, when you click on a K ion, all other potassiums in the structure will be simultaneously selected (Fig. 10).

Now label the K ions using the set of buttons grouped under 'Label selected items'. Select the options 'chemical symbol', 'white labels', 'centred', and leave the label size at the default value.

Now turn 'selection haloes off', so that they are not rendered in the enhanced figure. You should also click 'all' under the 'Select items' heading. This will not now have any visible effect, but will ensure that the Jmol applet presented to the reader will have the default 'select all' state active. If you do not do this, a reader who has experience of Jmol will find that the applet does not behave as expected.

Finally, select the option 'hide hydrogen atoms' on this tab, to remove visual clutter, and save the result as your new enhanced figure (Fig. 11).

Lesson 2: adding features to the enhanced image page

In this lesson you will provide options to the reader for viewing the crystal packing from different directions.

When you move the current view away from its orientation down the c axis, the large atoms clutter the view. You can obtain a better impression of the packing from different viewpoints by reverting to a simple stick representation, where only the bonds are shown. On the general tab therefore use the 'overall style' menu to select 'sticks'. The K ions are not shown as bonded, and so disappear from view (although their labels are still visible). You can address this by going to the select/label tab; select 'none' to ensure that any existing selections are cleared (again you may find it useful to switch selection haloes on while you perform these operations); select 'by element' and then click on a K ion; in the area headed 'Colour/style of selected items' choose an atomic radii value of '20% van der Waals'; select 'labels off' (you may need to select another option first); and finally select 'all' and switch selection haloes off.

All this is tedious to describe, but comes naturally with a few moments practice. The result is a more schematic view of the crystal packing (Fig. 12).

Now go to the button scripts tab (Fig. 13). This allows you to input up to four Jmol scripts, each of which will be associated with a button on the enhanced image page that will run this script when selected by the reader.

For the moment, we suppose that you do not know any commands in the Jmol scripting language. Nevertheless, you can still make use of this page. Click on the topmost button marked 'import view'. This will copy into the adjacent field the entire graphics state of the image currently in the visualization window. You should write a caption to describe this view in the field provided -- something like 'Schematic view of the crystal packing down the c axis.'

You can see the effect this has had by switching to the preview tab (Fig. 14). Now, in addition to the standard buttons for recovering the initial view and toggling the spin state, there is a new button, labelled '(a)', that links to the script you have just created. Use your mouse to move the crystal packing diagram around, then click on this new button. You will see that it returns the view to the one that you selected.

Now save what you have done. This time click on the 'Secondary save' button, the one marked 'Save updates to scripts only'. Do not select the button marked 'Save current view as main figure': if you do, then the view currently in the visualization window will overwrite the view that you have previously saved. You will now see the new button also on the enhanced figure page. Now return to the editor, and repeat the procedure outlined above to create the schematic bonds-only view of the packing. (There are other ways to retrieve this new view that we shall describe in later tutorials. At the moment, however, go through the exercise again, for practice. On the general tab, select the Orientation: 'right: bc plane at back, a axis outward'. The packing diagram should rotate to that orientation. You may need to zoom in to re-fit it to the full applet window.

Go to the button scripts tab and click on the second button that says 'import view'. This will paste the current graphics state into the second scripts window. Add an appropriate caption below this.

If you really need the practice, you can repeat the entire cycle, but instead just go to the general tab, select the 'top' orientation, resize the image, return to the button scripts tab, import this view, and add an appropriate caption.

Finally, manipulate the model to find an oblique view where interesting motifs of the packing are apparent, and save this in the slot for the fourth script. Now save what you have done (again using the 'Secondary save' button) to find that you have created the result shown in Fig. 15.

Lesson 3: using the Jmol menu

If you have used Jmol before, you will be aware that you can access many of the features of the program through a pop-up menu that you activate by right-clicking in the applet window (Fig. 16). You may use this menu to change the appearance of the model in the visualization window. Many of the menu options are implemented within the different editing palettes within the toolkit, and you may use the Jmol menu or the palettes interchangeably. Sometimes it is simply more convenient to work completely within the area of the applet; at other times the edit palettes may provide easier access to the options you want to use.

An interesting case is shown in Fig. 17. Jmol creates its menus dynamically, and can change certain features according to the nature of the current model. In our example structure, there is some positional disorder associated with an oxygen atom. This is represented in the CIF by assigning the disordered atom to two alternative locations. Jmol recognises these as distinct configurations. By default, both are visualized; but the Jmol menu allows you to select one or the other. In Fig. 17 we show how to select one of the alternatives in order to reduce the visual clutter of the disordered site.

Lesson 4: introduction to Jmol scripting

In Lesson 2, you added new scripts to the enhanced figure page using the 'import view' buttons. This imports a complex Jmol script describing fully the current graphics state. It has the advantage that you are able to generate complex views using the toolkit interface without needing to know anything of the Jmol scripting language. On the other hand, it is quite a heavyweight approach, since it generates many commands, and reproduces a very specific view. You may wish to provide the reader with options to perform various operations, and for this it's helpful to know at least a few basic Jmol commands. Many of these are very simple, and we provide a summary of some particularly useful ones in Appendix A.

The scripts that you have already added to the enhanced figure page are run when the reader clicks on a button. A button interface is perhaps the most natural for a script that will run once to provide a fully controlled, predictable effect - an animation, or a specified view with specific styles of atoms, bonds etc.

To provide additional options to the reader, you might consider 'checkboxes' or 'radio buttons'. In general, checkboxes should be used to provide functions that act independently of each other, and so are additive. Normally, the action of a checkbox is reversed when the box is cleared. Radio buttons are used to select among mutually exclusive options. The Jmol toolkit provides for up to four checkbox scripts, and one or two groups of radio buttons, each with up to six options.

Begin with a simple example (Fig. 18). Supply a script to run when the checkbox is selected ('stereo on'); a complementary one to run when the checkbox is unselected ('stereo off'); and a very brief caption to explain to the reader the purpose of the box. We recommend finishing each Jmol script command with a semicolon as a matter of good practice, although the toolkit's save procedure should normalize these if you forget to do so. You can switch to the preview tab to see how the new option for stereo rendering has been added to the output page.

Now return to the editor, and add a set of mutually exclusive options. As an example, we show in Fig. 19 the commands to render the current view in different styles - space-filling, ionic radii, ball-and-stick, or stick.

Fig, 20 shows the result obtained by a reader, who has selected the button option (d) to obtain the oblique view of the cell packing, then rendered the view in stereo (zooming out to get a better impression of the three-dimensional effect), and selected a ball-and-stick representation.

Lesson 5: becoming a power user

In the previous lesson you used some raw Jmol script commands. To get the most out of this application, there is no substitute for learning the Jmol scripting language, which is very well documented on the Jmol web site. However, it is a large and often complex language, and considerable investment of effort will be needed to become an expert.

The toolkit provides some utilities that will help the novice Jmol scripter to build up knowledge and experience of this language, and in lesson illustrates some of these features.

The Jmol console

In Lesson 4 we introduced the idea that simple Jmol scripts, such as those sitting behind many of the buttons in the toolkit editing palettes, could usefully be copied as scripts for the use of the reader. Here we show how to use the Jmol console to discover from the toolkit what those commands actually are.

The console is a window that allows communication between the user and the Jmol application. It can be launched from the Jmol pop-up menu; in Fig.16 the 'Console' command may be seen near the bottom of the leftmost menu panel.

The console window has two main panes. The lower is an interactive shell, into which the user may type (or paste) commands for Jmol to execute. The upper pane returns information from the applet. The buttons along the bottom control aspects of the communication.

In the example of Fig. 21, you can set a stereo-view representation using a menu on the general edit tab. This splits the molecular view into two halves; the view in the right half is rotated by 5°, a typical displacement for comfortable cross-eyed stereoscopic visualization. Now bring up the console from the Jmol menu, and select the 'History' button at the bottom of the console. The upper window pane is filled with the commands that Jmol has most recently executed. Most of these represent the detailed setting of the graphics state during the loading process. At the bottom of the pane, however, you can see 'console', representing the command to bring up the console window, followed by 'stereo -5'. This last is the command to create a stereo pair offset differing by a 5° rotation. Select the 'wall-eyed stereo' option from the edit palette, click again on 'History', and you will see the command 'stereo 5' - clearly representing a 5° rotation in the opposite sense. Immediately you have has learned how to specify side-by-side stereo views to Jmol, and indeed how to change the angle of rotation to some value other than the default.

If you want to test the effect, say, of a 10° rotation, simply type in the lower pane of the console window the command 'stereo -10' and click on the 'Execute' button; the result of the command is immediately shown in the visualization window.

Experimenting in the Jmol scratch window

The toolkit provides a workspace for experimenting with Jmol commands on the scratch tab. Note that anything you do here can be done with the Jmol console directly, by cutting and pasting or by interactive scripting. However, for some users this may be a more convenient interface.

You can use this scratch workspace to figure out a way of highlighting some of the crystal planes for special attention. As you explore the available palettes, you may come across the options on the special tab for slicing through the crystal along a number of planes. Fig. 22 shows an example of the crystal sliced along the (220) plane. It is not exactly what we want - we do not want the space-filling representation that the menu has forced upon us; we wish just to highlight a plane rather than cropping to it; and we may wish to emphasise some planes other than those available to us through the menu. However, it is a promising start.

From the console history, you can see that the last commands executed by the applet in creating this view were

load "" {444 666 1};spacefill 100%;slab on;
isosurface p1 hkl {1/2 1/2 0}; isosurface off;
slab plane $p1;

Copy and paste these into the text field on the scratch tab (Fig. 23). By inspection, you might suppose that the first command reloads the structure, displaying a range of 27 unit cells (from the symmetry operator codes 444 to 666), and that the second is what generates the spacefilling view. Test this hypothesis by changing the first line to

load "" {335 775 1};spacefill 20%;slab on;

and clicking on the 'Test' button below the scratch window. You will see that you now have a ball-and-stick representation, and that the portion of the crystal depicted shows 5 x 5 unit cells in the ab plane. By continuing to experiment in this way, you will find that the 'slab' commands are what determines how much of the structure is actually displayed. You can remove these. The 'isosurface' commands are used to specify the plane through a given set of $hkl$ indices. If you remove the 'isosurface off' command, you will see that the first 'isosurface' command actually renders a plane. If you wish to provide the reader with a script that does not affect the existing atom/bond style or the amount of the crystal on display, you can indeed also remove the portions of this script that affect these parameters.

In the end, you will find that a script such as the following will simply display a plane described by a particular set of Miller indices (in this case 110):

isosurface p1 hkl {1 1 0}; color isosurface red; show $p1;

and the plane may be removed with the script

isosurface p1 delete;

These could conveniently be the complementary scripts written to determine the on/off events associated with a checkbox (Fig. 24).

Of course, one may need to consult the Jmol documentation and not rely solely on trial-and-error. Nevertheless, the scratch workspace allows you to test various scripting ideas without having to save the figure to see the effects of your changes.

When you have worked out a satisfactory script in the scratch workspace, you may copy and paste it from the scratch window into any of the other script entry boxes that the toolkit supports.

Other uses for the scratch window

As with the other fields for Jmol scripts, the scratch window has an 'Import view' button allowing the complete graphics state of the image in the visualization window to be captured. This can be useful to capture an initial view that will be modified by subsequent additions or edits. The scratch window is designed to be large enough to allow a reasonable amount of interactive editing.

By contrast, the script fields on the other tabs are rather small - typically exposing only a line or two of text. This allows for several to be visible on the same page; it also encourages the use of short, one-line Jmol scripts, rather than unduly long or complex ones. On the other hand, if a large script has been stored in one of these fields that requires subsequent editing, the most convenient way might be to copy and paste it into the scratch window, manipulate it there (with the ability to make live tests on any changes you make); then finally paste the finished script back into its initial slot.

Note that the contents of the scratch window are retained when the enhanced figure is saved, although they do not find their way onto the final page created for the reader. This allows the scratch window to be used as a persistent store of specific scripts. In particular, it could be used to backup the main figure, in case you inadvertently overwrite it at a later stage by clicking on the wrong 'save' button.

Previous

Top

Next