
Residual Diagnostics for MARS Models
residual_diagnostics.RdCompute a compact residual-diagnostics summary that works across univariate,
multivariate, and multilevel mars fits.
Value
A list containing residual vectors, global summaries, and optional grouped summaries. Normality and heteroscedasticity tables include status and reason fields explaining unavailable calculations; their numeric entries remain NA when the diagnostic cannot be computed. The printed model summary omits unavailable normality and heteroscedasticity screens; these tables retain the explanation for direct inspection with residual_diagnostics().
Details
The raw residual is the observed effect minus the fitted mean. The summary reports its mean, standard deviation, root mean squared error and mean absolute error, plus the sum of squared Pearson residuals and internally studentized residual magnitudes. These are descriptive diagnostics, not a second heterogeneity test. Studentization conditions on fitted covariance and fixed-effect leverage; it is not an externally studentized deletion diagnostic.
Shapiro-Wilk is applied to finite whitened residuals (at most the first 5,000) when at least three nonconstant values exist. Its p-value is an exploratory screen: whitening and estimation of the mean/covariance do not make fitted residuals an independent sample with known parameters.
The heteroscedasticity screen correlates absolute raw residuals with fitted means and fits an ordinary linear trend. It requires at least three finite observations and variation in both quantities. An intercept-only mean model has constant fitted values, so this diagnostic is unavailable; the NA entries do not indicate a fitting failure. The ordinary-regression p-value does not adjust for within-study dependence, fitted-model selection or multiple screens. A nonsignificant result does not establish homoscedasticity or normality.
Examples
# \donttest{
fit <- mars(
data = teacher_expectancy,
studyID = "study",
effectID = NULL,
sample_size = NULL,
formula = yi ~ 1,
variance = "vi",
varcov_type = "univariate",
structure = "univariate"
)
residual_diagnostics(fit)
#> $structure
#> [1] "univariate"
#>
#> $residuals
#> index fitted raw pearson studentized whitened cluster
#> 1 1 0.08370125 -0.05370125 -0.2894608 -0.30137138 -0.2894608 1
#> 2 2 0.08370125 0.03629875 0.1805522 0.18682044 0.1805522 2
#> 3 3 0.08370125 -0.22370125 -1.0349632 -1.06582986 -1.0349632 3
#> 4 4 0.08370125 1.09629875 2.7587522 2.78234493 2.7587522 4
#> 5 5 0.08370125 0.17629875 0.4477729 0.45167476 0.4477729 5
#> 6 6 0.08370125 -0.14370125 -0.8378221 -0.87858986 -0.8378221 6
#> 7 7 0.08370125 -0.10370125 -0.6046099 -0.63402974 -0.6046099 7
#> 8 8 0.08370125 -0.40370125 -1.5570994 -1.58893746 -1.5570994 8
#> 9 9 0.08370125 0.18629875 0.8712944 0.89787448 0.8712944 9
#> 10 10 0.08370125 0.71629875 2.5041998 2.54603591 2.5041998 10
#> 11 11 0.08370125 0.45629875 1.3756781 1.39266016 1.3756781 11
#> 12 12 0.08370125 0.09629875 0.3678895 0.37526470 0.3678895 12
#> 13 13 0.08370125 -0.10370125 -0.3241958 -0.32850500 -0.3241958 13
#> 14 14 0.08370125 0.14629875 0.4560310 0.46205653 0.4560310 14
#> 15 15 0.08370125 -0.26370125 -1.2554598 -1.29521503 -1.2554598 15
#> 16 16 0.08370125 -0.14370125 -0.6648399 -0.68466798 -0.6648399 16
#> 17 17 0.08370125 0.21629875 1.1078661 1.14877901 1.1078661 17
#> 18 18 0.08370125 -0.01370125 -0.0824445 -0.08673841 -0.0824445 18
#> 19 19 0.08370125 -0.15370125 -0.6935148 -0.71314420 -0.6935148 19
#>
#> $summary
#> n n_finite_raw mean_raw sd_raw rmse mae q_pearson
#> 1 19 19 0.07998296 0.3588749 0.3583434 0.2491422 25.5952
#> mean_abs_studentized max_abs_studentized prop_abs_studentized_gt2
#> 1 0.9379231 2.782345 0.1052632
#> prop_abs_studentized_gt3
#> 1 0
#>
#> $normality
#> test n_tested statistic p_value status reason
#> 1 shapiro_wilk_whitened 19 0.9380569 0.2432095 available
#>
#> $heteroscedasticity
#> n corr_abs_raw_fitted slope p_value status
#> 1 19 NA NA NA unavailable
#> reason
#> 1 Fitted values are constant; a residual-versus-fitted trend cannot be estimated.
#>
#> $by_cluster
#> study n mean_raw rmse mean_abs_studentized q_pearson
#> 1 1 1 -0.05370125 0.05370125 0.30137138 0.083787533
#> 2 2 1 0.03629875 0.03629875 0.18682044 0.032599086
#> 3 3 1 -0.22370125 0.22370125 1.06582986 1.071148868
#> 4 4 1 1.09629875 1.09629875 2.78234493 7.610713888
#> 5 5 1 0.17629875 0.17629875 0.45167476 0.200500531
#> 6 6 1 -0.14370125 0.14370125 0.87858986 0.701945812
#> 7 7 1 -0.10370125 0.10370125 0.63402974 0.365553100
#> 8 8 1 -0.40370125 0.40370125 1.58893746 2.424558653
#> 9 9 1 0.18629875 0.18629875 0.89787448 0.759153985
#> 10 10 1 0.71629875 0.71629875 2.54603591 6.271016866
#> 11 11 1 0.45629875 0.45629875 1.39266016 1.892490274
#> 12 12 1 0.09629875 0.09629875 0.37526470 0.135342683
#> 13 13 1 -0.10370125 0.10370125 0.32850500 0.105102892
#> 14 14 1 0.14629875 0.14629875 0.46205653 0.207964242
#> 15 15 1 -0.26370125 0.26370125 1.29521503 1.576179427
#> 16 16 1 -0.14370125 0.14370125 0.68466798 0.442012038
#> 17 17 1 0.21629875 0.21629875 1.14877901 1.227367367
#> 18 18 1 -0.01370125 0.01370125 0.08673841 0.006797095
#> 19 19 1 -0.15370125 0.15370125 0.71314420 0.480962821
#>
#> $by_outcome
#> NULL
#>
#> attr(,"class")
#> [1] "mars_residual_diagnostics"
# }