Instructions for authoring molecular structure tutorials in the Jmol Tutorial-Authoring Template (JTAT).

This document is incomplete. I plan to complete it in the near future. You are welcome to use it as is. Meanwhile, if you have specific questions, don't hesitate to contact me (emartz@microbio.umass.edu). -Eric Martz, July 12, 2008




Jmol is a powerful, free program that displays 3D molecular models. The models, displayed and colored as desired, can be rotated and zoomed interactively with the mouse. The tutorial-authoring tools discussed here, Proteopedia and JTAT, use Jmol (in its java applet form) within a web browser. Tutorials may be made freely available on-line, or, in the case of JTAT, can also be projected from a local (optionally private) copy.

The easiest and quickest way to create a molecular structure tutorial in Jmol is with Proteopedia.Org, an innovative free website created in 2007 by Sussman, Prilusky, and Hodis. Its Scene Authoring Tool makes it quite easy to create customized molecular views or scenes, and its wiki format makes it easy to describe your scenes with accompanying text. "Green links" placed in the text show your views. Examples of such tutorials are linked to Proteopedia's main page.

Proteopedia limits what you can do, to some degree, which contributes to its ease of use. JTAT offers greater control, and offers several features and amenities to enhance your tutorials, but these come at the price of requiring additional skills and time during tutorial authoring.

Luckily, you don't have to decide in advance which to use. We recommend that you start making a tutorial in Proteopedia. Then, if it seems worthwhile, you can easily move the scenes and text from Proteopedia into JTAT, to get a feel for what is involved. In fact, we recommend using Proteopedia to author your molecular scenes, even when you plan to deliver your tutorial in JTAT.

Both Proteopedia and JTAT tutorials operate in standard web browsers, such as Firefox, Internet Explorer, and Safari (Windows, Mac OS X, or linux). Both support multiple molecules in one page/chapter, and both have toggles for graphics quality. They differ in the following features:

Proteopedia vs. JTAT
Features Proteopedia JTAT
Molecule May scroll out of view. Often small, but can be enlarged temporarily (with edit preview) or permanently. Always visible and large.Text and view buttons scroll without moving the molecule.
Compare
Molecules
Side by Side		 Yes, but no synchronization
(as of 4/08).		 Yes, up to 4, with synchronization,
maintaining alignment.
Details All text is always in view. There is no mechanism to hide "details". Details are hidden, e.g. when projecting to an audience, but can be displayed, e.g. when one person is viewing the tutorial. Showing details for one molecular view at a time leaves more view descriptions visible, making it easy to see where you are in a series of molecular views.
Slider None. Zoom slider invites user to zoom without remembering mouse gestures. Optional slab slider.
Centering Only via Jmol's menu. Centering convenience button is provided below the molecular view.
Authoring: Text Easily type into a form as wiki text. Text editor needed to type HTML into disk files. Familiarity with a little HTML is required -- HTML quick reference is provided.
Authoring: Molecular Scenes/Views Superb Scene Authoring Tool  makes it incredibly easy.  Using Proteopedia's Scene Authoring Tool is recommended. Then you simply paste the resulting script into a .spt file.
Editing of content by users. Easy: its a wiki! Authors may protect tutorials but their contents can be copied to other pages for editing and adaptation by others. Editing files with a text editor is possible only when the tutorial's author chooses to make the files available by download or email request.
Putting the tutorial online Automatic. All contributions are online immediately because its a wiki. Requires uploading to a server. (Author may choose not to put the tutorial online, but this denies access by students.)

Proteopedia and JTAT enable authors of macromolecular structure tutorials to concentrate on the scientific content, rather than on web page programming. Authors choose molecules, design molecular views, and explain them. JTAT provides a template or "shell" that sets up the molecular display, a scrolling panel of view buttons and descriptions, ready-made style sheets, and many other amenities that improve usability and make your tutorials look classy. Typically, most molecular views show a single molecule, but JTAT can show two, three, or four molecules for side by side comparisons. The best way to see JTAT's range of capabilities is to run through the JTAT Demonstration Tutorial.

JTAT displays molecules in a web browser, using the Jmol java applet, a free, open-source molecular display program that requires no installation. JTAT tutorials work from disk files (off line) or from servers (on line). They work in Windows (in Internet Explorer, Mozilla Firefox), in Mac OS X (in Safari or Firefox), and in linux (in Firefox).

In brief, after getting familiar with these instructions, you download JTAT. It includes an empty template, which is a working tutorial, except without any molecular content. You view the template in your favorite web browser. Then, following the instructions below, you insert molecular content into the template. The content consists primarily of customized molecular views, with descriptions of the views, which include color keys: text colored to match the colors of the molecule. After each change to your tutorial's content, you reload it in the browser to see the change. When you're finished, you can put the tutorial on-line for use by your students, or project it from local files (or on-line) to illustrate a lecture.

Proteopedia.Org is the easiest and quickest way to create an on-line macromolecular structure tutorial. A detailed comparison with JTAT is in the table above, and succinct comparisons with other tutorial-authoring systems are on JTAT's main page.

We suggest that you begin by creating, in Proteopedia, a few scenes (views) of the molecule(s) that will feature in your tutorial, and also that you begin writing their descriptions there. You will need to apply for an account at Proteopedia.Org, which requires that you use your real name. Click the log in/request account link at the upper right at Proteopedia.Org.

