Molecular Playground/Procedures

From Proteopedia

This page details procedures for authoring content modules for Molecular Playground. It is a supplement to the main article on authoring modules, Molecular Playground/Authoring.

This page describes procedures step by step. Modules at Levels II and III use utility functions in MPSupportVersion01.spt. A list of these function is provided at Molecular_Playground/Support_Script_Help.

Help Is Available!

If you have any questions about these procedures, or run into any problems, please contact (User:Eric Martz). If you have suggestions to improve this page, either edit the page yourself, or email the suggestions to Eric.

Create a Customized Molecular Scene in Proteopedia

This procedure applies to Levels I and II.

1. Create a page in Proteopedia where you will create your customized molecular scene. A good place to do this is in a protected Sandbox in your User namespace, such as User:Your Name/Sandbox 1. Step by step instructions for creating and using such a Sandbox are available in Help:Sandboxes#Protected_Sandbox_Pages.

2. Normally, in Proteopedia, while editing a page, you insert Jmol by clicking a button labeled 3D at the top of the wikitext box. This Jmol is square. However, for Molecular Playground, you need a rectangular Jmol the same shape as the projection. Instead of clicking the 3D button, paste this into your page

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

   and then save the page. Jmol will be empty, but that's OK, we are going to add a molecule next.

3. Create the customized molecular scene that you wish to show in MP by using the Scene Authoring Tools in Proteopedia. Save your scene, and copy the green link that displays it into your wikitext box. Introductory videos and extensive help are available to get you started with these easy-to-use tools.

   Proteopedia:Video_Guide which includes A Video on Adding Molecular Scenes. Help:Editing which includes How To Create A New Page Instructions for creating a molecular scene with Proteopedia's Scene Authoring Tools.

   If the molecule in your scene is not a published PDB file (so it has no PDB code), or is only a portion or modified version of a published PDB file, you can upload it to Proteopedia for use in your scene. Be sure that the filename ends in .pdb. If your PDB file is a modified version of a published one, don't give it the same name as the published file would have. For example, if you downloaded the PDB file for 1d66 and modified it, don't upload it as 1d66.pdb. Name the file to indicate the nature of the modification. For example, if you deleted the protein and kept only the DNA, you could name the file 1d66_dna.pdb. Click on Upload file in the toolbox section on the left side of any page in Proteopedia. After uploading the file, in the Scene Authoring Tools, use the load molecule tab, and you will see a slot for From Proteopedia uploaded file. Enter the filename without spaces and without the prefix "Image:" -- put underscores in place of spaces.

4. Save your scene without "zoom-out" and "transition". Don't worry if you have already saved your scene. You can save as many versions of each scene as you wish.

   1. Edit your page and Show the Scene Authoring Tools.

   2. Load your scene.

   3. Click on the Save tab.

   4. Add to the description "No zoom-out, no transition".

   5. Set the scene to spin when it loads.

   6. Check show scene transition options.

   7. Skip both options: skip the zoom-out and skip the transition.

   8. Save your scene, making sure to change the scene number in your wikitext to show this new version of the scene.

   9. Save the page and click the green link to display the scene. Fix any problems that you see.

Capture the State Script for Your Scene

This procedure applies to Levels I and II.

