polyphys.spec#

polyphys.spec#

This spec module holds the records that describe one study as data, every one of them in a module that imports neither MDAnalysis nor polyphys.probe, so a study’s spec builds without the mda extra:

  • ProjectSpec, the per-project facts that the parser class does not hold. A parser class declares how a study’s filenames read; a 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.

  • ProbeSpec, how 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 BinderSpec of how their binding is counted.

  • AnalysisTable, the analysis of one particle group, which lists a PropertySpec per probe artifact for 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.

Added in version 0.9.0: The records of polyphys.manage.projects and the table records and builders of polyphys.analyze.pipeline moved here; their old import paths warned with DeprecationWarning.

Changed in version 1.0.0: The old import paths are removed: polyphys.manage.projects no longer exists, and polyphys.analyze.pipeline no longer serves the table records and builders.

Contents#

Project and probe records:

  • ProjectSpec, a frozen record of one study.

  • ProbeSpec, a frozen record of how one study’s trajectories are probed, built beside its ProjectSpec.

  • CHAIN_SIZE_OBSERVABLES, the names a ProbeSpec may list as chain-size observables.

  • BinderSpec, a frozen record of how the binding of a study’s two-patch binders to its chain is counted, held by the ProbeSpec of a study with binders.

  • BINDER_SERIES, the eight binding counts and the stems of their time series.

  • PerWhole, a number or a function of a whole’s parser, and RecenterT, how a probe moves a frame’s positions.

Analysis records:

Dependencies#

Notation#

\(\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).

\(\Delta\)

The rounding step, divisor, of \(\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 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']

Module Attributes

PerWhole

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.

RecenterT

How a probe moves the positions of a frame before binning them.

CHAIN_SIZE_OBSERVABLES

The chain-size observables that 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.

BINDER_SERIES

The eight per-frame binding counts that BinderStatistics measures, in the research code's order: each attribute of 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.

PostHook

see polyphys.analyze.pipeline, "Notation", and its hooks.

Functions

edge(direction)

A bin-edge file shared by the two-dimensional histograms of a direction.

histogram(direction, species[, post_hook])

A one-dimensional histogram with its bin-edge file.

histogram_2d(plane, species)

A two-dimensional histogram, summed over segments and stacked over wholes.

matrix_tseries(name, species[, post_hook])

A time series of arrays: one array per frame, concatenated over segments.

tseries(name, species[, post_hook])

A scalar time series: one value per frame, concatenated over segments.

Classes

AnalysisTable(group, lineage, stamps, properties)

The analysis of one particle group of a study, as data.

BinderSpec(patches, binders, cutoff[, ...])

How the binding of a study's two-patch binders to its chain is counted: the facts BinderStatistics needs beyond the selections of the ProbeSpec that holds this record.

ProbeSpec(project, selections, chain, ...[, ...])

How the trajectories of one study are probed: the facts that polyphys.probe needs beyond the study's ProjectSpec.

ProjectSpec(parser, group, divisor, ...)

The per-project facts that the analysis of a study needs and its parser class does not hold.

PropertySpec(name, species, relation, whole_type)

One probe artifact of a particle group, and how it reduces.

class polyphys.spec.AnalysisTable(group, lineage, stamps, properties)[source]#

Bases: object

The analysis of one particle group of a study, as data.

Variables:
  • group (str) – The particle group whose artifacts the table reduces.

  • lineage ({'segment', 'whole'}) – The lineage of the group’s probe artifacts; see polyphys.analyze.pipeline, “Notation”.

  • stamps (bool) – Whether the group’s stamp files are combined by 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 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.

Parameters:

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 \(O(p + o)\) for \(p\) properties and the \(o\) outputs their hooks declare.

Added in version 0.6.0.

Changed in version 0.9.0: Repeated output names are rejected.

group: str#
lineage: Literal['segment', 'whole']#
properties: tuple[polyphys.spec.PropertySpec, ...]#
stamps: bool#
polyphys.spec.BINDER_SERIES: Mapping[str, tuple[str, str]] = mappingproxy({'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 eight per-frame binding counts that BinderStatistics measures, in the research code’s order: each attribute of 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.

Added in version 0.7.0.

class polyphys.spec.BinderSpec(patches, binders, cutoff, inclusive=True, patches_per_binder=2, store_distances=False, *, cis_threshold)[source]#

Bases: object

How the binding of a study’s two-patch binders to its chain is counted: the facts BinderStatistics needs beyond the selections of the ProbeSpec that holds this record.

Added in version 0.7.0.

Changed in version 1.0.0: cis_threshold is keyword-only and has no default.

Parameters:
  • patches (str) – 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 \(k\) are the ones at positions \(2k\) and \(2k + 1\) of the selection, in atom-ID order.

  • binders (str) – 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 \(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) – Whether a pair at exactly cutoff is a contact (\(r \le r_\mathrm{thres}\), the thesis criterion) or not (\(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) – The number of patches per binder. Only 2 is accepted, which binding_statistics() counts; the field is kept so that binders of another valence can be declared once a kernel counts them.

  • store_distances (bool) – 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.

Variables:

series (Mapping of str to PropertyT) – Each attribute name of FrameBinding in 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 series are \(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: ...
binders: str#
cis_threshold: int#
cutoff: float#
inclusive: bool#
patches: str#
patches_per_binder: int#
property series: Mapping[str, str]#

Each binding count’s attribute name mapped to the full name of its time series, in the research code’s order.

store_distances: bool#
polyphys.spec.CHAIN_SIZE_OBSERVABLES: tuple[str, ...] = ('transSizeT', 'fsdT', 'gyrT', 'rfloryT', 'asphericityT', 'shapeT', 'principalT')#

The chain-size observables that 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 \(3 \\times 3\) matrix; the others are scalars.

Added in version 0.7.0.

polyphys.spec.PerWhole#

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. ProbeSpec.resolve() turns either into the number for one whole.

Added in version 0.7.0.

alias of float | Callable[[ParserBase], float]

polyphys.spec.PostHook#

see 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 AnalysisTable reads to reject a repeated name when the table is built; every hook of polyphys.analyze.pipeline declares them.

Added in version 0.6.0.

Changed in version 0.9.0: The optional outputs method.

Type:

A post-hook (wholes, context) -> tuple[Derived, ...]

alias of Callable[[ArrayWholes, HookContext], tuple[Derived, …]]

class polyphys.spec.ProbeSpec(project, selections, chain, observables, unwrap, bin_sizes=dict(), histogram_species=(), block_frames=None, recenter='half', pair_species=None, contact_cutoff=None, minimum_image=True, binders=None)[source]#

Bases: object

How the trajectories of one study are probed: the facts that polyphys.probe needs beyond the study’s 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 CHAIN_SIZE_OBSERVABLES and, for the scalar ones, against the project’s tseries_properties.

Added in version 0.7.0.

Parameters:
  • project (polyphys.spec.ProjectSpec) – The study’s project spec.

  • selections (typing.Mapping[str, 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 (str) – The label in selections of the polymer chain, whose chain-size time series are named <observable><chain>.

  • observables (tuple[str, ...]) – The chain-size observables measured per frame, each a name in 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 polyphys.probe.chain_size.ChainSize.

  • bin_sizes (typing.Mapping[typing.Literal['x', 'y', 'z', 'r', 'theta'], typing.Union[float, typing.Callable[[polyphys.manage.parser.ParserBase], float]]]) – 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[str, ...]) – The labels in selections of the species whose spatial 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 | None) – The block length \(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 (typing.Union[typing.Literal['none', 'half'], tuple[float, float, float]]) – 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 (str | None) – The label in selections of the species whose pair distances and contacts PairDistances collects, such as 'Foci'; None when the study has no such species. Requires contact_cutoff.

  • contact_cutoff (typing.Union[float, typing.Callable[[polyphys.manage.parser.ParserBase], float], 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) – 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 (polyphys.spec.BinderSpec | None) – 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.

Variables:
  • name (str) – The project name, from the project spec.

  • parser (type of ParserBase) – The study’s parser class, from the project spec.

  • geometry (GeometryT) – The study’s geometry, from the project spec.

Raises:
  • TypeError – If project is not a ProjectSpec, or if binders is neither None nor a 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 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 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 \(O(s + o + b + h)\) for \(s\) selections, \(o\) observables, \(b\) bin sizes, and \(h\) histogram species; every derived attribute is \(O(1)\).

bin_sizes: Mapping[Literal['x', 'y', 'z', 'r', 'theta'], Union[float, Callable[[polyphys.manage.parser.ParserBase], float]]]#
binders: polyphys.spec.BinderSpec | None#
block_frames: int | None#
chain: str#
contact_cutoff: Union[float, Callable[[polyphys.manage.parser.ParserBase], float], None]#
property geometry: Literal['cubic', 'cylindrical']#

The study’s geometry, from the project spec.

histogram_species: tuple[str, ...]#
minimum_image: bool#
property name: str#

The project name, from the project spec.

observables: tuple[str, ...]#
pair_species: str | None#
property parser: type[polyphys.manage.parser.ParserBase]#

The study’s parser class, from the project spec.

project: polyphys.spec.ProjectSpec#
recenter: Union[Literal['none', 'half'], tuple[float, float, float]]#
static resolve(value, parser)[source]#

The number a PerWhole quantity takes for one whole.

Parameters:
Returns:

The number for this whole.

Return type:

float

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

\(O(1)\) beyond the cost of the callable.

Added in version 0.7.0.

Changed in version 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).

selections: Mapping[str, str]#
unwrap: bool#
class polyphys.spec.ProjectSpec(parser, group, divisor, physical_attrs, species_sizes, tseries_properties, *, crowder_attr)[source]#

Bases: object

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[polyphys.manage.parser.ParserBase]) – The study’s concrete parser class.

  • group (str) – The particle group of the polymer, such as 'bug' or 'nucleoid'; one of the parser’s groups, and not 'all'.

  • divisor (float) – The step \(\Delta > 0\) to which the bulk volume fraction of crowders \(\phi_c\) (crowder_attr, dimensionless) is rounded in the phi_bulk_c_round column of the space tables.

  • physical_attrs (tuple[str, ...]) – The parser attributes added as columns to the space tables, in column order.

  • species_sizes (typing.Mapping[str, 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[str, ...]) – 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 \(\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.

    Added in version 0.9.0.

Variables:
  • name (str) – The parser class name, which is the project name.

  • geometry (GeometryT) – The parser’s geometry.

  • topology (TopologyT) – The parser’s polymer topology.

  • directions (tuple of 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 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 \(O(a + s + n)\) for \(a\) physical attributes, \(s\) species, and the \(n\) names that attributes_at() collects; every derived attribute is \(O(1)\).

crowder_attr: str#
property directions: tuple[Literal['x', 'y', 'z', 'r', 'theta'], ...]#

The directions of the density profiles in the parser’s geometry.

divisor: float#
property geometry: Literal['cubic', 'cylindrical']#

The parser’s geometry.

group: str#
property hierarchy: str#

their first keyword and *.

Type:

A glob prefix of the ensemble_long names

property name: str#

The parser class name, which is the project name.

parser: type[polyphys.manage.parser.ParserBase]#
physical_attrs: tuple[str, ...]#
property space_hierarchy: str#

their first keyword and *.

Type:

A glob prefix of the space names

property space_pattern: str#

A glob pattern that matches the study’s space names.

species_sizes: Mapping[str, str]#
property topology: str#

The parser’s polymer topology.

tseries_properties: tuple[str, ...]#
class polyphys.spec.PropertySpec(name, species, relation, whole_type, edge_prop=None, post_hook=None)[source]#

Bases: object

One probe artifact of a particle group, and how it reduces.

Variables:
  • 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 polyphys.analyze.pipeline, “Notation”.

  • whole_type ({'vector', 'matrix', 'bin_edge'}) – The shape of one whole as loaded; see 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 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'.

Parameters:
  • name (str)

  • species (str)

  • relation (Literal['histogram', 'tseries', 'bin_edge'])

  • whole_type (Literal['vector', 'matrix', 'bin_edge'])

  • edge_prop (str | None)

  • post_hook (PostHook | None)

Notes

The named constructors tseries(), histogram(), histogram_2d(), edge(), and 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' ...

Added in version 0.6.0.

edge_prop: str | None = None#
property has_edges: bool#

Whether the property has a bin-edge file.

name: str#
post_hook: Optional[Callable[[dict[str, numpy.ndarray], polyphys.analyze.pipeline.HookContext], tuple[polyphys.analyze.pipeline.Derived, ...]]] = None#
property prop: str#

The property as it appears in file names, name then species.

relation: Literal['histogram', 'tseries', 'bin_edge']#
species: str#
whole_type: Literal['vector', 'matrix', 'bin_edge']#
polyphys.spec.RecenterT#

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.

Added in version 0.7.0.

alias of Literal[‘none’, ‘half’] | tuple[float, float, float]

polyphys.spec.edge(direction)[source]#

A bin-edge file shared by the two-dimensional histograms of a direction.

Parameters:

direction (typing.Literal['x', 'y', 'z', 'r', 'theta']) – The direction, such as 'x': the property is <direction>Edge, with no species.

Returns:

A 'bin_edge' property.

Return type:

polyphys.spec.PropertySpec

Examples

>>> edge('x').prop
'xEdge'

Added in version 0.6.0.

polyphys.spec.histogram(direction, species, post_hook=None)[source]#

A one-dimensional histogram with its bin-edge file.

Parameters:
Returns:

A 'histogram' 'vector' property with edge_prop set.

Return type:

polyphys.spec.PropertySpec

Examples

>>> spec = histogram('r', 'Crd')
>>> spec.prop, spec.edge_prop
('rHistCrd', 'rEdgeCrd')

Added in version 0.6.0.

polyphys.spec.histogram_2d(plane, species)[source]#

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 edge() properties of the plane’s two directions.

  • species (str) – The species, such as 'Crd'.

Returns:

A 'histogram' 'matrix' property.

Return type:

polyphys.spec.PropertySpec

Examples

>>> histogram_2d('xy', 'Crd').prop
'xyHistCrd'

Added in version 0.6.0.

polyphys.spec.matrix_tseries(name, species, post_hook=None)[source]#

A time series of arrays: one array per frame, concatenated over segments.

Parameters:
Returns:

A 'tseries' 'matrix' property.

Return type:

polyphys.spec.PropertySpec

Examples

>>> matrix_tseries('principalT', 'Mon').whole_type
'matrix'

Added in version 0.6.0.

polyphys.spec.tseries(name, species, post_hook=None)[source]#

A scalar time series: one value per frame, concatenated over segments.

Parameters:
Returns:

A 'tseries' 'vector' property.

Return type:

polyphys.spec.PropertySpec

Examples

>>> tseries('gyrT', 'Mon').prop
'gyrTMon'

Added in version 0.6.0.