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_sizes names 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 r profile 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#

Dependencies#

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

PROFILE_NORMALIZERS

The default normalizer of a density profile, by (geometry, direction): 'first' for r in a cylinder, 'max' otherwise.

SUM_NORMALIZERS

The default normalizer of the species sum, by (geometry, direction): 'first' for r in a cylinder, 'last' otherwise.

Functions

normalize_r(prop, ens_avg[, normalizer])

Normalize the scaled radial profile <prop>-scale of an ensemble-averaged distribution by a reference value.

normalize_z(prop, ens_avg[, normalizer, fold])

Normalize the scaled longitudinal profile <prop>-scale of an ensemble-averaged distribution by a reference value and, by default, fold it about \(z = 0\).

space_profiles(input_database, quantity, ...)

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.

space_profiles_from_spec(input_database, ...)

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_rule_profiles(profiles, prop, geometry, ...)

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' for r in 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' for r in 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>-scale of 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>-scale divided by it.

Return type:

pandas.DataFrame

Raises:

ValueError – If normalizer is none of the accepted forms.

Warns:

UserWarning – If the reference value is zero; <prop>-norm is 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>-scale of 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_center is \(|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 a bin_center column 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 in normalize_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>-normalizer and <prop>-norm added, as in normalize_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 has ceil(n / 2) rows ordered by \(|z|\).

Return type:

pandas.DataFrame

Raises:

ValueError – If normalizer is none of the accepted forms, or fold is True and ens_avg has no bin_center column or its bin centers do not increase symmetrically about \(z = 0\), to a tolerance of 1e-9 times the largest \(|z|\).

Warns:

UserWarning – If the reference value is zero; <prop>-norm is 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 -var and -sem columns 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_curve by 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>-scale is the volume fraction divided by the species’ diameter, and for quantity='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>-scale loses its unit; only its <prop>-norm survives, since dividing by the profile’s own reference value is scale-invariant. A profile whose <prop>-mean sums to one, as one normalized by its sum does, raises a UserWarning naming 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 a bin_center column and a <direction><quantity><species>-mean column 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: the species_sizes of the study’s ProjectSpec.

  • crowders (typing.Sequence[str]) – The crowder species, each a key of species_sizes; one set of bin_center columns 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 of PROFILE_NORMALIZERS for the parser’s geometry and direction. Otherwise 'first', 'last', 'max', or a number, as in normalize_r(); or a function of two arguments, the scaled profile and the parser instance of the file, returning the value, so that lambda df, info: info.phi_bulk_c / info.dcrowd normalizes 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.csv in the analysis phase’s space directory, which make_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 into phi_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_constant repeats it.

  • <prop>-scale: <prop>-mean divided by \(a\) for 'Phi' and times \(a^2\) for 'Rho'.

  • <prop>-scale-normalized_curve: <prop>-scale divided 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>-normalizer and <prop>-norm: from normalize_r() or, for 'z', normalize_z() with folding, so that a 'z' profile has ceil(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.pipeline writes 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_center divided by its maximum.

  • ensemble_long, the file’s state-point name; one column per entry of physical_attrs; crowder_attr; and phi_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\) also bin_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, and bin_center-recentered-norm (bin_center-recentered-norm-<c> with several crowders), which is \(b - (D \bmod a_c)\) divided by its maximum.

Return type:

pandas.DataFrame

Raises:
  • ValueError – If quantity is not 'Rho' or 'Phi'; if the parser’s geometry and direction have no entry in PROFILE_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>-mean sums to one within 1e-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-sem column and normalizer is not None; the column is dropped. Also if a file’s reference value is zero; its <prop>-norm is then zero.

Examples

One ensemble-averaged radial volume fraction of crowders of diameter ac2.0 in 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>-norm is 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-sem is 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-sem through, 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, the ensemble_long glob 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]) – The ensAvg directory of the space, which holds the files <ensemble_long>-<group>-<direction><quantity><species>-ensAvg.csv of the raw ensemble-averaged profiles, as space_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 in space_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 in space_profiles(); None takes the default of PROFILE_NORMALIZERS for 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.csv in the analysis phase’s space directory next to input_database.

Returns:

The table of space_profiles(), with a spec.crowder_attr column and phi_bulk_c_round, that attribute rounded to a multiple of spec.divisor.

Return type:

pandas.DataFrame

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 its space_profiles() result for the same prop; each has the columns of by, bin_center, and <prop><species>-scale, in the same row order, with -scale built 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 of SUM_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-sem values \(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:

pandas.DataFrame

Raises:

ValueError – If profiles is empty; if the species disagree on the by columns or on bin_center in any row; if a row has NaN in a by column; if (geometry, direction) has no entry in SUM_NORMALIZERS; or if normalizer is none of the accepted forms.

Warns:

UserWarning – If a state point’s reference value is zero; its <prop>Sum-norm is 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.