jagsNEC-package: Package: jagsNEC Type: Package Title: No-Effect-Concentration...

In AIMS/NEC-estimation: A Bayesian No Effect Concentration (NEC) package. R package version 1. doi:10.5281/ZENODO.3966864

Package:	jagsNEC
Type:	Package
Title:	No-Effect-Concentration modelling with jags
Version:	1.0
Date:	2020-28-07
Author:	Rebecca Fisher
Maintainer:	Rebecca Fisher
License:	Apache 2
LazyLoad:	yes
Depends:	R2jags

Description

Bayesian model fitting can be difficult to automate across a broad range of usage cases, particularly with respect to specifying valid initial values and appropriate priors. This is one reason the use of Bayesian statistics for NEC estimation (or even ECx estimation) is not currently widely adopted across the broader ecotoxicological community, who rarely have access to specialist statistical expertise.

The jagsNEC package attempts to provide an accessible interface to the R2jags package specifically for fitting NEC models and other concentration-response models, with a range of models specified based on the known distribution of the "concentration" or "dose" variable (the predictor, x) as well as the "response" (y) variable.

The model formula, including priors and the init function required to call a jags model are automatically generated based on information contained in the supplied data. While the distribution of the x and y variables can be specified directly, jagsNEC will automatically 'guess' the correct distribution to use based on the characteristics of the provided data.

Specific models can be fit directly using fit.jagsNEC. Alternatively it is possible to fit a specific set or all of the available models using the function fit.jagsMANEC. The fit.jagsMANEC function returns a model weighted estimate of predicted posterior values, based on deviance information criteria (DIC) model weights, analogous to the way model weights are generated using AIC or AICc. It is also possible to obtain all individual model fits from the fitted jagsMANECfit model object if required. Multi-model inference can be useful where there are a range of plausible models that could be used and has been recently adopted in ecotoxicology for SSD model inference.

An additional endpoint has also been derived using Bayesian posterior predicted values to estimate the "No-Statistical-Effect-Concentration" as the concentration at which predicted values for each MCMC chain fall below a lower percentile bound (defined as sig.val) of the control, which is assumed to be the lowest treatment (x.var) concentration in the data. NSEC estimates are currently used to approximate NEC for models without a specific NEC step parameter (in jagsNEC these have the prefix ECx in their model name). Note that this endpoint definition has not been tested and peer reviewed, and should not currently be used in reporting. NEC values should only be reported for NEC model types.

Important information on the current package build is contained in the jagsNEC and jagsMANEC helpfiles (see ?jagsNEC and ?jagsMANEC).

Details

This package is currently under development. Your are using the beta version and there may be unexpected behaviour. Please do not use, report on, or otherwise rely on the outputs of this package unless they have been verified as valid by someone knowledgeable in statistics and you are confident that the results are valid.

We are keen on any feedback regarding usage, and especially bug reporting that includes an easy to run self contained reproducible example of either unexpected behaviour or example model fits that fail to converge (have poor chain mixing, yield other errors or just simply don't provide a fit that is intuitively consistent with visual inspection of the data). Such information will hopefully help us towards building a more robust package.

We cannot help troubleshoot issues if an easy to run reproducible example is not supplied.

Please see the github page for this pacakge for usage examples at https://github.com/AIMS/NEC-estimation

Note that jagsNEC by default tries to guess the distribution of both the y and x data, however these can be manually supplied (see ?fit.jagsNEC).

Note if the x data contain 0 but are otherwise gamma distributed, the x data are adjusted by adding 1/10^3 of the next smallest value to avoid errors in the jags fit.

Note that while an unsupported data type may run successfully, especially if the default behaviour of estimating the data type used, it is unlikely that the desired model specification has been fit. jagsNEC writes out the jags model file that has been used. You can find this in your project working directory labelled as NECmod.txt to inspect the fitted model, including the likelihood function used for the response variable as well as the values used for the priors on the parameters.

Note while jagsNEC tries to set sensible prior values and build robust initial starting functions, this is difficult to achieve across a range of models in practice. You may have better results by adjusting these yourself directly in jags if you are able.

jagsNEC will first attempt to fit a model using the model file and init.fun generated by write.jags.NECmod. n.tries is used to specify the number of attempt to try with the custom init.fun. If all n.tries fail, or do not meet the specified chain mixing criteria, jagsNEC will then try another n.tries times to fit the model using the default initial values in jags. If all attempts fail an error will be returned. If there are valid attempts, all are stored in a list and returned with the final model output (all.Js). The current behaviour is for the final selected model in that case to be either the first to meet the specified chain mixing criteria, or if none meet the criteria, the fit with the best chain mixing (as defined as the lowest ratio of between to within chain coefficient of variation) is returned.

As noted above, the package is in beta and entirely experimenal. Please provide any positive feedback, suggestions, requests and criticisms.

Author(s)

Rebecca Fisher and Gerard Ricardo (Australian Institue of Marine Science); David Fox (Environmetrics Australia)

Maintainer: Rebecca Fisher [e-mail]

References

https://github.com/AIMS/NEC-estimation

Examples

install.packages("jagsNEC", dependencies = TRUE)
library(jagsNEC)

AIMS/NEC-estimation documentation built on Dec. 7, 2020, 10:44 a.m.