gromacs.utilities – Helper functions and classes — GromacsWrapper 0.5.0-dev documentation

# `gromacs.utilities` – Helper functions and classes

The module defines some convenience functions and classes that are used in other modules; they do not make use of `gromacs.tools` or `gromacs.cbook` and can be safely imported at any time.

## Classes

`FileUtils` provides functions related to filename handling. It can be used as a base or mixin class. The `gromacs.analysis.Simulation` class is derived from it.

class `gromacs.utilities.` `FileUtils`

  Mixin class to provide additional file-related capabilities.

  `check_file_exists`(filename, resolve='exception', force=None)

    If a file exists then continue with the action specified in `resolve`.

    `resolve` must be one of

    “ignore”
      always return `False`
    “indicate”
      return `True` if it exists
    “warn”
      indicate and issue a `UserWarning`
    “exception”
      raise `IOError` if it exists

    Alternatively, set force for the following behaviour (which ignores resolve):

    `True`
      same as resolve = “ignore” (will allow overwriting of files)
    `False`
      same as resolve = “exception” (will prevent overwriting of files)
    `None`
      ignored, do whatever resolve says
  `default_extension` = None

    Default extension for files read/written by this class.

  `filename`(filename=None, ext=None, set_default=False, use_my_ext=False)

    Supply a file name for the class object.

    Typical uses:

        fn = filename()             ---> <default_filename>
        fn = filename('name.ext')   ---> 'name'
        fn = filename(ext='pickle') ---> <default_filename>'.pickle'
        fn = filename('name.inp','pdf') --> 'name.pdf'
        fn = filename('foo.pdf',ext='png',use_my_ext=True) --> 'foo.pdf'

    The returned filename is stripped of the extension (`use_my_ext=False`) and if provided, another extension is appended. Chooses a default if no filename is given.

    Raises a `ValueError` exception if no default file name is known.

    If `set_default=True` then the default filename is also set.

    `use_my_ext=True` lets the suffix of a provided filename take priority over a default `ext` tension.

    Changed in version 0.3.1: An empty string as ext = “” will suppress appending an extension.

  `infix_filename`(name, default, infix, ext=None)

    Unless name is provided, insert infix before the extension ext of default.

class `gromacs.utilities.` `AttributeDict`

  A dictionary with pythonic access to keys as attributes — useful for interactive work.

class `gromacs.utilities.` `Timedelta`

  Extension of `datetime.timedelta`.

  Provides attributes ddays, dhours, dminutes, dseconds to measure the delta in normal time units.

  ashours gives the total time in fractional hours.

## Functions

Some additional convenience functions that deal with files and directories:

`gromacs.utilities.` `openany`(directory[, mode='r'])

  Context manager to open a compressed (bzip2, gzip) or plain file (uses `anyopen()`).

`gromacs.utilities.` `anyopen`(datasource, mode='r', **kwargs)

  Open datasource (gzipped, bzipped, uncompressed) and return a stream.

  Arguments: | datasource a stream or a filename mode `'r'` opens for reading, `'w'` for writing [‘r’] kwargs additional keyword arguments that are passed through to the actual handler; if these are not appropriate then an exception will be raised by the handler

`gromacs.utilities.` `realpath`(*args)

  Join all args and return the real path, rooted at /.

  Expands `~` and environment variables such as `$HOME`.

  Returns `None` if any of the args is none.

`gromacs.utilities.` `in_dir`(directory[, create=True])

  Context manager to execute a code block in a directory.

  - The directory is created if it does not exist (unless create = `False` is set)
  - At the end or after an exception code always returns to the directory that was the current directory before entering the block.

`gromacs.utilities.` `find_first`(filename, suffices=None)

  Find first filename with a suffix from suffices.

  Arguments: | filename base filename; this file name is checked first suffices list of suffices that are tried in turn on the root of filename; can contain the ext separator (`os.path.extsep`) or not
  Returns: | The first match or `None`.

`gromacs.utilities.` `withextsep`(extensions)

  Return list in which each element is guaranteed to start with `os.path.extsep`.

Functions that improve list processing and which do not treat strings as lists:

`gromacs.utilities.` `iterable`(obj)

  Returns `True` if obj can be iterated over and is not a string.

`gromacs.utilities.` `asiterable`(obj)

  Returns obj so that it can be iterated over; a string is not treated as iterable

`gromacs.utilities.` `firstof`(obj)

  Returns the first entry of a sequence or the obj.

  Treats strings as single objects.

Functions that help handling Gromacs files:

`gromacs.utilities.` `unlink_f`(path)

  Unlink path but do not complain if file does not exist.

`gromacs.utilities.` `unlink_gmx`(*args)

  Unlink (remove) Gromacs file(s) and all corresponding backups.

`gromacs.utilities.` `unlink_gmx_backups`(*args)

  Unlink (rm) all backup files corresponding to the listed files.

`gromacs.utilities.` `number_pdbs`(*args, **kwargs)

  Rename pdbs x1.pdb ... x345.pdb –> x0001.pdb ... x0345.pdb

  Arguments: | args: filenames or glob patterns (such as “pdb/md*.pdb”) format: format string including keyword num [“%(num)04d”]

Functions that make working with matplotlib easier:

`gromacs.utilities.` `activate_subplot`(numPlot)

  Make subplot numPlot active on the canvas.

  Use this if a simple `subplot(numRows, numCols, numPlot)` overwrites the subplot instead of activating it.

`gromacs.utilities.` `remove_legend`(ax=None)

  Remove legend for axes or gca.

  See http://osdir.com/ml/python.matplotlib.general/2005-07/msg00285.html

Miscellaneous functions:

`gromacs.utilities.` `convert_aa_code`(x)

  Converts between 3-letter and 1-letter amino acid codes.

`gromacs.utilities.` `autoconvert`(s)

  Convert input to a numerical type if possible.

  1. A non-string object is returned as it is
  2. Try conversion to int, float, str.

## Data

`gromacs.utilities.` `amino_acid_codes` = {'A': 'ALA', 'C': 'CYS', 'E': 'GLU', 'D': 'ASP', 'G': 'GLY', 'F': 'PHE', 'I': 'ILE', 'H': 'HIS', 'K': 'LYS', 'M': 'MET', 'L': 'LEU', 'N': 'ASN', 'Q': 'GLN', 'P': 'PRO', 'S': 'SER', 'R': 'ARG', 'T': 'THR', 'W': 'TRP', 'V': 'VAL', 'Y': 'TYR'}

  translation table for 1-letter codes –> 3-letter codes .. Note: This does not work for HISB and non-default charge state aa!