5. Capture the state script for your scene. In order to project your scene in MP, you will need to capture the state script into a file on your computer. When completed, the script file will be submitted to the MP team. Having a local copy on your computer also has the advantage that you can display the scene in the Jmol application, in a 1024 x 768 pixel window, just as it will appear when projected in MP.
   1. Choose a short name for the MP module you are developing, typically using the name of the molecule. This name will be used in the names of all the files making up the module, thereby making them easy to identify. If there need to be spaces within the name, replace them with underscores (or simply omit the spaces). For example, "your_molecule" or "yourMolecule".

   2. Create a folder (directory) on your computer to contain the files for this module, e.g. a folder named yourMolecule.

   3. Display the state script: Display your scene in Proteopedia. Toggle spinning OFF. Orient the molecule as you would like it to first appear, by rotating it with the mouse. Click on "Jmol" (or right click) to open Jmol's menu, and select Show, Current state.

   4. Save the state script into a file: Block select the entire state script in the upper frame of the Jmol Script Console window and copy it to the clipboard. (On Macs, use Ctrl-A, Ctrl-C instead of Cmd-A, Cmd-C!.) Paste the entire state script into a text editing program. Save the state script into a file named e.g. yourMolecule_state.spt in the yourMolecule folder. The file type .spt signifies that this is a Jmol script. Be sure to save it as plain text.

   5. Disable the load command: Put a hash sign (#) before the load command in the state script. You will find this command at the end of the second block of commands, namely, at the end of the block that begins "function _setFileState() {". Prefixing "#" comments it out, disabling it. The result should look something like this:

      #load /*file*/"http://proteopedia.org/cgi-bin/getpdbz?3ckz";

      Save the state script file as plain text with the load command disabled.

   6. Disable the initialize command: Comment out the command "initialize". Near the very end of the state script, the last function is "function _setState()". The first line in this function is "initialize". Add a hash sign "#" before this line. Save the state script file as plain text with both the load and intiialize commands disabled.

6. Test your state script in the Jmol application.

   1. Put Jmol.jar in yourMolecule folder. Download Jmol: At Jmol.Org, select Download (upper right), go to the Jmol Downloads Page, and download the current version as a binary.zip file. Unzip the file (this is automatic on Macs), and copy the file Jmol.jar (one of a large number of files in the zipped download). This is the Jmol application. Paste Jmol.jar into yourMolecule folder.

   2. Add the PDB file: Put a copy of the PDB file featured in your module in the yourMolecule folder. In Proteopedia, search for your PDB code, and on the page titled with that PDB code, use the coordinates: save as pdb link to download the file. Rename the file to yourMolecule.pdb. It will help if all the filenames in your module contain the name of your molecule.

   3. Open Jmol: You should now have 3 files in yourMolecule folder: Jmol.jar, a PDB file which we'll refer to as yourMolecule.pdb, and a yourMolecule_state.spt file. Double-click Jmol.jar, and a black window will appear titled "Jmol". If the white "Jmol Script Console" window does not appear, use Jmol's File menu, Output Console to open it.

   4. Display your scene: In the white window, type load yourMolecule.pdb and press Enter. The molecule should appear in the black Jmol window. Then enter script yourMolecule_state.spt, and your scene should appear.

Submit Your Level I Module

You have now completed the preparation of your Jmol state script. If you are making a Level I module, write your banner title, and submit the script file, PDB file, and banner title to the MP Team. Remember to design your banner text for the general public, including non-scientists.

Please also develop a web page (see Molecular Playground/Authoring#Web Page Procedure in Proteopedia), and submit the address (URL) of that page as well.

If you are making a Level II module, proceed with the next section.

Completing A Level II Module

6. Add a banner and (optionally) a color key.
   1. Download 3 scripts: For each of the following scripts, click the link below. It will take you to a page whose title begins "Image:"^[1]. On the "Image:" page, right click on the link to the script near the top left of the page and download the script file to yourMolecule folder. (If you left click, you can examine the script in the browser.)

      • Image:MP relenza03.spt
      • Image:MPSceneVersion01.spt
      • Image:MPSupportVersion01.spt (see description of what is in this at Molecular_Playground/Support_Script_Help)

   2. Rename MP_relenza.spt to yourMolecule.spt.

   3. Customize the variables defined in yourMolecule.spt to specify details for your molecule. Change the following variable definitions:

      • pdbFileName
      • localStateScript
      • bannerMessage: Create a short, one-line description of your scene, mentioning the name of the molecule, and what is important about the scene or the molecule. Remember to design this for the general public, including non-scientists.

      Be careful to keep each variable's value within quotation marks!

   4. Test your scripts. You should now have 6 files in the yourMolecule folder: Jmol.jar, yourMolecule.pdb, yourMolecule_state.spt, and the three .spt files listed above. In the Jmol application's white Jmol Script Console window (bottom section), enter script yourMolecule.spt. You should see your molecule, in your scene, with your banner at the top. (If not, re-check the preceding steps.) You will also see an inappropriate color key left over from the Relenza module.

   5. Color key? If your scene includes portions colored by element (CPK color scheme), you may like to display a color key. In that case, you need to list the appropriate elements in the variable "elementList". Otherwise, you should comment out "#elementList".

      If you would like words other than element names in your color key, you can use arbitrary color keys by specifying the desired terms and colors in lines colorKey("word", "color"). If not, comment out these lines ("#colorKey(...)").

   6. Entrance zoom? If you like the entrance zoom, you can leave the variables zoomStart and zoomEnd as they are (or you can adjust their values, which are percentages of the initial default zoom level). If you don't want the entrance zoom, comment out these two variables.

7. Final Testing: Test your script, making adjustments as needed, to make sure it shows everything as you wish.

8. Submit Your New Module to Molecular Playground: You will need to submit three of the six files in yourMolecule folder to be displayed in Molecular Playground: yourMolecule.spt, yourMolecule_state.spt, and yourMolecule.pdb. See email contacts at MolecularPlayground.Org.

Displaying a Level II Scene in a Proteopedia Web Page

This procedure does NOT apply to Level I modules. For Level II modules, you should begin creating your web page following the instructions at Molecular Playground/Authoring#Web Page Procedure in Proteopedia. You will reach a step in that procedure where you are invited, as a non-required option, to follow the procedure below.

This procedure assumes that you have followed the procedure above, for Level II modules, to create a script yourMolecule.spt (where yourMolecule is the name of the molecule that you are displaying). Here is explained how to display that script in a page in Proteopedia, which can become the web page that you offer for more information to those MP onlookers who visit MolecularPlayground.Org.

1. Specify proteopediaStateScript: In yourMolecule.spt is the variable proteopediaStateScript that needs to specify the filepath for your state script on the Proteopedia server. Display the Proteopedia page where you developed your molecular scene, and edit that page. From the <applet .... /> tag, copy the name of the scene, after "name=". From the example Molecular Playground/Relenza, this is

   User:Eric_Martz/Molecular_Playground/Authoring/3ckz_relenza_tyr274/9

   On Macs, copy with Ctrl-C not Cmd-C. Paste it into the file MP_yourMolecule.spt between the double quotes for the value of proteopediaStateScript. Now, add /wiki/scripts/ to the beginning, and .spt to the end. The final product should look similar to this:

   proteopediaStateScript = "/wiki/scripts/User:Eric_Martz/Molecular_Playground/Authoring/3ckz_relenza_tyr274/9.spt"

   (which came from the example MP_relenza03.spt).

2. Put a button into your web page: At the point where you want a button to display your scene, copy and paste the following into the wikitext of your web page:

   <jmol>
   <jmolButton>
   <script>
   script "/wiki/images/6/6c/MP_relenza01.spt"
   </script>
   <text>Display Scene</text>
   </jmolButton>
   </jmol>
   

   Make sure there are no spaces before any of the lines you pasted in. Save the page. (If you click the button now, your Jmol will display the Relenza scene.)

   Note: Alternatively you may use a green link to play your script instead of a button. See the demonstration at Demonstration of a complex animation playing from a green link.

3. Upload your script: At Proteopedia, click on Upload file in the toolbox on the left side of every page. Use the Choose File button to select MP_yourMolecule.spt. You don't need to change anything else on the page. (Optionally, in the Summary box, enter the title of the permanent page in Proteopedia where you will display the scene.) Click the button Upload file.

4. Get the filepath to your uploaded script: After uploading your script, you will be at a new page with the title Image:MP_yourMolecule.spt. On that page, right-click on the link to MP_yourMolecule.spt, near the top, and "Copy Link".

5. Paste the script filepath into the button: Paste the filepath to the uploaded script into the double quotes replacing "/wiki/images/6/6c/MP_relenza01.spt" in the example above. Trim the filepath so that it begins with "/wiki... and ends with ...spt". Save the web page.

6. Test the button: Clicking on the button should show your molecular scene, complete with banner, color keys, etc.

If you need to make changes to the script that you uploaded, it is no problem. You can re-upload the same script filename to put a new version on the server, as many times as needed.

Now, resume building your web page at Molecular_Playground/Authoring#Procedure_for_using_Proteopedia.

Advanced Authoring

If you are editing your own script manually (e.g. for a Level III module), you may still make profit of the utilitites included in the support script.

See Molecular Playground/Support Script Help.

Notes

1. ↑ All files uploaded to Proteopedia are stored in the "Image:" namespace, regardless of whether they are actually images. This includes PDB files (.pdb) and Jmol script files (.spt).