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#
BinderStatistics, the per-frame binding analysis.
Dependencies#
Python standard library: math, pathlib, typing.
MDAnalysis 2.8 or later, through the
mdaextra:AnalysisBaseandResultsGroup.polyphys.analyze.clusters:find_direct_contacts(),binding_statistics(), andBindingStats.polyphys.probe.core:_ProbeAnalysis, the base whoseruncloses the pool of themultiprocessingbackend, and_compute_part, which computes each part of a split run on its own copy of the analysis.
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
The result key of the per-frame loop-length histogram. |
|
The result key of the per-frame monomer-to-patch distance matrices, when they are stored. |
Classes
|
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._ProbeAnalysisThe 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, whichUniverse.select_atomsgives.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; only2is accepted, whichbinding_statistics()counts.periodic (
tuple[bool,bool,bool]) – Whether the minimum image is taken alongx,y, andz, with the box lengths of each frame. The research probe took none;from_spec()sets every direction in a cube andzonly in a cylinder.store_distances (
bool) – Whether the monomer-to-patch distance matrix of every frame is kept inresultsand written bysave().chain_label (
str) – The species labels that name the filessave()writes;'Mon','HnsPatch', and'HnsCore'by default, the H-NS studies’ names.patch_label (
str) – The species labels that name the filessave()writes;'Mon','HnsPatch', and'HnsCore'by default, the H-NS studies’ names.binder_label (
str) – The species labels that name the filessave()writes;'Mon','HnsPatch', and'HnsCore'by default, the H-NS studies’ names.verbose (
bool) – Whether to show a progress bar duringrun().
- 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 (
tupleofbool) – 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 + 1on a ring,n_monomerson a linear chain, asBindingStatssizes it.results (
Results) – Afterrun(): one int64 array of shape(n_frames,)per attribute ofFrameBindinginBINDER_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 framet, with column 0 always 0; and, with store_distances,'distances', float64 of shape(n_frames, n_monomers, n_patches).n_frames (
int) – Afterrun(), the number of frames analyzed, fromAnalysisBase.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 not2; if periodic is not three booleans; or if a label is empty. Duringrun(), 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 withbinding_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:
_prepareallocates the arrays for the frames of the run,_single_framewrites the current frame’s row, and_concludedoes nothing. The class is marked parallelizable, withserial,multiprocessing, anddaskbackends; each worker fills the arrays of its own frames, which_get_aggregatorconcatenates along the frame axis (ResultsGroup.ndarray_hstackfor the eight series,ResultsGroup.ndarray_vstackfor 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
xin a box of length 10, a patch atx = 9.8touches 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 patchesuniverse.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’sBinderSpec; the topology is the project’s; and the minimum image is taken along every direction in a cube and alongzonly in a cylinder.Added in version 0.7.0.
- Parameters:
universe (
MDAnalysis.core.universe.Universe) – The trajectory, asmake_universe()opens it.spec (
polyphys.spec.ProbeSpec) – The study’s probe spec, with binders set.verbose (
bool) – Whether to show a progress bar duringrun().
- Returns:
The analysis, not yet run.
- Return type:
- 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')
- property keys: tuple[str, ...]#
The keys of
results, in the ordersave()writes them: the eight series ofBINDER_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,nTransTHnsCorewith the default labels), the histogram asloopLengthHistT<chain_label>, and, with store_distances, the distances asdistMatT<chain_label><patch_label>.- Return type:
- 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.