polyphys.probe.binders#

polyphys.probe.binders#

The polyphys.probe.binders module counts, in every frame of a trajectory, how the two-patch binders of a study bind its polymer chain: how many patches touch a monomer, how many binders are free, dangling by one patch, or bridging two monomers, how many bridged pairs are cis or trans, and the histogram of the bridged pairs’ genomic distances, the loop lengths. BinderStatistics is an MDAnalysis AnalysisBase, so it runs over a slice of frames in serial or, split across workers, in parallel, and stores one array per count in its results.

The research code measured the same eight counts in the H-NS probe of each study: the distances between every monomer and every patch, with no minimum image, the contacts below a cutoff, and the counts of its hns_binding. Here the distances take the minimum image along the directions the study’s geometry makes periodic, the cutoff and the comparison are the study’s BinderSpec, and the counting is binding_statistics().

Contents#

Dependencies#

Notation#

\(N_m\), \(N_p\), \(N_b = N_p / 2\)

The numbers of monomers, patches, and binders; the two patches of binder \(k\) are the patches \(2k\) and \(2k + 1\) in atom-ID order.

\(r_{ij}\)

The distance between monomer \(i\) and patch \(j\), in the dump’s length unit, the monomer diameter in the studies; along a periodic direction of box length \(L\), the component is reduced to \([-L/2, L/2)\) first (the minimum image).

\(r_\mathrm{thres}\)

The binding threshold, cutoff: monomer \(i\) and patch \(j\) are in contact when \(r_{ij} \le r_\mathrm{thres}\) (inclusive) or \(r_{ij} < r_\mathrm{thres}\).

\(d\)

The genomic distance of a bridged pair, in bonds along the backbone, the shorter way round on a ring; a bridge is cis when \(d \le\) cis_threshold and trans otherwise.

Examples

A linear chain of four beads one unit apart and one binder whose two patches sit 0.3 above beads 0 and 2, in a one-frame universe:

>>> import MDAnalysis as mda
>>> import numpy as np
>>> universe = mda.Universe.empty(6, trajectory=True)
>>> universe.atoms.positions = np.array(
...     [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [2.0, 0.0, 0.0], [3.0, 0.0, 0.0],
...      [0.0, 0.3, 0.0], [2.0, 0.3, 0.0]])
>>> analysis = BinderStatistics(
...     universe.atoms[:4], universe.atoms[4:], cutoff=0.5,
...     topology='linear', cis_threshold=1).run()
>>> analysis.results['n_binders_bridging'], analysis.results['n_pairs_trans']
(array([1]), array([1]))
>>> analysis.results['loop_length_histogram']
array([[0, 0, 1, 0]])

Added in version 0.7.0.

Module Attributes

LOOP_KEY

The result key of the per-frame loop-length histogram.

DISTANCES_KEY

The result key of the per-frame monomer-to-patch distance matrices, when they are stored.

Classes

BinderStatistics(chain, patches, *, cutoff, ...)

The binding of two-patch binders to one polymer chain, counted in every frame.

class polyphys.probe.binders.BinderStatistics(chain, patches, *, cutoff, topology, cis_threshold, inclusive=True, patches_per_binder=2, periodic=(False, False, False), store_distances=False, chain_label='Mon', patch_label='HnsPatch', binder_label='HnsCore', verbose=False)[source]#

Bases: polyphys.probe.core._ProbeAnalysis

The binding of two-patch binders to one polymer chain, counted in every frame.

Added in version 0.7.0.

Changed in version 1.0.0: cis_threshold has no default.

