"""Stereology: the sections of a phase by the planes of the grid, and the recovery of the
size distribution of its particles from them (Wicksell 1925; Saltykov 1967), for spheres
and for aligned ellipsoids of a common shape and orientation, as Degdeg & Dirrenberger
for the pores of a copper foam.
A plane normal to the unit vector ``n`` at the distance ``d`` from the centre of the
ellipsoid ``x . M x = 1``, ``M^-1 = R diag(a^2, b^2, c^2) R^T``, cuts it in an ellipse of
area ``pi abc (s - d^2) / s^(3/2)``, ``s = n . M^-1 n``. Uniformly placed particles have
``u = d / sqrt(s)`` uniform over ``[-1, 1]``: the equivalent radius of their sections is
``r = r_max sqrt(1 - u^2)``, the law of a sphere, ``F(v) = 1 - sqrt(1 - v^2)`` for
``v = r / r_max``, with ``r_max = kappa a``, ``kappa = sqrt(l1 l2) / s_hat^(1/4)`` for the
shape factors ``l1 = b/a``, ``l2 = c/a`` and ``s_hat = n . R diag(1, l1^2, l2^2) R^T n``;
the planes of a family cut the particles in proportion to their height ``H = 2 a
sqrt(s_hat)``. On classes of radii of width ``delta``, a particle of the 3D class ``I``
(``r_max = I delta``) gives a section of the 2D class ``J <= I`` with the probability
``P_IJ = (sqrt(I^2 - (J - 1)^2) - sqrt(I^2 - J^2)) / I`` (the Scheil–Schwartz–Saltykov
matrix), so that the areal densities of the sections are ``N_A,J = sum_I P_IJ H_I N_V,I``,
inverted class by class from the largest.
"""
from __future__ import annotations
from dataclasses import dataclass
import numpy as np
from scipy import ndimage
from morphogen.analysis.basic import indicator
from morphogen.distributions import Discrete
from morphogen.image import VoxelImage
#: In-plane 8-connectivity of the slices of a stack whose first axis is normal to them.
_PLANE = np.zeros((3, 3, 3), dtype=bool)
_PLANE[1] = True
[docs]
@dataclass
class Sections:
"""The sections of a phase by the planes normal to ``axis``: their equivalent radii
``sqrt(area / pi)``, their weights (1, or the Miles–Lantuéjoul factor of a section
inside the frame of a non-periodic image) and the total area of the planes."""
axis: int
radii: np.ndarray
weights: np.ndarray
area: float
[docs]
def areal_density(self, edges) -> np.ndarray:
"""Sections per unit area in the classes of radii between ``edges``."""
counts, _ = np.histogram(self.radii, bins=edges, weights=self.weights)
return counts / self.area
[docs]
def mean_radius(self) -> float:
"""Number mean of the section radii."""
return float(np.average(self.radii, weights=self.weights))
def _separate(work: np.ndarray, h, prominence) -> np.ndarray:
"""Watershed of the distance map of each slice from its maxima of the given
prominence (and the highest point of each section)."""
from morphogen.kernels.watershed import flood, prominent_maxima
prominence = 0.5 * min(h) if prominence is None else float(prominence)
out = np.zeros(work.shape, dtype=np.int32)
count = 0
for k in range(work.shape[0]):
mask = work[k]
if not mask.any():
continue
dist = ndimage.distance_transform_edt(mask, sampling=h)
peaks = prominent_maxima(dist, mask, prominence)
markers, m = ndimage.label(peaks, structure=np.ones((3, 3), dtype=bool))
markers = markers.astype(np.int32)
markers[~mask] = -1
flood(-dist, markers)
markers[~mask] = 0
out[k] = np.where(markers > 0, markers + count, 0)
count += m
return out
[docs]
def section_sizes(
image,
phase: int = 1,
axis: int = 2,
*,
separate: bool = False,
prominence: float | None = None,
min_radius: float = 0.0,
periodic=None,
) -> Sections:
"""The sections of ``phase`` by the planes of voxels normal to ``axis`` (8-connected
pixels). ``separate``: touching sections are split by a watershed of their distance
map from its maxima of prominence at least ``prominence`` (physical units, default
half a pixel), in the manner of the binary watershed of Fiji. Sections of equivalent
radius below ``min_radius`` are dropped. On periodic images each section counts once,
whole across the faces; otherwise the sections cut by the frame are dropped and the
others weighted by ``n1 n2 / ((n1 - 1 - w1)(n2 - 1 - w2))`` for their extents ``w``
in pixels (Miles–Lantuéjoul)."""
x = indicator(image, phase).astype(bool)
spacing = np.asarray(image.spacing if isinstance(image, VoxelImage) else (1.0, 1.0, 1.0), float)
if periodic is None:
periodic = bool(image.periodic) if isinstance(image, VoxelImage) else False
axis = int(axis)
mask = np.ascontiguousarray(np.moveaxis(x, axis, 0))
h = spacing[[a for a in range(3) if a != axis]]
n0, n1, n2 = mask.shape
work = np.pad(mask, ((0, 0), (n1, n1), (n2, n2)), mode="wrap") if periodic else mask
labels, n = ndimage.label(work, structure=_PLANE)
if separate and n:
labels = _separate(work, h, prominence)
pixels = np.bincount(labels.ravel())
radii, weights = [], []
for k, box in enumerate(ndimage.find_objects(labels), start=1):
if box is None:
continue
lo1, hi1, lo2, hi2 = box[1].start, box[1].stop, box[2].start, box[2].stop
if lo1 == 0 or lo2 == 0 or hi1 == work.shape[1] or hi2 == work.shape[2]:
continue # cut by the frame (or wrapping onto itself)
if periodic:
if not (n1 <= lo1 < 2 * n1 and n2 <= lo2 < 2 * n2):
continue # another copy of a section of the window
weight = 1.0
else:
free = (n1 - 1 - (hi1 - lo1)) * (n2 - 1 - (hi2 - lo2))
if free <= 0:
continue
weight = n1 * n2 / free
radii.append(np.sqrt(pixels[k] * h[0] * h[1] / np.pi))
weights.append(weight)
radii, weights = np.asarray(radii, float), np.asarray(weights, float)
keep = radii >= float(min_radius)
return Sections(axis, radii[keep], weights[keep], float(n0 * n1 * h[0] * n2 * h[1]))
[docs]
def saltykov_matrix(n: int) -> np.ndarray:
"""``P[I - 1, J - 1]``: the probability that a particle of the 3D class ``I`` (largest
section radius ``I delta``) is cut in a section of the 2D class ``J`` (radii between
``(J - 1) delta`` and ``J delta``), classes counted upward; its rows sum to 1."""
i = np.arange(1, n + 1, dtype=float)[:, None]
j = np.arange(1, n + 1, dtype=float)[None, :]
upper = np.sqrt(np.clip(i**2 - (j - 1.0) ** 2, 0.0, None))
lower = np.sqrt(np.clip(i**2 - j**2, 0.0, None))
return np.where(j <= i, (upper - lower) / i, 0.0)
[docs]
def section_scales(shape=(1.0, 1.0), rotation=None, axis: int = 2) -> tuple[float, float]:
"""``(kappa, h)``: an ellipsoid of short semi-axis ``a``, shape factors ``shape =
(b/a, c/a)`` and axes ``rotation`` (columns: the directions of its axes a, b, c in the
frame of the image; default x, y, z) is cut by the planes normal to ``axis`` in sections
of equivalent radius at most ``kappa a``, and spans ``h a`` across them. From a fabric
tensor ``f``: ``shape = (f.ratios[1], f.ratios[0])``, ``rotation = f.axes[:, ::-1]``."""
l1, l2 = (float(v) for v in shape)
r = np.eye(3) if rotation is None else np.asarray(rotation, dtype=float)
s_hat = float(r[int(axis)] @ np.diag([1.0, l1 * l1, l2 * l2]) @ r[int(axis)])
return float(np.sqrt(l1 * l2) / s_hat**0.25), float(2.0 * np.sqrt(s_hat))
[docs]
@dataclass
class Unfolding:
"""A 3D size distribution recovered from sections: the short semi-axes of its classes
(``radii``, on the mean scale of the directions) and their numbers per unit volume
(``density``, the mean of the directions); per direction (``axes``), the densities
(``directional``), the largest short semi-axis ``a_max`` (``scales``), the measured and
refolded areal densities of the 2D classes and the relative L1 error of the refolding."""
radii: np.ndarray
density: np.ndarray
directional: np.ndarray
scales: np.ndarray
measured: np.ndarray
refolded: np.ndarray
errors: np.ndarray
axes: tuple[int, ...]
[docs]
def fractions(self) -> np.ndarray:
"""Number fractions of the classes."""
return self.density / self.density.sum()
[docs]
def distribution(self) -> Discrete:
"""The number distribution of the short semi-axes (classes of negative density
dropped), e.g. the ``seed_radius`` of a :class:`~morphogen.models.LevelSetFoam`."""
keep = self.density > 0
return Discrete(tuple(map(float, self.radii[keep])), tuple(map(float, self.density[keep])))
def _quantile(sections: Sections, q: float) -> float:
"""Weighted ``q``-quantile of the section radii."""
order = np.argsort(sections.radii)
cumulative = np.cumsum(sections.weights[order])
k = min(int(np.searchsorted(cumulative, q * cumulative[-1])), len(order) - 1)
return float(sections.radii[order][k])
def _unfold(measured, heights, p, classes: int):
"""Densities of the ``classes`` largest 3D classes from the areal densities of each
direction (Saltykov's recursion), their mean and its refolding."""
bins = p.shape[0]
top = np.arange(bins - classes, bins)
directional = np.zeros((len(measured), classes))
for d, (n_a, h) in enumerate(zip(measured, heights, strict=True)):
n_v = np.zeros(bins)
for i in top[::-1]:
n_v[i] = (n_a[i] - p[i + 1 :, i] @ (h[i + 1 :] * n_v[i + 1 :])) / (p[i, i] * h[i])
directional[d] = n_v[top]
mean = directional.mean(axis=0)
refolded = np.array([(mean * h[top]) @ p[top] for h in heights])
errors = np.abs(refolded - measured).sum(axis=1) / np.maximum(measured.sum(axis=1), 1e-300)
return directional, mean, refolded, errors
[docs]
def unfold_sections(
sections,
*,
shape=(1.0, 1.0),
rotation=None,
bins: int = 20,
classes: int | None = None,
percentile: float = 99.0,
) -> Unfolding:
"""The size distribution of particles of a common shape (``shape``, ``rotation``: see
:func:`section_scales`) from their sections normal to one or several axes (a
:class:`Sections` or a list), as Degdeg & Dirrenberger: in each direction the sections
up to the ``percentile`` of their radii, ``r_max``, fall in ``bins`` classes of width
``r_max / bins``, and the ``classes`` largest 3D classes (short semi-axes ``I / bins``
of ``a_max = r_max / kappa``) come from Saltykov's recursion; their densities are
averaged over the directions class by class. ``classes=None``: the number that
minimizes the summed L1 error of refolding the mean through each direction (several
directions: with one, the refolding of all the classes is exact)."""
sections = [sections] if isinstance(sections, Sections) else list(sections)
if classes is None and len(sections) < 2:
raise ValueError("unfold_sections: give the number of classes for a single direction")
p = saltykov_matrix(int(bins))
measured, heights, scales = [], [], []
for sec in sections:
if not len(sec.radii):
raise ValueError(f"unfold_sections: no sections normal to axis {sec.axis}")
kappa, h = section_scales(shape, rotation, sec.axis)
r_max = _quantile(sec, float(percentile) / 100.0)
measured.append(sec.areal_density(np.linspace(0.0, r_max, int(bins) + 1)))
a_max = r_max / kappa
heights.append(h * a_max * np.arange(1, int(bins) + 1) / int(bins))
scales.append(a_max)
measured = np.asarray(measured)
if classes is None:
totals = [_unfold(measured, heights, p, c)[3].sum() for c in range(1, int(bins) + 1)]
classes = int(np.argmin(totals)) + 1
directional, mean, refolded, errors = _unfold(measured, heights, p, int(classes))
top = np.arange(int(bins) - int(classes), int(bins)) + 1
radii = float(np.mean(scales)) * top / int(bins)
return Unfolding(
radii,
mean,
directional,
np.asarray(scales),
measured,
refolded,
errors,
tuple(s.axis for s in sections),
)
def _mean_radii(sections) -> dict[int, float]:
if isinstance(sections, dict):
return {int(a): float(r) for a, r in sections.items()}
return {s.axis: s.mean_radius() for s in sections}
[docs]
def shape_consistency(sections, shape=(1.0, 1.0), rotation=None) -> np.ndarray:
"""The mean section radius over ``kappa`` in each direction (the axes of ``sections``,
a list of :class:`Sections` or a mapping axis -> mean radius): ``(pi / 4) m2 / m1``
of the short semi-axes in every direction when the particles have the given shape."""
means = _mean_radii(sections)
return np.array([r / section_scales(shape, rotation, a)[0] for a, r in means.items()])
[docs]
def consistent_shape(sections, rotation=None) -> tuple[float, float]:
"""The shape factors ``(b/a, c/a)`` for which :func:`shape_consistency` is the same in
the three directions: ``r_D^4 s_hat_D`` common to them, a linear system in the squared
shape factors (``b/a = (r_x / r_y)^2``, ``c/a = (r_x / r_z)^2`` for the default axes).
It is ill-conditioned for axes far from the planes of the grid."""
means = _mean_radii(sections)
if sorted(means) != [0, 1, 2]:
raise ValueError("consistent_shape: the mean section radii normal to x, y and z")
r = np.eye(3) if rotation is None else np.asarray(rotation, dtype=float)
w = np.linalg.solve(r**2, 1.0 / np.array([means[a] for a in range(3)]) ** 4)
if np.any(w <= 0):
raise ValueError("consistent_shape: no ellipsoid of these axes fits the section radii")
return float(np.sqrt(w[1] / w[0])), float(np.sqrt(w[2] / w[0]))