polyphys.analyze.clusters#
polyphys.analyze.clusters#
The 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
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_particlesThe number of particles in the group, \(n\).
positionsTheir coordinates, shape
(n_particles, n_dims), in the caller’s length unit; every length below is in that unit.distThe matrix of center-to-center distances, shape
(n_particles, n_particles), symmetric with a zero diagonal.cutoffA length \(r_c\). Two particles are in direct contact when their center-to-center distance is at most \(r_c\) (
inclusive=True) or below it (inclusive=False); this is the contact criterion of Sevick, Monson, and Ottino (1988).direct_contactsThe boolean direct-contact matrix \(A\),
A[i, j]true when particlesiandjare 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_contactsis its number of edges, \(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_matrixThe boolean contact matrix \(C\),
C[i, j]true wheniandjare in the same cluster: the transitive closure of \(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 ofn_backbonemonomers.- patch, binder
A binder is a protein with two binding sites, its patches; binder
kowns patches2kand2k + 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 mostcis_thresholdbonds and trans when it is larger.
Contents#
Distances and contacts:
pair_distances() builds dist from positions, with the minimum
image in the periodic directions of an orthogonal box;
find_direct_contacts() applies the cutoff.
Clusters:
cluster_labels() labels the connected components of the contact graph
with scipy.sparse.csgraph.connected_components();
count_clusters() histograms their sizes; contact_matrix() expands
the labels to \(C\); count_bonds() histograms the degrees.
Genomic distances and pair separations:
genomic_distance() and foci_pair_info() measure distances along
the backbone; pair_distance_histograms() bins the time series of pair
separations on one shared grid, and pair_separation_density() turns the
counts into the probability density of the separation vector.
Binding:
enforce_single_patch_contact(), monomer_binder_contacts(),
split_binders(), and binder_contacts() reshape a monomer-patch
contact matrix; binding_statistics() counts free, dangling, bridging,
cis, and trans binders in one frame as a FrameBinding,
BindingStats accumulates frames and the loop-length histogram, and
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 sizesand has lengthn_particles + 1with[0]always 0;count_bonds(A)[d]is the number of particles withdbonds and has lengthn_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(\(n\)),n_contacts(\(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,
scipy.sparse.csgraph.connected_components(). https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csgraph.connected_components.htmlM. Rubinstein and R. H. Colby, Polymer Physics (Oxford University Press, 2003), Chapter 2.
Added in version 0.6.0.
Module Attributes
The polymer topologies the genomic distance is defined for. |
Functions
|
Link binders that touch the same or neighboring monomers. |
|
Count free, dangling, bridging, cis, and trans binders in one frame. |
|
Label the clusters, the connected components of the contact graph. |
|
Expand the direct contacts to the full contact matrix of the clusters. |
|
Histogram the number of bonds, the direct contacts per particle. |
|
Histogram the cluster sizes of one frame. |
|
Keep at most one monomer per patch: the lowest-index one. |
|
Mark the pairs whose distance is within a cutoff as direct contacts. |
|
List every pair of foci with its genomic distance. |
|
Count the backbone bonds between paired monomers along the chain. |
|
Collapse the patches of each binder into one column. |
|
Histogram the separation time series of each pair on one shared grid. |
|
Compute the matrix of center-to-center distances between all pairs. |
|
Estimate the probability density of a pair's separation vector. |
|
Separate the dangling binders from the bridging ones. |
|
Recount the binding statistics of saved distance matrices at every cutoff and cis threshold of a grid. |
Classes
|
Binding statistics accumulated over frames, with the loop-length histogram. |
|
The binding statistics of two-patch binders in one frame. |
- class polyphys.analyze.clusters.BindingStats(n_monomers, topology, cis_threshold, frames=list())[source]#
Bases:
objectBinding statistics accumulated over frames, with the loop-length histogram.
- Parameters:
n_monomers (
int) – The number of monomers along the backbone; positive.topology (
typing.Literal['linear','ring']) – Whether the chain is open or closed.cis_threshold (
int) – The largest genomic distance, in bonds, of a cis bridge; non-negative.frames (list[FrameBinding])
- Variables:
frames (
listofFrameBinding) – 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 ofdbonds. Its length isn_monomerson a linear chain, where the largest distance isn_monomers - 1, andn_monomers // 2 + 1on a ring, where it isn_monomers // 2.[0]is always 0.
Notes
Building the object costs \(O(n_\mathrm{monomers})\) space for the histogram; each
append()costs \(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])
Added in version 0.6.0.
- append(frame)[source]#
Add one frame’s statistics and its bridged pairs to the histogram.
- Parameters:
frame (
polyphys.analyze.clusters.FrameBinding) – Asbinding_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.
- Return type:
- as_dict()[source]#
Return the eight counts as time series.
- Returns:
One
int64array of shape(n_frames,)per count, keyed by theFrameBindingattribute name; bridged_pairs is not included.- Return type:
- loop_length_histogram: numpy.typing.NDArray[numpy.int64]#
- update(direct_contacts)[source]#
Compute one frame’s statistics and append them.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The monomer-patch contact matrix of the frame, shape(n_monomers, n_patches), asbinding_statistics()takes it.- Raises:
ValueError – As
binding_statistics(), or if the matrix has not n_monomers rows.- Return type:
- class polyphys.analyze.clusters.FrameBinding(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, bridged_pairs)[source]#
Bases:
objectThe binding statistics of two-patch binders in one frame.
- Variables:
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_freeis 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 mostcis_thresholdbonds.n_pairs_trans (
int) – Distinct monomer pairs bridged at more thancis_thresholdbonds.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_transis its number of rows.
- Parameters:
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)
Added in version 0.6.0.
- bridged_pairs: numpy.typing.NDArray[numpy.int64]#
- polyphys.analyze.clusters.Topology#
The polymer topologies the genomic distance is defined for.
alias of
Literal[‘linear’, ‘ring’]
- polyphys.analyze.clusters.binder_contacts(direct_contacts, topology)[source]#
Link binders that touch the same or neighboring monomers.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The monomer-binder contact matrix, shape(n_monomers, n_binders), boolean or 0/1, with the monomers in backbone order along the rows.topology (
typing.Literal['linear','ring']) – Whether the chain is open or closed; on a ring the first and last monomers are neighbors.
- Returns:
The binder-binder direct-contact matrix, shape
(n_binders, n_binders),bool:[k, l]true when binderskandltouch the same monomer or two monomers adjacent along the backbone. Symmetric, with a true diagonal for every binder, bound or not, socount_clusters()sees every binder as a cluster of at least size 1.- Return type:
- Raises:
ValueError – If direct_contacts is not two-dimensional or topology is invalid.
Notes
With \(M\) the monomer-binder matrix and \(N_i = M_i \lor M_{i+1}\) the matrix of the monomer pairs
(i, i + 1)that are neighbors, the result is \(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 \(O(n_\mathrm{monomers} n_\mathrm{binders}^2)\) from the two products; space is \(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]])
Added in version 0.6.0.
- polyphys.analyze.clusters.binding_statistics(direct_contacts, topology, cis_threshold)[source]#
Count free, dangling, bridging, cis, and trans binders in one frame.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – 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 binderkin columns2kand2k + 1.topology (
typing.Literal['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:
The counts and the bridged pairs; see its attributes.
- Return type:
- 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
enforce_single_patch_contact(), so each bridging binder joins exactly two monomers; the pairs are then made distinct, their genomic distance is taken fromgenomic_distance(), and a pair of distance 0 (both patches on one monomer) is dropped.Time is \(O(n_\mathrm{monomers} n_\mathrm{patches} + n_\mathrm{binders} \log n_\mathrm{binders})\); space is \(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=1the 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]])
Added in version 0.6.0.
- polyphys.analyze.clusters.cluster_labels(direct_contacts)[source]#
Label the clusters, the connected components of the contact graph.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The direct-contact matrix \(A\), shape(n_particles, n_particles), boolean or 0/1, symmetric. The diagonal is ignored.- Return type:
- Returns:
n_clusters (
int) – The number of clusters, from 0 (no particles) ton_particles.labels (
numpy.ndarray) – Shape(n_particles,),int64:labels[i]is the cluster of particlei, in0, ..., n_clusters - 1. Which cluster gets which label is not specified; comparelabels[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 \(A\). They are found with
scipy.sparse.csgraph.connected_components()(directed=False), a depth-first search that runs in time and space proportional to \(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 \(O(n^2)\) time and \(O(E)\) space, so the call is \(O(n^2)\) in all; the Python-level merge of matrix columns it replaces was \(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)
Added in version 0.6.0.
- polyphys.analyze.clusters.contact_matrix(direct_contacts)[source]#
Expand the direct contacts to the full contact matrix of the clusters.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The direct-contact matrix \(A\), shape(n_particles, n_particles), boolean or 0/1, symmetric.- Returns:
The contact matrix \(C\), the same shape,
bool:[i, j]is true wheniandjare in the same cluster. Symmetric, with a true diagonal; it is its own transitive closure, so(C @ C > 0) == C.- Return type:
- Raises:
ValueError – If direct_contacts is not a square symmetric matrix.
Notes
\(C\) is the transitive closure of \(A\) in the sense of Sevick, Monson, and Ottino (1988):
C[i, j]is true when some chain of direct contacts joinsitoj. It is built aslabels[i] == labels[j]fromcluster_labels(). Time is \(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]])
Added in version 0.6.0.
- polyphys.analyze.clusters.count_bonds(direct_contacts)[source]#
Histogram the number of bonds, the direct contacts per particle.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The direct-contact matrix \(A\), shape(n_particles, n_particles), boolean or 0/1, symmetric. A true diagonal is allowed and does not count as a bond.- Returns:
Shape
(n_particles,),int64:[d]is the number of particles withdbonds,dfrom 0 ton_particles - 1.sum(hist)isn_particlesandsum(d * hist[d])is twice the number of direct contacts.- Return type:
- 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 \(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])
Added in version 0.6.0.
- polyphys.analyze.clusters.count_clusters(direct_contacts)[source]#
Histogram the cluster sizes of one frame.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The direct-contact matrix \(A\), shape(n_particles, n_particles), boolean or 0/1, symmetric.- Returns:
Shape
(n_particles + 1,),int64:[s]is the number of clusters of sizes.[0]is always 0, since no cluster is empty, andsum(s * hist[s])isn_particles.- Return type:
- Raises:
ValueError – If direct_contacts is not a square symmetric matrix.
Notes
The sizes are the multiplicities of the labels from
cluster_labels(), counted withnumpy.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 \(O(n^3)\) and meaningful only when that matrix is exactly block all-ones. Time is \(O(n^2)\), dominated bycluster_labels(); space is \(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])
Added in version 0.6.0.
- polyphys.analyze.clusters.enforce_single_patch_contact(direct_contacts)[source]#
Keep at most one monomer per patch: the lowest-index one.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The monomer-patch contact matrix, shape(n_monomers, n_patches), boolean or 0/1:[i, j]true when monomeritouches patchj.- Returns:
The same shape,
bool, with every column reduced to its first true entry; columns without a contact stay empty.- Return type:
- 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 \(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]])
Added in version 0.6.0.
- polyphys.analyze.clusters.find_direct_contacts(dist, cutoff, inclusive=True)[source]#
Mark the pairs whose distance is within a cutoff as direct contacts.
- Parameters:
dist (
numpy.typing.ArrayLike) – Center-to-center distances, shape(n_rows, n_cols), in the caller’s length unit: a self-distance matrix frompair_distances(), or the distances between two groups, such as monomers along the rows and binder patches along the columns.cutoff (
float) – The contact distance \(r_c\), in the same unit; positive.inclusive (
bool) – Count a pair at exactly the cutoff as a contact (dist <= cutoff) or not (dist < cutoff).
- Returns:
direct_contacts, the same shape as dist,bool. For a self-distance matrix it is symmetric with a true diagonal.- Return type:
- 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 \(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]])
Added in version 0.6.0.
- polyphys.analyze.clusters.foci_pair_info(genomic_pos, n_monomers, topology)[source]#
List every pair of foci with its genomic distance.
- Parameters:
genomic_pos (
numpy.typing.ArrayLike) – Backbone indices of the foci, the tagged monomers, shape(n_foci,), integers in0, ..., n_monomers - 1.n_monomers (
int) – The number of monomers along the backbone, foci included.topology (
typing.Literal['linear','ring']) – Whether the chain is open or closed.
- Returns:
Shape
(n_pairs, 3),int64, one row per pair in the order ofnumpy.triu_indices(n_foci, 1): the two backbone indices and their genomic distance in bonds.n_pairsisn_foci (n_foci - 1) / 2.- Return type:
- Raises:
ValueError – As
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 \(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]])
Added in version 0.6.0.
- polyphys.analyze.clusters.genomic_distance(atoms_a, atoms_b, topology, n_backbone)[source]#
Count the backbone bonds between paired monomers along the chain.
- Parameters:
atoms_a (
numpy.typing.ArrayLike) – Backbone indices of the paired monomers, integers in0, ..., n_backbone - 1, in any two shapes that broadcast together.atoms_b (
numpy.typing.ArrayLike) – Backbone indices of the paired monomers, integers in0, ..., n_backbone - 1, in any two shapes that broadcast together.topology (
typing.Literal['linear','ring']) – Whether the chain is open or closed.n_backbone (
int) – The number of monomers along the backbone; positive.
- Returns:
The genomic distance of each pair, the broadcast shape of the inputs,
int64, in bonds:|a - b|on a linear chain andmin(|a - b|, n_backbone - |a - b|)on a ring, the shorter way round. The number of monomers between the pair is one less.- Return type:
- Raises:
ValueError – If topology is not
'linear'or'ring', if n_backbone is not positive, or if an index is outside0, ..., n_backbone - 1.
Notes
Time and space are \(O(m)\) for \(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])
Added in version 0.6.0.
- polyphys.analyze.clusters.monomer_binder_contacts(direct_contacts, patches_per_binder)[source]#
Collapse the patches of each binder into one column.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The monomer-patch contact matrix, shape(n_monomers, n_patches), boolean or 0/1, with the patches of binderkin columnsk * patches_per_binderto(k + 1) * patches_per_binder - 1.patches_per_binder (
int) – The number of patches per binder; positive and dividingn_patches.
- Returns:
The monomer-binder contact matrix, shape
(n_monomers, n_binders),bool:[i, k]true when monomeritouches any patch of binderk.- Return type:
- 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 \(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]])
Added in version 0.6.0.
- polyphys.analyze.clusters.pair_distance_histograms(distances, bin_size, r_max)[source]#
Histogram the separation time series of each pair on one shared grid.
- Parameters:
distances (
numpy.typing.ArrayLike) – 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 \(\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, aspolyphys.analyze.measurer.create_bin_edge_and_hist()gives.
- Return type:
tuple[numpy.typing.NDArray[numpy.int_],numpy.typing.NDArray[numpy.double]]- 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 ton_frames.edges (
numpy.ndarray) – Shape(n_bins + 1,),float64: the bin edges, equally spacedbin_sizeapart from 0. Binkis[edges[k], edges[k + 1]), except the last, which also includes its upper edge, asnumpy.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
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 \(O(n_\mathrm{pairs} n_\mathrm{frames} \log n_\mathrm{bins})\), from a binary search of the edges per frame; space is \(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.])
Added in version 0.6.0.
Changed in version 0.9.0: Count the bins with the round-off tolerance of
polyphys.analyze.measurer.create_bin_edge_and_hist().
- polyphys.analyze.clusters.pair_distances(positions, box=None)[source]#
Compute the matrix of center-to-center distances between all pairs.
- Parameters:
positions (
numpy.typing.ArrayLike) – Coordinates of the particles, shape(n_particles, n_dims), in the caller’s length unit.box (
numpy.typing.ArrayLike|None) – Lengths of an orthogonal periodic box, shape(n_dims,), in the same unit. A direction with length0orinfis not periodic. WithNone, no direction is periodic.
- Returns:
dist, shape(n_particles, n_particles),float64: the distance between particlesiandjat[i, j]; symmetric, with a zero diagonal.- Return type:
- 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 \(L\) the separation \(\Delta\) is replaced by its minimum image, \(\Delta - L\, \mathrm{round}(\Delta / L)\), which lies in \([-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 \(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 \(O(n^2 d)\) for \(n\) particles in \(d\) dimensions. Space is \(O(n^2)\): at most four
(n, n)float64arrays 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.1andx = 9.9are0.2apart through the boundary of a box of length10and9.8apart 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
Added in version 0.6.0.
- polyphys.analyze.clusters.pair_separation_density(counts, edges)[source]#
Estimate the probability density of a pair’s separation vector.
- Parameters:
counts (
numpy.typing.ArrayLike) – Histogram counts frompair_distance_histograms(), shape(..., n_bins), one row per pair; every row must have a positive total.edges (
numpy.typing.ArrayLike) – The bin edges, shape(n_bins + 1,), non-negative and strictly increasing, in the caller’s length unit.
- Returns:
\(\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.- Return type:
- 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 \(\vec R\) be the separation vector of one pair of monomers and \(P(\vec R)\) its probability density over the chain’s configurations, \(\int P\, d^3R = 1\). The scalar separation \(R = |\vec R|\) has density \(P(R) = 4\pi R^2 \bar P(R)\), where \(\bar P(R)\) is the average of \(P(\vec R)\) over the directions of \(\vec R\); the factor \(4\pi R^2\) is the Jacobian of spherical coordinates, nothing else. With \(H_k\) frames out of \(N_f\) in the shell between \(R_k\) and \(R_{k+1}\), whose volume is \(\Delta V_k = \tfrac{4\pi}{3}(R_{k+1}^3 - R_k^3)\),
\[\bar P_k = \frac{H_k}{N_f\, \Delta V_k}, \qquad \sum_k \bar P_k\, \Delta V_k = 1 .\]\(-k_B T \ln \bar P(R)\) is the free energy of the pair at separation \(R\), up to a constant; for an ideal chain of \(n\) Kuhn segments of length \(b\), \(P(\vec R)\) is the Gaussian \((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 \(\bar P\), not its definition. The exact shell volume is used rather than \(4\pi R_c^2 \Delta r\) at the bin center, which is 25% too small in the first bin. Time and space are \(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, \(\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
Added in version 0.6.0.
- polyphys.analyze.clusters.split_binders(direct_contacts)[source]#
Separate the dangling binders from the bridging ones.
- Parameters:
direct_contacts (
numpy.typing.ArrayLike) – The monomer-binder contact matrix, shape(n_monomers, n_binders), boolean or 0/1, asmonomer_binder_contacts()returns it.- Return type:
tuple[numpy.typing.NDArray[numpy.bool],numpy.typing.NDArray[numpy.bool]]- 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
enforce_single_patch_contact()has been applied, appears in neither either. Time and space are \(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]])
Added in version 0.6.0.
- polyphys.analyze.clusters.threshold_sweep(distances, cutoffs, cis_thresholds, topology, *, inclusive)[source]#
Recount the binding statistics of saved distance matrices at every cutoff and cis threshold of a grid.
- Parameters:
distances (
numpy.typing.ArrayLike) – 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 binderkat2kand2k + 1along the third; thedistancesthatBinderStatisticsstores.cutoffs (
typing.Union[typing.Sequence[float],numpy.typing.ArrayLike]) – The contact distances \(r_c\) to sweep, in the same unit, each positive; non-empty. Swept in the order given.cis_thresholds (
typing.Sequence[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 (
typing.Literal['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), asfind_direct_contacts(). Keyword only, with no default, because the comparison decides whether the sweep reproduces stored counts: a sweep agrees with the series thatBinderStatisticssaved only at the spec’s cutoff, cis threshold, and comparison.
- Return type:
- 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 ofFrameBinding, each the mean over the frames (float64), under the attribute namesn_patch_monomer_contacts,n_patches_engaged,n_patches_free,n_binders_free,n_binders_dangling,n_binders_bridging,n_pairs_cis, andn_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 ofdbonds at the cutoff of rowk.n_lengthsisn_monomerson a linear chain andn_monomers // 2 + 1on a ring, asBindingStats;[:, 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
distMatTMonHnsPatchmatrices, 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 withinclusive=Trueat 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
BindingStatsand an autocorrelation-aware estimate such aspolyphys.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
find_direct_contacts()andbinding_statistics(), and its bridged pairs are split once per cis threshold. With \(n_c\) cutoffs, \(n_t\) cis thresholds, \(n_f\) frames, \(N_m\) monomers, \(N_p\) patches, and \(N_b = N_p / 2\) binders, time is \(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 \(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]])
Added in version 0.7.0.
Changed in version 0.9.0: Reject a cis threshold that is not a whole number instead of truncating it.