Next: Acknowledgements Up: Timeline Tutorial Previous: Trajectory analysis: titin domain Contents

Subsections

Analysis Scripts

Simple user-defined all-residue scripts

The Calculate $\rightarrow$ Calc. User Defined (Per.-Res.) command allows you to call the name of a user-defined tcl procedure which will be run on every residue. Name the function in Analysis Define every residue function; prepend ``::'' to indicate the global namespace. The named Tcl procedure will be provided with three VMD selections to work with: resCompleteSel (the current residue or selection group), resAtomSel (a single atom for each protein or nucleic residue), and proteinNucSel ("protein or nucleic" VMD selection for the whole molecule).

Example 1:

Type into the VMD Tk console:

proc ::myResX {resAtomSel  resCompleteSel  proteinNucSel} {
    return [$resAtomSel get x]
}

Example 2: Type into the VMD Tk console:

proc  ::myCountContacts {resAtomSel  resCompleteSel  proteinNucSel} {
    return [llength [lindex [measure contacts 4.0 $resCompleteSel \
             $proteinNucSel ] 0]]
}

The above files can be sourced from the VMD Tk Console:
cd timeline-tutorial-files, cd examples,then source myResX.tcl
and
source myCountContacts.tcl .
The functions will remain available for the rest of the VMD session; .

Writing a .tcl script to generate a per-residue .tml data file

The Timeline plugin can save data to .tml files, which provide per-residue or per-selection data for a given molecule and trajectory. This subsection shows how to generate a per-residue .tml file using Tcl code. These can be generated in a non-interactive VMD session, running on one or more processors, to enable long calculation jobs.

Use your text editor to create a tcl file in the the timeline-tutorial-files to contain the data calculation script. Name it: titin-per-res-rmsd.tcl. We'll include some simple commands, and two tcl procedures: the user-specfied analysis myRmsdBatchCalc, and the plugin-provided ::timeline::writeDataFileHeader

See sample scripts, including the completed version of titin-per-res-rmsd.tcl, in the examples directory, which is in the timeline-tutorial-files directory.

Require the Timeline Tcl package (will load if not already present; this is required when VMD is started in text-only mode)
```
package require timeline 2.0
```

Add commands to load trajectory data. For a newly-started VMD session, the following will load the trajectory as molecule 0, so we'll set that as the molecule to analyze.

mol new titin.psf type psf first 0 last -1 step 1 filebonds 1 \
        autobonds 1 waitfor all
mol addfile titin.dcd type dcd first 0 last -1 step 1 filebonds 1 \
        autobonds 1 waitfor all

set myMolid 0

Set the file name to which you will write data:
```
set outFilename titin-per-res-rmsd.tml
```
Begin a tcl procedure to analyze and write the analysis data
```
proc myRmsdBatchCalc {filename molid} {
```
Since we are making a per-residue data file, usesFreeSelection is set to 0. (See the follwinng subsection for more on "Free Selection".)
```
  # 0 for per-residue calcs
  # 1 for per-selection calcs
  set usesFreeSelection 0
```

Set all the following values, which will satisfy all user-set header data Here, we set set the chain and the number of residues we examine manually. This molecule has only 1 chain; for molecules with more chains we would have to generate data for all chains.

  # include units in title
  set dataTitle "res. RMSD (A)"
  set firstFrame 0
  set lastFrame 96
  # the sample molecule is a 1-chain, 1-segment molecule, so 
  # we will do a simple loop over residue numbers
  set theChain "T"
  set theSeg "TIT"
  set firstRes 1
  set lastRes 89

  set numFrames [expr $lastFrame - $firstFrame + 1]

Set the number of items (referred to as selection groups)

  set numSelectionGroups [expr $lastRes-$firstRes + 1]

Check the filename and open the file for writing

if {$filename == ""  } {
    die "usage: myRMSDBatchCalc FILENAME MOLID\n FILENAME\
           cannot be an empty string."
   }

set outDataFile [open $filename w]

Now write out the .tml data file header.

::timeline::writeDataFileHeader $outDataFile $molid $dataTitle \ 
     $numFrames $numSelectionGroups $usesFreeSelection

Now perform the actual analysis calculations for the whole trajectory, looping over residues and frames, and output the data. For this example, we calculate the RMSD of each individual residue for each frame of the simulation vs. its initial (frame 0) configuration

  set chain $theChain
  set seg $theSeg
  for {set r $firstRes} {$r <= $lastRes} {incr r} {
    set sela [atomselect $molid "resid $r"]
    set selb [atomselect $molid "resid $r"]
    $sela frame 0
    for {set f $firstFrame} {$f<=$lastFrame} {incr f} {
      $selb frame $f
      display update
      set val [measure rmsd $sela $selb]
      set resid $r
      puts $outDataFile "$resid $chain $seg $f $val"
    }
  }

Now that all the data has been written, close the data file and end the procedure.
```
  close $outDataFile
  return
}
```
Now we call the procedure we just entered.
```
myRmsdBatchCalc $outFilename $myMolid
```
Generate the .tml file by running the .tcl script in VMD, in either an interactive session using the source command or at a command prompt:
vmd -dispdev text -eofexit < titin-per-res-rmsd.tcl > titin-per-res-rmsd.log .
To view the data in Timeline, load the corresponding trajectory into an interactive VMD session, then load the .tml file you generated into Timeline, in either of these ways:
- Use Timeline menu File $\rightarrow$ Load Data File to load a single file
- or via Timeline menu Data $\rightarrow$ Set Collection Directory when you have placed the .tml file placed in a directory with other .tml files to form a Data Collection for this trajectory.
An example of the output Timeline data file titin-per-res-rmsd.tml, which is in the example_output directory in the examples directory.

**Figure 12:** Protein contacts count, per beta strand, for titin I91 domain, over all frames of the loaded trajectory. When selected in the 2D view (left panel), the whole strand is highlighted in the 3D view. (right panel). The values in the 2D view are the total protein contacts for all the residues in each strand.
$\includegraphics[width=5.5in]{FIGS/tl-strand-contacts}$

Writing a .tcl script to generate a per-selection .tml data file

This subsection shows how to generate a per-selection .tml file using Tcl code. These can be generated in a non-interactive VMD session, running on one or more processors, to enable long calculation jobs.

See a per-selection plot in Figure 12. Note that the selection of a single element in the 2D plot selects a large selection of the molecule; here all the residues in beta-strand B.

Create a tcl file to contain the data calculation script. For example: titin-strand-contacts.tcl. We'll include in this file some simple commands, and two tcl procedures: the user-specfied analysis myUserDataWrite, and the plugin-provided ::timeline::writeDataFileHeader.
See sample scripts, including the completed version of titin-strand-contacts.tcl, in the examples directory in timeline-tutorial-files.
Require the Timeline Tcl package (will load if not already present; this is required when VMD is started in text-only mode)
```
package require timeline 2.0
```
Set the file name of the .tml file you want to produce, and the target molecule number.
```
set theFilename titin-strand-contacts.tml
set theMolid 0
```

Add commands to load the trajectory data. For a newly-started VMD session, the following will load trajectory as molecule 0:

# load the file
mol new titin.psf type psf first 0 last -1 step 1 filebonds 1 \
        autobonds 1 waitfor all
mol addfile titin.dcd type dcd first 0 last -1 step 1 filebonds 1 \
        autobonds 1 waitfor all

Start defining the analysis procedure:

proc myBatchDataWrite {filename molid} {

Since we are making a per-selection data file, usesFreeSelection is set to 1. ``Free Selection'' since the user can assign arbitrary atoms to each selection group. The atoms in a selection group are set at the initial frame of the loaded trajectory; the atoms in a selection group are not recalculated for later frames in the trajectory.
```
# 0 for per-residue calcs
# 1 for per-selection calcs
set usesFreeSelection 1
```

Set all the following data, which will satisfy the required header data except for numSelectionGroups.

set dataTitle "# contacts"
set firstFrame 0
set lastFrame 96

set numFrames [expr $lastFrame - $firstFrame + 1]

Set the number of selection groups. For each selection group, there is a VMD selection string, and a human-readable label.

  set labeledSels  [list {"strand A" "resid 4 to 7"}\
          {"strand A'" "resid 11 to 15"} \
          {"strand B" "resid 18 to 26"}  \
          {"strand C" "resid 32 to 36"}  \
          {"strand D" "resid 47 to 52"}  \
          {"strand E" "resid 55 to 61"}  \
          {"strand F" "resid 69 to 75"}  \
          {"strand G" "resid 78 to 88"}]
  set numSelectionGroups [llength $labeledSels]

Set data filename to output and open the file for writing

  if {$filename == ""  } {
    die "usage: myBatchDataWrite FILENAME MOLID"
   }

  set outDataFile [open $filename w]

Analyze the trajectory. For this tutorial, we have manually specified selections, and so here we do know the number of selection groups. In other scripts, selection groups are chosen during analysis, e.g. for a hydrogen bond display script, each selection group is the set of atoms involved in a hydrogen bond, and the number of selection groups is the total number of such groups detected across frame in the loaded trajectory, which changes with each trajectory.

  # Calculation takes place here 
  # Also, assigns the freeSelLabel and freeSelString for 
  # each selection group. 
  set protSel [atomselect $molid "protein"]
  set i 0
  foreach {selPair} $labeledSels {
    foreach {label seltext} $selPair {}
    puts "starting sel. label: >>$label<<  seltext: >$seltext<"
    set trajdat(freeSelLabel,$i) $label 
    set trajdat(freeSelString,$i) $seltext 
    set sel [atomselect $molid $seltext]
    for {set trajFrame $firstFrame} {$trajFrame <= $lastFrame} \
           {incr  trajFrame} {
      $sel frame $trajFrame
      $protSel frame $trajFrame
        
      # Calculation...
      set d  [llength [lindex [measure contacts 4.0 $sel $protSel] 0]] 

      set trajdat($trajFrame,$i) $d
      puts "$seltext, $trajFrame $i $d"
    }
    $sel delete
    incr i
  }

Set the default value for any unset selection/frame combinations, in case we missed any:
```
    set defaultVal 0
```
Here we write the file header, several lines of formatted comments at the start of the file to identify the file version, number of entries, some data labels, etc.. It is the same for all .tml calculation files, and is provided by the plugin. See the manual for details of the current header format, a current version of Timeline should be backward compatible with all older .tml file formats.
```
::timeline::writeDataFileHeader $outDataFile $molid $dataTitle $numFrames \
     $numSelectionGroups $usesFreeSelection
```

...write out the calculated data ...

    for {set i 0} {$i<$numSelectionGroups} {incr i} {
      puts $outDataFile "freeSelLabel $i $trajdat(freeSelLabel,$i)"
      puts $outDataFile "freeSelString $i $trajdat(freeSelString,$i)"
      for {set trajFrame 0} {$trajFrame < $numFrames} {incr  trajFrame} {
        if {![info exists trajdat($trajFrame,$i)]} {
           set v $defaultVal
        } else {
           set v $trajdat($trajFrame,$i)
        }
        puts $outDataFile "$trajFrame $i $v" 
      }
    }

...then close the data file, and end the procedure.
```
  close $outDataFile
  return
}
```
Now call the calculation procedure for molecule 0.
```
myBatchDataWrite $theFilename $theMolid
```
Generate the .tml file by running the .tcl script in VMD, in either an interactive session with source titin-strand-contacts.tcl or in a non-windowed command line session as in
vmd -dispdev text -e titin-strand-contacts.tcl
or
vmd -dispdev text -eofexit < titin-strand-contacts.tcl > tsc.log .
You can read the resulting tml file into Timeline in two ways: via menu File $\rightarrow$ Load Data File to load a single file or via Data $\rightarrow$ Set Collection Directory when placed in a directory with other .tml files to form a Data Collection for this trajectory.
An example of the output Timeline data file titin-strand-contacts.tml, which is in the example_output directory in the examples directory.
Note how the number of contacts per strand changes as individual strands unravel. Compare this to the secondary structure 2D plot in Figure 8 and to the hydrogen bond-breaking patterns in Figure 10.

Next: Acknowledgements Up: Timeline Tutorial Previous: Trajectory analysis: titin domain Contents

school@ks.uiuc.edu