R/glm_effect_estimators.R

Defines functions .ps_logistic .ps_lasso .ps_grf estimate_propensity_scores make_consistency_comparator effect_measure_to_label is_log_scale back_transform_estimate .robust_or_model_se .build_adjusted_formula .make_glm_or_estimator_fast .fs_logit_two_group .make_lm_estimator_fast .fs_lm_two_group .make_lm_estimator .make_poisson_rate_estimator .estimate_rr .estimate_or .fs_rd_gcomp_se .estimate_rd .make_glm_binary_estimator .make_cox_estimator .fs_existence_reason .fs_binary_cells .fs_nonestimable make_effect_estimator

Documented in estimate_propensity_scores make_effect_estimator

# =============================================================================
# glm_effect_estimators.R
#
# Effect-estimator closures for GLM outcomes (binary, continuous) and
# propensity score estimation for observational studies.
#
# Each estimator factory returns a function of the form:
#
#   function(data_slice) -> list(estimate, se, converged, n0, n1,
#                                measure, method_used)
#
# where `estimate` is on the log scale (log-OR, log-RR, log-IRR) or identity
# scale (RD, IRD, MD) consistent with the chosen `effect_measure`.
#
# Exported functions:
#   - make_effect_estimator: factory for estimator closures
#   - estimate_propensity_scores: PS estimation with GRF/LASSO/logistic
#
# Internal helpers (not exported):
#   - .make_cox_estimator, .make_glm_binary_estimator, etc.
#   - .estimate_rd, .estimate_or, .estimate_rr, .fs_rd_gcomp_se
#   - .ps_grf, .ps_lasso, .ps_logistic
#   - .build_adjusted_formula, .robust_or_model_se
# =============================================================================


# ---------------------------------------------------------------------------
# Top-level dispatcher
# ---------------------------------------------------------------------------

#' Make an Effect-Estimator Closure
#'
#' Returns a closure \code{function(data_slice)} that estimates the
#' within-subgroup treatment effect for the requested outcome type and
#' effect measure.  The closure is called repeatedly inside the
#' splitting-consistency loop and the bootstrap worker, so it must be
#' lightweight and handle small-sample edge cases gracefully.
#'
#' @param outcome_type Character. One of \code{"survival"}, \code{"binary"},
#'   \code{"continuous"}, or \code{"count"}.
#' @param treat.name  Character. Name of the binary treatment column (0/1).
#' @param outcome.name Character. Name of the outcome column.
#' @param event.name  Character or \code{NULL}. Name of the event indicator
#'   (survival only).
#' @param offset.name Character or \code{NULL}. Name of the follow-up time
#'   column for rate-based measures (IRR, IRD).
#' @param effect_measure Character or \code{NULL}.
#'   For binary: \code{"OR"} (default), \code{"RR"}, \code{"RD"},
#'   \code{"IRR"}, \code{"IRD"}.
#'   For continuous: \code{"MD"} (default).
#'   For survival: \code{"HR"} (default).
#'   \code{NULL} uses the default for the outcome type, which for binary
#'   is \code{"OR"} -- the same default \code{\link{forestsearch}} uses.
#' @param adverse_outcome Logical. If \code{TRUE} (default), higher
#'   outcome values indicate harm and the effect is computed on the
#'   raw outcome.  If \code{FALSE}, higher values indicate benefit
#'   (e.g., improvement) and, where it applies, the effect is computed
#'   on a reversed outcome so that effect > 0 (or a ratio > 1) indicates
#'   treatment harm.  By outcome type and effect measure:
#'   \itemize{
#'     \item \code{"binary"} with \code{"OR"}, \code{"RR"} or \code{"RD"}:
#'       with \code{FALSE} the outcome is replaced by \code{1 - Y} before
#'       fitting.  The log-OR and the RD change sign; the log-RR becomes
#'       the log risk ratio of the complementary event,
#'       \code{log((1 - p1) / (1 - p0))}, which is not \code{-log(p1 / p0)}
#'       (\code{p1}, \code{p0}: the treated and control risks).
#'     \item \code{"continuous"} (\code{"MD"}): with \code{FALSE} the
#'       outcome is replaced by \code{-Y} before fitting, so the MD
#'       changes sign.
#'     \item \code{"count"} (\code{"IRR"}, \code{"IRD"}), and
#'       \code{"binary"} with \code{"IRR"} or \code{"IRD"}: ignored; the
#'       Poisson rate estimator always uses the raw outcome.
#'     \item \code{"survival"}: ignored; the Cox estimator always uses the
#'       raw time and event.
#'   }
#'   \code{\link{forestsearch}} resolves its own default (\code{TRUE} for
#'   binary and count outcomes, \code{FALSE} otherwise) and passes it here;
#'   this function's default is \code{TRUE} for every outcome type.
#' @param robust_se Logical. Use sandwich robust SE when available.
#'   Default \code{TRUE}.
#' @param adjust_covariates This option is implemented but has not been
#'   tested against the manuscript analyses or the simulation studies of
#'   León and Anderson (2026a, 2026b), which use the unadjusted
#'   treatment-only fits.
#'   Character vector or \code{NULL}. Additional
#'   covariate names to include in the outcome model formula.
#' @param ps_adjust_method This option is implemented but has not been
#'   tested against the manuscript analyses or the simulation studies of
#'   León and Anderson (2026a, 2026b), which use the unadjusted
#'   treatment-only fits.
#'   Character. Propensity score adjustment method.
#'   One of \code{"none"} (default), \code{"iptw"} (stabilized inverse
#'   probability of treatment weights), or \code{"dr_gcomp"} (Bang &
#'   Robins 2005 IPS covariate with G-computation).
#' @param ... Additional arguments (reserved for future extensions).
#'
#' @return A closure \code{function(data_slice)} returning a list with
#'   components: \code{estimate}, \code{se}, \code{converged}, \code{n0},
#'   \code{n1}, \code{measure}, \code{method_used}.
#'
#' @examples
#' \dontrun{
#' # Binary outcome with odds ratio
#' fn <- make_effect_estimator("binary", "treat", "event",
#'   effect_measure = "OR")
#' result <- fn(my_data)
#' exp(result$estimate)  # odds ratio
#'
#' # Poisson rate with IPTW adjustment
#' fn_iptw <- make_effect_estimator("binary", "treat", "event",
#'   offset.name = "time", effect_measure = "IRR",
#'   ps_adjust_method = "iptw")
#' }
#'
#' @importFrom stats glm binomial poisson predict as.formula update vcov coef weighted.mean lm
#' @importFrom survival coxph Surv
#' @export
make_effect_estimator <- function(
    outcome_type,
    treat.name,
    outcome.name,
    event.name         = NULL,
    offset.name        = NULL,
    effect_measure     = NULL,
    adverse_outcome    = TRUE,
    robust_se          = TRUE,
    adjust_covariates  = NULL,
    ps_adjust_method   = c("none", "iptw", "dr_gcomp"),
    ...
) {
  ps_adjust_method <- match.arg(ps_adjust_method)
  outcome_type <- match.arg(
    outcome_type,
    choices = c("survival", "binary", "continuous", "count")
  )

  # Resolve default effect measure
  if (is.null(effect_measure)) {
    # Binary defaults to "OR", matching forestsearch()'s own binary default.
    effect_measure <- switch(outcome_type,
      survival   = "HR",
      binary     = "OR",
      continuous = "MD",
      count      = "IRR"
    )
  }

  # Validate offset requirement for rate-based measures
  if (effect_measure %in% c("IRR", "IRD") && is.null(offset.name)) {
    stop(
      "effect_measure = '", effect_measure,
      "' requires `offset.name` (follow-up time column).",
      call. = FALSE
    )
  }

  switch(outcome_type,

    survival = {
      .make_cox_estimator(
        treat.name        = treat.name,
        outcome.name      = outcome.name,
        event.name        = event.name,
        adjust_covariates = adjust_covariates,
        ps_adjust_method  = ps_adjust_method,
        ...
      )
    },

    binary = {
      # "OR" first: match.arg() returns the first choice for a NULL argument,
      # so the choice ORDER is itself a default.  Unreachable today -- the
      # resolution above always yields a length-1 value -- but an "RD" sitting
      # here contradicts the binary default resolved at :112-120, and a future
      # path that reaches this with NULL must land on the same measure.
      effect_measure <- match.arg(
        effect_measure,
        choices = c("OR", "RD", "RR", "IRR", "IRD")
      )
      if (effect_measure %in% c("IRR", "IRD")) {
        .make_poisson_rate_estimator(
          treat.name        = treat.name,
          outcome.name      = outcome.name,
          offset.name       = offset.name,
          effect_measure    = effect_measure,
          robust_se         = robust_se,
          adjust_covariates = adjust_covariates,
          ps_adjust_method  = ps_adjust_method,
          ...
        )
      } else {
        .make_glm_binary_estimator(
          treat.name        = treat.name,
          outcome.name      = outcome.name,
          effect_measure    = effect_measure,
          robust_se         = robust_se,
          adjust_covariates = adjust_covariates,
          ps_adjust_method  = ps_adjust_method,
          adverse_outcome   = adverse_outcome,
          ...
        )
      }
    },

    continuous = {
      .make_lm_estimator(
        treat.name        = treat.name,
        outcome.name      = outcome.name,
        adjust_covariates = adjust_covariates,
        ps_adjust_method  = ps_adjust_method,
        adverse_outcome   = adverse_outcome,
        ...
      )
    },

    count = {
      # Count / rate outcomes always route to the Poisson rate estimator
      effect_measure <- match.arg(
        effect_measure,
        choices = c("IRR", "IRD")
      )
      .make_poisson_rate_estimator(
        treat.name        = treat.name,
        outcome.name      = outcome.name,
        offset.name       = offset.name,
        effect_measure    = effect_measure,
        robust_se         = robust_se,
        adjust_covariates = adjust_covariates,
        ps_adjust_method  = ps_adjust_method,
        ...
      )
    }
  )
}


