PoolTestR is an R package with tools for working with pooled or grouped samples, initially inspired by the stand-alone software, ‘PoolScreen’. The package can be used to perform the same analyses as PoolScreen i.e. estimate the prevalence of a marker in the population based on tests performed on pooled samples. In our package, the estimates of prevalence can also be adjusted to account for the hierarchical sampling designs that are often used for molecular xenomonitoring studies. Taking this a step further, our package enable users to perform to mixed effect regression to identify covariates associated with the outcome of interest, estimate odds ratios, and predict prevalence. Analyses are available in both frequentist and Bayesian frameworks.
More features are planned or in the works: spatial mapping; models for combining and comparing results from human-based and vector-based surveillance, adjustments for imperfect test specificity/sensitivity; functions for helping with optimal experimental design; functions for inferring whether a disease has been locally eliminated from a series of pooled tests over time. Suggestions and contributions are welcome.
The details of our package are described in an article published in Environmental Modelling and Software. We are happy to share a pdf of this article with you on request.
We also have a graphical user interface to PoolTestR available called PoolTools. PoolTools is a shiny web app that facilitates analyses of pool-tested data using functions from PoolTestR.
If you find this package helpful, please let us know – we’d love to hear how it’s being used.
There are three ways to download and install PoolTestR:
To use the full functionality of the package, including running Bayesian regression models, you will need to install PoolTestR from source (see the Advanced Installation section below).
We release official versions of PoolTestR on CRAN and on GitHub.
The development versions of PoolTestR can be used by installing PoolTestR from R-universe or GitHub.
Instructions to install PoolTestR through each of these methods are listed below. These instructions have been tested on Windows, Linux, and Mac (both Intel and Apple Silicon chips). Please get in touch if you have problems with installation.
To install the latest official release of PoolTestR from CRAN (the official repository for R packages), use the following command in R:
# Install PoolTestR from CRAN
install.packages("PoolTestR")This will install an old version of PoolTestR that lacks the latest
features. In addition, Bayesian regression modelling (via function
PoolRegBayes) may require you to install additional
software.
You can download development versions of PoolTestR from the angusmclure universe on R-universe.
Visit PoolTestR on R-universe here.
R-universe contains binaries for the current master
branch of the PoolTestR GitHub repository. Usually, the binaries on
R-universe are updated within a few hours of each new commit to the
master branch of PoolTestR.
# Install PoolTestR from R-universe
install.packages("PoolTestR", repos = c("https://angusmclure.r-universe.dev"))To use the full functionality of the package, including running
Bayesian regression models, you will need either RTools
(for Windows) or macrtools (for Mac OS). You will also need
the latest versions of two packages, StanHeaders and
rstan.
Download the necessary software for your operating system:
Windows:
Install RTools for Windows following the instructions here.
Mac OS:
Install the R package macrtools following the
instructions here
# From macrtools documentation, retrived 18/10/2024
# install.packages("remotes")
remotes::install_github("coatless-mac/macrtools")Use macrtools to install the required components (XCode
CLI, gfortran, and R Development binaries from the Recipes project)
following the instructions here
# From macrtools documentation, retrived 18/10/2024
macrtools::macos_rtools_install()Stanheaders and rstanInstall latest version of Stanheaders and
rstan with:
install.packages("StanHeaders", repos = c("https://mc-stan.org/r-packages/", getOption("repos")))
install.packages("rstan", repos = c("https://mc-stan.org/r-packages/", getOption("repos")))PoolTestR.To also install the most up-to-date version of PoolTestR
directly from GitHub, in addition to the above steps also run:
install.packages("devtools") # you can skip this if you already have devtools installed
options(timeout = 300) # increases time-limit for downloading package to 300 seconds (for slow connections)
devtools::install_github("AngusMcLure/PoolTestR")If installing from source (the only option if installing from GitHub) this will take some time (really depends on your machine, perhaps up to an hour) and probably produce a lot of text in your R console. The text is related to the compilation of stan source code.
If installing from CRAN (basic installation) installation should be very fast and not generate any warning messages.
Note: In the past, some Windows users needed to
adjust some settings (in the Makevars file) to install the
package correctly, because of issues in other packages on which
PoolTestR relies. These other packages have addressed these issues in
most cases, so manual adjustments shouldn’t be needed. However,
future updates may break this.
Please let us know if you have issues with installation.
The following provides some examples of how to use the core functionality of the package to estimate prevalence. You can copy and paste the code into your R console to see it run.
Start by loading the package: (If this doesn’t work this means installation was not successful. Please let us know if this happens for you)
library(PoolTestR)Now it’s time to load up data into R using read.csv() or
a similar function. Each line of the dataset should contain the details
of a single pooled test. At minimum this must include: * the the number
of specimens in the pool * and the result of the test
Instead of working with real data, for this example we’ll be using a
simulated dataset called SimpleExampleData that’s included
with the package. The synthetic dataset consists of pools (sizes 1, 5,
or 10) taken from 4 different regions and 3 different years. Within each
region 4 villages are selected, and within each selected village 8 sites
are selected for the collection of specimens, i.e. a hierarchical
sampling frame. Take a look at the first few rows of the data:
head(SimpleExampleData)We begin by using the function PoolPrev to estimate the
prevalence across the whole dataset i.e. a single prevalence for all
locations and years. The first argument to PoolPrev is the
data (in our case SimpleExampleData). The second argument
is the name of the column in the data containing the result of the test
(in our case Result): the entries in this column must be 0
for negative pool tests and 1 for a positive pool tests and cannot be
missing. The third argument is the name of the column with the number of
specimens/isolates/insects in each pool (in our case
NumInPool)
PrevWholeDataset <- PoolPrev(SimpleExampleData,Result,NumInPool)
PrevWholeDataset The output contains a maximum likelihood estimate of the prevalence with 95% confidence intervals and a Bayesian estimate (Jeffrey’s prior) with 95% credible intervals. It also contains the total number of pools and the number of these that were positive.
PoolTestR allows us to use different variables within the dataset to stratify (i.e., partition) data before estimating prevalence.
If we want to estimate prevalence separately for each region we
simply include Region as an additional argument
PrevByRegion <- PoolPrev(SimpleExampleData, Result, NumInPool, Region)
PrevByRegionIf we want to estimate prevalence at the level of villages:
PrevByVillage <- PoolPrev(SimpleExampleData, Result, NumInPool, Village)
PrevByVillageSimilarly if we want to estimate prevalence separately for each year (but ignoring differences between places):
PrevByYear <- PoolPrev(SimpleExampleData, Result, NumInPool, Year)
PrevByYearIf we want to estimate prevalence separately for each combination of region AND year:
PrevByRegionYear <- PoolPrev(SimpleExampleData, Result, NumInPool, Region, Year)
PrevByRegionYearIf we had more variables we wanted to group the data by (e.g. climate, season, sex, age…) we could keep on adding the appropriate column names to the function call. But remember that the more groups you split your data into, the fewer samples in each group which will usually lead to wider confidence/credible intervals.
In some cases it may be appropriate to use a regression framework to
estimate prevalence and adjust for variables (such as year) instead of
stratifying. The following fits a logistic-type regression model
treating region as a categorical variable and Year as an ordinal (with
linear trend on the logit scale). The inputs follow the same pattern as
the glm function, with an additional argument for the the
pool sizes.
Model <- PoolReg(Result ~ Year + Region, SimpleExampleData, NumInPool)
summary(Model)We can use the getPrevalence function to extract or
predict prevalence based off the regression model:
getPrevalence(Model)So far we have ignored the hierarchical sampling structure implicit in our data (i.e. villages within regions and sites within villages). As there is likely to be some spatial variation in prevalence between sample sites it is best practice to account for this. One way to do this is to use a hierarchical model. Failing to do so may produce biased or overconfident estimates of the prevalence (i.e. confidence intervals will be unreasonably narrow). This is straightforward with
The hierarchical counterpart to ```PoolPrev``` is ```HierPoolPrev```, which
takes a single additional argument with the names of the columns defining the
hierarchy. Note: the function assumes that in the data every location is
uniquely identified, e.g. village ID for village 1 in region A should be
something like "A-1", not simply "1". To estimate the prevalence for the whole
population adjusting for hierarchical sampling frame but ignoring Year:
```R
PrevByHier <- HierPoolPrev(SimpleExampleData, Result, NumInPool,
c("Village","Site"))
PrevByHierTo also stratify by Year
PrevByYearHier <- HierPoolPrev(SimpleExampleData, Result, NumInPool,
c("Village","Site"), Year)
PrevByYearHierThe same kind of adjustments can be conducted in a regression framework, using mixed effect regression models. The following fits a mixed-effect regression model with Year and Region as fixed/population effects with a linear trend on the logit scale and Village and Site random/group effects:
HierModel <- PoolReg(Result ~ Year + Region + (1|Village) + (1|Site), SimpleExampleData, NumInPool)
summary(HierModel)
getPrevalence(HierModel)PoolTools is a
web app to analyse and design surveys with pool-tested data, using the R
packages PoolTestR and PoolPoweR. To
analyse data in PoolTools, select the Analyse option.
Documentation and tutorials are available at the PoolTools
wiki.
PoolTools makes certain statistical assumptions during data analysis. If the PoolTools default options are not appropriate for your analysis, we recommend using the PoolTestR R package instead.