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 notNone
.trjfile (
str
, optional) – Trajectory file. See supported coordinate formats of MDAnalysis. Ignored if trj is notNone
.begin (
int
, optional) – First frame to read from a newly created trajectory. Frame numbering starts at zero. Ignored if trj is notNone
. 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 notNone
.every (
int
, optional) – Read every n-th frame from the newly created trajectory. Ignored if trj is notNone
.updating_ref, updating_sel (
bool
, optional) – Use anUpdatingAtomGroup
for a 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
. Ignored if trj is notNone
.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