# ---------------------------------------------------------------------------
# Survival estimator (Cox) -- wraps existing inline logic into closure form
# ---------------------------------------------------------------------------

#' @noRd
# ---------------------------------------------------------------------------
# The estimability boundary
# ---------------------------------------------------------------------------
# An estimand that does not exist on a candidate must not be reported as a
# number.  glm() and coxph() both return a FINITE, divergent coefficient with
# converged = TRUE when an arm (or a cell) is empty -- the pathology is not
# visible through `converged`, so the existence condition is checked BEFORE
# the fit, per estimand:
#
#   OR            all four cells >= 1 (control/treated x events/non-events)
#   RR, IRR, HR   >= 1 event in each arm
#   RD, IRD, MD   no condition -- these estimands exist on any slice and are
#                 left byte-identical.  In particular RD's tier-3
#                 raw-proportions fallback returns converged = FALSE BY
#                 DESIGN and is never treated as non-estimable.
#
# This is not an admission floor: it adds no minimum count anywhere, and
# nothing is forwarded to the DINA or GRF collectors.  It only replaces a
# nonsense number with NA and a reason.

#' @noRd
.fs_nonestimable <- function(reason, n0, n1, measure, method_used) {
  list(
    estimate    = NA_real_,
    se          = NA_real_,
    converged   = FALSE,
    n0          = n0,
    n1          = n1,
    measure     = measure,
    method_used = method_used,
    reason      = reason
  )
}

#' @noRd
.fs_binary_cells <- function(y, t) {
  y <- as.integer(y)
  t <- as.integer(t)
  c(e0  = sum(t == 0L & y == 1L, na.rm = TRUE),
    ne0 = sum(t == 0L & y == 0L, na.rm = TRUE),
    e1  = sum(t == 1L & y == 1L, na.rm = TRUE),
    ne1 = sum(t == 1L & y == 0L, na.rm = TRUE))
}

#' @noRd
.fs_existence_reason <- function(measure, cells) {
  need <- switch(measure,
    OR  = c("e0", "ne0", "e1", "ne1"),
    RR  = c("e0", "e1"),
    IRR = c("e0", "e1"),
    HR  = c("e0", "e1"),
    NULL)
  if (is.null(need)) return(NULL)
  empty <- need[cells[need] == 0L]
  if (length(empty) == 0L) return(NULL)
  labs <- c(e0  = "control events",  ne0 = "control non-events",
            e1  = "treated events",  ne1 = "treated non-events")
  paste0("non-estimable: ",
         paste(labs[empty], collapse = " = 0, "), " = 0")
}


.make_cox_estimator <- function(treat.name, outcome.name, event.name,
                                adjust_covariates = NULL,
                                ps_adjust_method = "none", ...) {

  force(treat.name)
  force(outcome.name)
  force(event.name)
  force(adjust_covariates)
  force(ps_adjust_method)

  function(data_slice) {
    n0 <- sum(data_slice[[treat.name]] == 0L, na.rm = TRUE)
    n1 <- sum(data_slice[[treat.name]] == 1L, na.rm = TRUE)

    # Existence: the log-HR needs at least one event in each arm.  A
    # zero-event arm gives coxph() a monotone likelihood and a finite
    # divergent coefficient with no error raised.
    why <- .fs_existence_reason(
      "HR",
      .fs_binary_cells(data_slice[[event.name]], data_slice[[treat.name]]))
    if (!is.null(why)) {
      return(.fs_nonestimable(why, n0, n1, "log-HR", "nonestimable"))
    }

    result <- tryCatch({
      surv_obj <- survival::Surv(
        time  = data_slice[[outcome.name]],
        event = data_slice[[event.name]]
      )
      rhs <- treat.name
      if (ps_adjust_method == "none" &&
          !is.null(adjust_covariates) && length(adjust_covariates) > 0) {
        rhs <- paste(c(treat.name, adjust_covariates), collapse = " + ")
      }
      fmla <- stats::as.formula(paste0("surv_obj ~ ", rhs))

      if (ps_adjust_method == "iptw" && "sw" %in% names(data_slice)) {
        fit <- survival::coxph(fmla, data = data_slice,
                               weights = data_slice$sw)
      } else {
        fit <- survival::coxph(fmla, data = data_slice)
      }
      coef_val <- stats::coef(fit)[[treat.name]]
      se_val   <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
      list(
        estimate    = coef_val,
        se          = se_val,
        converged   = TRUE,
        n0          = n0,
        n1          = n1,
        measure     = "log-HR",
        method_used = "coxph"
      )
    },
    error = function(e) {
      list(
        estimate = NA_real_, se = NA_real_, converged = FALSE,
        n0 = n0, n1 = n1, measure = "log-HR", method_used = "coxph_failed"
      )
    })
    result
  }
}


# ---------------------------------------------------------------------------
# Binary GLM estimator (RD, OR, RR)
# ---------------------------------------------------------------------------