Proteopedia's Scene Authoring Tool is by far the easiest way to create a customized view of a macromolecule. You may decide that completing your tutorial in Proteopedia, and leaving it there on-line, meets your needs quite well.

Protected Pages. Proteopedia is a wiki. Unlike most wiki's, however, you can protect your tutorial in Proteopedia from changes by others. (By contributing your tutorial to Proteopedia, you give others permission to copy your tutorial, and modify and adapt the copy, but your original will remain intact.) Instructions for creating protected pages are linked to Proteopedia's main page, under What Can Proteopedia Do For Me?.

Scenes and scene descriptions that you create in Proteopedia can readily be installed in JTAT. Indeed, Proteopedia is the easiest way to create macromolecular scenes for JTAT, and the way that we recommend. Other methods are described below.

Jmol requires java. Jmol comes in two forms, both of which have the same display capabilities and command language. Both require java in order to operate. Java is free, and cross-platform; that is, it enables programs written in java to run identically on Windows, Apple Macs, or linux, without needing a different implementation for each platform. Apple Mac OSX comes with java, and Apple Software Updates keep it up to date. Windows comes without java, but java can be installed at no cost, quickly and smoothly from java.com. Java is used by many other programs besides Jmol.

Jmol Applet. JTAT uses the applet form of Jmol because this is the form that operates within a web browser. Delivering tutorials to users on the web has many advantages. The browser makes the display, layout formatting, and organization of text relatively easy. Delivering tutorials in browsers makes them highly accessible. When a web surfer visits a site that uses Jmol, Jmol is sent to the user's browser silently, quickly, and automatically. This means that, aside from having to install java on Windows systems, nothing needs to be installed in order to use a Jmol applet-based tutorial. When you download JTAT, the Jmol applet is included.

Web browsers contain a versatile programming language called javascript (not to be confused with java). This makes it possible to have menus, buttons, and links that control the molecular view within the applet. It also enables the applet to inform the browser about actions taken by the user, such as what atom has been clicked. JTAT uses javascript extensively, but you will need to learn hardly any javascript in order to use JTAT to author a tutorial.

Jmol Application. The Jmol application is a stand-alone program (as are RasMol, PyMol, and many other popular molecular visualization programs). Unlike the Jmol applet, it runs independently of, and has nothing to do with, web browsers. And unlike RasMol and PyMol, which need implementations (source code compilations) specific for each computer platform, a single Jmol program runs identically (with the help of java) on Windows, Apple Macs, and linux. Optionally, the application can be used when you are developing molecular view scripts for JTAT. Instructions are provided.

Biochemistry. We assume that you know about, or are learning about, a molecular structure -- and that you wish to present a series of informative views of this molecule, explaining its salient structural features, and how they support its function.

Text Editing. First, you'll need to be able to edit plain text files, using a text editing program. Plain text editors include Notepad, a simple but adequate text editor that comes with Windows, and BBEdit, a superb and sophisticated commercial program for Macs. You can also use word processors (such as Wordpad in Windows, Textedit on Macs, or Microsoft Word) but then you must be careful to save the file as plain ("ASCII" or "DOS") text. If you inadvertantly save it as a document file, it won't work -- but then you can simply re-save it as plain text.

You'll need to edit plain text files that contain the text descriptions for your molecular views, and the Jmol script (.spt) files that specify those views.

Windows Notepad: Start, (All) Programs, Accessories, Notepad.

Mac OSX: BBEdit is the supreme Mac text editor. 30 day free demo from barebonessoftware.com

HTML (HyperText Markup Language). Second, you'll need to be familiar with just a little HTML, in order to color your text to match colors in the molecular view, and to insert links and images into your tutorials. Quick references are provided for HTML and coloring text.

Jmol scripting. Third, you'll need some familiarity with the Jmol molecular view command scripting language. This is a superset of the RasMol and Chime command languages. Command scripts, or scripts for short, will be saved in plain text files whose names end ".spt".

Gather the PDB codes for the molecular models that you want to display in your tutorial. Good places to search for published PDB files are listed in the syllabus for the most recent Martz Workshop.

