% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simKHCE.R
\name{simKHCE}
\alias{simKHCE}
\title{Simulate a kidney disease \code{hce} dataset}
\usage{
simKHCE(
  n,
  CM_A,
  CM_P = -4,
  n0 = n,
  TTE_A = 1000,
  TTE_P = TTE_A,
  fixedfy = 2,
  Emin = 20,
  Emax = 100,
  sigma = NULL,
  Sigma = 3,
  m = 10,
  theta = -0.4605,
  phi = 0,
  two_meas = c("no", "base", "postbase", "both"),
  df_sigma = Inf
)
}
\arguments{
\item{n}{sample size in the active treatment group.}

\item{CM_A}{annualized eGFR slope in the active group.}

\item{CM_P}{annualized eGFR slope in the control group.}

\item{n0}{sample size in the control treatment group.}

\item{TTE_A}{event rate per year in the active group for KFRT.}

\item{TTE_P}{event rate per year in the placebo group for KFRT.}

\item{fixedfy}{length of follow-up in years.}

\item{Emin}{lower limit of eGFR at baseline.}

\item{Emax}{upper limit of eGFR at baseline.}

\item{sigma}{within-patient standard deviation.}

\item{Sigma}{between-patient standard deviation.}

\item{m}{number of equidistant visits.}

\item{theta}{coefficient of dependence of eGFR values and the risk of KFRT.}

\item{phi}{coefficient of proportionality (between 0 and 1) of the treatment effect. The case of 0 corresponds to the uniform treatment effect.}

\item{two_meas}{determines whether to use duplicate measurements at baseline and/or at \code{fixedfy}. The default is to use a single measurement.}

\item{df_sigma}{degrees of freedom for the measurement error distribution. The default \code{Inf} gives normal measurement errors; must be more than 2.}
}
\description{
Simulate a kidney disease \code{hce} dataset, capturing eGFR (Estimated Glomerular Filtration Rate) progression over time, along with
a competing and dependent terminal event: KFRT (Kidney Failure Replacement Therapy)
}
\details{
The default setting is \code{TTE_A = TTE_P} because, conditional on eGFR level,
the treatment effect does not influence the event rate of KFRT. In this model,
the effect of treatment on KFRT operates entirely through its impact on eGFR decline.

Let \code{CM_A} and \code{CM_P} be denoted by \eqn{\beta_A} and \eqn{\beta_P}, respectively.
Let \code{TTE_A} and \code{TTE_P} be denoted by \eqn{\lambda_A} and \eqn{\lambda_P}, respectively.
Let \code{theta} be denoted by \eqn{\theta}, \code{phi} by \eqn{\phi}, \code{sigma} by \eqn{\sigma},
\code{Sigma} by \eqn{\Sigma}, and \code{df_sigma} by \eqn{\nu}.

The parameters \code{TTE_A} and \code{theta} are chosen so that when GFR is 15, the event rate
is 1 per patient per year, and when GFR is 25, the event rate is 0.01 per patient per year. These
parameter values are obtained by solving
\deqn{
\lambda_g \exp(\theta \cdot \mathrm{GFR}) = \mathrm{rate}
}
for the group-specific baseline rate \eqn{\lambda_g} and \eqn{\theta}. When the observed eGFR is above 30,
the event rate is set to a very low value (\code{10e-7}), while when the observed eGFR is below or equal to 7,
the event rate is set to a very high value (\code{10e5}). This ensures that patients with observed low eGFR values
always experience KFRT, while those with high eGFR values do not.

By default, the within-patient standard deviation, \code{sigma}, is set to \code{NULL}. When left as \code{NULL}, \code{sigma}
is calculated as
\deqn{
\sigma_{ij} = \sqrt{0.67 \cdot \mu_{ij}},
}
where \eqn{\mu_{ij}} denotes the predicted eGFR for patient \eqn{i} at visit \eqn{j}. This yields
time-dependent measurement variability, with lower predicted eGFR values corresponding to lower variability.
In the implementation, to prevent the variance from becoming negative or too small, the quantity
\eqn{0.67 \cdot \mu_{ij}} is truncated below at \code{0.1} before taking the square root.

When \code{df_sigma = Inf} (the default), measurement errors are normally distributed:
\deqn{
\varepsilon_{ij} \sim N(0, \sigma_{ij}^2).
}
When \code{df_sigma} is finite and greater than 2, measurement errors follow a Student t distribution
with heavier tails:
\deqn{
\varepsilon_{ij} = \sigma_{ij}\sqrt{\frac{\nu - 2}{\nu}} T_{\nu},
}
where \eqn{\nu =} \code{df_sigma} and \eqn{T_{\nu}} is a standard t random variable with \eqn{\nu}
degrees of freedom. This scaling preserves the same time-dependent standard deviation defined by \code{sigma},
so that
\deqn{
\mathrm{Var}(\varepsilon_{ij}) = \sigma_{ij}^2.
}

Given the overall effect \code{Delta} and the placebo progression rate \code{CM_P}, a fully uniform (purely additive)
treatment effect—meaning the same average effect applies to all patients regardless of baseline progression—is
implemented by setting \eqn{\phi = 0} and
\deqn{
\beta_A = \Delta + \beta_P.
}
A fully proportional treatment effect—no additive component, the effect scales with the baseline rate—is
implemented by setting
\deqn{
\beta_A = \beta_P
}
and
\deqn{
\phi = \frac{\Delta}{|\beta_P|}.
}
A more relativistic intermediate effect (half additive and half proportional) is obtained by setting
\deqn{
\phi = \frac{\Delta}{2|\beta_P|}
}
and
\deqn{
\beta_A = \frac{\Delta}{2} + \beta_P.
}

The kidney hierarchical composite endpoint is defined in the following order:
(1) Kidney Failure Replacement Therapy (KFRT); (2) Sustained eGFR < 15;
(3) Sustained 57 percent or more decline in eGFR; (4) Sustained 50 percent or more decline in eGFR;
(5) Sustained 40 percent or more decline in eGFR; and (6) Change in eGFR. In practice, because KFRT is
frequently initiated when true eGFR is very low, sustained eGFR < 15 events are rarely observed.

If \code{two_meas} is not \code{"no"}, a second measurement is generated using the same latent baseline eGFR and
subject-specific slope, but with an independent measurement error draw from the same distribution as above.
The two measurements are then averaged at baseline when \code{two_meas = "base"}, at the final visit when
\code{two_meas = "postbase"}, or at both baseline and the final visit when \code{two_meas = "both"}. This implementation
preserves correlation between the duplicate measurements because they share the same underlying true trajectory.
}
\examples{
# Example - Specifying the most important variables
set.seed(2022)
## The overall treatment effect
Delta <- 0.75
## The placebo progression rate
CM_P <- - 4.5
## Intermediate effect (half additive and half proportional)
delta <- Delta/2
CM_A <- delta + CM_P 
phi <- Delta / (2*abs(CM_P))
L <- simKHCE(n = 1000, CM_A = CM_A, CM_P = CM_P, 
fixedfy = 4, Emin = 25, Emax = 75, phi = phi)
dat <- L$HCE
calcWO(dat)
}
\seealso{
\code{\link[=simHCE]{simHCE()}} for a general function of simulating \code{hce} datasets.
}
