Source code for polyphys.analyze.correlations

"""
==========================================================
:mod:`polyphys.analyze.correlations`
==========================================================


The :mod:`polyphys.analyze.correlations` module measures how a signal is
correlated with itself: the autocorrelation function of a time series with
its confidence band, the decay model fitted to such a curve, and the cosine
correlation between the bond vectors of a polymer chain, from which a
persistence length follows. Every routine is a pure NumPy or SciPy kernel on
arrays; reading time series or frames, choosing the lags to fit, and
averaging over frames are the caller's work.

Notation
========

``x``
    A time series, shape ``(n_frames,)`` or ``(n_frames, n_series)``, in the
    caller's unit; the frames are equally spaced in time and run along axis
    0, and each column is an independent series.
``nlags``
    The largest lag :math:`k` at which the autocorrelation is reported, in
    frames; a lag is the number of frames between the two values compared.
``acf``
    The sample autocorrelation function :math:`r_k`, the covariance of the
    series with itself :math:`k` frames later divided by its variance:
    :math:`r_0 = 1` and :math:`|r_k| \\le 1`.
``half_width``
    The half-width of the confidence interval around :math:`r_k` at level
    :math:`1 - \\alpha`, from Bartlett's large-sample variance of
    :math:`r_k`; the interval is ``acf - half_width`` to
    ``acf + half_width``.
*decay model*
    One of the forms of the stretched exponential (Kohlrausch-Williams-Watts)
    function :math:`A \\exp[-(x / \\tau)^\\beta] + B` listed in
    :data:`DECAY_MODELS`, with the *decay time* :math:`\\tau` in the unit of
    ``x``, the *stretching exponent* :math:`\\beta` (1 for a pure
    exponential), the *amplitude* :math:`A`, and the *offset* :math:`B`.
``positions``
    The coordinates of the monomers of one chain in chain order, shape
    ``(..., n_atoms, n_dims)``, unwrapped (no periodic image breaks a bond);
    any leading axes, such as frames, are carried through.
``topology``
    ``'linear'`` or ``'ring'``: whether the chain's last monomer is bonded
    back to its first.
*bond vector*
    :math:`\\mathbf{b}_i = \\mathbf{r}_{i+1} - \\mathbf{r}_i`, and on a ring
    also :math:`\\mathbf{b}_{n-1} = \\mathbf{r}_0 - \\mathbf{r}_{n-1}`;
    ``n_bonds`` is ``n_atoms - 1`` on a linear chain and ``n_atoms`` on a
    ring. :math:`\\hat{\\mathbf{u}}_i` is the unit bond vector.
*bond cosine correlation*
    :math:`C(k) = \\langle \\hat{\\mathbf{u}}_i \\cdot
    \\hat{\\mathbf{u}}_{i+k} \\rangle`, the mean cosine of the angle between
    two bonds :math:`k` bonds apart along the chain, averaged over the pairs
    in one frame; :math:`C(0) = 1`.

Contents
========

Autocorrelation:
:func:`acf` estimates :math:`r_k` for :math:`k = 0, \\dots,` ``nlags`` by
the fast Fourier transform, with Bartlett's confidence band, as an
:class:`AcfResult`; :func:`bartlett_half_width` is that band on its own,
for a stored :math:`r_k` at any level.

Decay fits:
:data:`DECAY_MODELS` names the decay models; :func:`initial_guess` reads a
starting point for each parameter off the data; :func:`fit_decay` fits a
model with :func:`scipy.optimize.curve_fit` and reports the parameters,
their standard errors, and whether the fit converged as a
:class:`DecayFit`, whose :meth:`DecayFit.evaluate` draws the fitted curve.

Bonds:
:func:`bond_vectors` differences the positions along the chain;
:func:`bond_cosine_correlation` averages the cosines between bond pairs at
every lag by the fast Fourier transform.

Conventions
===========

- The autocorrelation uses the ``1/n_frames`` estimator of the
  autocovariance at every lag, which keeps the sequence positive
  semi-definite and is the default of ``statsmodels.tsa.stattools.acf``;
  dividing by ``n_frames - k`` instead is unbiased per lag but can give
  :math:`|r_k| > 1`.
- Bartlett's variance for lag :math:`k` sums the squared autocorrelations at
  the lags below it, :math:`\\mathrm{var}(r_k) = (1 + 2 \\sum_{j=1}^{k-1}
  r_j^2) / n_\\mathrm{frames}` for :math:`k \\ge 2`, with
  :math:`\\mathrm{var}(r_1) = 1 / n_\\mathrm{frames}` and
  :math:`\\mathrm{var}(r_0) = 0`; this is the convention of
  ``statsmodels``, so a band computed here matches one computed there.
- Decay models are written in the decay time :math:`\\tau`, not the rate
  :math:`\\omega = \\tau^{-\\beta}` of some research code; convert with
  :math:`\\tau = \\omega^{-1/\\beta}`.
- A failed fit never raises: :attr:`DecayFit.converged` is false and the
  parameters are NaN.
- On a ring every lag :math:`k` has ``n_bonds`` pairs, going round the ring,
  so :math:`C(k) = C(n_\\mathrm{bonds} - k)` and the lags that carry
  information are :math:`0 \\le k \\le n_\\mathrm{bonds} / 2`. On a linear
  chain lag :math:`k` has ``n_bonds - k`` pairs.
- Complexities are stated per call in ``n_frames`` (:math:`n`),
  ``n_series`` (:math:`m`), ``n_bonds`` (:math:`N`), the number of leading
  frames of a positions array (:math:`F`), and ``n_points`` of a fit.

References
==========

- M. S. Bartlett, "On the theoretical specification and sampling properties
  of autocorrelated time-series", Supplement to the Journal of the Royal
  Statistical Society 8, 27-41 (1946). https://doi.org/10.2307/2983611
- NIST/SEMATECH e-Handbook of Statistical Methods, section 1.3.3.1,
  "Autocorrelation Plot".
  https://www.itl.nist.gov/div898/handbook/eda/section3/autocopl.htm
- G. Williams and D. C. Watts, "Non-symmetrical dielectric relaxation
  behavior arising from a simple empirical decay function", Trans. Faraday
  Soc. 66, 80-85 (1970). https://doi.org/10.1039/TF9706600080
- SciPy, :func:`scipy.optimize.curve_fit`.
  https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.curve_fit.html
- M. Rubinstein and R. H. Colby, Polymer Physics (Oxford University Press,
  2003), Chapter 2, on the bond correlation and the persistence length.
- MDAnalysis, :class:`MDAnalysis.analysis.polymer.PersistenceLength`, the
  same bond autocorrelation and exponential fit for linear chains.
  https://docs.mdanalysis.org/stable/documentation_pages/analysis/polymer.html
- MDAnalysis User Guide, "Determining the persistence length of a polymer".
  https://userguide.mdanalysis.org/stable/examples/analysis/polymers_and_membranes/polymer.html

.. versionadded:: 0.6.0
"""

import logging
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from typing import Any, Literal

import numpy as np
import numpy.typing as npt
from scipy.optimize import curve_fit
from scipy.stats import norm

__all__ = [
    'AcfResult',
    'DECAY_MODELS',
    'DecayFit',
    'DecayModel',
    'Topology',
    'acf',
    'bartlett_half_width',
    'bond_cosine_correlation',
    'bond_vectors',
    'fit_decay',
    'initial_guess',
]

logger = logging.getLogger(__name__)

Topology = Literal['linear', 'ring']
"""The polymer topologies the bond vectors are defined for."""

FloatArray = npt.NDArray[np.float64]
ModelFunction = Callable[..., FloatArray]


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}'."
        )


def _fft_length(n: int) -> int:
    """Return the smallest power of two that is at least ``2 n - 1``."""
    return 1 << (2 * n - 1).bit_length()


# ---------------------------------------------------------------------------
# Autocorrelation
# ---------------------------------------------------------------------------


[docs] @dataclass(frozen=True) class AcfResult: """ The sample autocorrelation of one or more time series. .. versionadded:: 0.6.0 Attributes ---------- values : numpy.ndarray :math:`r_k` for lags ``0`` to ``nlags``, shape ``(nlags + 1,)`` for a one-dimensional series or ``(nlags + 1, n_series)`` for columns. ``values[0]`` is 1. half_width : numpy.ndarray or None The half-width of the confidence interval around each value at level ``1 - alpha``, the same shape as `values`; ``half_width[0]`` is 0. ``None`` when no band was asked for. alpha : float or None The significance level of the band, or ``None``. """ values: FloatArray half_width: FloatArray | None alpha: float | None
[docs] def acf( x: npt.ArrayLike, nlags: int, alpha: float | None = 0.05, ) -> AcfResult: """ Estimate the autocorrelation function of a time series by the FFT. Parameters ---------- x : array_like The time series, shape ``(n_frames,)`` or ``(n_frames, n_series)``, with the frames along axis 0 and one series per column; every value finite, and no series constant. nlags : int The largest lag, in frames, from 0 to ``n_frames - 1``. alpha : float or None, default 0.05 The significance level of the confidence band, in ``(0, 1)``; 0.05 gives a 95 % band. ``None`` skips the band. Returns ------- AcfResult The autocorrelation at lags 0 to `nlags` and its band. Raises ------ ValueError If `x` is not one- or two-dimensional or has fewer than two frames, holds a non-finite value, or has a constant series; if `nlags` is outside ``[0, n_frames - 1]``; or if `alpha` is outside ``(0, 1)``. Notes ----- With :math:`\\bar{x}` the mean of the series, the autocovariance is :math:`c_k = \\frac{1}{n} \\sum_{t=0}^{n-k-1} (x_t - \\bar{x}) (x_{t+k} - \\bar{x})` and :math:`r_k = c_k / c_0` (NIST/SEMATECH e-Handbook, section 1.3.3.1). The sum over :math:`t` for every :math:`k` is one linear correlation, computed as the inverse transform of the squared magnitude of the series' Fourier transform after zero-padding to at least :math:`2n - 1` points so that no wrap-around enters (Wiener-Khinchin). The band is Bartlett's (1946) large-sample approximation under the hypothesis that the autocorrelation vanishes beyond lag :math:`k - 1`: :math:`\\mathrm{var}(r_k) \\approx (1 + 2 \\sum_{j=1}^{k-1} r_j^2) / n`, so the band widens with the lag, and the half-width is :math:`z_{1-\\alpha/2} \\sqrt{\\mathrm{var}(r_k)}` with :math:`z` the standard normal quantile. For a white-noise series it reduces to :math:`\\pm z_{1-\\alpha/2} / \\sqrt{n}`. The approximation needs :math:`n \\gg` `nlags`. Time is :math:`O(m\\, n \\log n)` and space :math:`O(m\\, n)`, with :math:`n` the frames and :math:`m` the series. Examples -------- The alternating series ``1, -1, 1, -1, ...`` of 8 frames has mean 0, :math:`c_k = (-1)^k (8 - k) / 8`, and so :math:`r_1 = -7/8` and :math:`r_2 = 6/8`: >>> import numpy as np >>> from polyphys.analyze.correlations import acf >>> x = np.tile([1.0, -1.0], 4) >>> result = acf(x, nlags=2) >>> np.round(result.values, 6) array([ 1. , -0.875, 0.75 ]) The 95 % band is 0 at lag 0, :math:`1.96 / \\sqrt{8}` at lag 1, and wider at lag 2 because :math:`r_1^2` enters: >>> np.round(result.half_width, 4) array([0. , 0.693 , 1.1025]) .. versionadded:: 0.6.0 """ series = np.asarray(x, dtype=np.float64) if series.ndim not in (1, 2): raise ValueError( f'x must be one- or two-dimensional; got {series.ndim}' ' dimension(s).' ) n_frames = series.shape[0] if n_frames < 2: raise ValueError(f'x must have at least two frames; got {n_frames}.') if not np.all(np.isfinite(series)): raise ValueError('x must be finite.') if not 0 <= nlags < n_frames: raise ValueError( f'nlags must be between 0 and n_frames - 1 = {n_frames - 1};' f' got {nlags}.' ) if alpha is not None and not 0 < alpha < 1: raise ValueError(f'alpha must be in (0, 1); got {alpha}.') if np.any(np.all(series == series[0], axis=0)): raise ValueError('x has a constant series; its acf is undefined.') centered = series - series.mean(axis=0) n_fft = _fft_length(n_frames) spectrum = np.fft.rfft(centered, n=n_fft, axis=0) autocov = np.fft.irfft(np.abs(spectrum) ** 2, n=n_fft, axis=0) autocov = autocov[: nlags + 1] / n_frames values: FloatArray = autocov / autocov[0] values[0] = 1.0 half_width: FloatArray | None = None if alpha is not None: half_width = bartlett_half_width(values, n_frames, alpha) return AcfResult(values=values, half_width=half_width, alpha=alpha)
[docs] def bartlett_half_width( values: npt.ArrayLike, n_frames: int, alpha: float = 0.05, ) -> FloatArray: """ The half-width of Bartlett's confidence band around an autocorrelation. Parameters ---------- values : array_like The sample autocorrelation :math:`r_k` for lags 0 to ``nlags``, shape ``(nlags + 1,)`` or ``(nlags + 1, n_series)``, as :func:`acf` returns it. n_frames : int The number of frames the autocorrelation was estimated from, at least 2. alpha : float, default 0.05 The significance level of the band, in ``(0, 1)``; 0.05 gives a 95 % band. Returns ------- numpy.ndarray The half-width at each lag, the same shape as `values`, ``float64``; 0 at lag 0. The band is ``values - half_width`` to ``values + half_width``. Raises ------ ValueError If `values` is not one- or two-dimensional, `n_frames` is below 2, or `alpha` is outside ``(0, 1)``. Notes ----- Bartlett's (1946) large-sample variance under the hypothesis that the autocorrelation vanishes beyond lag :math:`k - 1` is :math:`\\mathrm{var}(r_k) \\approx (1 + 2 \\sum_{j=1}^{k-1} r_j^2) / n`, and the half-width is :math:`z_{1-\\alpha/2} \\sqrt{\\mathrm{var}(r_k)}`. The band depends on the stored :math:`r_k`, `n_frames`, and `alpha` only, so a pipeline need store the autocorrelation alone and draw the band at any level later. Time and space are :math:`O(m\\, k)`, with :math:`k` the lags and :math:`m` the series. Examples -------- The band of the alternating series of :func:`acf`'s example, rebuilt from its autocorrelation: >>> import numpy as np >>> from polyphys.analyze.correlations import bartlett_half_width >>> np.round(bartlett_half_width([1.0, -0.875, 0.75], 8), 4) array([0. , 0.693 , 1.1025]) .. versionadded:: 0.6.0 """ acf_values = np.asarray(values, dtype=np.float64) if acf_values.ndim not in (1, 2): raise ValueError( f'values must be one- or two-dimensional; got {acf_values.ndim}' ' dimension(s).' ) if n_frames < 2: raise ValueError(f'n_frames must be at least 2; got {n_frames}.') if not 0 < alpha < 1: raise ValueError(f'alpha must be in (0, 1); got {alpha}.') variance = np.full_like(acf_values, 1.0 / n_frames) variance[0] = 0.0 if acf_values.shape[0] > 2: variance[2:] *= 1.0 + 2.0 * np.cumsum(acf_values[1:-1] ** 2, axis=0) z_score = float(norm.ppf(1.0 - alpha / 2.0)) half_width: FloatArray = z_score * np.sqrt(variance) return half_width
# --------------------------------------------------------------------------- # Decay fits # --------------------------------------------------------------------------- def _exp(x: FloatArray, tau: float) -> FloatArray: """:math:`\\exp(-x / \\tau)`.""" return np.asarray(np.exp(-x / tau), dtype=np.float64) def _stretched(x: FloatArray, tau: float, beta: float) -> FloatArray: """:math:`\\exp[-(x / \\tau)^\\beta]`.""" return np.asarray(np.exp(-((x / tau) ** beta)), dtype=np.float64) def _stretched_amp( x: FloatArray, tau: float, beta: float, amp: float ) -> FloatArray: """:math:`A \\exp[-(x / \\tau)^\\beta]`.""" return amp * _stretched(x, tau, beta) def _stretched_amp_offset( x: FloatArray, tau: float, beta: float, amp: float, offset: float ) -> FloatArray: """:math:`A \\exp[-(x / \\tau)^\\beta] + B`.""" return amp * _stretched(x, tau, beta) + offset
[docs] @dataclass(frozen=True) class DecayModel: """ A decay model: its function, parameter names, and formula. .. versionadded:: 0.6.0 Attributes ---------- function : callable ``function(x, *params)``, vectorized over `x`. names : tuple of str The parameter names in the order `function` takes them, from ``'tau'``, ``'beta'``, ``'amp'``, and ``'offset'``. formula : str The model as a formula, for labels. """ function: ModelFunction names: tuple[str, ...] formula: str
DECAY_MODELS: Mapping[str, DecayModel] = { 'exp': DecayModel(_exp, ('tau',), 'exp(-x/tau)'), 'stretched': DecayModel( _stretched, ('tau', 'beta'), 'exp(-(x/tau)^beta)' ), 'stretched_amp': DecayModel( _stretched_amp, ('tau', 'beta', 'amp'), 'amp exp(-(x/tau)^beta)' ), 'stretched_amp_offset': DecayModel( _stretched_amp_offset, ('tau', 'beta', 'amp', 'offset'), 'amp exp(-(x/tau)^beta) + offset', ), } """ The decay models :func:`fit_decay` accepts, by name. ``'exp'`` is the pure exponential :math:`\\exp(-x/\\tau)`; ``'stretched'`` the Kohlrausch-Williams-Watts form :math:`\\exp[-(x/\\tau)^\\beta]`; ``'stretched_amp'`` scales it by an amplitude :math:`A`; and ``'stretched_amp_offset'`` adds an offset :math:`B`. The parameters are ordered ``tau``, ``beta``, ``amp``, ``offset``. :math:`\\tau` is in the unit of ``x`` and positive; :math:`\\beta` is positive, 1 for a pure exponential. .. versionadded:: 0.6.0 """ def _get_model(model: str) -> DecayModel: """Return the :class:`DecayModel` named `model` or raise ``ValueError``.""" try: return DECAY_MODELS[model] except KeyError: names = ', '.join(repr(name) for name in DECAY_MODELS) raise ValueError( f"model must be one of {names}; got '{model}'." ) from None def _as_curve( x: npt.ArrayLike, y: npt.ArrayLike ) -> tuple[FloatArray, FloatArray]: """Return `x` and `y` as finite one-dimensional arrays of one length.""" x_arr = np.asarray(x, dtype=np.float64) y_arr = np.asarray(y, dtype=np.float64) if x_arr.ndim != 1 or y_arr.ndim != 1: raise ValueError( 'x and y must be one-dimensional; got' f' {x_arr.ndim} and {y_arr.ndim} dimension(s).' ) if x_arr.shape != y_arr.shape: raise ValueError( f'x and y must have the same length; got {x_arr.size} and' f' {y_arr.size}.' ) if not (np.all(np.isfinite(x_arr)) and np.all(np.isfinite(y_arr))): raise ValueError('x and y must be finite.') return x_arr, y_arr
[docs] @dataclass(frozen=True) class DecayFit: """ The result of fitting a decay model to a curve. .. versionadded:: 0.6.0 Attributes ---------- model : str The key of the model in :data:`DECAY_MODELS`. names : tuple of str The parameter names, in the order of `params`. params : numpy.ndarray The fitted parameters, shape ``(n_params,)``; all NaN when the fit did not converge. stderr : numpy.ndarray The standard error of each parameter, the square root of the diagonal of `pcov`; NaN where the covariance could not be estimated or the fit did not converge. pcov : numpy.ndarray The estimated covariance of the parameters, shape ``(n_params, n_params)``, as :func:`scipy.optimize.curve_fit` returns it; all NaN when the fit did not converge. p0 : numpy.ndarray The starting point the fit used, shape ``(n_params,)``. converged : bool Whether :func:`scipy.optimize.curve_fit` returned a solution. """ model: str names: tuple[str, ...] params: FloatArray stderr: FloatArray pcov: FloatArray p0: FloatArray converged: bool
[docs] def evaluate(self, x: npt.ArrayLike) -> FloatArray: """ Evaluate the fitted model at `x`. Parameters ---------- x : array_like Points in the unit of the fitted ``x``. Returns ------- numpy.ndarray The model at `x`, the same shape; all NaN when the fit did not converge. Examples -------- >>> import numpy as np >>> from polyphys.analyze.correlations import fit_decay >>> x = np.arange(0.0, 20.0) >>> fit = fit_decay(x, np.exp(-x / 4.0), 'exp') >>> np.round(fit.evaluate([0.0, 4.0]), 6) array([1. , 0.367879]) """ return DECAY_MODELS[self.model].function( np.asarray(x, dtype=np.float64), *self.params )
[docs] def initial_guess( x: npt.ArrayLike, y: npt.ArrayLike, model: str ) -> FloatArray: """ Read a starting point for each parameter of a decay model off the data. Parameters ---------- x : array_like The abscissa, shape ``(n_points,)``, finite, increasing, and non-negative, in the caller's unit (lags in frames, or time). y : array_like The curve at `x`, the same shape, finite. model : str A key of :data:`DECAY_MODELS`. Returns ------- numpy.ndarray One value per parameter of the model, in its order. Raises ------ ValueError If `model` is unknown, or `x` and `y` are not finite one-dimensional arrays of one length. Notes ----- The offset :math:`B` is the mean of the last tenth of `y` (at least one point); the amplitude :math:`A` is ``y[0] - B``, or 1 when that is 0; the decay time :math:`\\tau` is the first `x` at which :math:`(y - B) / A` is at or below :math:`1/e`, which is exact for a pure exponential sampled at :math:`\\tau`, or the last `x` when the curve never falls that far; and :math:`\\beta` is 1. A model without an offset takes :math:`B = 0`; one without an amplitude takes :math:`A = 1`. A :math:`\\tau` of 0 (the curve is already at :math:`1/e` at ``x[0] = 0``) is replaced by the first positive `x`, or 1. Time and space are :math:`O(n_\\mathrm{points})`. Examples -------- A pure exponential of decay time 4 crosses :math:`1/e` at ``x = 4``: >>> import numpy as np >>> from polyphys.analyze.correlations import initial_guess >>> x = np.arange(0.0, 20.0) >>> initial_guess(x, np.exp(-x / 4.0), 'exp') array([4.]) The offset is read off the tail, so it is a starting point, not the answer: >>> y = 2.0 * np.exp(-x / 4.0) + 0.5 >>> np.round(initial_guess(x, y, 'stretched_amp_offset'), 2) array([4. , 1. , 1.98, 0.52]) .. versionadded:: 0.6.0 """ spec = _get_model(model) x_arr, y_arr = _as_curve(x, y) n_points = x_arr.size if n_points == 0: raise ValueError('x and y must not be empty.') offset = 0.0 if 'offset' in spec.names: offset = float(np.mean(y_arr[-max(1, n_points // 10):])) amp = 1.0 if 'amp' in spec.names: amp = float(y_arr[0] - offset) if amp == 0.0: amp = 1.0 decayed = (y_arr - offset) / amp below = np.flatnonzero(decayed <= np.exp(-1.0)) tau = float(x_arr[below[0]]) if below.size else float(x_arr[-1]) if tau <= 0.0: positive = np.flatnonzero(x_arr > 0.0) tau = float(x_arr[positive[0]]) if positive.size else 1.0 guesses = {'tau': tau, 'beta': 1.0, 'amp': amp, 'offset': offset} return np.array([guesses[name] for name in spec.names], dtype=np.float64)
[docs] def fit_decay( x: npt.ArrayLike, y: npt.ArrayLike, model: str, p0: npt.ArrayLike | None = None, **kwargs: Any, ) -> DecayFit: """ Fit a decay model to a curve by nonlinear least squares. Parameters ---------- x : array_like The abscissa, shape ``(n_points,)``, finite, in the caller's unit (lags in frames, or time). Fit only the range meant for the model: on an autocorrelation, the lags the model describes; on a ring's bond correlation, lags up to ``n_bonds // 2``. y : array_like The curve at `x`, the same shape, finite. model : str A key of :data:`DECAY_MODELS`. p0 : array_like or None, default None The starting point, one value per parameter of the model, in its order. ``None`` takes :func:`initial_guess`. **kwargs Passed to :func:`scipy.optimize.curve_fit`: ``bounds``, ``sigma``, ``absolute_sigma``, ``maxfev``, ``method``, and the rest. Returns ------- DecayFit The parameters, their standard errors, the covariance, the starting point used, and whether the fit converged. Raises ------ ValueError If `model` is unknown; `x` and `y` are not finite one-dimensional arrays of one length; there are fewer points than parameters; or `p0` has the wrong length. :func:`scipy.optimize.curve_fit` also raises :exc:`ValueError` for an invalid option in `kwargs`, such as an unknown ``method`` or a `p0` outside ``bounds``. Notes ----- :func:`scipy.optimize.curve_fit` minimizes the sum of squared residuals from `p0`, by default with the Levenberg-Marquardt method (``'lm'``), or with ``'trf'`` when ``bounds`` are given, as its documentation states; ``method`` in `kwargs` chooses another. A nonlinear model can have several local minima, so `p0` matters, and the one used is recorded. A fit fails when the model is not finite at the start, when the optimizer stops without a solution, or when it does not move from the start and the covariance cannot be estimated, which is how the ``'lm'`` method signals a Jacobian that is zero or rank-deficient (the :func:`scipy.optimize.curve_fit` documentation, under ``pcov``). A failed fit is reported with ``converged=False``, NaN parameters, and a warning in the :mod:`logging` log, not an exception; invalid inputs or options still raise (see Raises). When the fit moves but the covariance cannot be estimated (SciPy emits an ``OptimizeWarning``), it is converged and the standard errors of the affected parameters are NaN. A start at the exact solution of noise-free data does not move either, but its covariance is finite, so it is converged. The standard error is the square root of the covariance diagonal, as in SciPy's documentation. The models are the stretched exponential of Williams and Watts (1970), Trans. Faraday Soc. 66, 80, https://doi.org/10.1039/TF9706600080, with :math:`\\beta = 1` for the pure exponential. Time is :math:`O(n_\\mathrm{iter}\\, n_\\mathrm{points}\\, n_\\mathrm{params})` and space :math:`O(n_\\mathrm{points}\\, n_\\mathrm{params})`. Examples -------- >>> import numpy as np >>> from polyphys.analyze.correlations import fit_decay >>> x = np.arange(0.0, 40.0) >>> y = 2.0 * np.exp(-((x / 5.0) ** 0.8)) + 0.3 >>> fit = fit_decay(x, y, 'stretched_amp_offset') >>> fit.converged True >>> fit.names ('tau', 'beta', 'amp', 'offset') >>> np.round(fit.params, 6) array([5. , 0.8, 2. , 0.3]) .. versionadded:: 0.6.0 .. versionchanged:: 0.9.0 A start where the model is not finite, and a fit that does not move and has no finite covariance, are failed fits; ``method='trf'`` no longer raises on a non-finite start. """ spec = _get_model(model) x_arr, y_arr = _as_curve(x, y) n_params = len(spec.names) if x_arr.size < n_params: raise ValueError( f"model '{model}' has {n_params} parameter(s) but x has only" f' {x_arr.size} point(s).' ) if p0 is None: start = initial_guess(x_arr, y_arr, model) else: start = np.asarray(p0, dtype=np.float64) if start.shape != (n_params,): raise ValueError( f"p0 must have one value per parameter of '{model}'," f' {spec.names}; got shape {start.shape}.' ) nan_params = np.full(n_params, np.nan) failed = DecayFit( model=model, names=spec.names, params=nan_params, stderr=nan_params.copy(), pcov=np.full((n_params, n_params), np.nan), p0=start, converged=False, ) # A start where the model is not finite cannot be fitted: 'lm' stays # there and 'trf' raises, so it is reported as a failed fit up front. with np.errstate(invalid='ignore', divide='ignore', over='ignore'): at_start = spec.function(x_arr, *start) if not np.all(np.isfinite(at_start)): logger.warning( "fit_decay: '%s' is not finite at the start %s; the fit failed.", model, start, ) return failed try: params, pcov = curve_fit( spec.function, x_arr, y_arr, p0=start, **kwargs ) except RuntimeError as error: logger.warning("fit_decay: '%s' did not converge: %s", model, error) return failed params = np.asarray(params, dtype=np.float64) pcov = np.asarray(pcov, dtype=np.float64) diagonal = np.diag(pcov) if np.array_equal(params, start) and not np.all(np.isfinite(pcov)): logger.warning( "fit_decay: '%s' did not move from the start %s and its" ' covariance could not be estimated; the fit failed.', model, start, ) return failed stderr = np.where(np.isfinite(diagonal), np.sqrt(np.abs(diagonal)), np.nan) if not np.all(np.isfinite(diagonal)): logger.warning( "fit_decay: '%s' converged but its covariance could not be" ' estimated.', model, ) return DecayFit( model=model, names=spec.names, params=params, stderr=np.asarray(stderr, dtype=np.float64), pcov=pcov, p0=start, converged=True, )
# --------------------------------------------------------------------------- # Bonds # ---------------------------------------------------------------------------
[docs] def bond_vectors( positions: npt.ArrayLike, topology: Topology ) -> FloatArray: """ Difference the positions of a chain into its bond vectors. Parameters ---------- positions : array_like The monomer coordinates in chain order, shape ``(..., n_atoms, n_dims)``, unwrapped, in the caller's length unit; ``n_atoms`` at least 2 on a linear chain and 3 on a ring. topology : {'linear', 'ring'} Whether the last monomer is bonded back to the first. Returns ------- numpy.ndarray The bond vectors :math:`\\mathbf{r}_{i+1} - \\mathbf{r}_i`, shape ``(..., n_bonds, n_dims)``, with ``n_bonds = n_atoms - 1`` on a linear chain and ``n_atoms`` on a ring, whose last bond is :math:`\\mathbf{r}_0 - \\mathbf{r}_{n-1}`. Bond lengths are ``numpy.linalg.norm(bonds, axis=-1)``. Raises ------ ValueError If `topology` is unknown, `positions` has fewer than two dimensions, or the chain is too short for its topology. Notes ----- Positions must be unwrapped: a periodic image jump inside a bond gives a bond of the box length. Time and space are :math:`O(F\\, n_\\mathrm{atoms}\\, n_\\mathrm{dims})`. Examples -------- >>> import numpy as np >>> from polyphys.analyze.correlations import bond_vectors >>> square = np.array([[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]]) >>> bond_vectors(square, 'linear') array([[ 1., 0.], [ 0., 1.], [-1., 0.]]) >>> bond_vectors(square, 'ring')[-1] array([ 0., -1.]) .. versionadded:: 0.6.0 """ _check_topology(topology) coords = np.asarray(positions, dtype=np.float64) if coords.ndim < 2: raise ValueError( 'positions must have shape (..., n_atoms, n_dims); got' f' {coords.ndim} dimension(s).' ) n_atoms = coords.shape[-2] minimum = 2 if topology == 'linear' else 3 if n_atoms < minimum: raise ValueError( f"a '{topology}' chain needs at least {minimum} atoms; got" f' {n_atoms}.' ) if topology == 'linear': return np.asarray(coords[..., 1:, :] - coords[..., :-1, :]) return np.asarray(np.roll(coords, -1, axis=-2) - coords)
[docs] def bond_cosine_correlation( positions: npt.ArrayLike, topology: Topology ) -> FloatArray: """ Average the cosine between bond vectors at every lag along a chain. Parameters ---------- positions : array_like The monomer coordinates in chain order, shape ``(..., n_atoms, n_dims)``, unwrapped; no two bonded monomers coincide. topology : {'linear', 'ring'} Whether the last monomer is bonded back to the first. Returns ------- numpy.ndarray :math:`C(k)` for lags ``0`` to ``n_bonds - 1``, shape ``(..., n_bonds)``, dimensionless in ``[-1, 1]`` with ``C(0) = 1``. Leading axes are kept, so the average over frames is ``result.mean(axis=0)`` for a ``(n_frames, n_atoms, n_dims)`` input. Raises ------ ValueError If `topology` is unknown, `positions` has a bad shape or a chain too short for its topology, or a bond has zero length. Notes ----- With :math:`\\hat{\\mathbf{u}}_i` the unit bond vectors, on a linear chain :math:`C(k) = \\frac{1}{N - k} \\sum_{i=0}^{N-k-1} \\hat{\\mathbf{u}}_i \\cdot \\hat{\\mathbf{u}}_{i+k}` over the :math:`N - k` pairs at lag :math:`k`; on a ring :math:`C(k) = \\frac{1}{N} \\sum_{i=0}^{N-1} \\hat{\\mathbf{u}}_i \\cdot \\hat{\\mathbf{u}}_{(i+k) \\bmod N}` over all :math:`N` pairs, so that the result does not depend on which monomer is labeled first and :math:`C(k) = C(N - k)`. The sums over :math:`i` are linear (zero-padded) or circular autocorrelations, computed by the FFT of each Cartesian component and summed over components. For a worm-like chain :math:`C(k) = \\exp(-k\\, b / \\ell_p)` with :math:`b` the bond length and :math:`\\ell_p` the persistence length (Rubinstein and Colby 2003, section 2.3), so fitting ``'exp'`` with :func:`fit_decay` on lags up to ``n_bonds // 2`` for a ring gives :math:`\\tau = \\ell_p / b`, and :math:`\\ell_p` is :math:`\\tau` times the mean bond length. On a linear chain this is the quantity and the fit of :class:`MDAnalysis.analysis.polymer.PersistenceLength` (``results.bond_autocorrelation``, ``results.lb``, ``results.lp``), which averages over chains and frames and does not treat rings. Time is :math:`O(F\\, N \\log N)` and space :math:`O(F\\, N)` for :math:`F` frames of :math:`N` bonds, against the :math:`O(F\\, N^2)` of the pairwise matrix. Examples -------- The bonds of a square ring turn by a right angle each, so :math:`C(k) = \\cos(\\pi k / 2)`: >>> import numpy as np >>> from polyphys.analyze.correlations import bond_cosine_correlation >>> square = np.array([[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]]) >>> np.round(bond_cosine_correlation(square, 'ring'), 12) array([ 1., 0., -1., 0.]) A straight rod has every bond parallel: >>> rod = np.outer(np.arange(4.0), [1.0, 2.0, 2.0]) >>> np.round(bond_cosine_correlation(rod, 'linear'), 12) array([1., 1., 1.]) .. versionadded:: 0.6.0 """ bonds = bond_vectors(positions, topology) lengths = np.linalg.norm(bonds, axis=-1) if np.any(lengths == 0.0): raise ValueError('every bond must have a positive length.') units = bonds / lengths[..., np.newaxis] # Put the bond axis last so the FFT runs along it, per component. components = np.swapaxes(units, -1, -2) n_bonds = components.shape[-1] if topology == 'linear': n_fft = _fft_length(n_bonds) pairs: FloatArray = np.arange(n_bonds, 0, -1, dtype=np.float64) else: n_fft = n_bonds pairs = np.full(n_bonds, float(n_bonds)) spectrum = np.fft.rfft(components, n=n_fft, axis=-1) power = np.sum(np.abs(spectrum) ** 2, axis=-2) sums = np.fft.irfft(power, n=n_fft, axis=-1)[..., :n_bonds] return np.asarray(sums / pairs, dtype=np.float64)