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 be True, if compound j of the selection AtomGroup has at least min_contacts contacts to compound i of the reference AtomGroup. A “contact” is defined as two Atoms from different AtomGroups 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 duplicate Atoms.
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 individual Atoms. Else, the contact matrix represents contacts between entire AtomGroups, Segments, Residues, or fragments. 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 the Atoms belonging to ref and sel are taken into account, even if the compound might comprise additional Atoms that are not contained in these AtomGroups.
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', because Atoms can only have one or no contact with another Atom.
fill_missing_cmp_ix (bool, optional) – If True, also create matrix elements for missing intermediate compound indices. These matrix elements will evaluate to False. Only relevant, if the compounds of the reference and/or selection group do not form a contiguous set of indices. See mdtools.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 dtype numpy.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 (numpy.ndarray) – Contact matrix as numpy.ndarray of dtype bool. Matrix elements evaluating to True indicate a contact between the respective compounds of the reference and selection AtomGroup.