Skip to content

Count outcomes in bcf() via Pólya-Gamma augmentation - #10

Merged
dwachsmuth merged 5 commits into
cma-zinbfrom
cma-bcf-count
Nov 8, 2026
Merged

dwachsmuth merged 5 commits into
cma-zinbfrom
cma-bcf-count

Conversation

@dwachsmuth

Copy link
Copy Markdown

Stacked on #9 (cma-zinb, ZINB BART), which is stacked on #8 (cma-nb). Adds count outcomes to bcf(): plain negative binomial and zero-inflated negative binomial (ZINB). This covers the BCF part of nash_experiments/docs/nashtree-zinb/feasibility-20261108.md §1.

Model

general_params = list(outcome_model = OutcomeModel("count", "log", family = "negbin" | "zinb")).

  • Count part. y_i ~ NB(mu_i, r) with log mu_i = o_i + c + mu_c(x_i, pi_hat_i) + [tau_0 + tau_c(x_i)] b(z_i) [+ rfx].
    • b(z) is the treatment basis: z, or the adaptive coding b_0 (1 - z) + b_1 z.
    • tau_0 + tau_c(x) is a log rate ratio, per unit of dose for a continuous treatment.
    • c is the fixed centering constant, as in the NB / ZINB BART.
    • New arguments offset_train / offset_test take the log exposure o.
  • Zero part (zinb). pi_i = Phi(c0 + mu_z(x_i, pi_hat_i) + tau_z(x_i) z_i). That makes four forests in all.
    • The zero prognostic forest has 50 trees by default and the zero treatment forest 25, on the raw z. Both use probit calibrations with the leaf scale held fixed: 2 / m for the prognostic forest, the probit-BCF delta_max formula with delta_max = 0.5 for the treatment forest.
    • They are configured through the new arguments zero_prognostic_forest_params and zero_treatment_effect_forest_params.
    • They use the count forests' variable weights, propensity column included.

Gibbs scheme

Each iteration runs the following steps.

  1. ZINB only: the structural-zero step shared with Zero-inflated negative-binomial BART outcome #9, then the probit zero prognostic and zero treatment forests, sampled on s.
  2. Pólya-Gamma step. Draw omega_i ~ PG(y_i + r, psi_i). Then:
    • resid_train gets the pseudo-outcome (y - r) / (2 omega) + log r - o, the role the latent z plays for probit.
    • The forest and rfx datasets get variance weights 1 / omega. Under ZINB, structural zeros get Inf.
    • The residual is the pseudo-outcome net of c + mu + [tau_0 + tau(x)] b(z) + rfx.
  3. Unchanged samplers. The prognostic forest, the treatment basis-regression forest (binary or continuous dose), propensity covariate, rfx, GFR and multi-chain resets all run on this weighted Gaussian regression as they are, with the error variance fixed at 1.
  4. Weighted tau_0 and adaptive coding. These are sampled in R from unweighted sums in the existing code. The count path recomputes them with the precision weights omega (0 for structural zeros); the Gaussian and probit code paths are untouched.
  5. Dispersion r. Slice step over the non-structural rows.

Refused with counts: variance forest, sample_sigma2_global = TRUE, a multivariate treatment with zinb, observation_weights with zinb. With negbin, observation_weights multiply the variance weights.

Prior calibration

  • Prognostic leaf scale: as in NB BART, (range(log1p y) / (4 sqrt(m)))^2.
  • Treatment forest: set on the log-rate-ratio scale by the new treatment_effect_forest_params$log_rate_ratio_prior_sd (default 0.5). sigma2_leaf = sd^2 / num_trees, so one prior sd of tau(x) is a rate ratio of 0.61 to 1.65.
  • tau_0: N(0, 1) by default.

API

  • predict.bcfmodel()
    • New offset argument.
    • Scales:
      • "linear": y_hat = log mu, mu/prognostic_function are log baseline rates, tau/cate are log rate ratios.
      • "rate": every term exponentiated: rates, rate ratios, multiplicative rfx.
      • "response": like "rate", except y_hat = (1 - pi) mu.
      • "zero_probability": y_hat = pi plus the zero-part terms.
    • New terms zero_prognostic, zero_tau and zero_forest. These are probit indices on "linear"; on the other scales zero_prognostic and zero_forest are probabilities and zero_tau stays a probit-scale coefficient.
  • computeContrastBCFModel() takes offset_0 / offset_1 and the four count scales. The linear contrast equals the CATE (tested).
  • sampleBCFPosteriorPredictive() draws NB counts with the matched r draw, then zeroes each draw with probability pi.
  • JSON (object, string, file, combined, combined string) carries the family, offset flag, dispersion draws and priors, log_rate_ratio_prior_sd, and the zero forests (forest_2, forest_3).
  • Warm start checks that the family and the zero-forest sizes match.
  • Other outputs: print, summary and extractParameter report counts. New outputs negbin_dispersion_samples, zero_mu_hat_*, zero_tau_hat_* and zero_hat_*.

Recovery

tests/testthat/test-bcf-count.R. Simulated data: n = 3,000, r = 3, offset.

  • Confounded binary treatment: pi(x) = 0.15 + 0.7 plogis(3 (x1 - 0.5)), and x1 also drives the prognostic part.
  • Count part: tau_c(x) = 0.3 + 0.4 x2, mean log rate ratio ≈ 0.50.
  • Zero part (ZINB): tau_z = -0.5 on the probit scale, 29–32% zeros.

Calibration used 8 data sets per family (16 fits, about 16–17 s each):

