---

title: "biomkrAccrual"

author: "SJ Cowtan"

date: 2024-10-01

date-format: YYYY

output: 

  - rmarkdown::html_vignette

vignette: >

  %\VignetteIndexEntry{biomkrAccrual}

  %\VignetteEngine{knitr::rmarkdown}

  %\VignetteEncoding{UTF-8}

---

```{r, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>"

)

```

```{r setup}

library(biomkrAccrual)

```

Simulating recruitment at time of randomisation to adaptive trials with 

arm eligibility determined by biomarker status.

The `{biomkrAccrual}` package uses a Poisson-Gamma-Dirichlet model to simulate

trial recruitment for multi-site, multi-region, multi-arm trials. Recruitment per 

site is modelled with the Poisson-Gamma model (Anisimov and Federov, 2007).

A hierarchical Dirichlet model is used to model biomarker proportions for sites

within regions. Recruitment to a given site in a given week is then randomised

to biomarker status using the prevalences drawn from the Dirichlet model for that

site.

## Running a single simulation

`biomkrAccrual()`

The default settings will use the configuration files in the `extdata` directory, and will

keep the resulting data files and recruitment plots. The location can be specified with 

`output_path` and `figs_path`.

## Running a set of simulations

`biomkrAccrualSim(n = 250)`

The datafiles and recruitment plots from the individual runs will not be kept (this

can be changed with `quietly = FALSE`) but will preserve the summary datafiles and

distribution plots.

## Practical notes

There are a very large number of arguments to both commands, and three configuation files,

one of which (the relationship of treatment arms to biomarker recruitment arms) is a JSON.  

This is because flexibility is required, and they are intended to be driven by a dashboard 

in future.

This package will not pass R CMD Check because it is written using the new object orientation 

system for R, `{S7}`, and CMD Check does not yet understand the syntax.

Anisimov, V.V., Fedorov, V.V., 2007. Modelling, prediction and adaptive adjustment of 

recruitment in multicentre trials. Statistics in Medicine 26, 4958–4975. 

https://doi.org/10.1002/sim.2956