contact_matrix¶
-
mdtools.structure.
contact_matrix
(ref, sel, cutoff, compound='atoms', min_contacts=1, fill_missing_cmp_ix=False, box=None, result=None, mdabackend='serial', debug=False)[source]¶ Construct a contact matrix for two MDAnalysis
AtomGroups
.Construct a boolean matrix whose elements indicate whether a contact exists between a given reference and selection compound or not. The matrix element
cm[i][j]
will beTrue
, if compoundj
of the selectionAtomGroup
has at least min_contacts contacts to compoundi
of the referenceAtomGroup
. A “contact” is defined as twoAtoms
from differentAtomGroups
whose distance is less than or equal to a given cutoff distance.- Parameters
ref, sel (MDAnalysis.core.groups.AtomGroup) – The reference/selection
AtomGroup
. Must be unique, i.e. must not contain dublicateAtoms
.cutoff (scalar) – A reference and selection
Atom
are considered to be in contact, if their distance is less than or equal to this cutoff. Must be greater than zero.compound ({‘atoms’, ‘group’, ‘segments’, ‘residues’, ‘fragments’}, optional) – The compounds of ref and sel for which to calculate the contact matrix. Must be either a single string which is applied to both, ref and sel, or a 1-dimensional array of two strings, the first for ref and and the second for sel. If compound is
'atoms'
, the resulting contact matrix represents contacts between the individualAtoms
. Else, the contact matrix represents contacts between entireAtomGroups
,Segments
,Residues
, orfragments
. Refer to the MDAnalysis’ user guide for an explanation of these terms. Note that in any case, even if e.g. compound is'residues'
, only theAtoms
belonging to ref and sel are taken into account, even if the compound might comprise additionalAtoms
that are not contained in theseAtomGroups
.min_contacts (int, optional) – Two compounds are considered to be in contact if the summed number of contacts between their
Atoms
is equal to or higher than min_contacts. Must be greater than zero. min_contacts is ignored if compound is'atoms'
, becauseAtoms
can only have one or no contact with anotherAtom
.fill_missing_cmp_ix (bool, optional) – If
True
, also create matrix elements for missing intermediate compound indices. These matrix elements will evaluate toFalse
. Only relevant, if the compounds of the reference and/or selection group do not form a contiguous set of indices. Seemdtools.structure.cm_fill_missing_cmp_ix()
for more details.box (array_like, option) – The unit cell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by
MDAnalysis.coordinates.base.Timestep.dimensions
:[lx, ly, lz, alpha, beta, gamma]
. If provided, the minimum image convention will be taken into account.result (numpy.ndarray, optional) – Preallocated result array for
MDAnalysis.lib.distances.distance_array()
which must have the shape(ref.n_atoms, sel.n_atoms)
and dtypenumpy.float64
. Avoids creating the array which saves time when the function is called repeatedly.mdabackend ({‘serial’, ‘OpenMP’}, optional) – Keyword selecting the type of acceleration for
MDAnalysis.lib.distances.distance_array()
. See there for further information.debug (bool, optional) – If
True
, run in debug mode.Deprecated since version 0.0.0.dev0: This argument is without use and will be removed in a future release.
- Returns
cm – Contact matrix as
numpy.ndarray
of dtypebool
. Matrix elements evaluating toTrue
indicate a contact between the respective compounds of the reference and selectionAtomGroup
.- Return type
See also
mdtools.structure.contact_matrices()
Construct a contact matrix for each frame in a trajectory
mdtools.structure.natms_per_cmp()
Get the number of
Atoms
of each compound in an MDAnalysisAtomGroup
mdtools.structure.cmp_contact_matrix()
Convert an
Atom
contact matrix to a compound contact matrixmdtools.structure.cmp_contact_count_matrix()
Take an
Atom
contact matrix and sum the contacts of allAtoms
belonging to the same compoundmdtools.structure.cm_fill_missing_cmp_ix()
Insert elements in a contact matrix at missing intermediate compound indices
mdtools.structure.contact_hists()
Bin the number of contacts between reference and selection compounds into histograms
MDAnalysis.lib.distances.distance_array()
Calculate all possible distances between a reference set of coordinates and another configuration
scipy.sparse
SciPy 2-D sparse matrix package
Notes
When holding multiply contact matrices in memory at once, you might want to convert them to
SciPy sparse matrices
to save memory.