User:Karsten Theis/Molecular Playground

From Proteopedia

Revision as of 14:06, 6 May 2025

This is a sketch how to create content for the Molecular Playground.

Project name

Choose a project name, for example UvrB_1d9z. In the example, I combined the protein name with the PDB ID code of the coordinates I am showing.

First scene

The easiest way to get started is with an existing Jmol scene (from Proteopedia, First Glance or from other sources - just make sure you have the rights to it). In the Jmol window, right-click somewhere on the top, and choose "console" from the menu. Then, type "write project_name.pngj" and save the file. This contains the coordinates and the drawing commands.

Then, start on your script file, named "project_name.spt". It could be as simple as:

load UvrB_1d9z.pngj
spin on

This assumes that your "UvrB_1d9z.pngj" file is in the same folder as the script file, "UvrB_1d9z.spt", which is how the molecular playground is set up.

What should you check before you save an existing scene?

1. Make sure the parts of interest stay in view as you rotate the molecule
2. Decide whether your background should be black (works well) or something else
3. Choose a descriptive file name

What are the advantages of creating and loading a pngj file?

1. It contains everything Jmol needs for the initial scene, including the coordinates
2. It preserves the orientation
3. It has a built-in preview that works without Jmol

Banner

There is space for limited text at the top of the display, called the banner. We will add one command to set the banner to "DNA repair protein UvrB":

load UvrB_1d9z.pngj
message driver:DNA repair protein UvrB
spin on

When running in the molecular playground, the banner is also used to give feedback when the viewers hands are detected for rotation and zoom. This minimal file is ready for the molecular playground, but we will expand it a bit for testing.

Testing online or offline

With a little bit of extra work, we can write a script that you can test online and share (by posting on Proteopedia, for example), or run locally. You will see the line "if (_applet)" below, which checks if Jmol is running in an applet (i.e. is online). Here is the updated script:

if (_applet) {
  script https://proteopedia.org/wiki/images/6/65/Molecular_playground_helpers.spt
  load https://proteopedia.org/wiki/images/f/f6/Uvrb_1d9z.pngj
} else {
  script Molecular_playground_helpers.spt
  load UvrB_1d9z.pngj
}

banner("DNA repair protein UvrB")
spin on

For the applet, the URLs are given in their complete form, so they should work on Proteopedia and on other platforms. Try opening up Jmol Simple, clicking on console, and pasting the code above to test.

To test this in a molecular playground installation, you have to copy the *.pngj and the *.spt files into the assets folder, and ask the admin to add the project to one of the play lists.

To run it on Proteopedia, you upload the script, edit a page to make a rectangular window and add a Jmol link with the script in it (go to the sandbox below to test it without the need to log in):

<Structure load='' size='[800,600]' frame='true' align='right' caption='' scene='' />
<jmol>
  <jmolLink>
    <script> script /images/6/65/UvrB_1d9z.spt</script>
    <text>UvrB, a helicase adapted for DNA repair</text>
  </jmolLink>
</jmol>

You can find working examples here.

Summary

Here are the steps without using Proteopedia:

1. Create an initial scene as PNGJ file
2. Create a script loading the initial scene (plus other commands, if desired)
3. Give both files to the Molecular Playground administrator

Here are the steps with Proteopedia:

1. Create an initial scene as PNGJ file, upload to Proteopedia and note the URL
2. Create a script loading the initial scene using the URL, upload to Proteopedia and note the URL
3. Call the script in a jmolLink on a page with a rectangular Jmol window

Creating a tour

We can expand the single-scene-script to show off the molecule. Below is the finished script, which you can try here. The first part is the same as the UvrB_1d9z script, up until the "# Guided tour ..." comment. The rest of the script goes to different views, changes the banner text and lets the viewer explore.

if (_applet) {
  script https://proteopedia.org/wiki/images/6/65/Molecular_playground_helpers.spt
  load https://proteopedia.org/wiki/images/f/f6/Uvrb_1d9z.pngj
} else {
  script Molecular_playground_helpers.spt
  load UvrB_1d9z.pngj
}