Parameters:
  • chain (MDAnalysis.core.groups.AtomGroup) – The chain, at least two monomers, in atom-ID order: the order along the backbone, which Universe.select_atoms gives.

  • patches (MDAnalysis.core.groups.AtomGroup) – The binders’ patches, in atom-ID order, from the same universe as chain: the two patches of binder \(k\) at positions \(2k\) and \(2k + 1\), so their number is a positive multiple of patches_per_binder. The binder cores are not needed.

  • cutoff (float) – The binding threshold \(r_\mathrm{thres}\), in the dump’s length unit; finite and positive.

  • topology (str) – 'linear' or 'ring', whether the chain is open or closed, which sets the genomic distance of a bridged pair and the length of the loop-length histogram.

  • cis_threshold (int) – The largest genomic distance, in bonds, of a cis bridge; non-negative, with no default.

  • inclusive (bool) – Whether a pair at exactly cutoff is a contact (\(r \le r_\mathrm{thres}\)) or not (\(r < r_\mathrm{thres}\)).

  • patches_per_binder (int) – The number of patches per binder; only 2 is accepted, which binding_statistics() counts.

  • periodic (tuple[bool, bool, bool]) – Whether the minimum image is taken along x, y, and z, with the box lengths of each frame. The research probe took none; from_spec() sets every direction in a cube and z only in a cylinder.

  • store_distances (bool) – Whether the monomer-to-patch distance matrix of every frame is kept in results and written by save().

  • chain_label (str) – The species labels that name the files save() writes; 'Mon', 'HnsPatch', and 'HnsCore' by default, the H-NS studies’ names.

  • patch_label (str) – The species labels that name the files save() writes; 'Mon', 'HnsPatch', and 'HnsCore' by default, the H-NS studies’ names.

  • binder_label (str) – The species labels that name the files save() writes; 'Mon', 'HnsPatch', and 'HnsCore' by default, the H-NS studies’ names.

  • verbose (bool) – Whether to show a progress bar during run().

Variables:
  • chain (AtomGroup) – The chain.

  • patches (AtomGroup) – The patches.

  • cutoff (float) – The binding threshold.

  • topology (TopologyT) – The chain’s topology.

  • inclusive (bool) – Whether a pair at exactly cutoff is a contact.

  • cis_threshold (int) – The largest genomic distance of a cis bridge, in bonds.

  • patches_per_binder (int) – The number of patches per binder, 2.

  • periodic (tuple of bool) – The directions along which the minimum image is taken.

  • store_distances (bool) – Whether the distance matrices are kept.

  • chain_label (EntityT) – The species label of the chain in the saved files.

  • patch_label (EntityT) – The species label of the patches in the saved files.

  • binder_label (EntityT) – The species label of the binders in the saved files.

  • n_lengths (int) – The length of a loop-length histogram row: n_monomers // 2 + 1 on a ring, n_monomers on a linear chain, as BindingStats sizes it.

  • results (Results) – After run(): one int64 array of shape (n_frames,) per attribute of FrameBinding in BINDER_SERIES, keyed by that name; 'loop_length_histogram', int64 of shape (n_frames, n_lengths), whose row [t, d] is the number of distinct bridged pairs at \(d\) bonds in frame t, with column 0 always 0; and, with store_distances, 'distances', float64 of shape (n_frames, n_monomers, n_patches).

  • n_frames (int) – After run(), the number of frames analyzed, from AnalysisBase.

  • times (frames,) – After run(), the indices and times of the frames analyzed, shape (n_frames,).

Raises:

ValueError – If chain has fewer than two atoms; if patches is empty, is not from the universe of chain, or has a number of atoms that is not a multiple of patches_per_binder; if cutoff is not a finite positive number; if topology is not 'linear' or 'ring'; if cis_threshold is negative; if patches_per_binder is not 2; if periodic is not three booleans; or if a label is empty. During run(), if a periodic direction is asked for and the frame carries no box.

Notes

Per frame, the analysis forms \(r_{ij}\) for every monomer and patch, with the minimum image along the periodic directions, marks the contacts with find_direct_contacts(), and counts them with binding_statistics(), whose rules hold here: the patch and binder counts use the contacts as marked, so a patch within the cutoff of two adjacent monomers is one engaged patch; the bridged pairs use one monomer per patch, the lowest-index one, so each bridging binder joins exactly two monomers; and cis and trans count distinct monomer pairs. The histogram row is the bincount of the bridged pairs’ genomic distances.

The binder model is the bivalent patchy protein of Brackley et al. [1], with a patch at each pole of a repulsive core, that the H-NS studies follow [2]; the dangling, cis, and trans modes and the cis threshold of two intervening monomers are those of Joyeux and Vreede [3], whose cis bridge joins sites “separated by at most two DNA beads”, a genomic distance of at most 3 bonds: cis_threshold of 3, which the H-NS studies state. A patch that sits between two consecutive monomers can touch both, which Brackley [4] notes as the one way a single patch reaches two beads; the single-patch rule resolves it.

