"""\
==========================================================
: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 companion
repository polyphys-lab, which PolyPhys does not depend on.
.. 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
[docs]
@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}.")
[docs]
@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]}*"
[docs]
@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)}.")
[docs]
@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', ...]]
[docs]
@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
[docs]
@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))
[docs]
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)
[docs]
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)
[docs]
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')
[docs]
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')
[docs]
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)