# 14.2.10. Helper functions — `MDAnalysis.lib.util`

Small helper functions that don’t fit anywhere else.

Changed in version 0.11.0: Moved mathematical functions into lib.mdamath

## 14.2.10.1. Files and directories

MDAnalysis.lib.util.filename(name, ext=None, keep=False)

  Return a new name that has suffix attached; replaces other extensions.

  Parameters:

    - name (str or NamedStream) – filename; extension is replaced unless `keep=True`; name can also be a `NamedStream` (and its `NamedStream.name` will be changed accordingly)

    - ext (None or str) – extension to use in the new filename

    - keep (bool) –

      - `False`: replace existing extension with ext;

      - `True`: keep old extension if one existed

  Changed in version 0.9.0: Also permits `NamedStream` to pass through.

MDAnalysis.lib.util.openany(datasource, mode='rt', reset=True)

  Context manager for `anyopen()`.

  Open the datasource and close it when the context of the `with` statement exits.

  datasource can be a filename or a stream (see `isstream()`). A stream is reset to its start if possible (via `seek()` or `reset()`).

  The advantage of this function is that very different input sources (“streams”) can be used for a “file”, ranging from files on disk (including compressed files) to open file objects to sockets and strings—as long as they have a file-like interface.

  Parameters:

    - datasource (a file or a stream)

    - mode ({'r', 'w'} (optional)) – open in r(ead) or w(rite) mode

    - reset (bool (optional)) – try to read (mode ‘r’) the stream from the start [`True`]

  Examples

  Open a gzipped file and process it line by line:

      with openany("input.pdb.gz") as pdb:
          for line in pdb:
              if line.startswith('ATOM'):
                  print(line)

  Open a URL and read it:

      import urllib2
      with openany(urllib2.urlopen("https://www.mdanalysis.org/")) as html:
          print(html.read())

  See also

  `anyopen()`

MDAnalysis.lib.util.anyopen(datasource, mode='rt', reset=True)

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

  datasource can be a filename or a stream (see `isstream()`). By default, a stream is reset to its start if possible (via `seek()` or `reset()`).

  If possible, the attribute `stream.name` is set to the filename or “<stream>” if no filename could be associated with the datasource.

  Parameters:

    - datasource – a file (from `file` or `open()`) or a stream (e.g. from `urllib2.urlopen()` or `io.StringIO`)

    - mode ({'r', 'w', 'a'} (optional)) – Open in r(ead), w(rite) or a(ppend) mode. This string is directly passed to the file opening handler (either Python’s openfe, bz2, or gzip). More complex modes are supported if the file opening handler supports it.

    - reset (bool (optional)) – try to read (mode ‘r’) the stream from the start

  Return type:

    file-like object

  See also

  `openany()`

    to be used with the `with` statement.

  Changed in version 0.9.0: Only returns the `stream` and tries to set `stream.name = filename` instead of the previous behavior to return a tuple `(stream, filename)`.

  Changed in version 2.0.0: New read handlers support pickle functionality if datasource is a filename. They return a custom picklable file stream in `MDAnalysis.lib.picklable_file_io`.

MDAnalysis.lib.util.greedy_splitext(p)

  Split extension in path p at the left-most separator.

  Extensions are taken to be separated from the filename with the separator `os.extsep` (as used by `os.path.splitext()`).

  Parameters:

    p (str) – path

  Returns:

    (root, extension) – where `root` is the full path and filename with all extensions removed whereas `extension` is the string of all extensions.

  Return type:

    tuple

  Example

      >>> from MDAnalysis.lib.util import greedy_splitext
      >>> greedy_splitext("/home/joe/protein.pdb.bz2")
      ('/home/joe/protein', '.pdb.bz2')

