Source code for polyphys.analyze.clusters

"""
==========================================================
: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 find_direct_contacts( dist: npt.ArrayLike, cutoff: float, inclusive: bool = True, ) -> npt.NDArray[np.bool_]: """ Mark the pairs whose distance is within a cutoff as direct contacts. Parameters ---------- dist : array_like Center-to-center distances, shape ``(n_rows, n_cols)``, in the caller's length unit: a self-distance matrix from :func:`pair_distances`, or the distances between two groups, such as monomers along the rows and binder patches along the columns. cutoff : float The contact distance :math:`r_c`, in the same unit; positive. inclusive : bool, default True Count a pair at exactly the cutoff as a contact (``dist <= cutoff``) or not (``dist < cutoff``). Returns ------- numpy.ndarray ``direct_contacts``, the same shape as `dist`, ``bool``. For a self-distance matrix it is symmetric with a true diagonal. Raises ------ ValueError If `cutoff` is not positive or `dist` is not two-dimensional. Notes ----- This is the contact criterion of Sevick, Monson, and Ottino (1988), J. Chem. Phys. 88, 1198, https://doi.org/10.1063/1.454720, for which the clusters are the connected components of the resulting graph. The cutoff is a project constant: in the foci projects it is the sum of a large monomer's and a crowder's diameter, the largest separation at which no crowder fits between the two. Time and space are :math:`O(n_\\mathrm{rows} n_\\mathrm{cols})`. Examples -------- >>> import numpy as np >>> from polyphys.analyze.clusters import find_direct_contacts >>> dist = np.array([[0.0, 1.0, 2.5], ... [1.0, 0.0, 1.5], ... [2.5, 1.5, 0.0]]) >>> find_direct_contacts(dist, 1.5).astype(int) array([[1, 1, 0], [1, 1, 1], [0, 1, 1]]) >>> find_direct_contacts(dist, 1.5, inclusive=False).astype(int) array([[1, 1, 0], [1, 1, 0], [0, 0, 1]]) .. versionadded:: 0.6.0 """ if not cutoff > 0: raise ValueError(f'cutoff must be positive; got {cutoff}.') distances = np.asarray(dist, dtype=np.float64) if distances.ndim != 2: raise ValueError( f'dist must be a two-dimensional matrix; got {distances.ndim}' ' dimension(s).' ) if inclusive: return np.asarray(distances <= cutoff, dtype=np.bool_) return np.asarray(distances < cutoff, dtype=np.bool_)
[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 contact_matrix(direct_contacts: npt.ArrayLike) -> npt.NDArray[np.bool_]: """ Expand the direct contacts to the full contact matrix of the clusters. Parameters ---------- direct_contacts : array_like The direct-contact matrix :math:`A`, shape ``(n_particles, n_particles)``, boolean or 0/1, symmetric. Returns ------- numpy.ndarray The contact matrix :math:`C`, the same shape, ``bool``: ``[i, j]`` is true when ``i`` and ``j`` are in the same cluster. Symmetric, with a true diagonal; it is its own transitive closure, so ``(C @ C > 0) == C``. Raises ------ ValueError If `direct_contacts` is not a square symmetric matrix. Notes ----- :math:`C` is the transitive closure of :math:`A` in the sense of Sevick, Monson, and Ottino (1988): ``C[i, j]`` is true when some chain of direct contacts joins ``i`` to ``j``. It is built as ``labels[i] == labels[j]`` from :func:`cluster_labels`. Time is :math:`O(n^2)`; space is one ``(n, n)`` boolean array. Examples -------- >>> import numpy as np >>> from polyphys.analyze.clusters import contact_matrix >>> contacts = np.array([[1, 1, 0, 0], ... [1, 1, 1, 0], ... [0, 1, 1, 0], ... [0, 0, 0, 1]]) >>> contact_matrix(contacts).astype(int) array([[1, 1, 1, 0], [1, 1, 1, 0], [1, 1, 1, 0], [0, 0, 0, 1]]) .. versionadded:: 0.6.0 """ _, labels = cluster_labels(direct_contacts) return np.asarray(labels[:, None] == labels[None, :], dtype=np.bool_)
[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 enforce_single_patch_contact( direct_contacts: npt.ArrayLike, ) -> npt.NDArray[np.bool_]: """ Keep at most one monomer per patch: the lowest-index one. Parameters ---------- direct_contacts : array_like The monomer-patch contact matrix, shape ``(n_monomers, n_patches)``, boolean or 0/1: ``[i, j]`` true when monomer ``i`` touches patch ``j``. Returns ------- numpy.ndarray The same shape, ``bool``, with every column reduced to its first true entry; columns without a contact stay empty. Raises ------ ValueError If `direct_contacts` is not two-dimensional. Notes ----- A patch is a single binding site and can hold one monomer, but a distance cutoff occasionally marks two or three adjacent monomers as its contacts. The project rule keeps the one with the lowest backbone index and treats the rest as artifacts. Applying the rule twice changes nothing. Time and space are :math:`O(n_\\mathrm{monomers} n_\\mathrm{patches})`. Examples -------- Patch 0 touches monomers 1 and 2; only monomer 1 is kept. >>> import numpy as np >>> from polyphys.analyze.clusters import enforce_single_patch_contact >>> contacts = np.array([[0, 1], ... [1, 0], ... [1, 0]]) >>> enforce_single_patch_contact(contacts).astype(int) array([[0, 1], [1, 0], [0, 0]]) .. versionadded:: 0.6.0 """ contacts = _as_contacts(direct_contacts, 'direct_contacts') n_monomers = contacts.shape[0] first = np.argmax(contacts, axis=0) engaged = contacts.any(axis=0) rows = np.arange(n_monomers)[:, None] return np.asarray((rows == first[None, :]) & engaged[None, :], dtype=np.bool_)
[docs] def monomer_binder_contacts( direct_contacts: npt.ArrayLike, patches_per_binder: int, ) -> npt.NDArray[np.bool_]: """ Collapse the patches of each binder into one column. Parameters ---------- direct_contacts : array_like The monomer-patch contact matrix, shape ``(n_monomers, n_patches)``, boolean or 0/1, with the patches of binder ``k`` in columns ``k * patches_per_binder`` to ``(k + 1) * patches_per_binder - 1``. patches_per_binder : int The number of patches per binder; positive and dividing ``n_patches``. Returns ------- numpy.ndarray The monomer-binder contact matrix, shape ``(n_monomers, n_binders)``, ``bool``: ``[i, k]`` true when monomer ``i`` touches any patch of binder ``k``. Raises ------ ValueError If `direct_contacts` is not two-dimensional, or if `patches_per_binder` is not positive or does not divide the number of columns. Notes ----- Time and space are :math:`O(n_\\mathrm{monomers} n_\\mathrm{patches})`. Examples -------- >>> import numpy as np >>> from polyphys.analyze.clusters import monomer_binder_contacts >>> contacts = np.array([[1, 0, 0, 0], ... [0, 1, 0, 0], ... [0, 0, 0, 1]]) >>> monomer_binder_contacts(contacts, 2).astype(int) array([[1, 0], [1, 0], [0, 1]]) .. versionadded:: 0.6.0 """ contacts = _as_contacts(direct_contacts, 'direct_contacts') n_monomers, n_patches = contacts.shape if patches_per_binder < 1: raise ValueError( f'patches_per_binder must be positive; got {patches_per_binder}.' ) if n_patches % patches_per_binder != 0: raise ValueError( f'the number of columns, {n_patches}, must be a multiple of' f' patches_per_binder, {patches_per_binder}.' ) n_binders = n_patches // patches_per_binder grouped = contacts.reshape(n_monomers, n_binders, patches_per_binder) return np.asarray(grouped.any(axis=2), dtype=np.bool_)
[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] def binder_contacts( direct_contacts: npt.ArrayLike, topology: Topology, ) -> npt.NDArray[np.bool_]: """ Link binders that touch the same or neighboring monomers. Parameters ---------- direct_contacts : array_like The monomer-binder contact matrix, shape ``(n_monomers, n_binders)``, boolean or 0/1, with the monomers in backbone order along the rows. topology : {'linear', 'ring'} Whether the chain is open or closed; on a ring the first and last monomers are neighbors. Returns ------- numpy.ndarray The binder-binder direct-contact matrix, shape ``(n_binders, n_binders)``, ``bool``: ``[k, l]`` true when binders ``k`` and ``l`` touch the same monomer or two monomers adjacent along the backbone. Symmetric, with a true diagonal for every binder, bound or not, so :func:`count_clusters` sees every binder as a cluster of at least size 1. Raises ------ ValueError If `direct_contacts` is not two-dimensional or `topology` is invalid. Notes ----- With :math:`M` the monomer-binder matrix and :math:`N_i = M_i \\lor M_{i+1}` the matrix of the monomer pairs ``(i, i + 1)`` that are neighbors, the result is :math:`M^\\top M > 0 \\lor N^\\top N > 0` plus the identity: the first term links binders sharing a monomer, the second links binders on neighboring monomers. Time is :math:`O(n_\\mathrm{monomers} n_\\mathrm{binders}^2)` from the two products; space is :math:`O(n_\\mathrm{monomers} n_\\mathrm{binders} + n_\\mathrm{binders}^2)`. Examples -------- Binder 0 on monomer 0 and binder 1 on monomer 3 are linked on a ring of four monomers, where 0 and 3 are neighbors, but not on a linear chain: >>> import numpy as np >>> from polyphys.analyze.clusters import binder_contacts >>> contacts = np.array([[1, 0], ... [0, 0], ... [0, 0], ... [0, 1]]) >>> binder_contacts(contacts, 'ring').astype(int) array([[1, 1], [1, 1]]) >>> binder_contacts(contacts, 'linear').astype(int) array([[1, 0], [0, 1]]) .. versionadded:: 0.6.0 """ _check_topology(topology) contacts = _as_contacts(direct_contacts, 'direct_contacts') n_binders = contacts.shape[1] if topology == 'ring': neighbors = contacts | np.roll(contacts, -1, axis=0) else: neighbors = contacts[:-1] | contacts[1:] weights = contacts.astype(np.int64) shared = weights.T @ weights > 0 adjacent_weights = neighbors.astype(np.int64) adjacent = adjacent_weights.T @ adjacent_weights > 0 linked = shared | adjacent | np.eye(n_binders, dtype=np.bool_) return np.asarray(linked, 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