Molecular Playground/Authoring

From Proteopedia

Jump to: navigation, search

This page makes recommendations and offers shortcuts for authoring effective presentation modules for Molecular Playground (MP; see MolecularPlayground.Org).

Contents

Components of a Module for MP

Each module in MP will ideally include the following components:

  1. A Jmol script that
    1. Displays a molecule, optionally with animations, labels, and color keys.
    2. Displays a one-line text banner stating the name of the molecule and why it is important, plus a second line with the invitation "More at MolecularPlayground.Org".
  2. A web page that plays the above Jmol script, and also provides more information about the molecule for a general audience, with links to information in greater depth. The author of the module can choose to put the web page in Proteopedia, or elsewhere.

For examples, see "The Molecules" web pages linked to MolecularPlayground.Org.

Designing An Effective Module

Use light colors on a black background

Because MP projects in a well-lit atrium, generally a black background (which will appear medium gray) works best. Dark colors are hard to see on the black background, so use light colors as much as possible. In particular, Jmol's default CPK colors for carbon, oxygen and nitrogen are marginally visible. Therefore the support script provided for MP includes a function colorAllLightCPK that applies lighter colors to these elements. See the example below demonstrating the difference.

Facilitate rotation by onlookers

MP invites onlookers to interact by rotating the structure at any time. Therefore, scripts should be designed to permit rotation as much of the time as possible. Furthermore, it may be desirable for the onlooker-set orientation to remain while the script proceeds, perhaps all the way to the end of the script. One command that goes counter to this goal is a moveto command, which precludes rotation until the specified orientation is completed. In the version of Jmol currently used in Proteopedia (11.8.9 in December, 2009), zoomto commands also enforce the current orientation, "fighting" with the onlooker who attempts rotation during the timed zoomto. Therefore, the support script provided for MP includes a function zoomRotatableTo() that performs the zoom while permitting rotation.

Avoid displays that seriously slow Jmol

The following displays cause spinning or rotation to become slow and jerky in the full-sized (1024 x 768 pixels) MP projection. Your displays will be more satisfying if these can be avoided. A good way to test this is to try your scripts in the Jmol application at 1024 x 768 pixels.

  • Large numbers of spacefilled atoms, such as spacefilling all atoms in a protein. The higher the zoom, the jerkier the spinning.
  • Translucency.
  • High-Quality Display, namely set antialiasdisplay true. The MPSupportVersion01.spt actually uses high-quality when the script is displayed in the applet, because at the typical applet size (450 x 350 pixels) the speed penalty is acceptable.
  • Trace is slower than backbone. Thick traces are slower than thin traces. High zoom levels are even slower. You can get away with a thin trace at low zoom for a moderate-sized protein.

Test your script at 1024 x 768 pixels

The UMass ISB[1] projector projects a rectangle 1024 pixels wide by 768 pixels high. When testing your scripts, it is best to size the Jmol application window close to 1024 x 768 pixels. (The pixel dimensions are shown at the bottom of the Jmol application window.) Speed and jerkiness of rotation are affected by the window size. Also, zoom values differ for square vs. rectangular Jmols. (The support script provided for MP specifies set zoomLarge off, which makes 100% zoom show the entire molecule within the smaller dimension of Jmol.)

Molecular Playground pages in Proteopedia should also use rectangular Jmols, rather than the default square ones. A good size is 450 x 338 (which has the same width/height ratio of 1.333 as does 1024 x 768). This can be specified in the applet tag in the wikitext editing box with size='[450,338]'. To see exactly how to do this, try editing the section below that contains a Jmol, which has this recommended size.

Jmol Scripting Options

Three Levels

Three levels of scripting are available for creating modules for MP. Each is described below, and examples are shown.

Level I: A single script file

This is the quickest and easiest way to prepare a module for MP. It will be a single customized molecular scene, spinning, without any transitions or animation. It may include labels on specific atoms, but will lack a color key. If you later decide that you want to add a color key, it is straightforward to reconfigure your Level I script into a Level II module. An example of how a Level I module will look when projected in MP is seen below when you press the Add Banner button in the next section.

