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("'formula' rhs includes transformations requiring an argument for ",
"'eq.x.rhs': 'eq.label' set to NA!."),
warn.transf.lhs.txt =
paste0("'formula' lhs includes transformations requiring an argument for ",
"'eq.with.lhs': 'eq.label' set to NA!."),
warn.spline.rhs.txt = paste0("'formula' rhs includes a spline base function: ",
" 'eq.label' set to NA!."),
warn.as.is.txt = paste0("Power (^) terms in 'formula' for a polynomial need to ",
"be protected by 'I()': 'eq.label' set to NA!."),
warn.poly.raw.txt = paste0("'poly()' in 'formula' has to be passed 'raw = TRUE': ",
"'eq.label' set to NA!"),
stop.pow.poly.text =
"Both 'poly()' and power (^) terms in 'formula', use one or the other.",
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.spline.rhs.txt, warn.as.is.txt, warn.poly.raw.txt, stop.pow.poly.text
character Text for warnings and errors. If
NULLthe warning is not issued and failure reported silently to the caller.- 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 cannot be demonstrated to be always correct, as it is
difficult to test, or even list all possible variations of supported vs.
unsupported formulas.
Many valid model formulas that can be successfully fitted, cannot
be automatically converted into correct character labels by functions in
'ggpmisc'. Thus, this function triggers a
warning in case of a test failure, not an error, returning a logic value. If
this value is FALSE, the statistics in 'ggpmisc' skip the generation
of an equation label, setting it to NA, while returning other
character labels and the numeric estimates
of the fitted coefficients. Thus, the stats can be used also
with models that are not polynomials or containing transformations, but in
this case the model equation when needed needs to be assembled in user's
code within a call to `aes()`.
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.
Spline base functions ns(), bs() and lspline() are
searched for and flagged, while poly() is accepted. 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 on with
raw = TRUE.
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
# spline terms not accepted
check_poly_formula(y ~ ns(x))
#> [1] TRUE
check_poly_formula(y ~ bs(x))
#> [1] TRUE
check_poly_formula(y ~ lspline(x))
#> [1] TRUE