[nasserboan]

Type

• Bug fix
• Feature
• Docs
• Breaking change

Related issue

None

What changed

BGNBD and MBGNBD gain parameter_uncertainty(n=200, seed=None, confidence=0.95): a parametric bootstrap that simulates n synthetic customer
bases from the fitted parameters, refits the model on each, and returns a
ParameterUncertainty result (one row per parameter with estimate, se,
ci_low, ci_high; to_pandas/to_json/plot). The MLE point estimates
carried no error bars, so a parameter the data pins down looked exactly like
one it barely constrains — on CDNOW calibration r sits in [0.219, 0.269]
while a spans [0.518, 1.184] and b [1.532, 3.934]. That weak identification
of the dropout pair is the honest result the method exists to surface.

The engine is model-agnostic (clv/_bootstrap.py); each model contributes its
own generative simulator, kept separate the way the two likelihoods are. The
MBG/NBD simulator adds the time-zero dropout branch. The small-cohort display
note now points at the method, ParameterUncertainty is exported from
clvkit.clv, and the user guide, API pages and the CDNOW notebook document it
(the notebook cell runs n=100, seed=42, about 30 s). Opt-in: nothing runs
unless called, no dependency added, no existing behaviour changes.

The test workflow also splits into four parallel jobs (code-quality, test,
dask, notebooks) so a failure names its own axis in the checks list.

How it was tested

28 new tests across tests/test_bgnbd_bootstrap.py and
tests/test_mbgnbd_bootstrap.py: the result contract, determinism (same
(n, seed) gives an identical frame), simulator↔likelihood agreement (a base
simulated at large N from known parameters refits to recover r/alpha and
a/(a+b) within tolerance, time-zero dropouts included), interval coverage of
the well-identified parameters, and the relative-width assertion that a/b
come back wider than r. Full suite: 292 passed, 1 skipped. The CDNOW golden
tests still reproduce the published estimates to the last printed digit.

Checks

• uv run pytest
• uv run ruff check
• uv run ruff format --check
• Notebooks still execute (uv run pytest --nbmake examples/)
• Docs updated
• Title reads as the commit message it will become