pytyche.bcf.binary

Phase 2 — independent binary/probit BCF (Albert-Chib data augmentation).

Two-forest Bayesian Causal Forest for binary outcomes, executed on GPU via bartz’s JAX BART sampler with Albert-Chib probit data augmentation. Maintains a prognostic forest (mu) and a treatment-effect forest (tau) updated by interleaved backfitting sweeps, with the latent z resampled from a one-sided truncated normal conditional on the binary observation after each mu/tau sweep.

The MCMC loop is compiled as a single XLA program via lax.scan — no Python dispatch between iterations. Error variance is fixed at 1 (probit unit-variance identification); the only stochastic update beyond the trees is the latent-z step.

Public API

fit_binary_bcf — observed-based entry point returning BinaryBCFResult.

Internal helpers

_fit_binary_bcf — raw-array private core (called by the public

wrapper and by internal callers such as pytyche.bcf.hurdle.compose).

_init_mu_forest_binary — initialize prognostic forest state on float32

latent z (bartz disallows error_scale on bool y, so we drive z ourselves).

_init_tau_forest_binary — initialize treatment-effect forest with

compensating leaf_prior_cov_inv (4×) since we skip the basis-weighted error_scale on the binary path.

_run_binary_bcf_loop — host-side wrapper that prepares inputs and

dispatches to the JIT’d scan.

_binary_bcf_scan — JIT’d two-forest MCMC with embedded

Albert-Chib z-update via truncated_normal_onesided.

Import graph

pytyche.bcf.binary imports configuration types from pytyche.bcf.config and the shared preprocessing helpers _compute_basis / _preprocess_covariates from pytyche.bcf.preprocess. After the preprocess extraction at Stage C, the lazy-import dance is gone: helpers are imported at module top with no circular dependency.

Functions

fit_binary_bcf(observed, *[, observed_copy, ...])

Fit binary BCF (Albert-Chib probit) on observed experiment data.
pytyche.bcf.binary.fit_binary_bcf(observed, *, observed_copy='view', calibration=None, seed=0, **kwargs)[source]

Fit binary BCF (Albert-Chib probit) on observed experiment data.

Accepts an ObservedExperimentData and dispatches to the private raw-array core _fit_binary_bcf.

Parameters:

  • observed (ObservedExperimentData) – Observed experiment data. Must have a binary outcome column (metric 'conversion_rate'); all outcome values must be in {0, 1} after float cast.

  • 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.

  • **kwargs – Additional keyword arguments forwarded to GPUBCFConfig.

Return type:

BinaryBCFResult

Returns:

BinaryBCFResult with observed set to the stashed snapshot; calibrated iff calibration was supplied.

Raises:

  • ValueError – If any variant contributes zero rows (missing treatment level), if the extracted outcome contains values outside {0, 1}, or — propagated from apply_calibration — if a supplied calibration’s fitted regime does not match the observed data.

  • NotImplementedError – If K >= 3 (use fit_hurdle_bcf for multi-arm).

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