pffr: bias-aware pointwise intervals (coef bias_ref, pffr_predict_ci) by fabian-s · Pull Request #132 · refunders/refund

fabian-s · 2026-09-28T15:54:17Z

Adds bias-aware pointwise confidence intervals for pffr fits, the interval recipe evaluated in the pffr dependence study (NCV fit, exact CL2 sandwich, plus the NCV–REML difference as a bias allowance).

For a linear estimand L the interval is

L θ̂_NCV ± z · sqrt(se²_CL2 + δ²),   δ = L (θ̂_NCV − θ̂_REML),

on the link scale; response-scale intervals transform the endpoints. δ cannot see bias that both fits share.

API

The user passes both fits; refund never refits silently.

coef(fit_ncv, bias_ref = fit_reml): every coefficient table gets a delta column, and pointwise intervals (crit = "z") use z·sqrt(se² + δ²).
pffr_predict_ci(fit_ncv, newdata, bias_ref = fit_reml, type = "link" | "response"): pointwise intervals for the linear predictor or the conditional mean.
With bias_ref, both default to sandwich = "cl2", cl2_adjustment = "exact" (Bayesian form). Explicit arguments are respected, and nothing changes without bias_ref.
The reference fit must be the same model (coefficient layout, model frame, weights, offsets, bases, family/link), otherwise an error is raised. Multi-predictor families, raw = TRUE, simultaneous bands and crit != "z" are rejected when bias_ref is given.
seWithMean = TRUE (the default) is the recommended setting. It only affects terms with a centring constraint (in pffr, the functional intercept). In a paired comparison on the study's cells it gave clearly better intercept coverage and interval scores than FALSE.
Docs show how to get the full intercept α(t) with its interval (Intercept(yindex) from coef() is mean-centred).

Checks

The intervals reproduce the study's own computation to 2.8e-13 on Gaussian, Poisson and binomial cells (β, γ, test-cohort mean).
New test-pffr-bias-aware.R: 10 tests, 104 expectations, 0 failures.
Unrelated test fixes:
- test-pffr-ncv.R no longer assumes mgcv's NCV Vc is smaller than Vp; that only held under an mgcv bug. It passes with patched and unpatched mgcv 1.9-5.
- test-pffr-ar.R used a nonexistent utils::package_version.
R/pffr-bias-aware.R is added to Collate.
The full test suite and R CMD check are running separately; the results will be posted here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JtmaCapnpxpQhDG2q2CQny

coef.pffr() gains `bias_ref`: given a second fit of the same model and data (typically REML for an NCV fit), each coefficient table gets a `delta` column (estimate difference through the same linear map as the SE) and pointwise z intervals use sqrt(se^2 + delta^2). New exported pffr_predict_ci() gives pointwise intervals for the linear predictor or conditional mean at fitted points or newdata, with sandwich/freq/cluster choices as in coef.pffr() and optional bias_ref; response-scale intervals transform the link-scale endpoints. The reference fit is checked for identical coefficient layout, model frame, weights, offsets, smooth bases, ffpc/pcre metadata, family and link. Tests reproduce the pffr-ci restart study's interval (NCV estimate, exact Bayesian CL2 SE, NCV-REML difference) for Gaussian and Poisson fits, delta = 0 for a fit as its own reference, seWithMean, missing dense and sparse responses, covariance passthrough, and rejections. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JtmaCapnpxpQhDG2q2CQny

…st fixes - With `bias_ref`, coef.pffr() and pffr_predict_ci() default to the covariance the interval was evaluated with: sandwich = NULL -> "cl2", cl2_adjustment = NULL -> "exact" (Bayesian form via freq = FALSE). Explicit choices are respected; without bias_ref nothing changes. - Document the full functional intercept alpha(t): Intercept(yindex) is centred and the level sits in "(Intercept)"; pffr_predict_ci() at covariate values where all other terms vanish gives alpha(t) with its bias-aware interval (exact intercept rows; tested and in the example). - Document seWithMean for the bias-aware path: keep the default TRUE. It acts only on constrained terms (the intercept; ff() and varying coefficients are unconstrained by-variable smooths). In the pffr-ci study cells TRUE matched the exact full-intercept rows, FALSE undercovered alpha by 7-15 pp. - Add pffr-bias-aware.R to Collate (it was missing, so an installed build lacked pffr_predict_ci()). - test-pffr-ncv: the NCV covariance test no longer asserts mgcv's buggy Vc < Vp; it checks Vc != Vp and that refund returns Vp, under both unpatched and patched mgcv 1.9-5. - test-pffr-ar: the mgcv 1.9-5 skip helper called the nonexistent utils::package_version(); use base package_version(). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JtmaCapnpxpQhDG2q2CQny

Copilot

Copilot review overview

🟡 Changes recommended

Two moderate unresolved findings affect missing-response alignment and multi-predictor validation.

Review effort: Lite
Findings: 1

Open (1)

Reject bias_ref for multi-linear-predictor families · New

What changed in this PR

Adds bias-aware pointwise confidence intervals for pffr coefficients and predictions using an NCV–REML reference contrast.

Changes:

Adds bias_ref support to coef.pffr().
Adds exported pffr_predict_ci().
Adds validation, covariance defaults, documentation, and tests.
Updates related NCV and version-check tests.

File	Summary
`tests/testthat/test-pffr-ncv.R`	Updates NCV covariance expectations.
`tests/testthat/test-pffr-bias-aware.R`	Adds bias-aware interval coverage.
`tests/testthat/test-pffr-ar.R`	Fixes package-version checking.
`R/pffr-methods.R`	Integrates bias-aware coefficient intervals. Moderate finding (2 votes): missing multi-linear-predictor validation.
`R/pffr-bias-aware.R`	Implements bias-aware calculations and prediction intervals. Moderate finding (1 vote): duplicate removal of missing-response rows.
`NEWS.md`	Documents the new functionality.
`NAMESPACE`	Exports `pffr_predict_ci()`.
`man/pffr_predict_ci.Rd`	Documents prediction intervals.
`man/pffr_bias_ref_difference.Rd`	Documents reference-fit validation.
`man/pffr_bias_aware_se.Rd`	Documents interval-width calculation.
`man/pffr_bias_aware_cov_defaults.Rd`	Documents covariance defaults.
`man/compute_coef_delta.Rd`	Documents coefficient-difference evaluation.
`man/coef.pffr.Rd`	Documents `bias_ref` support.
`man/coef_get_predictions.Rd`	Documents the extended helper interface.
`DESCRIPTION`	Adds the new source file to collation.

Files not reviewed (7)

man/coef.pffr.Rd: Generated file
man/coef_get_predictions.Rd: Generated file
man/compute_coef_delta.Rd: Generated file
man/pffr_bias_aware_cov_defaults.Rd: Generated file
man/pffr_bias_aware_se.Rd: Generated file
man/pffr_bias_ref_difference.Rd: Generated file
man/pffr_predict_ci.Rd: Generated file

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+  if (!is.null(bias_ref)) {
+    if (raw) {


fabian-s and others added 2 commits September 28, 2026 13:03

Copilot AI lite review requested due to automatic review settings September 28, 2026 15:54

Copilot started reviewing on behalf of fabian-s September 28, 2026 15:54 View session

Copilot AI reviewed Sep 28, 2026

View reviewed changes

Comment thread R/pffr-methods.R

Comment on lines +1669 to +1670

if (!is.null(bias_ref)) {

if (raw) {

Navigation Menu

pffr: bias-aware pointwise intervals (coef bias_ref, pffr_predict_ci) - #132

pffr: bias-aware pointwise intervals (coef bias_ref, pffr_predict_ci)#132
fabian-s wants to merge 2 commits into
pffr-refactorfrom
bias-aware-ci

fabian-s commented Sep 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

fabian-s commented Sep 28, 2026

API

Checks

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants