MD Movie

MD Movie is a tool for viewing and analysis of trajectories and other ensembles. For examples of use, see the Trajectory and Ensemble Analysis tutorial. See also: Morph Conformations, coordset

There are several ways to start MD Movie, a tool in the MD/Ensemble Analysis category.

Several formats are supported:

These input files can be gzipped.

The PDB options generally require coordinates for the same set of atoms to be supplied for each frame. However, if the coordinates supplied for a frame represent only a subset of the atoms in the preceding frame, it will be inferred that the remaining atoms are present but have the same coordinates as in the preceding frame. Changes are cumulated in the forward direction and based on all frames, even when frames are skipped during playback (step size > 1).

All or a contiguous subsegment of a trajectory can be loaded. If pipe is entered as the ending frame number, the input trajectory will be read until it runs out, as long as no other input specifies a smaller ending frame number. For example, for a GROMOS trajectory, the NSTLIM variable in the PROMD file should also be increased to at least the total number of frames expected. When a pipe has been specified, there will be an attempt to load the entire trajectory up front.

A further option is a metafile, simply a text file that specifies the input files/parameters. The first line designates trajectory type (where case is unimportant but any spaces should be stripped, for example, namd(prmtop/dcd) or gromos), and optionally, starting and ending frame numbers of the range to be loaded. A pipe can be specified as described above. If no frame numbers are supplied, the entire trajectory will be loaded; however, if "?" is given for both the starting and ending frame numbers, a dialog for entering this information will appear. The remaining lines specify input files and parameters in the same order as in the dialog. For example:

amber 500 1000
dna.prmtop
dna.mdcrd

pdb
single
108d.pdb

After input files and parameters have been specified, the first set of coordinates will be displayed and the MD Movie controller will appear:

If a subsegment was specified, a message about the restricted frame range will be displayed temporarily. The total number of frames in the trajectory (whether loaded or not) will continue to be reported. For all input formats except PDB and XYZ, the coordinates for a given frame are not read in until that frame is viewed or used for analysis.

From left to right, the buttons mean: play backward continuously; go back one step; stop; go forward one step; and play forward continuously. When the Loop option is on, forward play can wrap from the end to the beginning of the loaded trajectory and reverse play can wrap from the beginning to the end. The rate of continuous play can be adjusted with the Playback speed slider; up to a 1-second delay can be added between frame advances. When continuous play is not in use, the display can also be controlled by moving the pointer (inverted triangle) on the timeline or by entering a new Frame number. The Step size controls the level of sampling for continuous playback. For example, a step size of 3 indicates that only every third frame will be shown; however, when forward play loops from end to beginning, the movie will start at the first frame loaded, and when reverse play loops from beginning to end, the movie will start at the last frame loaded. Frame number and step size changes take effect when return (Enter) is pressed.

Frames can also be navigated by moving the black vertical line on a distance or angle plot or by using the command coordset. Pausing any continuous playback with the dialog is recommended before using these other methods.

** Protein secondary structure assignments are not recomputed automatically over the course of a trajectory. If displaying protein as a ribbon, see the note below. **

The current frame or all frames that have been viewed can be saved as a PDB file with File... Save PDB. The view can be held steady on selected atoms. One can define scripts to be executed at each frame update. A complete menu listing with short descriptions is included below.

Hide closes the interface without exiting from MD Movie; the interface can be reopened using the Tools menu entry for the instance of MD Movie. Quit exits from MD Movie and removes the structure from the Chimera window. Help opens this manual page in a browser window.

Images can be captured during trajectory playback and automatically assembled into a movie file. Manipulations in Chimera can be performed and per-frame scripts executed during the playback/image-saving process. See also: coordset, making movies

Important notes:
• Protein secondary structure assignments are not recomputed automatically over the course of a trajectory. If a protein or peptide is displayed as a ribbon with secondary-structure-specific scaling (width and height) and significant conformational changes are occurring, users may want to reassign secondary structure at each frame. This can be done with a per-frame script that includes the Chimera command ksdssp.
• For a one-to-one relationship between trajectory frames and recorded image frames, the Playback speed slider should be moved to the far right. Otherwise, identical image frames will be inserted between the unique data frames to slow playback. The frame number parameters described below refer only to the unique data frames. See also: frame rate and movie speed
• On certain platforms, other windows should not overlap the Chimera graphics window during recording (details...). This is not an issue when raytracing is used.

• File name - name for the resulting movie file
• File type (movie format) choices:
  • H.264 [.mp4]
  • VP8/WebM [.webm]
  • Theora [.ogv]
  • Quicktime [.mov]
  • AVI MSMPEG-4v2 [.avi]
  • MPEG-4 [.mp4]
  • MPEG-2 [.mpg]
  • MPEG-1 [.mpg]
  • WMV2 [.wmv]
• Starting frame (first frame loaded, by default) - number of the first frame at which to save an image
• Step size [n] - level of sampling within the indicated range (every n^th frame will be used)
• Ending frame (last frame loaded, by default) - number of the last frame to possibly include (if not skipped by sampling); must be within the range originally loaded
• Encode forward then backward ("roundtrip") (true/false) - whether to include the frames in reverse order as the second half of the movie
• Rendering:
  • Chimera (default) - Chimera rendering, normally offscreen (details...). Images can be supersampled, that is, initially generated at a higher resolution and then sampled down to the final size.
    • Supersample (1x1/2x2/3x3/4x4) - how many pixels to sample in the X and Y dimensions for each pixel in the final saved image; thus, 1x1 corresponds to no supersampling. Higher values increase the smoothness of edges in saved images and increase calculation time with little effect on file size. 3x3 is generally recommended when supersampling is done.
  • POV-Ray - raytrace with POV-Ray. This rendering option is the slowest but includes fancier effects such as high-quality shadows. The POV-Ray Options button opens the corresponding preferences.

• Quality (highest/higher/high/good/medium/fair/low) - higher quality corresponds to higher (variable) playback bit rates and a larger movie file, assuming the same window size and movie frame rate
• Image format - image file format (however, PNG will be used regardless of this setting if raytracing is done):
  • JPEG [.jpeg]
  • PNG [.jpeg]
  • PPM [.jpeg] (default)
• Additional recording options - options are the same as for the command movie record; if this field is left blank, image frames will be saved with default names in a default location (but normally deleted after movie encoding, depending on the encoding options)
• Additional encoding options - options are the same as for the command movie encode; if this field is left blank, the movie will be encoded to play at 25 frames per second, and image frames will be deleted after the movie has been encoded

Close closes the dialog without initiating recording. Image Tips shows the tips on preparing images, and Help opens this manual page in a browser window.

Per-Frame... Define script allows specification of a script to be executed at each trajectory frame. Scripts can be written in Chimera commands or Python code, and can incorporate trajectory frame numbers. Python scripts can also access the molecule model instance.

Examples:

• the following Chimera command script (eachFrame.com) identifies hydrogen bonds at each frame and shows only the residues involved:

  chain @ca
  ~disp solvent
  hb line 2 color yellow reveal true
  

  Commands to be executed only at a specific frame can be indicated with a leading #frame_num: (for example, #50:) that will be stripped before the command is executed.
  
  
• the following Python script (specificFrames.py) initiates events at specific frames:

  from chimera import runCommand
  frame = mdInfo['frame']
  if frame == mdInfo['startFrame']:
          runCommand("roll y 3 40")
  elif frame == 10:
          runCommand("color green")
  elif frame == 50:
          runCommand("color orange")
          runCommand("rl :ala; color dodger blue :ala; rep stick :ala")
  elif frame == 90:
          runCommand("~rl; rep wire :ala")
  else:
          runCommand("color byhet")
  

Note: Frame arguments in commands such as roll refer to image frames rather than to unique data (trajectory) frames. For a one-to-one correspondence between image and trajectory frames, the Playback speed slider must be positioned all the way to the right and the viewing step size set to 1. Whereas an MD Movie per-frame script executes at each trajectory frame, commands to be executed at each image frame (independent of any trajectory) can be specified with the perframe command. The rate at which Chimera draws image frames can be controlled with set maxFrameRate.

Insert text file allows browsing to a text file and placing its contents in the script area. Save to file saves the current contents of the script area to a text file.

OK and Apply execute the script with and without closing the dialog, respectively. If the movie is playing, the script will continue to be executed for each trajectory frame until Stop running script is chosen; if the movie is halted on a single frame, the script will be executed for that frame and will not be executed again until a different frame is shown. Clear deletes the contents of the script area. Close closes the dialog without executing the script, and Help opens this manual page in a browser window.

Analysis... Plot allows plotting values of structure measurements versus frame number:

• Distances
• Angles (each defined by three atoms, not necessarily bonded)
• Dihedrals (each defined by four atoms, not necessarily bonded)
• RMSD (root-mean-square deviation of specified atoms relative to a reference frame)

RMSD calculations require specifying the atoms of interest and the reference frame number. As in all-by-all RMSD analysis, least-squares-fit RMSD values are calculated without applying any transformation. The atoms can be specified by selection (where lack of selection indicates all atoms) in combination with the options:

• Ignore solvent and non-metal ions (true/false) - whether to ignore solvent residues and monatomic anions (Cl^–, Br^‐, etc.)
• Ignore hydrogens (true/false)
• Ignore metal ions (alkali/true/false) - whether to ignore alkali metal ions (Li⁺, Na⁺, K⁺, etc.), or all metal ions (if true), or none (if false, thus including any metal ions)

If frames have not yet been viewed/loaded, a dialog will appear with the choices: load all frames (in the range specified in the initial input), load every n^th frame, or simply wait until a frame is viewed to load it. Loading via this dialog is faster than viewing/playing the whole trajectory. If not all frames are loaded at this point, the plot will be filled in with additional values as the trajectory is viewed.

• line color (a color well)
• whether Shown on the plot
• measurement value at the current frame
• for distances/angles: names of the atoms defining the measurement
• for RMSDs: reference frame and number of atoms (per frame) used in the calculation

Plots can be hidden individually using the button above the table or collectively by closing the dialog window. In either case, the plots have not been deleted and can be shown again using the MD Movie Analysis... Plot menu.

The current frame is indicated with a vertical black line on the plot. Clicking elsewhere on the plot will reposition the line and jump to the corresponding frame, and playback can be controlled directly by dragging the line. Pausing any continuous playback is recommended to facilitate such manual control over frame viewing.

Below each plot are standard plot navigation icons provided by matplotlib. Images saved via the icon will not include the vertical black line. The Dump Values button at the bottom of the dialog allows saving measurements to a text file, using the number of decimal places specified in Structure Measurements.

It may be interesting to see which regions of space are highly populated by certain atoms relative to others in the trajectory or ensemble. For example, cations or water hydrogens may tend to occupy space around a negatively charged solute group. Occupancies can be represented as a three-dimensional grid of values, or volume data. Analysis... Calculate occupancy can be used to generate such data and display it with Volume Viewer. The occupancy map can be saved to a file and later reopened in Chimera.

The occupancy values are simply counts of how many times an atom in the specified set falls within a grid cell, except that the weighted-sphere option may award increments of >1 per atom. Both sphere options may increment multiple grid cells per atom.

Usually, one should first define a reference set of atoms to hold steady (the trajectory frames will be transformed to keep these atoms in the same place and orientation, as much as possible). This is accomplished by selecting the desired reference atoms and then choosing Actions... Hold selection steady. When the selection is later changed, the "hold steady" atoms will not change unless Actions... Hold selection steady is used again.

Next, one should select the atoms for which occupancy data will be collected. The atoms in the selection can be combined into a single set of occupancy data, or segregated by atom type.

• Starting frame (first frame loaded, by default) - number of the first frame to include in occupancy calculations; must be within the range originally loaded
• Step size [n] - level of sampling within the indicated range (every n^th frame will be used)
• Ending frame (last frame loaded, by default) - number of the last frame to possibly include (if not skipped by sampling); must be within the range originally loaded
• Limit data collection to within cutoff distance of any "held steady" atoms (true/false) - whether data should be collected only within the cutoff distance of any atom in the prior hold steady specification. This option is ignored if there was no hold steady specification.
• Cutoff distance (10.0 by default) - angstrom distance used to limit the volume data region to a zone around atoms in a prior hold steady specification
• Volume grid spacing (default 1.0 Å) - resolution of the resulting volume data grid
• Volume data name - name to use for the resulting volume data set(s); the name(s) will be listed in the Volume Viewer interface. For separate data sets collected for different atom types, the atom type symbol is enclosed in brackets and appended to the name.
• Collect data separately for each atom type in selection (true/false) - whether to make a separate set of volume data for each atom type in the selection
• Treat atoms as - whether to consider atomic VDW radii in occupancy calculations (the larger the grid spacing relative to the radii, the smaller the differences in results among the options)
  • points (default) - increment the count for each grid cell containing an atom center
  • uniform VDW spheres - increment the count for each grid cell with any part inside the VDW radius of an atom
  • center-weighted VDW spheres - increment the count for each grid cell with any part inside the VDW radius of an atom, but award cells in the outermost layer an increment of 1, the next layer inward an increment of 2, the next layer 3, etc. A grid cell is in the outmost layer if it overlaps the atom sphere but any adjacent grid cell (including those diagonally adjacent) does not.

Close closes the dialog without initiating the calculation. Help opens this manual page in a browser window.

• Starting frame (first frame loaded, by default) - number of the first frame to include in RMSD calculations; must be within the range originally loaded
• Step size [n] - level of sampling within the indicated range (every n^th frame will be used)
• Ending frame (last frame loaded, by default) - number of the last frame to possibly include (if not skipped by sampling); must be within the range originally loaded
• Lower RMSD threshold (white) (0.5 by default) - initial lower RMSD threshold for coloring, in angstroms; white will be used for this value and lower. If auto-recoloring is turned on, the threshold may change after all of the values have been computed.
• Upper RMSD threshold (black) (3.0 by default) - initial upper RMSD threshold for coloring, in angstroms; black will be used for this value and higher. RMSD values between the thresholds will be mapped to grayscale. If auto-recoloring is turned on, the threshold may change after all of the values have been computed.
• Restrict map to current selection, if any (true/false) - whether to use only the selected atoms, when a selection exists
• Ignore solvent and non-metal ions (true/false) - whether to ignore solvent residues and monatomic anions (Cl^–, Br^‐, etc.)
• Ignore hydrogens (true/false)
• Ignore metal ions (alkali/true/false) - whether to ignore alkali metal ions (Li⁺, Na⁺, K⁺, etc.), or all metal ions (if true), or none (if false, thus including any metal ions)
• Auto-recolor for contrast (true/false) - whether the RMSD map should be recolored automatically after all values have been computed, using thresholds that enclose the middle third of values (i.e., the lowest third of values will be white, the middle third in grayscale, the highest third black)

OK and Apply initiate the calculations with and without closing the dialog, respectively, while Close simply dismisses the dialog. Help opens this manual page in a browser window.

For each frame-to-frame comparison, the least-squares-fit RMSD between the indicated sets of atoms will be calculated, without applying any transformation. The values will be shown as grayscale squares within an RMSD map. The calculations may require additional frames to be read (frames within the loaded range are not actually read until viewed or otherwise used) and may take several minutes, depending on the size of the system and the number of frames. The Abort button at the bottom of the RMSD map dialog allows termination of a calculation in progress. To decrease computational time, use a sparser sampling of frames (larger step size) and/or fewer atoms in the calculation.

Multiple RMSD maps can be open at the same time. A given map can be recolored (without recalculation of RMSD values) using the map's menu option RMSD... Change thresholds to adjust the white/black threshold settings. When the cursor is placed over a map, the corresponding frame numbers and RMSD value are given below the map. Clicking on a map places the corresponding frame numbers in the Frame fields; clicking Go will show the corresponding frame of the trajectory in the graphics window.

Below the plot are standard navigation icons provided by matplotlib.

Other buttons on the RMSD map dialog:

