Supporting Functions

This module defines a functions for handling conformational ensembles.

saveEnsemble(ensemble, filename=None, **kwargs)[source]

Save ensemble model data as filename.ens.npz. If filename is None, title of the ensemble will be used as the filename, after white spaces in the title are replaced with underscores. Extension is .ens.npz. Upon successful completion of saving, filename is returned. This function makes use of savez() function.

loadEnsemble(filename, **kwargs)[source]

Returns ensemble instance loaded from filename. This function makes use of load() function. See also saveEnsemble()

trimPDBEnsemble(pdb_ensemble, occupancy=None, **kwargs)[source]

Returns a new PDB ensemble obtained by trimming given pdb_ensemble. This function helps selecting atoms in a pdb ensemble based on one of the following criteria, and returns them in a new PDBEnsemble instance.

Resulting PDB ensemble will contain atoms whose occupancies are greater or equal to occupancy keyword argument. Occupancies for atoms will be calculated using calcOccupancies(pdb_ensemble, normed=True).

Parameters:
  • occupancy (float) – occupancy for selecting atoms, must satisfy 0 < occupancy <= 1. If set to None then hard trimming will be performed.
  • hard (bool) – Whether to perform hard trimming. Default is False If set to True, atoms will be completely removed from pdb_ensemble. If set to False, a soft trimming of pdb_ensemble will be done where atoms will be removed from the active selection. This is useful, for example, when one uses calcEnsembleENMs() together with sliceModel() or reduceModel() to calculate the modes from the remaining part while still taking the removed part into consideration (e.g. as the environment).
calcOccupancies(pdb_ensemble, normed=False)[source]

Returns occupancy calculated from weights of a PDBEnsemble. Any non-zero weight will be considered equal to one. Occupancies are calculated by binary weights for each atom over the conformations in the ensemble. When normed is True, total weights will be divided by the number of atoms. This function can be used to see how many times a residue is resolved when analyzing an ensemble of X-ray structures.

showOccupancies(pdbensemble, *args, **kwargs)[source]

Show occupancies for the PDB ensemble using plot(). Occupancies are calculated using calcOccupancies().

buildPDBEnsemble(atomics, ref=None, title='Unknown', labels=None, atommaps=None, unmapped=None, **kwargs)[source]

Builds a PDBEnsemble from a given reference structure and a list of structures (Atomic instances). Note that the reference should be included in the list as well.

Parameters:
  • atomics (list) – a list of Atomic instances
  • ref (int, Chain, Selection, or AtomGroup) – reference structure or the index to the reference in atomics. If None, then the first item in atomics will be considered as the reference. If it is a PDBEnsemble instance, then atomics will be appended to the existing ensemble. Default is None
  • title (str) – the title of the ensemble
  • labels (list) – labels of the conformations
  • degeneracy (bool) – whether only the active coordinate set (True) or all the coordinate sets (False) of each structure should be added to the ensemble. Default is True
  • occupancy (float) – minimal occupancy of columns (range from 0 to 1). Columns whose occupancy is below this value will be trimmed
  • atommaps (list) – labels of atomics that were mapped and added into the ensemble. This is an output argument
  • unmapped (list) – labels of atomics that cannot be included in the ensemble. This is an output argument
  • subset (str) – a subset for selecting particular atoms from the input structures. Default is "all"
  • superpose (str, bool) – if set to 'iter', PDBEnsemble.iterpose() will be used to superpose the structures, otherwise conformations will be superposed with respect to the reference specified by ref unless set to False. Default is 'iter'
refineEnsemble(ensemble, lower=0.5, upper=10.0, **kwargs)[source]

Refine a PDBEnsemble based on RMSD criterions.

Parameters:
  • ensemble (Ensemble, PDBEnsemble) – the ensemble to be refined
  • lower (float) – the smallest allowed RMSD between two conformations with the exception of protected
  • upper (float) – the highest allowed RMSD between two conformations with the exception of protected
  • protected (list) – a list of either the indices or labels of the conformations needed to be kept in the refined ensemble
  • ref (int or str) – the index or label of the reference conformation which will also be kept. Default is 0
combineEnsembles(target, mobile, **kwargs)[source]

Combines two ensembles by mapping the atoms of mobile to that of target.

alignByEnsemble(atomics, ensemble)[source]

Align a set of Atomic objects using transformations from ensemble, which may be a PDBEnsemble or a PDBConformation instance.

Transformations will be applied based on indices so atomics and ensemble must have the same number of members.

Parameters: