"""
==========================================================
:mod:`polyphys.analyze.measurer`
==========================================================
The :mod:`polyphys.analyze.measurer` module measures one frame of positions:
distances, sizes, and spans of a group of particles, the statistics of
independent samples, the volumes of a bead cut by planes or by a sphere, and
fixed-width bins and histograms of one frame.
Contents
========
Core geometric and structural measurements:
:func:`apply_pbc_orthogonal`, :func:`pair_distance`, :func:`end_to_end`,
:func:`transverse_size`, :func:`max_distance`, and :func:`fsd`.
Summary statistics:
:func:`simple_stats` and :func:`sem`.
Advanced geometric calculations:
:func:`sphere_sphere_intersection` and :func:`spherical_segment`.
Binning and histogram processing:
:func:`create_bin_edge_and_hist`, :func:`fixedsize_bins`,
:func:`radial_histogram`, :func:`radial_cyl_histogram`,
:func:`axial_histogram`, :func:`azimuth_cyl_histogram`, and
:func:`planar_cartesian_histogram`.
Number-density and volume-fraction conversions live in
:mod:`polyphys.manage.utils`.
References
==========
For Feret's statistical diameter:
- Wang Y, Teraoka I, Hansen FY, Peters GH, Hassager O. "A Theoretical Study of
the Separation Principle in Size Exclusion Chromatography." Macromolecules
2010, 43, 3, 1651-1659. https://doi.org/10.1021/ma902377g
For spherical segment calculations:
- Weisstein, Eric W. "Spherical Segment." From MathWorld--A Wolfram Web
Resource. https://mathworld.wolfram.com/SphericalSegment.html
For sphere-sphere intersection:
- Weisstein, Eric W. "Sphere-Sphere Intersection." From MathWorld--A Wolfram
Web Resource. https://mathworld.wolfram.com/Sphere-SphereIntersection.html
"""
from typing import Dict, Tuple, Optional, Union, Any, List, cast
import numpy as np
from ..manage.types import AxisT, EntityT, PropertyT, BinT
from ..manage.utils import invalid_keyword
__all__ = [
'apply_pbc_orthogonal',
'axial_histogram',
'azimuth_cyl_histogram',
'create_bin_edge_and_hist',
'end_to_end',
'fixedsize_bins',
'fsd',
'max_distance',
'pair_distance',
'planar_cartesian_histogram',
'radial_cyl_histogram',
'radial_histogram',
'sem',
'simple_stats',
'sphere_sphere_intersection',
'spherical_segment',
'transverse_size',
]
# Relative tolerance for deciding whether a range holds a whole number of
# bins, used by :func:`create_bin_edge_and_hist` and :func:`fixedsize_bins`.
# The ratio ``(lmax - lmin) / bin_size`` is computed in float64, so a range
# that is exactly a whole number of bins can come out a few ulps above or
# below that integer (``2.1 / 0.3`` is ``7.000000000000001``). A plain
# ``ceil`` then adds a bin, and a plain comparison can leave the edges a few
# 1e-15 inside the range. The tolerance has to sit between two scales:
#
# - the accumulated round-off in the ratio, a few times the float64 epsilon
# (2.2e-16), so below about 1e-15 relative;
# - the smallest deviation a user can intend, which is set by the precision of
# the inputs: box sizes and bead diameters are read from filenames with at
# most seven significant digits, so about 1e-7 relative.
#
# Any value between those classifies every realistic input correctly. 1e-9
# keeps six orders of magnitude from the round-off side and two from the
# intent side; the margins are unequal on purpose, because the two errors are
# not equally bad. Calling a true multiple a non-multiple adds a bin and, for
# 'ordinary' bins, shifts the whole grid by half a bin; calling an intended
# non-multiple a multiple moves the edges by less than
# ``1e-9 * (lmax - lmin)``.
_BIN_COUNT_RTOL = 1e-9
def _count_bins(length: float, bin_size: float) -> Tuple[int, float]:
"""
Return the number of bins of width `bin_size` that cover `length`, and
the excess length they add.
When ``length / bin_size`` is a whole number up to the relative tolerance
``_BIN_COUNT_RTOL``, the count is that whole number and the excess is
exactly ``0.0``; otherwise the count is the ceiling of the ratio and the
excess ``n_bins * bin_size - length`` is strictly positive, by a margin
far above float64 round-off.
Parameters
----------
length : float
Length of the range to cover, positive.
bin_size : float
Width of each bin, positive.
Returns
-------
Tuple[int, float]
``(n_bins, excess)``.
Examples
--------
>>> _count_bins(2.1, 0.3)
(7, 0.0)
>>> n_bins, excess = _count_bins(2.0, 0.7)
>>> n_bins, round(excess, 12)
(3, 0.1)
"""
ratio = length / bin_size
n_bins = int(np.rint(ratio))
if n_bins > 0 and np.isclose(
ratio, n_bins, rtol=_BIN_COUNT_RTOL, atol=0.0
):
return n_bins, 0.0
n_bins = int(np.ceil(ratio))
return n_bins, n_bins * bin_size - length
def _histogram_or_raise(values: np.ndarray, edges: np.ndarray) -> np.ndarray:
"""
Histogram `values` over `edges`, raising if any value falls outside them.
`np.histogram` silently drops values below the first edge or above the
last one. For the spatial profiles this module serves, every position
belongs to the system, so a dropped position is a defect in the caller's
edges or an unwrapped coordinate, not data to ignore.
Parameters
----------
values : np.ndarray
One-dimensional array of values to bin.
edges : np.ndarray
Monotonically increasing bin edges, including the rightmost edge.
Returns
-------
np.ndarray
Counts per bin, shape ``(len(edges) - 1,)``; their sum is
``values.size``.
Raises
------
ValueError
If any value lies outside ``[edges[0], edges[-1]]``.
Examples
--------
>>> edges = np.array([0., 1., 2., 3.])
>>> _histogram_or_raise(np.array([0.5, 2.0, 3.0]), edges)
array([1, 0, 2])
>>> _histogram_or_raise(np.array([0.5, 9.0]), edges)
Traceback (most recent call last):
...
ValueError: 1 of 2 positions fall outside the edges [0.0, 3.0].
"""
# Declared, not cast: numpy 2.5 stubs type these counts as Any and
# numpy 2.3 stubs as an ndarray, where a cast is redundant.
hist: np.ndarray
hist, _ = np.histogram(values, bins=edges)
n_missed = values.size - int(hist.sum())
if n_missed:
raise ValueError(
f"{n_missed} of {values.size} positions fall outside the edges "
f"[{edges[0]}, {edges[-1]}]."
)
return hist
[docs]
def apply_pbc_orthogonal(
pbc_lengths: np.ndarray,
pbc_lengths_inverse: np.ndarray,
pbc: Dict[AxisT, float],
) -> Tuple[np.ndarray, np.ndarray]:
"""
Write the box length and its inverse of each axis in `pbc` into the
given arrays.
The arrays are modified in place and also returned; an axis not in
`pbc` keeps its value.
Parameters
----------
pbc_lengths : numpy.ndarray
The box length along each axis, shape ``(n_dim,)``, typically
``(3,)``, in the length unit of the positions; modified in place.
pbc_lengths_inverse : numpy.ndarray
The inverse box length along each axis, the same shape; modified in
place.
pbc : Dict[:py:obj:`~.AxisT`, float]
Axis indices (0=x, 1=y, 2=z) mapped to their box lengths, positive.
Returns
-------
pbc_lengths : numpy.ndarray
`pbc_lengths`, updated.
pbc_lengths_inverse : numpy.ndarray
`pbc_lengths_inverse`, updated.
Raises
------
ZeroDivisionError
If any specified length is zero, which would result in division by
zero.
ValueError
If any specified length is negative, which is physically invalid for
box dimensions.
Examples
--------
>>> pbc_lengths = np.zeros(3)
>>> pbc_lengths_inverse = np.zeros(3)
>>> pbc = {0: 10.0, 2: 20.0}
>>> apply_pbc_orthogonal(pbc_lengths, pbc_lengths_inverse, pbc)
(array([10., 0., 20.]), array([0.1 , 0. , 0.05]))
"""
for ax, length in pbc.items():
if length == 0.0:
raise ZeroDivisionError(f"Length for axis {ax} cannot be zero.")
if length < 0.0:
raise ValueError(
f"Length for axis {ax} must be positive; got {length}."
)
pbc_lengths[ax] = length
pbc_lengths_inverse[ax] = 1 / length
return pbc_lengths, pbc_lengths_inverse
[docs]
def pair_distance(
positions: np.ndarray, pbc: Optional[Dict[AxisT, float]] = None
) -> np.ndarray:
"""
Compute the displacement vector from the first particle to the second,
optionally under the minimum image convention.
Parameters
----------
positions : numpy.ndarray
The positions of the two particles, shape ``(2, n_dim)``; the
order sets the sign of the result. Integer positions are converted
to ``float64``.
pbc : Optional[Dict[:py:obj:`~.AxisT`, float]], default None
Dictionary with axis indices (0=x, 1=y, 2=z) as keys and box lengths as
values. If provided, periodic boundary conditions (PBC) are applied
along each axis with a finite length; an ``inf`` length leaves its
axis non-periodic, as in
:func:`polyphys.analyze.clusters.pair_distances`; see
:mod:`polyphys.manage.types`.
Returns
-------
np.ndarray
The signed displacement ``positions[1] - positions[0]`` along each
axis, shape ``(n_dim,)``, ``float64``, in the length unit of
`positions`; with `pbc`, each periodic component is folded into
``[-L/2, L/2]``.
Raises
------
ValueError
If `positions` does not contain exactly two sets of coordinates.
Notes
-----
The result is the component-wise displacement, not its Euclidean norm.
Examples
--------
>>> positions = np.array([[1.0, 2.0, 3.0], [4.0, 2.0, 3.0]])
>>> pair_distance(positions)
array([3., 0., 0.])
>>> pbc = {0: 8.0}
>>> positions = np.array([[1.0, 2.0, 3.0], [9.5, 2.0, 3.0]])
>>> pair_distance(positions, pbc)
array([0.5, 0. , 0. ])
"""
positions = np.asarray(positions, dtype=np.float64)
n_atoms, n_dims = positions.shape
if n_atoms != 2:
raise ValueError("'pair_distance' only works for two atoms.")
# Calculation in the center of geometry (cog) of the atom group.
delta = positions[1] - positions[0]
if pbc is not None:
# Prepare length and inverse-length arrays
pbc_lengths, pbc_lengths_inverse = apply_pbc_orthogonal(
np.zeros(n_dims), np.zeros(n_dims), pbc
)
# Apply the minimum image convention along the finite lengths; an
# infinite length is not periodic, and inf * 0 would give NaN.
periodic = np.isfinite(pbc_lengths)
delta[periodic] -= pbc_lengths[periodic] * np.round(
delta[periodic] * pbc_lengths_inverse[periodic]
)
# cast: numpy's stubs return Any; at runtime this is an ndarray.
return cast(np.ndarray, delta)
[docs]
def end_to_end(positions: np.ndarray) -> Union[np.floating, np.ndarray]:
"""
Compute the end-to-end distance of a chain, the distance between its
first and its last bead.
Parameters
----------
positions : np.ndarray
Array of shape (n_atoms, n_dim) containing atomic positions, in
backbone order from the first monomer to the last.
Returns
-------
numpy.floating
The end-to-end distance, in the length unit of `positions`.
Raises
------
ValueError
If `positions` contains fewer than two atoms.
Notes
-----
The positions are centered on their center of geometry first; the
distance does not depend on that translation.
Examples
--------
>>> positions = np.array([[0.0, 0.0, 0.0],
... [1.0, 0.0, 0.0],
... [2.0, 0.0, 0.0]])
>>> end_to_end(positions)
np.float64(2.0)
>>> positions = np.array([[1.0, 1.0, 1.0],
... [2.0, 2.0, 2.0],
... [3.0, 3.0, 3.0]])
>>> end_to_end(positions)
np.float64(3.4641016151377544)
"""
# calculation in the center of geometry of the atom group.
if positions.shape[0] < 2:
raise ValueError("`positions` must contain at least two atoms.")
centered_positions = positions - np.mean(positions, axis=0)
# cast: numpy 2.5 stubs return Any; at runtime this is a NumPy floating
# scalar, so the cast restates the annotation and changes nothing.
return cast(
Union[np.floating, np.ndarray],
np.linalg.norm(centered_positions[-1] - centered_positions[0]),
)
[docs]
def transverse_size(positions: np.ndarray, axis: AxisT) -> float:
"""
Compute the transverse size of a group of atoms, twice their mean
distance from their center in the plane perpendicular to `axis`.
Parameters
----------
positions : np.ndarray
Array of shape (n_atoms, n_dim) containing atomic positions, in any
order.
axis : :py:obj:`~.AxisT`
The axis (0 for x, 1 for y, and 2 for z) perpendicular to the plane
in which the size is measured.
Returns
-------
float
Twice the mean distance of the atoms from their center of geometry
in the plane perpendicular to `axis`, a diameter, in the length unit
of `positions`.
Raises
------
IndexError
If `axis` is out of bounds for `positions`.
Notes
-----
The distance is calculated in a reference frame centered at the center of
geometry of atoms in the plane perpendicular to a given axis.
Examples
--------
>>> positions = np.array([[1, 0, 0], [1, 2, 2]])
>>> transverse_size(positions, axis=0)
np.float64(2.8284271247461903)
>>> transverse_size(positions, axis=1)
np.float64(2.0)
"""
trans_axes = {0: [1, 2], 1: [0, 2], 2: [0, 1]}
if axis >= positions.shape[1]:
raise IndexError(
f"Axis {axis} is out of bounds for positions array"
f" with shape {positions.shape}."
)
trans_pos = positions[:, trans_axes[axis]] - np.mean(
positions[:, trans_axes[axis]], axis=0
)
# Times by 2, so we have the diameter not radius:
# cast: numpy's stubs return Any. The value is a NumPy floating scalar
# (np.float32 for float32 input), not always a float; the cast only
# restates the existing annotation and changes nothing at runtime.
return cast(float, 2 * np.mean(np.linalg.norm(trans_pos, axis=1)))
[docs]
def max_distance(positions: np.ndarray) -> np.ndarray:
"""
Compute the extent of the positions along each Cartesian axis.
Parameters
----------
positions : np.ndarray
Array of shape (n_atoms, n_dim) containing atom positions, in any
order.
Returns
-------
np.ndarray
The largest coordinate minus the smallest along each axis, shape
``(n_dim,)``, in the length unit of `positions`.
Raises
------
ValueError
If `positions` is empty.
Notes
-----
The positions are centered on their center of geometry first; the
extent does not depend on that translation.
Examples
--------
>>> positions = np.array([[0, 0, 0], [4, 2, 6], [2, 3, 0]])
>>> max_distance(positions)
array([4., 3., 6.])
"""
# calculation in the center of geometry of the atom group.
centered_positions = positions - np.mean(positions, axis=0)
# cast: numpy's stubs return Any; at runtime this is an ndarray.
return cast(np.ndarray, np.ptp(centered_positions, axis=0))
[docs]
def fsd(positions: np.ndarray, axis: AxisT) -> float:
"""
Compute the span of the positions along the selected axis.
The span is the largest coordinate minus the smallest along `axis`, for
one configuration; nothing is averaged over frames or orientations. The
name ``fsd`` is kept from Feret's statistical diameter, the caliper
distance along a fixed direction.
Parameters
----------
positions : np.ndarray
Array of shape ``(n_atoms, n_dim)`` of atom positions, in any order;
the span does not depend on it.
axis : :py:obj:`~.AxisT`
Axis index (0=x, 1=y, 2=z) along which to compute the span; see
:mod:`polyphys.manage.types`.
Returns
-------
float
The span along `axis`, in the units of `positions`.
Raises
------
IndexError
If `axis` is out of bounds for `positions`.
References
----------
Wang Y, Teraoka I, Hansen FY, Peters GH, Hassager O. "A Theoretical
Study of the Separation Principle in Size Exclusion Chromatography."
Macromolecules 2010, 43, 3, 1651-1659.
https://doi.org/10.1021/ma902377g
Examples
--------
>>> positions = np.array([[1, 2, 3], [4, 8, 6]])
>>> fsd(positions, axis=1)
np.float64(6.0)
"""
if axis >= positions.shape[1]:
raise IndexError(
f"Axis {axis} is out of bounds for positions array"
f" with shape {positions.shape}."
)
# calculation in the center of geometry of the atom group:
positions = positions - np.mean(positions, axis=0)
# cast: numpy's stubs return Any. The value is a NumPy floating scalar
# (np.float32 for float32 input), not always a float; the cast only
# restates the existing annotation and changes nothing at runtime.
return cast(float, np.ptp(positions[:, axis]))
[docs]
def simple_stats(
entity: EntityT,
data: np.ndarray
) -> Dict[PropertyT, float | np.floating]:
"""
Compute basic statistics (mean, variance, SEM) for a physical `entity`.
Parameters
----------
entity : EntityT
The name that prefixes the keys of the result.
data : np.ndarray
One-dimensional array of independent samples.
Returns
-------
Dict[PropertyT, float | numpy.floating]
The mean, the sample variance with ``ddof=1``, and the SEM, the
sample standard deviation with ``ddof=1`` over the square root of
the number of samples, keyed ``'<entity>_mean'``,
``'<entity>_var'``, and ``'<entity>_sem'``.
Raises
------
ValueError
If `data` is empty or holds one sample, whose unbiased variance
divides by ``n - 1 = 0``.
Examples
--------
>>> import numpy as np
>>> simple_stats('energy', np.array([1.0, 2.0, 3.0])) # noqa: E501
{'energy_mean': np.float64(2.0), 'energy_var': np.float64(1.0), 'energy_sem': np.float64(0.5773502691896258)}
"""
if len(data) == 0:
raise ValueError('Input array must not be empty.')
if len(data) < 2:
raise ValueError(
'Input array must hold at least two samples for an unbiased'
' variance.'
)
# Unbiased std, var, and sem.
return {
entity + '_mean': np.mean(data),
entity + '_var': np.var(data, ddof=1),
entity + '_sem': np.std(data, ddof=1) / np.sqrt(len(data)),
}
[docs]
def sem(data: np.ndarray) -> float:
"""
Compute the standard error of the mean (SEM) of independent samples.
Parameters
----------
data : np.ndarray
One-dimensional array of sample data.
Returns
-------
float
The standard error of the mean, in the unit of `data`.
Raises
------
ValueError
If `data` is empty or holds one sample, whose sample standard
deviation with ``ddof=1`` divides by ``n - 1 = 0``.
Notes
-----
SEM is calculated using sample standard deviation (ddof=1) and sample size.
The estimate assumes independent samples, such as the means of independent
replicates. For a time series of correlated frames it understates the
error; use :func:`polyphys.analyze.stats.sem_blocked` instead.
Examples
--------
>>> import numpy as np
>>> sem(np.array([1.0, 2.0, 3.0]))
np.float64(0.5773502691896258)
"""
if len(data) == 0:
raise ValueError('Input data array must not be empty.')
if len(data) < 2:
raise ValueError(
'Input data array must hold at least two samples for an unbiased'
' standard deviation.'
)
# cast: numpy's stubs return Any. The value is a NumPy floating scalar
# (np.float32 for float32 input), not always a float; the cast only
# restates the existing annotation and changes nothing at runtime.
return cast(float, np.std(data, ddof=1) / len(data) ** 0.5)
[docs]
def spherical_segment(r: float, a: float, b: float) -> float:
"""
Compute the volume of a spherical segment defined by two parallel planes.
Parameters
----------
r : float
Radius of the sphere. Must be positive.
a : float
Distance of the first plane from the center of the sphere, along the
axis of symmetry.
b : float
Distance of the second plane from the center of the sphere, along the
axis of symmetry.
Returns
-------
vol : float
Volume of the spherical segment.
Raises
------
ValueError
If `r` is not a positive number.
Notes
-----
- `a` and `b` can be positive or negative values, as long as they fall
within the range `[-r, r]`.
- The function will adjust `a` and `b` to `-r` or `r` if they exceed these
bounds.
- If `a = r` or `b = r`, the spherical segment becomes a spherical cap.
- If both `a` and `b` lie outside the range `[-r, r]` and share the same
sign, the volume is zero.
References
----------
Weisstein, Eric W. "Spherical Segment." From MathWorld--A Wolfram Web
Resource. https://mathworld.wolfram.com/SphericalSegment.html
Examples
--------
>>> spherical_segment(3, 1, 2)
20.94395102393195
>>> spherical_segment(3, -3, 3)
113.09733552923255
"""
if r <= 0:
raise ValueError(f"The radius 'r' must be positive. Got {r}.")
# Ensure the bounds are within [-r, r]
lower = max(min(a, b), -r)
upper = min(max(a, b), r)
# If both bounds are outside [-r, r] with the same sign, the volume is zero
if lower * upper >= r**2:
return 0.0
# Calculate the volume of the spherical segment
vol = np.pi * (r**2 * (upper - lower) - (upper**3 - lower**3) / 3)
return vol
[docs]
def sphere_sphere_intersection(r1: float, r2: float, d: float) -> float:
"""
Compute the volume of intersection between two spheres.
The sphere with radius `r1` is separated from the sphere with radius `r2`
by a distance `d` along the x-axis. Thus, the vector form of the distance
between their centers is `(d, 0, 0)` in Cartesian coordinates.
Parameters
----------
r1 : float
Radius of the first sphere.
r2 : float
Radius of the second sphere.
d : float
Distance between the centers of the two spheres along the x-axis.
Returns
-------
vol : float
Volume of the intersection between the two spheres.
References
----------
Weisstein, Eric W. "Sphere-Sphere Intersection." From MathWorld--A Wolfram
Web Resource. https://mathworld.wolfram.com/Sphere-SphereIntersection.html
Examples
--------
>>> sphere_sphere_intersection(3, 4, 2)
94.90227807719167
>>> sphere_sphere_intersection(3, 4, 10)
0.0
"""
r_max = max(r1, r2)
r_min = min(r1, r2)
# Volume is zero if one sphere has a radius of zero or no intersection
# occurs:
if r1 == 0.0 or r2 == 0.0:
return 0.0
if d >= r_min + r_max:
return 0.0
if d <= r_max - r_min:
# The smaller sphere is entirely contained within the larger one
return 4 * np.pi * r_min**3 / 3
# Calculate the intersection volume for overlapping spheres
vol = (
(np.pi / (12 * d))
* (r_max + r_min - d) ** 2
* (
d**2
+ 2 * d * (r_max + r_min)
- 3 * (r_min**2 + r_max**2)
+ 6 * r_min * r_max
)
)
return vol
[docs]
def create_bin_edge_and_hist(
bin_size: float, lmin: float, lmax: float, output: Optional[str] = None
) -> Tuple[np.ndarray, np.ndarray]:
"""
Create bin edges of a fixed width and a zero-filled histogram.
The edges start at `lmin` and step by `bin_size` up to the first edge at
or beyond `lmax`, so there are ``n_bins = ceil((lmax - lmin) / bin_size)``
bins of width `bin_size`. When the range is a whole number of bins up to
the relative tolerance ``_BIN_COUNT_RTOL`` (1e-9), the last edge is
exactly `lmax`; otherwise it exceeds `lmax` by less than one bin.
Parameters
----------
bin_size : float
Size of each bin.
lmin : float
Lower bound of the system in the direction of interest.
lmax : float
Upper bound of the system in the direction of interest.
output : Optional[str], default None
Filename (including filepath) to which bin edges array is saved. A
`.npy` extension will be appended to the filename if it does not
already have one.
Returns
-------
Tuple[np.ndarray, np.ndarray]
- bin_edges : Array of bin edges, shape ``(n_bins + 1,)``, equal to
``lmin + bin_size * k`` for ``k = 0, ..., n_bins``.
- hist : Zero-initialized histogram of dtype ``np.int64`` and shape
``(n_bins,)``. The 64-bit integer type keeps per-frame counts
accumulated in place (``hist += np.histogram(...)[0]``) from
overflowing.
Raises
------
ValueError
If `lmin` is not less than `lmax`.
Notes
-----
The `.npy` extension is handled internally by `np.save`.
The edges come from `np.linspace`, so their number is exactly
``n_bins + 1``; a float-step `np.arange` can return one edge too many
when `bin_size` is not exactly representable (for example 0.3). The bin
count treats a ratio within 1e-9 of a whole number as that whole number;
see ``_BIN_COUNT_RTOL`` for why.
Time and space are O(`n_bins`).
Examples
--------
>>> edges, hist = \
create_bin_edge_and_hist(bin_size=1.0, lmin=0.0, lmax=5.0)
>>> edges
array([0., 1., 2., 3., 4., 5.])
>>> hist
array([0, 0, 0, 0, 0])
A step that is not exactly representable still gives one edge per bin
plus one, ending exactly at `lmax`:
>>> edges, hist = create_bin_edge_and_hist(0.3, -6.0, 6.0)
>>> print(len(edges), len(hist), edges[0], edges[-1])
41 40 -6.0 6.0
A range that is not a multiple of `bin_size` is covered by one more bin:
>>> create_bin_edge_and_hist(0.7, 0.0, 2.0)[0]
array([0. , 0.7, 1.4, 2.1])
"""
if lmin >= lmax:
raise ValueError("'lmin' must be less than 'lmax'.")
n_bins, excess = _count_bins(lmax - lmin, bin_size)
upper = lmax if excess == 0.0 else lmin + n_bins * bin_size
bin_edges = np.linspace(lmin, upper, n_bins + 1)
hist = np.zeros(n_bins, dtype=np.int64)
if output is not None:
np.save(output, bin_edges)
return bin_edges, hist
[docs]
def fixedsize_bins(
bin_size: float,
lmin: float,
lmax: float,
bin_type: BinT = 'ordinary',
save_bin_edges: Optional[str] = None,
) -> Dict[str, Any]:
"""
Generate bin edges and zero-filled histogram arrays with consistent
bin width.
Every bin type returns ``n_bins + 1`` equally spaced edges of width
`bin_size` that cover [`lmin`, `lmax`].
Parameters
----------
bin_size : float
Width of each bin.
lmin : float
Start of the range
lmax : float
End of the range
bin_type : :py:obj:`~.BinT`, default 'ordinary'
Type of binning. With ``n_bins = ceil((lmax - lmin) / bin_size)``
bins, the excess length ``n_bins * bin_size - (lmax - lmin)`` is
zero when the range is a whole number of bins and is otherwise
shared out as follows:
- 'ordinary': Extends `lmin` and `lmax` symmetrically, by half the
excess each. Examples are Cartesian coordinates and spherical polar
coordinate.
- 'nonnegative': Extends `lmin` and `lmax` symmetrically if the
extended `lmin` stays nonnegative; otherwise `lmin` is set to 0 and
`lmax` to ``n_bins * bin_size``. Examples are radial directions in
the polar, spherical, and cylindrical coordinate systems.
- 'periodic': Periodic binning over one period, ``lmax - lmin``,
which must be a whole number of bins; the edges run from `lmin` to
`lmax` exactly. Examples are azimuthal directions in cylindrical
and spherical coordinate systems.
See the Notes for how "a whole number of bins" is decided.
See :mod:`polyphys.manage.types`.
save_bin_edges : Optional[str], default None
Filename (including filepath) to which bin edges array is saved. A
`.npy` extension will be appended to the filename if it does not
already have one.
Returns
-------
Dict[str, Any]
Dictionary with keys:
- 'n_bins' : int
Number of bins.
- 'bin_edges' : np.ndarray
A monotonically increasing array of bin edges, including the
rightmost edge.
- 'collector' : np.ndarray
Zero-initialized array of dtype ``np.int64`` and shape
``(n_bins,)`` for histogram counts. The 64-bit integer type keeps
per-frame counts accumulated in place
(``collector += np.histogram(...)[0]``) from overflowing.
- 'collector_std' : np.ndarray
Zero-initialized array of dtype ``np.float64`` and shape
``(n_bins,)`` for standard deviation values or the squared counts
they are computed from.
- 'range' : Tuple[float, float]
Updated range of bins (`lmin`, `lmax`).
Raises
------
ValueError
If `lmin` is not less than `lmax`.
ValueError
If `bin_type` is 'nonnegative' and `lmin` is negative: clipping the
lower end to zero would leave the range below zero uncovered.
ValueError
If `bin_type` is 'periodic' and ``lmax - lmin`` is not a multiple of
`bin_size`. A last bin running past the period would cover values
that never occur, so a density normalized by its width would be
biased low.
Notes
-----
The `.npy` extension is handled internally by `np.save`.
The edges come from `np.linspace`, so their number is exactly
``n_bins + 1``, and the first and last edges enclose `lmin` and `lmax`
exactly: a position at either end of the range falls inside the bins,
and `np.histogram` counts a value equal to the last edge in the last bin.
**Deciding whether the range is a whole number of bins.** The ratio
``(lmax - lmin) / bin_size`` is computed in float64, so a range that is
exactly a whole number of bins can come out a few ulps above or below
that integer: ``2.1 / 0.3`` is ``7.000000000000001``, and
``530 * 0.03`` is a few 1e-15 below ``15.9``. Taking the ceiling of such
a ratio adds a bin and, for 'ordinary' bins, shifts every edge by half
a bin; comparing it directly can leave the end edges a few 1e-15 inside
the range, where a position at exactly `lmin` or `lmax` is lost. The ratio
is therefore compared with the nearest integer at the relative tolerance
``_BIN_COUNT_RTOL`` = 1e-9. That tolerance sits between the two
scales that matter: the accumulated round-off in the ratio, a few times
the float64 epsilon (about 1e-15), and the smallest deviation a user can
intend, which the seven significant digits of the box sizes and bead
diameters in the simulation filenames put at about 1e-7. It is closer to
the intent side on purpose, because the two misclassifications are not
equally bad: calling a true multiple a non-multiple adds a bin and shifts
the grid, while calling an intended non-multiple a multiple moves the
edges by less than ``1e-9 * (lmax - lmin)``.
The symmetric extension of the 'ordinary' bins follows MDAnalysis's
``fixedwidth_bins``; the nearest-integer bin count departs from it, for
the reasons above.
Time and space are O(`n_bins`).
References
----------
MDAnalysis ``lib.util.fixedwidth_bins``:
https://github.com/MDAnalysis/mdanalysis/blob/ae9ff4b738606ba1e7c18a8a9b99a8a87eb69f74/package/MDAnalysis/lib/util.py#L1350
Examples
--------
>>> result = fixedsize_bins(1.0, 0.0, 5.0)
>>> result['n_bins']
5
>>> result['bin_edges']
array([0., 1., 2., 3., 4., 5.])
A range that is a whole number of bins up to round-off is tiled exactly:
>>> result = fixedsize_bins(0.3, 0.0, 2.1)
>>> edges = result['bin_edges']
>>> print(result['n_bins'], edges[0], edges[-1])
7 0.0 2.1
A radial range whose lower end would fall below zero is clipped there,
and the bins keep their width:
>>> result = fixedsize_bins(1.0, 0.1, 2.5, bin_type='nonnegative')
>>> result['bin_edges']
array([0., 1., 2., 3.])
Azimuthal bins of 5 degrees span exactly one period:
>>> result = fixedsize_bins(np.pi / 36, -np.pi, np.pi, bin_type='periodic')
>>> print(result['n_bins'], result['bin_edges'][-1] == np.pi)
72 True
"""
if lmin >= lmax:
raise ValueError("'lmin' must be less than 'lmax'.")
_length = lmax - lmin
_delta = bin_size
n_bins, excess = _count_bins(_length, _delta)
dl = 0.5 * excess # the excess length to share between the two ends
if bin_type == 'ordinary':
# add half of the excess to each end:
lmin_adj = lmin - dl
lmax_adj = lmax + dl
elif bin_type == 'nonnegative':
if lmin < 0.0:
raise ValueError(
"'lmin' must be nonnegative for the 'nonnegative' bin type."
)
if lmin - dl < 0.0:
# clip the lower end at zero and span n_bins full widths from it
lmin_adj = 0.0
lmax_adj = n_bins * _delta
else:
lmin_adj = lmin - dl
lmax_adj = lmax + dl
elif bin_type == 'periodic':
if excess != 0.0:
raise ValueError(
f"For the 'periodic' bin type, the period 'lmax - lmin' "
f"({_length}) must be a multiple of 'bin_size' ({_delta})."
)
lmin_adj, lmax_adj = lmin, lmax
else:
invalid_keyword(bin_type, ['ordinary', 'nonnegative', 'periodic'])
bin_edges = np.linspace(lmin_adj, lmax_adj, n_bins + 1, endpoint=True)
collectors = np.zeros(n_bins, dtype=np.int64)
collectors_std = np.zeros(n_bins, dtype=np.float64)
if save_bin_edges is not None:
np.save(save_bin_edges, bin_edges)
return {
'n_bins': n_bins,
'bin_edges': bin_edges,
'collector': collectors,
'collector_std': collectors_std,
'range': (lmin_adj, lmax_adj),
}
[docs]
def radial_histogram(
positions: np.ndarray,
edges: np.ndarray,
) -> np.ndarray:
"""
Bin the distances of the positions from the origin, the spherical
radial coordinate.
Parameters
----------
positions : np.ndarray
Array of shape (n_atoms, n_dim) containing atom positions, in any
order.
edges : np.ndarray
A monotonically increasing array of bin edges, including the rightmost
edge. The last bin includes its right edge. Every position must lie
within the outermost edges: a coordinate along a periodic axis must
already be wrapped into the box, since this function does not wrap.
Returns
-------
hist : np.ndarray
The counts per bin, shape ``(len(edges) - 1,)``, integer.
Raises
------
ValueError
If the positions array is not two-dimensional.
ValueError
If any position falls outside the outermost edges. `np.histogram`
would drop it silently; here a dropped position means wrong edges or
an unwrapped coordinate, so it is an error.
Examples
--------
>>> positions= np.array([[1, 0, 0], [0, 1, 0], [0, 0, 2]])
>>> edges = np.array([0, 1, 2, 3])
>>> radial_histogram(positions, edges)
array([0, 2, 1])
"""
if positions.ndim != 2:
raise ValueError(
"'positions' must be a 2D array with shape (n_atoms, n_dim)."
)
rad_distances = np.linalg.norm(positions, axis=1)
return _histogram_or_raise(rad_distances, edges)
[docs]
def radial_cyl_histogram(
positions: np.ndarray,
edges: np.ndarray,
dim: AxisT,
) -> np.ndarray:
"""
Bin the distances of the positions from the axis along `dim`, the
cylindrical radial coordinate.
Parameters
----------
positions : np.ndarray
Array of shape (n_atoms, n_dim) containing atom positions, in any
order.
edges : np.ndarray
A monotonically increasing array of bin edges, including the rightmost
edge. The last bin includes its right edge. Every position must lie
within the outermost edges: a coordinate along a periodic axis must
already be wrapped into the box, since this function does not wrap.
dim : :py:obj:`~.AxisT`
Axis direction (0=x, 1=y, 2=z); see :mod:`polyphys.manage.types`.
Returns
-------
hist : np.ndarray
The counts per bin, shape ``(len(edges) - 1,)``, integer.
Raises
------
ValueError
If `dim` is not one of {0, 1, 2}.
ValueError
If the positions array is not two-dimensional.
ValueError
If any position falls outside the outermost edges. `np.histogram`
would drop it silently; here a dropped position means wrong edges or
an unwrapped coordinate, so it is an error.
Examples
--------
>>> import numpy as np
>>> positions = np.array([[1, 0, 0], [0, 2, 0], [0, 0, 3], [0, 3, 4]])
>>> edges = np.array([0, 1, 2, 3, 4])
>>> radial_cyl_histogram(positions, edges, dim=1)
array([1, 1, 0, 2])
"""
if dim not in {0, 1, 2}:
raise ValueError("'dim' must be one of {0, 1, 2}.")
if positions.ndim != 2:
raise ValueError(
"'positions' must be a 2D array with shape (n_atoms, n_dim)."
)
trans_axes = np.roll(np.arange(3), -dim)[1:] # selecting transverse axes
trans_distances = np.linalg.norm(positions[:, trans_axes], axis=1)
return _histogram_or_raise(trans_distances, edges)
[docs]
def axial_histogram(
positions: np.ndarray,
edges: np.ndarray,
dim: AxisT,
) -> np.ndarray:
"""
Bin signed coordinates along the selected axis `dim`.
Parameters
----------
positions : np.ndarray
Array of shape (n_atoms, n_dim) containing atom positions, in any
order.
edges : np.ndarray
A monotonically increasing array of bin edges, including the rightmost
edge. The last bin includes its right edge. Every position must lie
within the outermost edges: a coordinate along a periodic axis must
already be wrapped into the box, since this function does not wrap.
dim : :py:obj:`~.AxisT`
The longitudinal axis (0=x, 1=y, 2=z); see
:mod:`polyphys.manage.types`.
Returns
-------
hist : np.ndarray
The counts per bin, shape ``(len(edges) - 1,)``, integer.
Raises
------
ValueError
If `dim` is not one of {0, 1, 2}.
ValueError
If the positions array is not two-dimensional.
ValueError
If any position falls outside the outermost edges. `np.histogram`
would drop it silently; here a dropped position means wrong edges or
an unwrapped coordinate, so it is an error.
Examples
--------
>>> positions= np.array([[1, 2, 3], [2, 3, 4], [1, 2, 2]])
>>> edges = np.array([0, 1, 2, 3, 4, 5])
>>> axial_histogram(positions, edges, dim=0)
array([0, 2, 1, 0, 0])
"""
if dim not in {0, 1, 2}:
raise ValueError("'dim' must be one of {0, 1, 2}.")
if positions.ndim != 2:
raise ValueError(
"'positions' must be a 2D array with shape (n_atoms, n_dim)."
)
return _histogram_or_raise(positions[:, dim], edges)
[docs]
def azimuth_cyl_histogram(
positions: np.ndarray,
edges: np.ndarray,
dim: AxisT,
) -> np.ndarray:
"""
Bin the azimuthal angles of the positions about the axis along `dim`,
in radians.
Parameters
----------
positions : np.ndarray
Array of shape (n_atoms, n_dim) containing atom positions, in any
order.
edges : np.ndarray
A monotonically increasing array of bin edges, in radians, including
the rightmost edge; the angles lie in ``[-pi, pi]``, as
:obj:`numpy.arctan2` returns them. The last bin includes its right
edge. Every position must lie within the outermost edges: a
coordinate along a periodic axis must already be wrapped into the
box, since this function does not wrap.
dim : :py:obj:`~.AxisT`
The longitudinal axis (0=x, 1=y, 2=z); see
:mod:`polyphys.manage.types`.
Returns
-------
hist : np.ndarray
The counts per bin, shape ``(len(edges) - 1,)``, integer.
Raises
------
ValueError
If `dim` is not one of {0, 1, 2}.
ValueError
If the positions array is not two-dimensional.
ValueError
If any position falls outside the outermost edges. `np.histogram`
would drop it silently; here a dropped position means wrong edges or
an unwrapped coordinate, so it is an error.
Examples
--------
>>> positions= np.array([[1, 0, 0], [0, 1, 0], [-1, 0, 0]])
>>> edges = np.linspace(-np.pi, np.pi, 5)
>>> azimuth_cyl_histogram(positions, edges, dim=2)
array([0, 0, 1, 2])
"""
if dim not in {0, 1, 2}:
raise ValueError("'dim' must be one of {0, 1, 2}.")
if positions.ndim != 2:
raise ValueError(
"'positions' must be a 2D array with shape (n_atoms, n_dim)."
)
transverse_axes = np.roll(np.arange(3), -dim)[1:]
azimuthal_angles = np.arctan2(
positions[:, transverse_axes[1]], positions[:, transverse_axes[0]]
)
return _histogram_or_raise(azimuthal_angles, edges)
[docs]
def planar_cartesian_histogram(
positions: np.ndarray,
edges: List[np.ndarray],
dim: AxisT,
) -> np.ndarray:
"""
Compute a two-dimensional histogram in the plane perpendicular to `dim`,
in Cartesian coordinates.
Parameters
----------
positions : np.ndarray
Array of shape (n_atoms, n_dim) containing atom positions, in any
order.
edges : List[np.ndarray]
Two monotonically increasing arrays of bin edges, one per planar axis,
each including its rightmost edge. The last bin along each axis
includes its right edge. Every position must lie within the outermost
edges along both axes: a coordinate along a periodic axis must already
be wrapped into the box, since this function does not wrap.
dim : :py:obj:`~.AxisT`
Cartesian axis (0=x, 1=y, 2=z). The right-hand rule is used to pass the
planar axes to the `np.histogram2d`: When `dim=0` (x), `dim=1` (y) and
`dim=2` (z) values are passed respectively. When `dim=1` (y), `dim=2`
(z) and `dim=0` (x) values are passed respectively. When `dim=2` (z),
`dim=0` (x) and `dim=1` (y) values are passed respectively. See
:mod:`polyphys.manage.types`.
Returns
-------
hist : np.ndarray
The counts per cell, shape ``(len(edges[0]) - 1, len(edges[1]) - 1)``,
``float64``, as :func:`numpy.histogram2d` returns them, with rows
along the first planar axis.
Raises
------
ValueError
If `dim` is not one of {0, 1, 2}.
ValueError
If the positions array is not two-dimensional.
ValueError
If any position falls outside the outermost edges. `np.histogram`
would drop it silently; here a dropped position means wrong edges or
an unwrapped coordinate, so it is an error.
ValueError
If the length of `edges` is not two.
Examples
--------
>>> positions= np.array([[1, 1, 0], [2, 2, 0], [3, 3, 0]])
>>> edges = [np.array([0, 2, 4]), np.array([0, 2, 4])]
>>> planar_cartesian_histogram(positions, edges, dim=2)
array([[1., 0.],
[0., 2.]])
"""
if dim not in {0, 1, 2}:
raise ValueError("'dim' must be one of {0, 1, 2}.")
if positions.ndim != 2:
raise ValueError(
"'positions' must be a 2D array with shape (n_atoms, n_dim)."
)
if len(edges) != 2:
raise ValueError("'edges' must contain two arrays, one for each axis.")
t_dims = np.roll(np.arange(3), -dim)[1:] # selecting transverse axes
hist, _, _ = np.histogram2d(
positions[:, t_dims[0]],
positions[:, t_dims[1]],
bins=edges,
)
n_missed = len(positions) - int(hist.sum())
if n_missed:
raise ValueError(
f"{n_missed} of {len(positions)} positions fall outside the "
f"edges [{edges[0][0]}, {edges[0][-1]}] x "
f"[{edges[1][0]}, {edges[1][-1]}]."
)
# cast: numpy's stubs return Any; at runtime this is an ndarray.
return cast(np.ndarray, hist)