The MDAnalysis contract: _prepare allocates the arrays for the frames of the run, _single_frame writes the current frame’s row, and _conclude does nothing. The class is marked parallelizable, with serial, multiprocessing, and dask backends; each worker fills the arrays of its own frames, which _get_aggregator concatenates along the frame axis (ResultsGroup.ndarray_hstack for the eight series, ResultsGroup.ndarray_vstack for the histogram and the distances).

Cost per frame: \(O(N_m N_p)\) time for the distances and the contacts, plus \(O(N_b \log N_b)\) to make the bridged pairs distinct, and \(O(N_m N_p)\) space for the distance and contact matrices. Over a run of \(F\) frames, \(O(F)\) space per series, \(O(F N_m / 2)\) for the histogram, and, with store_distances, \(8 F N_m N_p\) bytes for the float64 distances, held in memory until save(), as the research code held its list of matrices. Positions come from MDAnalysis as float32, so each distance carries a relative round-off of about \(10^{-7}\) before it is compared with the cutoff.

References

Examples

A ring of six beads and two binders over one frame: binder 0 bridges beads 0 and 2, two bonds apart; binder 1 dangles from bead 4 with its other patch far away.

>>> import MDAnalysis as mda
>>> import numpy as np
>>> chain = np.column_stack([np.arange(6.0), np.zeros(6), np.zeros(6)])
>>> patches = np.array([[0.0, 0.3, 0.0], [2.0, 0.3, 0.0],
...                     [4.0, 0.3, 0.0], [9.0, 9.0, 9.0]])
>>> universe = mda.Universe.empty(10, trajectory=True)
>>> universe.atoms.positions = np.vstack([chain, patches])
>>> analysis = BinderStatistics(
...     universe.atoms[:6], universe.atoms[6:], cutoff=0.5,
...     topology='ring', cis_threshold=4).run()
>>> [int(analysis.results[key][0]) for key in BINDER_SERIES]
[3, 1, 3, 0, 1, 1, 1, 0]
>>> analysis.results['loop_length_histogram']
array([[0, 0, 1, 0]])

The eight values are, in the order of BINDER_SERIES: three patch-monomer contacts, one free and three engaged patches, no free binder, one bridging and one dangling binder, one cis pair and no trans pair.

With the minimum image along x in a box of length 10, a patch at x = 9.8 touches bead 0:

>>> universe.trajectory.ts.dimensions = [10.0, 10.0, 10.0, 90, 90, 90]
>>> universe.atoms[9].position = [9.8, 0.0, 0.0]
>>> wrapped = BinderStatistics(
...     universe.atoms[:6], universe.atoms[6:], cutoff=0.5,
...     topology='ring', cis_threshold=4,
...     periodic=(True, False, False)).run()
>>> int(wrapped.results['n_binders_bridging'][0])
2
classmethod from_spec(universe, spec, *, verbose=False)[source]#

Build the analysis of a study’s binders from its probe spec.

The chain is universe.select_atoms(spec.selections[spec.chain]) and the patches universe.select_atoms(spec.selections[spec.binders.patches]); the cutoff, the comparison, the cis threshold, the patches per binder, whether the distances are stored, and the labels are the spec’s BinderSpec; the topology is the project’s; and the minimum image is taken along every direction in a cube and along z only in a cylinder.

Added in version 0.7.0.

Parameters:
Returns:

The analysis, not yet run.

Return type:

typing.Self

Raises:

ValueError – If the spec has no binders, or if the selections pick fewer than two monomers or a number of patches that is not a positive multiple of the patches per binder.

Examples

