1. System requirements

The clinical trial simulator (CTS) is written in R (1) which is freely available for installation on Windows, Mac OS and Linux platforms from https://www.r-project.org. It is also recommended to install R Studio https://www.rstudio.com which provides a helpful user interface for R. The CTS has been tested on Mac OS but should be compatible with Windows and Linux and run on any desktop or laptop machine.

2. Installation guide

The model code can be downloaded and installed directly from a GitHub repository (https://github.com/mrc-ide/EPIONCHO-IBM-CTS). The RCurl (2) package must be installed to do this. Installation should take no more than a few seconds on most desktop or laptop machines.

install.packages("RCurl")
script <- RCurl::getURL("https://raw.githubusercontent.com/mrc-ide/EPIONCHO-IBM-CTS/master/EPIONCHO-IBM-CTS.R", ssl.verifypeer = FALSE)
eval(parse(text = script))

3. Demo

3.1 Simulating equilibrium conditions

It is best to run the CTS to equilibrium (get.equib=1), save the output and use this as the starting point for simulating clinical trials, including repeated simulations of trials with different designs (e.g. different number of treatments, different participant eligibility criteria, etc.). This is an efficient way of simulating different trials conducted in (hypothetically) identical transmission settings. The default parameters run the model for 50 years (stop.time=50) to simulate equilibrium conditions. The transmission setting is defined by the annual biting rate (ABR) which here is set to 1,000 (ABR=1000). The human population size is set to 1,000 (N=1000). Note that running to equilibrium can be quite slow, taking in excess of 5-6 minutes (depending on machine performance). Setting print.progress=1 allows monitoring of progress.

equib <- run.mod(get.equib = 1, stop.time=50, ABR=1000, N=1000, print.progress = 0)

3.2 Clinical trial simulation

Parameters relevant to the trial design are passed to the simulator via a clin.trial list argument of the run.mod function. The exception is the num.ss parameter for the number of skin snips taken per participant which is passed outside of the list (alongside other parameters of the underlying transmission model). It is also important to set get.equib=0 and to pass the equilibrium conditions to the simulator by setting input.eq=equib.

As an example, the following code simulates a clinical trial of a single dose (n.trt.trial=1) of a macrofilaricidal only macrofilaricide (MOM=1), with 90% efficacy (macro.eff=0.9), applying the inclusion criteria of participants having > 2 microfilariae (mf) per milligram (min.mf=2) and being at least 18 years old (min.age=18). The target sample size for the trial is 50, (target.ss=50) with a 10% loss to follow up per year (drop.out=0.1). The response is measured by taking 2 skin snips per participant (num.ss=2) and the follow up time is three years (stop.trial=4 - start.trial=1). It is also important to change stop.time=50 to stop.time=4 so that the simulation stops when the trial stops (although it certain circumstances it may be useful to allow simulations to continue beyond the immediate timeframe of the trial)

cts <- run.mod(get.equib = 0, input.var=1, input.eq = equib, stop.time=4, ABR=1000, N=1000, num.ss=2,give.treat = 0, clin.trial = list(MOM=1, macro.t=3/12, macro.eff=0.90, start.trial=1, stop.trial=4, n.trt.trial=1, trial.int=1,min.age=18, target.ss=50, min.mf=0, drop.out=0.1), print.progress=0)

3.3 Visualisation

The CTS returns a number of outputs which can be viewed using str(cts). The outputs of principal interest are the mean intensity of mf (per mg) and the prevalence of mf in the ivermectin-treated control and macrofilaricide-treated test cohorts. It is also informative to plot the dynamics of infection in the population as a whole. The following code can be used to plot the dynamics of response measures (mf intensity and prevalence) in the ivermectin-treated and macrofilaricide-treated cohorts, alongside the population-wide parasite dynamics.

par(mfrow=c(1,2), xpd=NA)
col.ivm <- rgb(136, 86, 167, max=255)
col.mac <-  rgb(227,74,51, max=255)
col.pop <- "grey"
plot(cts$mn.mf.ss.cohort.2 ~ I(cts$t-1), type="l", col=col.mac, 
     xlab="years since start of trial", ylab = "mean microfilarial intensity (mf / mg)", bty="n", 
     ylim=c(0,14))
lines(cts$mn.mf.ss.cohort.1 ~ I(cts$t-1), type="l", col=col.ivm)
lines(cts$mn.mf.ss~I(cts$t-1), col= col.pop)
legend(0.2,15, legend=c("ivermectin-treated cohort", "macrofilaricide-treated cohort", "population"), lwd=1, 
       col=c(col.ivm, col.mac, col.pop), bty="n")
plot(I(cts$prev.ss.cohort.1)*100 ~ I(cts$t-1), type="l", col=col.ivm, 
     xlab="years since start of trial", ylab = "microfilarial prevalence (%)", 
     bty="n")
lines(I(cts$prev.ss.cohort.2)*100 ~ I(cts$t-1), type="l", col=col.mac)
lines(I(cts$pr.mf.ss)*100~I(cts$t-1), col= col.pop)

4. Further instructions for use

The demo illustrates how to use the CTS to simulate a relatively simple trial design. More complex designs and scenarios can be simulated, including repeated rounds of treatment and trials conducted in communities with past and ongoing MDA with ivermectin.

4.1 Repeated treatments

Repeated treatments can be simulated by changing the n.trt.trial and trial.int parameters, the former specifying the number of treatments to be given and the latter the interval (in years) between treatments. For example, the following code simulates a trial where both the MOM and ivermectin are given three times to the participant cohorts at yearly intervals. The code for plotting the output is not shown here but can be reproduced by substituting cts with cts.multi in the data visualisation code above.

cts.multi <- run.mod(get.equib = 0, input.var=1, input.eq = equib, stop.time=4, ABR=1000, N=1000, num.ss=2,give.treat = 0, clin.trial = list(MOM=1, macro.t=3/12, macro.eff=0.90, start.trial=1, stop.trial=4, n.trt.trial=3, trial.int=1,min.age=18, target.ss=50, min.mf=0, drop.out=0.1), print.progress=0)

4.2 Trials conducted in a backdrop of MDA

The parameters (outside of the clin.trial list) treat.start, n.trt and trt.int define the start time of MDA, the number of treatments to be simulated and the interval (in years) between treatments respectively. For example, the following code will simulate a (single treatment) trial of a macrofilaricide initiated six months after the last round of MDA (with ivermectin) in a community with a prior history of a single round of MDA. Participants are followed up within the community while MDA continues annually.

cts.MDA <- run.mod(get.equib = 0, input.var=1, input.eq = equib, stop.time=4.5, ABR=1000, N=1000, num.ss=2,give.treat = 1, treat.start = 1, n.trt=3, treat.int=1, clin.trial = list(MOM=1, macro.t=3/12, macro.eff=0.90, start.trial=1.5, stop.trial=4.5, n.trt.trial=1, trial.int=1,min.age=18, target.ss=50, min.mf=0, drop.out=0.1), print.progress=0)

1. R Core Team. R: A language and environment for statistical computing. (R Foundation for Statistical Computing, 2018).

2. Lang, D. T. & CRAN team. RCurl: General network (http/ftp/...) client interface for r. (2019).