
MARS Model Examples
Brandon LeBeau
2026-11-20
MARS-Model-Examples.RmdThis vignette shows three common ways to use mars():
- a univariate meta-analysis with one effect size per study,
- a multivariate meta-analysis with multiple dependent effect sizes, and
- a multilevel meta-analysis with nested effect sizes.
The examples use datasets included with the package and keep the fitted models small enough to run quickly during package installation.
Selecting Coefficient Inference
summary(fit) keeps the default output, including stored
robust results when available. Explicit inference and
test arguments select one coefficient table and report its
covariance method, reference distribution, degrees of freedom, and
confidence intervals. These choices apply to the summary; they preserve
the fitted estimates, heterogeneity, and original model object.
| Model | Model-based tests | Cluster-robust tests |
|---|---|---|
| Independent univariate |
"z", "t", "hksj",
"Satterthwaite"
|
"z", "naive-t", "naive-tp",
"Satterthwaite"
|
| Multivariate/correlation synthesis |
"z", "Satterthwaite"
|
Same robust choices, clustering by independent study |
| Multilevel |
"z", "Satterthwaite"
|
Same robust choices, clustering above dependent effects |
Model-based Satterthwaite requires a converged fit with estimated,
interior, identifiable heterogeneity and GLS covariance. HKSJ requires
independent univariate ML/REML data with estimated constant
heterogeneity and inverse-variance GLS weights. Robust choices require
independent clusters, an estimable covariance adjustment, and positive
degrees of freedom. See ?mars_inference_options for the
full compatibility table and argument combinations.
Univariate Meta-Analysis
Use structure = "univariate" when each row contributes a
single effect size with its own sampling variance. The bcg
data include log risk-ratio estimates (yi) and their
sampling variances (vi) from tuberculosis vaccine
trials.
fit_uni <- mars(
data = bcg,
formula = yi ~ 1,
studyID = "trial",
variance = "vi",
varcov_type = "univariate",
structure = "univariate",
estimation_method = "MLE"
)
summary(fit_uni)
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> univariate
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> yi ~ 1
#>
#> Data Summary:
#> Number of Effect Sizes: 13
#> Number of Fixed Effects: 1
#> Number of Random Effects: 1
#>
#> Random Components:
#> term var SD
#> intercept 0.28 0.5292
#>
#> Fixed Effects Estimates:
#> attribute estimate SE z_test p_value lower upper
#> (Intercept) -0.7112 0.1719 -4.137 3.513e-05 -1.048 -0.3743
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -12.67 31.33 29.33 30.46 37.9
#>
#> Q Error: 152.233 (12), p < 0.0001
#>
#> I2 (General): 91.37828
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 13
#> Finite raw residuals 13
#> Mean raw residual -0.02945
#> SD of raw residuals 0.6938
#> Root mean squared residual 0.6672
#> Mean absolute residual 0.5958
#> Sum of squared Pearson residuals 13.16
#> Mean |studentized residual| 0.9527
#> Maximum |studentized residual| 1.434
#> Proportion |studentized residual| > 2 0
#> Proportion |studentized residual| > 3 0
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 13 0.886 0.08592Moderators can be added directly to the formula. Here, absolute latitude is used as a study-level predictor.
fit_uni_mod <- mars(
data = bcg,
formula = yi ~ 1 + ablat,
studyID = "trial",
variance = "vi",
varcov_type = "univariate",
structure = "univariate",
estimation_method = "MLE"
)
summary(fit_uni_mod)
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> univariate
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> yi ~ 1 + ablat
#>
#> Data Summary:
#> Number of Effect Sizes: 13
#> Number of Fixed Effects: 2
#> Number of Random Effects: 1
#>
#> Random Components:
#> term var SD
#> intercept 0.03435 0.1853
#>
#> Fixed Effects Estimates:
#> attribute estimate SE z_test p_value lower upper
#> (Intercept) 0.28211 0.187185 1.507 1.318e-01 -0.08477 0.64898
#> ablat -0.02951 0.005488 -5.377 7.560e-08 -0.04027 -0.01875
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -7.686 25.37 21.37 23.07 43.77
#>
#> Q Error: 30.733 (11), p = 0.0012
#>
#> I2 (General): 49.32886
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 13
#> Finite raw residuals 13
#> Mean raw residual -0.03533
#> SD of raw residuals 0.5817
#> Root mean squared residual 0.56
#> Mean absolute residual 0.3935
#> Sum of squared Pearson residuals 18.46
#> Mean |studentized residual| 1.021
#> Maximum |studentized residual| 2.704
#> Proportion |studentized residual| > 2 0.1538
#> Proportion |studentized residual| > 3 0
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 13 0.9727 0.924
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 13 0.1005 0.09779 0.7439Normal, t, and Hartung-Knapp inference
Use inference = "model" to select model covariance.
Normal Wald inference uses test = "z". The residual-df t
test uses the same covariance with n - p degrees of
freedom, where n is the number of independent effects and
p is the number of mean coefficients. level
sets pointwise coefficient confidence coverage.
summary(fit_uni_mod, inference = "model", test = "z", level = 0.90)
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> univariate
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Summary inference: model; covariance: gls; test: z; level: 0.9
#> Coefficient/contrast inference only; heterogeneity, scale, prediction and model-fit tests are unchanged.
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> yi ~ 1 + ablat
#>
#> Data Summary:
#> Number of Effect Sizes: 13
#> Number of Fixed Effects: 2
#> Number of Random Effects: 1
#>
#> Random Components:
#> term var SD
#> intercept 0.03435 0.1853
#>
#> Fixed Effects Estimates:
#> attribute estimate SE z_test df p_value lower upper
#> (Intercept) 0.28211 0.187185 1.507 Inf 1.318e-01 -0.02578 0.59000
#> ablat -0.02951 0.005488 -5.377 Inf 7.560e-08 -0.03854 -0.02048
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -7.686 25.37 21.37 23.07 43.77
#>
#> Q Error: 30.733 (11), p = 0.0012
#>
#> I2 (General): 49.32886
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 13
#> Finite raw residuals 13
#> Mean raw residual -0.03533
#> SD of raw residuals 0.5817
#> Root mean squared residual 0.56
#> Mean absolute residual 0.3935
#> Sum of squared Pearson residuals 18.46
#> Mean |studentized residual| 1.021
#> Maximum |studentized residual| 2.704
#> Proportion |studentized residual| > 2 0.1538
#> Proportion |studentized residual| > 3 0
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 13 0.9727 0.924
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 13 0.1005 0.09779 0.7439
summary(fit_uni_mod, inference = "model", test = "t", level = 0.90)
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> univariate
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Summary inference: model; covariance: gls; test: t; level: 0.9
#> Coefficient/contrast inference only; heterogeneity, scale, prediction and model-fit tests are unchanged.
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> yi ~ 1 + ablat
#>
#> Data Summary:
#> Number of Effect Sizes: 13
#> Number of Fixed Effects: 2
#> Number of Random Effects: 1
#>
#> Random Components:
#> term var SD
#> intercept 0.03435 0.1853
#>
#> Fixed Effects Estimates:
#> attribute estimate SE t_test df p_value lower upper
#> (Intercept) 0.28211 0.187185 1.507 11 0.1599520 -0.05405 0.61827
#> ablat -0.02951 0.005488 -5.377 11 0.0002243 -0.03936 -0.01965
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -7.686 25.37 21.37 23.07 43.77
#>
#> Q Error: 30.733 (11), p = 0.0012
#>
#> I2 (General): 49.32886
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 13
#> Finite raw residuals 13
#> Mean raw residual -0.03533
#> SD of raw residuals 0.5817
#> Root mean squared residual 0.56
#> Mean absolute residual 0.3935
#> Sum of squared Pearson residuals 18.46
#> Mean |studentized residual| 1.021
#> Maximum |studentized residual| 2.704
#> Proportion |studentized residual| > 2 0.1538
#> Proportion |studentized residual| > 3 0
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 13 0.9727 0.924
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 13 0.1005 0.09779 0.7439Hartung-Knapp ("hksj", also accepted as
"knha") rescales coefficient covariance by the weighted
residual sum of squares divided by n - p and uses a t
distribution. The modified adjustment bounds that scale below by one, so
it cannot reduce the GLS standard errors.
summary(fit_uni_mod, inference = "model", test = "hksj",
hksj_adjust = "standard")
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> univariate
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Summary inference: model; covariance: gls; test: hksj; level: 0.95
#> Hartung-Knapp adjustment: standard; variance multiplier: 1.678142
#> Coefficient/contrast inference only; heterogeneity, scale, prediction and model-fit tests are unchanged.
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> yi ~ 1 + ablat
#>
#> Data Summary:
#> Number of Effect Sizes: 13
#> Number of Fixed Effects: 2
#> Number of Random Effects: 1
#>
#> Random Components:
#> term var SD
#> intercept 0.03435 0.1853
#>
#> Fixed Effects Estimates:
#> attribute estimate SE t_test df p_value lower upper
#> (Intercept) 0.28211 0.242485 1.163 11 0.269282 -0.25160 0.81581
#> ablat -0.02951 0.007109 -4.151 11 0.001614 -0.04516 -0.01386
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -7.686 25.37 21.37 23.07 43.77
#>
#> Q Error: 30.733 (11), p = 0.0012
#>
#> I2 (General): 49.32886
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 13
#> Finite raw residuals 13
#> Mean raw residual -0.03533
#> SD of raw residuals 0.5817
#> Root mean squared residual 0.56
#> Mean absolute residual 0.3935
#> Sum of squared Pearson residuals 18.46
#> Mean |studentized residual| 1.021
#> Maximum |studentized residual| 2.704
#> Proportion |studentized residual| > 2 0.1538
#> Proportion |studentized residual| > 3 0
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 13 0.9727 0.924
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 13 0.1005 0.09779 0.7439
summary(fit_uni_mod, inference = "model", test = "hksj",
hksj_adjust = "modified")
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> univariate
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Summary inference: model; covariance: gls; test: hksj; level: 0.95
#> Hartung-Knapp adjustment: modified; variance multiplier: 1.678142
#> Coefficient/contrast inference only; heterogeneity, scale, prediction and model-fit tests are unchanged.
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> yi ~ 1 + ablat
#>
#> Data Summary:
#> Number of Effect Sizes: 13
#> Number of Fixed Effects: 2
#> Number of Random Effects: 1
#>
#> Random Components:
#> term var SD
#> intercept 0.03435 0.1853
#>
#> Fixed Effects Estimates:
#> attribute estimate SE t_test df p_value lower upper
#> (Intercept) 0.28211 0.242485 1.163 11 0.269282 -0.25160 0.81581
#> ablat -0.02951 0.007109 -4.151 11 0.001614 -0.04516 -0.01386
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -7.686 25.37 21.37 23.07 43.77
#>
#> Q Error: 30.733 (11), p = 0.0012
#>
#> I2 (General): 49.32886
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 13
#> Finite raw residuals 13
#> Mean raw residual -0.03533
#> SD of raw residuals 0.5817
#> Root mean squared residual 0.56
#> Mean absolute residual 0.3935
#> Sum of squared Pearson residuals 18.46
#> Mean |studentized residual| 1.021
#> Maximum |studentized residual| 2.704
#> Proportion |studentized residual| > 2 0.1538
#> Proportion |studentized residual| > 3 0
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 13 0.9727 0.924
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 13 0.1005 0.09779 0.7439
# Use the same settings to extract matching coefficient intervals.
confint(fit_uni_mod, inference = "model", test = "hksj",
hksj_adjust = "modified")
#> 2.5% 97.5%
#> (Intercept) -0.25159819 0.81581251
#> ablat -0.04515611 -0.01386256Model-based Satterthwaite instead uses expected covariance-parameter information to approximate coefficient-specific degrees of freedom, retaining GLS standard errors. This differs from the cluster-robust Satterthwaite calculation below.
summary(fit_uni_mod, inference = "model", test = "Satterthwaite")
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> univariate
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Summary inference: model; covariance: gls; test: Satterthwaite; level: 0.95
#> Expected-information delta-method Satterthwaite
#> Coefficient/contrast inference only; heterogeneity, scale, prediction and model-fit tests are unchanged.
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> yi ~ 1 + ablat
#>
#> Data Summary:
#> Number of Effect Sizes: 13
#> Number of Fixed Effects: 2
#> Number of Random Effects: 1
#>
#> Random Components:
#> term var SD
#> intercept 0.03435 0.1853
#>
#> Fixed Effects Estimates:
#> attribute estimate SE t_test df p_value lower upper
#> (Intercept) 0.28211 0.187185 1.507 6.577 0.1782239 -0.16636 0.73057
#> ablat -0.02951 0.005488 -5.377 7.423 0.0008517 -0.04234 -0.01668
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -7.686 25.37 21.37 23.07 43.77
#>
#> Q Error: 30.733 (11), p = 0.0012
#>
#> I2 (General): 49.32886
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 13
#> Finite raw residuals 13
#> Mean raw residual -0.03533
#> SD of raw residuals 0.5817
#> Root mean squared residual 0.56
#> Mean absolute residual 0.3935
#> Sum of squared Pearson residuals 18.46
#> Mean |studentized residual| 1.021
#> Maximum |studentized residual| 2.704
#> Proportion |studentized residual| > 2 0.1538
#> Proportion |studentized residual| > 3 0
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 13 0.9727 0.924
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 13 0.1005 0.09779 0.7439Multivariate Meta-Analysis
Use effectsize_type = "cor" for correlations stored in a
wide study-level dataset. In this workflow, variable_names
identifies the correlation columns, and mars() builds the
working multivariate dataset internally.
fit_mv <- mars(
data = becker09,
studyID = "ID",
effectID = "numID",
sample_size = "N",
effectsize_type = "cor",
varcov_type = "weighted",
variable_names = c(
"Cognitive_Performance",
"Somatic_Performance",
"Selfconfidence_Performance",
"Somatic_Cognitive",
"Selfconfidence_Cognitive",
"Selfconfidence_Somatic"
)
)
#> Warning in return_estimates(q_f = q_f, q_r = q_r, estimated_pars =
#> optim_values[["par"]], : Hessian inversion failed: Hessian is singular,
#> indefinite, or numerically unidentified.
summary(fit_mv)
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> multivariate
#>
#> Estimation Method:
#> Restricted Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> NULL
#>
#> Data Summary:
#> Number of Effect Sizes: 54
#> Number of Fixed Effects: 6
#> Number of Random Effects: 6
#>
#> Random Components:
#> ri_1 ri_2 ri_3 ri_4 ri_5 ri_6
#> ri_1 0.1263 0.07697 -0.03975 0.005319 -0.018838 0.005678
#> ri_2 0.8801 0.06057 -0.03959 0.006390 -0.018856 0.001176
#> ri_3 -0.4483 -0.64450 0.06228 -0.011109 0.018174 -0.012527
#> ri_4 0.3331 0.57781 -0.99068 0.002019 -0.003211 0.002126
#> ri_5 -0.5011 -0.72416 0.68835 -0.675316 0.011193 -0.001087
#> ri_6 0.2047 0.06121 -0.64310 0.606249 -0.131591 0.006093
#>
#> Fixed Effects Estimates:
#> attribute estimate SE z_test p_value lower upper
#> 1 -0.03392 0.12243 -0.2771 7.817e-01 -0.27388 0.2060
#> 2 -0.07108 0.08998 -0.7900 4.295e-01 -0.24743 0.1053
#> 3 0.23285 0.09194 2.5326 1.132e-02 0.05265 0.4131
#> 4 0.54416 0.03359 16.1977 5.233e-59 0.47832 0.6100
#> 5 -0.45298 0.05156 -8.7859 1.551e-18 -0.55403 -0.3519
#> 6 -0.39757 0.04483 -8.8691 7.374e-19 -0.48543 -0.3097
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> 16.24 -32.48 21.52 72.04 32.29
#>
#> Q Error: 198.662 (48), p < 0.0001
#>
#> I2 (General):
#> names values
#> ri_1 93.75
#> ri_2 87.79
#> ri_3 88.09
#> ri_4 19.34
#> ri_5 57.06
#> ri_6 41.97
#>
#> I2 (Jackson):
#> names values
#> ri_1 89.58
#> ri_2 81.11
#> ri_3 84.71
#> ri_4 20.61
#> ri_5 55.58
#> ri_6 41.00
#>
#> I2 (Between): 84.15488
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 54
#> Finite raw residuals 54
#> Mean raw residual -0.006088
#> SD of raw residuals 0.2431
#> Root mean squared residual 0.2409
#> Mean absolute residual 0.1832
#> Sum of squared Pearson residuals 112.6
#> Mean |studentized residual| 1.228
#> Maximum |studentized residual| 4.244
#> Proportion |studentized residual| > 2 0.1852
#> Proportion |studentized residual| > 3 0.05556
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 54 0.977 0.3838
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 54 0.003616 0.001683 0.9793The result estimates the average correlation vector and a between-study covariance structure for the dependent correlations.
Cluster-robust inference for pooled correlations
Supply cluster as the name of the column identifying
independent studies in the fitted analysis data. Correlation synthesis
reshapes the input and stores that column name in
fit_mv$study_id ("study" here), keeping each
study’s dependent correlations together. robust_type
selects the sandwich covariance adjustment; "CR2" with
test = "Satterthwaite" uses cluster influences for
coefficient-specific degrees of freedom. If a fit already stores robust
clustering, cluster can be omitted.
summary(fit_mv, inference = "robust", cluster = fit_mv$study_id,
robust_type = "CR2", test = "Satterthwaite")
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> multivariate
#>
#> Estimation Method:
#> Restricted Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Summary inference: robust; covariance: CR2; test: Satterthwaite; level: 0.95
#> Coefficient/contrast inference only; heterogeneity, scale, prediction and model-fit tests are unchanged.
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> NULL
#>
#> Data Summary:
#> Number of Effect Sizes: 54
#> Number of Fixed Effects: 6
#> Number of Random Effects: 6
#>
#> Random Components:
#> ri_1 ri_2 ri_3 ri_4 ri_5 ri_6
#> ri_1 0.1263 0.07697 -0.03975 0.005319 -0.018838 0.005678
#> ri_2 0.8801 0.06057 -0.03959 0.006390 -0.018856 0.001176
#> ri_3 -0.4483 -0.64450 0.06228 -0.011109 0.018174 -0.012527
#> ri_4 0.3331 0.57781 -0.99068 0.002019 -0.003211 0.002126
#> ri_5 -0.5011 -0.72416 0.68835 -0.675316 0.011193 -0.001087
#> ri_6 0.2047 0.06121 -0.64310 0.606249 -0.131591 0.006093
#>
#> Fixed Effects Estimates:
#> attribute estimate SE t_test df p_value lower
#> factor(data[[effectID]])1 -0.03392 0.12250 -0.2769 8.868 7.882e-01 -0.31167
#> factor(data[[effectID]])2 -0.07108 0.08979 -0.7916 8.695 4.497e-01 -0.27529
#> factor(data[[effectID]])3 0.23285 0.09173 2.5386 8.256 3.394e-02 0.02247
#> factor(data[[effectID]])4 0.54416 0.02468 22.0523 5.987 5.818e-07 0.48375
#> factor(data[[effectID]])5 -0.45298 0.05099 -8.8831 6.661 6.233e-05 -0.57481
#> factor(data[[effectID]])6 -0.39757 0.04322 -9.1994 6.089 8.542e-05 -0.50294
#> upper
#> 0.2438
#> 0.1331
#> 0.4432
#> 0.6046
#> -0.3311
#> -0.2922
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> 16.24 -32.48 21.52 72.04 32.29
#>
#> Q Error: 198.662 (48), p < 0.0001
#>
#> I2 (General):
#> names values
#> ri_1 93.75
#> ri_2 87.79
#> ri_3 88.09
#> ri_4 19.34
#> ri_5 57.06
#> ri_6 41.97
#>
#> I2 (Jackson):
#> names values
#> ri_1 89.58
#> ri_2 81.11
#> ri_3 84.71
#> ri_4 20.61
#> ri_5 55.58
#> ri_6 41.00
#>
#> I2 (Between): 84.15488
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 54
#> Finite raw residuals 54
#> Mean raw residual -0.006088
#> SD of raw residuals 0.2431
#> Root mean squared residual 0.2409
#> Mean absolute residual 0.1832
#> Sum of squared Pearson residuals 112.6
#> Mean |studentized residual| 1.228
#> Maximum |studentized residual| 4.244
#> Proportion |studentized residual| > 2 0.1852
#> Proportion |studentized residual| > 3 0.05556
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 54 0.977 0.3838
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 54 0.003616 0.001683 0.9793These options apply to the pooled correlation coefficients. A subsequent path or factor model has its own summary and does not inherit these test choices. HKSJ and residual-df model t tests are unavailable for dependent correlations.
Multilevel Meta-Analysis
Use structure = "multilevel" when effect sizes are
nested. Random effects are specified in the model formula with the same
general style as mixed-model formulas. In the school data,
effects are nested within studies, and studies are nested within
districts.
fit_ml <- mars(
data = school,
formula = effect ~ 1 + (1 | district/study),
studyID = "district",
variance = "var",
varcov_type = "multilevel",
structure = "multilevel",
estimation_method = "MLE"
)
summary(fit_ml)
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> multilevel
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> effect ~ 1 + (1 | district/study)
#>
#> Data Summary:
#> Number of Effect Sizes: 56
#> Number of Fixed Effects: 1
#> Number of Random Effects: 2
#>
#> Random Data Summary:
#> Number unique district: 11
#> Number unique study: 56
#>
#> Random Components:
#> term var SD
#> district 0.05774 0.2403
#> study 0.03286 0.1813
#>
#> Fixed Effects Estimates:
#> attribute estimate SE z_test p_value lower upper
#> (Intercept) 0.1845 0.08048 2.292 0.02191 0.02671 0.3422
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -8.395 24.79 22.79 28.87 24.5
#>
#> Q Error: 578.864 (55), p < 0.0001
#>
#> I2 (General):
#> names values
#> district 92.11
#> study 86.92
#>
#> I2 (Jackson): 98.69621
#> I2 (Between): 86.37273
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 56
#> Finite raw residuals 56
#> Mean raw residual -0.06446
#> SD of raw residuals 0.3258
#> Root mean squared residual 0.3293
#> Mean absolute residual 0.2632
#> Sum of squared Pearson residuals 96.8
#> Mean |studentized residual| 1.065
#> Maximum |studentized residual| 4.196
#> Proportion |studentized residual| > 2 0.1071
#> Proportion |studentized residual| > 3 0.03571
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 56 0.9555 0.03766Fixed moderators can be combined with the random-effects structure in the same formula.
fit_ml_mod <- mars(
data = school,
formula = effect ~ 1 + year + (1 | district/study),
studyID = "district",
variance = "var",
varcov_type = "multilevel",
structure = "multilevel",
estimation_method = "MLE"
)
summary(fit_ml_mod)
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> multilevel
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> effect ~ 1 + year + (1 | district/study)
#>
#> Data Summary:
#> Number of Effect Sizes: 56
#> Number of Fixed Effects: 2
#> Number of Random Effects: 2
#>
#> Random Data Summary:
#> Number unique district: 11
#> Number unique study: 56
#>
#> Random Components:
#> term var SD
#> district 0.06617 0.2572
#> study 0.03265 0.1807
#>
#> Fixed Effects Estimates:
#> attribute estimate SE z_test p_value lower upper
#> (Intercept) -10.218657 18.09645 -0.5647 0.5723 -45.68705 25.24973
#> year 0.005226 0.00909 0.5749 0.5654 -0.01259 0.02304
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -9.081 30.16 26.16 34.26 29.23
#>
#> Q Error: 550.26 (54), p < 0.0001
#>
#> I2 (General):
#> names values
#> district 93.02
#> study 86.80
#>
#> I2 (Jackson):
#> names values
#> district 98.22
#> study 98.23
#>
#> I2 (Between): 83.78149
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 56
#> Finite raw residuals 56
#> Mean raw residual -0.05828
#> SD of raw residuals 0.3192
#> Root mean squared residual 0.3217
#> Mean absolute residual 0.2568
#> Sum of squared Pearson residuals 94.56
#> Mean |studentized residual| 1.055
#> Maximum |studentized residual| 4.077
#> Proportion |studentized residual| > 2 0.1071
#> Proportion |studentized residual| > 3 0.03571
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 56 0.9561 0.04019
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 56 0.1237 0.4555 0.3635Model-based and robust Satterthwaite inference
For an eligible multilevel fit, model-based Satterthwaite uses the
fitted covariance structure to approximate degrees of freedom. Robust
inference instead uses independent clusters. In these data, districts
contain the dependent studies and effects, so
cluster = "district" preserves the full dependence
blocks.
summary(fit_ml, inference = "model", test = "Satterthwaite")
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> multilevel
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Summary inference: model; covariance: gls; test: Satterthwaite; level: 0.95
#> Expected-information delta-method Satterthwaite
#> Coefficient/contrast inference only; heterogeneity, scale, prediction and model-fit tests are unchanged.
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> effect ~ 1 + (1 | district/study)
#>
#> Data Summary:
#> Number of Effect Sizes: 56
#> Number of Fixed Effects: 1
#> Number of Random Effects: 2
#>
#> Random Data Summary:
#> Number unique district: 11
#> Number unique study: 56
#>
#> Random Components:
#> term var SD
#> district 0.05774 0.2403
#> study 0.03286 0.1813
#>
#> Fixed Effects Estimates:
#> attribute estimate SE t_test df p_value lower upper
#> (Intercept) 0.1845 0.08048 2.292 10.84 0.04297 0.00699 0.3619
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -8.395 24.79 22.79 28.87 24.5
#>
#> Q Error: 578.864 (55), p < 0.0001
#>
#> I2 (General):
#> names values
#> district 92.11
#> study 86.92
#>
#> I2 (Jackson): 98.69621
#> I2 (Between): 86.37273
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 56
#> Finite raw residuals 56
#> Mean raw residual -0.06446
#> SD of raw residuals 0.3258
#> Root mean squared residual 0.3293
#> Mean absolute residual 0.2632
#> Sum of squared Pearson residuals 96.8
#> Mean |studentized residual| 1.065
#> Maximum |studentized residual| 4.196
#> Proportion |studentized residual| > 2 0.1071
#> Proportion |studentized residual| > 3 0.03571
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 56 0.9555 0.03766
summary(fit_ml_mod, inference = "robust", cluster = "district",
robust_type = "CR2", test = "Satterthwaite", level = 0.90)
#> Results generated with MARS:v 0.6.0.8
#> Friday, November 20, 2026
#>
#> Model Type:
#> multilevel
#>
#> Estimation Method:
#> Maximum Likelihood
#>
#> Coefficient covariance: gls
#> Summary inference: robust; covariance: CR2; test: Satterthwaite; level: 0.9
#> Coefficient/contrast inference only; heterogeneity, scale, prediction and model-fit tests are unchanged.
#> Optimizer convergence code: 0
#>
#>
#> Model Formula:
#> effect ~ 1 + year + (1 | district/study)
#>
#> Data Summary:
#> Number of Effect Sizes: 56
#> Number of Fixed Effects: 2
#> Number of Random Effects: 2
#>
#> Random Data Summary:
#> Number unique district: 11
#> Number unique study: 56
#>
#> Random Components:
#> term var SD
#> district 0.06617 0.2572
#> study 0.03265 0.1807
#>
#> Fixed Effects Estimates:
#> attribute estimate SE t_test df p_value lower upper
#> (Intercept) -10.218657 19.99486 -0.5111 4.137 0.6354 -52.44170 32.00439
#> year 0.005226 0.01004 0.5204 4.171 0.6292 -0.01593 0.02638
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -9.081 30.16 26.16 34.26 29.23
#>
#> Q Error: 550.26 (54), p < 0.0001
#>
#> I2 (General):
#> names values
#> district 93.02
#> study 86.80
#>
#> I2 (Jackson):
#> names values
#> district 98.22
#> study 98.23
#>
#> I2 (Between): 83.78149
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 56
#> Finite raw residuals 56
#> Mean raw residual -0.05828
#> SD of raw residuals 0.3192
#> Root mean squared residual 0.3217
#> Mean absolute residual 0.2568
#> Sum of squared Pearson residuals 94.56
#> Mean |studentized residual| 1.055
#> Maximum |studentized residual| 4.077
#> Proportion |studentized residual| > 2 0.1071
#> Proportion |studentized residual| > 3 0.03571
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 56 0.9561 0.04019
#>
#> Heteroscedasticity screen (|raw residual| vs fitted):
#> N Correlation Slope p-value
#> 56 0.1237 0.4555 0.3635Other robust covariance choices are "CR0",
"CR1", "CR1p", "CR1S", and
"CR3". Robust test = "naive-t" uses clusters
minus one degrees of freedom; "naive-tp" uses clusters
minus mean coefficients. Robust "t" aliases
"naive-t". Do not split a dependent district into smaller
clusters or combine robust inference with hksj_adjust or
vcov_method.
Choosing a Structure
The same entry point, mars(), handles each model family.
The main choice is how the effect sizes are organized:
-
structure = "univariate"for one effect size per independent study unit, -
effectsize_type = "cor"or"smd"for dependent multivariate effect sizes, -
structure = "multilevel"for nested effect sizes described with random effects in the formula.
After fitting, summary() provides the main estimates and
standard errors for each model. Explicit inference choices affect
mean-coefficient tests and pointwise confidence intervals. Heterogeneity
and joint model-fit tests, prediction intervals, and downstream analyses
keep their fitted calculations. Bootstrap, jackknife, and permutation
results require their explicit resampling functions; these are not
launched by summary().