% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ratio.regression.R
\name{binregRatio}
\alias{binregRatio}
\alias{rmtlRatio}
\title{Percentage of Years Lost Due to a Cause Regression}
\usage{
binregRatio(
  formula,
  data,
  cause = 1,
  time = NULL,
  beta = NULL,
  type = c("III", "II", "I"),
  offset = NULL,
  weights = NULL,
  cens.weights = NULL,
  cens.model = ~+1,
  se = TRUE,
  relative.to.causes = NULL,
  kaplan.meier = TRUE,
  cens.code = 0,
  no.opt = FALSE,
  method = "nr",
  augmentation = NULL,
  outcome = c("rmtl", "cif"),
  model = c("logit", "exp", "lin"),
  Ydirect = NULL,
  ...
)
}
\arguments{
\item{formula}{Formula with an outcome (see \code{coxph}). The first covariate on the RHS 
is typically the treatment or group indicator. Can include \code{cluster(id)}.}

\item{data}{Data frame containing the variables.}

\item{cause}{Numeric code of the cause of interest.}

\item{time}{Time point \eqn{t} for the analysis. Required.}

\item{beta}{Starting values for optimization (default NULL, uses zeros).}

\item{type}{Type of estimator: \code{"I"} (IPCW only), \code{"II"} (IPCW + augmentation), 
or \code{"III"} (IPCW + complex augmentation). Default is \code{"III"}.}

\item{offset}{Offsets for the partial likelihood.}

\item{weights}{Weights for the score equations.}

\item{cens.weights}{External censoring weights (if provided, \code{cens.model} is ignored).}

\item{cens.model}{Formula for the censoring model (default \code{~+1}, stratified KM). 
Can include \code{strata()} for stratified censoring.}

\item{se}{Logical; if TRUE, computes standard errors based on IPCW (default TRUE).}

\item{relative.to.causes}{If not NULL, compares the RMTL of the specified \code{cause} 
to the RMTL of the causes in this vector (the denominator becomes the sum of these causes).}

\item{kaplan.meier}{Logical; if TRUE, uses Kaplan-Meier for IPCW weights; if FALSE, 
uses \eqn{\exp(-\text{cumulative hazard})}.}

\item{cens.code}{Censoring code (default 0).}

\item{no.opt}{Logical; if TRUE, skips optimization and uses \code{beta} directly.}

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

\item{augmentation}{Initial augmentation term (used for type "II" and "III").}

\item{outcome}{Outcome type: \code{"rmtl"} (years lost) or \code{"cif"} (cumulative incidence).}

\item{model}{Link function: \code{"logit"} (default), \code{"exp"}, or \code{"lin"}.}

\item{Ydirect}{Matrix with two columns (numerator, denominator) to use directly as the response.}

\item{...}{Additional arguments passed to lower-level functions.}
}
\value{
An object of class \code{"binreg"} and \code{"ratio"} containing:
  \item{coef}{Coefficient estimates.}
  \item{se.coef}{Standard errors.}
  \item{var}{Variance-covariance matrix.}
  \item{iid}{Influence function decomposition (with censoring adjustment).}
  \item{iidI}{Influence function without censoring adjustment.}
  \item{naive.var}{Variance assuming known censoring.}
  \item{time}{Time point used.}
  \item{cause}{Cause of interest.}
  \item{Causes}{Set of causes considered in the denominator.}
  \item{Yipcw}{IPCW-adjusted response matrix.}
  \item{coefI, varI}{Results from the initial (type "I") fit.}
  \item{augmentation}{Final augmentation term used.}
}
\description{
Estimates the percentage of the restricted mean time lost (RMTL) that is attributable 
to a specific cause and models how covariates affect this percentage using IPCW regression.
}
\details{
Let the total years lost be \eqn{Y = t - \min(T, t)} and the years lost due to cause 1 be 
\eqn{Y_1 = I(\epsilon=1) (t - \min(T, t))}. The function models the ratio:
\deqn{ \text{logit}\left( \frac{E(Y_1 | X)}{E(Y | X)} \right) = X^T \beta }

Estimation is based on a binomial regression IPCW response estimating equation:
\deqn{ X \left( \Delta^{\text{ipcw}}(t) \left( Y \cdot \text{expit}(X^T \beta) - Y_1 \right) \right) = 0 }
where \eqn{\Delta^{\text{ipcw}}(t) = I(\min(t,T) < C) / G_c(\min(t,T))} is the IPCW adjustment.

The function supports three types of estimators:
\itemize{
  \item \code{"I"}: Classical outcome IPCW regression (no augmentation).
  \item \code{"II"}: Adds a censoring augmentation term \eqn{X \int E(Z(t)| T>s)/G_c(s) d \hat M_c} 
    to improve efficiency (requires an initial estimate of \eqn{\beta}).
  \item \code{"III"}: Adds a more complex augmentation term separating the expectations of 
    \eqn{Y} and \eqn{Y_1} for further efficiency gains.
}

The variance is based on the squared influence functions (IID). A "naive" variance 
(assuming known censoring) is also provided for comparison.
}
\examples{
data(bmt); bmt$time <- bmt$time+runif(408)*0.001

rmtl30 <- rmstIPCW(Event(time,cause!=0)~platelet+tcell+age, bmt, time=30, cause=1, outcome="rmtl")
rmtl301 <- rmstIPCW(Event(time,cause)~platelet+tcell+age, bmt, time=30, cause=1)
rmtl302 <- rmstIPCW(Event(time,cause)~platelet+tcell+age, bmt, time=30, cause=2)

estimate(rmtl30)
estimate(rmtl301)
estimate(rmtl302)

## Percentage of total RMTL due to cause 1
rmtlratioI <- rmtlRatio(Event(time,cause)~platelet+tcell+age, bmt, time=30, cause=1)
summary(rmtlratioI)

newdata <- data.frame(platelet=1, tcell=1, age=1)
pp <- predict(rmtlratioI, newdata)
pp

## Percentage of total cumulative incidence due to cause 1
cifratio <- binregRatio(Event(time,cause)~platelet+tcell+age, bmt, time=30, cause=1, model="cif")
summary(cifratio)
pp <- predict(cifratio, newdata)
pp
}
\references{
Scheike, T. & Tanaka, S. (2025). Restricted mean time lost ratio regression: Percentage of restricted mean time lost due to specific cause. WIP.
}
\seealso{
\code{\link{resmeanIPCW}}, \code{\link{binreg}}
}
\author{
Thomas Scheike
}
