cgr_control_limit: Determine control limits for CGR-CUSUM by simulation

View source: R/cgr_control_limit.R

cgr_control_limitR Documentation

Determine control limits for CGR-CUSUM by simulation

Description

This function can be used to determine control limits for the CGR-CUSUM (cgr_cusum) procedure by restricting the type I error alpha of the procedure over time.

Usage

cgr_control_limit(time, alpha = 0.05, psi, n_sim = 20, coxphmod,
  baseline_data, cbaseh, inv_cbaseh, interval = c(0, 9e+12),
  h_precision = 0.01, ncores = 1, seed = 1041996, pb = FALSE,
  chartpb = FALSE, detection = "upper", maxtheta = log(6), assist)

Arguments

time

A numeric value over which the type I error alpha must be restricted.

alpha

A proportion between 0 and 1 indicating the required maximal type I error. Default is 0.05.

psi

A numeric value indicating the estimated Poisson arrival rate of subjects at their respective units. Can be determined using parameter_assist().

n_sim

An integer value indicating the amount of units to generate for the determination of the control limit. Larger values yield more precise control limits, but greatly increase computation times. Default is 20.

coxphmod

(optional): A cox proportional hazards regression model as produced by the function coxph(). Suggested:
coxph(Surv(survtime, censorid) ~ covariates, data = baseline_data).
Alternatively, a list with the following elements:

formula:

a formula() in the form ~ covariates;

coefficients:

a named vector specifying risk adjustment coefficients for covariates. Names must be the same as in formula and colnames of data.

baseline_data

(optional): A data.frame used for covariate resampling with rows representing subjects and at least the following named columns:

entrytime:

time of entry into study (numeric);

survtime:

time from entry until event (numeric);

censorid:

censoring indicator (0 = right censored, 1 = observed), (integer).

and optionally additional covariates used for risk-adjustment. Can only be specified in combination with coxphmod.

cbaseh

(optional): A function that returns the unadjusted cumulative baseline hazard H_0(t). If cbaseh is missing but coxphmod has been specified as a survival object, this baseline hazard rate will be determined using the provided coxphmod.

inv_cbaseh

(optional): A function that returns the unadjusted inverse cumulative baseline hazard H^{-1}_0(t). If inv_cbaseh is missing, it will be determined from cbaseh numerically.

interval

(optional): Interval in which survival times should be solved for numerically.

h_precision

(optional): A numerical value indicating how precisely the control limit should be determined. By default, control limits will be determined up to 2 significant digits.

ncores

(optional): Number of cores to use to parallelize the computation of the CGR-CUSUM charts. If ncores = 1 (default), no parallelization is done. You can use detectCores() to check how many cores are available on your computer.

seed

(optional): A numeric seed for survival time generation. Default = my birthday.

pb

(optional): A boolean indicating whether a progress bar should be shown. Default is FALSE.

chartpb

(optional): A boolean indicating whether progress bars should be displayed for the constructions of the charts. Default is FALSE.

detection

Should the control limit be determined for an "upper" or "lower" CGR-CUSUM? Default is "upper".

maxtheta

(optional): Maximum value of maximum likelihood estimate for parameter \theta. Default is log(6), meaning that at most a 6 times increase/decrease in the odds/hazard ratio is expected.

assist

(optional): Output of the function parameter_assist()

Details

This function performs 3 steps to determine a suitable control limit.

  • Step 1: Generates n_sim in-control units (failure rate as baseline). If data is provided, subject covariates are resampled from the data set.

  • Step 2: Determines chart values for all simulated units.

  • Step 3: Determines control limits such that at most a proportion alpha of all units cross the control limit.

The generated data as well as the charts are also returned in the output.

Value

A list containing three components:

  • call: the call used to obtain output;

  • charts: A list of length n_sim containing the constructed charts;

  • data: A data.frame containing the in-control generated data.

  • h: Determined value of the control limit.

  • achieved_alpha: Achieved type I error on the sample of n_sim simulated units.

Author(s)

Daniel Gomon

See Also

cgr_cusum

Other control limit simulation: bernoulli_control_limit(), bk_control_limit()

Examples


require(survival)

#Determine a cox proportional hazards model for risk-adjustment
exprfit <- as.formula("Surv(survtime, censorid) ~ age + sex + BMI")
tcoxmod <- coxph(exprfit, data= surgerydat)

#Determine a control limit restricting type I error to 0.1 over 500 days
#with specified cumulative hazard function without risk-adjustment
a <- cgr_control_limit(time = 500, alpha = 0.1, cbaseh = function(t) chaz_exp(t, lambda = 0.02),
inv_cbaseh = function(t) inv_chaz_exp(t, lambda = 0.02), psi = 0.5, n_sim = 10)


#Determine a control limit restricting type I error to 0.1 over 500 days
#using the risk-adjusted cumulative hazard found using coxph()
b <- cgr_control_limit(time = 500, alpha = 0.1, coxphmod = tcoxmod, psi = 0.5, n_sim = 10,
baseline_data = subset(surgerydat, unit == 1))

print(a$h)
print(b$h)


success documentation built on June 22, 2024, 10:19 a.m.