Scientific randomness from a declared protocol, with verifiable arrays and execution receipts.
Chances unifies distributions, resampling, allocation, and point designs through one seeded protocol. Declare the scientific decision, inspect it before drawing, and retain the result with the evidence needed to verify and repeat it.
Chances owns generation, validation, archival integrity, and conditional exact replay. Researchers own the choice of distribution, resampling unit, experimental design, and interpretation. Chances does not infer those decisions or certify scientific suitability. It is not a cryptographic random generator or a physical entropy service. Core execution requires a seed, uses local generators, and leaves Python and NumPy global random state unchanged.
The catalog covers 19 operations and 132 distribution families.
| Research task | Supported capability |
|---|---|
| Draw from a scientific model | Univariate and multivariate distributions, empirical samples, and mixtures |
| Resample observations | Whole-row selection, permutations, bootstrap, and stratified splits |
| Plan a study or simulation | Balanced allocation, antithetic pairs, and randomized or quasi Monte Carlo designs |
| Keep computations isolated | Explicit seeds and named streams with isolated generators |
| Audit and repeat a result | Validation before drawing, checked arrays, saved receipts, verification, and conditional exact replay |
Use the operation catalog to select a family, its parameters, and its preconditions.
This README describes the 2.0 API in this repository. Historical 0.1 releases on PyPI use a different interface. Start from the current source checkout:
git clone https://github.com/autonomio/chances.git
cd chances
python -m pip install .Use Python 3.10 or later. Installation supplies NumPy and SciPy; no optional runtime extras are required. Choose a new output directory for the example; existing destinations are rejected.
from pathlib import Path
import numpy as np
import chances
spec = {
"version": 1,
"operation": "normal",
"parameters": {"size": 100, "loc": 0.0, "scale": 1.0},
"randomness": {"seed": 42, "stream": "experiment/replicate-1"},
}
profile = chances.inspect(spec)
first = chances.generate(spec)
second = chances.generate(spec)
assert profile["output"]["shape"] == [100]
assert first.data.shape == (100,)
assert np.array_equal(first.data, second.data)
assert first.receipt == second.receipt
bundle = Path("first-batch")
first.write(bundle)
checked = chances.verify(bundle)
repeated = chances.replay(bundle)
assert np.array_equal(first.data, checked.data)
assert np.array_equal(first.data, repeated.data)
assert first.receipt == checked.receipt == repeated.receipt
assert {path.name for path in bundle.iterdir()} == {
"data.npy", "recipe.json", "receipt.json"
}
print(first.data.shape)
print(bundle.resolve())Expected result: (100,) and the absolute path of the retained first-batch
directory. The array and receipt match across generation, verification, and
replay in this environment. The example keeps those files for inspection.
inspect validates and describes without drawing randomness. generate returns
data, a NumPy array, and receipt, JSON evidence. A stream name identifies one
computation; declare different names for distinct replicates. See the
specification contract for defaults and stream semantics.
| File | Retained evidence |
|---|---|
data.npy |
Generated array |
recipe.json |
Resolved scientific protocol |
receipt.json |
Source, stream, engine state, implementation, environment, output identity, and mathematical checks |
source.npy, when supplied |
Input observations in their declared order |
The same bundle can be inspected from a shell or an agent through JSON commands:
python -m chances inspect first-batch/recipe.json
python -m chances verify first-batch
python -m chances replay first-batchThe reproducible batch guide covers the full archival workflow; the command-line reference defines arguments, JSON output, and structured failures.
Exact replay requires the recorded compatibility envelope. It does not promise equality across package versions, platforms, or changed chunk sizes. Unsigned receipts establish integrity relative to retained evidence; they do not establish authorship, independent samples, or the suitability of a statistical model. The receipt reference defines these boundaries and recovery from changed or incompatible evidence.
| Job | Start here |
|---|---|
| Save, verify, and repeat a computation | Reproducible batch |
| Resample aligned observations or partition strata | Resampling |
| Retain point designs or treatment allocations | Experimental design |
| Select a distribution and its parameters | Operation catalog |
| Integrate Python or an agent | Python API |
| Run JSON commands | Command line |
| Replace a historical method | Migration |
| Navigate the whole manual | Documentation hub |
Installed agents start at Path(chances.__file__).parent / "AGENTS.md";
the installed manual and catalogs live beside it under docs/.
Structured ChancesError fields support recovery without substituting a method.
Start with CONTRIBUTING.md and developer setup and validation. Propose work through Autonomio Chances issues.
Use SUPPORT.md for bug reports, feature requests, and usage questions. Include a minimal protocol, Chances and Python versions, operating system, and the structured error. Use a small shareable fixture when a report needs source data.
Report suspected vulnerabilities privately through GitHub Security Advisories. Use SECURITY.md for supported versions, response policy, and artifact verification. Do not report vulnerabilities through public issues.
Use CITATION.cff for software citation metadata. A reproducible research citation should identify Chances, its version, and the retained protocol and receipt. No DOI is supplied.