NB ZINB
max error, average log rate ratio 0.055 0.060
naive (exposure-adjusted, confounded) log rate ratio 0.68–0.77 0.77–0.88
truth inside 95% interval of average-CATE draws 7/8 8/8
max CATE RMSE 0.098 0.104
min CATE correlation (tau_c sd 0.115) 0.74 0.46
min rate correlation 0.985 0.980
r inside 99% interval 8/8 8/8
tau_z: max error / 95% coverage – 0.063 / 8 of 8
effect on pi, mean pi(x,1) - pi(x,0) (truth −0.147): max error / coverage – 0.020 / 8 of 8
pi correlation (min) / RMSE (max) – 0.816 / 0.066

The NB coverage miss is seed 2002: interval 0.504–0.618 against a truth of 0.503.

Test thresholds, applied to the first seed of each family:

  • |ATE error| < 0.1, plus the 95% interval;
  • CATE RMSE < 0.13 and CATE correlation > 0.4;
  • rate correlation > 0.97;
  • r inside its 99% interval;
  • ZINB: |tau_z error| < 0.15 plus its 95% interval, effect on pi error < 0.04, pi correlation > 0.78, pi RMSE < 0.08.

Timing

n = 5,000, default forests (250 prognostic + 100 treatment trees), 100 MCMC iterations from root, median of 3 runs, single thread, ms per iteration:

path ms / iter
Gaussian BCF 30.4
NB BCF 63.9
ZINB BCF (50 + 25 zero trees) 68.1

Tests

Full suite, NOT_CRAN=true:

expectations failed skipped tests
before (cma-zinb, after #9) 1687 0 2
after 1854 0 2

Every pre-existing file has an identical count; test-bcf-count.R adds 167 expectations. In test-negbin.R and test-zinb.R, the one expectation that bcf() refuses counts now checks that it refuses a variance forest with counts.

Bitwise check. fixtures/bcf-reference.rds was captured from the build before bcf.R was edited (make-bcf-reference.R), and current draws match it bitwise. It covers:

  • Gaussian BCF with an intercept_plus_treatment rfx, 2 chains, GFR and test set, plus prediction and contrast;
  • Gaussian adaptive coding from root, plus the posterior predictive;
  • Gaussian continuous dose with observation weights;
  • probit BCF with rfx, 2 chains, plus probability predictions.

The #8 and #9 references still pass.

Other coverage: predict scales and terms, contrasts, the posterior predictive mean and zero mass, the 5 JSON round trips, multiple chains (GFR and root), combined JSON, warm starts, continuous dose, adaptive coding with unit and non-unit weights, and validation.

Found and left unchanged

These are pre-existing, upstream code. They are also written up in NASH-FORK.md.

  • Probit BCF and tau_0. With sample_intercept = TRUE (the default), tau_0 b(z) is left out of both the truncated-normal mean and the residual handed to the forests in the latent step. The count path includes it. Fixing probit would change its draws, so it is out of scope here.
  • Treatment leaf-scale update in the GFR loop. It calls forest_model_config_mu$update_leaf_model_scale(current_leaf_scale_mu), i.e. the prognostic config with the prognostic scale. The MCMC loop is correct.
  • Gaussian tau_0 and adaptive coding ignore observation_weights.

Not verified

  • Bitwise references exist for aarch64-apple-darwin23 only.
  • No comparison against bartisan (GPL; not read or run).
  • No R-hat or ESS study. CATE heterogeneity recovery is weak for the zero-inflated family (min correlation 0.46) at this signal size.
  • Recovery was calibrated only for a binary treatment without rfx. The following run through the same code and have shape, finiteness and round-trip tests but no recovery study:
    • continuous dose;
    • intercept_plus_treatment and custom rfx bases;
    • adaptive coding;
    • an internally estimated propensity;
    • multivariate treatment with negbin.
  • The tau_z prior default (delta_max = 0.5) and log_rate_ratio_prior_sd = 0.5 are reasoned defaults, not tuned.
  • num_threads > 1 is untested.
  • The Python package is untouched.

No GPL sources were read or copied. Everything was installed into a scratch library only.

🤖 Generated with Claude Code

dwachsmuth and others added 5 commits November 8, 2026 15:07
…counts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Polya-Gamma step turns the count part into the weighted Gaussian
regression bcf() already fits: prognostic forest, basis-regression
treatment forest (binary or continuous dose), propensity covariate,
adaptive coding, tau_0, random effects, GFR and multiple chains run on the
pseudo-outcome with variance weights 1 / omega. tau_0 and the coding
parameters, sampled in R, use the precision weights; tau_c is a log rate
ratio with a prior set by log_rate_ratio_prior_sd (default 0.5).
family = 'zinb' adds probit zero-part prognostic and treatment forests on
the structural-zero indicators, sharing the step of bart(). Variance
forests and a sampled global variance are refused.

predict.bcfmodel() gains the rate, response and zero_probability scales,
the zero-part terms and an offset; computeContrastBCFModel() and
sampleBCFPosteriorPredictive() handle counts; JSON carries the family,
dispersion draws and zero-part forests. Gaussian and probit draws are
bitwise unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recovery of a log rate ratio under confounded assignment (NB and ZINB) and
of the zero-part effect, with thresholds calibrated over 16 fits; Gaussian
and probit BCF draws bitwise against a reference; predict scales and terms,
contrasts, posterior predictive, JSON round trips, multiple chains, warm
starts, continuous dose, adaptive coding, weights and validation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dwachsmuth
dwachsmuth added this pull request to stack #11 November 8, 2026 23:14
@dwachsmuth
dwachsmuth marked this pull request as ready for review November 8, 2026 23:14
@dwachsmuth
dwachsmuth merged commit 84f5ccb into cma-rfx Nov 8, 2026
2 checks passed
@dwachsmuth
dwachsmuth deleted the cma-bcf-count branch November 8, 2026 23:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant