Jmol/State

From Proteopedia

Proteopedia uses the Jmol^[1] viewer to show molecules in three dimensions. What Jmol shows is described by its state. The state is a set of Jmol instructions, available for viewing in the Jmol console and for saving as state script or as part of a so-called PNGJ file. Executing the state script is a way of recreating a scene previously saved.

Parts of the State

The state script contains six sections that are executed in sequence when loading it.

  _setWindowState;
  _setFileState;
  _setParameterState;
  _setModelState;
  _setPerspectiveState;
  _setSelectionState;

The coordinates are loaded in _setFileState, and drawing commands are issued in _setModelState. Commands issued in the other four sections will also affect what is displayed. Parts of the scene might be hidden by commands in _setSelectionState. The exact appearance of the scene is dependent on parameters set in _setWindowState and _setParameterState, and the initial view (orientation, size, centering) is dependent on commands in _setModelState.

In Proteopedia, some parts of the Jmol state are changed after saving from the Scene Authoring Tools to allow loading of locally saved coordinates and enable features such as the scene caption and transitions from the previous scene.

Retrieving a compact portable script

In some situations, the state script is not as valuable as the Jmol commands entered to create the scene. If you want to make a similar scene with different coordinates or want to use the script for training purposes, a compact, portable, human-readable script rendering the same scene as the state script is desirable.

The state script relies on the exact order of atoms (and exact order of generated bonds) in the file. If you inadvertently apply the state to coordinates slightly different from the original, the resultant scene might look corrupted (i.e. it does not make sense). In this context, the state script is less portable than the Jmol commands used to generate it. It is also typically less compact and less readable for humans. While the history of issued commands is often not available directly, it is possible to reverse-engineer a compact set of commands that is portable to different coordinates, or can serve as an example to make a similar scene.

The main challenge in retrieving a compact list of commands are the atom and bond selections. For example, to draw all arginine side chains in a space-filling mode, you could issue the Jmol commands "select arg and sidechain; spacefill on". In the state script, this will show as two selection commands and two spacefill commands. The first selection is a list of atom numbers corresponding to the carbons of the arginine side chain, and the second a list of the nitrogens (because they are shown by default with different radii). For a trained human, it is fairly easy to reverse-engineer the selection by displaying the selected atoms, and by using commands such as "show sequence", "show selected" and "show coordinates".

Another challenge are commands that get expanded (made explicit) in the state script. The "spacefill" command with default atomic radii mentioned above is one example. Another example is applying a rainbow or CPK color scheme. In the state script, every single color will be represented by a distinct set of commands. However, if you are familiar with the color schemes, it should be straightforward (but tedious) to get a compact command that reproduces the scene.

Finally, some atom selections are based on distance criteria or properties (e.g. secondary structure) that are not obvious from the output of a "show selected" command. Often, these types of selections start making sense in the context of the scene, the figure caption and the accompanying text. If they don't make sense, you can still "translate" the list of atom numbers into a list of residue numbers and atom types, improving readability and portability.

Example Explained on YouTube

Here is an example of figuring out a short script that describes an existing scene.

See Also

• Jmol/Index, a list of Jmol-related resources.

References

1. ↑ Jmol - a paradigm shift in crystallographic visualization. J. Appl. Cryst. (2010). 43, 1250-1260 doi:https://dx.doi.org/10.1107/S0021889810030256