Supporting Functions

This module defines input and output functions.

parseArray(filename, delimiter=None, skiprows=0, usecols=None, dtype=<type 'float'>)

Parse array data from a file.

This function is using numpy.loadtxt() to parse the file. Each row in the text file must have the same number of values.

Parameters:

• filename (str or file) – File or filename to read. If the filename extension is .gz or .bz2, the file is first decompressed.
• delimiter (str) – The string used to separate values. By default, this is any whitespace.
• skiprows (int) – Skip the first skiprows lines, default is 0.
• usecols (list) – Which columns to read, with 0 being the first. For example, usecols = (1,4,5) will extract the 2nd, 5th and 6th columns. The default, None, results in all columns being read.
• dtype (numpy.dtype.) – Data-type of the resulting array, default is float().

parseModes(normalmodes, eigenvalues=None, nm_delimiter=None, nm_skiprows=0, nm_usecols=None, ev_delimiter=None, ev_skiprows=0, ev_usecols=None, ev_usevalues=None)

Returns NMA instance with normal modes parsed from normalmodes.

In normal mode file normalmodes, columns must correspond to modes (eigenvectors). Optionally, eigenvalues can be parsed from a separate file. If eigenvalues are not provided, they will all be set to 1.

Parameters:

• normalmodes (str or file) – File or filename that contains normal modes. If the filename extension is .gz or .bz2, the file is first decompressed.
• eigenvalues (str or file) – Optional, file or filename that contains eigenvalues. If the filename extension is .gz or .bz2, the file is first decompressed.
• nm_delimiter (str) – The string used to separate values in normalmodes. By default, this is any whitespace.
• nm_skiprows (0) – Skip the first skiprows lines in normalmodes. Default is 0.
• nm_usecols (list) – Which columns to read from normalmodes, with 0 being the first. For example, usecols = (1,4,5) will extract the 2nd, 5th and 6th columns. The default, None, results in all columns being read.
• ev_delimiter (str) – The string used to separate values in eigenvalues. By default, this is any whitespace.
• ev_skiprows (0) – Skip the first skiprows lines in eigenvalues. Default is 0.
• ev_usecols (list) – Which columns to read from eigenvalues, with 0 being the first. For example, usecols = (1,4,5) will extract the 2nd, 5th and 6th columns. The default, None, results in all columns being read.
• ev_usevalues (list) – Which columns to use after the eigenvalue column is parsed from eigenvalues, with 0 being the first. This can be used if eigenvalues contains more values than the number of modes in normalmodes.

See parseArray() for details of parsing arrays from files.

parseSparseMatrix(filename, symmetric=False, delimiter=None, skiprows=0, irow=0, icol=1, first=1)

Parse sparse matrix data from a file.

This function is using parseArray() to parse the file. Input must have the following format:

1       1    9.958948135375977e+00
1       2   -3.788214445114136e+00
1       3    6.236155629158020e-01
1       4   -7.820609807968140e-01

Each row in the text file must have the same number of values.

Parameters:

• filename (str or file) – File or filename to read. If the filename extension is .gz or .bz2, the file is first decompressed.
• symmetric (bool) – Set True if the file contains triangular part of a symmetric matrix, default is True.
• delimiter (str) – The string used to separate values. By default, this is any whitespace.
• skiprows (int) – Skip the first skiprows lines, default is 0.
• irow (int) – Index of the column in data file corresponding to row indices, default is 0.
• icol (int) – Index of the column in data file corresponding to column indices, default is 1.
• first (int) – First index in the data file (0 or 1), default is 1.

Data-type of the resulting array, default is float().

parseGromacsModes(run_path, title='', model='nma', **kwargs)

