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/selectionAtomGroup
. Must be unique, i.e. must not contain duplicateAtoms
.cutoff (
scalar
) – A reference and selectionAtom
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 theirAtoms
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) – IfTrue
, 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 byMDAnalysis.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 forMDAnalysis.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 forMDAnalysis.lib.distances.distance_array()
. See there for further information.debug (
bool
, optional) – IfTrue
, 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 (
numpy.ndarray
) – Contact matrix asnumpy.ndarray
of dtypebool
. Matrix elements evaluating toTrue
indicate a contact between the respective compounds of the reference and selectionAtomGroup
.
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.