Skip to contents

Compute a compact residual-diagnostics summary that works across univariate, multivariate, and multilevel mars fits.

Usage

residual_diagnostics(object, cluster = NULL, outcome = NULL)

Arguments

object

A fitted mars object.

cluster

Optional column name in object$data for cluster-level summaries.

outcome

Optional column name in object$data for outcome-level summaries.

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"
# }