# Guided tour, showing 3 features of UvrB
antialiasDisplay=false; cartoonFancy=false; antialiasDisplayFlag=false #faster rotation

banner("UvrB, a DNA repair helicase [PDB ID 1d9z]")
spin on # Start with spinning molecule so the 3D nature is clear
delay 5
spin off
moveto 1.0 { -844 -132 520 125.23} 300.0 0.0 0.0 {42.099225806451614 43.53887096774192 61.17029032258063} 68.42333343999844 {0 0 0} 0 0 0 3.0 0.0 0.0;
banner("bound ATP")
delay 2
select ATP; color cpk
delay2play(5) # delays 5 seconds plus the time viewer rotates/zooms the structure
banner("DNA binding clamp in cyan")
moveto 1.0 { -905 -349 244 137.3} 260.87 0.0 0.0 {64.70854666666669 12.864631111111102 63.586506666666644} 64.2453671308168 {0 0 0} 0 0 0 3.0 0.0 0.0;
delay 2
delay2play(5)
moveto 1.0 { -732 -239 637 116.38} 260.87 0.0 0.0 {58.64131184407797 19.068823088455765 30.446964017990993} 81.87433897489076 {0 0 0} 0 0 0 3.0 0.0 0.0;
banner("UvrA binding domain ([1t5l] has corrected fold)")
delay 2
delay2play(5)
moveto 1.0 { -850 23 526 128.87} 115.0 0.0 0.29 {56.569378268323966 31.076560437205238 59.530780111444614} 51.673541253257795 {0 0 0} 0 0 0 3.0 0.0 0.0;
antialiasDisplay=true; cartoonFancy=true; antialiasDisplayFlag=true #nicer rendering
banner("Thanks for watching")

The "moveto 1.0" commands change the orientation. You can manually change the orientation (and centering and zoom) to something you like, and then write "show moveto" in the Jmol console. This gives you the command to copy and paste into your script. You can also use the console to select the feature of interest ("select ATP"), and then issue the command "center selected" to center automatically. Again, you would issue "show moveto" to get the orientation, and paste it into your script.

The "banner()" function changes the banner and the "delay" function waits until proceeding to the next step. The "delay2play()" function is a bit more complex. It monitors the orientation of the molecule. As long as the viewer changes the orientation, it will not proceed in the script. Once the viewer is done interacting for a prescribed number of seconds, it goes back to the orientation it had before the viewer interaction, and proceeds with the script.

There is only one command that changes the scene, "select ATP; color CPK". It changes the color of the bound ATP from silver to CPK (a color scheme giving unique colors to each chemical element). You can have lots of other commands in your script, even loading a new set of coordinates (or new PNGJ file). You can get as fancy as Jmol allows, which is pretty fancy.

An example for a more complex script is also here. It uses a picture as background, and switches between the two molecules, cyclohexane and benzene.

FAQ

• Why use the PNGJ file? It has the advantage of saving everything in a single file (coordinates, state, additional information case-by-case such as electron density, surfaces, background image, etc.). It also makes it easy to adopt scenes that are already made. Alternatively, you could just load a PDB file, and script everything else, which is nice for others learning how to script Jmol.
• Why do we need a rectangular canvas? Traditionally, the Jmol canvas is square (makes sense for rotating molecules, round would be even better). However, the Molecular Playground uses a projector with 4:3 aspect ratio, and it makes sense to build content starting with that aspect ratio. Granted, the banner uses some of that, so the real aspect ratio is a bit different.
• What are good sources for the initial scene? First Glance in Jmol (check out the electron density), Proteopedia, Molecule of the Month (RCSB or for small molecules Bristol, Google e.g. "jmol DNA", http://jmol.x3dna.org/ for nucleic acids and complexes.

Sandbox

You can use this space to load a PNGJ file (right-click, "file > load > open local file") and start finding good viewing orientations or testing Jmol commands (via console). Complex visualizations might be slower here than on molecular playground because the Jmol application is more powerful than the applet used in the browser.