R: Model the reduction of faecal egg count

fecr_stan {eggCounts}

R Documentation

Model the reduction of faecal egg count

Description

Models the reduction in faecal egg counts with Bayesian hierarchical models. See Details for a list of model choices.

Usage

fecr_stan(preFEC, postFEC, rawCounts = FALSE, preCF = 50, postCF = preCF, 
  paired = TRUE, indEfficacy = TRUE, zeroInflation = FALSE, 
  muPrior, kappaPrior, deltaPrior, phiPrior, deltakappaPrior,
  nsamples = 2000, nburnin = 1000, thinning = 1, nchain = 2, 
  ncore = 1, adaptDelta = 0.95, saveAll = FALSE, verbose = FALSE)

Arguments

`preFEC`	numeric vector. Pre-treatment faecal egg counts.
`postFEC`	numeric vector. Post-treatment faecal egg counts.
`rawCounts`	logical. If TRUE, `preFEC` and `postFEC` correspond to raw counts (as counted on equipment). Otherwise they correspond to calculated epgs (raw counts times correction factor). Defaults to `FALSE`.
`preCF`	a positive integer or a vector of positive integers. Pre-treatment correction factor(s).
`postCF`	a positive integer or a vector of positive integers. Post-treatment correction factor(s).
`paired`	logical. If TRUE, uses the model for the paired design. Otherwise uses the model for the unpaired design
`indEfficacy`	logical. If TRUE, uses the paired model allowing for individual efficacy. Only use in combination with `paired = TRUE` and `zeroInflation = FALSE`.
`zeroInflation`	logical. If TRUE, uses the model with zero-inflation. Otherwise uses the model without zero-inflation.
`muPrior`	a named list. Prior for the group mean epg parameter `\mu`. The default prior is `list(priorDist = "gamma", hyperpars = c(1,0.001))`, i.e. a gamma distribution with shape 1 and rate 0.001, its 90% probability mass lies between 51 and 2996.
`kappaPrior`	a named list. Prior for the group dispersion parameter `\kappa`. The default prior is `list(priorDist = "gamma", hyperpars = c(1,0.7))`, i.e. a gamma distribution with shape 1 and rate 0.7, its 90% probability mass lies between 0.1 and 4.3 with a median of 1.
`deltaPrior`	a named list. Prior for the reduction parameter `\delta`. The default prior is `list(priorDist = "beta", hyperpars = c(1,1))`, i.e. a uniform prior between 0 and 1.
`phiPrior`	a named list. Prior for the zero-inflation parameter `\phi`. The default prior is `list(priorDist = "beta", hyperpars = c(1,1))`, i.e. a uniform prior between 0 and 1.
`deltakappaPrior`	a named list. Prior information for the shape parameter of reduction `\delta_\kappa`. The default prior is `list(priorDist = "normal",hyperpars=c(2,1))`. Only used if `indEfficacy = TRUE`.
`nsamples`	a positive integer. Number of samples for each chain (including burn-in samples).
`nburnin`	a positive integer. Number of burn-in samples.
`thinning`	a positive integer. Thinning parameter, i.e. the period for saving samples.
`nchain`	a positive integer. Number of chains.
`ncore`	a positive integer. Number of cores to use when executing the chains in parallel.
`adaptDelta`	numeric. The target acceptance rate, a numeric value between 0 and 1.
`saveAll`	logical. If TRUE, posterior samples for all parameters are saved in the `stanfit` object. If FALSE, only samples for `\delta`, `\mu`, `\kappa` and `\phi` are saved. Default to FALSE.
`verbose`	logical. If TRUE, prints progress and debugging information.

Details

List of built-in models

unpaired without zero-inflation: set paired = FALSE, indEfficacy = FALSE, zeroInflation = FALSE
unpaired with zero-inflation: set paired = FALSE, indEfficacy = FALSE, zeroInflation = TRUE
paired without zero-inflation: set paired = TRUE, indEfficacy = FALSE, zeroInflation = FALSE
paired with zero-inflation: set paired = TRUE, indEfficacy = FALSE, zeroInflation = TRUE
paired with individual efficacy: set paired = TRUE, indEfficacy = TRUE, zeroInflation = FALSE

Prior choice

Consider using non-default prior for \delta when,

there is on average an increase in egg counts after treatment
there are divergent-sample warnings
there are non-convergence warnings

Two examples of useful non-default priors include:

list(priorDist = "normal", hyperpars = c(1, 5)) for stablizing the reduction parameter without being informative.
list(priorDist = "beta", hyperpars = c(0, 5)) for allowing up to 4-fold increase of egg count after treatment.

Other information

The first time each model with non-default priors is applied, it can take up to 20 seconds to compile the model. Currently the function only support prior distributions with two parameters. For a complete list of supported priors and their parameterization, please consult the list of distributions in Stan User Guide.

The default number of samples per chain is 2000, with 1000 burn-in samples. Normally this is sufficient in Stan. If the chains do not converge, one should tune the MCMC parameters until convergence is reached to ensure reliable results.

Value

Prints out the posterior summary of FECR as the reduction, meanEPG.untreated as the mean pre-treatment epg, and meanEPG.treated as the mean after-treatment epg. The posterior summary contains the mean, standard deviation (sd), 2.5%, 50% and 97.5% percentiles, the 95% highest posterior density interval (HPDLow95 and HPDHigh95) and the posterior mode.

NOTE: Based on our simulation studies, we recommend to use (2.5%, 97.5%) as the 95% credible interval and the median as summary statistics of reduction for the individual efficacy model. For all other models, we recommend to use the 95% HPD interval and the mode.

The returned value is a list that consists of:

`stan.samples`	an object of S4 class `stanfit` representing the fitted results
`posterior.summary`	a data.frame that is the same as the printed posterior summary

Author(s)

Craig Wang

References

Individual efficacy models: Craig Wang, Paul R. Torgerson, Ray M. Kaplan, Melissa M. George, Reinhard Furrer. (2018) Modelling anthelmintic resistance by extending eggCounts package to allow individual efficacy, International Journal for Parasitology: Drugs and Drug Resistance, Volume 8, Pages 386-393. <doi:10.1016/j.ijpddr.2018.07.003>

Zero-inflation models: Craig Wang, Paul R. Torgerson, Johan Hoglund, Reinhard Furrer. (2017) Zero-inflated hierarchical models for faecal egg counts to assess anthelmintic efficacy, Veterinary Parasitology, Volume 235, Pages 20-28. <doi:10.1016/j.vetpar.2016.12.007>

Other models: Paul R. Torgerson, Michaela Paul, Reinhard Furrer. (2014) Evaluating faecal egg count reduction using a specifically designed package 'eggCounts' in R and a user friendly web interface, International Journal for Parasitology, Volume 44, Pages 299-303. <doi:10.1016/j.ijpara.2014.01.005>

Examples

## load sample data
data(epgs)

## apply individual efficacy model to the data vectors
model <- fecr_stan(epgs$before, epgs$after, rawCounts = FALSE, preCF = 50, 
                   paired = TRUE, indEfficacy = TRUE)
## convert to MCMC object and inspect the summary
samples <- stan2mcmc(model$stan.samples)
summary(samples)

[Package eggCounts version 2.4 Index]