nrgten.enm

class nrgten.enm.ENM(pdb_file, added_atypes=None, added_massdef=None, atypes_list=None, massdef_list=None, verbose=False, solve=False, use_pickle=False, ignore_hetatms=False, solve_mol=True, one_mass=False, teruel2021_legacy=False, use_precomp_vcon=False)

Abstract base class (ABC) for Elastic Network Models (ENMs).

The ENM class implements methods that are common for all implemented ENMs (ENCoM, ANM and STeM as of this writing) as well as the basic constructor. Subclasses are responsible for implementing the build_hessian() method (which generates the Hessian matrix) as well as the pickle() and build_from_pickle() methods which allow the pickling of solved ENMs for greatly accelerated subsequent computation of various metrics and/or properties.

dirpath

The absolute path to the directory containing the enm.py module.

Type:

str

verbose

If True, verbose mode is on.

Type:

bool

pickle_version

Ensures that ENMs pickled in the past are consistent with the current pickling scheme.

Type:

str

one_mass

For nucleic acids, False means 3 masses per nucleotide and True means 1 mass/nucleotide

Type:

bool

atypes_dict

Dictionary of atom types built from the .atomtypes configuration files.

Type:

dict

massdefs

Mass definitions built from the .masses configuration files.

Type:

MassDef

pdb_file

The PDB file on which the ENM is run.

Type:

str

mols

list of Macromol objects representing the macromolecules in the PDB file (one per MODEL).

Type:

list

mol

The first Macromol (and the only in case of single-model PDBs), on which the ENM will be solved.

Type:

Macromol

not_there

Set of atoms that are not defined in the .atomtypes and .masses config files (normally empty).

Type:

set

h

The Hessian matrix.

Type:

numpy.ndarray

eigvecs

The eigenvectors, in row format (one eigenvector per row).

Type:

numpy.ndarray

eigvals

list of eigenvalues, from lowest to highest

Type:

list

eigvecs_mat

The eigenvectors in column format (one eigenvector per column).

Type:

numpy.ndarrary

bfacts

The computed b-factors.

Type:

list

entropy

The computed vibrational entropy.

Type:

float

__init__(pdb_file, added_atypes=None, added_massdef=None, atypes_list=None, massdef_list=None, verbose=False, solve=False, use_pickle=False, ignore_hetatms=False, solve_mol=True, one_mass=False, teruel2021_legacy=False, use_precomp_vcon=False)

Constructor for the ENM abstract base class.

Parameters:

  • pdb_file (str) – The PDB file to read.

  • added_atypes (list, optional) – list of .atypes configuration files to add.

  • added_massdef (list, optional) – list of .masses configuration files to add.

  • atypes_list (list, optional) – If supplied, the default .atypes configuration files are ignored and these are the only ones read.

  • massdef_list (list, optional) – If supplied, the default .masses configuration files are ignored and these are the only ones read.

  • verbose (bool, optional) – Triggers the verbose mode.

  • solve (bool, optional) – If True, the Hessian matrix will be built and solved.

  • use_pickle (bool, optional) – If True, the ENM object will be solved only once and subsequently built from its pickled representation. Uses a lot of disk space for large systems.

  • ignore_hetatms (bool, optional) – Flag to ignore HETATM records in the PDB file.

  • solve_mol (bool, optional) – If True, the underlying Macromol object will be solved, i.e. the connectivity of the residues will be inferred.

  • one_mass (bool, optional) – If True, nucleic acids will be built using only one mass per nucleotide instead of 3.

  • teruel2021_legacy (bool, optional) – If True, the parameters will perfectly reproduce the vibrational entropy calculations in the Teruel et al. 2021 PLoS Computational Biology paper

build_conf_ensemble(modes_list, filename, step=0.5, max_displacement=2.0, max_conformations=10000, use_motion=False)

Creates a conformational ensemble as a multi-model PDB file.

The idea is to make every combination of the selected modes at every given rmsd step, up to a total deformation for each mode (and in both directions).

Note

The mode indices in the modes_list argument are assumed to start at 1, with the first nontrivial mode thus being at index 7.

Parameters:

  • modes_list (list) – list of integer indices of modes to use for the conformational ensemble. The first non-trivial mode is at index 7.

  • filename (str) – The filename where the conformational ensemble will be written.

  • step (optional, float) – The RMSD step between each grid point in the conformational ensemble.

  • max_displacement (float, optional) – The maximum RMSD displacement for each mode. Has to be a multiple of step.

  • max_conformations (int, optional) – The maximum number of conformations. Ensures that users do not accidentally generate huge PDB files.

abstract build_from_pickle()

Builds the solved ENM state from a pickled object. Implemented by subclasses.

Note

Since ENMs in general have parameters, subclasses need to make sure to check that the input PDB and all parameters are identical between the pickled representation and the present run. See example in ENCoM class in encom module.

Returns:

True if successful, False otherwise.

Return type:

bool

abstract build_hessian()

Builds the Hessian matrix for the ENM. Implemented by subclasses.

compute_bfactors(filter=None)

Computes the predicted b-factors.

The root-mean-square flutuations of every mass can be seen as a prediction of the experimental temperature factors, or B-factors.

