flux-stats
The statistics of FLUX, as a package of their own. Every statistic the fidelity check of the FLUX Simulation Engine (flux-sim-engine) compares has one definition here. A profiler that runs where the data lives imports this package to form the same numbers, without installing the engine.
It holds these modules:
flux_stats.registryandflux_stats.definitions: one definition per statistic (mean/1,marginalHistogram/1,levelHistogram/1,support/1,correlation/1andquantile/1). Each definition names the quantities it keeps, how it forms them from values on the grid, how they are spelled and how two of them compare.flux_stats.column_metrics: the seven column metrics a profile carries.flux_stats.spelling: the exact decimal and rational spellings those documents use for numbers.flux_stats.reading: how the fidelity check reads a record, so that a profiler reads it the same way. A number becomes the exact rational it spells, an RFC 3339 instant integer milliseconds, a category its NFC string. It applies each column's null policy, forms the groups, and refuses withFLX-5005,FLX-5022orFLX-5031what it cannot read.flux_stats.profile: the reader of the profile document (PROFILE-SPEC). It reads a profile whole, or refuses it withFLX-5036.flux_stats.fixedpoint: the fixed-point grid every statistic is formed and compared on. Every comparison is an exact integer inequality (KERNEL-SPEC §12).flux_stats.tails: exact decisions about binomial tails, such as whether an empty cell or a count is too unlikely under a share, decided from directed-rounding bounds and, where those cannot tell, the exactFraction.flux_stats.sampling: estimates from a sample of whole blocks of records, the one-stage cluster ratio estimator with a 95 % interval, every number exact and every bound widened, never narrowed.flux_stats.integers: a test for a count, an ordinal or a size: anint, never abool, and not below a floor.flux_stats.errors: theFLX-nnnncode catalog its refusals are numbered in (KERNEL-SPEC §13).
The package depends on the Python standard library alone and runs on Python 3.10 or newer. It reads no clock, draws no randomness and opens no connection. Its tests import it in a fresh interpreter and check that nothing else loads.
Install
pip install flux-stats
It has no dependencies. Releases start with the first flux-sim-engine release that depends on flux-stats; the 0.0.1 on PyPI only reserves the name and holds no code. Before that release, install it from a checkout of this repository with pip install ./packages/flux-stats.
Use
Form a statistic over values already on the grid, and compare two of them under a declared tolerance:
>>> from flux_stats import Check, Parameters, definition_for_kind
>>> mean = definition_for_kind("mean")
>>> mean.identifier
'mean/1'
>>> reference = mean.measure("", [20, 20], Parameters())
>>> synthetic = mean.measure("", [21, 21], Parameters())
>>> (reference.k, reference.sum_x, synthetic.sum_x)
(2, 40, 42)
>>> mean.compare(synthetic, reference, Check(subject="p0", tolerance="absolute", margin_units=1))
True
Read a profile document, from the root of this repository:
>>> from pathlib import Path
>>> from flux_stats.profile import load_profile_text
>>> text = Path("docs/spec/profile-example.json").read_text(encoding="utf-8")
>>> profile, document = load_profile_text(text)
>>> sorted(profile.tables)
['payment', 'subscriber']
>>> profile.tables["subscriber"].row_count
1200
Read values the way the fidelity check reads them:
>>> from flux_stats.reading import exact, nfc, parse_rfc3339_ms
>>> exact("1.25", "column 'amount' row 0")
Fraction(5, 4)
>>> parse_rfc3339_ms("2024-02-29T12:00:00Z")
1709208000000
>>> nfc("e\u0301") == "\u00e9"
True
tests/test_readme.py runs all three blocks.
Known limits
Two limits of the record reader remain (ADR 0009, amendment of 2026-11-17):
nfcuses the running Python's Unicode database, so a string holding a character newer than one Python knows can be normalised differently on two Pythons.- A number is read when it needs at most 1000 digits written out, a leading
0.not counted (digits_written_out), the bound a fidelity block's numbers have. A profile document's plain decimal counts that0too (the pattern inprofile-1.schema.json, whichflux_stats.spellingapplies), so a value at the very edge, such as1E-1000, is read but cannot be published as a minimum or a maximum, and a sum of values near the bound can need more digits than a document allows. Either way the document is refused whole and nothing is written. The length of the text a cell arrives as is the caller's to bound: reading a cell costs time and memory in proportion to it.
Versions
flux-stats is released with flux-sim-engine, from the same tag and at the same version, and the engine depends on exactly that version. A profile formed with one release is read and compared by the same definitions in the engine of that release.
Development
The package lives in the flux-engine repository, as a member of its uv workspace. From the repository root, make test-stats-alone builds this package, installs the wheel into a clean environment that has no flux-sim-engine, and runs packages/flux-stats/tests there. The engine's own test run collects the same tests.
License
Metadata
Release files for flux-stats 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| flux_stats-0.6.0.tar.gz | 102.1 kB | With provenance | Details for flux_stats-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| flux_stats-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for flux_stats-0.6.0-py3-none-any.whl |
Total release size: 167.3 kB
Release files / flux_stats-0.6.0.tar.gz
| Download URL | flux_stats-0.6.0.tar.gz |
|---|---|
| Size | 102.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3ef90b5d8afe45f1e39efae1f7669aa1ef851371cc783746f7453f93e367935e
|
|
BLAKE2b-256 checksum How to use checksums |
64df99b1726fe70c288432281e23d6a6d09829b9b781843afa02e3eee4fbe58d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / flux_stats-0.6.0-py3-none-any.whl
| Download URL | flux_stats-0.6.0-py3-none-any.whl |
|---|---|
| Size | 65.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ca86db7be090e0e221d60c056e69a36301e24921ddebc406a7654e1b58b76019
|
|
BLAKE2b-256 checksum How to use checksums |
7f27072cb549ad0f7a36cc827a59691d145727ae15eb8448405e21510540b7b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for flux-stats 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for flux_stats-0.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.