sim_followup {PWEXP}

Estimate follow up time and number of events by simulation

Description

sim_follwup is used to estimate follow-up time and number of events (given calander time, or number of randomized samples, or number of events).

Usage

sim_followup(at, type = 'calander', group="Group 1", strata='Strata 1',
            allocation=1, event_lambda=NA, drop_rate=NA, death_lambda=NA,
            n_rand=NULL, rand_rate=NULL, total_sample=NULL, extra_follow=0,
            by_group=FALSE, by_strata=FALSE, advanced_dist=NULL,
            stat=c(mean, median, sum), follow_up_endpoint=c('death', 'drop_out',
            'cut'), count_in_extra_follow=FALSE, count_insufficient_event=FALSE,
            start_date=NULL, rep=300, seed=1818)

Arguments

at

specify a vector of occasions. When type='calander', at is the time from fisrt randomization; when type='event', at is the number of accumulated events; when type='sample', at is the number of randomized samples.

type

specify the type of at. Must be 'calander', event or sample.

group

a character vector of the names of each group (e.g., c('treatment','control')). See simdata.

strata

a character vector of the names of strata in groups (e.g., c('young','old')). See simdata.

allocation

the relative ratio of sample size in each subgroup (group*strata). The value will be recycled if the length is less than needed. See simdata.

event_lambda

the hazard rate of the primary endpoint (event). The value will be recycled if the length is less than needed. See simdata.

drop_rate

(optional) the drop-out rate (patients/month). Not hazard rate. The value will be recycled if the length is less than needed. See simdata.

death_lambda

(optional) the hazard rate of death. The value will be recycled if the length is less than needed. See simdata.

n_rand

(required when rand_rate=NULL) a vector of the number of randomization each month; can be non-integers. See simdata.

rand_rate

(required when n_rand=NULL) the randomization rate (patients/month; can be non-integer). See simdata.

total_sample

(required when n_rand=NULL) total scheduled sample size. See simdata.

extra_follow

delay the analysis time by extra time (extra_follow) after the time specified by at. See details.

by_group

logical; if TRUE, also return results by each group.

by_strata

logical; if TRUE, also return results by each stratum.

advanced_dist

use user-specified distributions for event, drop-out and death. A list containing random generation functions. See details and examples in simdata.

stat

a vector of functions to summarize the follow-up time. See example.

follow_up_endpoint

Which endpoints can be regarded as the end of follow-up. Choose from 'death', 'drop_out', 'cut' (censored at the end of the trial) or 'event'.'

count_in_extra_follow

logical; whether to count subjects who are randomized after the time spcified by at but before the time specified by at + extra_follow.

count_insufficient_event

logical; only affects the result when type='event'. If TRUE, for samples that cannot achieve required number of events, the last follow-up time is the analysis time. If FALSE, these samples will be dropped.

start_date

the start date of the first randomization; in the format: "2000-01-30"

rep

number simulated iterations.

seed

a random seed.

Details

See the help document of simdata for most arguments details.

When type='calander', the function estimates the follow-up time and number of events at time at plus extra_follow; when type='event', the function estimates these at the time when total number of events is at plus time extra_follow; when type='sample', the function estimates these at the time when total number of randomized subjects is at plus time extra_follow.

The stat specifies a vector of user defined functions. Each of them must take a vector of individual follow-up time as input and return a single summary value. See example.

Value

A data frame containing the some of these columns:

ID

subject ID

group

group indicator

strata

stratum indicator

randT

randomization time (from the beginning of the trial)

eventT

event time (from randT)

eventT_abs

event time (from the beginning of the trial)

dropT

drop-out time (from randT)

dropT_abs

drop-out time (from the beginning of the trial)

deathT

death time (from randT)

deathT_abs

death time (from the beginning of the trial)

censor

censoring (drop-out or death) indicator

censor_reason

censoring reason ('drop_out','death','never_event'(followT=inf))

event

event indicator

followT

follow-up time / observed time (from randT)

followT_abs

follow-up time / observed time (from the beginning of the trial)

Note

event_lambda, drop_rate, death_lambda can be 0, which means the corresponding subgroup will have an Inf value for each variable.

Author(s)

Tianchen Xu [e-mail]

See Also

simdata

Examples

# Two groups. Treatment:place=1:2. Drop rate=3%/month. Hazard ratio=0.7.

# define the piecewiese exponential event generation function
myevent_dist_trt <- function(n)rpwexp(n, rate=c(0.1, 0.01, 0.2)*0.7, breakpoint=c(5,14))
myevent_dist_con <- function(n)rpwexp(n, rate=c(0.1, 0.01, 0.2), breakpoint=c(5,14))

# user defined summary function, the proportion of subjects that follow more than 12 month
prop_12 <- function(x)mean(x >= 12)

# estimate the event curve or timeline:
# (here rep=60 is for demo purpose only, please increase this value in practice!)
event_curve <- sim_followup(at=seq(20,90,10), type = 'calendar', group = c('trt','con'),
             rand_rate = 20, total_sample = 1000, drop_rate = 0.03, allocation = 1:2,
             advanced_dist = list(event_dist=c(myevent_dist_trt, myevent_dist_con)),
             by_group = TRUE, stat = c(median, mean, prop_12), start_date = "2020-01-01",
             rep=60)
time_curve <- sim_followup(at=seq(200,600,100), type = 'event', group = c('trt','con'),
             rand_rate = 20, total_sample = 1000, drop_rate = 0.03, allocation = 1:2,
             advanced_dist = list(event_dist=c(myevent_dist_trt, myevent_dist_con)),
             stat = c(median, mean, prop_12), start_date = "2020-01-01", rep=60)
# plot event curve or timeline
plot(event_curve$T_all$analysis_time_c, event_curve$T_all$event, xlab='Time',
    ylab='Number of events', type='b')
plot(time_curve$T_all$event, time_curve$T_all$analysis_time_c, xlab='Number of
    events', ylab='Time', type='b')