Runs the sorted-residual diagnostics in both directions: y regressed on
x with the residuals ordered by x, and x regressed on y with the
residuals ordered by y. The relationship is treated as nonlinear only
when both directions reject, so the result does not depend on which
variable is passed first.
Value
An object of class "smartcor_lintest": a list with p_bp,
p_lb, p_bds, p_het, p_reset (for the direction used),
p_y_on_x, p_x_on_y, direction, p.value (combined), alpha,
n_complete, structure_detected, homoskedastic, linear,
conclusion, decision, method, r_pearson, r_spearman,
r_kendall, r_final, reason, null_hypothesis, and
interpretation.
Details
In each direction, incomplete pairs are removed, the regression is fitted,
and the residuals are ordered by the regressor. Residuals that share a
regressor value are averaged, so the order of tied rows does not matter.
Box-Pierce and Ljung-Box tests use lag 1. The BDS p-value is the smallest
of the p-values from fNonlinear::bdsTest(residuals, m = 3) across its
four default distance thresholds. Breusch-Pagan and RESET use the
defaults in the lmtest package.
A direction rejects linearity when at least one residual structure test
rejects and RESET rejects. Its p-value is max(min(p_bp, p_lb, p_bds), p_reset), the intersection-union p-value of that rule. Spearman is
selected only when both directions reject; the combined p.value is the
larger of the two directional p-values (p_y_on_x, p_x_on_y), so
p.value < alpha exactly when linearity is rejected. Otherwise Pearson is
selected, and the inference recommendation (standard or robust/bootstrap)
comes from the direction that does not reject; when both do not reject,
from the one with the larger p-value. The component p-values reported at
the top level belong to that direction (direction).
The regression model behind the test assumes errors independent of the regressor, which can hold in only one direction unless the pair is bivariate normal. Requiring both directions to reject keeps skewed margins from being read as nonlinearity.
linear = TRUE means this rule did not detect nonlinearity; it does not
establish linearity. Fewer than five distinct values, a constant variable,
an exact linear fit, or undefined diagnostics make a direction
inconclusive. If neither direction can be tested, or one rejects and the
other cannot be tested, the result is inconclusive (linear = NA) and
Pearson is retained. This function returns correlation estimates and an
inference recommendation; it does not compute confidence intervals or
correlation p-values.
Examples
set.seed(42)
x = runif(100, 0, 2)
y = 2 + 3 * x + rnorm(100, sd = 0.5)
test_linearity(x, y)
#>
#> -- Linearity Test (sorted residual diagnostics) --
#>
#> H0: the relationship between x and y is linear
#> N = 100, alpha = 0.05
#> y on x p = 0.7628, x on y p = 0.02783
#> Components (y on x):
#> Box-Pierce p = 0.4258, Ljung-Box p = 0.4189, BDS p (min) = 0.2065
#> Breusch-Pagan p = 0.2373, RESET p = 0.7628
#> Combined p = 0.7628 (fail_to_reject)
#> Decision: Pearson (standard t-test)
#> No evidence of nonlinearity in at least one direction at alpha = 0.05; this
#> does not establish linearity.