check_formula: Check if input model formula is appropriate to use with `bayesnec`

Description

Perform a series of checks to ensure that the input formula is valid for usage within bayesnec.

Usage

check_formula(formula, data, run_par_checks = FALSE)

Value

A validated object of class bayesnecformula and formula.

Arguments

formula: An object of class bayesnecformula as returned by function bayesnecformula.
data: A data.frame containing the variables specified in formula.
run_par_checks: See details. A logical defining whether random terms for specific parameters should be checked against the underlying concentration-response model defined in formula. Defaults to FALSE.

Details

This function allows the user to make sure that the input formula will allow for a successful model fit with the function bnec. Should all checks pass, the function returns the original formula. Otherwise it will fail and requires that the user fixes it until they're able to use it with bnec.

The argument run_par_checks is irrelevant for most usages of this package because it only applies if three conditions are met: 1) the user has specified a group-level effect; 2) the group-level effects is parameter specific (e.g. (par | group_variable) rather than pgl/ogl(group_variable)); and 3) The user is keen to learn if the specified parameter is found in the specified model (via argument model in the crf term -- see details in ?bayesnecformula).

NB: aterms other than trials() and weights() are currently omitted from model.frame output. If you need other aterms as part of that output please raise an issue on our GitHub page. See details about aterms in ?bayesnecformula.

Examples

Run this code

library(bayesnec)
nec3param <- function(beta, nec, top, x) {
  top * exp(-exp(beta) * (x - nec) *
    ifelse(x - nec < 0, 0, 1))
}

data <- data.frame(x = seq(1, 20, length.out = 10), tr = 100, wght = c(1, 2),
                   group_1 = sample(c("a", "b"), 10, replace = TRUE),
                   group_2 = sample(c("c", "d"), 10, replace = TRUE))
data$y <- nec3param(beta = -0.2, nec = 4, top = 100, data$x)

# returns error
# > f_1 <- y ~ crf(x, "nec3param") + z
# regular formula not allowed, wrap it with function bnf
# > check_formula(f_1, data)
# population-level covariates are not allowed
# > check_formula(bnf(f_1), data)

# \donttest{
# expect a series of messages for because not all
# nec models have the "bot" parameter
f_2 <- y | trials(tr) ~ crf(x, "nec") + (nec + bot | group_1)
check_formula(bnf(f_2), data, run_par_checks = TRUE)
# }
# runs fine
f_3 <- "y | trials(tr) ~ crf(sqrt(x), \"nec3param\")"
check_formula(bnf(f_3), data)
f_4 <- y | trials(tr) ~ crf(x, "nec3param") + ogl(group_1) + pgl(group_2)
inherits(check_formula(bnf(f_4), data), "bayesnecformula")