Check if input model formula is appropriate to use with bayesnec

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

check_formula(formula, data, run_par_checks = FALSE)

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.

Value

A validated object of class bayesnecformula and formula.

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.

See also

bnec, bayesnecformula

Examples

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)
#> Performing single parameter checks on all models...
#> The parameter(s) "bot" not valid parameters in nec3param. If this was a mistake, check ?models and ?show_params, otherwise ignore.
#> The parameter(s) "bot" not valid parameters in nechorme. If this was a mistake, check ?models and ?show_params, otherwise ignore.
#> The parameter(s) "bot" not valid parameters in necsigm. If this was a mistake, check ?models and ?show_params, otherwise ignore.
#> The parameter(s) "bot" not valid parameters in neclin. If this was a mistake, check ?models and ?show_params, otherwise ignore.
#> The parameter(s) "bot" not valid parameters in neclinhorme. If this was a mistake, check ?models and ?show_params, otherwise ignore.
#> The parameter(s) "bot" not valid parameters in nechormepwr. If this was a mistake, check ?models and ?show_params, otherwise ignore.
#> The parameter(s) "bot" not valid parameters in nechormepwr01. If this was a mistake, check ?models and ?show_params, otherwise ignore.
#> y | trials(tr) ~ crf(x, "nec") + (nec + bot | group_1)
#> <environment: 0x5585c1a3e4e8>
# }
# runs fine
f_3 <- "y | trials(tr) ~ crf(sqrt(x), \"nec3param\")"
check_formula(bnf(f_3), data)
#> y | trials(tr) ~ crf(sqrt(x), "nec3param")
#> <environment: 0x5585c0a52b30>
f_4 <- y | trials(tr) ~ crf(x, "nec3param") + ogl(group_1) + pgl(group_2)
inherits(check_formula(bnf(f_4), data), "bayesnecformula")
#> [1] TRUE