polyphys.analyze.sumrule#
polyphys.analyze.sumrule#
The polyphys.analyze.sumrule module tests the density sum rule of
Jeon et al. (2016) on the ensemble-averaged density profiles of a space: it
scales each species’ profile by its particle size, normalizes it by a
reference value, folds a longitudinal profile about the polymer’s center,
and sums the species’ scaled profiles state point by state point. The
profiles come from the ensAvg stage of the artifact lineage that
polyphys.manage.organizer builds; the per-frame densities behind them
are the caller’s work.
The profiles must be the raw ensemble averages, in their physical units: a
volume fraction or a number density, not a profile already divided by its
sum, its integral, or its maximum. The sum rule relates the species to each
other through their physical scales, so a species normalized on its own
enters the sum \(\sum_i \phi_i / a_i\) with an arbitrary weight and
<prop>-scale loses its unit and its comparability with the nominal bulk
value. Only the <prop>-norm columns of such a profile survive, because
dividing by the profile’s own 'first' or 'max' value is
scale-invariant. space_profiles() warns when a profile sums to one,
the signature of a profile normalized by its sum, but cannot detect the
other normalizations from one profile.
Notation#
- \(a_i\)
The particle diameter of species \(i\), in the monomer diameter: the parser attribute that the study’s
species_sizesnames for it.- \(\phi_i(x)\), \(\rho_i(x)\)
The local volume fraction (dimensionless) and local number density (per cubic monomer diameter) of species \(i\), related by \(\phi_i = \pi a_i^3 \rho_i / 6\).
- \(r\)
The radial coordinate: the distance from the cylinder axis in a cylinder and from the polymer’s center of mass in a periodic cube. The bins of an
rprofile run outward from \(r = 0\).- \(z\)
The longitudinal coordinate: the axial distance from the polymer’s center of mass in a cylinder, with bins symmetric about \(z = 0\).
- scaled profile
One term of the sum rule, the column
<prop>-scale: \(\phi_i / a_i\) for a volume fraction and \(a_i^2 \rho_i\) for a number density.- normalizer
The reference value a scaled profile, or the species sum, is divided by: see
NormalizerT.- \(D\), \(a_c\)
The cylinder diameter and a crowder diameter; the ratio \(\kappa = (D - a_c) / a_c\) sets how far the crowder layering on the wall reaches inward.
Contents#
normalize_r()andnormalize_z(): normalize one scaled profile, folding a longitudinal one about \(z = 0\).space_profiles(): scale, normalize, and annotate every ensemble-averaged profile of one species across a space.space_profiles_from_spec(): the same, with the study’s choices read from itsProjectSpec.sum_rule_profiles(): sum the species’ scaled profiles and normalize the sum.PROFILE_NORMALIZERSandSUM_NORMALIZERS: the default normalizers by geometry and direction.
Dependencies#
numpy and pandas.
polyphys.manage.organizer:make_database()andcreate_fullname().
References
C. Jeon, C. Hyeon, Y. Jung, and B.-Y. Ha, “How are molecular crowding and the spatial organization of a biopolymer interrelated”, Soft Matter 12, 9786-9796 (2016). https://doi.org/10.1039/c6sm01924b
J. Kim, C. Jeon, H. Jeong, Y. Jung, and B.-Y. Ha, “A polymer in a crowded and confined space: effects of crowder size and poly-dispersity”, Soft Matter 11, 1877-1888 (2015). https://doi.org/10.1039/c4sm02198c
A. H. Sadeghi Isfahani, PhD thesis, University of Waterloo (2024), Chapter 3.
Added in version 0.6.0.
Module Attributes
The default normalizer of a density profile, by (geometry, direction): |
|
The default normalizer of the species sum, by (geometry, direction): |
Functions
|
Normalize the scaled radial profile |
|
Normalize the scaled longitudinal profile |
|
Scale and normalize the ensemble-averaged density profiles of one species across a space for the density sum rule, add the physical attributes of each state point, and concatenate them into one DataFrame. |
|
Scale and normalize the ensemble-averaged density profiles of one species across a space for the density sum rule, with the columns, the species sizes, and the rounding step the study's spec declares. |
|
Sum the scaled density profiles of several species, state point by state point, and normalize the sum by its own reference value: the left side of the density sum rule. |
- polyphys.analyze.sumrule.PROFILE_NORMALIZERS: dict[tuple[Literal['cubic', 'cylindrical'], Literal['x', 'y', 'z', 'r', 'theta']], Union[Literal['first', 'last', 'max'], float, Callable[[pandas.DataFrame], float]]] = {('cubic', 'r'): 'max', ('cylindrical', 'r'): 'first', ('cylindrical', 'z'): 'max'}#
The default normalizer of a density profile, by (geometry, direction):
'first'forrin a cylinder,'max'otherwise.Added in version 0.6.0.
- polyphys.analyze.sumrule.SUM_NORMALIZERS: dict[tuple[Literal['cubic', 'cylindrical'], Literal['x', 'y', 'z', 'r', 'theta']], Union[Literal['first', 'last', 'max'], float, Callable[[pandas.DataFrame], float]]] = {('cubic', 'r'): 'last', ('cylindrical', 'r'): 'first', ('cylindrical', 'z'): 'last'}#
The default normalizer of the species sum, by (geometry, direction):
'first'forrin a cylinder,'last'otherwise.Added in version 0.6.0.
- polyphys.analyze.sumrule.normalize_r(prop, ens_avg, normalizer='first')[source]#
Normalize the scaled radial profile
<prop>-scaleof an ensemble-averaged distribution by a reference value.The radial coordinate \(r\) is the distance from the cylinder axis in a cylinder and from the polymer’s center of mass in a periodic cube, in the monomer diameter; the profile’s bins run outward from \(r = 0\).
- Parameters:
prop (
str) – The full property name, such as'rPhiCrd'; the input has the column<prop>-scale.ens_avg (
pandas.DataFrame) – The ensemble-averaged distribution, one row per bin. It is not modified.normalizer (
typing.Union[typing.Literal['first','last','max'],float,typing.Callable[[pandas.DataFrame],float]]) – The reference value:'first'is the value at \(r = 0\),'last'the value of the outermost bin,'max'the maximum; a number is used as given; a function is called with ens_avg and returns the value.
- Returns:
A copy of ens_avg with two more columns:
<prop>-normalizer, the reference value, and<prop>-norm,<prop>-scaledivided by it.- Return type:
- Raises:
ValueError – If normalizer is none of the accepted forms.
- Warns:
UserWarning – If the reference value is zero;
<prop>-normis then zero.
Examples
>>> profile = pd.DataFrame({'bin_center': [0.5, 1.5, 2.5], ... 'rPhiCrd-scale': [2.0, 4.0, 1.0]}) >>> normalize_r('rPhiCrd', profile)['rPhiCrd-norm'].tolist() [1.0, 2.0, 0.5] >>> normalize_r('rPhiCrd', profile, 'max')['rPhiCrd-norm'].tolist() [0.5, 1.0, 0.25] >>> normalize_r('rPhiCrd', profile, 8.0)['rPhiCrd-norm'].tolist() [0.25, 0.5, 0.125]
A function sees the whole frame, so it can average the inner bins:
>>> normalize_r('rPhiCrd', profile, ... lambda df: df['rPhiCrd-scale'].iloc[:2].mean() ... )['rPhiCrd-normalizer'].iloc[0] np.float64(3.0)
Notes
Time and space are \(O(n_\text{bins} \, n_\text{cols})\) for the copy. The references of the sum rule are in
space_profiles().Added in version 0.6.0.
- polyphys.analyze.sumrule.normalize_z(prop, ens_avg, normalizer='max', fold=True)[source]#
Normalize the scaled longitudinal profile
<prop>-scaleof an ensemble-averaged distribution by a reference value and, by default, fold it about \(z = 0\).The longitudinal coordinate \(z\) is the axial distance from the polymer’s center of mass, in the monomer diameter. Folding needs bins symmetric about \(z = 0\); it averages bin \(i\) with its mirror bin \(n - 1 - i\) and keeps the center bin of an odd count as it is; the folded
bin_centeris \(|z|\). The one exception is<prop>-scale-normalized_curve, a distribution over the bins, whose mirror bins are summed, so the folded curve is the distribution of \(|z|\) and still sums to one.- Parameters:
prop (
str) – The full property name, such as'zRhoMon'; the input has the column<prop>-scale.ens_avg (
pandas.DataFrame) – The ensemble-averaged distribution, one row per bin, with abin_centercolumn when fold is True. It is not modified.normalizer (
typing.Union[typing.Literal['first','last','max'],float,typing.Callable[[pandas.DataFrame],float]]) – The reference value, as innormalize_r();'max'is the far-field value of a crowder profile and the center value of a monomer profile when each is monotone in \(|z|\).fold (
bool) – Whether to fold the profile about \(z = 0\).
- Returns:
A copy of ens_avg with
<prop>-normalizerand<prop>-normadded, as innormalize_r(). With fold, every numeric column is averaged with its mirror bin, the other columns are those of the \(z \geq 0\) half, and the result hasceil(n / 2)rows ordered by \(|z|\).- Return type:
- Raises:
ValueError – If normalizer is none of the accepted forms, or fold is True and ens_avg has no
bin_centercolumn or its bin centers do not increase symmetrically about \(z = 0\), to a tolerance of1e-9times the largest \(|z|\).- Warns:
UserWarning – If the reference value is zero;
<prop>-normis then zero.
Examples
An even number of bins folds to half as many:
>>> profile = pd.DataFrame({'bin_center': [-1.5, -0.5, 0.5, 1.5], ... 'zRhoMon-scale': [1.0, 3.0, 3.0, 1.0]}) >>> normalize_z('zRhoMon', profile) bin_center zRhoMon-scale zRhoMon-normalizer zRhoMon-norm 0 0.5 3.0 3.0 1.000000 1 1.5 1.0 3.0 0.333333
An odd number keeps its center bin:
>>> profile = pd.DataFrame({'bin_center': [-1.0, 0.0, 1.0], ... 'zRhoMon-scale': [2.0, 4.0, 2.0]}) >>> normalize_z('zRhoMon', profile)['zRhoMon-norm'].tolist() [1.0, 0.5]
Notes
The
-varand-semcolumns of the input are averaged like every other numeric column, which is what the research code did; the result is not the uncertainty of the folded mean, which would need the per-replicate folded profiles. Time and space are \(O(n_\text{bins} \, n_\text{cols})\).Added in version 0.6.0.
Changed in version 0.9.0: Reject bins that are not symmetric about \(z = 0\), and fold
<prop>-scale-normalized_curveby summing mirror bins.
- polyphys.analyze.sumrule.space_profiles(input_database, quantity, direction, species, parser, hierarchy, physical_attrs, group, species_sizes, *, crowders=('Crd',), normalizer=None, divisor=0.025, round_to=3, is_save=False, crowder_attr='phi_bulk_c')[source]#
Scale and normalize the ensemble-averaged density profiles of one species across a space for the density sum rule, add the physical attributes of each state point, and concatenate them into one DataFrame.
The density sum rule of Jeon et al. (2016), eqns (5) to (7), states that in a crowded polymer solution the volume fractions \(\phi_i(x)\) of the species \(i\), each rescaled by its particle diameter \(a_i\), sum to the far-field value of the crowder term:
\[\sum_i \frac{\phi_i(x)}{a_i} \approx \frac{\phi_c(\infty)}{a_c}, \qquad \sum_i a_i^2 \rho_i(x) \approx a_c^2 \rho_c(\infty),\]where the number density \(\rho_i = 6 \phi_i / (\pi a_i^3)\) makes the two forms the same statement, and \(x\) is the radial coordinate \(r\) (the distance from the cylinder axis in a cylinder and from the polymer’s center of mass in a periodic cube) or the longitudinal coordinate \(z\) (the axial distance from the polymer’s center of mass). This function builds one term of the sum: for
quantity='Phi'the scaled profile<prop>-scaleis the volume fraction divided by the species’ diameter, and forquantity='Rho'the number density times the diameter squared.sum_rule_profiles()builds the sum.The input profiles must be the raw ensemble averages, in their physical units. A profile normalized beforehand, by its sum, its integral, or its maximum, enters the species sum with an arbitrary weight, and its
<prop>-scaleloses its unit; only its<prop>-normsurvives, since dividing by the profile’s own reference value is scale-invariant. A profile whose<prop>-meansums to one, as one normalized by its sum does, raises aUserWarningnaming the file; the other normalizations cannot be told from one profile.- Parameters:
input_database (
str) – Path to the directory of the ensemble-averaged profiles, named<ensemble_long>-<group>-<direction><quantity><species>-ensAvg.csv, ending with a path separator. Each file has abin_centercolumn and a<direction><quantity><species>-meancolumn holding the raw ensemble-averaged volume fraction or number density.quantity (
typing.Literal['Rho','Phi']) – The number density or the volume fraction.direction (
typing.Literal['x','y','z','r','theta']) – The coordinate of the profile;'z'exists in a cylinder only.species (
str) – The species label of the profile, such as'Mon'or'Crd'; a key of species_sizes.parser (
type[polyphys.manage.parser.ParserBase]) – The study’s parser class; its geometry chooses the default normalizer and the recentered columns.hierarchy (
str) – Pattern prefix of the filenames, such as'N*'.physical_attrs (
list[str]) – The parser attributes added as columns to the result.group (
str) – The particle group of the profiles, usually'all'.species_sizes (
typing.Mapping[str,str]) – Each species label mapped to the parser attribute holding its particle diameter, in the monomer diameter: thespecies_sizesof the study’sProjectSpec.crowders (
typing.Sequence[str]) – The crowder species, each a key of species_sizes; one set ofbin_centercolumns in crowder units is added per crowder.normalizer (
typing.Union[typing.Literal['first','last','max'],float,typing.Callable[[pandas.DataFrame,typing.Any],float],None]) – The reference value of the normalization. None takes the default ofPROFILE_NORMALIZERSfor the parser’s geometry and direction. Otherwise'first','last','max', or a number, as innormalize_r(); or a function of two arguments, the scaled profile and the parser instance of the file, returning the value, so thatlambda df, info: info.phi_bulk_c / info.dcrowdnormalizes a'Phi'profile by the nominal bulk volume fraction of crowders in scale units. An explicit value is logged at INFO with the default it replaces.divisor (
float) – Rounding step of the bulk volume fraction of crowders named by crowder_attr.round_to (
int) – Number of decimal places of that rounding.is_save (
bool) – If True, save the result as<space>-<group>-<direction><quantity><species>-normalizedRescaled-space.csvin theanalysisphase’sspacedirectory, whichmake_database()creates next to input_database, and log the path at INFO.crowder_attr (
str) – The parser attribute holding the bulk volume fraction of crowders, added as a column of that name and rounded intophi_bulk_c_round.
- Returns:
The profiles of every file, concatenated in filename order, with
<prop> = <direction><quantity><species>and these columns added to each file’s own:<prop>-scaler: the diameter \(a\) for'Phi'and \(a^2\) for'Rho';<prop>-sumrule_constantrepeats it.<prop>-scale:<prop>-meandivided by \(a\) for'Phi'and times \(a^2\) for'Rho'.<prop>-scale-normalized_curve:<prop>-scaledivided by its sum over the bins; for'z', folded by summing mirror bins, so it is the distribution of \(|z|\) and still sums to one.<prop>-normalizerand<prop>-norm: fromnormalize_r()or, for'z',normalize_z()with folding, so that a'z'profile hasceil(n / 2)rows.<prop>-norm-sem, when the file has it and normalizer is None: carried through from the file and, for'z', folded like every other numeric column.polyphys.analyze.pipelinewrites it as the standard error over the wholes of each whole’s profile divided by its own value in the bin the default normalizer names: the SEM across profiles normalized separately for each whole. Normalization is nonlinear, so it is not generally an uncertainty estimate for<prop>-norm, the normalized ensemble mean. With an explicit normalizer the column no longer matches<prop>-norm’s reference bin, so it is dropped with a warning.bin_center-norm:bin_centerdivided by its maximum.ensemble_long, the file’s state-point name; one column per entry of physical_attrs; crowder_attr; andphi_bulk_c_round.For each crowder of crowders with size attribute
c:bin_center-<c>, which is \(2 b / a_c\) for the bin center \(b\), the bin center in crowder radii. For'r'in a cylinder of diameter \(D\) alsobin_center-<c>-recentered, which is \(2 b / a_c - (D \bmod a_c) / a_c\), so that the wall sits at an integer number of crowder diameters and the layers of different state points overlay, andbin_center-recentered-norm(bin_center-recentered-norm-<c>with several crowders), which is \(b - (D \bmod a_c)\) divided by its maximum.
- Return type:
- Raises:
ValueError – If quantity is not
'Rho'or'Phi'; if the parser’s geometry and direction have no entry inPROFILE_NORMALIZERS, such as'z'in a cube; if no file matches; or if normalizer is none of the accepted forms.KeyError – If species or a crowder is not a key of species_sizes.
- Warns:
UserWarning – If a file’s
<prop>-meansums to one within1e-6, which marks a profile normalized by its sum; the file is processed regardless, since a raw profile can sum to one by coincidence. If a file has a<prop>-norm-semcolumn and normalizer is not None; the column is dropped. Also if a file’s reference value is zero; its<prop>-normis then zero.
Examples
One ensemble-averaged radial volume fraction of crowders of diameter
ac2.0in a cylinder, normalized by its axis value:>>> import tempfile >>> from pathlib import Path >>> from polyphys.tests.synthetic import ChainCyl >>> tmp = tempfile.TemporaryDirectory() >>> database = Path(tmp.name) / 'analysis' / 'N20-all-ensAvg' >>> database.mkdir(parents=True) >>> state = 'N20r5.5lz25.0ac2.0nc100dt0.005bdump1000adump5000' >>> pd.DataFrame({'bin_center': [0.5, 1.5, 2.5], ... 'rPhiCrd-mean': [0.2, 0.3, 0.1]}).to_csv( ... database / f'{state}-all-rPhiCrd-ensAvg.csv', index=False) >>> space = space_profiles(str(database) + '/', 'Phi', 'r', 'Crd', ... ChainCyl, 'N*', ['dcyl'], 'all', ... {'Mon': 'dmon', 'Crd': 'dcrowd'}) >>> space[['bin_center', 'rPhiCrd-scale', 'rPhiCrd-norm', ... 'bin_center-dcrowd-recentered']] bin_center rPhiCrd-scale rPhiCrd-norm bin_center-dcrowd-recentered 0 0.5 0.10 1.0 0.5 1 1.5 0.15 1.5 1.5 2 2.5 0.05 0.5 2.5 >>> space['dcyl'].tolist() [10.0, 10.0, 10.0] >>> tmp.cleanup()
Notes
Files are selected by globbing
input_database + hierarchy + '-<group>-<prop>-ensAvg.csv'and sorted alphanumerically by name.Let n_files be the number of matched files, n_bins the number of rows of each, and n_cols the number of columns of the result. Time is \(O(n_\text{files} \, n_\text{bins} \, n_\text{cols} + n_\text{files} \log n_\text{files})\); one file is in memory at a time while the finished frames accumulate, so peak memory is about twice the result, \(O(n_\text{files} \, n_\text{bins} \, n_\text{cols})\).
The default normalizers follow the research code: the value at \(r = 0\) in a cylinder, where the outermost bins are the crowder layers on the wall and no far field exists, and the maximum otherwise. The sum rule is a local relation and holds in the moderate-compaction regime to about 15 percent (Jeon et al., 2016, Section 3.1); under cylindrical confinement its radial form holds only where the wall layering is weak, which the ratio \(\kappa = (D - a_c) / a_c\) controls (Sadeghi Isfahani, 2024, Chapter 3).
<prop>-normis the normalized ensemble average, the published estimator (Jeon et al., 2016, p. 9788: a time average within each run, then over runs, then normalized by the far-field value), not the average of per-whole normalized profiles. The file’s<prop>-norm-semis the SEM across profiles normalized separately for each whole at the same bin. It is not generally an uncertainty estimate for the normalized ensemble mean.
References
C. Jeon, C. Hyeon, Y. Jung, and B.-Y. Ha, “How are molecular crowding and the spatial organization of a biopolymer interrelated”, Soft Matter 12, 9786-9796 (2016). https://doi.org/10.1039/c6sm01924b
J. Kim, C. Jeon, H. Jeong, Y. Jung, and B.-Y. Ha, “A polymer in a crowded and confined space: effects of crowder size and poly-dispersity”, Soft Matter 11, 1877-1888 (2015). https://doi.org/10.1039/c4sm02198c
A. H. Sadeghi Isfahani, PhD thesis, University of Waterloo (2024), Chapter 3.
Added in version 0.6.0.
Changed in version 0.7.0: Carry
<prop>-norm-semthrough, and warn on a profile that sums to one.
- polyphys.analyze.sumrule.space_profiles_from_spec(input_database, spec, quantity, direction, species, *, group='all', crowders=('Crd',), normalizer=None, round_to=3, save=False)[source]#
Scale and normalize the ensemble-averaged density profiles of one species across a space for the density sum rule, with the columns, the species sizes, and the rounding step the study’s spec declares.
The spec supplies every study choice of
space_profiles(): the parser, theensemble_longglob prefix (spec.hierarchy), the attributes that become columns (spec.physical_attrs), the parser attribute holding the particle diameter \(a_i\) of each species (spec.species_sizes), the rounding step \(\Delta\) of the bulk volume fraction of crowders \(\phi_c\) (spec.divisor), and the parser attribute that holds \(\phi_c\) (spec.crowder_attr). No study default is taken from the library.- Parameters:
input_database (
str|os.PathLike[str]) – TheensAvgdirectory of the space, which holds the files<ensemble_long>-<group>-<direction><quantity><species>-ensAvg.csvof the raw ensemble-averaged profiles, asspace_profiles()requires.spec (
polyphys.spec.ProjectSpec) – The study’s spec.quantity (
typing.Literal['Rho','Phi']) – The number density or the volume fraction.direction (
typing.Literal['x','y','z','r','theta']) – The coordinate of the profile;'z'exists in a cylinder only.species (
str) – The species label of the profile, such as'Mon'or'Crd'; a key of spec.species_sizes.group (
str) – The particle group of the profiles. A density profile covers every particle of its species, so it is in the'all'group, not the polymer group spec.group.crowders (
typing.Sequence[str]) – The crowder species, each a key of spec.species_sizes, as inspace_profiles().normalizer (
typing.Union[typing.Literal['first','last','max'],float,typing.Callable[[pandas.DataFrame,typing.Any],float],None]) – The reference value of the normalization, as inspace_profiles(); None takes the default ofPROFILE_NORMALIZERSfor the spec’s geometry and direction.round_to (
int) – The number of decimal places of the rounded \(\phi_c\).save (
bool) – Also write the table to<space>-<group>-<direction><quantity><species>-normalizedRescaled-space.csvin theanalysisphase’sspacedirectory next to input_database.
- Returns:
The table of
space_profiles(), with a spec.crowder_attr column andphi_bulk_c_round, that attribute rounded to a multiple of spec.divisor.- Return type:
- Raises:
ValueError – As
space_profiles()raises them.- Warns:
UserWarning – As
space_profiles()warns.
Notes
The cost is that of
space_profiles(): \(O(n_\text{files} \, n_\text{bins} \, n_\text{cols} + n_\text{files} \log n_\text{files})\) time and \(O(n_\text{files} \, n_\text{bins} \, n_\text{cols})\) memory for n_files matched files of n_bins rows and n_cols columns of the result.Examples
In a cylinder of diameter \(D = 10\) and length \(Z = 50\) with \(n_c = 100\) crowders of diameter \(a_c = 2\), \(\phi_c = 2 n_c a_c^3 / (3 Z (D - a_c)^2) = 1/6\), which the spec’s step of 0.1 rounds to 0.2:
>>> import tempfile >>> from pathlib import Path >>> from polyphys.tests.synthetic import ChainCyl >>> from polyphys.spec import ProjectSpec >>> spec = ProjectSpec( ... parser=ChainCyl, group='bug', divisor=0.1, ... crowder_attr='phi_bulk_c', physical_attrs=('dcyl',), ... species_sizes={'Mon': 'dmon', 'Crd': 'dcrowd'}, ... tseries_properties=('gyrTMon',)) >>> tmp = tempfile.TemporaryDirectory() >>> database = Path(tmp.name) / 'analysis' / 'N20-all-ensAvg' >>> database.mkdir(parents=True) >>> state = 'N20r5.5lz25.0ac2.0nc100dt0.005bdump1000adump5000' >>> pd.DataFrame({'bin_center': [0.5, 1.5, 2.5], ... 'rPhiCrd-mean': [0.2, 0.3, 0.1]}).to_csv( ... database / f'{state}-all-rPhiCrd-ensAvg.csv', index=False) >>> space = space_profiles_from_spec(database, spec, 'Phi', 'r', 'Crd') >>> space[['bin_center', 'rPhiCrd-norm', 'dcyl', 'phi_bulk_c_round']] bin_center rPhiCrd-norm dcyl phi_bulk_c_round 0 0.5 1.0 10.0 0.2 1 1.5 1.5 10.0 0.2 2 2.5 0.5 10.0 0.2 >>> tmp.cleanup()
Added in version 0.9.0.
- polyphys.analyze.sumrule.sum_rule_profiles(profiles, prop, geometry, direction, *, by=('ensemble_long',), normalizer=None)[source]#
Sum the scaled density profiles of several species, state point by state point, and normalize the sum by its own reference value: the left side of the density sum rule.
With the species’ scaled profiles \(\phi_i(x) / a_i\) from
space_profiles(), the sum \(\sum_i \phi_i(x) / a_i\) is constant in \(x\) where the sum rule holds (Jeon et al., 2016, eqn (5); eqn (7) for several crowders). Normalized by its own value at the reference, the sum is one there and its departure from one elsewhere measures the rule’s failure.The species’ profiles must descend from the raw ensemble averages, as
space_profiles()requires: the sum weights each species by its physical scale, and a species normalized on its own, by its sum, its integral, or its maximum, enters with an arbitrary weight. Nothing here can detect that, so it is the caller’s contract.- Parameters:
profiles (
typing.Mapping[str,pandas.DataFrame]) – Each species label mapped to itsspace_profiles()result for the same prop; each has the columns of by,bin_center, and<prop><species>-scale, in the same row order, with-scalebuilt from the raw ensemble-averaged profile.prop (
str) – The direction and quantity, such as'rPhi'or'zRho'.geometry (
typing.Literal['cubic','cylindrical']) – The geometry of the study, which with direction chooses the default normalizer.direction (
typing.Literal['x','y','z','r','theta']) – The coordinate of the profiles.by (
typing.Sequence[str]) – The columns that identify a state point; the sum is normalized within each. An empty sequence treats the whole input as one.normalizer (
typing.Union[typing.Literal['first','last','max'],float,typing.Callable[[pandas.DataFrame],float],None]) – The reference value of each state point’s sum. None takes the default ofSUM_NORMALIZERS: the value at \(r = 0\) for'r'in a cylinder, the far-field (last-bin) value otherwise, where the monomer term vanishes and the sum is the crowder term \(\phi_c(\infty) / a_c\). A function is called with the state point’s frame of the columns below. An explicit value is logged at INFO with the default it replaces.
- Returns:
One row per bin and state point, in the input order: the by columns,
bin_center,<prop>Sum-scale(the sum over species),<prop>Sum-normalizer(the reference value of the state point), and<prop>Sum-norm. When every species carries<prop><species>-norm-sem, also<prop>Sum-norm-sem, the species’-norm-semvalues \(s_i\) added in quadrature, \(\sqrt{\sum_i s_i^2}\), which assumes that the species’ errors are independent. Each \(s_i\) is the SEM across profiles normalized separately for each whole, not generally an uncertainty estimate for a normalized ensemble mean, so neither is the sum. It refers to the sum of the separately normalized species, \(\sum_i \phi_i / (a_i N_i)\) for each species’ own normalizer \(N_i\), and to<prop>Sum-norm, \(\sum_i \phi_i / a_i\) over the sum’s normalizer, only when every species shares one normalizer value.- Return type:
- Raises:
ValueError – If profiles is empty; if the species disagree on the by columns or on
bin_centerin any row; if a row has NaN in a by column; if (geometry, direction) has no entry inSUM_NORMALIZERS; or if normalizer is none of the accepted forms.- Warns:
UserWarning – If a state point’s reference value is zero; its
<prop>Sum-normis then zero.
Examples
Two species over three radial bins of one state point in a cube: the monomer term falls to zero where the crowder term reaches its far-field value, and the sum is one where the rule holds:
>>> keys = {'ensemble_long': ['s1'] * 3, 'bin_center': [0.5, 1.5, 2.5]} >>> monomers = pd.DataFrame({**keys, 'rPhiMon-scale': [0.8, 0.4, 0.0]}) >>> crowders = pd.DataFrame({**keys, 'rPhiCrd-scale': [0.2, 0.6, 1.0]}) >>> total = sum_rule_profiles({'Mon': monomers, 'Crd': crowders}, ... 'rPhi', 'cubic', 'r') >>> total[['bin_center', 'rPhiSum-scale', 'rPhiSum-norm']] bin_center rPhiSum-scale rPhiSum-norm 0 0.5 1.0 1.0 1 1.5 1.0 1.0 2 2.5 1.0 1.0 >>> total['rPhiSum-normalizer'].tolist() [1.0, 1.0, 1.0]
Notes
Time and space are \(O(n_\text{species} \, n_\text{rows})\) for the sum, the checks, and the error, plus \(O(n_\text{rows})\) per state point for the normalization. See
space_profiles()for the references. The species’ errors are correlated within a whole by excluded volume, which the quadrature sum ignores; the per-bin estimator is an open question.Added in version 0.6.0.
Changed in version 0.7.0: Added
<prop>Sum-norm-sem.