MDAnalysis.lib.util.which(program)

  Determine full path of executable program on `PATH`.

  (Jay at http://stackoverflow.com/questions/377017/test-if-executable-exists-in-python)

  Parameters:

    programe (str) – name of the executable

  Returns:

    path – absolute path to the executable if it can be found, else `None`

  Return type:

    str or None

  Deprecated since version 2.7.0: This method is deprecated and will be removed in version 3.0.0. Please use shutil.which instead.

MDAnalysis.lib.util.realpath(*args)

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

  Expands ‘~’, ‘~user’, and environment variables such as `$HOME`.

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

MDAnalysis.lib.util.get_ext(filename)

  Return the lower-cased extension of filename without a leading dot.

  Parameters:

    filename (str)

  Returns:

    - root (str)

    - ext (str)

MDAnalysis.lib.util.check_compressed_format(root, ext)

  Check if this is a supported gzipped/bzip2ed file format and return UPPERCASE format.

  Parameters:

    - root (str) – path of a file, without extension ext

    - ext (str) – extension (currently only “bz2” and “gz” are recognized as compressed formats)

  Returns:

    format – upper case format extension if the compression can be handled by `openany()`

  Return type:

    str

  See also

  `openany`

    function that is used to open and decompress formats on the fly; only compression formats implemented in `openany()` are recognized

MDAnalysis.lib.util.format_from_filename_extension(filename)

  Guess file format from the file extension.

  Parameters:

    filename (str)

  Returns:

    format

  Return type:

    str

  Raises:

    TypeError – if the file format cannot be determined

MDAnalysis.lib.util.guess_format(filename)

  Return the format of filename

  The current heuristic simply looks at the filename extension and can work around compressed format extensions.

  Parameters:

    filename (str or stream) – path to the file or a stream, in which case `filename.name` is looked at for a hint to the format

  Returns:

    format – format specifier (upper case)

  Return type:

    str

  Raises:

    ValueError – if the heuristics are insufficient to guess a supported format

  Added in version 0.11.0: Moved into lib.util

## 14.2.10.2. Modules and packages

MDAnalysis.lib.util.is_installed(modulename: str)

  Checks if module is installed

  Parameters:

    modulename (str) – name of the module to be tested

  Added in version 2.8.0.

## 14.2.10.3. Streams

Many of the readers are not restricted to just reading files. They can also use gzip-compressed or bzip2-compressed files (through the internal use of `openany()`). It is also possible to provide more general streams as inputs, such as a `io.StringIO` instances (essentially, a memory buffer) by wrapping these instances into a `NamedStream`. This `NamedStream` can then be used in place of an ordinary file name (typically, with a class:~MDAnalysis.core.universe.Universe but it is also possible to write to such a stream using `MDAnalysis.Writer()`).

In the following example, we use a PDB stored as a string `pdb_s`:

    import MDAnalysis
    from MDAnalysis.lib.util import NamedStream
    from io import StringIO

    pdb_s = "TITLE     Lonely Ion\\nATOM      1  NA  NA+     1      81.260  64.982  10.926  1.00  0.00\\n"
    u = MDAnalysis.Universe(NamedStream(StringIO(pdb_s), "ion.pdb"))
    print(u)
    #  <Universe with 1 atoms>
    print(u.atoms.positions)
    # [[ 81.26000214  64.98200226  10.92599964]]

It is important to provide a proper pseudo file name with the correct extension (“.pdb”) to `NamedStream` because the file type recognition uses the extension of the file name to determine the file format or alternatively provide the `format="pdb"` keyword argument to the `Universe`.

The use of streams becomes more interesting when MDAnalysis is used as glue between different analysis packages and when one can arrange things so that intermediate frames (typically in the PDB format) are not written to disk but remain in memory via e.g. `io.StringIO` buffers.

Note

A remote connection created by `urllib2.urlopen()` is not seekable and therefore will often not work as an input. But try it…

class MDAnalysis.lib.util.NamedStream(stream, filename, reset=True, close=False)

  Stream that also provides a (fake) name.

  By wrapping a stream stream in this class, it can be passed to code that uses inspection of the filename to make decisions. For instance. `os.path.split()` will work correctly on a `NamedStream`.

  The class can be used as a context manager.

  `NamedStream` is derived from `io.IOBase` (to indicate that it is a stream). Many operations that normally expect a string will also work with a `NamedStream`; for instance, most of the functions in `os.path` will work with the exception of `os.path.expandvars()` and `os.path.expanduser()`, which will return the `NamedStream` itself instead of a string if no substitutions were made.

  Example

  Wrap a `io.StringIO` instance to write to:

      from io import StringIO
      import os.path
      stream = StringIO()
      f = NamedStream(stream, "output.pdb")
      print(os.path.splitext(f))

  Wrap a `file` instance to read from:

      stream = open("input.pdb")
      f = NamedStream(stream, stream.name)

  Use as a context manager (closes stream automatically when the `with` block is left):

      with NamedStream(open("input.pdb"), "input.pdb") as f:
         # use f
         print f.closed  # --> False
         # ...
      print f.closed     # --> True

  Note

  This class uses its own `__getitem__()` method so if stream implements `stream.__getitem__()` then that will be masked and this class should not be used.

  Warning

  By default, `NamedStream.close()` will not close the stream but instead `reset()` it to the beginning. [1] Provide the `force=True` keyword to `NamedStream.close()` to always close the stream.

  Initialize the `NamedStream` from a stream and give it a name.

  The constructor attempts to rewind the stream to the beginning unless the keyword reset is set to `False`. If rewinding fails, a `MDAnalysis.StreamWarning` is issued.

  Parameters:

    - stream (stream) – an open stream (e.g. `file` or `io.StringIO`)

    - filename (str) – the filename that should be associated with the stream

    - reset (bool (optional)) – start the stream from the beginning (either `reset()` or `seek()`) when the class instance is constructed

    - close (bool (optional)) – close the stream when a `with` block exits or when `close()` is called; note that the default is not to close the stream

  Notes

  By default, this stream will not be closed by `with` and `close()` (see there) unless the close keyword is set to `True`.

  Added in version 0.9.0.

  close(force=False)

    Reset or close the stream.

    If `NamedStream.close_stream` is set to `False` (the default) then this method will not close the stream and only `reset()` it.

    If the force = `True` keyword is provided, the stream will be closed.

    Note

    This `close()` method is non-standard. `del NamedStream` always closes the underlying stream.

  property closed

    `True` if stream is closed.

  fileno()

    Return the underlying file descriptor (an integer) of the stream if it exists.

    An `IOError` is raised if the IO object does not use a file descriptor.

  flush()

    Flush the write buffers of the stream if applicable.

    This does nothing for read-only and non-blocking streams. For file objects one also needs to call `os.fsync()` to write contents to disk.

  readable()

    Return `True` if the stream can be read from.

    If `False`, `read()` will raise `IOError`.

  readline()

    Read and return a line from the stream.

    If size is specified, at most size bytes will be read.

    The line terminator is always b’n’ for binary files; for text files, the newlines argument to open can be used to select the line terminator(s) recognized.

  reset()

    Move to the beginning of the stream

  seek(offset, whence=0)

    Change the stream position to the given byte offset .

    Parameters:

      - offset (int) – offset is interpreted relative to the position indicated by whence.

      - whence ({0, 1, 2} (optional)) –

        Values for whence are:

        > - `io.SEEK_SET` or 0 – start of the stream (the default); offset should be zero or positive

        > - `io.SEEK_CUR` or 1 – current stream position; offset may be negative

        > - `io.SEEK_END` or 2 – end of the stream; offset is usually negative

    Returns:

      the new absolute position in bytes.

    Return type:

      int

  seekable()

    Return `True` if the stream supports random access.

    If `False`, `seek()`, `tell()` and `truncate()` will raise `IOError`.

  tell()

    Return the current stream position.

  truncate(*size)

    Truncate the stream’s size to size.

    Parameters:

      size (int (optional)) – The size defaults to the current position (if no size argument is supplied). The current file position is not changed.

  writable()

    Return `True` if the stream can be written to.

    If `False`, `write()` will raise `IOError`.

MDAnalysis.lib.util.isstream(obj)

  Detect if obj is a stream.

  We consider anything a stream that has the methods

  - `close()`

  and either set of the following

  - `read()`, `readline()`, `readlines()`

  - `write()`, `writeline()`, `writelines()`

  Parameters:

    obj (stream or str)

  Returns:

    `True` if obj is a stream, `False` otherwise

  Return type:

    bool

  See also

  `io`

  Added in version 0.9.0.

## 14.2.10.4. Containers and lists

MDAnalysis.lib.util.iterable(obj)

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

MDAnalysis.lib.util.asiterable(obj)

  Returns obj so that it can be iterated over.

  A string is not detected as and iterable and is wrapped into a `list` with a single element.

  See also

  `iterable`

MDAnalysis.lib.util.hasmethod(obj, m)

  Return `True` if object obj contains the method m.

class MDAnalysis.lib.util.Namespace

  Class to allow storing attributes in new namespace.

## 14.2.10.5. Arrays

MDAnalysis.lib.util.unique_int_1d(values)

  Find the unique elements of a 1D array of integers.

  This function is optimal on sorted arrays.

  Parameters:

    values (numpy.ndarray) – 1D array of dtype `numpy.int64` in which to find the unique values.

  Returns:

    A deduplicated copy of values.

  Return type:

    numpy.ndarray

  Added in version 0.19.0.

MDAnalysis.lib.util.unique_rows(arr, return_index=False)

  Return the unique rows of an array.

  Parameters:

    - arr (numpy.ndarray) – Array of shape `(n1, m)`.

    - return_index (bool, optional) – If `True`, returns indices of array that formed answer (see `numpy.unique()`)

  Returns:

    - unique_rows (numpy.ndarray) – Array of shape `(n2, m)` containing only the unique rows of arr.

    - r_idx (numpy.ndarray (optional)) – Array containing the corresponding row indices (if return_index is `True`).

  Examples

  Remove dupicate rows from an array:

      >>> import numpy as np
      >>> from MDAnalysis.lib.util import unique_rows
      >>> a = np.array([[0, 1], [1, 2], [1, 2], [0, 1], [2, 3]])
      >>> b = unique_rows(a)
      >>> b
      array([[0, 1],
             [1, 2],
             [2, 3]])

  See also

  `numpy.unique`

MDAnalysis.lib.util.blocks_of(a, n, m)

  Extract a view of `(n, m)` blocks along the diagonal of the array a.

  Parameters:

    - a (numpy.ndarray) – Input array, must be C contiguous and at least 2D.

    - n (int) – Size of block in first dimension.

    - m (int) – Size of block in second dimension.

  Returns:

    view – A view of the original array with shape `(nblocks, n, m)`, where `nblocks` is the number of times the miniblocks of shape `(n, m)` fit in the original.

  Return type:

    numpy.ndarray

  Raises:

    ValueError – If the supplied n and m don’t divide a into an integer number of blocks or if a is not C contiguous.

  Examples

      >>> import numpy as np
      >>> from MDAnalysis.lib.util import blocks_of
      >>> arr = np.arange(16).reshape(4, 4)
      >>> view = blocks_of(arr, 2, 2)
      >>> view[:] = 100
      >>> arr
      array([[100, 100,   2,   3],
             [100, 100,   6,   7],
             [  8,   9, 100, 100],
             [ 12,  13, 100, 100]])

  Notes

  n, m must divide a into an identical integer number of blocks. Please note that if the block size is larger than the input array, this number will be zero, resulting in an empty view!

  Uses strides and therefore requires that the array is C contiguous.

  Returns a view, so editing this modifies the original array.

  Added in version 0.12.0.

MDAnalysis.lib.util.group_same_or_consecutive_integers(arr)

  Split an array of integers into a list of same or consecutive sequences.

  Parameters:

    arr (`numpy.ndarray`)

  Returns:

    - list of `numpy.ndarray`

    - Examples

    - >>> import numpy as np

    - >>> arr = np.array([ 2, 3, 4, 7, 8, 9, 10, 11, 15, 16])

    - >>> group_same_or_consecutive_integers(arr)

    - [array([2, 3, 4]), array([ 7, 8, 9, 10, 11]), array([15, 16])]

## 14.2.10.6. File parsing

class MDAnalysis.lib.util.FORTRANReader(fmt)

  FORTRANReader provides a method to parse FORTRAN formatted lines in a file.

  The contents of lines in a file can be parsed according to FORTRAN format edit descriptors (see Fortran Formats for the syntax).

  Only simple one-character specifiers supported here: I F E A X (see `FORTRAN_format_regex`).

  Strings are stripped of leading and trailing white space.

  Set up the reader with the FORTRAN format string.

  The string fmt should look like ‘2I10,2X,A8,2X,A8,3F20.10,2X,A8,2X,A8,F20.10’.

  Parameters:

    fmt (str) – FORTRAN format edit descriptor for a line as described in Fortran Formats

  Example

  Parsing of a standard CRD file:

      atomformat = FORTRANReader('2I10,2X,A8,2X,A8,3F20.10,2X,A8,2X,A8,F20.10')
      for line in open('coordinates.crd'):
          serial,TotRes,resName,name,x,y,z,chainID,resSeq,tempFactor = atomformat.read(line)

  number_of_matches(line)

    Return how many format entries could be populated with legal values.

  parse_FORTRAN_format(edit_descriptor)

    Parse the descriptor.

    Parameters:

      edit_descriptor (str) – FORTRAN format edit descriptor

    Returns:

      dict with totallength (in chars), repeat, length, format, decimals

    Return type:

      dict

    Raises:

      ValueError – The edit_descriptor is not recognized and cannot be parsed

    Note

    Specifiers: L ES EN T TL TR / r S SP SS BN BZ are not supported, and neither are the scientific notation Ew.dEe forms.

  read(line)

    Parse line according to the format string and return list of values.

    Values are converted to Python types according to the format specifier.

    Parameters:

      line (str)

    Returns:

      list of entries with appropriate types

    Return type:

      list

    Raises:

      ValueError – Any of the conversions cannot be made (e.g. space for an int)

    See also

    `FORTRANReader.number_of_matches()`

MDAnalysis.lib.util.FORTRAN_format_regex = '(?P<repeat>\\d+?)(?P<format>[IFEAX])(?P<numfmt>(?P<length>\\d+)(\\.(?P<decimals>\\d+))?)?'

  Regular expresssion (see `re`) to parse a simple FORTRAN edit descriptor. `(?P<repeat>\d?)(?P<format>[IFELAX])(?P<numfmt>(?P<length>\d+)(\.(?P<decimals>\d+))?)?`

## 14.2.10.7. Data manipulation and handling

MDAnalysis.lib.util.fixedwidth_bins(delta, xmin, xmax)

  Return bins of width delta that cover xmin, xmax (or a larger range).

  The bin parameters are computed such that the bin size delta is guaranteed. In order to achieve this, the range [xmin, xmax] can be increased.

  Bins can be calculated for 1D data (then all parameters are simple floats) or nD data (then parameters are supplied as arrays, with each entry correpsonding to one dimension).

  Parameters:

    - delta (float or array_like) – desired spacing of the bins

    - xmin (float or array_like) – lower bound (left boundary of first bin)

    - xmax (float or array_like) – upper bound (right boundary of last bin)

  Returns:

    The dict contains ‘Nbins’, ‘delta’, ‘min’, and ‘max’; these are either floats or arrays, depending on the input.

  Return type:

    dict

  Example

  Use with `numpy.histogram()`:

      B = fixedwidth_bins(delta, xmin, xmax)
      h, e = np.histogram(data, bins=B['Nbins'], range=(B['min'], B['max']))

MDAnalysis.lib.util.get_weights(atoms, weights)

  Check that a weights argument is compatible with atoms.

  Parameters:

    - atoms (AtomGroup or array_like) – The atoms that the weights should be applied to. Typically this is a `AtomGroup` but because only the length is compared, any sequence for which `len(atoms)` is defined is acceptable.

    - weights ({"mass", None} or array_like) – All MDAnalysis functions or classes understand “mass” and will then use `atoms.masses`. `None` indicates equal weights for all atoms. Using an `array_like` assigns a custom weight to each element of atoms.

  Returns:

    weights – If “mass” was selected, `atoms.masses` is returned, otherwise the value of weights (which can be `None`).

  Return type:

    array_like or None

  Raises:

    - TypeError – If weights is not one of the allowed values or if “mass” is selected but `atoms.masses` is not available.

    - ValueError – If weights is not a 1D array with the same length as atoms, then the exception is raised. `TypeError` is also raised if `atoms.masses` is not defined.

MDAnalysis.lib.util.ltruncate_int(value, ndigits)

  Truncate an integer, retaining least significant digits

  Parameters:

    - value (int) – value to truncate

    - ndigits (int) – number of digits to keep

  Returns:

    truncated – only the ndigits least significant digits from value

  Return type:

    int

  Examples

      >>> from MDAnalysis.lib.util import ltruncate_int
      >>> ltruncate_int(123, 2)
      23
      >>> ltruncate_int(1234, 5)
      1234

MDAnalysis.lib.util.flatten_dict(d, parent_key=())

  Flatten a nested dict d into a shallow dict with tuples as keys.

  Parameters:

    d (dict)

  Return type:

    dict

  Note

  Based on https://stackoverflow.com/a/6027615/ by user https://stackoverflow.com/users/1897/imran

  Added in version 0.18.0.

## 14.2.10.8. Strings

MDAnalysis.lib.util.convert_aa_code(x)

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

  Parameters:

    x (str) – 1-letter or 3-letter amino acid code

  Returns:

    3-letter or 1-letter amino acid code

  Return type:

    str

  Raises:

    ValueError – No conversion can be made; the amino acid code is not defined.

  Note

  Data are defined in `amino_acid_codes` and `inverse_aa_codes`.

MDAnalysis.lib.util.parse_residue(residue)

  Process residue string.

  Parameters:

    residue (str) – The residue must contain a 1-letter or 3-letter or 4-letter residue string, a number (the resid) and optionally an atom identifier, which must be separate from the residue with a colon (“:”). White space is allowed in between.

  Returns:

    (3-letter aa string, resid, atomname); known 1-letter aa codes are converted to 3-letter codes

  Return type:

    tuple

  Examples

  - “LYS300:HZ1” –> (“LYS”, 300, “HZ1”)

  - “K300:HZ1” –> (“LYS”, 300, “HZ1”)

  - “K300” –> (“LYS”, 300, None)

  - “4GB300:H6O” –> (“4GB”, 300, “H6O”)

  - “4GB300” –> (“4GB”, 300, None)

MDAnalysis.lib.util.conv_float(s)

  Convert an object s to float if possible.

  Function to be passed into `map()` or a list comprehension. If the argument can be interpreted as a float it is converted, otherwise the original object is passed back.

MDAnalysis.lib.util.atoi(s: str) → int

  Convert the leading number part of a string to an integer.

  Parameters:

    s (str) – The string to convert to an integer.

  Returns:

    number – The first numeric part of the string converted to an integer. If the string does not start with a number, 0 is returned.

  Return type:

    int

  Examples

      >>> from MDAnalysis.lib.util import atoi
      >>> atoi('34f4')
      34
      >>> atoi('foo')
      0

  Added in version 2.8.0.

## 14.2.10.9. Class decorators

MDAnalysis.lib.util.cached(key, universe_validation=False)

  Cache a property within a class.

  Requires the Class to have a cache dict `_cache` and, with universe_validation, a `universe` with a cache dict `_cache`.

  Example

  How to add a cache for a variable to a class by using the @cached decorator:

      class A(object):
          def__init__(self):
              self._cache = dict()

          @property
          @cached('keyname')
          def size(self):
              # This code gets run only if the lookup of keyname fails
              # After this code has been run once, the result is stored in
              # _cache with the key: 'keyname'
              return 10.0

          @property
          @cached('keyname', universe_validation=True)
          def othersize(self):
              # This code gets run only if the lookup
              # id(self) is not in the validation set under
              # self.universe._cache['_valid']['keyname']
              # After this code has been run once, id(self) is added to that
              # set. The validation set can be centrally invalidated at the
              # universe level (say, if a topology change invalidates specific
              # caches).
              return 20.0

  Added in version 0.9.0.

MDAnalysis.lib.util.store_init_arguments(func)

  Decorator to store arguments passed to the init method of a class.

  Arguments are stored as a dictionary in `cls._kwargs`.

  Notes

  - Only does a shallow copy, if the arguments are changed by the class after passing through the decorator this will be reflected in the stored arguments.

  - If not empty, `args` is not unpacked and stored as-is in the dictionary. If no `args` are passed, then no `arg` entry will be stored in the dictionary.

  Added in version 2.2.0.

## 14.2.10.10. Function decorators

MDAnalysis.lib.util.static_variables(**kwargs)

  Decorator equipping functions or methods with static variables.

  Static variables are declared and initialized by supplying keyword arguments and initial values to the decorator.

  Example

      >>> from MDAnalysis.lib.util import static_variables
      >>> @static_variables(msg='foo calls', calls=0)
      ... def foo():
      ...     foo.calls += 1
      ...     print("{}: {}".format(foo.msg, foo.calls))
      ...
      >>> foo()
      foo calls: 1
      >>> foo()
      foo calls: 2

  Note

  Based on https://stackoverflow.com/a/279586 by Claudiu

  Added in version 0.19.0.

MDAnalysis.lib.util.warn_if_not_unique(groupmethod)

  Decorator triggering a `DuplicateWarning` if the underlying group is not unique.

  Assures that during execution of the decorated method only the first of potentially multiple warnings concerning the uniqueness of groups is shown.

  Raises:

    DuplicateWarning – If the `AtomGroup`, `ResidueGroup`, or `SegmentGroup` of which the decorated method is a member contains duplicates.

  Added in version 0.19.0.

MDAnalysis.lib.util.check_coords(*coord_names, **options)

  Decorator for automated coordinate array checking.

  This decorator is intended for use especially in `MDAnalysis.lib.distances`. It takes an arbitrary number of positional arguments which must correspond to names of positional arguments of the decorated function. It then checks if the corresponding values are valid coordinate arrays or an `AtomGroup`. If the input is an array and all these arrays are single coordinates (i.e., their shape is `(3,)`), the decorated function can optionally return a single coordinate (or angle) instead of an array of coordinates (or angles). This can be used to enable computations of single observables using functions originally designed to accept only 2-d coordinate arrays.

  If the input is an `AtomGroup` it is converted into its corresponding position array via a call to AtomGroup.positions.

  The checks performed on each individual coordinate array are:

  - Check that coordinate arrays are of type `numpy.ndarray`.

  - Check that coordinate arrays have a shape of `(n, 3)` (or `(3,)` if single coordinates are allowed; see keyword argument allow_single).

  - Automatic dtype conversion to `numpy.float32`.

  - Optional replacement by a copy; see keyword argument enforce_copy .

  - If coordinate arrays aren’t C-contiguous, they will be automatically replaced by a C-contiguous copy.

  - Optional check for equal length of all coordinate arrays; see optional keyword argument check_lengths_match.

  Parameters:

    - *coord_names (tuple) – Arbitrary number of strings corresponding to names of positional arguments of the decorated function.

    - **options (dict, optional) –

      - enforce_copy (`bool`, optional) – Enforce working on a copy of the coordinate arrays. This is useful to ensure that the input arrays are left unchanged. Default: `True`

      - enforce_dtype (`bool`, optional) – Enforce a conversion to float32. Default: `True`

      - allow_single (`bool`, optional) – Allow the input coordinate array to be a single coordinate with shape `(3,)`.

      - convert_single (`bool`, optional) – If `True`, single coordinate arrays will be converted to have a shape of `(1, 3)`. Only has an effect if allow_single is `True`. Default: `True`

      - reduce_result_if_single (`bool`, optional) – If `True` and all input coordinates are single, a decorated function `func` will return `func()[0]` instead of `func()`. Only has an effect if allow_single is `True`. Default: `True`

      - check_lengths_match (`bool`, optional) – If `True`, a `ValueError` is raised if not all coordinate arrays contain the same number of coordinates. Default: `True`

      - allow_atomgroup (`bool`, optional) – If `False`, a `TypeError` is raised if an `AtomGroup` is supplied Default: `False`

  Raises:

    - ValueError – If the decorator is used without positional arguments (for development purposes only). If any of the positional arguments supplied to the decorator doesn’t correspond to a name of any of the decorated function’s positional arguments. If any of the coordinate arrays has a wrong shape.

    - TypeError – If any of the coordinate arrays is not a `numpy.ndarray` or an `AtomGroup`. If the dtype of any of the coordinate arrays is not convertible to `numpy.float32`.

  Example

      >>> import numpy as np
      >>> import MDAnalysis as mda
      >>> from MDAnalysis.tests.datafiles import PSF, DCD
      >>> from MDAnalysis.lib.util import check_coords
      >>> @check_coords('coords1', 'coords2', allow_atomgroup=True)
      ... def coordsum(coords1, coords2):
      ...     assert coords1.dtype == np.float32
      ...     assert coords2.flags['C_CONTIGUOUS']
      ...     return coords1 + coords2
      ...
      >>> # automatic dtype conversion:
      >>> coordsum(np.zeros(3, dtype=np.int64), np.ones(3))
      array([1., 1., 1.], dtype=float32)
      >>>
      >>> # automatic handling of non-contiguous arrays:
      >>> coordsum(np.zeros(3), np.ones(6)[::2])
      array([1., 1., 1.], dtype=float32)
      >>>
      >>> # automatic handling of AtomGroups
      >>> u = mda.Universe(PSF, DCD)
      >>> try:
      ...     coordsum(u.atoms, u.select_atoms("index 1 to 10"))
      ... except ValueError as err:
      ...     err
      ValueError('coordsum(): coords1, coords2 must contain the same number of coordinates, got [3341, 10].')
      >>>
      >>> # automatic shape checking:
      >>> try:
      ...     coordsum(np.zeros(3), np.ones(6))
      ... except ValueError as err:
      ...     err
      ValueError('coordsum(): coords2.shape must be (3,) or (n, 3), got (6,)')

  Added in version 0.19.0.

  Changed in version 2.3.0: Can now accept an `AtomGroup` as input, and added option allow_atomgroup with default False to retain old behaviour

MDAnalysis.lib.util.check_atomgroup_not_empty(groupmethod)

  Decorator triggering a `ValueError` if the underlying group is empty.

  Avoids downstream errors in computing properties of empty atomgroups.

  Raises:

    ValueError – If the input `AtomGroup`, of a decorated method is empty.

  Added in version 2.4.0.

## 14.2.10.11. Code management

MDAnalysis.lib.util.deprecate(*args, **kwargs)

  Issues a DeprecationWarning, adds warning to old_name’s docstring, rebinds `old_name.__name__` and returns the new function object.

  This function may also be used as a decorator.

  It adds a restructured text `.. deprecated:: release` block with the sphinx deprecated role to the end of the docs. The message is added under the deprecation block and contains the release in which the function was deprecated.

  Parameters:

    - func (function) – The function to be deprecated.

    - old_name (str, optional) – The name of the function to be deprecated. Default is None, in which case the name of func is used.

    - new_name (str, optional) – The new name for the function. Default is None, in which case the deprecation message is that old_name is deprecated. If given, the deprecation message is that old_name is deprecated and new_name should be used instead.

    - release (str) – Release in which the function was deprecated. This is given as a keyword argument for technical reasons but is required; a `ValueError` is raised if it is missing.

    - remove (str, optional) – Release for which removal of the feature is planned.

    - message (str, optional) – Additional explanation of the deprecation. Displayed in the docstring after the warning.

  Returns:

    old_func – The deprecated function.

  Return type:

    function

  Examples

  When `deprecate()` is used as a function as in the following example,

      oldfunc = deprecate(func, release="0.19.0", remove="1.0",
                          message="Do it yourself instead.")

  then `oldfunc` will return a value after printing `DeprecationWarning`; `func` is still available as it was before.

  When used as a decorator, `func` will be changed and issue the warning and contain the deprecation note in the do string.

      @deprecate(release="0.19.0", remove="1.0",
                 message="Do it yourself instead.")
      def func():
          \"\"\"Just pass\"\"\"
          pass

  The resulting doc string (`help(func)`) will look like:

      `func` is deprecated!

      Just pass.

      .. deprecated:: 0.19.0
         Do it yourself instead.
         `func` will be removed in 1.0.

  (It is possible but confusing to change the name of `func` with the decorator so it is not recommended to use the new_func keyword argument with the decorator.)

  Added in version 0.19.0.

class MDAnalysis.lib.util._Deprecate(old_name=None, new_name=None, release=None, remove=None, message=None)

  Decorator class to deprecate old functions.

  Refer to deprecate for details.

  See also

  `deprecate`

  Added in version 0.19.0.

MDAnalysis.lib.util.dedent_docstring(text)

  Dedent typical python doc string.

  Parameters:

    text (str) – string, typically something like `func.__doc__`.

  Returns:

    string with the leading common whitespace removed from each line

  Return type:

    str

  See also

  `textwrap.dedent`

  Added in version 0.19.0.

## 14.2.10.12. Data format checks

MDAnalysis.lib.util.check_box(box)

  Take a box input and deduce what type of system it represents based on the shape of the array and whether all angles are 90 degrees.

  Parameters:

    box (array_like) – The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by `MDAnalysis.coordinates.timestep.Timestep.dimensions`: `[lx, ly, lz, alpha, beta, gamma]`.

  Returns:

    - boxtype ({`'ortho'`, `'tri_vecs'`}) – String indicating the box type (orthogonal or triclinic).

    - checked_box (numpy.ndarray) –

      Array of dtype `numpy.float32` containing box information:

        - If boxtype is `'ortho'`, cecked_box will have the shape `(3,)` containing the x-, y-, and z-dimensions of the orthogonal box.

        - If boxtype is `'tri_vecs'`, cecked_box will have the shape `(3, 3)` containing the triclinic box vectors in a lower triangular matrix as returned by `triclinic_vectors()`.

  Raises:

    ValueError – If box is not of the form `[lx, ly, lz, alpha, beta, gamma]` or contains data that is not convertible to `numpy.float32`.

  See also

  `MDAnalysis.lib.mdamath.triclinic_vectors`

Footnotes

[1]

The reason why `NamedStream.close()` does not close a stream by default (but just rewinds it to the beginning) is so that one can use the class `NamedStream` as a drop-in replacement for file names, which are often re-opened (e.g. when the same file is used as a topology and coordinate file or when repeatedly iterating through a trajectory in some implementations). The `close=True` keyword can be supplied in order to make `NamedStream.close()` actually close the underlying stream and `NamedStream.close(force=True)` will also close it.