create_arm: Create an 'arm' object

In npsurvSS: Sample Size and Power Calculation for Common Non-Parametric Tests in Survival Analysis

Description

Create an object of class 'arm' by specifying the trial parameters for a single arm, including the sample size, accrual distribution, survival distribution, loss to follow-up distribution, and study duration.

Usage

create_arm(size, accr_time, accr_dist = "pieceuni",
  accr_interval = c(0, accr_time), accr_param = NA, surv_cure = 0,
  surv_interval = c(0, Inf), surv_shape = 1, surv_scale,
  loss_shape = 1, loss_scale, follow_time = Inf, total_time = Inf)

Arguments

size	sample size. If total sample size is unknown, provide the integer sample size relative to the opposing arm, e.g. 1 for 1:2 randomization ratio or 2 for 2:3.
accr_time	accrual duration.
accr_dist	accrual distribution. Default is piecewise uniform. Alternatively, 'truncexp' allows for a truncated exponential distribution as proposed by Lachin and Foulkes (1986). Depending on the value of accr_param, this distribution can be either convex or concave.
accr_interval	accrual intervals. Defaults to the single interval spanning from 0 to accr_time. If a piecewise uniform accrual with more than one interval is desired, specify accr_interval as the vector of increasing changepoints (knots) starting from 0 and ending with accr_time, e.g. c(0, 2, 4) defines a piecewise uniform distribution with two intervals, [0, 2) and [2, 4].
accr_param	additional accrual parameter(s). For a piecewise uniform accrual with more than one interval, specify accr_param as the vector of probabilities a patient is enrolled in each interval. The probabilities should naturally sum to 1. For accr_dist='truncexp', specify accr_param as a single number. >0 results in a convex distribution and <0 results in a concave distribution.
surv_cure	proportion of patients that are cured.
surv_interval	survival intervals. Defaults to the single interval spanning from 0 to infinity. If a piecewise exponential survival is desired for uncured patients, specify surv_interval as the vector of increasing changepoints (knots) starting from 0 and ending with infinity, e.g. c(0, 6, 10, Inf).
surv_shape	Weibull shape parameter for the survival distribution of uncured patients.
surv_scale	Weibull scale parameter for the survival distrubition of uncured patients. Piecewise exponential survival may be defined by specifying surv_shape=1 and surv_scale as the vector of piecewise hazard rates.
loss_shape	Weibull shape parameter for the loss to follow-up distribution.
loss_scale	Weibull scale parameter for the loss to follow-up distribution.
follow_time	follow-up duration.
total_time	total study duration. Only 1 of the 2 parameters, follow_time or total_time, need to be defined. If neither is defined, total_time is defaulted to max value 1e6.

Value

a list containing assumptions of size, accrual, censoring, survival, and follow-up for a single arm.

References

Lachin, J. M. and Foulkes, M. A. (1986) Evaluation of sample size and power for analyses of survival with allowance for nonuniform patient entry, losses to follow-up, noncompliance, and stratification. Biometrics, 42, 507-519.

See Also

create_arm_lachin for creating an object of subclass 'lachin'.

Examples

# Example 1
example <- create_arm(size=120,
  accr_time=6,                   # uniform accrual
  surv_scale=0.05,               # exponential survival
  loss_scale=0.005,              # exponential loss to follow-up
  follow_time=12)
class(example)                   # this example also satisfies properties of subclass 'lachin'

# Example 2
create_arm(size=120,
  accr_time=6,                   # truncated exponential accrual
  accr_dist="truncexp",
  accr_param=0.1,
  surv_shape=2,                  # weibull survival
  surv_scale=0.05,
  loss_shape=1.5,                # weilbull loss to follow-up
  loss_scale=0.005,
  total_time=18)

# Example 3
create_arm(size=120,
  accr_time=6,
  accr_interval=c(0,2,4,6),      # piecewise uniform accrual
  accr_param=c(0.2,0.3,0.5),
  surv_cure=0.1,                 # 10% cure fraction
  surv_interval=c(0,6,10,Inf),   # piecewise exponential survival for uncured patients
  surv_scale=c(0.05,0.04,0.03),
  loss_shape=0.7,                # weibull loss to follow-up
  loss_scale=0.005,
  total_time=18)

Example output

[1] "list"   "lachin" "arm"   
$size
[1] 120

$accr_time
[1] 6

$accr_dist
[1] "truncexp"

$accr_interval
[1] 0 6

$accr_param
[1] 0.1

$surv_cure
[1] 0

$surv_interval
[1]   0 Inf

$surv_shape
[1] 2

$surv_scale
[1] 0.05

$loss_shape
[1] 1.5

$loss_scale
[1] 0.005

$follow_time
[1] 12

$total_time
[1] 18

attr(,"class")
[1] "list" "arm" 
$size
[1] 120

$accr_time
[1] 6

$accr_dist
[1] "pieceuni"

$accr_interval
[1] 0 2 4 6

$accr_param
[1] 0.2 0.3 0.5

$surv_cure
[1] 0.1

$surv_interval
[1]   0   6  10 Inf

$surv_shape
[1] 1

$surv_scale
[1] 0.05 0.04 0.03

$loss_shape
[1] 0.7

$loss_scale
[1] 0.005

$follow_time
[1] 12

$total_time
[1] 18

attr(,"class")
[1] "list" "arm" 

npsurvSS documentation built on Jan. 11, 2020, 9:18 a.m.