• Save RMSDs - save the matrix of RMSD values to a text file
• Close - dismiss/delete the RMSD map
• Help - show this manual page in a browser window

• Starting frame (first frame loaded, by default) - number of the first frame to include in clustering calculations; must be within the range originally loaded
• Step size [n] - level of sampling within the indicated range (every n^th frame will be used)
• Ending frame (last frame loaded, by default) - number of the last frame to possibly include (if not skipped by sampling); must be within the range originally loaded
• Cluster based on current selection, if any (true/false) - whether to limit calculations to only the selected atoms, when a selection exists
• Ignore solvent and non-metal ions (true/false) - whether to ignore solvent residues and monatomic anions (Cl^–, Br^‐, etc.)
• Ignore hydrogens (true/false)
• Ignore metal ions (alkali/true/false) - whether to ignore alkali metal ions (Li⁺, Na⁺, K⁺, etc.), or all metal ions (if true), or none (if false, thus including any metal ions)

OK and Apply initiate the calculations with and without closing the dialog, respectively, whereas Close simply dismisses the dialog. Help opens this manual page in a browser window.

For each frame-to-frame comparison, the least-squares-fit RMSD between the indicated sets of atoms will be calculated, without applying any transformation. The calculations may require additional frames to be read (frames within the loaded range are not actually read until viewed or otherwise used) and may take several minutes, depending on the size of the system and the number of frames. The Abort button on the progress dialog allows terminating the calculation. To decrease computational time, use a sparser sampling of frames and/or fewer atoms in the calculation.

Clustering results are shown in a dialog. The top part of the dialog lists the clusters, and for each, the number of Members (how many of the input frames belong to the cluster) and the frame number of the best representative. Different colors are used to show membership in the different clusters within the timeline plot in the bottom part of the dialog. The color used for a cluster can be changed by clicking its color well and using the Color Editor.

Clicking the line for a cluster in the top part of the dialog displays its representative frame in the main window and makes the bars for all of the members of that cluster taller on the timeline plot. The current frame is indicated with an inverted triangle on the plot, and the trajectory can be navigated by moving the triangle, just as in the MD Movie controller dialog. Although more than one cluster can be chosen with the mouse in the top part of the dialog, only one frame can be displayed at a time.

An average structure for a cluster can be calculated by choosing the cluster in the top part of the dialog and clicking Generate average structure for cluster.

Below the plot are standard navigation icons provided by matplotlib.

Save allows writing the clustering information (membership and representatives) to a text file. Close dismisses the cluster dialog. Help opens this manual page in a browser window.

An average structure can be computed for the whole trajectory or user-specified frame ranges with Analysis... Average structure in the MD Movie menu, or for a chosen cluster by clicking the Generate average structure... button in the cluster dialog.

A simple average of the Cartesian (x,y,z) coordinates of the biopolymeric components of the trajectory (proteins/peptides and nucleic acids) is calculated and the result opened as a new model. The average structure may be distorted, especially in conformationally variable areas.

Choosing Analysis... Average structure opens a dialog with the following options:

• Starting frame (first frame loaded, by default) - number of the first frame to include in averaging
• Step size [n] - level of sampling within the indicated range (every n^th frame will be used)
• Ending frame (last frame loaded, by default) - number of the last frame to possibly include (if not skipped by sampling); must be within the range originally loaded

• Align structures based on current selection, if any (true/false) - align the frames to be averaged by matching the selected atoms
• Omit hydrogens (true/false) - whether to omit hydrogens from the average structure
• Include metal ions (true/non-alkali/false) - which metal ions to include in the average structure: all, all non-alkali (default, omitting Li⁺, Na⁺, K⁺, etc.), or none
• Name average structure (default average) - name for the new model

• Save PDB... open a dialog to save the current frame or all frames that have been viewed as a PDB file
• Record movie... set parameters for saving image frames and encoding them as a movie file
• Load Additional Frames... (only available for Amber trajectories and DCD files, see formats) read an additional trajectory file and append its frames to the end of the current trajectory

