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

An introductory tutorial

Upload structural data

An author wishing to prepare an enhanced figure before submitting an article comes to the start page, shown in Fig. 4.

It is important to enter an email address to which a receipt message will be sent. This message contains the URL that you will need to make future edits to the figure (each figure is given a unique and unguessable identifier). The message will also contain a second URL that should be cited within the article that you submit. This second URL will allow the Co-editor or referees to view your enhanced figure, but not to edit it.

If you wish, you may also supply a short label or tag that will appear in the subject line of the automatically generated email response. This can be helpful in identifying a particular figure if you plan to prepare several simultaneously.

Specify the type of structure you are illustrating - inorganic, small-molecule (this includes organic and metal-organic compounds and complexes), or biological macromolecular (proteins, nucleic acids etc.). This will set certain default values and styles appropriate to the type of structure you wish to illustrate, and will also select different editing palettes tailored to the requirements of that type.

Normally you will be uploading a CIF from your own computer to illustrate some new structure. You may specify the location of that CIF on your filesystem (using the 'Choose' button to browse the contents of your computer if needed).

Sometimes, however, you may wish to illustrate some aspect of a structure that has already been published or deposited in a structural database. If you know the reference code of such a structure in a public CIF archive (e.g. the Protein Data Bank or Crystallography Journals Online), you may enter the code on this page. At this time, 4-character alphanumeric codes (e.g. 1cro) are assumed to be protein structures deposited in the PDB; six-character codes of the form aannnn (where a is some alphabetic character, n a numeric one) are assumed to be structures published in IUCr journals.

If the CIF you are uploading contains several data blocks, by default the toolkit will load the first block containing structural data. You may select a different data block by specifying its numerical position within the CIF (do not count any blocks, such as those containing the text of an article, that do not contain structural data).

The special value 'all' will cause the toolkit to superimpose all models in the same visualization space. Note that this is rarely useful for crystal structures with different unit cells, but may occasionally be useful for comparing near-homologous structures.

You will understand this tutorial better by working through the steps with a real example. Enter 'sk3182' in the 'External database code' field to retrieve from the IUCr archive the CIF for the structure that we are using (Schlueter et al., 2008): poly[potassium [diaquapenta-μ2-dicyanamido-dicadmium(II)] dihydrate].

The user interface

Fig. 5 shows the result of uploading a CIF, in this case of an inorganic structure. The main parts of the edit window are identified for future reference.

At this stage, the first thing that you should do is to save the file that you have uploaded. (It is possible to begin editing the structure immediately, but it is best to save so that you receive the email message recording your edit URL, and so that the necessary permanent storage resources are set up on the IUCr server.)

In this introductory tutorial, you should always save using the left-hand 'Save' button (the one marked 'Primary save' in Fig. 5). This will save the current view in the visualization window as the initial view of your enhanced figure, and will create a static image of this view for publication in the PDF edition of the journal.

Fig. 6 shows the result of saving at this point. The top of the page summarises the information that you need to use the figure in your article submission.

The bottom of the page shows the enhanced figure that you have created. It contains a Jmol applet showing a default view of your structure. This is a fully interactive applet - a reader may move it around with the mouse, and access all the functionality of the Jmol applet by right-clicking within the applet.

On the right-hand side of the figure, a number of standard buttons have been placed for the reader. From the bottom up, they are: 'toggle spin', which starts or stops the structure rotating about a vertical axis in the plane of the screen; 'reset view' which returns to the starting view; and 'static view', which replaces the applet by the static image that will be used in the PDF edition of the journal.

You should click on the 'static view' button to check that the static image has indeed rendered correctly.

A simple edit

Now click on the 'Return to editor' button to return to the main edit page (Fig. 5). Alternatively, if you were to shut down your browser, you could return at any later stage to the editor using the URL that was mailed to you in the receipt message. It is also displayed as the 'Return address' on the edit page.

We shall create a packing diagram of this structure to demonstrate its beautiful symmetry in an extended crystal lattice.

Click on the crystallography tab in the right-hand panel to display a number of options allowing you to display particular features of the crystallographic symmetry. Fig. 7 shows the initial settings of the controls available to you on this tab.

One thing that you should be aware of is that the checkboxes, menus and radiobuttons control JavaScript functions that communicate commands to the Java applet. Using these, you will be able to change the appearance of the structure displayed by Jmol. However, there are other ways to change the graphics state of the object in the applet (some of these will be discussed in later tutorials). If you change some aspect of the display by one of these other means, the checkboxes etc. in the edit palette will not necessarily reflect those changes. That is, the checks or other selection marks against the items on these palettes are not guaranteed to reflect the current graphics state.

This is an inherent shortcoming of the loose coupling between Jmol, which is a Java applet, and the JavaScript commands which your browser can implement. You should find with a little practice that this does not greatly reduce the usability of the toolkit.

However, you should bear in mind that the same shortcoming will be present in the interactive figures that you are planning to create, and you should therefore take care to minimise the chances for inconsistency in the functions that you provide to the reader. Later tutorials will revisit this consideration.

Go now to the pull-down menu under the heading 'Cell packing' and select the option '3 x 3 x 1 unit cells'. The display in the Jmol window immediately changes to show the crystal packing down the c axis (Fig. 8).

You can appreciate the pattern better by zooming out. If you have a mouse with a scroll wheel, click in the applet window and zoom out using the wheel, until you have a view that just fits into the image area. Alternatively, hold down the SHIFT key and the left mouse button and move the mouse vertically up or down to zoom.

Now you may add a figure caption. Two boxes are provided for captions. Use the upper one for any comment that applies solely to the current view (i.e. to the image that readers of both PDF and HTML versions of the article will see). In this example we add a second caption ('the interpenetrating layers are best seen in an oblique view') that invites the reader to explore the packing by moving the structure around.

Save this, using the 'Primary save' button as before, and you have created your first enhanced figure for publication (Fig. 9)!

Good housekeeping

If you decide not to submit the figure for publication, it is only polite to remove it and the associated storage from the IUCr server, by clicking on the 'Delete' button at the foot of the edit window (Fig. 5).

The IUCr server routinely deletes files that have not been accessed for a certain period of time (currently three months). This should provide adequate time to prepare and submit an article. However, if review of the article is taking longer than this, you should return to the figure and refresh the files (a simple save will indicate to the server that the figure is still active).

Previous

Top

Next