Download the PDB files themselves. After you set up the directory for your new tutorial, these files can be put in the directory jtat/tutorial_name/molecules4all. ("molecules4all" means "molecules for all chapters" -- but you don't need to use any particular PDB file in more than one chapter.) Make sure that the saved filenames are all lower case (see below) and end in ".pdb".

You can download any molecular model that you see in Jmol (or Chime). Click on the "Jmol" frank in the lower right corner beneath the molecule, to open Jmol's menu. Click the top item on the menu, and then the last item on the submenu that opens. If the PDB file appears in the browser as text, use the browser's File, Save As, and save the file as plain text with a lower case filename ending with ".pdb".

Plan what you want to show and explain in your tutorial. The best place to start exploring a molecule is Proteopedia.Org: it shows the name of the molecule, the reference to the original publication, the abstract from the original publication, the resolution of the model, the locations and full names of ligands and functional sites, and more. From within Proteopedia, click the link (beneath the molecule) to FirstGlance in Jmol for further exploration.

The material that follows will make a lot more sense if you get familiar with the JTAT Demonstration Tutorial. First, you need to be familiar with how the Demo looks in a browser. This will help you understand what we mean below by Table of Contents and Chapter, molecular views, etc. Then, as you read below, be sure to look at the folders and files that make up jtat/jtatdemo. This will give you a concrete example to see how those folders and files support the tutorial as it appears in a browser.

It is very important that you understand the organization of files and folders within JTAT. This will enable you to avoid inadvertently breaking JTAT, and enable you to place your new tutorials and alterations correctly. It will greatly facilitate moving your tutorials to new versions of JTAT, should new versions become available.

The jtat folder. JTAT is contained in a folder (directory) we'll call jtat. When you download JTAT, the main folder will include its release date in its name. For example, jtat_2008_02_15 would signify a release date of 15 February (02), 2008. It is best to leave the release date in the folder name because you may well end up with several versions of JTAT side by side (see next paragraph), in which case leaving the release dates of each in their folder names will be very helpful. The release date of each version of JTAT is displayed at the bottom of the control panel in every tutorial. Below, we'll refer to the folder generically as jtat.

JTAT versions. You can have multiple versions of JTAT side by side, as long as the main jtat folder has a distinct name for each version. In some cases, it might be simpler to leave a well-functioning tutorial in an older version, particularly when it would need extensive revisions to make it compatible with a newer version of JTAT.

Tutorial folders. Multiple tutorials can be contained in jtat, each in its own folder. For example, the JTAT Demonstration Tutorial is in a folder named jtat/jtatdemo. Were you to create a new tutorial on acetylcholinesterase, an appropriate folder name for it would be jtat/acetylcholinesterase. This folder will contain all text, molecular view scripts, images, and other components that are specific to this tutorial.

All tutorials in jtat share the JTAT shell, that is, the code that sets up and operates the tutorial. This code is in a set of standard folders that are shared in common among all tutorials, and are named as follows:

Each tutorial that you create will add another folder to the above list.

In addition to the above folders, the following are the only files that should be present in jtat:

JTAT files you can edit. For the most part, you should not alter the jtat files or folders that are outside your tutorial's folder. There are a few exceptions listed below. However, most authors will never need to touch any of these files (except for index.htm).

Copy the Template. To create a new tutorial, copy (duplicate) the folder named template (in the jtat folder), including all the folders and files it contains. Now rename Copy of template to, for example, acetylcholinesterase (or whatever is the topic of your planned tutorial). Below, we'll refer to it generically as tutorial_name.

Lower case for all folder and file names! Nearly all file and folder names in JTAT are entirely in lower case letters. (The exceptions are Jmol.js and jmolApplet*.jar.) We strongly recommend that you use only lower case letters (a, b, c, ...) and no upper case letters (NOT A, B, C, ...) in file and folder names. Case mismatches in file or folder references are harmless in Windows and Macs, but when your tutorial is moved to a server, they can be tedious to fix!

View Your New Tutorial. There are several ways to set up a convenient way to view your new tutorial. Use whichever you like.

  1. Shortcut/Alias. Find the file jtat/tutorial_name/index.htm. Find the new shortcut/alias named index.htm on your Desktop, and rename it to your tutorial_name. To view your new tutorial, double-click it.

  2. Bookmark: After opening your tutorial (template) in the browser (previous paragraph), add a Bookmark or Favorite. Use that to open the tutorial in your next browser session.

Note that Firefox is recommended (in both Windows and Macs) for developing and testing JTAT tutorials (see below).

Files and folders making up a tutorial. Your new tutorial folder (we'll call it tutorial_name) should contain the following:

If you haven't already done so, put the PDB files you need in jtat/tutorial_name/molecules4all.

Before starting to add content to your new tutorial, it will be helpful to understand the files that will make up each chapter. The folder for each chapter (we'll call it chapter_name) needs to contain the following files. The contents folder contains similar files as indicated.

This section assumes that you have already followed the instructions under How to Start a New Tutorial.

Title. When you first view your copy of the template in your browser, at the top, you'll see someting like Put Tutorial Title Here. Let's do that. This may be the first time you will be editing a .js (javascript) file, so in the next section, we discuss some technical problems that might occur, and how to find and fix them. It would be a good idea to read Editing Javascript Files before continuing with this section.

In the file jtat/tutorial_name/contents/contents.js, you will find a line something like this:

Use your text editor to replace the placeholder text with the real title of your tutorial. For example, you might change the above line to this:

Now, save the changed file (as plain text), and then reload your tutorial in your browser, and you should see your real title in the browser.

If you do not see the the title that you typed into the file contents.js, please read the following section, which describes troubleshooting.

Adding textual content to your tutorial is largely a process of repeating the above cycle: change a javascript text variable, save the .js file, reload the page in your browser, and troubleshoot if anything goes wrong.

Do you need a Contents page in your tutorial? If your tutorial will have more than one chapter, you should use a Contents page (which serves as a Table of Contents) that provides a list of your chapter titles, and a link to enter each chapter.

If you will have only one chapter, you may prefer to skip the Contents page. In order to do that, in the file jtat/tutorial_title/index.htm, change this line

to this line

Of course, if you renamed the folder chapter01 to something else, you'll need to use that name in the above line.

Finishing the text in your Contents page. Now that you know how to put text into javascript string variables in the file jtat/tutorial_name/contents/contents.js, you can proceed finish up the text in your Contents page. Examining the variables in contents.js will show you where to put the subtitle, introduction to your tutorial, the name of your first chapter, any details you wish to provide, and the conclusion. All of these are optional except for the name of your first chapter. Those you don't need can be set to empty (blank) strings.

Adding a molecule to your Contents page.

Editing javascript files. The textual content of in a JTAT tutorial is stored in javascript files, whose names end in .js. The text itself is stored in various javascript text string variables. For example, in the file jtat/tutorial_name/contents/contents.js you will find:

The above line defines the javascript variable chapterTitle to contain the text you see in quotation marks. You simply edit the text between the quotation marks to put in a real title. For example

The tricky part is to avoid inadvertantly changing the parts shown in red here:

Those red parts are absolutely required, unchanged. For example, none of the following will work. (Portions following // are comments, that is, they are ignored by javascript.)

So, the trick is to pay careful attention to leaving the javascript syntax intact. (The word var is not always needed. It depends on issues we don't need to get into here. If var is present, leave it; if not, don't add it.)

It is highly recommended that you make one change at a time to a javascript file, and then reload the relevant page of your tutorial in the browser to confirm that all is well. When you have made many changes before testing the result (by reloading in the browser), it becomes much harder to find the problem. But what if you do accidentally damage the javascript?

Troubleshooting: The Javascript Console. Sooner or later you will accidentally damage the syntax of the javascript. It happens to the best of us -- fairly often! The symptom will typically be that parts of the page will fail to appear in the web browser.

The Firefox web browser is particularly good at telling you exactly where the problem is. Therefore, we highly recommend that you use Firefox (on both Windows and Macs) for testing JTAT tutorials during development.

Firefox locates broken javascript in its Error Console. This is a special window that is opened from Firefox's Tools menu. So, whenever you suspect a problem with javascript, check the Error Console. To make sure that only current errors are shown, press the Clear button in the Error Console, reload your page in the browser, and then check the Error Console again.

Double vs. single quotes . It doesn't matter whether a text string is double or single quoted, provided the opening quote and the closing quote are matched. These two are valid and equivalent:

A common pitfall is to include quoted material within a quoted string. This is best accomplished by using double vs. single quotes. For example, suppose we want the word red to appear in color, using an HTML font color tag. The following will not work because the opening quote around red (marked with ^) inadvertantly closes the whole text string variable.

The solution is to use double quotes within single quotes (or vice versa):

But you have to be careful to match each pair!

Apostrophes and escaping quotes. Single quotes are often used around the main text, so you can double-quote items within the text, such as red font coloring. In such cases, you cannot use a single quotation mark as an apostrophe, because it prematurely terminates the quoted string:

One solution, of course, is to use double quotes around the main text. However, in the example above, we need double quotes within the text for red . So the solution is to mark the apostrophe as being part of the text, not the end of it. This is done by preceding it with a backslash (\), which is called escaping it:

Literal quotes. If you want literal quotation marks to appear around a word or phrase in the text, use HTML quotation tags:

If the text is long (multiple lines), there are two ways to handle it.

In the above method, leaving the \n\ off the end of a line causes a fatal javascript error (meaning simply that the javascript cannot be interpreted, and will fail to display correctly). The Error Console will help you find the culprit. The second method is like this:

The above two methods are equally good.

Empty string variables. Sometimes you want no text in a certain location. For example, you might not need a subtitle. In such cases, it may be crucial that the subtitle variable be defined but its value be empty:

Deleting the above line would leave the variable chapterSubtitle undefined, and could cause a fatal javascript error.

The following steps will install a molecular view on your Contents page.

  1. Make sure the PDB file for your view is present in jtat/tutorial_name/molecules4all
  2. Near the end of the file jtat/tutorial_name/contents/contents.js you will find a javascript function setupButton(...). This is where you specify the molecular view for the Contents page. Even though there will be no molecular view buttons in the Contents page, the molecular view is specified by using this function.
  3. Leaving the number of molecules specified as 1, put the correct PDB filename in the second parameter. If you want to look at an example, see jtat/jtatdemo/contents/contents.js. Now reload your tutorial in the browser, and you should see the molecule.
  4. At this stage, the molecular view will be a default view specified in jtat/tutorial_name/contents/initial-view.spt. To customize the view, you will need to change the contents of this script file. See the next section below to set the desired orientation and zoom. For the rendering and coloring, see scripting.

Jmol makes it easy to specify the initial orientation and zoom for any molecular view. Here is how.

(This section makes some references to Jmol commands and command scripts. You may want to read the upcoming section on Scripting Molecular Views before proceeding.)

  1. Use the mouse to rotate and zoom the molecule to the orientation and size that you want. Zooming can be done with the mouse wheel, unless you are using Safari. Before moving the mouse wheel, click on the molecule to focus Jmol. If you want finer control, or if you are using Safari, hold down the shift key while dragging the mouse up or down in Jmol.
  2. Click on the gray Jmol, to the lower right of the molecule, to open Jmol's Main menu. At Show, click on Orientation. The Jmol console will appear, and it will contain something like this: 
    3. moveto /* time, axisAngle */ 1.0 { -512 593 -622 120.03}
/* zoom, translation */  111.93 0.0 0.0
/* center, rotationRadius */ {27.204605 41.80329 28.43788} 45.783455
/* navigation center, translation, depth */ {0.0 0.0 0.0} -49.80277 -41.18717 50.0;
#OR
#Follows Z-Y-Z convention for Euler angles
reset;center {27.204605 41.80329 28.43788}; rotate z -87.96; rotate y 85.43; rotate z -6.31; zoom 111.93; set rotationRadius 45.78;
Jmol script terminated
  3. Copy the desired line from the Show Orientation report. On Mac OS X, you will need to block, then drag and drop because (at present) you can't copy from the Jmol console. Which line?
  4. Paste the reset/moveto command into the initial-view.spt script file for the contents or chapter in question. It should be near the end.
  5. Uncomment the commands provided in the initial-view.spt template file that put the molecule in a good starting position to roll and zoom into view. These are about three command lines that include zoom 15, which reduces the molecule to 15% of full size before it starts zooming into view.
  6. If you are using a moveto command, change the first number after the word moveto to the number of seconds over which you want the action to occur. Try different values to see what you like. Typically, about 2 seconds is good.
  7. Try reloading the contents or chapter containing your new orientation/zoom script (or pressing the View 1 button) to see the result.
  8. In chapters with multiple views, normally each View button will leave the prior orientation/zoom unchanged. This means the user can rotate the molecule, and zoom it, and then see different views in that user-set orientation and zoom. Alternatively, if you want to force the view into a particular orientation/zoom, you can add the reset or moveto command into the viewNN.spt file. If this file contains a state script, it will already include orientation and zoom. However, if you want to change only the orientation and zoom (but not the colors and representations) you can simply paste another reset or moveto command into the end of the script file.
  9. Repeat this procedure later on for each new view, as you develop or polish it.

Next, provide the following specifics for the window title, and the footer material that can be viewed at the bottom of the Contents as well as every chapter.

What is a "script"? The term "script" is short for "command script", which is a series of commands to Jmol that specify how to render a molecular view. Typically these commands are stored in a plain text "script" file, with a filename ending ".spt".

Optional: If you want to examine some script files now, look at the files ending in ".spt" in the jtat/jtatdemo/ch_* directories. Note, however, that these were all created by direct scripting rather than being state scripts generated by Jmol.

There are several ways to generate these molecular view scripts.

Scripting in Proteopedia is recommended because it is easiest and can produce a wide range of molecular views that will meet most needs. Some advanced molecular views (such as translucency, cavity surfaces, or crystal symmetry operations) will not be available in the dialogs of Proteopedia's Scene Authoring Tool -- in these cases you could enter script commands into Jmol's Console within Proteopedia.

Before using Proteopedia to make molecular view scripts for JTAT, you should first have tried creating a tutorial directly in a Proteopedia wiki page. Molecular scenes in such a page can easily be moved later into script files for JTAT following the instructions below. You don't need to use the procedure below unless Proteopedia seems too limiting, and you want to try using JTAT instead.

Making JTAT scripts in Proteopedia:

  1. You will need a page in Proteopedia in which to author molecular scenes, unless you have already authored the scenes that you want to put into JTAT. For this purpose, you can create a protected page named Scenes for [topic of your tutorial] in JTAT. (see Help:Protected Pages).

  2. Obtain the desired molecular scene in Proteopedia. It does not matter which of the following methods you use to obtain the scene. Jmol will generate the appropriate state script regardless.


  3. Display the state script in the output (top) box of Jmol's Console. (See above for how to open the Console.) With the Console open, click Clear Output, then State.

  4. Copy and paste the state script.

  5. Disable the load command! The state script includes a command that begins with "load", designed to load the molecular model (typically a PDB file). This command must be disabled. (JTAT loads the molecular model separately before running the state script.) Disable this one command line in the state script by putting a pound sign (#) before the word "load", making it "#load". This converts it from an executable command into a comment. For example, here are 5 lines from a state script that include the "load" command as the middle line. It has been disabled:
  6. Save the state script into a script file in the folder containing the chapter where the scene/view will be displayed. For example, if that is Chapter 1, save the script file into jtat/tutorial_name/chapter01. The filename must end with .spt.

Editing JTAT scripts in Proteopedia:

Suppose that you already have a molecular view in JTAT that you scripted in Proteopedia, but you want to make changes. If it will be easier to modify the existing scene than to re-create the desired scene from the beginning, here is how.

  1. If the existing scene is still present in the page in Proteopedia where you created it, simply edit that Proteopedia page, open the Scene Authoring Tool, and load the existing scene.

      2. If the existing scene is no longer available in Proteopedia:
    1. Edit the appropriate page in Proteopedia.
    2. Open the Scene Authoring Tool, and load the relevant molecule.
    3. Open the JTAT .spt file for the existing scene in your text editor.
    4. Transfer the script from the .spt file into Jmol's Console.
    5. Execute the script. Now you should see the existing scene.

  2. Use any of the methods listed above to change the scene. Then, continuing as above: display, copy and save the state script into the .spt file in JTAT.

You can also put molecular views obtained in FirstGlance in Jmol into JTAT script files. To do this, it is crucial that you start FirstGlance from within Proteopedia, using the link to FirstGlance beneath each Jmol display (on pages titled with a PDB identification code). These links within Proteopedia start the beta version of FirstGlance, which should be using a version of Jmol that is matched to the Jmol version used in Proteopedia and JTAT. Mismatches between the version of Jmol used to generate the state script, and the version asked to run it, may cause the molecular view to fail to appear, or to be incorrect.

Certain views that are obtained very easily in FirstGlance are very difficult to obtain in Proteopedia. These include any view generated with the Contacts.. dialog, as well as (under More Views..) the display of all salt bridges or all cation-pi orbital interactions.

As in Proteopedia, scenes obtained in FirstGlance can be modified by direct command entry into Jmol's Console before you transfer the state script. It would also be possible to transfer a FirstGlance state script into Proteopedia (by transfering it into the console and executing it), and then modify it with Proteopedia's Scene Authoring Tool. Then you could transfer the final scene from Proteopedia to a .spt file for JTAT.

Once you have obtained the desired molecular view in FirstGlance, display and transfer the state script into a .spt file, following the instructions above.

Direct scripting will be unnecessary for most JTAT tutorials. Therefore, most authors of JTAT tutorials will not need to learn direct scripting.

Learning how to make molecular view scripts is the most technical option for authoring tutorials with JTAT. If you have some knowledge of the command languages for RasMol or Chime, Jmol scripting will be very similar for basic operations. However, Jmol has many capabilities not present in RasMol or Chime.

Select atoms, then display and color them. In Jmol, as in Chime and RasMol, you select a subset of the atoms first, and then apply a display style and/or color or color scheme to them (or hide them). Next, you can select a different subset of atoms, and so forth, until the desired molecular view is complete.

Jmol's menu can be used for selection, display and coloring in either the application or the applet. Jmol's menu is cumbersome for more than a few operations, and lacks help, but may be used if you wish.

Script Command Reference Manual. The commands understood by Jmol are listed and explained in a master Jmol Command Reference Manual. Here you will find detailed descriptions of each command, often together with examples demonstrating their uses. Because Jmol is under rapid development, the documentation sometimes lags behind current Jmol behavior. If, after consulting the documentation, questions remain, don't hesitate to ask for help at the Jmol-users email list.

Jmol's command language is a superset of the language used by the MDL Chime browser plugin, which was popular from its inception in 1996 until Jmol became macromolecule-capable, around 2004 (see the Chime-based tutorials, being phased out, at molviz.org, and many more at molvisindex.org). In turn, Chime's command language is a superset of the language invented by Roger A. Sayle for RasMol, a very popular stand-alone molecular visualization application that became available in 1993. Thus, the Jmol language is easier to learn for those already familiar with the Chime or RasMol languages.

Jmol is preferable to RasMol because RasMol does not work in a web browser, and has no support for tutorials. Chime has not been developed for a decade, is not open source, and is difficult to get to work by today's standards (see About Chime).

Help: the Jmol-users email list. This is a very active email discussion of Jmol use. Not infrequently over a dozen messages are broadcast in a single day. This is the place to ask for help, to report bugs, and to make suggestions for enhancements. Suggestions for enhancements may also be entered as Feature Requests. At http://jmol.org, click on the Projects link near the upper right. There you will see the links for Feature Requests, and for the jmol-users mailing list. It is best to subscribe before you ask for help, so you can see the replies. If you don't want to keep receiving all the broadcasts, you can always unsubscribe, possibly resubscribing again later if you have more questions.

The DRuMS Standard Color Schemes. Careful selection of colors can help your structural views to communicate effectively, and enhance their attractiveness. Unless there are compelling reasons to do otherwise, we recommend that you use the DRuMS Standard Color Schemes. These build upon colors used for elements in physical models, and upon the color schemes for secondary structure in RasMol, Chime, and Jmol, and extend them to nucleotides and chemical composition. The colors are designed to be distinguishable when any or all schemes are combined. DRuMS is used in Protein Explorer, FirstGlance in Jmol, and Biochemistry in 3D, the latter being tutorials designed to complement Lehninger Principles of Biochemistry, and elsewhere.

JTAT makes it easy to apply standard (DRuMS) color schemes to your molecules by several methods.

Proteopedia. If you are using Proteopedia to generate your view scripts, it provides several DRuMS color schemes at the touch of a button. In Proteopedia's Scene Authoring Tool, in the colors tab, the following are DRuMS color schemes:

With the exceptions of amino and amino 2, the other color schemes there are also quite commonly used, although not formally part of DRuMS.

Direct Scripting. If you are writing your own scripts by hand, you may use Jmol's built-in DRuMS color schemes for element or secondary structure, or ready-made DRuMS coloring scripts provided with JTAT. Assuming the script file calling these coloring scripts is in a contents or chapter folder, these can be called as follows in .spt files:

color cpk # element, all carbons same color, cf. element.spt
etc.
script "../../_drums/element.spt" # Element (CPK), with alpha carbons darker.

script "../../_drums/composition.spt" # Composition.

color structure # Secondary structure.

script "../../_drums/aacharge.spt" # Charge (protein only).
  Colors whole residues in case terminal sidechain (charged) atoms are missing. Remainder of protein white.
script "../../_drums/polarity2.spt"
script "../../_drums/polarity4.spt"
script "../../_drums/polarity5.spt"

script "../../_drums/nucbases.spt"

Mnemonics:
script "../../_drums/nucbasesbb.spt"

script "../../_drums/polarity2.spt" # hydrophobic/polar (polarity2; protein only)

script "../../_drums/purpyr.spt"
script "../../_drums/purpyrbb.spt"
qcolors

We'll use "animation" to mean an animation that plays in Jmol, and "movie" to mean a true movie -- a series of still photos played in sequence. If you haven't already, please review the chapter on Animations and Movies in the JTAT Demonstration Tutorial. The key difference is that an animation in Jmol can be viewed from any perspective (by rotating it with the mouse), while animating. A movie has only one perspective (or a limited set). Also, the color scheme and rendering can be changed easily in Jmol to show different aspects of the animation, while a separate movie is typically required for each such change. Finally, animations in Jmol typically require transfer of less than one tenth of the amount of data through the Internet than does a movie.

In a Jmol-based tutorial, the only reason to use a movie is when the movie is already available (along with permission to use it!), thereby saving you from creating an animation, or when the movie shows something other than a molecular conformational change, and hence could not be shown in Jmol. On the other hand, in a Powerpoint presentation, movies are great because incorporating Jmol is either impossible (Macs) or technically tricky (Windows). (To create movies for Powerpoint, see Top5.MolviZ.Org.)

Generating a molecular movie that involves a conformational change involves making a multiple-model atomic coordinate (PDB) file first. Once you have such a file, you are better off animating it in Jmol.

Typically, an animation of a conformational change starts with two empirical PDB files representing two conformations. Unless the change is very small (slight shifts of a few sidechains), intermediate models will need to be interpolated in order to see and understand the structural changes. This is called molecular morphing. The main purpose of such morphing is not to predict the actual trajectory of the change, but to allow one to follow it with the eye. For examples, beyond the JTAT Demo Tutorial, there are morphs and movies that I made using RasMol and Chime in the pre-Jmol era.

The resulting multiple-model PDB file can then be animated in Jmol with a few simple commands, such as:

These commands can be seen in action in the chapter on Animations and Movies in the JTAT Demonstration Tutorial, for example, in jtat/jtatdemo/ch_anim/view01.spt.

Protein Explorer has an NMR Models and Animation control panel which is quite powerful for viewing animations of multiple-model PDB files. But it works only on Windows in Firefox, and requires that you install the free plugin MDL Chime. For more details, go to ProteinExplorer.Org.

Creating a Morph PDB File. The easiest way to morph between two empirical PDB files is by submitting them to the Yale Morph Server. This server first does a linear interpolation (see below), and then a little energy minimization on each step, producing a "chemically possible" trajectory. Yale will generally produce a satisfactory result unless you want to show ligand(s) in the animation. It can handle multiple chains including both protein and nucleic acid chains, and it can handle the situation when the empirical models have somewhat different sequences. Don't hesitate to ask the Yale team for help if at first you don't succeed -- they have been quite helpful to me.

Ligands in a Morph. Although the Yale Morph Server will strip any ligand out of submitted PDB files, you can put a ligand back into the morph it produces -- provided you only want the ligand in the starting or ending model. This is what is typically needed when the ligand induces the conformational change. The ligand ATOM lines of the PDB file can simply be copied into the appropriate (first or last) model in the morph PDB file. However, it may need to be realigned first. This can be done with the free program DeepView. If you need help, please contact me directly (emartz AT microbio DOT umass DOT edu -- I enjoy making morphs) or contact the molvis-list.

Linear Interpolation Morphing. If the Yale Morph Server does not produce the result you seek, you can perform a simple linear interpolation using free software that I wrote. Its big limitation is that the starting PDB files (first and last frames of the animation) have to have exactly the same atoms in the same order. In a linear interpolation, each atom moves in a straight line between its initial and final positions. This causes bond lengths and angles to violate normal values, and may even cause atoms to pass through each other. The result is a "chemically impossible" trajectory. However, obvious violations of chemistry serve to remind the viewer of the usual purpose of a morph (see above). Again, feel free to contact me for help or a collaboration on morph construction (emartz AT microbio DOT umass DOT edu).

Movie Formats vs. Browser Compatibility If you are going to use a movie in JTAT, you should be aware of the following issues concerning the data formats of movie files.

Making a Molecular Movie. The Polyview-3D server is the easiest place to create publication-quality movies of macromolecules. It produces multi-gif (.gif) movies which work in all popular browsers without installing any special plugins. If you want a really simple movie, such as a molecule rotating about its vertical axis, or rocking back and forth, all you need is a PDB code or PDB file.

If you want to animate a conformational change, you'll need a multiple-model "morph" PDB file. For information on creating these, please see Animations.

If Polyview-3D does not lend itself to the rendering you want in your movie, you can make an mpeg with the Jmol application. This will involve direct scripting. The application can write jpeg files, so you can write an animating script loop that writes a jpeg file for each step in the animation. You can then assemble these .jpeg files into an mpeg movie. We are told that this can be done with the free program GIMP, but we have no experience with this. For help, please ask on the jmol-users email list.

How do you put a movie in JTAT? Small movies can be placed directly in the control panel of a JTAT Tutorial, as illustrated in the chapter on Animations and Movies in the JTAT Demonstration Tutorial. Also illustrated there is the use of a link in the control panel to open a new browser tab or window to show a large movie. If you want to use a movie in your tutorial, please take a look at the code in jtat/jtatdemo/ch_anim/chapter.js, for a small movie in the control panel (look for lacrep_anim_small.gif), or jtat/jtatdemo/ch_anim/lacrepan.htm, for a large movie in a separate window.

END OF COMPLETED INSTRUCTIONS -- MORE REMAIN TO BE ADDED BELOW! 
###########################################################################

Below are some notes to myself that might be useful until I get them
properly incorporated into the instructions document.

I have not yet described how to set up a view button in a
chapter. This should be straightforward from examining
jtat/tutorial_name/chapter_name/chapter.js and/or
jtat/template/chapter01/chapter.js.

Not mentioned below, but to be described in a future version of
these instructions, are many javascript and style sheet variables that control
things. You can find these in the files described
above.

In particular, use the color schemes (in .spt files and in HTML text)
provided in jtat/_drums!!

--------
How to find out which script file (*.spt) is attached to a view
button. (Show History)

Reload the chapter (click on the browser's reload/refresh button)
so only the initial view has been displayed. Next, click the
button for the view in question. (Don't click other views first,
as they will add confusion.) Open Jmol's menu, and click Show,
History. The Jmol Console window will open, and the commands
that have been sent to Jmol will be listed.

The command history shows all commands sent to Jmol since the
applet was first loaded in the chapter. The initial view script
block will start after a comment "# Begin Script for Initial
View" and end before a comment "# End Script for Initial View".
Within this block will typically be the command "script
initial-view.spt", since that is the default script file used for
the first view in a chapter. Before and after this line will be
other commands that JTAT automatically adds to the .spt file
itself.

Following the initial-view script will be the script for the view
button you pressed. For example, if you pressed "View 5", it will
start after the comment line "# Begin Script for View 5" and end
before the comment "# End Script for View 5".

Note that the commands within a script file (*.spt) are not shown
in the history. For example, the file "initial-view.spt"
typically includes the command "script view01.spt", but this will
not be listed in the history. There are two ways to see
all of the commands received by Jmol. One is to open the
.spt file(s) in a text editor. The other is to use "set
debugscript on" (see next section below).



Debugging Scripts

There are two reasons why a script may not produce the desired
molecular view.

First, the commands may simply not be the ones needed to produce
the desired view, even though all commands may be syntactically
correct (understood by Jmol). In this case, you will have to try
different commands, experimenting until you acheive the desired
view. If, after consulting the Jmol command language
documentation (see "What is a Script"), you are still unable to
do this, don't hesitate to ask for help at the jmol-users email
list (link to section above).

The second reason why the desired molecular view may not be
achieved is that one or more commands in a script may be
syntactically invalid, meaning that Jmol cannot understand them.
Such commands are reported by Jmol as "script ERROR:" followed by
details. These reports appear in the Jmol console. @@@ what if
the error is in a .spt file? do they still appear with
debugscript off?

It is very helpful to be able to see the actual commands Jmol
executed, in order. To do this, open the Jmol console (link). In
the lower box (command input box), type "set debugscript on" and
press Enter. Make sure that you typed it correctly by noting
whether any error is reported in the top box (output box). Also
you can find out whether debugscript is on or off (true or false)
by entering the command "show debugscript".

With debugscript on, click the "Clear Output" button in the Jmol
Console. Now, click a view button in your tutorial. The output
box of Jmol's Console will list every command executed, in order,
including commands within script files (*.spt). Examine the
output carefully for any ERROR reports.

If your tutorial has multiple-molecule views, you first need to
display a view with the number of molecules that are in the view
you wish to debug. Then open the console for one of the Jmols (or
for as many as you wish -- multiple Jmol consoles can be open at
once), set debugscript on, and proceed as above. If the number of
Jmols (molecules) changes when you click the problematic view
button, then new Jmol(s) will be loaded, and these will not have
debugscript turned on.

The above scheme shows all commands and all errors. Often,
however, you will be primarily interested in debugging commands
in a script file. This can also be done by inserting two commands
into the script file, at the top, one to open the console, and
one to turn on debugging:

console
set debugscript on

This method does not report commands that are automatically
inserted by JTAT before and after your script file. However, if
you now click "Clear Output" and press the problematic view
button again, the console is already open and debugging is
already on, so on this second pass, you will see all commands.

After you have debugged the script file, and the desired
molecular view is being achieved, you can either delete the above
two commands, or comment them out by prefixing them with the
pound sign, as follows:

#console
#set debugscript on
 
Color Scheme

Open Jmol's menu. Here you can select portions of the molecule
(or all of it) using the options under Select. The number in
parentheses (following the word "Select") is the number of atoms
currently selected. You can then apply a plain color, or a
multiple-color scheme, to the selected atoms using the Color
menu. For atoms represented as spheres ("spacefilled"), color
atoms. For secondary structure cartoons, color
cartoon. For straight backbone "rods" connecting
alpha-carbon positions, color backbone. For smoothed
backbone traces, color trace, and so forth.

You can also apply any arbitrary red-green-blue values (RGB) to
the selected atoms with commands such as

color atoms [x00ff00] # RGB hexadecimal values 00, ff, 00
color cartoon [x428691] # RGB hexadecimal values 42, 86, 91
color cartoon [66, 134, 145] # RGB decimal values equivalent to the previous line

For more on these commands, see the Jmol command script
documention (link to scripts, above).