Table Of Contents

Previous topic

7.8. Constants and unit conversion — MDAnalysis.core.units

Next topic

7.10. Setting up logging — MDAnalysis.core.log

This Page

7.9. Helper functions — MDAnalysis.core.util

Small helper functions that don’t fit anywhere else.

7.9.1. Files and directories

MDAnalysis.core.util.filename(name, ext=None, keep=False)[source]

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

Arguments:
name

filename; extension is replaced unless keep=True

ext

extension

keep

False: replace existing extension; True: keep if exists

MDAnalysis.core.util.openany(directory[, mode='r'])[source]

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

MDAnalysis.core.util.anyopen(datasource, mode='r')[source]

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

Arguments:
datasource

a file or a stream

mode

‘r’ or ‘w’

MDAnalysis.core.util.greedy_splitext(p)[source]

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

MDAnalysis.core.util.which(program)[source]

Determine full path of executable program on PATH.

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

MDAnalysis.core.util.realpath(*args)[source]

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

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

Returns None if any of the args is None.

7.9.2. Containers and lists

MDAnalysis.core.util.iterable(obj)[source]

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

MDAnalysis.core.util.asiterable(obj)[source]

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

7.9.3. File parsing

class MDAnalysis.core.util.FORTRANReader(fmt)[source]

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

Usage:

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)

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

number_of_matches(line)[source]

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

parse_FORTRAN_format(edit_descriptor)[source]

Parse the descriptor.

parse_FORTRAN_format(edit_descriptor) –> dict
Returns:dict with totallength (in chars), repeat, length, format, decimals
Raises:ValueError if 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)[source]

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

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

Returns:list of entries with appropriate types
Raises:ValueError if any of the conversions cannot be made (e.g. space for an int)
MDAnalysis.core.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+))?)?

7.9.4. Data manipulation and handling

MDAnalysis.core.util.fixedwidth_bins(delta, xmin, xmax)[source]

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

dict = fixedwidth_bins(delta,xmin,xmax)

The dict contains ‘Nbins’, ‘delta’, ‘min’, and ‘max’.

7.9.5. Strings

MDAnalysis.core.util.convert_aa_code(x)[source]

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

See also

Data are defined in amino_acid_codes and inverse_aa_codes.

MDAnalysis.core.util.parse_residue(residue)[source]

Process residue string.

Examples:
  • “LYS300:HZ1” –> (“LYS”, 300, “HZ1”)
  • “K300:HZ1” –> (“LYS”, 300, “HZ1”)
  • “K300” –> (“LYS”, 300, None)
  • “4GB300:H6O” –> (“4GB”, 300, “H6O”)
  • “4GB300” –> (“4GB”, 300, None)
Argument: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
MDAnalysis.core.util.conv_float(s)[source]

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.

7.9.6. Mathematics and Geometry

MDAnalysis.core.util.normal(vec1, vec2)[source]

Returns the unit vector normal to two vectors.

\[\hat{\mathbf{n}} = \frac{\mathbf{v}_1 \times \mathbf{v}_2}{|\mathbf{v}_1 \times \mathbf{v}_2|}\]

If the two vectors are collinear, the vector \(\mathbf{0}\) is returned.

MDAnalysis.core.util.norm(v)[source]

Returns the length of a vector, sqrt(v.v).

\[v = \sqrt{\mathbf{v}\cdot\mathbf{v}}\]

Faster than numpy.linalg.norm() because no frills.

MDAnalysis.core.util.angle(a, b)[source]

Returns the angle between two vectors in radians

MDAnalysis.core.util.dihedral(ab, bc, cd)[source]

Returns the dihedral angle in radians between vectors connecting A,B,C,D.

The dihedral measures the rotation around bc:

  ab
A---->B
       \ bc
       _\'
         C---->D
           cd

The dihedral angle is restricted to the range -π <= x <= π.

New in version 0.8.

MDAnalysis.core.util.stp(vec1, vec2, vec3)[source]

Takes the scalar triple product of three vectors.

Returns the volume V of the parallel epiped spanned by the three vectors

\[V = \mathbf{v}_3 \cdot (\mathbf{v}_1 \times \mathbf{v}_2)\]