• Hold selection steady - transform subsequent trajectory frames to keep the selected atoms in the same place and orientation, as much as possible (since the atoms may move relative to one another). For best results, the selection should include at least three atoms, not linearly arranged, to define a frame of reference. If the selection is changed, Hold selection steady must be chosen again to start using the new selection.
  
  
• Stop holding steady - return to the default behavior of only transforming the coordinates according to user manipulations and commands

• Define script... open a dialog for entering a script (written in Chimera commands or Python code) to be executed after each trajectory frame update. OK and Apply execute the script with and without closing the dialog, respectively. If the movie is playing, the script will continue to be executed for each trajectory frame until Stop running script is chosen.
• Stop running script - do not run the script after subsequent trajectory frame updates

• Calculate occupancy... collect and display (with Volume Viewer) occupancy data for the selected atoms over a specified set of frames (details)
• Cluster... cluster the trajectory based on all-by-all RMSD comparisons among specified frames (details)
• RMSD map... calculate a two-dimensional RMSD map containing all-by-all comparisons among specified frames (details)
• Average structure... calculate a Cartesian average structure over specified frames (details)

MD Movie uses the Trajectory module to read the various formats (chimera/share/Trajectory, where chimera is the Chimera installation location). Trajectory contains a subdirectory, formats, which in turn contains subdirectories that each correspond to the Python module for a supported format. By convention, the module (and directory) name for each format is the name of the format with the first letter of each word capitalized and all other letters lowercase. For example, the MMTK module's name is Mmtk.

A format's module is typically structured so that the code that interfaces with Trajectory's generic format handling is in __init__.py, and the code specific to reading a particular format is in another python file, usually named after the format itself (for example, Gromos.py).

__init__.py must support the following:

• If the format name displayed to the user should be different from the module name (usually it should, due to capitalization), then there must be a global variable named formatName that is initialized to the display name of the format.
• A class named ParamGUI must be defined to handle presenting the file-loading interface to the user. It must have two methods:
  • __init__, which receives a Tkinter.Frame instance argument. The __init__ method should populate the frame with widgets for gathering the input information for the format from the user.
  • loadEnsemble, which takes as arguments a starting frame number, ending frame number, and callback function. loadEnsemble needs to compose a list of the arguments that were provided by the user to the widgets defined in __init__, and then call this module's global loadEnsemble function (see below) with that list as the first argument and the start/end frame number and callback as the remaining three arguments.
• A global loadEnsemble function that generates an ensemble instance (discussed later). This function is not only called by the ParamGUI.loadEnsemble method, but also when a metafile is used to specify the input parameters. This function takes four arguments: a format-specific list of input parameters, a starting frame number, an ending frame number, and a callback function to start the MD Movie interface. The global loadEnsemble function should call the interface with the generated ensemble as an argument, and should remember the provided format-specific values as preferred defaults for future uses of the format.

The format-specific .py file defines an ensemble class that gets instantiated from __init__.py's loadEnsemble function. The ensemble class must support the following methods:

• An __init__ method that takes the format's input parameters and start/end frames as arguments. The __init__ method may read input files or do whatever is necessary to support the other instance methods (such as call into a C/C++ module to read the files, as is done for Amber format).
• A GetDict method that takes a string argument. The string specifies what data should be returned. The possible string values are:
  • atomnames - return a list of the atom names; a residue's atoms must be consecutive
  • elements - return a list of the atom elements. These should be instances of chimera.Element (which can be initialized with a string such as "Fe" or a number). Trajectory's determineElementFromMass function may be useful if the format does not specify the atomic number directly or it cannot be determined easily from the atom name.
  • resnames - return a list of the residue names
  • bonds - return a list of bonds (2-tuples of indices into the atomnames list)
  • ipres - a list of the first atom of each residue (indices into atomnames, but unlike previous indices these are 1-based, so the first element of ipres will always be 1)
• A __getitem__ method taking a frame-number argument (starting with 1): return a list of 3-tuples corresponding to the xyz coordinates of the atoms in that frame (in the same order as atomnames). The coordinates should be in angstroms.
• A __len__ method that returns the total number of frames in the trajectory (not just the number of frames between the user-specified start/end frames).