getpower.clst: Calculate power for the Cox proportional hazard model with time-dependent exposure using method 1 with clustering

Description

This functions runs nSim (number of simulations; specified by the user) Monte Carlo simulations on the Cox proportional model with a cluster option. At each simulation, the function calls tdSim.clst internally. The function returns a data frame of scenario-specific parameters (including statistical power) and appends the output to a file with file name specified in the input parameters list. The user also has an option to display an incidence plot.

Usage

getpower.clst(nSim, N, duration = 24, med.TTE.Control = 24, rho = 1, beta,
    med.TimeToCensor = 14, df, type, scenario, prop.fullexp = 0,
    maxrelexptime = 1, min.futime = 0, min.postexp.futime = 0, output.fn,
    simu.plot = FALSE)

Arguments

nSim

Number of simulations.

Number of subjects to be screened.

duration

Length of the study in months; the default value is 24 (months).

med.TTE.Control

Median time to event for control group; the default value is 24 (months).

rho

Shape parameter of the Weibull distribution. Default is 1, which will generate survival times by using the exponential distribution.

beta

A numeric value that represents the exposure effect, which is the regression coefficient (log hazard ratio) that represents the magnitude of the relationship between the exposure covariate and the risk of an event.

med.TimeToCensor

Median time to censoring for all subjects. The default value is 14 (months). Also see help document for tdSim.method1.

A user-specified n by 3 clustering data frame with columns corresponding to cat_id (category id, which is the physician site id. It can be either text strings or integers), cat_prop (category proportion, which is the proportion of subjects in correspondin

type

A text string indicating the what type of dataset is of interest. Either "fixed" or "td" should be inputted.

scenario

A text string to name a scenario that is being simulated. The user can simply put " " if he/she decides to not name the scenario.

prop.fullexp

A numeric value in interval [0, 1) that represents the proportion of exposed subjects that are fully exposed from the beginning to the end of the study. The default value is 0, which means all exposed subjects have an exposure status transition at some po

maxrelexptime

A numeric value that represents minimum post-exposure follow-up time (in months). The default value is 0, which means no minimum post-exposure follow-up time is considered. If it has a positive value, this argument will help exclude subjects that only spe

min.futime

A numeric value that represents minimum follow-up time (in months). The default value is 0, which means no minimum follow-up time is considered. If it has a positive value, this argument will help exclude subjects that only spend a short amount of time in

min.postexp.futime

output.fn

A .csv filename to write in the output. If the filename does not exist, the function will create a new .csv file for the output.

simu.plot

A logical value indicating whether or not to output an incidence plot.The default value is FALSE.

Value

i_scenarioScenario name specified by the user.
i_typeDataset type specified by the user.
i_NNumber of subjects to be screened, specified by the user.
i_min.futimeMinimum follow-up time to be considered, specified by the user.
i_min.postexp.futimeMinimum post-exposure follow-up time to be considered, specified by the user.
i_catCategory id specified in user's input data frame.
i_cat_propCategory proportion specified in user's input data frame.
i_cat_exp.propCategory exposure proportion specified in user's input dataframe.
i_exp.propWeighted exposure proportion calculated from user's input dataframe.
i_lambdaValue of the scale parameter of the Weibull distribution to generate survival times. Calculated from median time to event for control group, which is specified by the user.
i_rhoUser-specified Value of the shape parameter of the Weibull distribution to generate survival times.
i_rateCRate of the exponential distribution to generate censoring times. Calculated from median time to censoring, which is specified by the user.
i_betaInput value of regression coefficient (log hazard ratio).
N_effSimulated number of evaluable subjects, which is the resulting number of subjects with or without considering minimum follow-up time and/or minimum post-exposure follow-up time.
N_effexp_pSimulated proportion of exposed subjects with or without considering minimum follow-up time and/or minimum post-exposure follow-up time.
bhatSimulated value of regression coefficient (log hazard ratio).
HRSimulated value of hazard ratio.
dSimulated number of events in total.
d_cSimulated number of events in control group.
d_expSimulated number of events in exposed group.
mst_cSimulated median survival time in control group.
mst_expSimulated median survival time in exposed group.
powSimulated statistical power from the Cox regression model on data with time-dependent exposure.

Details

The function calculates power based on the Cox regression model, which calls the coxph function from the survival library using the the simulated data from tdSim.clst

References

Savignoni et al.: Matching methods to create paired survival data based on an exposure occurring over time: a simulation study with application to breast cancer.

BMC Medical Research Methodology 2014 14:83.

Examples

Run this code

# Install the survival package if needed.

library(survival)

# Create a clustering data frame as input with 3 categories and a 20% weighted
# exposure proportion.
  
input_df <- data.frame(cat_id = c('lo', 'med', 'hi'),
	cat_prop = c(0.65, 0.2, 0.15), cat_exp.prop = c(0.1, 0.3, 0.5))

# We recommend setting nSim to at least 500. It is set to 10 in the example to
# reduce run time for CRAN submission.

# Run 10 simulations. Each time simulate a dataset of 600 subjects with
# time-dependent exposure with both minimum follow-up time (4 months) and
# minimum post-exposure follow-up time (4 months) imposed. Also consider a
# quick exposure after entering the study for each exposed subject. Set the
# maximum relative exposure time to be 1/6. 

# Set the duration of the study to be 24 months; the median time to event for
# control group to be 24 months; exposure effect to be 0.3; median time to
# censoring to be 14 months.

ret <- getpower.clst(nSim = 10, N = 600, beta = 0.3, df = input_df,
    type = "td", scenario = "clustering", maxrelexptime = 1/6, min.futime = 4,
    min.postexp.futime = 4, output.fn = "output_clst.csv",)

Run the code above in your browser using DataLab