An MP module at Level I consists of two files plus two pieces of information that will be submitted to the MP team. The first three below are required in your initial submission.

  1. A single file of Jmol script commands that specifies a single molecular scene (the "state script").
  2. A PDB file that provides the molecular model displayed by the script.
  3. A banner title, which should be of length 65 characters or less.
  4. The URL of your "more information" web page (see #Web Page Procedure in Proteopedia). If your web page is not yet ready, this can be submitted later.

There are two ways to prepare the script file.

  • For Advanced Jmol Users: By hand. This requires familiarity with the Jmol Command Scripting Language. No instructions are provided here for this method, either for constructing the script file, or for making a supporting web page. See #Technical (All Three Levels) below for how your script will operate on MP.

Level II: A Single Molecular Scene With A Color Key

This method is a bit more complicated than Level I. The only advantages are that adding a color key is easy, and have a "zooming in entrance" is easy. Let's look at a concrete example.

Relenza binding to influenza neuraminidase N1 mutant H274Y (3ckz).

Drag the structure with the mouse to rotate

Example

At right is an example of a customized molecular scene[2] (), created with Proteopedia's Scene Authoring Tools.

Now we'll use the MP support script (explained in the procedure linked below) to put a banner at the top of Jmol[3]. Notice also that the chemical element colors for carbon, oxygen, and nitrogen (CPK colors) are now lighter, as recommended above. * (MP_relenza01.spt)

  • This is also how a Level I module would look.

Next, we'll use the MP support script (explained below) to add a color key[3]. (MP_relenza02.spt) Please remember that the Molecular Playground desires a balance between science and "art." Too much annotation detracts from the attraction of the playground.

Finally, we can jazz up the entrance with zooming [3]. (MP_relenza03.spt)

A module at Level II consists of:

  1. A master (top level) Jmol script file.
  2. A Jmol state script file that produces the customized molecular scene.
  3. A PDB file that provides the molecular model displayed by the scripts.
  4. The URL of your "more information" web page. If your web page is not yet ready, this can be submitted later.

In a Level II module, the banner text is built into the master script file. The script files use support scripts that are already available in MP, and are common to all modules.

Procedure

The step-by-step procedure for constructing Level II scripts, similar to those exemplified above, will be found at Molecular Playground/Procedures. These procedures explain how to use the MP Support scripts that will be required (Image:MPSceneVersion01.spt and Image:MPSupportVersion01.spt).

After preparing the script files, you can finish your web page, following the instructions below: #Web Page Procedure in Proteopedia.

Level III: A Complex Animation

If your module will be more complex than can be produced by a single scene in Proteopedia, then you will need to write much of the script by hand. However, we still strongly recommend that you first do a Level II module. This will familiarize you with key points that will not be repeated below.

In creating a script for a complex animation, you don't have to start from scratch! You should start by downloading the script from whichever of these existing modules has the most in common with your plans:

You will find links for downloading the scripts on the above-linked pages. These scripts contain crucial sections for initialization (including calling the support script), defining useful variables, loading the molecule, etc. They will show, by example, how to do the things displayed in these modules. You can change the module-specific parts of one of these scripts to customize it for your module. The first step is to change the local PDB file loaded from tamiflu.pdb or hivdrug.pdb to yourMolecule.pdb . It is a good idea to test the script after each change. That way, if something doesn't work, you'll know which change caused the problem.

Proteopedia contains a support script for Molecular Playground, Image:MPSupportVersion01.spt. The support script contains functions that make it easy to do commonly needed tasks, such as

  • colorAllLightCPK: makes the default colors for carbon, nitrogen, and oxygen lighter, so they show up better when projected in a well-lighted room.
  • showBannerAcrossTop() places a banner across the top of Jmol. It sets up a white background for the banner, and automatically adjusts the font size for projection vs. an applet on the web page.
  • labelAtomWithPointer()
  • zoomRotatableTo() zooms slowly (up or down), and permits the onlooker to rotate the molecule during zooming.
  • growSpacefill() and growWireframe() make the selected atoms "grow" slowly into spacefilled or wireframe representations, permitting rotation by the onlooker during these transitions.

If you need a transition or function that is not included, don't hesitate to ask for help in adding it. Please contact .

Technical (All Three Levels)

MP takes responsibility for loading the PDB file before your script is run, and it adds a delay after your script is run so that your scene will spin for a while before a repeat cycle of your script, or a different script, is run. For all three levels, MP defines the following variables before any master script is run:

  • PlaygroundProjection = true; # this if false if undefined
  • PlaygroundContentPath # the path on the MP server to your .spt and .pdb files. The filename must be appended to this.
  • PlaygroundSupportScriptPath # the path on the MP server to MPSupportVersion01.spt and MPSceneVersion01.spt. The filename must be appended.


Web Pages

MP offers more information about the molecule displayed in each module by going to MolecularPlayground.Org. The web page providing that information should be brief, should emphasize the impact or importance of the structure displayed, and should be designed for a general audience of non-scientists. Links to articles in greater depth (possibly within Proteopedia, or at Wikipedia) can be provided for those who want more.

Examples:

Advantages of using Proteopedia

Creating the web page in Proteopedia has numerous advantages.

  • Creation and later editing of the page, using the wikitext mechanism, are quite easy, requiring no specialized knowledge of HTML.
  • Other visitors to Proteopedia may improve the web page in a collaborative effort. Alternatively, should you prefer, you can protect your page from editing by anyone but yourself. It is also possible to hide the page from others while you are developing it, using Proteopedia's Workbench mechanism.
  • Installing Jmol on your page is very easy, requiring no specialized knowledge of the Jmol applet.
  • You may show the exact scene or animation, as projected at MP, in Jmol on the web page in Proteopedia.
  • You do not need to provide a web server. Proteopedia's web server makes your page available to the world immediately, with no additional effort, free of charge.
  • Detailed instructions are provided (below).

Your MP web page need not be in Proteopedia. You can put it on another server if you prefer. If you use a server other than Proteopedia, the procedures here do not apply, and you will need to know how to build HTML pages and how to use Jmol.

Web Page Procedure in Proteopedia

  1. Identify the page in Proteopedia where you will develop your article to provide more information as a supplement to your module in MP. Most likely you already set up this page and developed your scene there (see Molecular_Playground/Procedures#Create_a_Customized_Molecular_Scene_in_Proteopedia). We recommend that you develop your web page in a temporary, protected page that you create named User:Your Name/Sandbox 1 (or 2 or higher if you already have a Sandbox 1). For instructions on how to create this page, see Help:Sandboxes#Protected_Sandbox_Pages. After you have completed the development of the content in your page, you can move the content to a new permanent page named Molecular Playground/Your Molecule (see the last item below).

  2. When you were developing your molecular scene, you installed a rectangular Jmol into your page. Now, you can specify that your custom scene will be automatically displayed when the page loads, rather than having to press a green link. To do this, insert the red line below into your <applet ... /> tag.

    <applet size='[450,338]' frame='true' align='right'
    scene='XXX'
    caption='YYY' />

  3. Replace 'XXX' with the name of your scene: Copy the name of the scene from the green link <scene name='...'> tag that shows your scene. Copy the quoted name (without "name=" and without the quotes), and paste that to replace XXX. Make sure the scene name has one single quote mark at each end. Save your page. Your scene should appear automatically a moment after the page loads. After you are satisfied that the scene is loading correctly, you can delete the green link(s) you used to develop the scene, unless you want to keep more than one scene to accompany the explanation in your page.

  4. Replace 'YYY' with a descriptive caption for your scene. This is a good place to mention the PDB code for the model you are showing. Put the lower case PDB code between double square brackets, like this [[3ckz]], which will make a link like this: 3ckz.

  5. This step applies only to Level II modules, and even for those, it is optional: Insert a button that will show the scene as projected in MP. See Molecular Playground/Procedures#Displaying a Level II Scene in a Proteopedia Web Page.

  6. Write the text for your page, dividing it into logical sections. See the example pages linked above. On the example pages, use the edit this page tab to see how the wikitext is done, then Cancel editing (so that you don't change the example pages).

  7. Insert {{Template:MP_masthead}} at the top of your page to show the MP masthead photographs. Depending on what follows, you may need to put several blank lines after it to force the Contents table down, as done in Molecular_Playground/HIV_Protease_Inhibitor. Or you may need to insert {{Clear}} as done in Molecular Playground/Tamiflu.

  8. At the very bottom of your page, paste in [[Category: Molecular Playground]]. This adds your page to that Category, which lists all such pages.

  9. Just above the previous item, paste in {{Template:Molecular Playground animation description}}.

  10. Search for related pages in Proteopedia, Wikipedia, and the scientific literature and provide links to them.

  11. Optional: Near the bottom of your page, include a Methods section, patterned after those on the example pages, with links to all the scripts and PDB files employed on your page.

  12. Create a new, permanent page in Proteopedia named Molecular Playground/Your Molecule (substituting the name of your molecule for Your Molecule). See How To Create A New Page. Move the contents of your Sandbox 1 page to a permanent page title: see Help:Sandboxes#Publishing Your Completed Article.

  13. Email the address (URL) of your permanent web page to the MP team (see email addresses at MolecularPlayground.Org) asking them to add a link to your page.

Notes and References

  1. ↑ MolecularPlayground.Org
  2. ↑ This scene shows the anti-influenza drug Relenza binding to mutant neuraminidase H274Y (3ckz). This mutant is resistant to Tamiflu. For more information, see Avian_Influenza_Neuraminidase,_Tamiflu_and_Relenza#Resistance_to_Tamiflu_and_Relenza.
  3. ↑ 3.0 3.1 3.2 The font sizes in the banner and color key will be proportionally larger when projected in MP, but they will not be larger in the Popup window in Proteopedia. Using the MP support script in Proteopedia requires that we upload our main script. Uploaded scripts can be played with buttons, as demonstrated above, but are not played with green links.

See Also

Proteopedia Page Contributors and Editors (what is this?)

Eric Martz, Craig T Martin

Retrieved from "http://proteopedia.org/wiki/index.php/Molecular_Playground/Authoring"
Personal tools