Returns NMA containing eigenvectors and eigenvalues parsed from a run directory containing results from gmx covar or gmx nmeig followed by gmx anaeig including eigenvalues in an xvg file and eigenvectors in pdb files (see http://www.strodel.info/index_files/lecture/html/analysis-9.html).

Parameters:

• run_path (str) – path to the run directory
• title (str) – title for resulting object Default is ""
• model (str) – type of calculated that was performed. It can be either "nma" or "pca". If it is not changed to "pca" then "nma" will be assumed.
• eigval_fname (str) – filename or path for xvg file containing eigenvalues Default is "eigenval.xvg" as this is the default from Gromacs
• eigvec_fname (str) – filename or path for trr file containing eigenvectors Default is "eigenvec.trr" as this is the default from Gromacs
• pdb_fname (str) – filename or path for pdb file containing the reference structure Default is "average.pdb" although this is probably suboptimal

parseScipionModes(metadata_file, title=None, pdb=None, parseIndices=False)

Returns NMA or GNM containing eigenvectors and eigenvalues parsed from an NMA, GNM or PCA protocol path from ContinuousFlex or Scipion-EM-ProDy.

Parameters:

• metadata_file (str) – metadata sqlite file in Scipion protocol path The location of this file is currently limited to the top level of the project path and not to deep directories like the extra path.
• title (str) – title for NMA object
• pdb (str) – pdb file to help define dof
• parseIndices (bool) – whether to parse indices and output a ModeSet default False

writeArray(filename, array, format='%3.2f', delimiter=' ')

Write 1-d or 2-d array data into a delimited text file.

This function is using numpy.savetxt() to write the file, after making some type and value checks. Default format argument is "%d". Default delimiter argument is white space, " ".

filename will be returned upon successful writing.

writeModes(filename, modes, format='%.18e', delimiter=' ')

Write modes (eigenvectors) into a plain text file with name filename. See also writeArray().

writeScipionModes(output_path, modes, write_star=False, scores=None, only_sqlite=False, collectivityThreshold=0.0)

Writes modes to a set of files that can be recognised by Scipion. A directory called “modes” will be created if it doesn’t already exist. Filenames inside will start with “vec” and have the mode number as the extension.

Parameters:

• output_path (str) – path to the directory where the modes directory will be
• modes (Mode, ModeSet, NMA) – modes to be written to files
• write_star (bool) – whether to write modes.xmd STAR file. Default is False as qualifyModesStep writes it with scores.
• scores (list) – scores from qualifyModesStep for re-writing sqlite Default is None and then it uses calcScipionScore()
• only_sqlite (bool) – whether to write only the sqlite file instead of everything. Default is False but it can be useful to set it to True for updating the sqlite file.
• collectivityThreshold (float) – collectivity threshold below which modes are not enabled Default is 0.

saveModel(nma, filename=None, matrices=False, **kwargs)

Save nma model data as filename.nma.npz. By default, eigenvalues, eigenvectors, variances, trace of covariance matrix, and name of the model will be saved. If matrices is True, covariance, Hessian or Kirchhoff matrices are saved too, whichever are available. If filename is None, name of the NMA instance will be used as the filename, after " " (white spaces) in the name are replaced with "_" (underscores). Extension may differ based on the type of the NMA model. For ANM models, it is .anm.npz. Upon successful completion of saving, filename is returned. This function makes use of savez() function.

loadModel(filename, **kwargs)

Returns NMA instance after loading it from file (filename). This function makes use of load() function. See also saveModel().

saveVector(vector, filename, **kwargs)

Save vector data as filename.vec.npz. Upon successful completion of saving, filename is returned. This function makes use of numpy.savez() function.

loadVector(filename)

Returns Vector instance after loading it from filename using numpy.load(). See also saveVector().

calcENM(atoms, select=None, model='anm', trim='trim', gamma=1.0, title=None, n_modes=None, **kwargs)

Returns an ANM or GNM instance and atoms used for the calculations. The model can be trimmed, sliced, or reduced based on the selection.

Parameters:

• atoms (Atomic, AtomGroup, Selection, ndarray) – atoms on which the ENM is performed. It can be any Atomic class that supports selection or a ndarray.
• select (str, Selection, ndarray) – part of the atoms that is considered as the system. If set to None, then all atoms will be considered as the system
• model (str) – type of ENM that will be performed. It can be either "anm" or "gnm" or "exanm"
• trim (str) – type of method that will be used to trim the model. It can be either "trim" , "slice", or "reduce". If set to "trim", the parts that is not in the selection will simply be removed

realignModes(modes, atoms, ref)

Align modes in the original frame based on atoms onto another frame based on ref using the transformation from alignment of atoms to ref

Parameters:

• modes (ModeSet, ANM, PCA) – multiple 3D modes
• atoms (Atomic) – central structure related to modes to map onto ref Inserting atoms into an ensemble and projecting onto modes should give all zeros
• ref (Atomic) – reference structure for mapping