Type:	Package
Title:	2-Stage Preference Trial Design and Analysis
Version:	1.1.6
URL:	https://github.com/kaneplusplus/preference
BugReports:	https://github.com/kaneplusplus/preference/issues
Description:	Design and analyze two-stage randomized trials with a continuous outcome measure. The package contains functions to compute the required sample size needed to detect a given preference, treatment, and selection effect; alternatively, the package contains functions that can report the study power given a fixed sample size. Finally, analysis functions are provided to test each effect using either summary data (i.e. means, variances) or raw study data <doi:10.18637/jss.v094.c02>.
License:	LGPL-2
Imports:	ggplot2, tidyr
Suggests:	testthat
Encoding:	UTF-8
RoxygenNote:	7.1.1
LazyData:	true
NeedsCompilation:	no
Packaged:	2020-09-08 19:22:57 UTC; mike
Author:	Briana Cameron [aut, cph], Denise Esserman [ctb], Michael Kane [cre, ctb]
Maintainer:	Michael Kane <michael.kane@yale.edu>
Repository:	CRAN
Date/Publication:	2020-09-09 06:20:03 UTC

Design and Analysis of Two-stage Randomized Clinical Trials

Description

The preference package is used for the design and analysis of two-stage randomized trials with a continuous outcome measure. In this study, patients are first randomized to either a random or choice arm. Patients initially randomized to the choice arm are allowed to select their preferred treatment from the available treatment options; patients initially randomized to the random arm undergo a second randomization procedure to one of the available treatment options. The design has also been extended to include important stratification variables; the functions provided in this package can accommodate both the unstratified and stratified designs.

In this study, there are three effects that may be of interest. The treatment effect captures the difference in outcome between patients randomized to treatment A and treatment B (similar to a traditional RCT). The selection effect captures the difference in outcome between patients that prefer treatment A and patients that prefer treatment B, regardless of the treatment that is actually received. Finally, the preference effect compares the outcomes of patients who receive their preferred treatment (either treatment A or treatment B) and patients who do not receive their preferred treatment.

To aid in the design of these two-stage randomized studies, sample size functions are provided to determine the necessary sample size to detect a particular selection, preference, and/or treatment effect. If the sample size is fixed prior to the start of the study, functions are provided to calculate the study power to detect each effect. Finally, the optimal_proportion function can be used to determine the optimal proportion of patients randomized to the choice arm in the initial randomization.

To analyze the data from the two-stage randomized trial, two analysis functions are provided. The function preference computes the test statistic and p-value for each effect given provided raw study data. The function fit_preference_summary uses provided summary data (mean, variance, and sample size) of each study group to compute the test statistic and p-value of each effect. The test statistics can be accessed from the models using the summary() function.

Preference Trial Function Calls:

• preference.trial: construct a preferene.trial based on effect and sample sizes.

• pt_from_power: construct a preference.trial based on power and effect size.

• pt_from_ss: construct a preference.trial based on sample size

Analysis Function Calls

• preference and fit_preference: computes test statistic and p-value for observed #' selection, preference, and treatment effects using provided raw data

• fit_preference_summary: computes test statistic and p-value for observed selection, preference, and treatment effects using provided summary data (mean, variance, sample size)

Other Function Calls

• treatment_effect_size: computes the treatment effect that can be detected given a specified sample size and power

• optimal_proportion: computes the optimal proportion randomized to choice arm (defined for unstratified design only)

• effects_from_means: computes the treatment, selection, and preference effect sizes provided the study means in each treatment arm

Data Sets

• imap: summary SF36 outcome data for the two-stage randomized IMAP study

• imap_strat: summary SF36 outcome data for the two-stage randomized IMAP study stratified by high vs. low STAI score

Acknowledgments: This work was partially supported through a Patient-Centered Outcomes Research Institute (PCORI) Award (ME-1511-32832) and Yale's CTSA Award (Ul1TR001863). We would also like to thank the IMAP team for sharing their data to demonstrate this package.

Disclaimer: All statements in this report, including its findings and conclusions, are solely those of the authors and do not necessarily represent the views of the Patient-Centered Outcomes Research Institute (PCORI), its Board of Governors or Methodology Committee.

References

Rucker G (1989). "A two-stage trial design for testing treatment, self-selection and treatment preference effects." Stat Med, 8(4):477-485. (PubMed)

McCaffery et al. (2010) "Psychosocial outcomes of three triage methods for the management of borderline abnormal cervical smears: an open randomised trial." BMJ, 340:b4491. (PubMed)

Walter et. al. (2011). "Optimal allocation of participants for the estimation of selection, preference and treatment effects in the two-stage randomised trial design." Stat Med, 31(13):1307-1322. (PubMed)

McCaffery et al. (2011) "Determining the Impact of Informed Choice: Separating Treatment Effects from the Effects of Choice and Selection in Randomized Trials." Med Decis Making, 31(2):229-236. (PubMed)

Turner RM, et al. (2014). "Sample Size and Power When Designing a Randomized Trial for the Estimation of Treatment, Selection, and Preference Effects." Medical Decision Making, 34:711-719. (PubMed)

Cameron B, Esserman D (2016). "Sample Size and Power for a Stratified Doubly Randomized Preference Design." Stat Methods Med Res. (PubMed)

Calculate Effect Sizes from Means

Description

Calculates the preference, selection and treatment effects given the means of each treatment group in the choice and random arms for the 2-stage randomized study.

Usage

effects_from_means(mu1, mu2, mu11, mu22, phi, nstrata = 1, xi = NULL)

Arguments

References

Rucker G (1989). "A two-stage trial design for testing treatment, self-selection and treatment preference effects." Stat Med, 8(4):477-485. (PubMed)

Examples

effects_from_means(mu1=1, mu2=2, mu11=1.5, mu22=2.5, phi=0.5)

Fit the Preference Data Collected from a Two-stage Clinical Trial

Description

Computes the test statistics and p-values for the preference, selection, and treatment effects for the two-stage randomized trial using collected outcome, random, treatment, and strata values for specified significance level.

Usage

fit_preference(outcome, arm, treatment, strata, alpha = 0.05)

Arguments

Examples

# Unstratified
outcome <- c(10, 8, 6, 10, 5, 8, 7, 6, 10, 12, 11, 6, 8, 10, 5, 7, 9, 
             12, 6, 8, 9, 10, 7, 8,11)
arm <- c(rep("choice", 13), rep("random", 12))
treatment <- c(rep(1, 5), rep(2, 8), rep(1, 6), rep(2, 6))
fit_preference(outcome, arm, treatment)

# Stratified
# Same data plus strata information.
strata <- c(1,1,2,2,2,1,1,1,1,2,2,2,2,1,1,1,2,2,2,1,1,1,2,2,2)
fit_preference(outcome, arm, treatment, strata, alpha=0.1)

Fit Preference Model from Summary Data

Description

Computes the test statistics and p-values for the preference, selection, and treatment effects in a two-stage randomized trial using summary data.

Usage

fit_preference_summary(
  x1mean,
  x1var,
  m1,
  x2mean,
  x2var,
  m2,
  y1mean,
  y1var,
  n1,
  y2mean,
  y2var,
  n2,
  xi = 1,
  nstrata = 1,
  alpha = 0.05
)

Arguments

References

Rucker G (1989). "A two-stage trial design for testing treatment, self-selection and treatment preference effects." Stat Med, 8(4):477-485. (PubMed)

Cameron B, Esserman D (2016). "Sample Size and Power for a Stratified Doubly Randomized Preference Design." Stat Methods Med Res. (PubMed)

Examples

# Unstratified

x1mean <- 5
x1var <- 1
m1 <- 15
x2mean <- 7
x2var <- 1.1
m2 <- 35
y1mean <- 6
y1var <- 1
n1 <- 25
y2mean <- 8
y2var <- 1.2
n2 <- 25
fit_preference_summary(x1mean, x2var, m1, x2mean, x2var, m2, y1mean, y1var,
               n1, y2mean, y2var, n2)

# Stratified

