contact_matrices¶

mdtools.structure.contact_matrices(ref, sel, cutoff, trj=None, topfile=None, trjfile=None, begin=0, end=- 1, every=1, updating_ref=False, updating_sel=False, compound='atoms', min_contacts=1, fill_missing_cmp_ix=False, mdabackend='serial', verbose=True)[source]¶

Construct a contact matrix for two MDAnalysis AtomGroups for each frame in a trajectory.

Parameters

ref, sel (MDAnalysis.core.groups.AtomGroup or str) – ‘Reference/Selection group’: Either a MDAnalysis AtomGroup (if trj is not None) or a selection strings for creating a MDAnalysis AtomGroup (if trj is None). See MDAnalysis’ selection syntax for possible choices of selection strings.
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.
trj (MDAnalysis.coordinates.base.ReaderBase or MDAnalysis.coordinates.base.FrameIteratorBase, optional) – MDAnalysis trajectory to read. If None, a new MDAnalysis Universe and trajectory are created from topfile and trjfile.
topfile (str, optional) – Topology file. See supported topology formats of MDAnalysis. Ignored if trj is not None.
trjfile (str, optional) – Trajectory file. See supported coordinate formats of MDAnalysis. Ignored if trj is not None.
begin (int, optional) – First frame to read from a newly created trajectory. Frame numbering starts at zero. Ignored if trj is not None. If you want to use only specific frames from an already existing trajectory, slice the existing trajectory accordingly and parse it as MDAnalysis.coordinates.base.FrameIteratorSliced object to the trj argument.
end (int, optional) – Last frame to read from a newly created trajectory. This is exclusive, i.e. the last frame read is actually end - 1. A value of -1 means to read the very last frame. Ignored if trj is not None.
every (int, optional) – Read every n-th frame from the newly created trajectory. Ignored if trj is not None.
updating_ref, updating_sel (bool, optional) – Use and UpdatingAtomGroup for a newly created reference/selection group. Selection expressions of UpdatingAtomGroups are re-evaluated every time step. E.g. useful for position-based selections like ‘type Li and prop z <= 2.0’. Note that the contact matrices for different frames might have different shapes when using UpdatingAtomGroups. Ignored if trj is not None.
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.
mdabackend ({‘serial’, ‘OpenMP’}, optional) – Keyword selecting the type of acceleration for MDAnalysis.lib.distances.distance_array(). See there for further information.
verbose (bool, optional) – If True, print progress information to standard output.

Returns

cms – List of contact matrices, one for each frame in the trajectory. The contact matrices are stored as scipy.sparse.csr_matrix. Each contact matrix has as many rows as reference compounds and as many columns as selection compounds. See mdtools.structure.contact_matrix() for more details.

Return type

list