jagsNEC.R

#    Copyright 2020 Australian Institute of Marine Science
#
#    Licensed under the Apache License, Version 2.0 (the "License");
#    you may not use this file except in compliance with the License.
#    You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.

#' \tabular{ll}{
#' Package: \tab jagsNEC\cr
#' Type: \tab Package\cr
#' Title: \tab No-Effect-Concentration modelling with jags\cr
#' Version: \tab 1.0\cr
#' Date: \tab 2020-28-07\cr
#' Author: \tab Rebecca Fisher\cr
#' Maintainer: \tab Rebecca Fisher\cr
#' License: \tab Apache 2\cr
#' LazyLoad: \tab yes\cr
#' Depends: \tab R2jags\cr
#' }
#'
#' @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 package for usage examples at
#' \url{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.
#'
#' @name jagsNEC-package
#' @aliases jagsNEC jagsNEC-package
#' @docType package
#' @author
#' Rebecca Fisher and Gerard Ricardo (Australian Institue of Marine Science); David Fox
#' (Environmetrics Australia)
#'
#' Maintainer: Rebecca Fisher \email{r.fisher@@aims.gov.au}
#' @references
#' \url{https://github.com/AIMS/NEC-estimation}
#' @examples
#' install.packages("jagsNEC", dependencies = TRUE)
#' library(jagsNEC)
NULL