Analyse a model formula to determine if it describes a polynomial with terms in order of increasing powers, and fulfils the expectations of the algorithm used to generate the equation-label.
Usage
check_poly_formula(
formula,
x.name = "x",
warn.incr.poly.text = "'formula' not an increasing polynomial: 'eq.label' set to NA!",
warn.transf.rhs.txt = paste0("rhs includes transformations requiring an argument for ",
"'eq.x.rhs': 'eq.label' set to NA!."),
warn.transf.lhs.txt = paste0("lhs includes transformations requiring an argument for ",
"'eq.with.lhs': 'eq.label' set to NA!."),
warn.as.is.txt = paste0("Power (^) terms in model formula of a polynomial need to ",
"be protected by 'I()': 'eq.label' set to NA!."),
warn.poly.raw.txt = paste0("'poly()' in model formula has to be passed 'raw = TRUE': ",
"'eq.label' set to NA!"),
stop.pow.poly.text = "Both 'poly()' and power (^) terms in model formula.",
check.transf.rhs = TRUE,
check.transf.lhs = TRUE
)Arguments
- formula
A model formula in
x.name.- x.name
character The name of the explanatory variable in the formula.
- warn.incr.poly.text, warn.transf.lhs.txt, warn.transf.rhs.txt, warn.as.is.txt, warn.poly.raw.txt, stop.pow.poly.text
character Text for warnings and errors.
- check.transf.rhs, check.transf.lhs
logical flag enabling test for transformation of variables.
Value
A logical, TRUE if the formula describes an increasing polynomial suitable for conversion into a text label, and FALSE otherwise. When validation fails, warnings are issued describing the problem encountered.
Details
The assumption is that this function will be called from within a
ggplot2 compatible layer function, and that model formulas will always have
a single explanatory variable, variables will be x and y. Its
behaviour is undefined or erroneous in other cases.
This validation check could return a false positive or a false negative
results with some formulas as it is difficult to test, or even list all
possible variations of supported vs. unsupported formulas. This makes
testing difficult. In addition, many valid model formulas that can be
succesfully fitted, are not correctly converted into character labels.
Thus, this function triggers a warning in case of failure, not an error,
and returns a logic value. If this value is FALSE, the statistics in
'ggpmisc' skip the generation of an equation label, setting it to
NA. However, if the formula is accepted by the model fit function,
other labels and the numeric estimates of the fitted coefficients remain
usable. The stats can be used also with models that are not polynomials or
containing transformations.
Model formulas with and without an intercept term are accepted as valid, as
+0, -1 and +1 are accepted. If a single as.is
power term is included or if arithmetic (sqrt(), exp(),
log()), or trigonometric functions (cos(), sin(),
tan(), etc.) are encountered a warning is issued about the need to
pass a matching argument to parameter eq.x.rhs of the statistic.
If two or more terms are as.is (I( ) protected) powers
(^), they are expected to be in increasing order with no missing
intermediate power terms. If poly() is used in the model formula, a
single term is expected. When calling function poly(),
raw = TRUE must be passed to obtain suitable estimates for the
fitted coefficients, and this is also checked.
When the formula rhs contains more than one power term, all power
terms defined using ^ must be protected as "as.is"
I(), as otherwise they are not powers but instead part of the
formula specification.
If the warning text is NULL or character(0) no warning is
issued, but the test is done. In contrast, check.transf.rhs,check =
FALSE and transf.lhs = FALSE skip these two tests. The caller
always receives a length-1 logical as returned value.
Examples
# polynomials
check_poly_formula(y ~ 1)
#> [1] TRUE
check_poly_formula(y ~ x)
#> [1] TRUE
check_poly_formula(y ~ x^3)
#> Warning: Terms in 'formula' were dropped! Forgotten 'I()'?
#> [1] FALSE
check_poly_formula(y ~ x + 0)
#> [1] TRUE
check_poly_formula(y ~ x - 1)
#> [1] TRUE
check_poly_formula(y ~ x + 1)
#> [1] TRUE
check_poly_formula(y ~ x + I(x^2))
#> [1] TRUE
check_poly_formula(y ~ 1 + x + I(x^2))
#> [1] TRUE
check_poly_formula(y ~ x + I(x^2) + I(x^3))
#> [1] TRUE
check_poly_formula(y ~ I(x) + I(x^2) + I(x^3))
#> [1] TRUE
# transformations on x, first degree polynomials
check_poly_formula(y ~ sqrt(x))
#> Warning: rhs includes transformations requiring an argument for 'eq.x.rhs': 'eq.label' set to NA!.
#> [1] FALSE
check_poly_formula(y ~ log(x))
#> Warning: rhs includes transformations requiring an argument for 'eq.x.rhs': 'eq.label' set to NA!.
#> [1] FALSE
check_poly_formula(y ~ I(x^2))
#> Warning: rhs includes transformations requiring an argument for 'eq.x.rhs': 'eq.label' set to NA!.
#> [1] FALSE
# incomplete or terms in decreasing/mixed order
check_poly_formula(y ~ I(x^2) + x)
#> Warning: 'formula' not an increasing polynomial: 'eq.label' set to NA!
#> [1] FALSE
check_poly_formula(y ~ I(x^2) + I(x^3))
#> Warning: 'formula' not an increasing polynomial: 'eq.label' set to NA!
#> [1] FALSE
check_poly_formula(y ~ I(x^2) + I(x^4))
#> Warning: 'formula' not an increasing polynomial: 'eq.label' set to NA!
#> [1] FALSE
check_poly_formula(y ~ x + I(x^3) + I(x^2))
#> Warning: 'formula' not an increasing polynomial: 'eq.label' set to NA!
#> [1] FALSE
# polynomials using poly()
check_poly_formula(y ~ poly(x, 2, raw = TRUE)) # label o.k.
#> [1] TRUE
check_poly_formula(y ~ poly(x, 2)) # orthogonal polynomial -> bad label
#> Warning: 'poly()' in model formula has to be passed 'raw = TRUE': 'eq.label' set to NA!
#> [1] FALSE