Title: Design and Analysis of Pilot Trials Assessing Recruitment Feasibility
Version: 1.0.0
Description: Find optimal decisions rules for guiding progression decisions following a pilot trial, assuming a hierarchical recruitment model. Estimate the time until the main trial recruits to target, given the recruitment data observed in the pilot.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.3
Suggests: BH, knitr, patchwork, RcppEigen, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Imports: brms, ggplot2, mco, mgcv, posterior, rlang
VignetteBuilder: knitr
URL: https://dtwilson.github.io/fahb/, https://github.com/DTWilson/fahb
BugReports: https://github.com/DTWilson/fahb/issues
NeedsCompilation: no
Packaged: 2026-04-28 15:01:50 UTC; meddwilb
Author: Duncan Wilson ORCID iD [aut, cre, cph]
Maintainer: Duncan Wilson <d.t.wilson@leeds.ac.uk>
Repository: CRAN
Date/Publication: 2026-04-29 08:00:02 UTC

fahb: Feasibility Assessment with Hierarchical Bayes

Description

Tools for simulation, design, and analysis of internal pilot trials using frequentist and Bayesian operating characteristics.

Author(s)

Maintainer: Duncan Wilson d.t.wilson@leeds.ac.uk (ORCID) [copyright holder]

See Also

Useful links:

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.