>>> import MDAnalysis as mda
>>> import numpy as np
>>> from polyphys.tests.synthetic import RingCubBinders
>>> from polyphys.spec import (
...     BinderSpec, ProbeSpec, ProjectSpec)
>>> project = ProjectSpec(
...     parser=RingCubBinders, group='nucleoid', divisor=0.01,
...     crowder_attr='phi_bulk_c',
...     physical_attrs=('space', 'nmon', 'nhns'),
...     species_sizes={'Mon': 'dmon', 'Hns': 'dhns'},
...     tseries_properties=(
...         'nBoundTHnsPatch', 'nFreeTHnsPatch', 'nEngagedTHnsPatch',
...         'nFreeTHnsCore', 'nBridgeTHnsCore', 'nDangleTHnsCore',
...         'nCisTHnsCore', 'nTransTHnsCore', 'gyrTMon'))
>>> spec = ProbeSpec(
...     project, {'Mon': 'type 1', 'HnsPatch': 'type 2'}, 'Mon',
...     ('gyrT',), unwrap=True,
...     binders=BinderSpec('HnsPatch', 'HnsCore', cutoff=0.685,
...                        cis_threshold=3))
>>> universe = mda.Universe.empty(6, trajectory=True)
>>> universe.add_TopologyAttr('types', ['1'] * 4 + ['2'] * 2)
>>> analysis = BinderStatistics.from_spec(universe, spec)
>>> analysis.chain.n_atoms, analysis.patches.n_atoms
(4, 2)
>>> analysis.topology, analysis.periodic, analysis.cutoff
('ring', (True, True, True), 0.685)
classmethod get_supported_backends()[source]#

The backends run() accepts: 'serial', 'multiprocessing', and 'dask'.

Examples

>>> BinderStatistics.get_supported_backends()
('serial', 'multiprocessing', 'dask')
Return type:

tuple[str, ...]

property keys: tuple[str, ...]#

The keys of results, in the order save() writes them: the eight series of BINDER_SERIES, the loop-length histogram, and, with store_distances, the distances.

Examples

>>> import MDAnalysis as mda
>>> universe = mda.Universe.empty(4, trajectory=True)
>>> analysis = BinderStatistics(
...     universe.atoms[:2], universe.atoms[2:], cutoff=0.5,
...     topology='linear', cis_threshold=3)
>>> analysis.keys[-2:]
('n_pairs_trans', 'loop_length_histogram')
save(save_to, name)[source]#

Save each array as <name>-<series>.npy, under the research code’s names.

Added in version 0.7.0.

Parameters:
  • save_to (str | os.PathLike[str]) – An existing directory.

  • name (str) – The artifact’s name, <parser.name>-<parser.group> in the studies, such as 'N200...ens1-nucleoid'.

Returns:

The files written, in the order of keys: the eight series as <stem><patch_label> or <stem><binder_label> (nBoundTHnsPatch, nFreeTHnsPatch, nEngagedTHnsPatch, nFreeTHnsCore, nBridgeTHnsCore, nDangleTHnsCore, nCisTHnsCore, nTransTHnsCore with the default labels), the histogram as loopLengthHistT<chain_label>, and, with store_distances, the distances as distMatT<chain_label><patch_label>.

Return type:

list[pathlib.Path]

Raises:

RuntimeError – If run() has not been called.

Notes

The research code summed the loop-length histogram over the frames into loopLengthHist<chain_label>; the per-frame rows saved here sum to it along the frame axis.

Examples

>>> import tempfile
>>> import MDAnalysis as mda
>>> import numpy as np
>>> universe = mda.Universe.empty(4, trajectory=True)
>>> universe.atoms.positions = np.array(
...     [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0],
...      [0.0, 0.3, 0.0], [5.0, 5.0, 5.0]])
>>> analysis = BinderStatistics(
...     universe.atoms[:2], universe.atoms[2:], cutoff=0.5,
...     topology='linear', cis_threshold=3).run()
>>> with tempfile.TemporaryDirectory() as tmp:
...     paths = analysis.save(tmp, 'N2ens1-nucleoid')
...     names = [path.name for path in paths]
...     dangling = np.load(paths[5]).tolist()
>>> names[0]
'N2ens1-nucleoid-nBoundTHnsPatch.npy'
>>> names[5], dangling
('N2ens1-nucleoid-nDangleTHnsCore.npy', [1])
>>> names[8]
'N2ens1-nucleoid-loopLengthHistTMon.npy'
polyphys.probe.binders.DISTANCES_KEY = 'distances'#

The result key of the per-frame monomer-to-patch distance matrices, when they are stored.

polyphys.probe.binders.LOOP_KEY = 'loop_length_histogram'#

The result key of the per-frame loop-length histogram.