pytyche.bcf.hurdle

Public fit entry point for hurdle BCF.

The canonical public surface is fit_hurdle_bcf, which accepts an ObservedExperimentData and dispatches to the appropriate private raw-array core based on the pooling argument.

Private cores (raw-array, no observed stashing):

  • _fit_joint_hurdle_bcf — joint shared-tree MCMC (model.py)

  • _fit_independent_hurdle_bcf — two-stage binary+continuous (compose.py)

Functions

fit_hurdle_bcf(observed, *[, pooling, ...])

Fit hurdle BCF on observed experiment data.
pytyche.bcf.hurdle.fit_hurdle_bcf(observed, *, pooling='joint', observed_copy='view', calibration=None, seed=0, progress=False, **kwargs)[source]

Fit hurdle BCF on observed experiment data.

Dispatches to the joint shared-tree MCMC (pooling='joint') or the independent two-stage estimator (pooling='independent') based on the pooling argument. All MCMC configuration is forwarded through **kwargs to GPUBCFConfig.

Parameters:

  • observed (ObservedExperimentData) – Observed experiment data. Must have at least two variants.

  • pooling (Literal['joint', 'independent']) – 'joint' (default) — shared-tree MCMC estimator (canonical); 'independent' — two-stage binary + continuous estimator.

  • observed_copy (Literal['view', 'deep', 'ref']) – Copy mode for stashing the observed data on the result. 'view' (default) — zero-copy read-only view; 'deep' — independent deep copy; 'ref' — identity (no copy).

  • calibration (Calibration | None) – Optional SBC-fitted artifact applied post-fit — sugar for .apply_calibration(calibration) on the returned result (one application path; the kwarg adds no numerics). None (default) returns the raw posterior.

  • seed (int) – Random seed forwarded to GPUBCFConfig as random_seed.

  • progress (bool) – When True, the joint fit renders tqdm progress bars on stderr (GFR warm-start sweeps, MCMC chunks). The default False is fully silent. pooling='independent' accepts the flag but has no per-phase reporting hooks — its channel fits run inside JIT-compiled loops.

  • **kwargs – Additional keyword arguments forwarded to GPUBCFConfig. Unknown keys raise TypeError (frozen dataclass with no extra fields).

Return type:

HurdleBCFResult

Returns:

HurdleBCFResult with pooling and observed set to the stashed snapshot; calibrated iff calibration was supplied.

Raises:

  • ValueError – If pooling is not 'joint' or 'independent', if any variant contributes zero rows (missing treatment level), or — propagated from apply_calibration — if a supplied calibration’s fitted regime (metric, n_treatments, pooling) does not match this fit.

  • NotImplementedError – If pooling='independent' and K >= 3 (use pooling='joint' for multi-arm experiments).

  • TypeError – If **kwargs contains unknown GPUBCFConfig field names.

Modules

compose

Composed (independent) hurdle BCF: public API and CATE composition helpers.

model

Joint shared-tree hurdle BCF model: public API and single-chain step.

orchestration

Hurdle BCF chunk machinery and PPC summary.

proposals

Hurdle BCF grow/prune proposals and forest initialisation.

step

Hurdle BCF forest-level backfitting sweep (3-stage pattern).