Source code for morphogen.analysis.covariance

"""Covariance (two-point probability) functions of images.

``C(h) = P(x in A, x + h in A)`` is estimated with fast Fourier transforms: circularly
for periodic images, with zero padding and normalization by the number of pairs
otherwise. ``C(0)`` is the volume fraction and ``C(h) -> p^2`` when correlations vanish.
"""

from __future__ import annotations

from dataclasses import dataclass

import numpy as np
from scipy import fft as sfft

from morphogen import settings
from morphogen.analysis.basic import indicator
from morphogen.image import VoxelImage

_ROWS = 1 << 15


[docs] @dataclass class AxisFunction: """A function of the lags along the x, y and z axes (the covariance, the lineal-path and two-point cluster functions of :mod:`morphogen.analysis.correlation`).""" lags: dict[str, np.ndarray] values: dict[str, np.ndarray] volume_fraction: float
[docs] def mean(self) -> tuple[np.ndarray, np.ndarray]: """Average of the three axes (requires cubic voxels and equal lengths).""" n = min(len(v) for v in self.values.values()) lags = self.lags["x"][:n] return lags, np.mean([v[:n] for v in self.values.values()], axis=0)
[docs] class AxisCovariance(AxisFunction): """Covariance along the x, y and z axes."""
def _axis_correlation(field: np.ndarray, axis: int, max_lag: int, periodic: bool) -> np.ndarray: x = np.moveaxis(field, axis, -1) n = x.shape[-1] rows = x.reshape(-1, n) size = n if periodic else int(sfft.next_fast_len(2 * n)) acc = np.zeros(max_lag + 1) for start in range(0, rows.shape[0], _ROWS): block = rows[start : start + _ROWS].astype(np.float64) f = sfft.rfft(block, n=size, axis=-1, workers=settings.workers()) corr = sfft.irfft(f * np.conj(f), n=size, axis=-1, workers=settings.workers()) acc += corr[:, : max_lag + 1].sum(axis=0) pairs = rows.shape[0] * (n if periodic else (n - np.arange(max_lag + 1))) return acc / pairs
[docs] def covariance(image, phase: int = 1, *, max_lag: int | None = None, periodic=None): """Covariance of ``phase`` along the three axes, for lags 0..max_lag voxels. ``max_lag`` defaults to half the image size along each axis. """ field = indicator(image, phase) spacing = image.spacing if isinstance(image, VoxelImage) else (1.0, 1.0, 1.0) if periodic is None: periodic = image.periodic if isinstance(image, VoxelImage) else False lags, values = {}, {} for axis, name in enumerate("xyz"): n = field.shape[axis] m = n // 2 if max_lag is None else min(int(max_lag), n - 1) values[name] = _axis_correlation(field, axis, m, periodic) lags[name] = np.arange(m + 1) * spacing[axis] return AxisCovariance(lags, values, float(np.mean(field, dtype=np.float64)))
[docs] def covariance_map(image, phase: int = 1) -> np.ndarray: """Full 3D covariance of a periodic image, zero lag at the centre (fftshift order).""" field = indicator(image, phase).astype(np.float64) f = sfft.rfftn(field, workers=settings.workers()) corr = sfft.irfftn(f * np.conj(f), s=field.shape, workers=settings.workers()) / field.size return sfft.fftshift(corr)