x1mean <- c(5, 3)
x1var <- c(1, 1)
m1 <- c(15, 30)
x2mean <- c(7, 7)
x2var <- c(1.1, 3.1)
m2 <- c(35, 40)
y1mean <- c(6, 4)
y1var <- c(1, 2)
n1 <- c(25, 35)
y2mean <- c(8, 12)
y2var <- c(1.2, 1)
n2 <- c(25, 20)
fit_preference_summary(x1mean, x2var, m1, x2mean, x2var, m2, y1mean, y1var,
                       n1, y2mean, y2var, n2, alpha=0.1)

Data from the IMAP study

Description

The “Improving Management of Abnormal Pap Smears” study used a two-stage randomized preference trial design to evaluate psychosocial outcomes in women found to have atypical cells in a Pap Smear. Two systems for managing the atypical cells were tested (repeated Pap smears or HCV triage) and a doubly randomized design was used to evaluate the role of patient preference. The data set provides mean, standard deviation and sample sizes of the SF36 outcome for each treatment in both the choice and random arms.

Three data sets are provided with the preference package based on the IMAP study. The first, imap_summary provides summary statistics of the entire trial. The second imap_summary_stratified, summary statistics of the study per strata. The third imap is a resampled version of the individual level data including stratification. Each of these data sets are compatible with the analysis functions fit_preference_summary, fit_preference, and preference, provided in this package. The examples sections in the documentation illustrate their use.

References

McCaffery et al. (2010) "Psychosocial outcomes of three triage methods for the management of borderline abnormal cervical smears: an open randomised trial." BMJ, 340:b4491. (PubMed)

McCaffery et al. (2011) "Determining the Impact of Informed Choice: Separating Treatment Effects from the Effects of Choice and Selection in Randomized Trials." Med Decis Making, 31(2):229-236. (PubMed)

Unstratified Optimized Theta

Description

Calculates the optimal proportion of patients assigned to the choice arm in an unstratified two-stage randomized trial

Usage

optimal_proportion(w_sel, w_pref, w_treat, sigma2, phi, delta_pi, delta_nu)

Arguments

References

Walter et. al. (2011). "Optimal allocation of participants for the estimation of selection, preference and treatment effects in the two-stage randomised trial design." Stat Med, 31(13):1307-1322. (PubMed)

Examples

optimal_proportion(w_sel=0.2, w_pref=0.4, w_treat=0.4, sigma2=1, phi=0.5,
                   delta_pi=1, delta_nu=0.5)

Power Calculation from Sample Size

Description

Calculates the study power to detect a set of effects given a particular sample size in a two-stage randomized clinical trial

Usage

overall_power(
  N,
  phi,
  sigma2,
  delta_pi,
  delta_nu,
  delta_tau,
  alpha = 0.05,
  theta = 0.5,
  xi = 1,
  nstrata = 1,
  k = 1
)

Arguments

References

Turner RM, et al. (2014). "Sample Size and Power When Designing a Randomized Trial for the Estimation of Treatment, Selection, and Preference Effects." Medical Decision Making, 34:711-719. (PubMed)

Cameron B, Esserman D (2016). "Sample Size and Power for a Stratified Doubly Randomized Preference Design." Stat Methods Med Res. (PubMed)

Power Calculation from Sample Size

Description

Calculates the study power to detect the preference effect given a particular sample size in a two-stage randomized clinical trial with a binary outcome measure

Usage

overall_power_binom(
  N,
  phi,
  p11,
  p22,
  p1,
  p2,
  alpha = 0.05,
  theta = 0.5,
  xi = 1,
  nstrata = 1
)

Arguments

Overall Sample Size

Description

Calculates the sample size required to detect a given set of effects in a two-stage randomized clinical trial. Returns the largest of the required sample sizes for a given set of treatment, selection, and preference effects.

Usage

overall_sample_size(
  power,
  phi,
  delta_pi,
  delta_nu,
  delta_tau,
  sigma2,
  alpha = 0.05,
  theta = 0.5,
  xi = 1,
  nstrata = 1,
  k = 1,
  dist = "norm"
)

Arguments

References

Turner RM, et al. (2014). "Sample Size and Power When Designing a Randomized Trial for the Estimation of Treatment, Selection, and Preference Effects." Medical Decision Making, 34:711-719. (PubMed)

