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
orstr
) – Reference and selection group: Either an MDAnalysisAtomGroup
(if trj is notNone
) or a selection string for creating an MDAnalysisAtomGroup
(if trj isNone
). See MDAnalysis’ selection syntax for possible choices of selection strings.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.trj (
MDAnalysis.coordinates.base.ReaderBase
or MDAnalysis.coordinates.base.FrameIteratorBase, optional) – MDAnalysis trajectory to read. IfNone
, a new MDAnalysisUniverse
and trajectory are created from topfile and trjfile.topfile (
str
, optional) – Topology file. See supported topology formats of MDAnalysis. Ignored if trj is given.trjfile (
str
, optional) – Trajectory file. See supported coordinate formats of MDAnalysis. Ignored if trj is given.begin (
int
, optional) – First frame to read from a newly created trajectory. Frame numbering starts at zero. Ignored if trj is given. If you want to use only specific frames from an already existing trajectory, slice the existing trajectory accordingly and parse it asMDAnalysis.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 actuallyend - 1
. A value of-1
means to read the very last frame. Ignored if trj is given.every (
int
, optional) – Read every n-th frame from the newly created trajectory. Ignored if trj is given.updating_ref, updating_sel (
bool
, optional) – If trj is not given, indicate that the provided reference/selection group is anUpdatingAtomGroup
. If trj is given, use anUpdatingAtomGroup
for the newly created reference/selection group. Selection expressions ofUpdatingAtomGroups
are re-evaluated every time step. For instance, this is 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 usingUpdatingAtomGroups
.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.mdabackend (
{'serial', 'OpenMP'}
, optional) – Keyword selecting the type of acceleration forMDAnalysis.lib.distances.distance_array()
. See there for further information.verbose (
bool
, optional) – IfTrue
, print progress information to standard output.
- Returns:
cms (
list
) – List of contact matrices, one for each frame in the trajectory. The contact matrices are stored asscipy.sparse.csr_matrix
. Each contact matrix has as many rows as reference compounds and as many columns as selection compounds. Seemdtools.structure.contact_matrix()
for more details.
See also
mdtools.structure.contact_matrix()
Construct a boolean contact matrix for two MDAnalysis
AtomGroups
scipy.sparse
SciPy 2-D sparse matrix package