Note

In order to have more convenient numbers, the b-factors are scaled up by a factor of 1000. This does not affect the validity of the value as it is only an indicator of relative flexibility between the masses.

Parameters:

filter (set, optional) – set of str names of masses to select (corresponding to the names in .masses config files).

Returns:

the computed b-factors

Return type:

list

compute_vib_enthalpy(beta=None, factor=1)

Vibrational enthalpy from the eigenfrequencies (without rigid-rotor approximation).

Parameters:

  • beta (float, optional) – The scaling factor (higher beta means lower temperature). If None, the default value is used.

  • factor (float, optional) – Can be used to scale the default value when beta is set to None.

Returns:

The vibrational entropy of the system.

Return type:

float

compute_vib_entropy(beta=1)

Vibrational entropy from the eigenfrequencies (without rigid-rotor approximation). .. note:

This is a more exact form of the vibrational entropy and is the preferred way to compute it. The
compute_vib_entropy_rigid_rotor method is there only for reproducibility purposes as the old ENCoM model
used that form.
Parameters:

  • beta (float, optional) – The scaling factor (higher beta means lower temperature). Default is 1 due to

  • data. (preliminary) –

Returns:

The vibrational entropy of the system.

Return type:

float

compute_vib_entropy_rigid_rotor()

Computes the vibrational entropy of the system using the rigid-rotor approximation.

Note

This was the form used in the original ENCoM paper (doi: 10.1371/journal.pcbi.1003569)

Returns:

The vibrational entropy of the system.

Return type:

float

get_exp_bfacts(method='average', filter=None)

Extracts the experimental b-factors for every mass in the system.

Parameters:

  • method (str) – can currently be only “average” or “center”. Average is the mean taken from all the atoms in the residue. Center is the value from the center atom (on which the mass is positioned).

  • filter (set, optional) – set of str names of masses to select (corresponding to the names in .masses config files).

get_filtered_3n_vector(filter)

Gives the x,y,z coordinates of selected masses in the form of a single vector.

Note

The vector is in the format: [x1, y1, z1, x2, y2, z2, …, xN, yN, zN].

Parameters:

filter (set) – set of str names of masses to select (corresponding to the names in .masses config files).

Returns:

The 3N-dimensional vector of coordinates for the selected masses.

get_filtered_eigvecs_mat(indices=None, filter=None, transpose=True, n_vecs=None, start=0)

Allows to select subvectors that correspond to certain masses.

This is useful when there are multiple masses per residue and the user wants to reduce eigenvectors to have 1 xyz component per residue, for example. It also allows to select specific indices, which is useful in the case of alignments between slightly different structures.

Note

The filtered vectors are always orthonormalized.

Parameters:

  • indices (list, optional) – list of indices to select, from 0 to n-1 (n being the number of masses).

  • filter (set, optional) – set of str names of masses to select (corresponding to the names in .masses config files).

  • transpose (bool, optional) – If True, returns column vectors, otherwise returns row vectors.

  • n_vecs (int, optional) – The number of vectors to return, starting from start

  • start (int, optional) – The first vector to return.

Returns:

the filtered eigenvectors in column format, or row format if transpose is False.

Return type:

numpy.ndarray

get_filtered_xyz(filter)

Gives the x,y,z coordinates of selected masses in the form of an Nx3 matrix.

Parameters:

filter (set) – set of str names of masses to select (corresponding to the names in .masses config files).

Returns:

Nx3 matrix of x,y,z coordinates of the selected masses.

Return type:

numpy.ndarray

get_n_masses()

Gives the number of masses in the ENM.

Returns:

the number of masses in the ENM.

Return type:

int

get_xyz()

Gives the x,y,z coordinates of the masses in the form of an Nx3 matrix.

Returns:

Nx3 matrix of x,y,z coordinates of the masses.

Return type:

numpy.ndarray

is_equal(other)

Compares two ENM objects for equality. Useful for unpickling.

Parameters:

other (ENM) – instance of ENM to test.

Note

This is the general method that subclasses can call in addition to any specifics about their implementation.

Returns:

True if equal, False otherwise.

Return type:

bool

abstract pickle()

Uses the pickle module to produce a serialized object. Implemented by subclasses.

Note

Since many ENMs may end up being run on the same file, the extension of the pickled file must be unique (i.e. .encom.pickle, .anm.pickle, etc.)

set_bfactors(vector)

Sets the b-factors of all atoms in the file.

Parameters:

vector (list) – the new b-factors, needs to be the same length as the number of masses.

set_occupancy(vector)

Sets the occupancy of all atoms in the file.

Parameters:

vector (list) – the new occupancy values, need to be the same length as the number of masses.

solve()

Solves the Hessian matrix to get eigenvectors and eigenvalues.

Returns:

(eigenvalues, eigenvectors) eigenvectors are in row format

Return type:

tuple

write_dynamical_signature(outfile, normalize=False)

Writes a ‘dynamical signature’ to the output file specified.

The dynamical signature is simply the predicted b_factor at every mass.

Parameters:

  • outfile (str) – the output file.

  • normalize (bool, optional) – if True, the signature is normalized to 1