Analysis core modules

The core modules contain the important classes Simulation and Plugin. An analysis class is derived from gromacs.analysis.Simulation and additional plugins from gromacs.analysis.plugins are added to the instance; these plugin classes must be derived from Plugin.

gromacs.analysis – Analysis Package Overview

The gromacs.analysis package is a framework for analyzing Gromacs MD trajectories. The basic object is the Simulation class. For a particular project one has to derive a class from Simulation and add analysis plugin classes (from gromacs.analysis.plugins) for specific analysis tasks. This is slightly cumbersome but flexible.

New analysis plugins should follow the API sketched out in gromacs.analysis.core; see an example for use there.

Right now the number of plugins is limited and simply demonstrates how to use the framework in principle. If you would like to contribute your own plugins feel free to send then to the package author. If they have been written according to the API they will be added to the distribution and of course you will be acknowledged in the list of plugin authors in gromacs.analysis.plugins.

Simulation class

The Simulation class is central for doing analysis. The user can derive a custom analysis class that pre-defines values for plugins as seen in the Example.

class gromacs.analysis.Simulation(**kwargs)

Class that represents one simulation.

Analysis capabilities are added via plugins.

  1. Set the active plugin with the Simulation.set_plugin() method.
  2. Analyze the trajectory with the active plugin by calling the Simulation.run() method.
  3. Analyze the output from run() with Simulation.analyze(); results are stored in the plugin’s results dictionary.
  4. Plot results with Simulation.plot().

Set up a Simulation object.

Keywords:
sim

Any object that contains the attributes tpr, xtc, and optionally ndx (e.g. gromacs.cbook.Transformer). The individual keywords such as xtc override the values in sim.

tpr

Gromacs tpr file (required)

xtc

Gromacs trajectory, can also be a trr (required)

edr

Gromacs energy file (only required for some plugins)

ndx

Gromacs index file

absolute

True: Turn file names into absolute paths (typically required for most plugins); False keep a they are [True]

strict

True: missing required file keyword raises a TypeError and missing the file itself raises a IOError. False: missing required files only give a warning. [True]

analysisdir

directory under which derived data are stored; defaults to the directory containing the tpr [None]

plugins : list

plugin instances or tuples (plugin class, kwarg dict) or tuples (plugin_class_name, kwarg dict) to be used; more can be added later with Simulation.add_plugin().
add_plugin(plugin, **kwargs)

Add a plugin to the registry.

  • If plugin is a Plugin instance then the instance is directly registered and any keyword arguments are ignored.
  • If plugin is a Plugin class object or a string that can be found in gromacs.analysis.plugins then first an instance is created with the given keyword arguments and then registered.
Arguments:
plugin : class or string, or instance

If the parameter is a class then it should have been derived from Plugin. If it is a string then it is taken as a plugin name in gromacs.analysis.plugins and the corresponding class is added. In both cases any parameters for initizlization should be provided.

If plugin is already a Plugin instance then the kwargs will be ignored.

kwargs

The kwargs are specific for the plugin and should be described in its documentation.
analyze(plugin_name=None, **kwargs)

Run analysis for the plugin.

plot(plugin_name=None, figure=False, **kwargs)

Plot all data for the selected plugin:

plot(plugin_name, **kwargs)
Arguments:
plugin_name

name of the plugin to plot data from

figure
  • True: plot to file with default name.
  • string: use this filename (+extension for format)
  • False: only display
kwargs

arguments for plugin plot function (in many cases provided by gromacs.formats.XVG.plot() and ultimately by pylab.plot())
run(plugin_name=None, **kwargs)

Generate data files as prerequisite to analysis.

set_plugin(plugin_name)

Set the plugin that should be used by default.

If no plugin_name is supplied to run(), analyze() etc. then this will be used.

Example

Here we analyze a protein, which has three Cysteines (C96, C243, C372). We will use the plugins.CysAccessibility and the plugins.Distances plugin (arguments for Distances omitted):

from gromacs.analysis import Simulation
from gromacs.analysis.plugins import CysAccessibility, Distances

S = Simulation(tpr=..., xtc=..., analysisdir=...,
               plugins=[('CysAccessibility', {'cysteines': [96, 243, 372]}),
                        Distances(...),
                        ])
S.set_plugin('CysAccessibility')          # do CysAccessibility analysis
S.run()                                   # analyze trajectory and write files
S.analyze()                               # analyze output files
S.plot(figure=True)                       # plot and save the figure

Note

Absolute paths for the files and analysisdir are a good idea because many plugins change directory freely.

The plugins can be supplied when the Simulation object is constructed, or they can be later added, e.g.

S.add_plugin(Distances(name='Dist2', ...))

This second Distances analysis would be available with

