Package 'fahb'

Plot prior distributions

Description

Given the hyperparameters encoded in a fahb_problem object, return plots of the three prior distributions and a plot of the prior predictive distribution of the recruitment rate at a randomly selected site.

Usage

check_priors(problem)

Arguments

problem

an object of class fahb_problem.

Value

a list of ggplot2 plots.

Examples

problem <- fahb_problem()
check_priors(problem)

---

Build a fahb analysis object

Description

Given a fahb_problem object calculate summary statistics which can inform progression decisions. These include both standard progression criteria statistics, and the expectation of the posterior predictive distribution of the time until the trial recruits.

Usage

fahb_analysis(n_pilot, t_pilot, problem, site_t = NULL, bayes_model = NULL)

Arguments

n_pilot	integer vector of numbers recruited at each open site.
t_pilot	numeric vector of time (in years) each site has been open.
problem	object of class fahb_problem.
site_t	In the case of an external pilot, the time taken for all pilot sites to open.
bayes_model	optional object of class brmsfit which will be used in the Bayesian analysis via brms::update() to avoid compiling a new model.

Value

An object of class fahb_analysis.

Examples

## Example illustrating a full analysis workflow
## (Not run on CRAN due to Bayesian model fitting)


problem <- fahb_problem()
problem <- forecast(problem)

## Pilot trial data
n_pilot <- c(3, 5, 2)
t_pilot <- c(0.5, 0.6, 0.4)

analysis <- fahb_analysis(
  n_pilot = n_pilot,
  t_pilot = t_pilot,
  problem = problem
)

print(analysis)
plot(analysis)

---

Build a fahb design object

Description

Given a fahb_problem object, find efficient progression decision rules. These can include rules of the standard "progression criteria form", or rules based on a Bayesian analysis of the pilot trial data, or both.

Usage

fahb_design(problem, quietly = TRUE)

Arguments

problem	an object of class fahb_problem.
quietly	if this argument is set to FASLE then information about which steps have been completed will be printed to the console. Defaults to TRUE.

Value

an object of class fahb_design.

Examples

problem <- forecast(fahb_problem(), n_sims = 500)
fahb_design(problem)

---

Build a fahb_problem object

Description

Given a trial design and a set of model hyperparameters, build an object of class fahb_problem.

Usage

fahb_problem(
  N = 320,
  m = 20,
  t = 0.5,
  n_ext = NULL,
  m_ext = NULL,
  rel_thr = 1.2,
  so_hps = c(30, 2.85),
  mean_rr_hps = c(2, 0.329),
  sd_rr_hps = c(30, 100)
)

Arguments

N	target sample size.
m	number of recruiting sites.
t	timing of the pilot analysis in years.
n_ext	number of participants to recruit to an external pilot.
m_ext	number of sites to open in an external pilot.
rel_thr	threshold which discriminates feasible and infeasible trials, as a multiple of the expected time to recruit.
so_hps	site opening rate hyperparameters (shape and rate for a Gamma prior).
mean_rr_hps	mean site recruitment rate hyperparameters (mean and sd for a lognormal prior).
sd_rr_hps	variance in site recruitment rates hyperparameters (shape and rate for a Gamma prior).

Value

an object of class fahb_problem

Examples

fahb_problem()

---

Generate probabilistic forecasts of trial recruitment

Description

Generate probabilistic forecasts of trial recruitment

Usage

forecast(problem, n_sims = 10^4, overwrite = FALSE)

Arguments

problem	an object of class fahb_problem.
n_sims	number of replicates to use in the simulation.
overwrite	boolean indicating if we want to overwrite any simulation data currently held (defaults to FALSE).

Value

an object of class fahb_problem.

Examples

problem <- fahb_problem()
problem <- forecast(problem, n_sims = 10^3)

---

Plot posterior distributions from a fahb analysis

Description

Takes an object of class fahb_analysis and plots the posterior distributions of the predicted time for the trial to recruit and of the three model parameters.

Usage

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

Arguments

x	object of class fahb_analysis as produced by ⁠fahb_analysis().⁠
...	further arguments passed to or from other methods.

Value

no return value, called for side effects.

---

Plot operating characteristics of fahb designs

Description

Takes an object of class fahb_design and plots the estimated operating characteristics of decision rules - based on standard progression criteria, an approximate Bayesian analysis, or both.

Usage

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

Arguments

x	object of class fahb_design as produced by ⁠fahb_design().⁠
...	further arguments passed to or from other methods.

Value

no return value, called for side effects.

---

Print a fahb analysis object

Description

The default print method for a fahb_analysis object.

Usage

## S3 method for class 'fahb_analysis'
print(x, ...)

Arguments

x	object of class fahb_analysis as produced by fahb_analysis().
...	further arguments passed to or from other methods.

Value

no return value, called for side effects.

---

Print a fahb design object

Description

The default print method for a fahb_design object.

Usage

## S3 method for class 'fahb_design'
print(x, coarse = TRUE, ...)

Arguments

x	object of class fahb_design as produced by fahb_design().
coarse	binary indicator that only a coarse subset of all decision rules should be printed. Defaults to TRUE.
...	further arguments passed to or from other methods.

Value

no return value, called for side effects.

---