% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brier_binreg.R
\name{binregStrata}
\alias{binregStrata}
\title{Stratified Binomial Regression with cross-validation option}
\usage{
binregStrata(
  formula,
  data,
  cause = 1,
  time = NULL,
  beta = NULL,
  type = c("II", "I"),
  offset = NULL,
  weights = NULL,
  cens.weights = NULL,
  cens.model = ~+1,
  se = TRUE,
  kaplan.meier = TRUE,
  cens.code = 0,
  no.opt = FALSE,
  method = "nr",
  augmentation = NULL,
  outcome = c("cif", "rmst", "rmtl"),
  model = c("default", "logit", "exp", "lin"),
  Ydirect = NULL,
  strata = NULL,
  cv.fold = FALSE,
  low.memory = FALSE,
  ...
)
}
\arguments{
\item{formula}{A formula with a \code{\link[survival]{Surv}} or
\code{Event} object on the left-hand side, and covariates, optional
\code{cluster()}, \code{strata()}, \code{offset()}, and \code{weights()}
terms on the right-hand side.}

\item{data}{A \code{data.frame} containing the variables in \code{formula}.}

\item{cause}{Value(s) of the status variable that identify the event of
interest (cause 1 by default).}

\item{time}{The fixed time-point at which the CIF, RMST, or RMTL is
evaluated. Required.}

\item{beta}{Optional starting values for the regression coefficients.
Either a vector (recycled across strata) or a matrix with one row per
stratum.}

\item{type}{Character; either \code{"II"} (default) or \code{"I"}. When
\code{"II"}, an additional augmentation term and an extra component of
the censoring-related iid decomposition are computed.}

\item{offset}{Optional offset term; can also be specified via the formula.}

\item{weights}{Optional case weights; can also be specified via the
formula.}

\item{cens.weights}{Optional pre-computed inverse probability of censoring
weights. If supplied, the internal censoring model fit is skipped and
\code{se} is forced to \code{FALSE}.}

\item{cens.model}{A formula for the censoring model (right-hand side only,
fitted via \code{\link{phreg}}). Defaults to the Kaplan-Meier
(\code{~+1}).}

\item{se}{Logical. If \code{TRUE} (default), standard errors are computed,
including the contribution from estimating the censoring distribution.}

\item{kaplan.meier}{Logical. If \code{TRUE} (default), uses the
Kaplan-Meier estimator for censoring weights when the censoring model has
no covariates; otherwise a Cox-type estimator is used internally when
covariates are present.}

\item{cens.code}{The code in the status variable denoting censoring
(default 0).}

\item{no.opt}{Logical. If \code{TRUE}, no optimization is performed and the
object is evaluated at the supplied \code{beta}.}

\item{method}{Optimization method. Currently only \code{"nr"} (Newton-Raphson
via \code{lava::NR}) is supported.}

\item{augmentation}{Optional augmentation term(s) added to the score
equations, either a vector (recycled across strata) or a matrix with one
row per stratum.}

\item{outcome}{Character; the outcome scale to model: \code{"cif"}
(default), \code{"rmst"}, or \code{"rmtl"}.}

\item{model}{Character; the link function: \code{"default"} (chooses
\code{"logit"} for CIF and \code{"exp"} for RMST/RMTL), \code{"logit"},
\code{"exp"}, or \code{"lin"}.}

\item{Ydirect}{Optional, directly supplied response vector, overriding the
response otherwise constructed from \code{outcome}.}

\item{strata}{Optional numeric vector defining strata, used when strata are
not specified via \code{strata()} in the formula.}

\item{cv.fold}{Logical. If \code{TRUE}, for each stratum \code{s} the
regression coefficients are estimated using all observations \emph{not}
in stratum \code{s} (a cross-validation-style fit), rather than the
observations within stratum \code{s} (the default, \code{FALSE}).}

\item{low.memory}{Logical. If \code{TRUE} only saves key quanties, coef, var, iid and some design structures.}

\item{...}{Additional arguments, currently passed as optimizer
\code{control} settings (e.g. \code{tol}, \code{stepsize}) to the
Newton-Raphson routine.}
}
\value{
An object of class \code{c("binregStrata","binreg")}, a list with
  components including:
  \item{coef}{Estimated regression coefficients (stacked across strata).}
  \item{iid}{Subject-level iid decomposition of the coefficients, adjusted
    for censoring estimation when \code{se = TRUE}.}
  \item{var, robvar}{Robust (sandwich) variance-covariance matrix.}
  \item{se.coef, se.robust}{Standard errors derived from \code{var}.}
  \item{hessian, ihessian}{Per-stratum Hessians and their (pseudo-)inverses.}
  \item{coef_list}{Per-stratum coefficient vectors.}
  \item{time, cause, cens.code, model, outcome}{Echoed arguments.}
  \item{Y, Yipcw, IPCW}{The constructed response, IPCW-weighted response,
    and IPCW weights.}
  \item{cens.weights, formC, cens.strata, cens.nstrata}{Censoring model
    weights and related information (when internally estimated).}
  \item{nstrata, strata_orig, strata_call, cv.fold}{Stratification
    information and whether the cross-validation fold scheme was used.}
  \item{n, nevent, ncluster, nid, id, name.id}{Sample size and
    identifier information.}
  \item{call, design}{The matched call and the design object.}
}
\description{
Fits a stratified binomial regression model for the cumulative incidence
function (CIF), restricted mean survival time (RMST), or restricted mean
time lost (RMTL), using inverse probability of censoring weighting (IPCW).
Each stratum may either be fit on its own observations or, when
\code{cv.fold = TRUE}, on the complement of its observations (i.e. a
leave-one-stratum-out / cross-validation style fit). Standard errors are
computed via an iid decomposition that accounts for the estimation of the
censoring distribution.
}
\details{
When \code{cv.fold = FALSE} (the standard case), the coefficients for
stratum \code{s} are estimated using only observations with
\code{strata == s}. When \code{cv.fold = TRUE}, the coefficients for
stratum \code{s} are instead estimated using observations with
\code{strata != s}, i.e. the complement; this also affects the
construction of the censoring-related iid terms (\code{MGCiid}) and the
per-stratum subject-level influence functions used for the robust
variance.

Censoring weights are computed via a Cox model (\code{\link{phreg}}) on
\code{cens.model}, evaluated at \code{pmin(exit, time)}, unless
\code{cens.weights} is supplied directly. When \code{se = TRUE}, the
additional variability coming from the estimation of the censoring
distribution is incorporated into the standard errors via a martingale-type
iid decomposition (\code{MGCiid}).
}
\examples{
\dontrun{
library(mets)
data(bmt)
out <- binregStrata(Event(time, cause) ~ tcell + strata(platelet),
                     data = bmt, cause = 1, time = 50)
summary(out)
}

}
\seealso{
\code{\link{phreg}}, \code{\link{binreg}}
}
