polyphys 1.0.0__py3-none-any.whl

polyphys/spec.py

@@ -0,0 +1,1359 @@
+"""\
+==========================================================
+:mod:`polyphys.spec`
+==========================================================
+
+This :mod:`~polyphys.spec` module holds the records that describe one study
+as data, every one of them in a module that imports neither MDAnalysis nor
+:mod:`polyphys.probe`, so a study's spec builds without the ``mda`` extra:
+
+- :class:`ProjectSpec`, the per-project facts that the parser class does not
+  hold. A parser class declares how a study's filenames read; a
+  :class:`ProjectSpec` declares how the study's analysis reads its
+  artifacts: which particle group is the polymer, which parser attributes
+  become columns, how the bulk volume fraction of crowders is rounded, which
+  time series exist, and which size attribute scales each species' density
+  profile.
+- :class:`ProbeSpec`, how :mod:`polyphys.probe` reads the study's
+  trajectories: which MDAnalysis selection is each species, which
+  chain-size observables are measured, how the chain is unwrapped, the bin
+  sizes of the histograms, and, for a study with binders, a
+  :class:`BinderSpec` of how their binding is counted.
+- :class:`AnalysisTable`, the analysis of one particle group, which lists a
+  :class:`PropertySpec` per probe artifact for
+  :func:`~polyphys.analyze.pipeline.reduce_space`.
+
+The facts the parser already holds, such as the geometry, the topology, and
+the glob patterns of the ``space`` and ``ensemble_long`` names, are read from
+the parser rather than stored twice.
+
+PolyPhys holds no table of studies: a study builds its own spec where its
+analysis lives. The specs of the maintainer's studies are in the repository's
+top-level ``projects/`` folder, which is not part of the installed package.
+
+.. versionadded:: 0.9.0
+   The records of ``polyphys.manage.projects`` and the table records and
+   builders of :mod:`polyphys.analyze.pipeline` moved here; their old import
+   paths warned with :exc:`DeprecationWarning`.
+
+.. versionchanged:: 1.0.0
+   The old import paths are removed: ``polyphys.manage.projects`` no
+   longer exists, and :mod:`polyphys.analyze.pipeline` no longer serves the
+   table records and builders.
+
+Contents
+========
+
+Project and probe records:
+
+- :class:`ProjectSpec`, a frozen record of one study.
+- :class:`ProbeSpec`, a frozen record of how one study's trajectories are
+  probed, built beside its :class:`ProjectSpec`.
+- :data:`CHAIN_SIZE_OBSERVABLES`, the names a :class:`ProbeSpec` may list as
+  chain-size observables.
+- :class:`BinderSpec`, a frozen record of how the binding of a study's
+  two-patch binders to its chain is counted, held by the :class:`ProbeSpec`
+  of a study with binders.
+- :data:`BINDER_SERIES`, the eight binding counts and the stems of their
+  time series.
+- :data:`PerWhole`, a number or a function of a whole's parser, and
+  :data:`RecenterT`, how a probe moves a frame's positions.
+
+Analysis records:
+
+- :class:`PropertySpec` describes one probe artifact; :func:`tseries`,
+  :func:`histogram`, :func:`histogram_2d`, :func:`edge`, and
+  :func:`matrix_tseries` build the kinds the studies use.
+- :class:`AnalysisTable` lists the properties of one group.
+- :data:`PostHook`, the type of a post-hook; the hooks themselves are in
+  :mod:`polyphys.analyze.pipeline`.
+
+Dependencies
+============
+- Python standard library: `dataclasses`, `math`, `numbers`, `types`,
+  `typing`.
+- :mod:`polyphys.manage.parser`: :class:`~polyphys.manage.parser.ParserBase`.
+- :mod:`polyphys.manage.types`: domain type aliases such as
+  :py:obj:`~.GroupT`.
+
+Notation
+========
+:math:`\\phi_c`
+    The bulk volume fraction of crowders, the parser attribute
+    ``phi_bulk_c``: the fraction of the volume available to crowder centers
+    that the crowders fill (dimensionless).
+:math:`\\Delta`
+    The rounding step, `divisor`, of :math:`\\phi_c` in the
+    ``phi_bulk_c_round`` column (dimensionless).
+
+The *property*, *relation*, *whole type*, *post-hook*, and *lineage of a
+table* of the analysis records are as :mod:`polyphys.analyze.pipeline`,
+"Notation", defines them.
+
+Examples
+========
+>>> from polyphys.tests.synthetic import ChainCyl
+>>> spec = ProjectSpec(
+...     parser=ChainCyl, group='bug', divisor=0.025,
+...     crowder_attr='phi_bulk_c',
+...     physical_attrs=('space', 'nmon', 'dcyl', 'dcrowd'),
+...     species_sizes={'Mon': 'dmon', 'Crd': 'dcrowd'},
+...     tseries_properties=('gyrTMon',))
+>>> spec.geometry, spec.space_pattern, spec.hierarchy
+('cylindrical', 'N*D*ac*', 'N*')
+>>> table = AnalysisTable('bug', 'whole', False, (tseries('gyrT', 'Mon'),))
+>>> [prop.prop for prop in table.properties]
+['gyrTMon']
+"""
+import math
+import numbers
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import (
+    TYPE_CHECKING, Callable, Literal, Mapping, TypeGuard, get_args)
+
+from polyphys.manage.parser import ParserBase
+from polyphys.manage.types import (
+    DirectionT,
+    EntityT,
+    GeometryT,
+    GroupT,
+    PrimitiveLineageT,
+    PropertyT,
+    TopologyT,
+    WholeRelationT,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - for the type checker only
+    from polyphys.analyze.pipeline import ArrayWholes, Derived, HookContext
+
+__all__ = [
+    'BINDER_SERIES',
+    'CHAIN_SIZE_OBSERVABLES',
+    'AnalysisTable',
+    'BinderSpec',
+    'PerWhole',
+    'PostHook',
+    'ProbeSpec',
+    'ProjectSpec',
+    'PropertySpec',
+    'RecenterT',
+    'edge',
+    'histogram',
+    'histogram_2d',
+    'matrix_tseries',
+    'tseries',
+]
+
+# ---------------------------------------------------------------------------
+# Project and probe records
+# ---------------------------------------------------------------------------
+
+#: A quantity of a probe that is either the same number for every whole of a
+#: study or a function of the whole's parser, such as a bin size that scales
+#: with the crowder diameter. :meth:`ProbeSpec.resolve` turns either into the
+#: number for one whole.
+#:
+#: .. versionadded:: 0.7.0
+PerWhole = float | Callable[[ParserBase], float]
+
+#: How a probe moves the positions of a frame before binning them. The
+#: LAMMPS dump reader of MDAnalysis 2.4 and later translates every frame so
+#: that the lower box bounds sit at the origin, which undoes the ``fix
+#: recenter`` of the studies' LAMMPS scripts. ``'half'`` subtracts half the
+#: box lengths of the frame, which restores the LAMMPS frame exactly;
+#: ``'none'`` keeps the reader's frame; a triple is subtracted as given, so
+#: the research code's shift by half the parser's ``(dcyl, dcyl, lcyl)`` or
+#: ``lcube`` is reproducible.
+#:
+#: .. versionadded:: 0.7.0
+RecenterT = Literal['none', 'half'] | tuple[float, float, float]
+
+# The directions of the density profiles in each geometry.
+_DIRECTIONS: dict[GeometryT, tuple[DirectionT, ...]] = {
+    'cubic': ('r',),
+    'cylindrical': ('r', 'z'),
+}
+
+#: The chain-size observables that
+#: :class:`~polyphys.probe.chain_size.ChainSize` measures per frame, in the
+#: research code's order: each is the name of a time series without its
+#: species label, so ``'gyrT'`` with the chain label ``'Mon'`` is the
+#: ``gyrTMon`` artifact. ``'principalT'`` is a per-frame
+#: :math:`3 \\times 3` matrix; the others are scalars.
+#:
+#: .. versionadded:: 0.7.0
+CHAIN_SIZE_OBSERVABLES: tuple[PropertyT, ...] = (
+    'transSizeT', 'fsdT', 'gyrT', 'rfloryT', 'asphericityT', 'shapeT',
+    'principalT')
+
+# The chain-size observables that are per-frame matrices, which a project's
+# `tseries_properties` does not list.
+_MATRIX_OBSERVABLES: frozenset[PropertyT] = frozenset({'principalT'})
+
+#: The eight per-frame binding counts that
+#: :class:`~polyphys.probe.binders.BinderStatistics` measures, in the
+#: research code's order: each attribute of
+#: :class:`~polyphys.analyze.clusters.FrameBinding` mapped to the stem of its
+#: time series and to which label completes the name, ``'patches'`` for the
+#: three patch counts and ``'binders'`` for the five binder counts. With the
+#: labels ``HnsPatch`` and ``HnsCore``, ``n_binders_bridging`` is the
+#: ``nBridgeTHnsCore`` artifact.
+#:
+#: .. versionadded:: 0.7.0
+BINDER_SERIES: Mapping[str, tuple[PropertyT, str]] = MappingProxyType({
+    'n_patch_monomer_contacts': ('nBoundT', 'patches'),
+    'n_patches_free': ('nFreeT', 'patches'),
+    'n_patches_engaged': ('nEngagedT', 'patches'),
+    'n_binders_free': ('nFreeT', 'binders'),
+    'n_binders_bridging': ('nBridgeT', 'binders'),
+    'n_binders_dangling': ('nDangleT', 'binders'),
+    'n_pairs_cis': ('nCisT', 'binders'),
+    'n_pairs_trans': ('nTransT', 'binders'),
+})
+
+# The number of patches per binder that binding_statistics counts.
+_TWO_PATCHES = 2
+
+
+@dataclass(frozen=True, slots=True)
+class BinderSpec:
+    """
+    How the binding of a study's two-patch binders to its chain is counted: the
+    facts :class:`~polyphys.probe.binders.BinderStatistics` needs beyond the
+    selections of the :class:`ProbeSpec` that holds this record.
+
+    .. versionadded:: 0.7.0
+    .. versionchanged:: 1.0.0
+       `cis_threshold` is keyword-only and has no default.
+
+    Parameters
+    ----------
+    patches : :py:obj:`~.EntityT`
+        The label in the probe spec's `selections` of the binders' patches,
+        such as ``'HnsPatch'``, which names the three patch series
+        ``nBoundT``, ``nFreeT``, and ``nEngagedT``. The patches of binder
+        :math:`k` are the ones at positions :math:`2k` and :math:`2k + 1`
+        of the selection, in atom-ID order.
+    binders : :py:obj:`~.EntityT`
+        The label of the binders, such as ``'HnsCore'``, which names the
+        five binder series ``nFreeT``, ``nBridgeT``, ``nDangleT``,
+        ``nCisT``, and ``nTransT``. A label only: the binder cores are not
+        selected.
+    cutoff : float
+        The binding threshold :math:`r_\\mathrm{thres}`, in units of the
+        monomer diameter: a patch and a monomer closer than it are in
+        contact. Finite and positive. A study constant that the spec
+        states, never computed from the particle sizes; see the probe
+        guide, "Choosing the cutoff".
+    inclusive : bool, default True
+        Whether a pair at exactly `cutoff` is a contact
+        (:math:`r \\le r_\\mathrm{thres}`, the thesis criterion) or not
+        (:math:`r < r_\\mathrm{thres}`, the research probe's).
+    cis_threshold : int
+        Keyword-only, with no default. The largest genomic distance, in
+        bonds, of a cis bridge; non-negative. A study choice: the H-NS
+        studies state 3, a bridge with at most two monomers between its
+        sites, where the research probe used 4; the probe guide,
+        "Choosing the cis threshold", gives both values and why.
+    patches_per_binder : int, default 2
+        The number of patches per binder. Only ``2`` is accepted, which
+        :func:`~polyphys.analyze.clusters.binding_statistics` counts; the
+        field is kept so that binders of another valence can be declared
+        once a kernel counts them.
+    store_distances : bool, default False
+        Whether the probe also keeps and saves the monomer-to-patch
+        distance matrix of every frame, the input of the threshold sweep
+        and of the binder-cluster post-step of the research code.
+
+    Attributes
+    ----------
+    series : mapping of str to :py:obj:`~.PropertyT`
+        Each attribute name of
+        :class:`~polyphys.analyze.clusters.FrameBinding` in
+        :data:`BINDER_SERIES` mapped to the full name of its time series,
+        ``<stem><patches>`` or ``<stem><binders>``, in the research code's
+        order.
+
+    Raises
+    ------
+    ValueError
+        If `patches` or `binders` is not a non-empty string or the two are
+        equal; if `cutoff` is not a finite positive number; if
+        `cis_threshold` is a negative integer or not an integer; or if
+        `patches_per_binder` is not ``2``.
+
+    Notes
+    -----
+    Construction and :attr:`series` are :math:`O(1)`.
+
+    Examples
+    --------
+    >>> spec = BinderSpec(patches='HnsPatch', binders='HnsCore',
+    ...                   cutoff=0.685, cis_threshold=3)
+    >>> spec.series['n_binders_bridging'], spec.series['n_patches_free']
+    ('nBridgeTHnsCore', 'nFreeTHnsPatch')
+    >>> BinderSpec('HnsPatch', 'HnsCore', cutoff=0.685, cis_threshold=3,
+    ...            patches_per_binder=3)
+    Traceback (most recent call last):
+    ...
+    ValueError: 'patches_per_binder' must be 2, not 3: ...
+    """
+    patches: EntityT
+    binders: EntityT
+    cutoff: float
+    inclusive: bool = True
+    patches_per_binder: int = _TWO_PATCHES
+    store_distances: bool = False
+    cis_threshold: int = field(kw_only=True)
+
+    def __post_init__(self) -> None:
+        for name, label in (('patches', self.patches),
+                            ('binders', self.binders)):
+            if not (isinstance(label, str) and label):
+                raise ValueError(
+                    f"'{name}' must be a non-empty species label, not "
+                    f"{label!r}.")
+        if self.patches == self.binders:
+            raise ValueError(
+                f"'patches' and 'binders' must be different labels, not "
+                f"both {self.patches!r}.")
+        if not (isinstance(self.cutoff, (int, float))
+                and not isinstance(self.cutoff, bool)
+                and math.isfinite(self.cutoff) and self.cutoff > 0):
+            raise ValueError(
+                f"'cutoff' must be a finite positive number, not "
+                f"{self.cutoff!r}.")
+        if (isinstance(self.cis_threshold, bool)
+                or not isinstance(self.cis_threshold, int)
+                or self.cis_threshold < 0):
+            raise ValueError(
+                f"'cis_threshold' must be a non-negative integer, not "
+                f"{self.cis_threshold!r}.")
+        if (isinstance(self.patches_per_binder, bool)
+                or self.patches_per_binder != _TWO_PATCHES):
+            raise ValueError(
+                f"'patches_per_binder' must be {_TWO_PATCHES}, not "
+                f"{self.patches_per_binder!r}: binding_statistics counts "
+                "two-patch binders only.")
+
+    @property
+    def series(self) -> Mapping[str, PropertyT]:
+        """
+        Each binding count's attribute name mapped to the full name of its
+        time series, in the research code's order.
+        """
+        labels = {'patches': self.patches, 'binders': self.binders}
+        return MappingProxyType({
+            attr: f"{stem}{labels[which]}"
+            for attr, (stem, which) in BINDER_SERIES.items()})
+
+
+def _is_positive_number(value: object) -> TypeGuard[numbers.Real]:
+    """Whether `value` is a finite positive real number: a Python or NumPy
+    integer or float, never a bool."""
+    return (isinstance(value, numbers.Real) and not isinstance(value, bool)
+            and math.isfinite(value) and float(value) > 0)
+
+
+def _is_per_whole(value: object) -> bool:
+    """Whether `value` is a finite positive number or a callable."""
+    return callable(value) or _is_positive_number(value)
+
+
+def _check_resolved(result: object, subject: str) -> float:
+    """
+    Return `result`, a :py:data:`PerWhole` constant or what a callable
+    gave, as a float.
+
+    Raises
+    ------
+    ValueError
+        If `result` is not a finite positive number; the message begins
+        with `subject`, which names the quantity or the whole.
+    """
+    if _is_positive_number(result):
+        return float(result)
+    raise ValueError(
+        f"{subject} must resolve to a finite positive number, not "
+        f"{result!r}.")
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectSpec:
+    """
+    The per-project facts that the analysis of a study needs and its parser
+    class does not hold.
+
+    Every attribute a spec names is checked at construction against the
+    attributes its parser sets at the ``ensemble_long`` lineage, the lineage
+    whose names the organizer parses for these values.
+
+    Parameters
+    ----------
+    parser : type of :class:`~polyphys.manage.parser.ParserBase`
+        The study's concrete parser class.
+    group : :py:obj:`~.GroupT`
+        The particle group of the polymer, such as ``'bug'`` or
+        ``'nucleoid'``; one of the parser's groups, and not ``'all'``.
+    divisor : float
+        The step :math:`\\Delta > 0` to which the bulk volume fraction of
+        crowders :math:`\\phi_c` (`crowder_attr`, dimensionless) is rounded
+        in the ``phi_bulk_c_round`` column of the ``space`` tables.
+    physical_attrs : tuple of str
+        The parser attributes added as columns to the ``space`` tables, in
+        column order.
+    species_sizes : mapping of :py:obj:`~.EntityT` to str
+        Each species label of a density profile, such as ``'Mon'`` or
+        ``'Crd'``, mapped to the parser attribute that holds its particle
+        diameter, in units of the monomer diameter. Stored read-only, in the
+        given order.
+    tseries_properties : tuple of :py:obj:`~.PropertyT`
+        The per-frame time series of the study, named
+        ``<property>T<Species>``, such as ``'gyrTMon'``.
+    crowder_attr : str
+        Keyword-only. The parser attribute that holds :math:`\\phi_c`, such
+        as ``'phi_bulk_c'``, which the ``space`` tables add as a column and
+        round into ``phi_bulk_c_round``. A study choice, so it has no
+        default.
+
+        .. versionadded:: 0.9.0
+
+    Attributes
+    ----------
+    name : str
+        The parser class name, which is the project name.
+    geometry : :py:obj:`~.GeometryT`
+        The parser's geometry.
+    topology : :py:obj:`~.TopologyT`
+        The parser's polymer topology.
+    directions : tuple of :py:obj:`~.DirectionT`
+        The directions of the density profiles: ``('r',)`` in a cube and
+        ``('r', 'z')`` in a cylinder.
+    space_pattern : str
+        A glob pattern that matches the study's ``space`` names: each
+        keyword of the parser's ``space`` pattern followed by ``*``.
+    space_hierarchy : str
+        A glob prefix of the ``space`` names: their first keyword and ``*``.
+    hierarchy : str
+        A glob prefix of the ``ensemble_long`` names: their first keyword and
+        ``*``.
+
+    Raises
+    ------
+    TypeError
+        If `parser` is not a concrete subclass of
+        :class:`~polyphys.manage.parser.ParserBase`.
+    ValueError
+        If `group` is ``'all'`` or not one of the parser's groups; if
+        `divisor` is not a finite positive number; if `crowder_attr` is not
+        a non-empty string; or if `physical_attrs`, `species_sizes`, or
+        `crowder_attr` names an attribute the parser does not set at
+        ``ensemble_long``.
+
+    Examples
+    --------
+    >>> from polyphys.tests.synthetic import ChainCyl, RingCubBinders
+    >>> spec = ProjectSpec(
+    ...     parser=RingCubBinders, group='nucleoid', divisor=0.01,
+    ...     crowder_attr='phi_bulk_c',
+    ...     physical_attrs=('space', 'nmon', 'nhns', 'dcrowd'),
+    ...     species_sizes={'Mon': 'dmon', 'Crd': 'dcrowd', 'Hns': 'dhns'},
+    ...     tseries_properties=('gyrTMon',))
+    >>> spec.name, spec.geometry, spec.directions
+    ('RingCubBinders', 'cubic', ('r',))
+    >>> spec.space_pattern, spec.space_hierarchy, spec.hierarchy
+    ('N*nh*ac*', 'N*', 'N*')
+    >>> spec.species_sizes['Hns']
+    'dhns'
+
+    A spec that names an attribute the parser does not set fails at once:
+
+    >>> ProjectSpec(ChainCyl, 'bug', 0.025, ('nhns',), {}, (),
+    ...             crowder_attr='phi_bulk_c')
+    Traceback (most recent call last):
+    ...
+    ValueError: ChainCyl does not set ['nhns'] at 'ensemble_long'.
+
+    Notes
+    -----
+    Construction costs :math:`O(a + s + n)` for :math:`a` physical
+    attributes, :math:`s` species, and the :math:`n` names that
+    :meth:`~polyphys.manage.parser.ParserBase.attributes_at` collects; every
+    derived attribute is :math:`O(1)`.
+    """
+    parser: type[ParserBase]
+    group: GroupT
+    divisor: float
+    physical_attrs: tuple[str, ...]
+    species_sizes: Mapping[EntityT, str] = field(hash=False)
+    tseries_properties: tuple[PropertyT, ...]
+    crowder_attr: str = field(kw_only=True)
+
+    def __post_init__(self) -> None:
+        # Copy the containers so that a caller's list or dict cannot change
+        # the spec afterwards.
+        object.__setattr__(self, 'physical_attrs', tuple(self.physical_attrs))
+        object.__setattr__(self, 'tseries_properties',
+                           tuple(self.tseries_properties))
+        object.__setattr__(self, 'species_sizes',
+                           MappingProxyType(dict(self.species_sizes)))
+        parser = self.parser
+        if not (isinstance(parser, type) and issubclass(parser, ParserBase)
+                and parser._patterns is not None):
+            raise TypeError(
+                f"'parser' must be a concrete ParserBase subclass, not "
+                f"{parser!r}.")
+        name = parser.__name__
+        if self.group == 'all' or self.group not in parser._groups:
+            raise ValueError(
+                f"{name}: 'group' must be the polymer group, one of "
+                f"{[g for g in parser._groups if g != 'all']}, not "
+                f"{self.group!r}.")
+        if not (math.isfinite(self.divisor) and self.divisor > 0):
+            raise ValueError(
+                f"{name}: 'divisor' must be a finite positive number, not "
+                f"{self.divisor!r}.")
+        if not (isinstance(self.crowder_attr, str) and self.crowder_attr):
+            raise ValueError(
+                f"{name}: 'crowder_attr' must be a non-empty attribute name, "
+                f"not {self.crowder_attr!r}.")
+        available = parser.attributes_at('ensemble_long')
+        named = [*self.physical_attrs, *self.species_sizes.values(),
+                 self.crowder_attr]
+        missing = sorted({attr for attr in named if attr not in available})
+        if missing:
+            raise ValueError(
+                f"{name} does not set {missing} at 'ensemble_long'.")
+
+    @property
+    def name(self) -> str:
+        """
+        The parser class name, which is the project name.
+        """
+        return self.parser.__name__
+
+    @property
+    def geometry(self) -> GeometryT:
+        """
+        The parser's geometry.
+        """
+        return self.parser._geometry
+
+    @property
+    def topology(self) -> TopologyT:
+        """
+        The parser's polymer topology.
+        """
+        return self.parser._topology
+
+    @property
+    def directions(self) -> tuple[DirectionT, ...]:
+        """
+        The directions of the density profiles in the parser's geometry.
+        """
+        return _DIRECTIONS[self.geometry]
+
+    @property
+    def space_pattern(self) -> str:
+        """
+        A glob pattern that matches the study's ``space`` names.
+        """
+        return ''.join(f"{keyword}*"
+                       for keyword in self.parser.pattern('space'))
+
+    @property
+    def space_hierarchy(self) -> str:
+        """
+        A glob prefix of the ``space`` names: their first keyword and ``*``.
+        """
+        return f"{self.parser.pattern('space')[0]}*"
+
+    @property
+    def hierarchy(self) -> str:
+        """
+        A glob prefix of the ``ensemble_long`` names: their first keyword
+        and ``*``.
+        """
+        return f"{self.parser.pattern('ensemble_long')[0]}*"
+
+
+@dataclass(frozen=True, slots=True)
+class ProbeSpec:
+    """
+    How the trajectories of one study are probed: the facts that
+    :mod:`polyphys.probe` needs beyond the study's :class:`ProjectSpec`.
+
+    A probe spec is built beside the project spec, in the study's own
+    folder, and reads the parser class and the geometry from it rather than
+    storing them twice. Every observable it names is checked at construction
+    against :data:`CHAIN_SIZE_OBSERVABLES` and, for the scalar ones, against
+    the project's ``tseries_properties``.
+
+    .. versionadded:: 0.7.0
+
+    Parameters
+    ----------
+    project : ProjectSpec
+        The study's project spec.
+    selections : mapping of :py:obj:`~.EntityT` to str
+        Each species label, such as ``'Mon'`` or ``'Foci'``, mapped to the
+        MDAnalysis selection string that picks its atoms, such as
+        ``'resid 1'`` or ``'type 2'``. Stored read-only, in the given order.
+    chain : :py:obj:`~.EntityT`
+        The label in `selections` of the polymer chain, whose chain-size
+        time series are named ``<observable><chain>``.
+    observables : tuple of :py:obj:`~.PropertyT`
+        The chain-size observables measured per frame, each a name in
+        :data:`CHAIN_SIZE_OBSERVABLES`, in the order the probe stores them.
+    unwrap : bool
+        Whether the chain is unwrapped across the periodic boundaries before
+        its gyration tensor is formed for ``asphericityT``, the `unwrap`
+        argument of ``AtomGroup.asphericity``: ``False`` for a cylinder,
+        which is periodic along its axis only, and ``True`` for a periodic
+        cube. Every other observable, ``shapeT`` included, reads the
+        positions as the dump gives them; see
+        :class:`polyphys.probe.chain_size.ChainSize`.
+    bin_sizes : mapping of :py:obj:`~.DirectionT` to :py:data:`PerWhole`, \
+            default {}
+        The bin size of the histogram along each direction: in units of the
+        monomer diameter for a spatial direction, such as ``'r'`` or
+        ``'z'``, and in radians for the angle ``'theta'``. Each is a finite
+        positive number, or a function of a whole's parser returning one,
+        for a size that scales with a whole's particle diameters. Stored
+        read-only. Left empty by a study whose histograms are not probed.
+    histogram_species : tuple of :py:obj:`~.EntityT`, default ()
+        The labels in `selections` of the species whose spatial histograms
+        :class:`~polyphys.probe.histograms.SpatialHistograms` collects, each
+        once. Left empty by a study whose histograms are not probed; otherwise
+        `bin_sizes` and `block_frames` are required.
+    block_frames : int or None, default None
+        The block length :math:`b` of the two-dimensional maps: the number of
+        consecutive frames whose maps are averaged into one stored map, a
+        positive integer. Required with `histogram_species`.
+    recenter : :py:data:`RecenterT`, default 'half'
+        How the positions of a frame are moved before they are binned:
+        ``'half'`` subtracts half the frame's box lengths, which restores the
+        LAMMPS frame the dump reader translated; ``'none'`` keeps the reader's
+        frame; a triple ``(dx, dy, dz)`` is subtracted as given. Stored as a
+        tuple of floats when given as a triple.
+    pair_species : :py:obj:`~.EntityT` or None, default None
+        The label in `selections` of the species whose pair distances and
+        contacts :class:`~polyphys.probe.pairs.PairDistances` collects, such as
+        ``'Foci'``; ``None`` when the study has no such species. Requires
+        `contact_cutoff`.
+    contact_cutoff : :py:data:`PerWhole` or None, default None
+        The center-to-center distance, in units of the monomer diameter, at
+        or below which two particles of `pair_species` are in direct
+        contact: a finite positive number or a function of a whole's parser,
+        such as the sum of the large-monomer and crowder diameters.
+    minimum_image : bool, default True
+        Whether the pair distances use the minimum-image convention along
+        the periodic directions of the geometry: the axis of a cylinder, all
+        three directions of a cube.
+    binders : BinderSpec, optional
+        How the binding of the study's two-patch binders is counted, for a
+        study with binders such as the H-NS ones; ``None`` for a study
+        without. Its `patches` must be a label in `selections` other than
+        `chain`, and each of its eight time series must be one of the
+        project's ``tseries_properties``.
+
+    Attributes
+    ----------
+    name : str
+        The project name, from the project spec.
+    parser : type of :class:`~polyphys.manage.parser.ParserBase`
+        The study's parser class, from the project spec.
+    geometry : :py:obj:`~.GeometryT`
+        The study's geometry, from the project spec.
+
+    Raises
+    ------
+    TypeError
+        If `project` is not a :class:`ProjectSpec`, or if `binders` is
+        neither ``None`` nor a :class:`BinderSpec`.
+    ValueError
+        If `selections` is empty or has a label or a selection that is not
+        a non-empty string; if `chain` is not a label in `selections`; if
+        `observables` is empty, repeats a name, or names an observable that
+        is not in :data:`CHAIN_SIZE_OBSERVABLES`; if a scalar observable
+        with the chain label is not one of the project's
+        ``tseries_properties``; if a bin size is keyed by an unknown
+        direction or is neither a finite positive number nor callable; if a
+        histogram species is not a label in `selections` or repeats, or is
+        given without `bin_sizes` or `block_frames`; if `block_frames` is
+        not a positive integer; if `recenter` is neither ``'none'``,
+        ``'half'``, nor a triple of finite numbers; if `pair_species` is not
+        a label in `selections` or is given without `contact_cutoff`; if
+        `contact_cutoff` is neither a finite positive number nor callable;
+        or if the patches of `binders` are not a label in `selections`
+        other than `chain`, or one of its time series is not among the
+        project's ``tseries_properties``.
+
+    Examples
+    --------
+    >>> from polyphys.tests.synthetic import ChainCyl
+    >>> project = ProjectSpec(
+    ...     parser=ChainCyl, group='bug', divisor=0.025,
+    ...     crowder_attr='phi_bulk_c',
+    ...     physical_attrs=('space', 'nmon', 'dcyl', 'dcrowd'),
+    ...     species_sizes={'Mon': 'dmon', 'Crd': 'dcrowd'},
+    ...     tseries_properties=('fsdTMon', 'gyrTMon', 'rfloryTMon'))
+    >>> probe = ProbeSpec(
+    ...     project=project, selections={'Mon': 'resid 1'}, chain='Mon',
+    ...     observables=('rfloryT', 'fsdT', 'gyrT'), unwrap=False)
+    >>> probe.name, probe.geometry, probe.selections['Mon']
+    ('ChainCyl', 'cylindrical', 'resid 1')
+
+    An observable the project's time series do not list fails at once:
+
+    >>> ProbeSpec(project, {'Mon': 'resid 1'}, 'Mon', ('shapeT',), False)
+    Traceback (most recent call last):
+    ...
+    ValueError: ChainCyl: 'observables' names ['shapeTMon'], which ...
+
+    A study whose histograms are probed names the species, the bin sizes,
+    which may depend on the whole, and the block length; the bin sizes are
+    resolved for one whole from its parser:
+
+    >>> probe = ProbeSpec(
+    ...     project=project, selections={'Mon': 'resid 1', 'Crd': 'resid 0'},
+    ...     chain='Mon', observables=('gyrT',), unwrap=False,
+    ...     bin_sizes={'r': lambda info: 0.1 * min(info.dmon, info.dcrowd),
+    ...                'z': 0.5},
+    ...     histogram_species=('Mon', 'Crd'), block_frames=100)
+    >>> whole = ChainCyl(
+    ...     'N200r10.5lz50ac0.5nc100dt0.005bdump1adump1ens1',
+    ...     'whole', 'all')
+    >>> probe.resolve(probe.bin_sizes['r'], whole), probe.recenter
+    (0.05, 'half')
+
+    A study with binders adds a :class:`BinderSpec`:
+
+    >>> hns = ProjectSpec(
+    ...     parser=ChainCyl, group='bug', divisor=0.025,
+    ...     crowder_attr='phi_bulk_c',
+    ...     physical_attrs=('space', 'nmon', 'dcyl', 'dcrowd'),
+    ...     species_sizes={'Mon': 'dmon', 'Crd': 'dcrowd'},
+    ...     tseries_properties=(
+    ...         'gyrTMon', 'nBoundTHnsPatch', 'nFreeTHnsPatch',
+    ...         'nEngagedTHnsPatch', 'nFreeTHnsCore', 'nBridgeTHnsCore',
+    ...         'nDangleTHnsCore', 'nCisTHnsCore', 'nTransTHnsCore'))
+    >>> probe = ProbeSpec(
+    ...     project=hns, selections={'Mon': 'resid 1', 'HnsPatch': 'type 2'},
+    ...     chain='Mon', observables=('gyrT',), unwrap=False,
+    ...     binders=BinderSpec('HnsPatch', 'HnsCore', cutoff=0.685,
+    ...                        cis_threshold=3))
+    >>> probe.binders.series['n_pairs_cis']
+    'nCisTHnsCore'
+
+    Notes
+    -----
+    Construction costs :math:`O(s + o + b + h)` for :math:`s` selections,
+    :math:`o` observables, :math:`b` bin sizes, and :math:`h` histogram
+    species; every derived attribute is :math:`O(1)`.
+    """
+    project: ProjectSpec
+    selections: Mapping[EntityT, str] = field(hash=False)
+    chain: EntityT
+    observables: tuple[PropertyT, ...]
+    unwrap: bool
+    bin_sizes: Mapping[DirectionT, PerWhole] = field(
+        default_factory=dict, hash=False)
+    histogram_species: tuple[EntityT, ...] = ()
+    block_frames: int | None = None
+    recenter: RecenterT = 'half'
+    pair_species: EntityT | None = None
+    contact_cutoff: PerWhole | None = None
+    minimum_image: bool = True
+    binders: BinderSpec | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.project, ProjectSpec):
+            raise TypeError(
+                f"'project' must be a ProjectSpec, not {self.project!r}.")
+        if self.binders is not None \
+                and not isinstance(self.binders, BinderSpec):
+            raise TypeError(
+                f"'binders' must be a BinderSpec or None, not "
+                f"{self.binders!r}.")
+        name = self.project.name
+        # Copy the containers so that a caller's dict or list cannot change
+        # the spec afterwards.
+        object.__setattr__(self, 'selections',
+                           MappingProxyType(dict(self.selections)))
+        object.__setattr__(self, 'observables', tuple(self.observables))
+        object.__setattr__(self, 'bin_sizes',
+                           MappingProxyType(dict(self.bin_sizes)))
+        if not self.selections or any(
+                not (isinstance(key, str) and key
+                     and isinstance(value, str) and value)
+                for key, value in self.selections.items()):
+            raise ValueError(
+                f"{name}: 'selections' must map each species label to a "
+                f"non-empty selection string, not {dict(self.selections)!r}.")
+        if self.chain not in self.selections:
+            raise ValueError(
+                f"{name}: 'chain' must be a label in 'selections', one of "
+                f"{list(self.selections)}, not {self.chain!r}.")
+        if not self.observables:
+            raise ValueError(f"{name}: 'observables' must not be empty.")
+        unknown = [obs for obs in self.observables
+                   if obs not in CHAIN_SIZE_OBSERVABLES]
+        if unknown:
+            raise ValueError(
+                f"{name}: 'observables' names {unknown}, which are not in "
+                f"{list(CHAIN_SIZE_OBSERVABLES)}.")
+        if len(set(self.observables)) != len(self.observables):
+            raise ValueError(
+                f"{name}: 'observables' repeats a name: "
+                f"{list(self.observables)}.")
+        unlisted = [f"{obs}{self.chain}" for obs in self.observables
+                    if obs not in _MATRIX_OBSERVABLES
+                    and f"{obs}{self.chain}"
+                    not in self.project.tseries_properties]
+        if unlisted:
+            raise ValueError(
+                f"{name}: 'observables' names {unlisted}, which are not "
+                f"among the project's 'tseries_properties' "
+                f"{list(self.project.tseries_properties)}.")
+        directions = get_args(DirectionT)
+        for direction, size in self.bin_sizes.items():
+            if direction not in directions:
+                raise ValueError(
+                    f"{name}: 'bin_sizes' has the direction {direction!r}; "
+                    f"each must be one of {list(directions)}.")
+            if not _is_per_whole(size):
+                raise ValueError(
+                    f"{name}: the bin size along {direction!r} must be a "
+                    f"finite positive number or a callable, not {size!r}.")
+        object.__setattr__(self, 'histogram_species',
+                           tuple(self.histogram_species))
+        unselected = [species for species in self.histogram_species
+                      if species not in self.selections]
+        if unselected:
+            raise ValueError(
+                f"{name}: 'histogram_species' names {unselected}, which are "
+                f"not labels in 'selections' {list(self.selections)}.")
+        if len(set(self.histogram_species)) != len(self.histogram_species):
+            raise ValueError(
+                f"{name}: 'histogram_species' repeats a label: "
+                f"{list(self.histogram_species)}.")
+        if self.histogram_species and not self.bin_sizes:
+            raise ValueError(
+                f"{name}: 'histogram_species' needs 'bin_sizes'.")
+        if self.histogram_species and self.block_frames is None:
+            raise ValueError(
+                f"{name}: 'histogram_species' needs 'block_frames'.")
+        if self.block_frames is not None and not (
+                isinstance(self.block_frames, int)
+                and not isinstance(self.block_frames, bool)
+                and self.block_frames > 0):
+            raise ValueError(
+                f"{name}: 'block_frames' must be a positive integer, not "
+                f"{self.block_frames!r}.")
+        if self.recenter not in ('none', 'half'):
+            shift = self.recenter
+            if not (isinstance(shift, (tuple, list)) and len(shift) == 3
+                    and all(isinstance(value, (int, float))
+                            and not isinstance(value, bool)
+                            and math.isfinite(value) for value in shift)):
+                raise ValueError(
+                    f"{name}: 'recenter' must be 'none', 'half', or a triple "
+                    f"of finite numbers, not {shift!r}.")
+            object.__setattr__(self, 'recenter',
+                               tuple(float(value) for value in shift))
+        if self.pair_species is not None:
+            if self.pair_species not in self.selections:
+                raise ValueError(
+                    f"{name}: 'pair_species' must be a label in "
+                    f"'selections', one of {list(self.selections)}, not "
+                    f"{self.pair_species!r}.")
+            if self.contact_cutoff is None:
+                raise ValueError(
+                    f"{name}: 'pair_species' needs 'contact_cutoff'.")
+        if self.contact_cutoff is not None and not _is_per_whole(
+                self.contact_cutoff):
+            raise ValueError(
+                f"{name}: 'contact_cutoff' must be a finite positive number "
+                f"or a callable, not {self.contact_cutoff!r}.")
+
+        if self.binders is not None:
+            if self.binders.patches not in self.selections \
+                    or self.binders.patches == self.chain:
+                raise ValueError(
+                    f"{name}: the patches of 'binders' must be a label in "
+                    f"'selections' other than the chain {self.chain!r}, "
+                    f"not {self.binders.patches!r}.")
+            unlisted = [
+                series for series in self.binders.series.values()
+                if series not in self.project.tseries_properties]
+            if unlisted:
+                raise ValueError(
+                    f"{name}: 'binders' names the series {unlisted}, which "
+                    f"are not among the project's 'tseries_properties' "
+                    f"{list(self.project.tseries_properties)}.")
+
+    @staticmethod
+    def resolve(value: PerWhole, parser: ParserBase) -> float:
+        """
+        The number a :py:data:`PerWhole` quantity takes for one whole.
+
+        Parameters
+        ----------
+        value : :py:data:`PerWhole`
+            A number, returned as a float, or a function of `parser`.
+        parser : ParserBase
+            The whole's parser, passed to a callable `value`.
+
+        Returns
+        -------
+        float
+            The number for this whole.
+
+        Raises
+        ------
+        ValueError
+            If `value`, or what a callable `value` returns, is anything but
+            a finite positive number: a Python or NumPy integer or float,
+            not a bool.
+
+        Examples
+        --------
+        >>> from polyphys.tests.synthetic import ChainCyl
+        >>> whole = ChainCyl(
+        ...     'N200r10.5lz50ac0.5nc100dt0.005bdump1adump1ens1',
+        ...     'whole', 'all')
+        >>> ProbeSpec.resolve(0.5, whole)
+        0.5
+        >>> ProbeSpec.resolve(lambda info: info.dmon + info.dcrowd, whole)
+        1.5
+        >>> ProbeSpec.resolve(-1.0, whole)
+        Traceback (most recent call last):
+        ...
+        ValueError: A per-whole quantity of N200r10.5lz50ac0.5nc100dt0.005b...
+
+        Notes
+        -----
+        :math:`O(1)` beyond the cost of the callable.
+
+        .. versionadded:: 0.7.0
+
+        .. versionchanged:: 1.0.0
+           A callable may return a NumPy integer or float, such as
+           ``numpy.float32``, where only a Python number or
+           ``numpy.float64`` was accepted. A constant `value` is checked
+           with the same rule, where it was returned as ``float(value)``.
+        """
+        result = value(parser) if callable(value) else value
+        return _check_resolved(
+            result, f"A per-whole quantity of {parser.name}")
+
+    @property
+    def name(self) -> str:
+        """
+        The project name, from the project spec.
+        """
+        return self.project.name
+
+    @property
+    def parser(self) -> type[ParserBase]:
+        """
+        The study's parser class, from the project spec.
+        """
+        return self.project.parser
+
+    @property
+    def geometry(self) -> GeometryT:
+        """
+        The study's geometry, from the project spec.
+        """
+        return self.project.geometry
+
+# ---------------------------------------------------------------------------
+# Analysis records
+# ---------------------------------------------------------------------------
+
+
+#: A post-hook ``(wholes, context) -> tuple[Derived, ...]``: see
+#: :mod:`polyphys.analyze.pipeline`, "Notation", and its hooks. A hook may
+#: also declare the names of the artifacts it returns with a method
+#: ``outputs(prop) -> tuple[str, ...]``, which :class:`AnalysisTable` reads
+#: to reject a repeated name when the table is built; every hook of
+#: :mod:`polyphys.analyze.pipeline` declares them.
+#:
+#: .. versionadded:: 0.6.0
+#:
+#: .. versionchanged:: 0.9.0
+#:    The optional ``outputs`` method.
+PostHook = Callable[['ArrayWholes', 'HookContext'], tuple['Derived', ...]]
+
+
+@dataclass(frozen=True)
+class PropertySpec:
+    """
+    One probe artifact of a particle group, and how it reduces.
+
+    Attributes
+    ----------
+    name : str
+        The property's name without its species, such as ``'gyrT'`` or
+        ``'rHist'``.
+    species : str
+        The species the property is measured on, such as ``'Mon'``; the
+        empty string for a property without one, such as an edge file.
+    relation : {'tseries', 'histogram', 'bin_edge'}
+        How the segments of a whole combine; see
+        :mod:`polyphys.analyze.pipeline`, "Notation".
+    whole_type : {'vector', 'matrix', 'bin_edge'}
+        The shape of one whole as loaded; see
+        :mod:`polyphys.analyze.pipeline`, "Notation".
+    edge_prop : str, optional
+        The property of the file that holds this histogram's bin edges, such
+        as ``'rEdgeMon'`` for ``'rHistMon'``. Only for a ``'vector'``
+        ``'histogram'``.
+    post_hook : callable, optional
+        A post-hook ``(wholes, context) -> tuple[Derived, ...]``; see
+        :mod:`polyphys.analyze.pipeline`, "Notation". ``None`` passes the
+        wholes through under `prop`.
+
+    Raises
+    ------
+    ValueError
+        If `name` is empty; if `relation` or `whole_type` is unknown; if
+        exactly one of them is ``'bin_edge'``; or if `edge_prop` is given
+        for anything but a ``'vector'`` ``'histogram'``.
+
+    Notes
+    -----
+    The named constructors :func:`tseries`, :func:`histogram`,
+    :func:`histogram_2d`, :func:`edge`, and :func:`matrix_tseries` build the
+    kinds the studies use, so a table reads as data.
+
+    Examples
+    --------
+    >>> spec = PropertySpec('rHist', 'Mon', 'histogram', 'vector',
+    ...                     edge_prop='rEdgeMon')
+    >>> spec.prop, spec.has_edges
+    ('rHistMon', True)
+
+    An edge file is a ``'bin_edge'`` in both its relation and its shape:
+
+    >>> PropertySpec('xEdge', '', 'bin_edge', 'vector')
+    Traceback (most recent call last):
+    ...
+    ValueError: 'xEdge': relation 'bin_edge' and whole_type 'vector' ...
+
+    .. versionadded:: 0.6.0
+    """
+
+    name: str
+    species: EntityT
+    relation: WholeRelationT
+    whole_type: Literal['vector', 'matrix', 'bin_edge']
+    edge_prop: PropertyT | None = None
+    post_hook: 'PostHook | None' = None
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("A property's name must not be empty.")
+        if self.relation not in ('tseries', 'histogram', 'bin_edge'):
+            raise ValueError(
+                f"'{self.prop}': relation must be 'tseries', 'histogram', or "
+                f"'bin_edge', not '{self.relation}'."
+            )
+        if self.whole_type not in ('vector', 'matrix', 'bin_edge'):
+            raise ValueError(
+                f"'{self.prop}': whole_type must be 'vector', 'matrix', or "
+                f"'bin_edge', not '{self.whole_type}'."
+            )
+        if (self.relation == 'bin_edge') != (self.whole_type == 'bin_edge'):
+            raise ValueError(
+                f"'{self.prop}': relation '{self.relation}' and whole_type "
+                f"'{self.whole_type}' do not match; an edge file is "
+                "'bin_edge' in both."
+            )
+        if self.edge_prop is not None and not (
+            self.relation == 'histogram' and self.whole_type == 'vector'
+        ):
+            raise ValueError(
+                f"'{self.prop}': edge_prop is only valid for a 'vector' "
+                f"'histogram', not a '{self.whole_type}' '{self.relation}'."
+            )
+
+    @property
+    def prop(self) -> PropertyT:
+        """
+        The property as it appears in file names, `name` then `species`.
+        """
+        return self.name + self.species
+
+    @property
+    def has_edges(self) -> bool:
+        """
+        Whether the property has a bin-edge file.
+        """
+        return self.edge_prop is not None
+
+
+@dataclass(frozen=True)
+class AnalysisTable:
+    """
+    The analysis of one particle group of a study, as data.
+
+    Attributes
+    ----------
+    group : str
+        The particle group whose artifacts the table reduces.
+    lineage : {'segment', 'whole'}
+        The lineage of the group's probe artifacts; see
+        :mod:`polyphys.analyze.pipeline`, "Notation".
+    stamps : bool
+        Whether the group's stamp files are combined by
+        :func:`~polyphys.analyze.pipeline.reduce_stamps`.
+    properties : tuple of PropertySpec
+        The artifacts to reduce, each listed once.
+
+    Raises
+    ------
+    ValueError
+        If `lineage` is unknown; if two properties name the same artifact;
+        or if two outputs share a name, among the property of each entry
+        without a hook and the names each hook declares with its
+        ``outputs`` method, so that no output overwrites another when
+        :func:`~polyphys.analyze.pipeline.reduce_space` runs. A hook that
+        declares nothing is checked when it runs. As a hook's
+        ``outputs`` raises, such as for a hook given a property it cannot
+        reduce.
+
+    Examples
+    --------
+    >>> table = AnalysisTable('bug', 'whole', True, (tseries('gyrT', 'Mon'),))
+    >>> table.lineage, len(table.properties)
+    ('whole', 1)
+
+    Listing an artifact twice is an error, so a table cannot reduce one file
+    two ways by accident:
+
+    >>> AnalysisTable('bug', 'whole', True,
+    ...               (tseries('gyrT', 'Mon'), tseries('gyrT', 'Mon')))
+    Traceback (most recent call last):
+    ...
+    ValueError: Properties listed more than once: ['gyrTMon'].
+
+    So is a hook output that another entry also produces:
+
+    >>> from polyphys.analyze.pipeline import TimeAverage
+    >>> AnalysisTable('bug', 'whole', True, (
+    ...     tseries('gyrT', 'Mon', post_hook=TimeAverage('fsdT')),
+    ...     tseries('fsdT', 'Mon')))
+    Traceback (most recent call last):
+    ...
+    ValueError: Outputs named more than once: ['fsdTMon'].
+
+    Notes
+    -----
+    Construction is :math:`O(p + o)` for :math:`p` properties and the
+    :math:`o` outputs their hooks declare.
+
+    .. versionadded:: 0.6.0
+
+    .. versionchanged:: 0.9.0
+       Repeated output names are rejected.
+    """
+
+    group: GroupT
+    lineage: PrimitiveLineageT
+    stamps: bool
+    properties: tuple[PropertySpec, ...]
+
+    def __post_init__(self) -> None:
+        if self.lineage not in ('segment', 'whole'):
+            raise ValueError(
+                f"lineage must be 'segment' or 'whole', not "
+                f"'{self.lineage}'."
+            )
+        object.__setattr__(self, 'properties', tuple(self.properties))
+        seen: set[str] = set()
+        repeated: list[str] = []
+        for prop in self.properties:
+            if prop.prop in seen and prop.prop not in repeated:
+                repeated.append(prop.prop)
+            seen.add(prop.prop)
+        if repeated:
+            raise ValueError(f"Properties listed more than once: {repeated}.")
+        outputs: set[PropertyT] = set()
+        repeated_outputs: list[PropertyT] = []
+        for prop in self.properties:
+            for name in _declared_outputs(prop):
+                if name in outputs and name not in repeated_outputs:
+                    repeated_outputs.append(name)
+                outputs.add(name)
+        if repeated_outputs:
+            raise ValueError(
+                f"Outputs named more than once: {repeated_outputs}.")
+
+
+def _declared_outputs(prop: PropertySpec) -> tuple[PropertyT, ...]:
+    """
+    The names of the artifacts that `prop` yields: its own without a hook,
+    the hook's declared ``outputs``, or none for a hook that declares none.
+    """
+    if prop.post_hook is None:
+        return (prop.prop,)
+    declare = getattr(prop.post_hook, 'outputs', None)
+    if declare is None:
+        return ()
+    return tuple(declare(prop))
+
+
+def tseries(
+    name: str, species: EntityT, post_hook: 'PostHook | None' = None
+) -> PropertySpec:
+    """
+    A scalar time series: one value per frame, concatenated over segments.
+
+    Parameters
+    ----------
+    name : str
+        The property's name, such as ``'gyrT'``.
+    species : str
+        The species, such as ``'Mon'``.
+    post_hook : callable, optional
+        A post-hook; see :class:`PropertySpec`.
+
+    Returns
+    -------
+    PropertySpec
+        A ``'tseries'`` ``'vector'`` property.
+
+    Examples
+    --------
+    >>> tseries('gyrT', 'Mon').prop
+    'gyrTMon'
+
+    .. versionadded:: 0.6.0
+    """
+    return PropertySpec(name, species, 'tseries', 'vector',
+                        post_hook=post_hook)
+
+
+def histogram(
+    direction: DirectionT, species: EntityT,
+    post_hook: 'PostHook | None' = None,
+) -> PropertySpec:
+    """
+    A one-dimensional histogram with its bin-edge file.
+
+    Parameters
+    ----------
+    direction : str
+        The direction, such as ``'r'``, ``'z'``, or ``'theta'``: the property
+        is ``<direction>Hist<species>`` and its edges
+        ``<direction>Edge<species>``.
+    species : str
+        The species, such as ``'Crd'``.
+    post_hook : callable, optional
+        A post-hook; see :class:`PropertySpec`.
+
+    Returns
+    -------
+    PropertySpec
+        A ``'histogram'`` ``'vector'`` property with `edge_prop` set.
+
+    Examples
+    --------
+    >>> spec = histogram('r', 'Crd')
+    >>> spec.prop, spec.edge_prop
+    ('rHistCrd', 'rEdgeCrd')
+
+    .. versionadded:: 0.6.0
+    """
+    return PropertySpec(f'{direction}Hist', species, 'histogram', 'vector',
+                        edge_prop=f'{direction}Edge{species}',
+                        post_hook=post_hook)
+
+
+def histogram_2d(plane: str, species: EntityT) -> PropertySpec:
+    """
+    A two-dimensional histogram, summed over segments and stacked over wholes.
+
+    Parameters
+    ----------
+    plane : str
+        The plane as the probe phase names it, such as ``'xy'`` or
+        ``'xz'``: the property is ``<plane>Hist<species>``. Its edges are
+        the :func:`edge` properties of the plane's two directions.
+    species : str
+        The species, such as ``'Crd'``.
+
+    Returns
+    -------
+    PropertySpec
+        A ``'histogram'`` ``'matrix'`` property.
+
+    Examples
+    --------
+    >>> histogram_2d('xy', 'Crd').prop
+    'xyHistCrd'
+
+    .. versionadded:: 0.6.0
+    """
+    return PropertySpec(f'{plane}Hist', species, 'histogram', 'matrix')
+
+
+def edge(direction: DirectionT) -> PropertySpec:
+    """
+    A bin-edge file shared by the two-dimensional histograms of a direction.
+
+    Parameters
+    ----------
+    direction : str
+        The direction, such as ``'x'``: the property is
+        ``<direction>Edge``, with no species.
+
+    Returns
+    -------
+    PropertySpec
+        A ``'bin_edge'`` property.
+
+    Examples
+    --------
+    >>> edge('x').prop
+    'xEdge'
+
+    .. versionadded:: 0.6.0
+    """
+    return PropertySpec(f'{direction}Edge', '', 'bin_edge', 'bin_edge')
+
+
+def matrix_tseries(
+    name: str, species: EntityT, post_hook: 'PostHook | None' = None
+) -> PropertySpec:
+    """
+    A time series of arrays: one array per frame, concatenated over segments.
+
+    Parameters
+    ----------
+    name : str
+        The property's name, such as ``'principalT'`` (one matrix per frame)
+        or ``'clustersHistT'`` (one histogram per frame).
+    species : str
+        The species, such as ``'Mon'``.
+    post_hook : callable, optional
+        A post-hook; see :class:`PropertySpec`.
+
+    Returns
+    -------
+    PropertySpec
+        A ``'tseries'`` ``'matrix'`` property.
+
+    Examples
+    --------
+    >>> matrix_tseries('principalT', 'Mon').whole_type
+    'matrix'
+
+    .. versionadded:: 0.6.0
+    """
+    return PropertySpec(name, species, 'tseries', 'matrix',
+                        post_hook=post_hook)