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; aProjectSpecdeclares 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, howpolyphys.probereads 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, aBinderSpecof how their binding is counted.AnalysisTable, the analysis of one particle group, which lists aPropertySpecper probe artifact forreduce_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 itsProjectSpec.CHAIN_SIZE_OBSERVABLES, the names aProbeSpecmay 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 theProbeSpecof 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, andRecenterT, how a probe moves a frame’s positions.
Analysis records:
PropertySpecdescribes one probe artifact;tseries(),histogram(),histogram_2d(),edge(), andmatrix_tseries()build the kinds the studies use.AnalysisTablelists the properties of one group.PostHook, the type of a post-hook; the hooks themselves are inpolyphys.analyze.pipeline.
Dependencies#
Python standard library: dataclasses, math, numbers, types, typing.
polyphys.manage.types: domain type aliases such asGroupT.
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_roundcolumn (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
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. |
|
How a probe moves the positions of a frame before binning them. |
|
The chain-size observables that |
|
The eight per-frame binding counts that |
|
see |
Functions
|
A bin-edge file shared by the two-dimensional histograms of a direction. |
|
A one-dimensional histogram with its bin-edge file. |
|
A two-dimensional histogram, summed over segments and stacked over wholes. |
|
A time series of arrays: one array per frame, concatenated over segments. |
|
A scalar time series: one value per frame, concatenated over segments. |
Classes
|
The analysis of one particle group of a study, as data. |
|
How the binding of a study's two-patch binders to its chain is counted: the facts |
|
How the trajectories of one study are probed: the facts that |
|
The per-project facts that the analysis of a study needs and its parser class does not hold. |
|
One probe artifact of a particle group, and how it reduces. |
- class polyphys.spec.AnalysisTable(group, lineage, stamps, properties)[source]#
Bases:
objectThe 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; seepolyphys.analyze.pipeline, “Notation”.stamps (
bool) – Whether the group’s stamp files are combined byreduce_stamps().properties (
tupleofPropertySpec) – 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
outputsmethod, so that no output overwrites another whenreduce_space()runs. A hook that declares nothing is checked when it runs. As a hook’soutputsraises, such as for a hook given a property it cannot reduce.- Parameters:
group (str)
lineage (Literal['segment', 'whole'])
stamps (bool)
properties (tuple[PropertySpec, ...])
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.
- properties: tuple[polyphys.spec.PropertySpec, ...]#
- 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
BinderStatisticsmeasures, in the research code’s order: each attribute ofFrameBindingmapped 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 labelsHnsPatchandHnsCore,n_binders_bridgingis thenBridgeTHnsCoreartifact.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:
objectHow the binding of a study’s two-patch binders to its chain is counted: the facts
BinderStatisticsneeds beyond the selections of theProbeSpecthat 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 seriesnBoundT,nFreeT, andnEngagedT. 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 seriesnFreeT,nBridgeT,nDangleT,nCisT, andnTransT. 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. Only2is accepted, whichbinding_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 (
MappingofstrtoPropertyT) – Each attribute name ofFrameBindinginBINDER_SERIESmapped 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
seriesare \(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: ...
- polyphys.spec.CHAIN_SIZE_OBSERVABLES: tuple[str, ...] = ('transSizeT', 'fsdT', 'gyrT', 'rfloryT', 'asphericityT', 'shapeT', 'principalT')#
The chain-size observables that
ChainSizemeasures 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 thegyrTMonartifact.'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 methodoutputs(prop) -> tuple[str, ...], whichAnalysisTablereads to reject a repeated name when the table is built; every hook ofpolyphys.analyze.pipelinedeclares them.Added in version 0.6.0.
Changed in version 0.9.0: The optional
outputsmethod.- 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:
objectHow the trajectories of one study are probed: the facts that
polyphys.probeneeds beyond the study’sProjectSpec.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_OBSERVABLESand, for the scalar ones, against the project’stseries_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 inCHAIN_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 forasphericityT, the unwrap argument ofAtomGroup.asphericity:Falsefor a cylinder, which is periodic along its axis only, andTruefor a periodic cube. Every other observable,shapeTincluded, reads the positions as the dump gives them; seepolyphys.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 histogramsSpatialHistogramscollects, 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 contactsPairDistancescollects, such as'Foci';Nonewhen 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;Nonefor 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’stseries_properties.
- Variables:
name (
str) – The project name, from the project spec.parser (
typeofParserBase) – 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 neitherNonenor aBinderSpec.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’stseries_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’stseries_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#
- property parser: type[polyphys.manage.parser.ParserBase]#
The study’s parser class, from the project spec.
- project: polyphys.spec.ProjectSpec#
- static resolve(value, parser)[source]#
The number a
PerWholequantity takes for one whole.- Parameters:
value (
typing.Union[float,typing.Callable[[polyphys.manage.parser.ParserBase],float]]) – A number, returned as a float, or a function of parser.parser (
polyphys.manage.parser.ParserBase) – The whole’s parser, passed to a callable value.
- Returns:
The number for this whole.
- Return type:
- 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 ornumpy.float64was accepted. A constant value is checked with the same rule, where it was returned asfloat(value).
- class polyphys.spec.ProjectSpec(parser, group, divisor, physical_attrs, species_sizes, tseries_properties, *, crowder_attr)[source]#
Bases:
objectThe 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_longlineage, 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 thephi_bulk_c_roundcolumn of thespacetables.physical_attrs (
tuple[str,...]) – The parser attributes added as columns to thespacetables, 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 thespacetables add as a column and round intophi_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 (
tupleofDirectionT) – 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’sspacenames: each keyword of the parser’sspacepattern followed by*.space_hierarchy (
str) – A glob prefix of thespacenames: their first keyword and*.hierarchy (
str) – A glob prefix of theensemble_longnames: 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 atensemble_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)\).- property directions: tuple[Literal['x', 'y', 'z', 'r', 'theta'], ...]#
The directions of the density profiles in the parser’s geometry.
- parser: type[polyphys.manage.parser.ParserBase]#
- class polyphys.spec.PropertySpec(name, species, relation, whole_type, edge_prop=None, post_hook=None)[source]#
Bases:
objectOne 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; seepolyphys.analyze.pipeline, “Notation”.whole_type (
{'vector', 'matrix', 'bin_edge'}) – The shape of one whole as loaded; seepolyphys.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, ...]; seepolyphys.analyze.pipeline, “Notation”.Nonepasses 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:
Notes
The named constructors
tseries(),histogram(),histogram_2d(),edge(), andmatrix_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.
- post_hook: Optional[Callable[[dict[str, numpy.ndarray], polyphys.analyze.pipeline.HookContext], tuple[polyphys.analyze.pipeline.Derived, ...]]] = None#
- 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 recenterof 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)orlcubeis 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:
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:
direction (
typing.Literal['x','y','z','r','theta']) – 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 (
typing.Optional[typing.Callable[[dict[str,numpy.ndarray],polyphys.analyze.pipeline.HookContext],tuple[polyphys.analyze.pipeline.Derived,...]]]) – A post-hook; seePropertySpec.
- Returns:
A
'histogram''vector'property with edge_prop set.- Return type:
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:
- Returns:
A
'histogram''matrix'property.- Return type:
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:
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 (
typing.Optional[typing.Callable[[dict[str,numpy.ndarray],polyphys.analyze.pipeline.HookContext],tuple[polyphys.analyze.pipeline.Derived,...]]]) – A post-hook; seePropertySpec.
- Returns:
A
'tseries''matrix'property.- Return type:
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:
name (
str) – The property’s name, such as'gyrT'.species (
str) – The species, such as'Mon'.post_hook (
typing.Optional[typing.Callable[[dict[str,numpy.ndarray],polyphys.analyze.pipeline.HookContext],tuple[polyphys.analyze.pipeline.Derived,...]]]) – A post-hook; seePropertySpec.
- Returns:
A
'tseries''vector'property.- Return type:
Examples
>>> tseries('gyrT', 'Mon').prop 'gyrTMon'
Added in version 0.6.0.