#' Make a binary-outcome GLM estimator closure
#'
#' Supports three non-rate effect measures:
#'   - `"RD"` : risk difference (identity-link binomial, with fallbacks)
#'   - `"OR"` : odds ratio (logistic regression); returns log-OR
#'   - `"RR"` : risk ratio (log-binomial with modified-Poisson fallback)
#'
#' For RD the estimate is on the identity scale.  For OR and RR the estimate
#' is on the log scale, consistent with the consistency-criterion comparisons.
#'
#' @noRd
.make_glm_binary_estimator <- function(
    treat.name,
    outcome.name,
    effect_measure    = "RD",
    robust_se         = TRUE,
    adjust_covariates = NULL,
    ps_adjust_method  = "none",
    adverse_outcome   = TRUE,
    ...
) {
  force(treat.name)
  force(outcome.name)
  force(effect_measure)
  force(robust_se)
  force(adjust_covariates)
  force(ps_adjust_method)
  force(adverse_outcome)

  function(data_slice) {
    # When the outcome is beneficial (adverse_outcome = FALSE), flip
    # Y -> 1 - Y so that the effect is computed on the adverse (failure)
    # scale.  This ensures that effect > 0 (RD) or effect > 1 (OR/RR)
    # consistently indicates treatment HARM, aligning with the
    # survival convention where HR > 1 = treatment hurts.
    if (!adverse_outcome) {
      data_slice[[outcome.name]] <- 1L - data_slice[[outcome.name]]
    }

    n0 <- sum(data_slice[[treat.name]] == 0L, na.rm = TRUE)
    n1 <- sum(data_slice[[treat.name]] == 1L, na.rm = TRUE)

    # Existence, ratio estimands only.  RD falls straight through: the risk
    # difference exists on any slice and its three-tier fallback is untouched.
    if (effect_measure %in% c("OR", "RR")) {
      why <- .fs_existence_reason(
        effect_measure,
        .fs_binary_cells(data_slice[[outcome.name]], data_slice[[treat.name]]))
      if (!is.null(why)) {
        return(.fs_nonestimable(
          why, n0, n1,
          if (identical(effect_measure, "OR")) "log-OR" else "log-RR",
          "nonestimable"))
      }
    }

    result <- switch(effect_measure,

      # ---- Risk Difference (primary) ----------------------------------------
      RD = {
        fmla <- .build_adjusted_formula(outcome.name, treat.name,
                  if (ps_adjust_method == "none") adjust_covariates else NULL)
        .estimate_rd(data_slice, fmla, treat.name, outcome.name, n0, n1,
                     if (ps_adjust_method == "none") adjust_covariates else NULL,
                     ps_adjust_method)
      },

      # ---- Odds Ratio -------------------------------------------------------
      OR = {
        .estimate_or(data_slice, treat.name, outcome.name, n0, n1,
                     adjust_covariates, ps_adjust_method)
      },

      # ---- Risk Ratio -------------------------------------------------------
      RR = {
        fmla <- .build_adjusted_formula(outcome.name, treat.name,
                  if (ps_adjust_method == "none") adjust_covariates else NULL)
        .estimate_rr(data_slice, fmla, treat.name, outcome.name,
                     n0, n1, robust_se)
      }
    )

    # A ratio fit that reports non-convergence is not a usable estimate.
    # Guarded by !is.na(estimate) so the existing error branch -- which
    # already returns NA with converged = FALSE -- is returned unaltered,
    # and scoped to OR/RR so RD's converged = FALSE tier 3 is never caught.
    if (effect_measure %in% c("OR", "RR") &&
        isFALSE(result$converged) && !is.na(result$estimate)) {
      return(.fs_nonestimable("non-convergent fit", n0, n1,
                              result$measure, result$method_used))
    }

    result
  }
}


# ---------------------------------------------------------------------------
# RD estimation with three-tier fallback
# ---------------------------------------------------------------------------

#' @noRd
.estimate_rd <- function(data_slice, fmla, treat.name, outcome.name, n0, n1,
                         adjust_covariates = NULL, ps_adjust_method = "none") {
  y0 <- data_slice[[outcome.name]][data_slice[[treat.name]] == 0]
  y1 <- data_slice[[outcome.name]][data_slice[[treat.name]] == 1]
  p0 <- mean(y0, na.rm = TRUE)
  p1 <- mean(y1, na.rm = TRUE)

  # IPTW path: weighted means
  if (ps_adjust_method == "iptw" && "sw" %in% names(data_slice)) {
    sw <- data_slice$sw
    W  <- data_slice[[treat.name]]
    rd_est <- stats::weighted.mean(data_slice[[outcome.name]][W == 1], sw[W == 1]) -
              stats::weighted.mean(data_slice[[outcome.name]][W == 0], sw[W == 0])
    # SE via weighted proportions
    wp1 <- stats::weighted.mean(data_slice[[outcome.name]][W == 1], sw[W == 1])
    wp0 <- stats::weighted.mean(data_slice[[outcome.name]][W == 0], sw[W == 0])
    se_rd <- sqrt(wp1 * (1 - wp1) / sum(W == 1) + wp0 * (1 - wp0) / sum(W == 0))
    return(list(
      estimate = rd_est, se = se_rd, converged = TRUE,
      n0 = n0, n1 = n1, measure = "RD", method_used = "iptw_rd"
    ))
  }

  n_adj <- if (!is.null(adjust_covariates)) length(adjust_covariates) else 0L

  # Tier 1: Identity-link binomial GLM
  tier1 <- tryCatch({
    start_vals <- c(p0, p1 - p0, rep(0, n_adj))
    fit <- stats::glm(
      fmla,
      data   = data_slice,
      family = stats::binomial(link = "identity"),
      start  = start_vals
    )
    if (!fit$converged) stop("identity-link binomial did not converge")
    coef_val <- stats::coef(fit)[[treat.name]]
    se_val   <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
    list(
      estimate    = coef_val,
      se          = se_val,
      converged   = TRUE,
      n0          = n0,
      n1          = n1,
      measure     = "RD",
      method_used = if (n_adj > 0) "identity_binomial_adj" else "identity_binomial"
    )
  },
  error   = function(e) NULL,
  warning = function(w) {
    if (grepl("converge", conditionMessage(w), ignore.case = TRUE)) {
      return(NULL)
    }
    invokeRestart("muffleWarning")
  })

  if (!is.null(tier1)) return(tier1)

  # Tier 2: G-computation from logistic regression
  tier2 <- tryCatch({
    fit_logit <- stats::glm(
      fmla,
      data   = data_slice,
      family = stats::binomial(link = "logit")
    )
    if (!fit_logit$converged) stop("logistic did not converge")

    # G-computation: predict under each treatment arm, average over subjects
    nd0 <- nd1 <- data_slice
    nd0[[treat.name]] <- 0L
    nd1[[treat.name]] <- 1L
    pred0 <- stats::predict(fit_logit, newdata = nd0, type = "response")
    pred1 <- stats::predict(fit_logit, newdata = nd1, type = "response")
    rd_est <- mean(pred1) - mean(pred0)

    # SE of rd_est by the delta method: the two-sample binomial SE when
    # unadjusted, sqrt(g' V g) over every estimable coefficient when
    # adjusted (.fs_rd_gcomp_se()).  The scaled-coefficient form
    # abs(avg_deriv) * se_treat, which uses the treatment coefficient alone,
    # is kept only as the adjusted branch's fallback.
    se_treat <- sqrt(diag(stats::vcov(fit_logit)))[[treat.name]]
    # Convert logistic SE to RD scale using average marginal effect
    avg_deriv <- mean(pred1 * (1 - pred1))
    se_rd <- if (n_adj == 0L) {
      # Unadjusted (A-055): the two-arm logistic model is saturated, so the
      # arm means of pred0 and pred1 are the observed proportions p0 and p1,
      # and the exact delta-method SE of rd_est is the two-sample binomial
      # SE.  The scaled-coefficient form below drops the control arm's
      # variance and degenerates when an arm is at 0% or 100%.  No weights
      # reach this tier: the IPTW path (the only weighted one) returns
      # above, and neither glm() call here takes a weights argument.
      sqrt(p1 * (1 - p1) / n1 + p0 * (1 - p0) / n0)
    } else {
      # Adjusted (B1): the full delta method.  A value that is not a finite,
      # non-negative number keeps the scaled-coefficient form (NA when the
      # treatment coefficient is aliased, i.e. the effect is not
      # estimable); the helper never errors, so no slice is routed to tier
      # 3 by it.
      se_dm <- .fs_rd_gcomp_se(fit_logit, nd0, nd1, pred0, pred1)
      if (length(se_dm) == 1L && is.finite(se_dm) && se_dm >= 0) {
        se_dm
      } else {
        abs(avg_deriv) * se_treat
      }
    }

    list(
      estimate    = rd_est,
      se          = se_rd,
      converged   = TRUE,
      n0          = n0,
      n1          = n1,
      measure     = "RD",
      method_used = if (n_adj > 0) "logistic_gcomp_adj" else "logistic_margins"
    )
  },
  error = function(e) NULL)

  if (!is.null(tier2)) return(tier2)

  # Tier 3: Raw proportions
  rd_raw <- p1 - p0
  se_raw <- sqrt(
    p1 * (1 - p1) / max(n1, 1L) + p0 * (1 - p0) / max(n0, 1L)
  )
  list(
    estimate    = rd_raw,
    se          = se_raw,
    converged   = FALSE,
    n0          = n0,
    n1          = n1,
    measure     = "RD",
    method_used = "raw_means"
  )
}


#' Delta-method SE of the logistic g-computation risk difference
#'
#' The estimate is rd(b) = mean(plogis(X1 b)) - mean(plogis(X0 b)), with X1,
#' X0 the design matrices of every row of the slice with treatment set to 1
#' and to 0.  Its gradient in b is
#' g = colMeans(p1 (1 - p1) X1) - colMeans(p0 (1 - p0) X0), and the SE is
#' sqrt(g' V g) with V = vcov(fit).  Aliased coefficients (NA) are dropped
#' from b, X1, X0 and V.  When any aliased column is one on which X1 and X0
#' differ (a column that treatment changes), NA_real_ is returned, and the
#' caller, .estimate_rd(), keeps its previous expression abs(avg_deriv) *
#' se_treat.  This covers the slice where the treatment effect is not
#' estimable: the treatment column itself is aliased when one arm is empty
#' or has no observed outcome, dropping it would leave g = 0, and the
#' previous expression is NA there.  It also covers an aliased user-supplied
#' treatment-interaction column (e.g. adjust_covariates = c("site",
#' "treat:age") with age constant and nonzero on the slice), where the
#' treatment coefficient is estimable.
#' The design matrices are built as predict.lm() builds them (the fit's
#' terms, xlevels and contrasts), so the rows match p0 and p1, the fitted
#' probabilities the estimate averages.
#'
#' @param fit A converged logistic glm.
#' @param nd0,nd1 The slice with treatment set to 0 and to 1.
#' @param p0,p1 Fitted probabilities for nd0 and nd1 (predict(type =
#'   "response")).
#' @return The SE, or NA_real_ when it is not a finite, non-negative number,
#'   when an aliased column is one that treatment changes (see above), or
#'   when any step fails (an error or a warning); never an error.
#' @noRd
.fs_rd_gcomp_se <- function(fit, nd0, nd1, p0, p1) {
  tryCatch({
    b   <- stats::coef(fit)
    est <- names(b)[!is.na(b)]
    al  <- names(b)[is.na(b)]
    tt  <- stats::delete.response(stats::terms(fit))
    design <- function(nd) {
      mf <- stats::model.frame(tt, nd, na.action = stats::na.pass,
                               xlev = fit$xlevels)
      stats::model.matrix(tt, mf, contrasts.arg = fit$contrasts)
    }
    X0 <- design(nd0)
    X1 <- design(nd1)
    # Treatment changes an aliased column (stop -> NA; see above).
    stopifnot(!any(X1[, al, drop = FALSE] != X0[, al, drop = FALSE],
                   na.rm = TRUE))
    X0 <- X0[, est, drop = FALSE]
    X1 <- X1[, est, drop = FALSE]
    stopifnot(length(p0) == nrow(X0), length(p1) == nrow(X1))
    V <- stats::vcov(fit)[est, est, drop = FALSE]
    g <- colMeans(p1 * (1 - p1) * X1) - colMeans(p0 * (1 - p0) * X0)
    v <- sum(g * drop(V %*% g))
    if (is.finite(v) && v >= 0) sqrt(v) else NA_real_
  },
  error   = function(e) NA_real_,
  warning = function(w) NA_real_)
}


# ---------------------------------------------------------------------------
# OR estimation with IPTW / DR / unadjusted
# ---------------------------------------------------------------------------

#' @noRd
.estimate_or <- function(data_slice, treat.name, outcome.name, n0, n1,
                         adjust_covariates = NULL,
                         ps_adjust_method = "none") {

  tryCatch({
    if (ps_adjust_method == "iptw" && "sw" %in% names(data_slice)) {
      # IPTW: weighted logistic, coefficient IS the marginal log-OR
      fmla <- stats::as.formula(paste0(outcome.name, " ~ ", treat.name))
      fit <- stats::glm(fmla, data = data_slice,
                        family = stats::binomial(link = "logit"),
                        weights = data_slice$sw)
      coef_val <- stats::coef(fit)[[treat.name]]
      se_val   <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
      list(estimate = coef_val, se = se_val, converged = fit$converged,
           n0 = n0, n1 = n1, measure = "log-OR",
           method_used = "logistic_iptw")

    } else if (ps_adjust_method == "dr_gcomp" &&
               "ips_covar" %in% names(data_slice) &&
               "ps_hat" %in% names(data_slice)) {
      # Bang & Robins DR: logistic with IPS covariate + G-computation
      fmla <- stats::as.formula(
        paste0(outcome.name, " ~ ", treat.name, " + ips_covar"))
      fit <- stats::glm(fmla, data = data_slice,
                        family = stats::binomial(link = "logit"))

      # G-computation (Section 2.2, Bang & Robins 2005)
      ps <- data_slice$ps_hat
      nd1 <- nd0 <- data_slice
      nd1[[treat.name]] <- 1L
      nd1$ips_covar     <- 1 / ps
      nd0[[treat.name]] <- 0L
      nd0$ips_covar     <- 1 / (1 - ps)

      pred1 <- stats::predict(fit, newdata = nd1, type = "response")
      pred0 <- stats::predict(fit, newdata = nd0, type = "response")

      # log-OR from marginal probabilities
      p1 <- mean(pred1); p0 <- mean(pred0)
      log_or <- log((p1 / (1 - p1)) / (p0 / (1 - p0)))
      se_treat <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
      list(estimate = log_or, se = se_treat, converged = fit$converged,
           n0 = n0, n1 = n1, measure = "log-OR",
           method_used = "logistic_dr_gcomp")

    } else {
      # Unadjusted logistic
      fmla <- .build_adjusted_formula(outcome.name, treat.name,
                                      adjust_covariates)
      fit <- stats::glm(fmla, data = data_slice,
                        family = stats::binomial(link = "logit"))
      coef_val <- stats::coef(fit)[[treat.name]]
      se_val   <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
      list(estimate = coef_val, se = se_val, converged = fit$converged,
           n0 = n0, n1 = n1, measure = "log-OR",
           method_used = "logistic")
    }
  },
  error = function(e) {
    list(estimate = NA_real_, se = NA_real_, converged = FALSE,
         n0 = n0, n1 = n1, measure = "log-OR",
         method_used = paste0("logistic_failed_", ps_adjust_method))
  })
}


# ---------------------------------------------------------------------------
# RR estimation: log-binomial -> modified Poisson fallback
# ---------------------------------------------------------------------------

#' @noRd
.estimate_rr <- function(data_slice, fmla, treat.name, outcome.name,
                         n0, n1, robust_se) {

  # Attempt log-binomial first
  fit_rr <- tryCatch({
    p_start <- mean(data_slice[[outcome.name]], na.rm = TRUE)
    fit <- stats::glm(
      fmla,
      data   = data_slice,
      family = stats::binomial(link = "log"),
      start  = c(log(max(p_start, 0.01)), 0)
    )
    if (!fit$converged) stop("log-binomial did not converge")
    coef_val <- stats::coef(fit)[[treat.name]]
    se_val   <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
    list(
      estimate    = coef_val,
      se          = se_val,
      converged   = TRUE,
      n0          = n0,
      n1          = n1,
      measure     = "log-RR",
      method_used = "log_binomial"
    )
  },
  error   = function(e) NULL,
  warning = function(w) {
    if (grepl("converge", conditionMessage(w), ignore.case = TRUE)) {
      return(NULL)
    }
    invokeRestart("muffleWarning")
  })

  if (!is.null(fit_rr)) return(fit_rr)

  # Fallback: modified Poisson (Zou 2004)
  tryCatch({
    fit <- stats::glm(
      fmla,
      data   = data_slice,
      family = stats::poisson(link = "log")
    )
    coef_val <- stats::coef(fit)[[treat.name]]
    se_val   <- .robust_or_model_se(fit, treat.name, robust_se)
    list(
      estimate    = coef_val,
      se          = se_val,
      converged   = TRUE,
      n0          = n0,
      n1          = n1,
      measure     = "log-RR",
      method_used = "modified_poisson"
    )
  },
  error = function(e) {
    list(
      estimate = NA_real_, se = NA_real_, converged = FALSE,
      n0 = n0, n1 = n1, measure = "log-RR",
      method_used = "rr_failed"
    )
  })
}


# ---------------------------------------------------------------------------
# Poisson rate estimator (IRR and IRD)
# ---------------------------------------------------------------------------

#' Make a Poisson rate-model estimator closure
#'
#' Fits `glm(event ~ treat, family = poisson(link = "log"),
#'           offset = log(time))` and returns:
#'
#'   - For `"IRR"`: the log incidence rate ratio (treatment coefficient)
#'   - For `"IRD"`: the incidence rate difference computed from predicted rates
#'
#' Under constant baseline hazard (exponential survival), `exp(log-IRR)`
#' equals the Cox hazard ratio, providing a sanity check against the
#' existing survival pipeline.
#'
#' @noRd
.make_poisson_rate_estimator <- function(
    treat.name,
    outcome.name,
    offset.name,
    effect_measure    = "IRR",
    robust_se         = TRUE,
    adjust_covariates = NULL,
    ps_adjust_method  = "none",
    ...
) {
  force(treat.name)
  force(outcome.name)
  force(offset.name)
  force(effect_measure)
  force(robust_se)
  force(adjust_covariates)
  force(ps_adjust_method)

  function(data_slice) {
    n0 <- sum(data_slice[[treat.name]] == 0L, na.rm = TRUE)
    n1 <- sum(data_slice[[treat.name]] == 1L, na.rm = TRUE)

    # Existence, IRR only.  The rate difference (IRD) is untouched.
    if (identical(effect_measure, "IRR")) {
      why <- .fs_existence_reason(
        "IRR",
        c(e0  = sum(data_slice[[treat.name]] == 0L &
                    data_slice[[outcome.name]] > 0, na.rm = TRUE),
          ne0 = NA_integer_,
          e1  = sum(data_slice[[treat.name]] == 1L &
                    data_slice[[outcome.name]] > 0, na.rm = TRUE),
          ne1 = NA_integer_))
      if (!is.null(why)) {
        return(.fs_nonestimable(why, n0, n1, "log-IRR", "nonestimable"))
      }
    }

    # Validate offset column
    time_vec <- data_slice[[offset.name]]
    if (any(time_vec <= 0, na.rm = TRUE)) {
      time_vec <- pmax(time_vec, .Machine$double.eps)
    }

    # Add log-offset as column (avoids scoping issues with offset=)
    data_slice$.log_offset <- log(time_vec)

    result <- tryCatch({
      # =================================================================
      # Option A: IPTW -- stabilized weights, coefficient IS the effect
      # =================================================================
      if (ps_adjust_method == "iptw" && "sw" %in% names(data_slice)) {
        fmla <- stats::as.formula(
          paste0(outcome.name, " ~ ", treat.name, " + offset(.log_offset)")
        )
        fit <- stats::glm(
          fmla,
          data    = data_slice,
          family  = stats::poisson(link = "log"),
          weights = data_slice$sw
        )
        coef_val <- stats::coef(fit)[[treat.name]]
        se_val   <- .robust_or_model_se(fit, treat.name, robust_se)
        list(
          estimate    = coef_val,
          se          = se_val,
          converged   = fit$converged,
          n0 = n0, n1 = n1,
          measure     = "log-IRR",
          method_used = "poisson_iptw"
        )

      # =================================================================
      # Option B: Bang & Robins DR -- IPS covariate + G-computation
      # (Section 2.2, Bang & Robins 2005)
      # =================================================================
      } else if (ps_adjust_method == "dr_gcomp" &&
                 "ips_covar" %in% names(data_slice) &&
                 "ps_hat" %in% names(data_slice)) {
        fmla <- stats::as.formula(
          paste0(outcome.name, " ~ ", treat.name,
                 " + ips_covar + offset(.log_offset)")
        )
        fit <- stats::glm(
          fmla,
          data   = data_slice,
          family = stats::poisson(link = "log")
        )

        # G-computation: predict under both treatment scenarios
        # Under W=1: ips = 1/e(x);  Under W=0: ips = 1/(1-e(x))
        ps <- data_slice$ps_hat
        nd1 <- nd0 <- data_slice
        nd1[[treat.name]] <- 1L
        nd1$ips_covar     <- 1 / ps
        nd0[[treat.name]] <- 0L
        nd0$ips_covar     <- 1 / (1 - ps)

        pred1 <- stats::predict(fit, newdata = nd1, type = "response")
        pred0 <- stats::predict(fit, newdata = nd0, type = "response")

        if (effect_measure == "IRR") {
          est <- log(mean(pred1) / mean(pred0))
          # Delta-method SE approximation
          se_treat <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
          list(
            estimate    = est,
            se          = se_treat,
            converged   = fit$converged,
            n0 = n0, n1 = n1,
            measure     = "log-IRR",
            method_used = "poisson_dr_gcomp"
          )
        } else {
          # IRD
          est <- mean(pred1) - mean(pred0)
          se_treat <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
          avg_deriv <- mean(pred1)
          list(
            estimate    = est,
            se          = abs(avg_deriv) * se_treat,
            converged   = fit$converged,
            n0 = n0, n1 = n1,
            measure     = "IRD",
            method_used = "poisson_dr_gcomp"
          )
        }

      # =================================================================
      # Default: unadjusted (no PS)
      # =================================================================
      } else {
        fmla_off <- stats::as.formula(
          paste0(outcome.name, " ~ ", treat.name, " + offset(.log_offset)")
        )
        # If adjust_covariates provided (non-PS), add them
        if (!is.null(adjust_covariates) && length(adjust_covariates) > 0) {
          fmla_off <- stats::as.formula(paste0(
            outcome.name, " ~ ", treat.name, " + ",
            paste(adjust_covariates, collapse = " + "),
            " + offset(.log_offset)"))
        }
        fit <- stats::glm(
          fmla_off,
          data   = data_slice,
          family = stats::poisson(link = "log")
        )

        if (effect_measure == "IRR") {
          coef_val <- stats::coef(fit)[[treat.name]]
          se_val   <- .robust_or_model_se(fit, treat.name, robust_se)
          list(
            estimate    = coef_val,
            se          = se_val,
            converged   = fit$converged,
            n0 = n0, n1 = n1,
            measure     = "log-IRR",
            method_used = "poisson_offset"
          )
        } else {
          # IRD via delta method
          beta <- stats::coef(fit)
          V    <- stats::vcov(fit)
          mean_log_t <- mean(log(time_vec), na.rm = TRUE)
          lam0 <- exp(beta[[1L]] + mean_log_t)
          lam1 <- exp(beta[[1L]] + beta[[treat.name]] + mean_log_t)
          ird  <- lam1 - lam0
          grad <- c(lam1 - lam0, lam1)
          se_ird <- sqrt(as.numeric(t(grad) %*% V[1:2, 1:2] %*% grad))
          list(
            estimate    = ird,
            se          = se_ird,
            converged   = fit$converged,
            n0 = n0, n1 = n1,
            measure     = "IRD",
            method_used = "poisson_offset_delta"
          )
        }
      }
    },
    error = function(e) {
      measure_label <- if (effect_measure == "IRR") "log-IRR" else "IRD"
      list(
        estimate = NA_real_, se = NA_real_, converged = FALSE,
        n0 = n0, n1 = n1, measure = measure_label,
        method_used = paste0("poisson_failed_", ps_adjust_method)
      )
    })

    result
  }
}


# ---------------------------------------------------------------------------
# Continuous outcome estimator (linear regression / mean difference)
# ---------------------------------------------------------------------------

#' Make a continuous-outcome estimator closure
#'
#' Returns the within-subgroup OLS treatment coefficient (mean difference,
#' experimental minus control) and its standard error.
#'
#' @noRd
.make_lm_estimator <- function(treat.name, outcome.name,
                               adjust_covariates = NULL,
                               ps_adjust_method = "none",
                               adverse_outcome = TRUE, ...) {

  force(treat.name)
  force(outcome.name)
  force(adjust_covariates)
  force(ps_adjust_method)
  force(adverse_outcome)

  function(data_slice) {
    # When higher Y = better (adverse_outcome = FALSE), negate Y
    # so that MD > 0 consistently indicates treatment HARM,
    # aligning with the survival convention where HR > 1 = harm
    # and the binary convention where OR > 1 on adverse Y = harm.
    if (!adverse_outcome) {
      data_slice[[outcome.name]] <- -data_slice[[outcome.name]]
    }

    n0 <- sum(data_slice[[treat.name]] == 0L, na.rm = TRUE)
    n1 <- sum(data_slice[[treat.name]] == 1L, na.rm = TRUE)

    fmla <- .build_adjusted_formula(outcome.name, treat.name,
              if (ps_adjust_method == "none") adjust_covariates else NULL)

    result <- tryCatch({
      if (ps_adjust_method == "iptw" && "sw" %in% names(data_slice)) {
        # `weights` is evaluated by model.frame() in `data` and then in the
        # formula's environment.  `fmla` comes from .build_adjusted_formula(),
        # whose frame does not hold `data_slice`, so `weights = data_slice$sw`
        # never resolved and every weighted fit failed (0.4.0 and earlier).
        # `sw` is a column of data_slice (the guard above), so it resolves in
        # `data`.
        fit <- stats::lm(fmla, data = data_slice, weights = sw)
      } else {
        fit <- stats::lm(fmla, data = data_slice)
      }
      coef_val <- stats::coef(fit)[[treat.name]]
      se_val   <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
      list(
        estimate    = coef_val,
        se          = se_val,
        converged   = TRUE,
        n0          = n0,
        n1          = n1,
        measure     = "MD",
        method_used = "ols"
      )
    },
    error = function(e) {
      list(
        estimate = NA_real_, se = NA_real_, converged = FALSE,
        n0 = n0, n1 = n1, measure = "MD",
        method_used = "ols_failed"
      )
    })

    result
  }
}


# ---------------------------------------------------------------------------
# Unadjusted fast path (0.3.3)
# ---------------------------------------------------------------------------

#' Two-group OLS core, bit-identical to `lm()` + `coef()` + `vcov()`
#'
#' Fits `y ~ t` for an unadjusted, unweighted, offset-free two-group
#' comparison via `stats::lm.fit()` on the explicit two-column model matrix,
#' then extracts the treatment coefficient and its standard error by
#' replicating `stats::summary.lm()` / `stats::vcov.lm()` operation for
#' operation (R 4.6.1 sources), so the returned doubles are bit-identical to
#' the slow chain `sqrt(diag(stats::vcov(stats::lm(...))))[[treat.name]]`:
#'
#'   - `rss <- sum(r^2)`; `resvar <- rss/rdf`; the "essentially perfect fit"
#'     warning with `summary.lm()`'s exact condition and message;
#'   - `p1 <- 1L:p`; `R <- chol2inv(Qr$qr[p1, p1, drop = FALSE])` with
#'     `summary.lm()`'s pivot handling (`z$coefficients[Qr$pivot[p1]]` names
#'     the rows/cols of `cov.unscaled`);
#'   - `vcov.summary.lm()`: `sigma^2 * cov.unscaled` with
#'     `sigma <- sqrt(resvar)` (NOT `resvar` directly -- `sqrt(x)^2` is not
#'     `x` bitwise), expanded over aliased coefficients per
#'     `stats:::.vcov.aliased()` (`complete = TRUE`);
#'   - `sqrt(diag(vc))[[treat.name]]`.
#'
#' A rank-deficient fit (single treatment arm: `t` constant, the treatment
#' column aliased) therefore returns `estimate = NA` and `se = NA` without
#' error, exactly as the slow chain does.
#'
#' @param y Numeric vector. Outcome (already sliced, already sign-adjusted).
#' @param t Numeric or integer vector. Treatment indicator (0/1), same length.
#' @param treat.name Character. The treatment column name `model.matrix()`
#'   would use, so coefficient extraction matches the slow path's
#'   `[[treat.name]]`.
#' @return List with `estimate` and `se` (doubles, possibly `NA`).
#' @keywords internal
#' @noRd
.fs_lm_two_group <- function(y, t, treat.name) {
  X <- cbind(1, t)
  colnames(X) <- c("(Intercept)", treat.name)
  z <- stats::lm.fit(X, y)
  coef_val <- z$coefficients[[treat.name]]
  p <- z$rank
  rdf <- z$df.residual
  r <- z$residuals
  f <- z$fitted.values
  rss <- sum(r^2)
  resvar <- rss / rdf
  if (is.finite(resvar) && resvar < (mean(f)^2 + stats::var(c(f))) * 1e-30)
    warning("essentially perfect fit: summary may be unreliable")
  p1 <- 1L:p
  R <- chol2inv(z$qr$qr[p1, p1, drop = FALSE])
  est_names <- names(z$coefficients[z$qr$pivot[p1]])
  dimnames(R) <- list(est_names, est_names)
  sigma <- sqrt(resvar)
  aliased <- is.na(z$coefficients)
  vc <- sigma^2 * R
  if (NROW(vc) < (P <- length(aliased)) && any(aliased)) {
    cn <- names(aliased)
    VC <- matrix(NA_real_, P, P, dimnames = list(cn, cn))
    j <- which(!aliased)
    VC[j, j] <- vc
    vc <- VC
  }
  list(estimate = coef_val, se = sqrt(diag(vc))[[treat.name]])
}


#' Fast unadjusted continuous (MD) estimator closure
#'
#' Drop-in replacement for the `.make_lm_estimator()` closure when there is
#' no covariate adjustment, no propensity adjustment and no weighting: the
#' routing predicate at the construction site (`forestsearch_main.R`) selects
#' it, and every consumer of the closure (search loop, bootstrap H/Hc fits,
#' consistency machinery, display helpers) works unchanged because the
#' signature and the returned structure -- fields, names, types, failure
#' behaviour -- are identical to the slow closure's, and the numbers are
#' bit-identical (see `.fs_lm_two_group()`).
#'
#' @keywords internal
#' @noRd
.make_lm_estimator_fast <- function(treat.name, outcome.name,
                                    adverse_outcome = TRUE, ...) {

  force(treat.name)
  force(outcome.name)
  force(adverse_outcome)

  function(data_slice) {
    # Sign convention as in .make_lm_estimator(): negate Y when higher Y =
    # better so that MD > 0 indicates treatment harm.
    if (!adverse_outcome) {
      data_slice[[outcome.name]] <- -data_slice[[outcome.name]]
    }

    n0 <- sum(data_slice[[treat.name]] == 0L, na.rm = TRUE)
    n1 <- sum(data_slice[[treat.name]] == 1L, na.rm = TRUE)

    result <- tryCatch({
      core <- .fs_lm_two_group(data_slice[[outcome.name]],
                               data_slice[[treat.name]], treat.name)
      list(
        estimate    = core$estimate,
        se          = core$se,
        converged   = TRUE,
        n0          = n0,
        n1          = n1,
        measure     = "MD",
        method_used = "ols"
      )
    },
    error = function(e) {
      list(
        estimate = NA_real_, se = NA_real_, converged = FALSE,
        n0 = n0, n1 = n1, measure = "MD",
        method_used = "ols_failed"
      )
    })

    result
  }
}


# ---------------------------------------------------------------------------
# Unadjusted fast path, binary OR (0.4.0.9000)
# ---------------------------------------------------------------------------

#' Two-group logistic core, bit-identical to `glm()` + `coef()` + `vcov()`
#'
#' Fits `y ~ t` for an unadjusted, unweighted, offset-free two-group
#' comparison via `stats::glm.fit()` on the explicit two-column model matrix
#' -- the call `stats::glm()` makes for that formula (weights, start,
#' etastart, mustart and offset at their defaults, `intercept = TRUE`,
#' `singular.ok = TRUE`, `glm.control()`) -- then takes the treatment
#' coefficient and its standard error by replicating `stats::summary.glm()`
#' / `stats::vcov.glm()` operation for operation (R 4.6.1 sources):
#' `p1 <- 1L:p`; `covmat.unscaled <- chol2inv(Qr$qr[p1, p1, drop = FALSE])`;
#' `covmat <- dispersion * covmat.unscaled` with `dispersion = 1` for the
#' binomial family (kept as `1 * ...` so the arithmetic is the same);
#' `sqrt(diag(covmat))` at the treatment column.  A rank-deficient fit
#' (single treatment arm) returns `estimate = NA` and `se = NA` without
#' error, as the slow chain does.  `glm.fit()`'s own warnings ("fitted
#' probabilities numerically 0 or 1 occurred", "algorithm did not converge")
#' are raised exactly as through `glm()`: nothing is suppressed here.
#'
#' @param y Numeric vector. 0/1 outcome, already sliced, already on the
#'   adverse scale.
#' @param t Numeric or integer vector. Treatment indicator (0/1), same length.
#' @param treat.name Character. The treatment column name `model.matrix()`
#'   would use.
#' @return List with `estimate`, `se` (doubles, possibly `NA`) and
#'   `converged` (`glm.fit()`'s flag).
#' @keywords internal
#' @noRd
.fs_logit_two_group <- function(y, t, treat.name) {
  X <- cbind(1, t)
  colnames(X) <- c("(Intercept)", treat.name)
  fit <- stats::glm.fit(X, as.double(y),
                        family = stats::binomial(link = "logit"))
  coef_val <- fit$coefficients[[treat.name]]
  p1 <- seq_len(fit$rank)
  covmat <- 1 * chol2inv(fit$qr$qr[p1, p1, drop = FALSE])
  # Column 2 is the treatment term; with the treatment column aliased
  # (rank 1) the index is out of range and gives NA, as vcov(complete = TRUE)
  # does for an aliased coefficient.
  se_val <- unname(sqrt(diag(covmat))[2L])
  list(estimate = coef_val, se = se_val, converged = fit$converged)
}


#' Fast unadjusted binary odds-ratio estimator closure
#'
#' Drop-in replacement for the `.make_glm_binary_estimator()` closure when
#' `effect_measure = "OR"`, there is no covariate adjustment and no
#' propensity adjustment: the routing predicate at the construction site
#' (`forestsearch_main.R`) selects it, and every consumer of the closure
#' works unchanged because the signature and the returned structure --
#' fields, names, types, failure behaviour, the `reason` of a non-estimable
#' slice -- are identical to the slow closure's, and the numbers are
#' bit-identical (see `.fs_logit_two_group()`).  The search loop routes its
#' per-candidate fit to the vector path on the `fs_fast_unadjusted`
#' attribute; `fs_fast_core` in this closure's environment tells
#' `fit_glm_for_subgroup_fast()` which core to run (the continuous closure
#' carries no marker and keeps its OLS path).
#'
#' @keywords internal
#' @noRd
.make_glm_or_estimator_fast <- function(treat.name, outcome.name,
                                        adverse_outcome = TRUE, ...) {
  force(treat.name)
  force(outcome.name)
  force(adverse_outcome)
  fs_fast_core <- "logit_or"

  function(data_slice) {
    # Sign convention as in .make_glm_binary_estimator(): Y -> 1 - Y when the
    # outcome is beneficial, so that OR > 1 indicates treatment harm.
    if (!adverse_outcome) {
      data_slice[[outcome.name]] <- 1L - data_slice[[outcome.name]]
    }

    n0 <- sum(data_slice[[treat.name]] == 0L, na.rm = TRUE)
    n1 <- sum(data_slice[[treat.name]] == 1L, na.rm = TRUE)

    why <- .fs_existence_reason(
      "OR",
      .fs_binary_cells(data_slice[[outcome.name]], data_slice[[treat.name]]))
    if (!is.null(why)) {
      return(.fs_nonestimable(why, n0, n1, "log-OR", "nonestimable"))
    }

    result <- tryCatch({
      core <- .fs_logit_two_group(data_slice[[outcome.name]],
                                  data_slice[[treat.name]], treat.name)
      list(estimate = core$estimate, se = core$se, converged = core$converged,
           n0 = n0, n1 = n1, measure = "log-OR", method_used = "logistic")
    },
    error = function(e) {
      list(estimate = NA_real_, se = NA_real_, converged = FALSE,
           n0 = n0, n1 = n1, measure = "log-OR",
           method_used = "logistic_failed_none")
    })

    # The slow closure's non-convergence rule, verbatim.
    if (isFALSE(result$converged) && !is.na(result$estimate)) {
      return(.fs_nonestimable("non-convergent fit", n0, n1,
                              result$measure, result$method_used))
    }

    result
  }
}


# ---------------------------------------------------------------------------
# Utilities
# ---------------------------------------------------------------------------

#' Build model formula with optional covariate adjustment
#'
#' Constructs a formula string of the form `outcome ~ treat + cov1 + cov2`.
#' When `adjust_covariates` is NULL or empty, returns `outcome ~ treat`.
#'
#' @noRd
.build_adjusted_formula <- function(outcome.name, treat.name,
                                    adjust_covariates = NULL) {
  rhs <- treat.name
  if (!is.null(adjust_covariates) && length(adjust_covariates) > 0) {
    rhs <- paste(c(treat.name, adjust_covariates), collapse = " + ")
  }
  stats::as.formula(paste0(outcome.name, " ~ ", rhs))
}


#' Use sandwich robust SE if available; else model-based
#' @noRd
.robust_or_model_se <- function(fit, treat.name, robust_se = TRUE) {
  if (robust_se) {
    se_val <- tryCatch({
      if (!requireNamespace("sandwich", quietly = TRUE)) stop("no sandwich")
      sqrt(sandwich::sandwich(fit)[treat.name, treat.name])
    },
    error = function(e) {
      sqrt(diag(stats::vcov(fit)))[[treat.name]]
    })
  } else {
    se_val <- sqrt(diag(stats::vcov(fit)))[[treat.name]]
  }
  se_val
}


#' Exponentiate an estimate for log-scale measures; pass through identity-scale
#'
#' @param estimate Numeric scalar.
#' @param measure  Character. One of `"log-HR"`, `"log-OR"`, `"log-RR"`,
#'   `"log-IRR"`, `"RD"`, `"IRD"`, `"MD"`.
#'
#' @return Numeric scalar on the natural (exponentiated or identity) scale.
#'
#' @noRd
back_transform_estimate <- function(estimate, measure) {
  if (grepl("^log-", measure)) {
    exp(estimate)
  } else {
    estimate
  }
}


#' Is this effect measure on the log scale?
#' @noRd
is_log_scale <- function(measure) {
  measure %in% c("log-HR", "log-OR", "log-RR", "log-IRR")
}


#' Map user-facing effect_measure to internal measure label
#' @noRd
effect_measure_to_label <- function(effect_measure) {
  switch(effect_measure,
    HR  = "log-HR",
    OR  = "log-OR",
    RR  = "log-RR",
    IRR = "log-IRR",
    RD  = "RD",
    IRD = "IRD",
    MD  = "MD",
    stop("Unknown effect_measure: ", effect_measure, call. = FALSE)
  )
}


#' Map user-facing effect_measure to consistency comparison direction
#'
#' Returns a function `f(estimate, threshold)` that evaluates `TRUE` when
#' the estimate exceeds the threshold in the direction consistent with harm.
#'
#' For log-scale measures: `estimate >= log(threshold)`
#' For identity-scale measures: `estimate >= threshold`
#'
#' @noRd
make_consistency_comparator <- function(effect_measure) {
  if (effect_measure %in% c("HR", "OR", "RR", "IRR")) {
    # Log-scale: compare log(estimate) >= log(threshold)
    function(estimate, threshold) estimate >= log(threshold)
  } else {
    # Identity scale (RD, IRD, MD): compare estimate >= threshold
    function(estimate, threshold) estimate >= threshold
  }
}


# =============================================================================
# PROPENSITY SCORE ESTIMATION MODULE
# =============================================================================

#' Estimate Propensity Scores
#'
#' Computes \eqn{P(W = 1 \mid X)} using the requested method, then
#' constructs both stabilized IPTW weights and the Bang & Robins (2005)
#' inverse propensity score (IPS) covariate.  The data frame is returned
#' with three new columns: \code{ps_hat} (raw PS), \code{sw} (stabilized
#' IPTW weights), and \code{ips_covar} (IPS covariate).
#'
#' @param data Data frame.
#' @param treat.name Character.  Name of binary treatment column (0/1).
#' @param confounders.name Character vector.  Covariate names for the
#'   propensity model.
#' @param method Character.  One of \code{"grf"} (default), \code{"lasso"},
#'   \code{"logistic"}, or \code{"none"}.
#' @param grf_forest Optional.  A fitted \code{causal_forest} object from
#'   which to extract \code{W.hat}.
#' @param seed Integer.  Random seed for GRF.
#' @param trim Numeric vector of length 2.  Quantile bounds for PS trimming.
#'   Default: \code{c(0.025, 0.975)}.
#'
#' @return A list with:
#'   \item{data}{Data frame with \code{ps_hat}, \code{sw}, and
#'     \code{ips_covar} columns appended.}
#'   \item{ps_hat}{Numeric vector of estimated propensity scores.}
#'   \item{sw}{Numeric vector of stabilized IPTW weights.}
#'   \item{ips_covar}{Numeric vector of inverse PS covariates
#'     (Bang & Robins 2005).}
#'   \item{method}{Character.  Method actually used.}
#'   \item{trimmed}{Integer.  Number of observations trimmed.}
#'
#' @references
#' Bang H, Robins JM (2005). "Doubly Robust Estimation in Missing Data
#' and Causal Inference Models." \emph{Biometrics} 61(4): 962--973.
#'
#' Hernan MA, Robins JM, Brumback B (2000). "Marginal Structural Models
#' and Causal Inference in Epidemiology." \emph{Epidemiology} 11(5):
#' 550--560.
#'
#' @examples
#' \dontrun{
#' df <- survival::gbsg
#' df$grade3 <- as.integer(df$grade == "3")
#' ps_result <- estimate_propensity_scores(
#'   data = df,
#'   treat.name = "hormon",
#'   confounders.name = c("age", "meno", "size", "grade3", "nodes",
#'                        "pgr", "er"),
#'   method = "grf"
#' )
#' summary(ps_result$ps_hat)
#' summary(ps_result$sw)
#' }
#'
#' @importFrom grf regression_forest
#' @export
estimate_propensity_scores <- function(
    data,
    treat.name,
    confounders.name,
    method     = c("grf", "lasso", "logistic", "none"),
    grf_forest = NULL,
    seed       = 8316951L,
    trim       = c(0.025, 0.975)
) {
  method <- match.arg(method)

  if (method == "none") {
    return(list(
      data      = data,
      ps_hat    = NULL,
      ips_covar = NULL,
      method    = "none",
      trimmed   = 0L
    ))
  }

  W <- data[[treat.name]]
  X <- as.matrix(data[, confounders.name, drop = FALSE])

  ps_hat <- switch(method,
    grf      = .ps_grf(X, W, grf_forest, seed),
    lasso    = .ps_lasso(X, W),
    logistic = .ps_logistic(X, W, confounders.name, treat.name, data)
  )

  # Trim to avoid extreme weights / positivity violations
  n_trimmed <- 0L
  if (!is.null(trim) && length(trim) == 2L) {
    lo <- trim[1]
    hi <- trim[2]
    too_low  <- ps_hat < lo
    too_high <- ps_hat > hi
    n_trimmed <- sum(too_low | too_high, na.rm = TRUE)
    ps_hat <- pmax(pmin(ps_hat, hi), lo)
  }

  # -----------------------------------------------------------------------
  # Compute both adjustment quantities:
  #
  # 1. Stabilized IPTW weights (Option A -- default)
  #    sw_i = P(W=1) / e(X_i)       if W_i = 1
  #         = P(W=0) / (1 - e(X_i)) if W_i = 0
  #    Used as: glm(Y ~ treat, weights = sw, ...)
  #    The coefficient IS the marginal causal effect.
  #
  # 2. Bang & Robins (2005) IPS covariate (Option B)
  #    ips_i = 1 / f(W_i | X_i; alpha_hat)
  #          = 1 / e(X_i)       if W_i = 1
  #          = 1 / (1 - e(X_i)) if W_i = 0
  #    Used as: glm(Y ~ treat + ips_covar, ...) + G-computation
  #    The treatment effect requires G-computation (Section 2.2,
  #    Bang & Robins 2005).
  # -----------------------------------------------------------------------

  p_treat <- mean(W, na.rm = TRUE)
  sw <- ifelse(W == 1,
               p_treat / ps_hat,
               (1 - p_treat) / (1 - ps_hat))

  ips_covar <- ifelse(W == 1, 1 / ps_hat, 1 / (1 - ps_hat))

  data$ps_hat    <- ps_hat
  data$sw        <- sw
  data$ips_covar <- ips_covar

  list(
    data      = data,
    ps_hat    = ps_hat,
    sw        = sw,
    ips_covar = ips_covar,
    method    = method,
    trimmed   = n_trimmed
  )
}


#' GRF-based propensity score estimation
#'
#' Extracts W.hat from an existing causal forest, or fits a new
#' regression_forest on the treatment indicator.
#'
#' @noRd
.ps_grf <- function(X, W, grf_forest = NULL, seed = 8316951L) {

  # If a forest is already available, extract W.hat directly
  if (!is.null(grf_forest) && !is.null(grf_forest$W.hat)) {
    return(as.numeric(grf_forest$W.hat))
  }

  # Otherwise, fit a regression forest on W
  rf_w <- grf::regression_forest(X, W, seed = seed,
                                num.threads = .fs_grf_num_threads())
  ps <- predict(rf_w)$predictions
  as.numeric(ps)
}


#' LASSO logistic propensity score estimation
#'
#' Uses `glmnet` with `family = "binomial"` and `lambda.min` from CV.
#'
#' @noRd
.ps_lasso <- function(X, W) {
  if (!requireNamespace("glmnet", quietly = TRUE)) {
    stop("Package 'glmnet' required for ps_method = 'lasso'.", call. = FALSE)
  }

  cv_fit <- glmnet::cv.glmnet(
    x      = X,
    y      = W,
    family  = "binomial",
    alpha   = 1,     # LASSO
    nfolds  = 5
  )
  ps <- as.numeric(stats::predict(
    cv_fit, newx = X, s = "lambda.min", type = "response"
  ))
  ps
}


#' Logistic regression propensity score estimation
#'
#' Simple logistic regression with main effects only.
#'
#' @noRd
.ps_logistic <- function(X, W, confounders.name, treat.name, data) {
  fmla <- stats::as.formula(
    paste0(treat.name, " ~ ", paste(confounders.name, collapse = " + "))
  )
  fit <- stats::glm(fmla, data = data, family = stats::binomial(link = "logit"))
  ps <- stats::predict(fit, type = "response")
  as.numeric(ps)
}

Try the forestsearch package in your browser

Any scripts or data that you put into this service are public.

forestsearch documentation built on Nov. 15, 2026, 9:06 a.m.