Cameron B, Esserman D (2016). "Sample Size and Power for a Stratified Doubly Randomized Preference Design." Stat Methods Med Res. (PubMed)

Overall Sample Size Binomial

Description

Calculates the sample size required to detect a given set of effects in a two-stage randomize clinical trial with a binary outcome. Returns the sample size for each of the three effects: preference, selection and treatment

Usage

overall_sample_size_bin(
  power,
  phi,
  p11,
  p22,
  p1,
  p2,
  alpha = 0.05,
  theta = 0.5,
  xi = 1,
  nstrata = 1,
  k = 1
)

Arguments

Overall Sample Size Poisson Distribution

Description

Calculates the sample size required to detect a given set of effects in a two-stage randomized clinical trial. Returns the largest of the required sample sizes for a given set of treatment, selection, and preference effects.

Usage

overall_sample_size_pois(
  power,
  phi,
  lambda11,
  lambda22,
  lambda1,
  lambda2,
  alpha = 0.05,
  theta = 0.5,
  xi = 1,
  nstrata = 1
)

Arguments

Examples

# Unstratified
overall_sample_size_pois(power = 0.8, phi = 0.6, lambda11 = 0.6, 
                         lambda22 = 0.7, lambda1 = 0.4, lambda2 = 0.6)
# Stratified
overall_sample_size_pois(power = 0.8, phi = c(0.6, 0.5), 
                         lambda11 = c(0.6, 0.7), lambda22 = c(0.7,0.7), 
                         lambda1 = c(0.4, 0.6), lambda2 = c(0.6, 0.6), 
                         xi = c(0.5, 0.5), nstrata = 2)

Plot the effect sizes of a preference trial

Description

The plot() function visualizes the change in the preference effect, the selection effect, or both as a function of the total sample size of the trial. If the preference effect varies but the selection effect does not, then it plots the preference effect by the total sample size. Similarly if the selection effect varies but not the preference effect then selection effect vs total sample size is shown. When both preference and selection effect vary then the selection effect is shown conditioned on the given preference effects.

It is assumed that the set of trial provided as a parameter are related and are comparable. For example, the function does not check to if the strata are the same for all trials. If some other visualization is required then the user is reminded that a preference.trial object is a data frame and can be visualized in the usual way.

Usage

## S3 method for class 'preference.trial'
plot(x, ...)

Arguments

Examples

# Plot trials with fixed power and varying preference effect.
trials <- pt_from_power(power = 0.8, pref_effect = seq(0.5, 2, by = 0.1), 
                        selection_effect = 1, treatment_effect = 1, 
                        sigma2 = 1, pref_prop = 0.6)
plot(trials)
 
# Plot trials with fixed power and varying selection effect.
trials <- pt_from_power(power = 0.8, pref_effect = 1,
                        selection_effect = seq(0.5, 2, by = 0.1), 
                        treatment_effect = 1, sigma2 = 1, pref_prop = 0.6)
plot(trials)

# Plot trials with fixed power and varying preference and 
# selection effects.

# the selection effects of interest
selection_effects <- rep(seq(0.5, 2, by = 0.1), 4)

# the preference effects to condition on
pref_effects <- rep(seq(0.4, 1, by = 0.2), 
                    each = length(selection_effects)/4)

trials <- pt_from_power(power = 0.8, pref_effect = pref_effects,
                        selection_effect = selection_effects,
                        treatment_effect = 1, sigma2 = 1, pref_prop = 0.6)
plot(trials)
 

Fit Preference Data Collected from a Two-stage Clinical Trial

Description

The variables in the formula should reference columns in the data parameter and should have the following characteristics.

• outcome: Numeric values giving the outcome of interest.

• treatment: Character, categorical, or integer values denoting the treatment received by an individual.

• random: Logical value indicating whether the sample was from the random arm (TRUE) or choice (FALSE).

• strata: An optional integer value denoting which strata individuals belong to.

Usage

preference(form, data, alpha = 0.05)

Arguments

Examples

# Unstratified

outcome <- c(10, 8, 6, 10, 5, 8, 7, 6, 10, 12, 11, 6, 8, 10, 5, 7, 9, 
             12, 6, 8, 9, 10, 7, 8, 11)
arm <- c(rep("choice", 13), rep("random", 12))
treatment <- c(rep(1, 5), rep(2, 8), rep(1, 6), rep(2, 6))
d <- data.frame(outcome=outcome, treatment=treatment, arm=arm)
preference(outcome ~ treatment:arm, d)

# Stratified
random <- c(rep(FALSE, 13), rep(TRUE, 12))
treatment <- c(rep(1, 5), rep(2, 8), rep(1, 6), rep(2, 6))
strata <- c(1,1,2,2,2,1,1,1,1,2,2,2,2,1,1,1,2,2,2,1,1,1,2,2,2)
d <- data.frame(outcome=outcome, treatment=treatment, arm=arm, 
                strata=strata)
preference(outcome ~ treatment:arm|strata, d, alpha=0.1)

Create a Preference Trial

Description

Create a Preference Trial

Usage

preference.trial(
  pref_ss,
  pref_effect,
  selection_ss,
  selection_effect,
  treatment_ss,
  treatment_effect,
  sigma2,
  pref_prop,
  choice_prop = 0.5,
  stratum_prop = 1,
  alpha = 0.05,
  k = 1
)

Arguments

References

Turner RM, et al. (2014). "Sample Size and Power When Designing a Randomized Trial for the Estimation of Treatment, Selection, and Preference Effects." Medical Decision Making, 34:711-719. (PubMed)

Cameron B, Esserman D (2016). "Sample Size and Power for a Stratified Doubly Randomized Preference Design." Stat Methods Med Res. (PubMed)

Examples

# Unstratified single trial.
preference.trial(pref_ss=100, pref_effect=1, selection_ss=100, 
  selection_effect=1, treatment_ss=100, treatment_effect=1,
  sigma2=1, pref_prop=0.6)

# Stratified single trial.
preference.trial(pref_ss=100, pref_effect=1, selection_ss=100,
  selection_effect=1, treatment_ss=100, treatment_effect=1,
  sigma2=list(c(1, 0.8)), pref_prop=list(c(0.6, 0.3)),
  choice_prop=0.5, stratum_prop=list(c(0.3, 0.7)))

# Multiple trials unstratified.
preference.trial(pref_ss=100, pref_effect=seq(0.1, 2, by=0.5), 
  selection_ss=100, selection_effect=1, treatment_ss=100, 
  treatment_effect=1, sigma2=1, pref_prop=0.6)

# Multiple, stratified trials.
preference.trial(pref_ss=100, pref_effect=seq(0.1, 2, by=0.5), 
  selection_ss=100, selection_effect=1, treatment_ss=100, 
  treatment_effect=1, sigma2=list(c(1, 0.8)), pref_prop=list(c(0.6, 0.3)), 
  choice_prop=0.5, stratum_prop=list(c(0.3, 0.7)))

Design Preference Trials with Power Constraint(s)

Description

Create a set of preference trials with specified power. The power parameter guarantees that the power will be at least what is specified for each of the three arms.

Usage

pt_from_power(
  power,
  pref_effect,
  selection_effect,
  treatment_effect,
  sigma2,
  pref_prop,
  choice_prop = 0.5,
  stratum_prop = 1,
  alpha = 0.05,
  k = 1
)

Arguments

Examples

# Unstratified trials with power constraints.
pt_from_power(power=seq(.1, 0.8, by=0.1), pref_effect=1, selection_effect=1, 
  treatment_effect=1, sigma2=1, pref_prop=0.6)

# Stratified trials with power constraints. Note that the proportion
# of patients in the choice arm (choice prop) is fixed for all strata.
pt_from_power(power=seq(0.1, 0.8, by=0.1), pref_effect=1, 
  selection_effect=1, treatment_effect=1,
  sigma2=list(c(1, 0.8)), pref_prop=list(c(0.6, 0.3)),
  choice_prop=0.5, stratum_prop=list(c(0.3, 0.7)))

# or...

pt_from_power(power=seq(0.1, 0.8, by=0.1), pref_effect=1, 
  selection_effect=1, treatment_effect=1,
  sigma2=c(1, 0.8), pref_prop=c(0.6, 0.3),
  choice_prop=0.5, stratum_prop=c(0.3, 0.7))

Design Preference Trials with Sample Size Constraint(s)

Description

Create a set of preference trials where the maximum sample size for an arm is specified.

Usage

pt_from_ss(
  ss,
  pref_effect,
  selection_effect,
  treatment_effect,
  sigma2,
  pref_prop,
  choice_prop = 0.5,
  stratum_prop = 1,
  alpha = 0.05,
  k = 1
)

Arguments

Examples

# Unstratified trials with power constraints.
pt_from_ss(ss=seq(100, 1000, by=100), pref_effect=1, 
  selection_effect=1, treatment_effect=1, sigma2=1, pref_prop=0.6)

# Stratified trials with power constraints. Note that the proportion
# of patients in the choice arm (choice prop) is fixed for all strata.
pt_from_ss(ss=seq(100, 1000, by=100), pref_effect=1, 
  selection_effect=1, treatment_effect=1,
  sigma2=list(c(1, 0.8)), pref_prop=list(c(0.6, 0.3)),
  choice_prop=0.5, stratum_prop=list(c(0.3, 0.7)))

# or...

pt_from_ss(ss=seq(100, 1000, by=100), pref_effect=1, 
  selection_effect=1, treatment_effect=1,
  sigma2=c(1, 0.8), pref_prop=c(0.6, 0.3),
  choice_prop=0.5, stratum_prop=c(0.3, 0.7))

Power Calculation from Sample Size

Description

Calculates the study power to detect a set of effects given a particular sample size in a two-stage randomized clinical trial

Usage

pwr_overall_pois(
  N,
  phi,
  lambda11,
  lambda22,
  lambda1,
  lambda2,
  alpha = 0.05,
  theta = 0.5,
  xi = 1,
  nstrata = 1
)

Arguments

Examples

# Unstratified
pwr_overall_pois(N=400, phi=0.5, lambda11=0.8, lambda22=0.5, lambda1=0.5, lambda2=0.4)
# Stratified
pwr_overall_pois(N=400, phi=c(0.5,0.5), lambda11=c(0.7,0.8), lambda22=c(0.4,0.4), 
lambda1=c(0.5,0.4), lambda2=c(0.2,0.3), xi=c(0.3,0.7), nstrata=2)

Preference trial parameter accessors

Description

Accessor function have been created to get the sample size (sample_size), power (power), effect size (effect_size), arm proportion (proportion), significance (significance), and trial variance estimates (sigma2) for a set of preference trials.

Note that these methods are preferred over accessing the underlying data frame directly since the structure is slightly non-standard (some columns are lists) and some values, like power, are not stored directly.

Usage

sample_size(x)

## S3 method for class 'preference.trial'
sample_size(x)

power(x)

## S3 method for class 'preference.trial'
power(x)

effect_size(x)

## S3 method for class 'preference.trial'
effect_size(x)

proportion(x)

## S3 method for class 'preference.trial'
proportion(x)

significance(x)

## S3 method for class 'preference.trial'
significance(x)

sigma2(x)

## S3 method for class 'preference.trial'
sigma2(x)

Arguments

Examples

# Create a set of trials with a sequence of preference effects.
trials <- preference.trial(pref_ss=100, pref_effect=seq(0.1, 2, by=0.5), 
                           selection_ss=100, selection_effect=1, 
                           treatment_ss=100, treatment_effect=1, sigma2=1, 
                           pref_prop=0.6)

# the sample sizes
sample_size(trials)

# the powers
power(trials)

# the effect sizes
effect_size(trials)

# the arm proportions
proportion(trials)

# the significance
significance(trials)

# the variance estimates
sigma2(trials)

Treatment Effect Back Calculation

Description

Calculates the treatment effect that can be detected given a desired study power and overall study sample size for the two-stage randomized design

Usage

treatment_effect_size(
  N,
  power,
  sigma2,
  alpha = 0.05,
  theta = 0.5,
  xi = 1,
  nstrata = 1
)

Arguments

Examples

treatment_effect_size(N=300, power=0.9, sigma2=c(1,0.8), xi=c(0.3,0.7), 
                      nstrata=2)