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.