"""
==========================================================
:mod:`polyphys.analyze.clusters`
==========================================================
The :mod:`polyphys.analyze.clusters` module turns the positions of a group of
particles in one frame into contact and cluster statistics, and the contacts
between a polymer and two-patch binding proteins into binding statistics.
Every routine is a pure NumPy or SciPy kernel on one frame, except
:func:`threshold_sweep`, which recounts saved frames over a grid of cutoffs;
reading frames, choosing the particles, and accumulating over frames are
otherwise the caller's work.
Notation
========
``n_particles``
The number of particles in the group, :math:`n`.
``positions``
Their coordinates, shape ``(n_particles, n_dims)``, in the caller's length
unit; every length below is in that unit.
``dist``
The matrix of center-to-center distances, shape
``(n_particles, n_particles)``, symmetric with a zero diagonal.
``cutoff``
A length :math:`r_c`. Two particles are in *direct contact* when their
center-to-center distance is at most :math:`r_c` (``inclusive=True``) or
below it (``inclusive=False``); this is the contact criterion of Sevick,
Monson, and Ottino (1988).
``direct_contacts``
The boolean *direct-contact matrix* :math:`A`, ``A[i, j]`` true when
particles ``i`` and ``j`` are in direct contact. For a self-distance
matrix it is symmetric and its diagonal is true, since every particle is
at distance zero from itself. It is the adjacency matrix of the *contact
graph*, whose vertices are the particles and whose edges are the direct
contacts; ``n_contacts`` is its number of edges, :math:`E`.
*cluster*
A connected component of the contact graph: a maximal set of particles
joined by chains of direct contacts. Its *size* is its number of
particles, from 1 to ``n_particles``.
``contact_matrix``
The boolean *contact matrix* :math:`C`, ``C[i, j]`` true when ``i`` and
``j`` are in the same cluster: the transitive closure of :math:`A`, block
all-ones after sorting the particles by cluster.
*bonds*
The number of other particles a particle is in direct contact with: its
degree in the contact graph, from 0 to ``n_particles - 1``.
*genomic distance*
For two monomers of one polymer, the number of backbone bonds between them
along the chain: ``|i - j|`` on a linear chain, and the shorter way round,
``min(|i - j|, n_backbone - |i - j|)``, on a ring of ``n_backbone``
monomers.
*patch*, *binder*
A binder is a protein with two binding sites, its *patches*; binder ``k``
owns patches ``2k`` and ``2k + 1``. A binder is *free* when neither patch
touches a monomer, *dangling* when one does, and *bridging* when both do.
A bridge joins two monomers; it is *cis* when their genomic distance is at
most ``cis_threshold`` bonds and *trans* when it is larger.
Contents
========
Distances and contacts:
:func:`pair_distances` builds ``dist`` from ``positions``, with the minimum
image in the periodic directions of an orthogonal box;
:func:`find_direct_contacts` applies the cutoff.
Clusters:
:func:`cluster_labels` labels the connected components of the contact graph
with :func:`scipy.sparse.csgraph.connected_components`;
:func:`count_clusters` histograms their sizes; :func:`contact_matrix` expands
the labels to :math:`C`; :func:`count_bonds` histograms the degrees.
Genomic distances and pair separations:
:func:`genomic_distance` and :func:`foci_pair_info` measure distances along
the backbone; :func:`pair_distance_histograms` bins the time series of pair
separations on one shared grid, and :func:`pair_separation_density` turns the
counts into the probability density of the separation vector.
Binding:
:func:`enforce_single_patch_contact`, :func:`monomer_binder_contacts`,
:func:`split_binders`, and :func:`binder_contacts` reshape a monomer-patch
contact matrix; :func:`binding_statistics` counts free, dangling, bridging,
cis, and trans binders in one frame as a :class:`FrameBinding`,
:class:`BindingStats` accumulates frames and the loop-length histogram, and
:func:`threshold_sweep` recounts the saved distance matrices of a whole at
every cutoff and cis threshold of a grid, the research code's
choice-of-threshold sweep.
Conventions
===========
- A contact matrix is boolean. Integer 0/1 input is accepted everywhere and
converted; any nonzero entry counts as a contact.
- Cluster labels are integers ``0, ..., n_clusters - 1``; which cluster gets
which label is an implementation detail of SciPy, so compare partitions
(``labels[i] == labels[j]``), not label values.
- Size and degree histograms are indexed by the size or degree itself:
``count_clusters(A)[s]`` is the number of clusters of size ``s`` and has
length ``n_particles + 1`` with ``[0]`` always 0; ``count_bonds(A)[d]`` is
the number of particles with ``d`` bonds and has length ``n_particles``.
- Genomic distances are in bonds, never in monomers between.
- Contact cutoffs, cis thresholds, and bin ranges are project constants and
have no defaults here.
- Complexities are stated per call, for one frame, in ``n_particles``
(:math:`n`), ``n_contacts`` (:math:`E`), and the other sizes named in each
docstring.
References
==========
- E. M. Sevick, P. A. Monson, and J. M. Ottino, "Monte Carlo calculations of
cluster statistics in continuum models of composite morphology",
J. Chem. Phys. 88, 1198-1206 (1988). https://doi.org/10.1063/1.454720
- J. Hopcroft and R. Tarjan, "Algorithm 447: efficient algorithms for graph
manipulation", Commun. ACM 16, 372-378 (1973).
https://doi.org/10.1145/362248.362272
- SciPy, :func:`scipy.sparse.csgraph.connected_components`.
https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csgraph.connected_components.html
- M. Rubinstein and R. H. Colby, Polymer Physics (Oxford University Press,
2003), Chapter 2.
.. versionadded:: 0.6.0
"""
from dataclasses import dataclass, field
from typing import Literal, Sequence
import numpy as np
import numpy.typing as npt
import pandas as pd
from scipy.sparse import csr_array
from scipy.sparse.csgraph import connected_components
from .measurer import create_bin_edge_and_hist
__all__ = [
'BindingStats',
'FrameBinding',
'Topology',
'binder_contacts',
'binding_statistics',
'cluster_labels',
'contact_matrix',
'count_bonds',
'count_clusters',
'enforce_single_patch_contact',
'find_direct_contacts',
'foci_pair_info',
'genomic_distance',
'monomer_binder_contacts',
'pair_distance_histograms',
'pair_distances',
'pair_separation_density',
'split_binders',
'threshold_sweep',
]
Topology = Literal['linear', 'ring']
"""The polymer topologies the genomic distance is defined for."""
# The eight counts of a FrameBinding, in the order BindingStats.as_dict and
# threshold_sweep report them.
_BINDING_COUNTS = (
'n_patch_monomer_contacts', 'n_patches_engaged',
'n_patches_free', 'n_binders_free', 'n_binders_dangling',
'n_binders_bridging', 'n_pairs_cis', 'n_pairs_trans',
)
def _as_contacts(matrix: npt.ArrayLike, name: str) -> npt.NDArray[np.bool_]:
"""
Copy `matrix` to a two-dimensional boolean array.
Raises
------
ValueError
If `matrix` is not two-dimensional.
"""
contacts = np.asarray(matrix)
if contacts.ndim != 2:
raise ValueError(
f'{name} must be a two-dimensional matrix; got {contacts.ndim}'
' dimension(s).'
)
return contacts.astype(np.bool_, copy=False)
def _check_topology(topology: str) -> None:
"""Raise ``ValueError`` unless `topology` is ``'linear'`` or ``'ring'``."""
if topology not in ('linear', 'ring'):
raise ValueError(
f"topology must be 'linear' or 'ring'; got '{topology}'."
)
[docs]
def pair_distances(
positions: npt.ArrayLike,
box: npt.ArrayLike | None = None,
) -> npt.NDArray[np.float64]:
"""
Compute the matrix of center-to-center distances between all pairs.
Parameters
----------
positions : array_like
Coordinates of the particles, shape ``(n_particles, n_dims)``, in the
caller's length unit.
box : array_like, optional
Lengths of an orthogonal periodic box, shape ``(n_dims,)``, in the
same unit. A direction with length ``0`` or ``inf`` is not periodic.
With ``None``, no direction is periodic.
Returns
-------
numpy.ndarray
``dist``, shape ``(n_particles, n_particles)``, ``float64``: the
distance between particles ``i`` and ``j`` at ``[i, j]``; symmetric,
with a zero diagonal.
Raises
------
ValueError
If `positions` is not two-dimensional, if `box` has not one length
per dimension, or if a box length is negative or NaN.
Notes
-----
In a periodic direction of length :math:`L` the separation :math:`\\Delta`
is replaced by its minimum image, :math:`\\Delta - L\\,
\\mathrm{round}(\\Delta / L)`, which lies in :math:`[-L/2, L/2]`: the
distance to the nearest periodic image of the other particle. It is the
distance a contact criterion should use, provided the cutoff is below
:math:`L / 2`; for wrapped coordinates it is the only way to recover a
pair that straddles the boundary. Positions need not be wrapped.
Time is :math:`O(n^2 d)` for :math:`n` particles in :math:`d` dimensions.
Space is :math:`O(n^2)`: at most four ``(n, n)`` ``float64`` arrays at
once, the running sum of squares, the separation along one axis, and,
along a periodic axis, the temporaries of its minimum image. The
dimensions are accumulated one at a time, so no ``(d, n, n)`` temporary
is built.
Examples
--------
A 3-4-5 right triangle:
>>> import numpy as np
>>> from polyphys.analyze.clusters import pair_distances
>>> pair_distances([[0.0, 0.0], [3.0, 0.0], [3.0, 4.0]])
array([[0., 3., 5.],
[3., 0., 4.],
[5., 4., 0.]])
Two particles at ``x = 0.1`` and ``x = 9.9`` are ``0.2`` apart through
the boundary of a box of length ``10`` and ``9.8`` apart without it:
>>> positions = [[0.1, 0.0], [9.9, 0.0]]
>>> round(float(pair_distances(positions, box=[10.0, 0.0])[0, 1]), 10)
0.2
>>> round(float(pair_distances(positions)[0, 1]), 10)
9.8
.. versionadded:: 0.6.0
"""
pos = np.asarray(positions, dtype=np.float64)
if pos.ndim != 2:
raise ValueError(
'positions must have shape (n_particles, n_dims); got'
f' {pos.ndim} dimension(s).'
)
n_particles, n_dims = pos.shape
if box is None:
lengths = np.zeros(n_dims)
else:
lengths = np.asarray(box, dtype=np.float64)
if lengths.shape != (n_dims,):
raise ValueError(
f'box must have one length per dimension, shape ({n_dims},);'
f' got shape {lengths.shape}.'
)
if np.any(np.isnan(lengths)) or np.any(lengths < 0):
raise ValueError('box lengths must be non-negative numbers.')
dist_sq = np.zeros((n_particles, n_particles), dtype=np.float64)
for axis in range(n_dims):
delta = pos[:, axis, None] - pos[None, :, axis]
length = lengths[axis]
if 0 < length < np.inf:
delta -= length * np.round(delta / length)
dist_sq += delta * delta
return np.sqrt(dist_sq)
[docs]
def cluster_labels(
direct_contacts: npt.ArrayLike,
) -> tuple[int, npt.NDArray[np.int64]]:
"""
Label the clusters, the connected components of the contact graph.
Parameters
----------
direct_contacts : array_like
The direct-contact matrix :math:`A`, shape
``(n_particles, n_particles)``, boolean or 0/1, symmetric. The
diagonal is ignored.
Returns
-------
n_clusters : int
The number of clusters, from 0 (no particles) to ``n_particles``.
labels : numpy.ndarray
Shape ``(n_particles,)``, ``int64``: ``labels[i]`` is the cluster of
particle ``i``, in ``0, ..., n_clusters - 1``. Which cluster gets
which label is not specified; compare ``labels[i] == labels[j]``.
Raises
------
ValueError
If `direct_contacts` is not a square symmetric matrix.
Notes
-----
Two particles are in the same cluster when a chain of direct contacts
joins them, so the clusters are the connected components of the graph
with adjacency matrix :math:`A`. They are found with
:func:`scipy.sparse.csgraph.connected_components` (``directed=False``),
a depth-first search that runs in time and space proportional to
:math:`n + E` once the graph is sparse (Hopcroft and Tarjan, 1973,
Commun. ACM 16, 372, https://doi.org/10.1145/362248.362272). Building the
sparse graph from the dense matrix costs :math:`O(n^2)` time and
:math:`O(E)` space, so the call is :math:`O(n^2)` in all; the Python-level
merge of matrix columns it replaces was :math:`O(n^3)` and could stop
short of the closure.
Examples
--------
A path 0-1-2 and an isolated particle 3:
>>> import numpy as np
>>> from polyphys.analyze.clusters import cluster_labels
>>> contacts = np.array([[1, 1, 0, 0],
... [1, 1, 1, 0],
... [0, 1, 1, 0],
... [0, 0, 0, 1]])
>>> n_clusters, labels = cluster_labels(contacts)
>>> n_clusters
2
>>> bool(labels[0] == labels[2]), bool(labels[0] == labels[3])
(True, False)
.. versionadded:: 0.6.0
"""
contacts = _as_contacts(direct_contacts, 'direct_contacts')
n_particles = contacts.shape[0]
if contacts.shape != (n_particles, n_particles):
raise ValueError(
'direct_contacts must be square; got shape'
f' {contacts.shape}.'
)
if not np.array_equal(contacts, contacts.T):
raise ValueError('direct_contacts must be symmetric.')
if n_particles == 0:
return 0, np.zeros(0, dtype=np.int64)
n_clusters, labels = connected_components(
csr_array(contacts.astype(np.int8)),
directed=False,
return_labels=True,
)
return int(n_clusters), np.asarray(labels, dtype=np.int64)
[docs]
def count_clusters(direct_contacts: npt.ArrayLike) -> npt.NDArray[np.int64]:
"""
Histogram the cluster sizes of one frame.
Parameters
----------
direct_contacts : array_like
The direct-contact matrix :math:`A`, shape
``(n_particles, n_particles)``, boolean or 0/1, symmetric.
Returns
-------
numpy.ndarray
Shape ``(n_particles + 1,)``, ``int64``: ``[s]`` is the number of
clusters of size ``s``. ``[0]`` is always 0, since no cluster is
empty, and ``sum(s * hist[s])`` is ``n_particles``.
Raises
------
ValueError
If `direct_contacts` is not a square symmetric matrix.
Notes
-----
The sizes are the multiplicities of the labels from
:func:`cluster_labels`, counted with :func:`numpy.bincount` twice: once to
get each cluster's size, once to histogram the sizes. This replaces
reading the sizes off the eigenvalues of the contact matrix, which is
:math:`O(n^3)` and meaningful only when that matrix is exactly block
all-ones. Time is :math:`O(n^2)`, dominated by :func:`cluster_labels`;
space is :math:`O(n + E)`.
Examples
--------
A path 0-1-2 and an isolated particle 3 give one cluster of size 3 and
one of size 1:
>>> import numpy as np
>>> from polyphys.analyze.clusters import count_clusters
>>> contacts = np.array([[1, 1, 0, 0],
... [1, 1, 1, 0],
... [0, 1, 1, 0],
... [0, 0, 0, 1]])
>>> count_clusters(contacts)
array([0, 1, 0, 1, 0])
.. versionadded:: 0.6.0
"""
_, labels = cluster_labels(direct_contacts)
n_particles = labels.shape[0]
sizes = np.bincount(labels)
return np.bincount(sizes, minlength=n_particles + 1).astype(np.int64)
[docs]
def count_bonds(direct_contacts: npt.ArrayLike) -> npt.NDArray[np.int64]:
"""
Histogram the number of bonds, the direct contacts per particle.
Parameters
----------
direct_contacts : array_like
The direct-contact matrix :math:`A`, shape
``(n_particles, n_particles)``, boolean or 0/1, symmetric. A true
diagonal is allowed and does not count as a bond.
Returns
-------
numpy.ndarray
Shape ``(n_particles,)``, ``int64``: ``[d]`` is the number of
particles with ``d`` bonds, ``d`` from 0 to ``n_particles - 1``.
``sum(hist)`` is ``n_particles`` and ``sum(d * hist[d])`` is twice
the number of direct contacts.
Raises
------
ValueError
If `direct_contacts` is not a square symmetric matrix.
Notes
-----
A particle's bonds are its degree in the contact graph: its row sum
minus its diagonal entry. Time and space are :math:`O(n^2)`.
Examples
--------
A star: particle 0 touches 1, 2, and 3, which touch nothing else, so one
particle has three bonds and three have one.
>>> import numpy as np
>>> from polyphys.analyze.clusters import count_bonds
>>> star = np.array([[1, 1, 1, 1],
... [1, 1, 0, 0],
... [1, 0, 1, 0],
... [1, 0, 0, 1]])
>>> count_bonds(star)
array([0, 3, 0, 1])
.. versionadded:: 0.6.0
"""
contacts = _as_contacts(direct_contacts, 'direct_contacts')
n_particles = contacts.shape[0]
if contacts.shape != (n_particles, n_particles):
raise ValueError(
'direct_contacts must be square; got shape'
f' {contacts.shape}.'
)
if not np.array_equal(contacts, contacts.T):
raise ValueError('direct_contacts must be symmetric.')
degrees = contacts.sum(axis=1) - np.diagonal(contacts).astype(np.int64)
return np.bincount(degrees, minlength=n_particles).astype(np.int64)
[docs]
def genomic_distance(
atoms_a: npt.ArrayLike,
atoms_b: npt.ArrayLike,
topology: Topology,
n_backbone: int,
) -> npt.NDArray[np.int64]:
"""
Count the backbone bonds between paired monomers along the chain.
Parameters
----------
atoms_a, atoms_b : array_like
Backbone indices of the paired monomers, integers in
``0, ..., n_backbone - 1``, in any two shapes that broadcast
together.
topology : {'linear', 'ring'}
Whether the chain is open or closed.
n_backbone : int
The number of monomers along the backbone; positive.
Returns
-------
numpy.ndarray
The genomic distance of each pair, the broadcast shape of the inputs,
``int64``, in bonds: ``|a - b|`` on a linear chain and
``min(|a - b|, n_backbone - |a - b|)`` on a ring, the shorter way
round. The number of monomers between the pair is one less.
Raises
------
ValueError
If `topology` is not ``'linear'`` or ``'ring'``, if `n_backbone` is
not positive, or if an index is outside ``0, ..., n_backbone - 1``.
Notes
-----
Time and space are :math:`O(m)` for :math:`m` pairs.
Examples
--------
On a ring of 10 monomers, 0 and 9 are neighbors:
>>> from polyphys.analyze.clusters import genomic_distance
>>> genomic_distance([0, 1], [3, 9], 'linear', 10)
array([3, 8])
>>> genomic_distance([0, 1], [3, 9], 'ring', 10)
array([3, 2])
.. versionadded:: 0.6.0
"""
_check_topology(topology)
if n_backbone < 1:
raise ValueError(f'n_backbone must be positive; got {n_backbone}.')
a = np.asarray(atoms_a, dtype=np.int64)
b = np.asarray(atoms_b, dtype=np.int64)
for name, idx in (('atoms_a', a), ('atoms_b', b)):
if idx.size and (idx.min() < 0 or idx.max() >= n_backbone):
raise ValueError(
f'{name} must hold indices in 0, ..., {n_backbone - 1}.'
)
separation = np.abs(a - b)
if topology == 'ring':
separation = np.minimum(separation, n_backbone - separation)
return np.asarray(separation, dtype=np.int64)
[docs]
def foci_pair_info(
genomic_pos: npt.ArrayLike,
n_monomers: int,
topology: Topology,
) -> npt.NDArray[np.int64]:
"""
List every pair of foci with its genomic distance.
Parameters
----------
genomic_pos : array_like
Backbone indices of the foci, the tagged monomers, shape
``(n_foci,)``, integers in ``0, ..., n_monomers - 1``.
n_monomers : int
The number of monomers along the backbone, foci included.
topology : {'linear', 'ring'}
Whether the chain is open or closed.
Returns
-------
numpy.ndarray
Shape ``(n_pairs, 3)``, ``int64``, one row per pair in the order of
``numpy.triu_indices(n_foci, 1)``: the two backbone indices and their
genomic distance in bonds. ``n_pairs`` is ``n_foci (n_foci - 1) / 2``.
Raises
------
ValueError
As :func:`genomic_distance`, or if `genomic_pos` is not
one-dimensional.
Notes
-----
The row order matches the upper triangle of a foci distance matrix, so
``dist[np.triu_indices(n_foci, 1)]`` gives the separations in the same
order. Time and space are :math:`O(n_\\mathrm{foci}^2)`.
Examples
--------
Three foci on a ring of 10 monomers:
>>> from polyphys.analyze.clusters import foci_pair_info
>>> foci_pair_info([0, 4, 8], 10, 'ring')
array([[0, 4, 4],
[0, 8, 2],
[4, 8, 4]])
.. versionadded:: 0.6.0
"""
positions = np.asarray(genomic_pos, dtype=np.int64)
if positions.ndim != 1:
raise ValueError(
'genomic_pos must be one-dimensional; got'
f' {positions.ndim} dimension(s).'
)
first, second = np.triu_indices(positions.shape[0], 1)
pos_a = positions[first]
pos_b = positions[second]
distance = genomic_distance(pos_a, pos_b, topology, n_monomers)
return np.column_stack((pos_a, pos_b, distance)).astype(np.int64)
[docs]
def pair_distance_histograms(
distances: npt.ArrayLike,
bin_size: float,
r_max: float,
) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.float64]]:
"""
Histogram the separation time series of each pair on one shared grid.
Parameters
----------
distances : array_like
Pair separations over the frames, shape ``(n_pairs, n_frames)`` or
``(n_frames,)`` for one pair, in the caller's length unit;
non-negative and finite.
bin_size : float
The bin width :math:`\\Delta r`, positive.
r_max : float
The upper end of the grid, positive. The grid runs from 0 to the
first multiple of `bin_size` at or above `r_max`, so every pair,
whole, and ensemble shares the same bins; a range that is a whole
number of bins up to float64 round-off ends exactly at `r_max`, as
:func:`polyphys.analyze.measurer.create_bin_edge_and_hist` gives.
Returns
-------
counts : numpy.ndarray
Shape ``(n_pairs, n_bins)``, or ``(n_bins,)`` for a one-dimensional
input, ``int64``: the number of frames whose separation falls in each
bin. Each row sums to ``n_frames``.
edges : numpy.ndarray
Shape ``(n_bins + 1,)``, ``float64``: the bin edges, equally
spaced ``bin_size`` apart from 0. Bin ``k`` is
``[edges[k], edges[k + 1])``, except the last, which also includes
its upper edge, as
:func:`numpy.histogram` does.
Raises
------
ValueError
If `bin_size` or `r_max` is not positive, if a separation is
negative, NaN, or above the last edge, or if `distances` has more
than two dimensions.
Notes
-----
A separation above the grid raises rather than being dropped, because a
dropped frame would silently break the normalization of
:func:`pair_separation_density`. Choose `r_max` from the system, such as
the largest separation the box allows, not from the data: a grid set by
each whole's own maximum gives every whole a different number of bins,
and an average over wholes is then taken over different sets of wholes
in different bins.
Time is :math:`O(n_\\mathrm{pairs} n_\\mathrm{frames} \\log
n_\\mathrm{bins})`, from a binary search of the edges per frame; space is
:math:`O(n_\\mathrm{pairs} (n_\\mathrm{frames} + n_\\mathrm{bins}))`.
Examples
--------
>>> from polyphys.analyze.clusters import pair_distance_histograms
>>> counts, edges = pair_distance_histograms(
... [[0.5, 1.5, 1.5, 3.0], [2.0, 2.0, 2.0, 2.0]], bin_size=1.0,
... r_max=3.0)
>>> counts
array([[1, 2, 1],
[0, 0, 4]])
>>> edges
array([0., 1., 2., 3.])
.. versionadded:: 0.6.0
.. versionchanged:: 0.9.0
Count the bins with the round-off tolerance of
:func:`polyphys.analyze.measurer.create_bin_edge_and_hist`.
"""
if not bin_size > 0:
raise ValueError(f'bin_size must be positive; got {bin_size}.')
if not r_max > 0:
raise ValueError(f'r_max must be positive; got {r_max}.')
series = np.asarray(distances, dtype=np.float64)
if series.ndim > 2:
raise ValueError(
'distances must have shape (n_pairs, n_frames) or (n_frames,);'
f' got {series.ndim} dimensions.'
)
one_pair = series.ndim == 1
rows = series.reshape(1, -1) if one_pair else series
n_pairs, n_frames = rows.shape
# The bin count tolerates float64 round-off in r_max / bin_size, as
# every fixed-width grid of the package does, so a range of a whole
# number of bins ends exactly at r_max.
edges, _ = create_bin_edge_and_hist(bin_size, 0.0, r_max)
n_bins = edges.size - 1
if np.any(np.isnan(rows)) or np.any(rows < 0) or np.any(rows > edges[-1]):
raise ValueError(
f'distances must lie in [0, {edges[-1]}], the histogram grid.'
)
# Bin k holds edges[k] <= r < edges[k + 1]; a separation on the last edge
# goes into the last bin, as numpy.histogram does.
bins = np.searchsorted(edges, rows, side='right') - 1
bins = np.minimum(bins, n_bins - 1)
flat = bins + n_bins * np.arange(n_pairs)[:, None]
flat_counts = np.bincount(flat.ravel(), minlength=n_pairs * n_bins)
counts = flat_counts.reshape(n_pairs, n_bins).astype(np.int64)
if one_pair:
return counts[0], edges
return counts, edges
[docs]
def pair_separation_density(
counts: npt.ArrayLike,
edges: npt.ArrayLike,
) -> npt.NDArray[np.float64]:
"""
Estimate the probability density of a pair's separation vector.
Parameters
----------
counts : array_like
Histogram counts from :func:`pair_distance_histograms`, shape
``(..., n_bins)``, one row per pair; every row must have a positive
total.
edges : array_like
The bin edges, shape ``(n_bins + 1,)``, non-negative and strictly
increasing, in the caller's length unit.
Returns
-------
numpy.ndarray
:math:`\\bar P(r)`, the same shape as `counts`, ``float64``, in units
of one over the length unit cubed. For each row,
``sum(density * shell_volume)`` is 1.
Raises
------
ValueError
If `edges` is not a strictly increasing non-negative vector of length
``n_bins + 1``, or if a row of `counts` is all zero.
Notes
-----
Let :math:`\\vec R` be the separation vector of one pair of monomers and
:math:`P(\\vec R)` its probability density over the chain's
configurations, :math:`\\int P\\, d^3R = 1`. The scalar separation
:math:`R = |\\vec R|` has density :math:`P(R) = 4\\pi R^2 \\bar P(R)`,
where :math:`\\bar P(R)` is the average of :math:`P(\\vec R)` over the
directions of :math:`\\vec R`; the factor :math:`4\\pi R^2` is the
Jacobian of spherical coordinates, nothing else. With :math:`H_k` frames
out of :math:`N_f` in the shell between :math:`R_k` and :math:`R_{k+1}`,
whose volume is :math:`\\Delta V_k = \\tfrac{4\\pi}{3}(R_{k+1}^3 -
R_k^3)`,
.. math::
\\bar P_k = \\frac{H_k}{N_f\\, \\Delta V_k},
\\qquad \\sum_k \\bar P_k\\, \\Delta V_k = 1 .
:math:`-k_B T \\ln \\bar P(R)` is the free energy of the pair at
separation :math:`R`, up to a constant; for an ideal chain of :math:`n`
Kuhn segments of length :math:`b`, :math:`P(\\vec R)` is the Gaussian
:math:`(3 / 2\\pi n b^2)^{3/2} \\exp(-3R^2 / 2 n b^2)` (Rubinstein and
Colby, 2003, Chapter 2), a reference the estimate can be compared with
directly, since it carries no free constant. The estimate itself assumes
no chain model and no geometry: the accessible volume of a confinement
shapes :math:`\\bar P`, not its definition. The exact shell volume is
used rather than :math:`4\\pi R_c^2 \\Delta r` at the bin center, which
is 25% too small in the first bin. Time and space are
:math:`O(n_\\mathrm{pairs} n_\\mathrm{bins})`.
Examples
--------
Four frames all in the shell between 2 and 3: the density is one over
that shell's volume, :math:`\\tfrac{4\\pi}{3}(27 - 8)`.
>>> import numpy as np
>>> from polyphys.analyze.clusters import pair_separation_density
>>> density = pair_separation_density([0, 0, 4], [0.0, 1.0, 2.0, 3.0])
>>> np.round(density, 5)
array([0. , 0. , 0.01256])
>>> shells = 4 * np.pi / 3 * np.diff(np.array([0.0, 1.0, 2.0, 3.0])**3)
>>> float(np.sum(density * shells))
1.0
.. versionadded:: 0.6.0
"""
hist = np.asarray(counts, dtype=np.float64)
bounds = np.asarray(edges, dtype=np.float64)
if bounds.ndim != 1 or bounds.shape[0] != hist.shape[-1] + 1:
raise ValueError(
'edges must have length n_bins + 1 ='
f' {hist.shape[-1] + 1}; got shape {bounds.shape}.'
)
if bounds[0] < 0 or np.any(np.diff(bounds) <= 0):
raise ValueError(
'edges must be non-negative and strictly increasing.'
)
n_frames = hist.sum(axis=-1, keepdims=True)
if np.any(n_frames <= 0):
raise ValueError('every row of counts must have a positive total.')
shell_volume = 4.0 * np.pi / 3.0 * np.diff(bounds**3)
return np.asarray(hist / (n_frames * shell_volume), dtype=np.float64)
[docs]
def split_binders(
direct_contacts: npt.ArrayLike,
) -> tuple[npt.NDArray[np.bool_], npt.NDArray[np.bool_]]:
"""
Separate the dangling binders from the bridging ones.
Parameters
----------
direct_contacts : array_like
The monomer-binder contact matrix, shape ``(n_monomers, n_binders)``,
boolean or 0/1, as :func:`monomer_binder_contacts` returns it.
Returns
-------
dangling : numpy.ndarray
The same shape, ``bool``: the columns that touch exactly one monomer,
every other column cleared.
bridging : numpy.ndarray
The same shape, ``bool``: the columns that touch exactly two
monomers, every other column cleared.
Raises
------
ValueError
If `direct_contacts` is not two-dimensional.
Notes
-----
A binder touching no monomer is free and appears in neither output; one
touching three or more monomers, which a two-patch binder cannot do once
:func:`enforce_single_patch_contact` has been applied, appears in
neither either. Time and space are :math:`O(n_\\mathrm{monomers}
n_\\mathrm{binders})`.
Examples
--------
>>> import numpy as np
>>> from polyphys.analyze.clusters import split_binders
>>> contacts = np.array([[1, 1, 0],
... [0, 1, 0],
... [0, 0, 0]])
>>> dangling, bridging = split_binders(contacts)
>>> dangling.astype(int)
array([[1, 0, 0],
[0, 0, 0],
[0, 0, 0]])
>>> bridging.astype(int)
array([[0, 1, 0],
[0, 1, 0],
[0, 0, 0]])
.. versionadded:: 0.6.0
"""
contacts = _as_contacts(direct_contacts, 'direct_contacts')
n_monomers_bound = contacts.sum(axis=0)
dangling = contacts & (n_monomers_bound == 1)[None, :]
bridging = contacts & (n_monomers_bound == 2)[None, :]
return (np.asarray(dangling, dtype=np.bool_),
np.asarray(bridging, dtype=np.bool_))
[docs]
@dataclass(frozen=True, eq=False)
class FrameBinding:
"""
The binding statistics of two-patch binders in one frame.
Attributes
----------
n_patch_monomer_contacts : int
Direct contacts between patches and monomers, before the single-patch
rule; a patch touching two monomers contributes two.
n_patches_engaged : int
Patches touching at least one monomer.
n_patches_free : int
Patches touching none; ``n_patches_engaged + n_patches_free`` is the
number of patches.
n_binders_free : int
Binders with both patches free.
n_binders_dangling : int
Binders with exactly one patch engaged.
n_binders_bridging : int
Binders with both patches engaged. The three binder counts sum to the
number of binders.
n_pairs_cis : int
Distinct monomer pairs bridged at a genomic distance of at least 1 and
at most ``cis_threshold`` bonds.
n_pairs_trans : int
Distinct monomer pairs bridged at more than ``cis_threshold`` bonds.
bridged_pairs : numpy.ndarray
Shape ``(n_bridged_pairs, 3)``, ``int64``: for each distinct bridged
pair, the two monomer indices, lower first, and their genomic
distance in bonds. ``n_pairs_cis + n_pairs_trans`` is its number of
rows.
Notes
-----
The pair counts are per distinct monomer pair, so two binders bridging
the same pair count once, and a binder whose two patches hold the same
monomer is bridging but bridges no pair.
Examples
--------
>>> from polyphys.analyze.clusters import binding_statistics
>>> frame = binding_statistics([[1, 0], [0, 1]], 'linear',
... cis_threshold=1)
>>> frame.n_binders_bridging, frame.n_pairs_cis
(1, 1)
.. versionadded:: 0.6.0
"""
n_patch_monomer_contacts: int
n_patches_engaged: int
n_patches_free: int
n_binders_free: int
n_binders_dangling: int
n_binders_bridging: int
n_pairs_cis: int
n_pairs_trans: int
bridged_pairs: npt.NDArray[np.int64]
[docs]
def binding_statistics(
direct_contacts: npt.ArrayLike,
topology: Topology,
cis_threshold: int,
) -> FrameBinding:
"""
Count free, dangling, bridging, cis, and trans binders in one frame.
Parameters
----------
direct_contacts : array_like
The monomer-patch contact matrix, shape ``(n_monomers, n_patches)``,
boolean or 0/1, with the monomers in backbone order along the rows
and the two patches of binder ``k`` in columns ``2k`` and ``2k + 1``.
topology : {'linear', 'ring'}
Whether the chain is open or closed.
cis_threshold : int
The largest genomic distance, in bonds, of a cis bridge;
non-negative. A project constant.
Returns
-------
FrameBinding
The counts and the bridged pairs; see its attributes.
Raises
------
ValueError
If `direct_contacts` is not two-dimensional or has an odd number of
columns, if `topology` is invalid, or if `cis_threshold` is negative.
Notes
-----
The patch and binder counts use the contacts as given, so a patch
marked on two monomers still counts as one engaged patch and its binder
as one dangling or bridging binder. The bridged pairs use the contacts
after :func:`enforce_single_patch_contact`, so each bridging binder
joins exactly two monomers; the pairs are then made distinct, their
genomic distance is taken from :func:`genomic_distance`, and a pair of
distance 0 (both patches on one monomer) is dropped.
Time is :math:`O(n_\\mathrm{monomers} n_\\mathrm{patches} +
n_\\mathrm{binders} \\log n_\\mathrm{binders})`; space is
:math:`O(n_\\mathrm{monomers} n_\\mathrm{patches})`.
Examples
--------
A ring of six monomers and four binders. Binder 0 bridges monomers 0 and
2; binder 1 has patch 2 on monomers 3 and 4 (an artifact) and patch 3
free, so it dangles; binder 2 is free; binder 3 bridges monomers 5 and
0, neighbors on the ring. With ``cis_threshold=1`` the second bridge is
cis and the first, at 2 bonds, is trans.
>>> import numpy as np
>>> from polyphys.analyze.clusters import binding_statistics
>>> contacts = np.zeros((6, 8), dtype=int)
>>> contacts[0, 0] = contacts[2, 1] = 1
>>> contacts[3, 2] = contacts[4, 2] = 1
>>> contacts[5, 6] = contacts[0, 7] = 1
>>> frame = binding_statistics(contacts, 'ring', cis_threshold=1)
>>> (frame.n_patch_monomer_contacts, frame.n_patches_engaged,
... frame.n_patches_free)
(6, 5, 3)
>>> (frame.n_binders_free, frame.n_binders_dangling,
... frame.n_binders_bridging)
(1, 1, 2)
>>> frame.n_pairs_cis, frame.n_pairs_trans
(1, 1)
>>> frame.bridged_pairs
array([[0, 2, 2],
[0, 5, 1]])
.. versionadded:: 0.6.0
"""
_check_topology(topology)
if cis_threshold < 0:
raise ValueError(
f'cis_threshold must be non-negative; got {cis_threshold}.'
)
contacts = _as_contacts(direct_contacts, 'direct_contacts')
n_monomers, n_patches = contacts.shape
if n_patches % 2 != 0:
raise ValueError(
'direct_contacts must have two columns per binder; got'
f' {n_patches} columns.'
)
n_binders = n_patches // 2
per_patch = contacts.sum(axis=0)
engaged = per_patch > 0
n_patches_engaged = int(np.count_nonzero(engaged))
first_engaged = engaged[0::2]
second_engaged = engaged[1::2]
n_binders_free = int(np.count_nonzero(~first_engaged & ~second_engaged))
n_binders_bridging = int(
np.count_nonzero(first_engaged & second_engaged)
)
# Bridged pairs: one monomer per patch, then the two patches of each
# bridging binder.
single = enforce_single_patch_contact(contacts)
monomer_of_patch = np.argmax(single, axis=0)
bridging = first_engaged & second_engaged
pairs: npt.NDArray[np.int64] = np.column_stack(
(monomer_of_patch[0::2][bridging], monomer_of_patch[1::2][bridging])
)
pairs = np.sort(pairs, axis=1)
pairs = pairs[pairs[:, 0] != pairs[:, 1]]
pairs = np.unique(pairs, axis=0).reshape(-1, 2)
distance = genomic_distance(
pairs[:, 0], pairs[:, 1], topology, n_monomers
)
bridged_pairs = np.column_stack((pairs, distance)).astype(np.int64)
n_pairs_cis = int(np.count_nonzero(distance <= cis_threshold))
return FrameBinding(
n_patch_monomer_contacts=int(per_patch.sum()),
n_patches_engaged=n_patches_engaged,
n_patches_free=n_patches - n_patches_engaged,
n_binders_free=n_binders_free,
n_binders_dangling=n_binders - n_binders_free - n_binders_bridging,
n_binders_bridging=n_binders_bridging,
n_pairs_cis=n_pairs_cis,
n_pairs_trans=int(distance.shape[0]) - n_pairs_cis,
bridged_pairs=bridged_pairs,
)
[docs]
@dataclass
class BindingStats:
"""
Binding statistics accumulated over frames, with the loop-length
histogram.
Parameters
----------
n_monomers : int
The number of monomers along the backbone; positive.
topology : {'linear', 'ring'}
Whether the chain is open or closed.
cis_threshold : int
The largest genomic distance, in bonds, of a cis bridge;
non-negative.
Attributes
----------
frames : list of FrameBinding
The frames appended so far, in order.
loop_length_histogram : numpy.ndarray
``int64``: ``[d]`` is the number of distinct bridged pairs over all
frames at a genomic distance of ``d`` bonds. Its length is
``n_monomers`` on a linear chain, where the largest distance is
``n_monomers - 1``, and ``n_monomers // 2 + 1`` on a ring, where it
is ``n_monomers // 2``. ``[0]`` is always 0.
Notes
-----
Building the object costs :math:`O(n_\\mathrm{monomers})` space for the
histogram; each :meth:`append` costs :math:`O(n_\\mathrm{bridged\\
pairs})`.
Examples
--------
>>> import numpy as np
>>> from polyphys.analyze.clusters import BindingStats
>>> stats = BindingStats(n_monomers=4, topology='linear',
... cis_threshold=1)
>>> stats.update([[1, 0], [0, 1], [0, 0], [0, 0]])
>>> stats.update([[1, 0], [0, 0], [0, 0], [0, 1]])
>>> stats.n_frames
2
>>> stats.as_dict()['n_pairs_cis']
array([1, 0])
>>> stats.loop_length_histogram
array([0, 1, 0, 1])
.. versionadded:: 0.6.0
"""
n_monomers: int
topology: Topology
cis_threshold: int
frames: list[FrameBinding] = field(default_factory=list)
loop_length_histogram: npt.NDArray[np.int64] = field(init=False)
def __post_init__(self) -> None:
_check_topology(self.topology)
if self.n_monomers < 1:
raise ValueError(
f'n_monomers must be positive; got {self.n_monomers}.'
)
if self.cis_threshold < 0:
raise ValueError(
f'cis_threshold must be non-negative; got'
f' {self.cis_threshold}.'
)
if self.topology == 'ring':
n_lengths = self.n_monomers // 2 + 1
else:
n_lengths = self.n_monomers
self.loop_length_histogram = np.zeros(n_lengths, dtype=np.int64)
@property
def n_frames(self) -> int:
"""The number of frames appended so far."""
return len(self.frames)
[docs]
def append(self, frame: FrameBinding) -> None:
"""
Add one frame's statistics and its bridged pairs to the histogram.
Parameters
----------
frame : FrameBinding
As :func:`binding_statistics` returns it, computed with this
object's `topology` and `cis_threshold` for a chain of
`n_monomers`.
Raises
------
ValueError
If a bridged pair's genomic distance does not fit the histogram,
which means the frame came from a longer chain or another
topology.
"""
distance = frame.bridged_pairs[:, 2]
if distance.size and distance.max() >= self.loop_length_histogram.size:
raise ValueError(
'a bridged pair has a genomic distance beyond the chain;'
' the frame does not match n_monomers and topology.'
)
np.add.at(self.loop_length_histogram, distance, 1)
self.frames.append(frame)
[docs]
def update(self, direct_contacts: npt.ArrayLike) -> None:
"""
Compute one frame's statistics and append them.
Parameters
----------
direct_contacts : array_like
The monomer-patch contact matrix of the frame, shape
``(n_monomers, n_patches)``, as :func:`binding_statistics` takes
it.
Raises
------
ValueError
As :func:`binding_statistics`, or if the matrix has not
`n_monomers` rows.
"""
contacts = _as_contacts(direct_contacts, 'direct_contacts')
if contacts.shape[0] != self.n_monomers:
raise ValueError(
f'direct_contacts must have n_monomers = {self.n_monomers}'
f' rows; got {contacts.shape[0]}.'
)
self.append(
binding_statistics(contacts, self.topology, self.cis_threshold)
)
[docs]
def as_dict(self) -> dict[str, npt.NDArray[np.int64]]:
"""
Return the eight counts as time series.
Returns
-------
dict of numpy.ndarray
One ``int64`` array of shape ``(n_frames,)`` per count, keyed by
the :class:`FrameBinding` attribute name; `bridged_pairs` is not
included.
"""
return {
name: np.array(
[getattr(frame, name) for frame in self.frames],
dtype=np.int64,
)
for name in _BINDING_COUNTS
}
[docs]
def threshold_sweep(
distances: npt.ArrayLike,
cutoffs: Sequence[float] | npt.ArrayLike,
cis_thresholds: Sequence[int],
topology: Topology,
*,
inclusive: bool,
) -> tuple[pd.DataFrame, npt.NDArray[np.float64]]:
"""
Recount the binding statistics of saved distance matrices at every
cutoff and cis threshold of a grid.
Parameters
----------
distances : array_like
The monomer-to-patch distance matrices of one whole, shape
``(n_frames, n_monomers, n_patches)``, in the caller's length unit,
with the monomers in backbone order along the second axis and the
two patches of binder ``k`` at ``2k`` and ``2k + 1`` along the
third; the ``distances`` that
:class:`~polyphys.probe.binders.BinderStatistics` stores.
cutoffs : sequence of float
The contact distances :math:`r_c` to sweep, in the same unit, each
positive; non-empty. Swept in the order given.
cis_thresholds : sequence of int
The largest genomic distances, in bonds, of a cis bridge to sweep;
each non-negative, non-empty. Swept in the order given, inside each
cutoff.
topology : {'linear', 'ring'}
Whether the chain is open or closed.
inclusive : bool
Count a pair at exactly the cutoff as a contact (``dist <= cutoff``)
or not (``dist < cutoff``), as :func:`find_direct_contacts`. Keyword
only, with no default, because the comparison decides whether the
sweep reproduces stored counts: a sweep agrees with the series that
:class:`~polyphys.probe.binders.BinderStatistics` saved only at the
spec's cutoff, cis threshold, and comparison.
Returns
-------
counts : pandas.DataFrame
One row per ``(cutoff, cis_threshold)`` pair, cutoffs outer and cis
thresholds inner, in the order given, with no row repeated. Columns:
``cutoff`` (float64), ``cis_threshold`` (int64), and the eight
counts of :class:`FrameBinding`, each the mean over the frames
(float64), under the attribute names ``n_patch_monomer_contacts``,
``n_patches_engaged``, ``n_patches_free``, ``n_binders_free``,
``n_binders_dangling``, ``n_binders_bridging``, ``n_pairs_cis``, and
``n_pairs_trans``.
loop_length_histogram : numpy.ndarray
Shape ``(n_rows, n_lengths)``, ``float64``, one row per row of
`counts`: ``[k, d]`` is the mean over the frames of the number of
distinct bridged pairs at a genomic distance of ``d`` bonds at the
cutoff of row ``k``. ``n_lengths`` is ``n_monomers`` on a linear
chain and ``n_monomers // 2 + 1`` on a ring, as
:class:`BindingStats`; ``[:, 0]`` is always 0. The cis threshold
does not enter the histogram, so the rows of one cutoff are equal.
Raises
------
ValueError
If `distances` is not three-dimensional or has no frames, if
`cutoffs` or `cis_thresholds` is empty, if a cutoff is not positive
or a cis threshold is negative or not a whole number, if the number
of patches is odd, or
if `topology` is invalid.
Notes
-----
This is the research code's choice-of-threshold sweep on the saved
``distMatTMonHnsPatch`` matrices, with its two tables, the
frame-averaged counts and the frame-averaged loop-length histogram,
returned side by side rather than written with repeated rows. The
research sweep compared strictly, while the H-NS study specs count with
``inclusive=True`` at 0.685; the strict sweep's row at 0.685 therefore
omits the pairs at exactly the cutoff and does not match the stored
series. The research grid, ``numpy.arange(0.535, 0.685 + 0.01, 0.01)``,
also ran one step past its end to 0.695; build a grid with a count,
``0.535 + 0.01 * numpy.arange(16)``, to stop at 0.685.
Every count and the histogram are means over the frames, which treats
the frames as exchangeable; they are not uncertainties. An error bar on
a swept count needs the per-frame series of :class:`BindingStats` and
an autocorrelation-aware estimate such as
:func:`polyphys.analyze.stats.block_average`.
The contacts and the bridged pairs of a frame depend on the cutoff only;
the cis threshold splits the bridged pairs into cis and trans. Each
frame is therefore counted once per cutoff, with
:func:`find_direct_contacts` and :func:`binding_statistics`, and its
bridged pairs are split once per cis threshold. With :math:`n_c`
cutoffs, :math:`n_t` cis thresholds, :math:`n_f` frames,
:math:`N_m` monomers, :math:`N_p` patches, and :math:`N_b = N_p / 2`
binders, time is :math:`O(n_c n_f (N_m N_p + N_b \\log N_b) + n_c n_t
n_f N_b)` and space, beyond the input, is :math:`O(N_m N_p + n_c n_t
n_\\mathrm{lengths})`.
Examples
--------
A linear chain of three monomers and one binder, in two frames. In the
first frame, patch 0 sits 0.5 from monomer 0 and patch 1 sits 0.6 from
monomer 2; in the second, patch 1 is far from every monomer. Below 0.6
the binder dangles in both frames; at 0.65 it bridges monomers 0 and 2,
two bonds apart, in the first frame, a trans bridge for a cis threshold
of 1.
>>> import numpy as np
>>> from polyphys.analyze.clusters import threshold_sweep
>>> distances = np.full((2, 3, 2), 2.0)
>>> distances[0, 0, 0] = distances[1, 0, 0] = 0.5
>>> distances[0, 2, 1] = 0.6
>>> counts, loops = threshold_sweep(
... distances, [0.55, 0.65], [1], 'linear', inclusive=True)
>>> counts[['cutoff', 'n_binders_dangling', 'n_binders_bridging',
... 'n_pairs_trans']]
cutoff n_binders_dangling n_binders_bridging n_pairs_trans
0 0.55 1.0 0.0 0.0
1 0.65 0.5 0.5 0.5
>>> loops
array([[0. , 0. , 0. ],
[0. , 0. , 0.5]])
.. versionadded:: 0.7.0
.. versionchanged:: 0.9.0
Reject a cis threshold that is not a whole number instead of
truncating it.
"""
_check_topology(topology)
matrices = np.asarray(distances, dtype=np.float64)
if matrices.ndim != 3:
raise ValueError(
'distances must have shape (n_frames, n_monomers, n_patches);'
f' got {matrices.ndim} dimension(s).'
)
n_frames, n_monomers, n_patches = matrices.shape
if n_frames == 0:
raise ValueError('distances must hold at least one frame.')
if n_patches % 2 != 0:
raise ValueError(
'distances must have two patches per binder; got'
f' {n_patches} patches.'
)
cutoff_grid = np.asarray(cutoffs, dtype=np.float64).reshape(-1)
if cutoff_grid.size == 0:
raise ValueError('cutoffs must not be empty.')
if not np.all(cutoff_grid > 0):
raise ValueError(
f'every cutoff must be positive; got {cutoff_grid.tolist()}.'
)
cis_values = np.asarray(cis_thresholds).reshape(-1)
if cis_values.size == 0:
raise ValueError('cis_thresholds must not be empty.')
if not np.all(np.mod(cis_values, 1) == 0):
raise ValueError(
'every cis threshold must be a whole number of bonds; got'
f' {cis_values.tolist()}.'
)
cis_grid = cis_values.astype(np.int64)
if not np.all(cis_grid >= 0):
raise ValueError(
'every cis threshold must be non-negative; got'
f' {cis_grid.tolist()}.'
)
if topology == 'ring':
n_lengths = n_monomers // 2 + 1
else:
n_lengths = n_monomers
n_rows = cutoff_grid.size * cis_grid.size
means = np.zeros((n_rows, len(_BINDING_COUNTS)), dtype=np.float64)
histogram = np.zeros((n_rows, n_lengths), dtype=np.float64)
# The six counts that do not depend on the cis threshold, then the
# cis and trans pair counts, in the order of _BINDING_COUNTS.
n_fixed = len(_BINDING_COUNTS) - 2
for i, cutoff in enumerate(cutoff_grid):
fixed = np.zeros(n_fixed, dtype=np.int64)
n_cis = np.zeros(cis_grid.size, dtype=np.int64)
n_pairs = 0
loops = np.zeros(n_lengths, dtype=np.int64)
for matrix in matrices:
contacts = find_direct_contacts(matrix, cutoff, inclusive)
# Any cis threshold gives the same contacts and bridged pairs;
# 0 makes every pair trans, and the split is redone below.
frame = binding_statistics(contacts, topology, 0)
fixed += [getattr(frame, name)
for name in _BINDING_COUNTS[:n_fixed]]
distance = frame.bridged_pairs[:, 2]
n_pairs += distance.size
n_cis += np.count_nonzero(
distance[None, :] <= cis_grid[:, None], axis=1)
loops += np.bincount(distance, minlength=n_lengths)
rows = slice(i * cis_grid.size, (i + 1) * cis_grid.size)
means[rows, :n_fixed] = fixed / n_frames
means[rows, n_fixed] = n_cis / n_frames
means[rows, n_fixed + 1] = (n_pairs - n_cis) / n_frames
histogram[rows] = loops / n_frames
counts = pd.DataFrame(means, columns=list(_BINDING_COUNTS))
counts.insert(0, 'cis_threshold', np.tile(cis_grid, cutoff_grid.size))
counts.insert(0, 'cutoff', np.repeat(cutoff_grid, cis_grid.size))
return counts, histogram