R/ResidPlotDocs.R

In huntercole25/EcoCountHelper: An assistant for comparing and interpretting models with count data

#' Efficiently examine multiple model fits
#'
#' These functions are essentially wrappers for a few \code{\link[DHARMa]{DHARMa}} functions that allow users to assess model
#' fit for models produced using \code{\link[glmmTMB]{glmmTMB}} with or without random effects.
#' 
#' @name ResidPlotLong
#' 
#' @aliases ResidPlotWide
#' 
#' @param Data The unquoted name of the data frame or data table containing the raw data models are based on.
#' 
#' @param CountCol A character string specifying the name of the vector containing count data.
#' 
#' @param GroupCol A character string specifying the name of the vector containing group information (e.g., order, species) for each observation.
#'
#' @param Nsims A number indicating the number of data simulations to run with \code{\link[stats]{simulate}}.
#'
#' @param ModNames A character vector of model object names to assess model fit for.
#'
#' @param GroupPat A quoted regular expression that can be used to extract the character string representing
#' the column name containing the response variable of a model for (e.g., if the models "EpfuNb2" and "MyluNb2" are supplied for
#' the \code{ModNames} argument, an appropriate regular expression would be "^[[:alpha:]]\{4\}" because the response
#' variable columns are "Epfu" and "Mylu", respectively).
#' 
#' @param Looped A logical value indicating whether models were generated using a for loop or
#' apply function that results in the "Data" value in the model output including an iterative subset. 
#' Defaults to "T".
#'
#' @param TestVals A logical value indicating whether model fit test values should be generated alongside
#' the plots this function creates.
#'
#' @return These functions output the plots generated by \code{\link[DHARMa]{testResiduals}}. Each resultant plot is named with
#' the model name followed by "SimResidPlot" (e.g., the plot associated with a model named "EpfuNb2" would be named
#' "EpfuNb2SimResidPlot"). If \code{TestVals = T}, test values will also be generated. The resultant test values
#' are named with the model name follow by "ResidTests" (e.g., the test values associated with a model named
#' "EpfuNb2" would be named "EpfuNb2SimResidPlot").
#' 
#' @examples
#' #ResidPlotWide Example
#' data("BatDataWide", "Epfu_Nb2", "Myev_Nb2", package = "EcoCountHelper")
#' 
#' ResidPlotWide(BatDataWide, c("Epfu_Nb2", "Myev_Nb2"), "^[[:alpha:]]{4}")
#' 
#' Epfu_Nb2ResidTests
#' Epfu_Nb2SimResidPlot
#' Myev_Nb2ResidTests
#' Myev_Nb2SimResidPlot
#' 
#' #ResidPlotLong Example
#' data("BatDataLong", "Epfu_Nb2_Long", "Myev_Nb2_Long", package = "EcoCountHelper")
#' 
#' ResidPlotLong(BatDataLong, "Count", "Species",
#'  c("Epfu_Nb2_Long", "Myev_Nb2_Long"), "^[[:alpha:]]{4}")
#' 
#' Epfu_Nb2_LongResidTests
#' Epfu_Nb2_LongSimResidPlot
#' Myev_Nb2_LongResidTests
#' Myev_Nb2_LongSimResidPlot
#'
#' @export
NULL