Analysis core modules — GromacsWrapper 0.6.1 documentation

# 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.