Annotated Trajectories

Authors: David W.H. Swenson

This module provides a data structure that adds annotations to frames of a trajectory, intended to label those frames as being, for example, in a given metastable state. It also provides some tools to analysis whether a proposed state definition is compatible with those annotations.

Purpose of Module

When dealing with biomolecular systems, one of the common challenges is to define the (meta)stable states. The existence of metastable states is easily determined by visually inspecting the trajectory. However, identifying geometric criteria to characterize the states remains difficult.

This module provides a data structure that allows the user to easily annotate a trajectory with the visually identified states, and to compare those annotations to proposed state definitions. It also includes tools to visualize where the proposed state definition matches the annotations.

This implementation includes:

  • An Annotation class, which is essentially a structure to connect the state label and a range of frames (marked with their beginning and ending frames) that the user identifies as in the given state.
  • Another data structure, ValidationResults, which contains the correctly identified frames, as well as false positives and false negatives, for a given proposed state definition.
  • The AnnotatedTrajectory class, which associates the annotations with an OpenPathSampling Trajectory object and performs the analysis to compare the proposed states to those annotations.
  • A method plot_annotated, which plots the annotations and the proposed state definition in order to visually inspect the quality of the proposed state.

Background Information

This module builds on OpenPathSampling, a Python package for path sampling simulations. To learn more about OpenPathSampling, you might be interested in reading:


Tests in OpenPathSampling use the nose package.

The tests for this module can be run by downloading its source code, installing its requirements (namely, OpenPathSampling), and running the command nosetests from the root directory of the repository.

Once the requirements are installed, a standard installation of this package can be done with python install.


The features in this code, including the ability to save the annotations associated with a trajectory, are highlighted in a Jupyter notebook in its examples/ directory. It can be viewed here.

Source Code

This module is for the 0.1 release of annotated_trajectories. The source code for this module can be found in: