% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brier_binreg.R
\name{brier_binreg}
\alias{brier_binreg}
\title{Cross-validated Brier score for competing risks, RMST and RMTL regression
using stratified leave-fold-out fits (\code{binregStrata})}
\usage{
brier_binreg(
  formula,
  data,
  time,
  fold = 5,
  rhs = NULL,
  rhs0 = ~+1,
  cens.model = ~+1,
  brier.cens.model = ~+1,
  brier.args = list(),
  cv.split.index = NULL,
  ...
)
}
\arguments{
\item{formula}{Two-sided formula of the form
\code{Event(time, status) ~ covariates + cluster(id)} or
\code{Event(time, status, cause) ~ covariates + cluster(id)}.
The \code{cluster(id)} term is optional; if absent an internal
identifier \code{id__} is added automatically assuming independent
observations.}

\item{data}{A \code{data.frame} containing all variables in
\code{formula} and \code{rhs}.}

\item{time}{Scalar or numeric vector of evaluation time points. When a
vector is supplied the function loops over time points reusing the same
fold structure and returns a named list of \code{binregCV} objects with
class \code{"binregCV_list"}.}

\item{fold}{Integer. Number of cross-validation folds / strata
(default 5).}

\item{rhs}{Named list of one-sided formulas specifying candidate models,
e.g. \code{list(small = ~Z1, full = ~Z1 + Z2)}. If \code{NULL} (default),
the right-hand side of \code{formula} (minus any \code{cluster()} term)
is used as a single candidate named \code{"model1"}.}

\item{rhs0}{One-sided formula for the null (intercept-only) model
(default \code{~+1}).}

\item{cens.model}{Censoring model passed to \code{binregStrata} for the
CV fold fits (default \code{~+1}). Since folds are handled internally
by \code{binregStrata}'s \code{strata}/\code{cv.fold} mechanism, this
does \emph{not} need to include \code{strata(fold)}.}

\item{brier.cens.model}{Censoring model passed to \code{resmeanIPCW} when
computing Brier scores. Default \code{~+1} gives Kaplan-Meier weights.
Supply a stratified model, e.g. \code{~strata(Z1, Z2)}, for
covariate-adjusted IPCW weights.}

\item{brier.args}{Named list of additional arguments forwarded to every
\code{resmeanIPCW} call (beyond \code{formula}, \code{data},
\code{time}, \code{Ydirect}, \code{cens.model}, and \code{model} which
are set internally). Typically empty.}

\item{cv.split.index}{List from \code{folds(n, fold)} or a vector of fold
indices (1:fold) for each observation, to fix the cross-validation
folds. \code{NULL} (default) generates folds internally via
\code{folds(n, fold)}.}

\item{\dots}{Additional arguments passed to every \code{binreg} /
\code{binregStrata} call, e.g. \code{cause = 2}, \code{outcome = "rmst"},
or \code{offset}.}
}
\value{
An object of class \code{"binregCV"} (single time point) or
  \code{"binregCV_list"} (multiple time points), with the following
  structure:
\describe{
  \item{\code{null}}{List with \code{coef}, \code{se}, and \code{iid} for
    the null model. \code{coef} and \code{se} are named vectors with
    entries \code{bbrier} (apparent, log scale) and \code{bbrierCV}
    (cross-validated, log scale). \code{iid} contains the
    influence-function matrix for \code{bbrierCV} with delta-method
    correction for the stratified CV prediction step and the log
    transform.}
  \item{\code{models}}{Named list, one element per entry in \code{rhs}.
    Each element contains \code{coef} (\code{brier}, \code{brierCV}, log
    scale), \code{se}, \code{dcoef} (differences from null: log Brier
    ratios), \code{sed}, and \code{iid} (influence-function matrix for
    \code{brierCV}, log scale, with CV delta-method correction).}
  \item{\code{iid_mat}}{Matrix of dimension \eqn{n \times (1 +
    \code{length(rhs)})} with columns \code{null} and one per entry of
    \code{rhs}, each the log-scale CV Brier influence function for the
    corresponding model. Used by \code{\link{estimate.binregCV}} for joint
    inference.}
  \item{\code{cv.split.index}}{List of fold index vectors used.}
  \item{\code{rhs}, \code{rhs0}}{Processed candidate and null formulas
    (cluster terms removed).}
  \item{\code{model}}{Link function read from the \code{binreg} fit:
    \code{"logit"}, \code{"exp"}, or \code{"lin"}.}
  \item{\code{call}, \code{time}, \code{fold}, \code{cens.model},
    \code{brier.cens.model}}{Call and settings for printing and
    downstream use.}
}
}
\description{
Fits candidate models via \code{\link[mets]{binregStrata}} with
\code{cv.fold = TRUE} and evaluates each using apparent (in-sample) and
\emph{k}-fold cross-validated IPCW Brier scores relative to a null model.
Supports all outcome types available in \code{binreg}/\code{binregStrata}:
cause-specific cumulative incidence (competing risks), restricted mean
survival time (RMST), and restricted mean time lost (RMTL).
}
\details{
Cross-validation is delegated directly to
\code{\link[mets]{binregStrata}} via its \code{strata} and
\code{cv.fold = TRUE} arguments: each stratum (fold) gets its own
coefficient vector \eqn{\beta_s}, estimated on the complement of that
fold. Out-of-fold predictions are obtained by routing each observation to
the \eqn{\beta_s} corresponding to its own fold, which was trained on the
other folds.

The fold membership is stored in an internal \code{fold} column (1-based)
in \code{data} and passed to \code{binregStrata} as a 0-based
\code{strata} vector. Censoring weights for the underlying competing-risks
model are estimated according to \code{cens.model} as usual; since strata
already define the folds, \code{cens.model} need not include
\code{strata(fold)} explicitly.

Brier scores are computed on the \strong{linear scale} via
\code{resmeanIPCW(..., model = "lin")} and then log-transformed using
\code{lava::estimate(..., f = log)} with the delta method. All stored
coefficients, standard errors, and influence functions are therefore on
the \strong{log scale}. Use \code{summary(fit, transform = exp)} or
\code{estimate(fit, f = exp)} to back-transform to the original Brier
scale.

The delta-method correction for the cross-validated influence function
accounts for the block structure of \code{binregStrata}'s influence
function (\eqn{n_{id} \times (\code{nstrata} \times p)}, one
\eqn{p}-column block per stratum). For each stratum \eqn{s}, only
observations belonging to fold \eqn{s} have a non-zero derivative of
their out-of-fold prediction with respect to \eqn{\beta_s}, since
\eqn{\beta_s} is exactly the coefficient used to predict fold \eqn{s}.
The full gradient is therefore block-sparse, with one non-zero
\eqn{p}-length block per stratum, and the correction reduces to a single
matrix product against \code{iid(outff_fit)}.

Left-truncation (delayed entry) is not supported and will raise an error.
Specifically, \code{Event(entry, time, status)} is rejected; use
\code{Event(time, status)} or \code{Event(time, status, cause)}.
}
\section{Outcome types}{

The function supports all outcome types provided by \code{binreg}/
\code{binregStrata}:
\describe{
  \item{Competing risks CIF}{Default; use
    \code{Event(time, status, cause)} and pass \code{cause} via \code{...}.
    The Brier score measures squared error for the cause-specific CIF.}
  \item{RMST}{Pass \code{outcome = "rmst"} via \code{...}. The Brier score
    measures squared error for the restricted mean survival time up to
    \code{time}.}
  \item{RMTL}{Pass \code{outcome = "rmtl"} via \code{...}. The Brier score
    measures squared error for the restricted mean time lost.}
}
}

\section{Scale and inference}{

All output is on the log scale. To obtain Brier scores on the original
scale with confidence intervals, use:
\preformatted{
  summary(fit, transform = exp)
  estimate(fit, f = exp)
}
Differences on the log scale correspond to log Brier ratios; exponentiate
to obtain Brier ratios. For absolute differences on the original scale,
compute contrasts after \code{estimate(fit, f = exp)}.
}

\examples{
\dontrun{
library(mets)
data(bmt)
bmt$id <- seq_len(nrow(bmt))

## --- competing risks CIF/Survival (default) ---
fit <- brier_binreg(
  Event(time, cause) ~ tcell + platelet + age + cluster(id),
  data = bmt, time = 50,
  rhs = list(small = ~age, full = ~tcell + platelet + age)
)
summary(fit)                        ## log scale
summary(fit, transform = exp)       ## Brier scale

## multiple time points
fitm <- brier_binreg(
  Event(time, cause) ~ tcell + platelet + age + cluster(id),
  data = bmt, time = c(50, 60),
  rhs = list(small = ~age, full = ~tcell + platelet + age)
)
summary(fitm, transform = exp)

## joint inference across models via lava::estimate
e <- estimate(fitm)
e
estimate(e, f = exp)               ## back-transform

## stratified IPCW weights for Brier score
fit_strat <- brier_binreg(
  Event(time, cause) ~ tcell + platelet + age + cluster(id),
  data = bmt, time = 50,
  rhs = list(small = ~age, full = ~tcell + platelet + age),
  brier.cens.model = ~strata(tcell)
)

## --- RMST --- survival case only
fit_rmst <- brier_binreg(
  Event(time, cause) ~ tcell + platelet + age + cluster(id),
  data = bmt, time = 50, cause = 1:2,
  rhs    = list(small = ~age, full = ~tcell + platelet + age),
  outcome = "rmst"
)
summary(fit_rmst, transform = exp)

## --- RMTL --- competing risks or survival (RMTL)
fit_rmtl <- brier_binreg(
  Event(time, cause) ~ tcell + platelet + age + cluster(id),
  data = bmt, time = 50,
  rhs    = list(small = ~age, full = ~tcell + platelet + age),
  outcome = "rmtl"
)
summary(fit_rmtl, transform = exp)
}
}
\seealso{
\code{\link{estimate.binregCV}} for joint inference across models and
  time points;
  \code{\link{summary.binregCV}} and \code{\link{print.summary_binregCV_multi}}
  for formatted output;
  \code{\link[mets]{binregStrata}} for the underlying stratified
  regression model;
  \code{\link[mets]{resmeanIPCW}} for IPCW mean estimation;
  \code{\link[lava]{estimate}} for delta-method inference.
}
