% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/binomial.regression.R
\name{binreg}
\alias{binreg}
\alias{logitIPCW}
\alias{binregt}
\title{Binomial Regression for Censored Competing Risks Data}
\usage{
binreg(
  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,
  ...
)
}
\arguments{
\item{formula}{A formula object specifying the outcome and covariates. 
The outcome must be an \code{Event} object (\code{Event(time, cause)}).}

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

\item{cause}{Numeric vector or scalar indicating the cause of interest for the competing risks.}

\item{time}{Numeric scalar indicating the time point of interest for the cumulative incidence.}

\item{beta}{Optional numeric vector of starting values for the coefficients. Defaults to zeros.}

\item{type}{Character string. Either \code{"I"} (classic binomial regression) or \code{"II"} (adds augmentation term).}

\item{offset}{Optional numeric vector of offsets for the linear predictor.}

\item{weights}{Optional numeric vector of weights for the score equations.}

\item{cens.weights}{Optional numeric vector of pre-calculated censoring weights. If NULL, they are estimated internally.}

\item{cens.model}{A formula specifying the censoring model. Defaults to \code{~+1}. Can include strata (e.g., \code{~strata(group)}).}

\item{se}{Logical. If TRUE, computes standard errors based on IPCW influence functions.}

\item{kaplan.meier}{Logical. If TRUE, uses Kaplan-Meier estimator for IPCW weights; otherwise uses exponential baseline.}

\item{cens.code}{Numeric code representing censored observations in the status variable. Defaults to 0.}

\item{no.opt}{Logical. If TRUE, optimization is skipped and starting values are used.}

\item{method}{Character string. Optimization method: \code{"nr"} (Newton-Raphson) or \code{"nlm"}.}

\item{augmentation}{Optional numeric vector for additional augmentation terms.}

\item{outcome}{Character string. Outcome type: \code{"cif"} (Cumulative Incidence Function), \code{"rmst"} (Restricted Mean Survival Time), or \code{"rmtl"} (Restricted Mean Time Lost).}

\item{model}{Character string. Link function: \code{"default"} (auto-selects based on outcome), \code{"logit"}, \code{"exp"}, or \code{"lin"} (identity).}

\item{Ydirect}{Optional numeric vector. If provided, this outcome is used instead of constructing one from \code{outcome}. Useful for custom IPCW adjustments.}

\item{...}{Additional arguments passed to lower-level optimization functions.}
}
\value{
An object of class \code{"binreg"} containing coefficients, variance-covariance matrix, 
  influence functions (\code{iid}), and model details.
}
\description{
Fits a binomial regression model for a specific time point in the presence of 
right-censored data and competing risks. This function implements the 
Inverse Probability of Censoring Weighted (IPCW) estimating equation approach.
}
\details{
The model estimates the probability:
\deqn{P(T \leq t, \epsilon=1 | X ) = \text{expit}( X^T \beta) }

Based on binomial regresion IPCW response estimating equation: 
\deqn{ X ( \Delta^{ipcw}(t) I(T \leq t, \epsilon=1 ) - expit( X^T beta)) = 0 }
where \deqn{\Delta^{ipcw}(t) = I((min(t,T)< C)/G_c(min(t,T)-)} is 
IPCW adjustment of the response \deqn{Y(t)= I(T \leq t, \epsilon=1 )}.  
Two types of estimators are available:
\itemize{
  \item \code{type="I"}: Solves the standard IPCW estimating equation.
  \item \code{type="II"}: Adds a censoring augmentation term for efficiency gains, 
  solving \deqn{X \int E(Y(t)| T>s)/G_c(s) d \hat M_c}.
}

Alternatively, \code{logitIPCW} performs a standard logistic regression with 
IPCW weights applied directly to the likelihood. Thus solving 
\deqn{ X  I(min(T_i,t) < G_i)/G_c(min(T_i ,t)) ( I(T \leq t, \epsilon=1 ) - expit( X^T beta)) = 0 } 
a standard logistic regression with IPCW weights.

The variance estimation is based on squared influence functions, with options 
for naive variance (assuming known censoring) and robust variance (accounting 
for censoring model estimation).

Censoring model may depend on strata (cens.model=~strata(gX)).
}
\section{References}{

\itemize{
  \item Blanche PF, Holt A, Scheike T (2022). "On logistic regression with right censored data, with or without competing risks, and its use for estimating treatment effects." \emph{Lifetime data analysis}, 29, 441–482.
  \item Scheike TH, Zhang MJ, Gerds TA (2008). "Predicting cumulative incidence probability by direct binomial regression." \emph{Biometrika}, 95(1), 205–220.
}
}

\section{Outcome definition}{

The observed outcome \eqn{Y_i} constructed from \code{outcome} depends on whether
competing risks are present. Competing risks are detected automatically: the data are
considered to have competing risks when causes other than those specified in \code{cause}
are observed (i.e. \code{any(!(Causes \%in\% cause))}, where \code{Causes} are all
non-censoring event codes found in the data).

\strong{No competing risks} (all observed events belong to \code{cause}):
\itemize{
  \item \code{"cif"}: \eqn{Y_i = I(T_i \leq t, \epsilon_i = 1)}. Cumulative incidence.
  \item \code{"rmst"}: \eqn{Y_i = \min(T_i, t)}. Restricted mean survival time.
  \item \code{"rmtl"}: \eqn{Y_i = t - \min(T_i, t)}. Restricted mean time lost.
}

\strong{Competing risks} (causes beyond \code{cause} are observed in the data):
\itemize{
  \item \code{"cif"}: \eqn{Y_i = I(T_i \leq t, \epsilon_i \in \code{cause})}. Cumulative
    incidence for the cause(s) of interest.
  \item \code{"rmst"} or \code{"rmtl"}: \eqn{Y_i = I(\epsilon_i \in \code{cause})(t - \min(T_i, t))}.
    Cause-specific years lost, accumulated only for subjects who experience an event in \code{cause}.
}

The default link function (\code{model = "default"}) is \code{"logit"} for \code{"cif"} and
\code{"exp"} for \code{"rmst"} and \code{"rmtl"}.
If \code{Ydirect} is supplied, outcome construction is bypassed entirely.
}

\examples{
data(bmt); bmt$time <- bmt$time+runif(408)*0.001
# logistic regresion with IPCW binomial regression 
out <- binreg(Event(time,cause)~tcell+platelet,bmt,time=50)
summary(out)
head(iid(out))

predict(out,data.frame(tcell=c(0,1),platelet=c(1,1)),se=TRUE)

outs <- binreg(Event(time,cause)~tcell+platelet,bmt,time=50,cens.model=~strata(tcell,platelet))
summary(outs)

## glm with IPCW weights 
outl <- logitIPCW(Event(time,cause)~tcell+platelet,bmt,time=50)
summary(outl)

##########################################
### risk-ratio of different causes #######
##########################################
data(bmt)
bmt$id <- 1:nrow(bmt)
bmt$status <- bmt$cause
bmt$strata <- 1
bmtdob <- bmt
bmtdob$strata <-2
bmtdob <- dtransform(bmtdob,status=1,cause==2)
bmtdob <- dtransform(bmtdob,status=2,cause==1)
###
bmtdob <- rbind(bmt,bmtdob)
dtable(bmtdob,cause+status~strata)

cif1 <- cif(Event(time,cause)~+1,bmt,cause=1)
cif2 <- cif(Event(time,cause)~+1,bmt,cause=2)
plot(cif1)
plot(cif2,add=TRUE,col=2)

cifs1 <- binreg(Event(time,cause)~tcell+platelet+age,bmt,cause=1,time=50)
cifs2 <- binreg(Event(time,cause)~tcell+platelet+age,bmt,cause=2,time=50)
summary(cifs1)
summary(cifs2)

cifdob <- binreg(Event(time,status)~-1+factor(strata)+
	 tcell*factor(strata)+platelet*factor(strata)+age*factor(strata)
	 +cluster(id),bmtdob,cause=1,time=50,cens.model=~strata(strata))
summary(cifdob)
head(iid(cifdob)) 

newdata <- data.frame(tcell=1,platelet=1,age=0,strata=1:2,id=1)
riskratio <- function(p) {
  cifdob$coef <- p
  p <- predict(cifdob,newdata,se=0)
  return(p[1]/p[2])
}
lava::estimate(cifdob,f=riskratio)

predict(cifdob,newdata)
(p1 <- predict(cifs1,newdata))
(p2 <- predict(cifs2,newdata))
p1[1,1]/p2[1,1]

}
\author{
Thomas Scheike
}