S.set_plugin('Dist2')

Other plugins might require no or a very different initialization. See the plugin documentation for what is required.

analysis.core – Core classes for analysis of Gromacs trajectories

This documentation is mostly of interest to programmers who want to write analysis plugins.

Programming API for plugins

Additional analysis capabilities are added to a gromacs.analysis.Simulation class with plugin classes. For an example see gromacs.analysis.plugins.

API description

Analysis capabilities can be added with plugins to the simulation class. Each plugin is registered with the simulation class and provides at a minimum run(), analyze(), and plot() methods.

A plugin consists of a subclass of Plugin and an associated Worker instance. The former is responsible for administrative tasks and documentation, the latter implements the analysis code.

A plugin class must be derived from Plugin and typically bears the name that is used to access it. A plugin instance must be registered with a Simulation object. This can be done implicitly by passing the Simulation instance in the simulation keyword argument to the constructor or by explicitly calling the Plugin.register() method with the simulation instance. Alternatively, one can also register a plugin via the Simulation.add_plugin() method.

Registering the plugin means that the actual worker class is added to the Simulation.plugins dictionary.

A plugin must eventually obtain a pointer to the Simulation class in order to be able to access simulation-global parameters such as top directories or input files.

See analysis.plugins.CysAccessibility and analysis.plugins._CysAccessibility in analysis/plugins/CysAccessibility.py as examples.

API requirements

  • Each plugin is contained in a separate module in the gromacs.analysis.plugins package. The name of the module must be the name of the plugin class in all lower case.

  • The plugin name is registered in gromacs.analysis.plugins.__plugins__. (Together with the file naming convention this allows for automatic and consistent loading.)

  • The plugin itself is derived from Plugin; the only changes are the doc strings and setting the Plugin.worker_class class attribute to a Worker class.

  • The corresponding worker class is derived from Worker and must implement

    • Worker.__init__() which can only use keyword arguments to initialize the plugin. It must ensure that init methods of super classes are also called. See the existing plugins for details.
    • Worker.run() which typically generates the data by analyzing a trajectory, possibly multiple times. It should store results in files.
    • Worker.analyze() analyzes the data generated by Worker.run().
    • Worker.plot() plots the analyzed data.
    • Worker._register_hook() (see below)

  • The worker class can access parameters of the simulation via the Worker.simulation attribute that is automatically set when the plugin registers itself with Simulations. However, the plugin should not rely on simulation being present during initialization (__init__) because registration of the plugin might occur after init.

    This also means that one cannot use the directory methods such as Worker.plugindir() because they depend on Simulation.topdir() and Simulation.plugindir().

    Any initialization that requires access to the Simulation instance should be moved into the Worker._register_hook() method. It is called when the plugin is actually being registered. Note that the hook must also call the hook of the super class before setting any values. The hook should pop any arguments that it requires and ignore everything else.

  • Parameters of the plugin are stored in Worker.parameters (either as attributes or as key/value pairs, see the container class gromacs.utilities.AttributeDict).

  • Results are stored in Worker.results (also a gromacs.utilities.AttributeDict).

Classes

class gromacs.analysis.core.Simulation(**kwargs)

Bases: object

Class that represents one simulation.

Analysis capabilities are added via plugins.

  1. Set the active plugin with the Simulation.set_plugin() method.
  2. Analyze the trajectory with the active plugin by calling the Simulation.run() method.
  3. Analyze the output from run() with Simulation.analyze(); results are stored in the plugin’s results dictionary.
  4. Plot results with Simulation.plot().

Set up a Simulation object.

Keywords:
sim

Any object that contains the attributes tpr, xtc, and optionally ndx (e.g. gromacs.cbook.Transformer). The individual keywords such as xtc override the values in sim.

tpr

Gromacs tpr file (required)

xtc

Gromacs trajectory, can also be a trr (required)

edr

Gromacs energy file (only required for some plugins)

ndx

Gromacs index file

absolute

True: Turn file names into absolute paths (typically required for most plugins); False keep a they are [True]

strict

True: missing required file keyword raises a TypeError and missing the file itself raises a IOError. False: missing required files only give a warning. [True]

analysisdir

directory under which derived data are stored; defaults to the directory containing the tpr [None]

plugins : list

plugin instances or tuples (plugin class, kwarg dict) or tuples (plugin_class_name, kwarg dict) to be used; more can be added later with Simulation.add_plugin().
_apply_all(func, **kwargs)

Execute func for all plugins.

add_plugin(plugin, **kwargs)

Add a plugin to the registry.

  • If plugin is a Plugin instance then the instance is directly registered and any keyword arguments are ignored.
  • If plugin is a Plugin class object or a string that can be found in gromacs.analysis.plugins then first an instance is created with the given keyword arguments and then registered.
Arguments:
plugin : class or string, or instance

If the parameter is a class then it should have been derived from Plugin. If it is a string then it is taken as a plugin name in gromacs.analysis.plugins and the corresponding class is added. In both cases any parameters for initizlization should be provided.

If plugin is already a Plugin instance then the kwargs will be ignored.

kwargs

The kwargs are specific for the plugin and should be described in its documentation.
analyze(plugin_name=None, **kwargs)

Run analysis for the plugin.

analyze_all(**kwargs)

Execute the analyze() method for all registered plugins.

check_file(filetype, path, resolve='exception')

Raise ValueError if path does not exist. Uses filetype in message.

Arguments:
filetype

type of file, for error message

path

path to file

resolve
“ignore”

always return True

“indicate”

return True if it exists, False otherwise

“warn”

indicate and issue a UserWarning

“exception”

raise IOError if it does not exist [default]
check_plugin_name(plugin_name)

Raises a exc:ValueError if plugin_name is not registered.

current_plugin

The currently active plugin (set with Simulation.set_plugin()).

get_plugin(plugin_name=None)

Return valid plugin or the default for *plugin_name*=``None``.

has_plugin(plugin_name)

Returns True if plugin_name is registered.

plot(plugin_name=None, figure=False, **kwargs)

Plot all data for the selected plugin:

plot(plugin_name, **kwargs)
Arguments:
plugin_name

name of the plugin to plot data from

figure
  • True: plot to file with default name.
  • string: use this filename (+extension for format)
  • False: only display
kwargs

arguments for plugin plot function (in many cases provided by gromacs.formats.XVG.plot() and ultimately by pylab.plot())
plugindir(plugin_name, *args)

Directory where the plugin creates and looks for files.

run(plugin_name=None, **kwargs)

Generate data files as prerequisite to analysis.

run_all(**kwargs)

Execute the run() method for all registered plugins.

set_plugin(plugin_name)

Set the plugin that should be used by default.

If no plugin_name is supplied to run(), analyze() etc. then this will be used.

topdir(*args)

Returns a path under self.analysis_dir, which is guaranteed to exist.

Note

Parent dirs are created if necessary.

class gromacs.analysis.core.Plugin(name=None, simulation=None, **kwargs)

Plugin class that can be added to a Simulation instance.

All analysis plugins must be derived from this base class.

If a Simulation instance is provided to the constructore in the simulation keyword argument then the plugin instantiates and registers a worker class in Simulation.plugins and adds the Simulation instance to the worker.

Otherwise the Plugin.register() method must be called explicitly with a Simulation instance.

The plugin class handles the administrative tasks of interfacing with the Simulation class. The worker runs the analysis.

Note

If multiple Plugin instances are added to a Simulation one must set the name keyword argument to distinguish the instances. Plugins are referred to by this name in all further interactions with the user. There are no sanity checks: A newer plugin with the same name simply replaces the previous one.

Registers the plugin with the simulation class.

Specific keyword arguments are listed below, all other kwargs are passed through.

Arguments:
name : string

Name of the plugin. Should differ for different instances. Defaults to the class name.

simulation : Simulation instance

The Simulation instance that owns this plugin instance. Can be None but then the register() method has to be called manually with a simulation instance later.

kwargs

All other keyword arguments are passed to the Worker.
plugin_name

Name of the plugin; this must be a unique identifier across all plugins of a Simulation object. It should also be human understandable and must be a valid python identifier as it is used as a dict key.

simulation

The Simulation instance who owns the plugin. Can be None until a successful call to register().

worker

The Worker instance of the plugin.

register(simulation)

Register the plugin with the Simulation instance.

This method also ensures that the worker class knows the simulation instance. This is typically required for its run(), analyze(), and plot() methods.

worker_class = None

actual plugin gromacs.analysis.core.Worker class (name with leading underscore)

class gromacs.analysis.core.Worker(**kwargs)

Bases: gromacs.utilities.FileUtils

Base class for a plugin worker.

Set up Worker class.

Keywords:
plugin : instance

The Plugin instance that owns this worker. Must be supplied.

simulation

A :class:Simulation` object, required for registration, but can be supplied later.

kwargs

All other keyword arguments are passed to the super class.
_register_hook(**kwargs)

Things to initialize once the Simulation instance is known.

The hook is called from Plugin.register().

Note

Subclasses should do all their Simulation - dependent initialization in their own _register_hook() which must call the super class hook via the super mechanism.

plugindir(*args)

Returns a directory located under the plugin top directory.

savefig(filename=None, ext='png')

Save the current figure under the default name or filename.

Uses the supplied format and extension ext.

topdir(*args)

Returns a directory located under the simulation top directory.