Skip to contents

This vignette shows three common ways to use mars():

  1. a univariate meta-analysis with one effect size per study,
  2. a multivariate meta-analysis with multiple dependent effect sizes, and
  3. 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.08592

Moderators 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.7439

Normal, 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.7439

Hartung-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.01386256

Model-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.7439

Multivariate 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.9793

The 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.9793

These 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.03766

Fixed 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.3635

Model-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.3635

Other 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().