Skip to contents

Primary interface for fitting univariate, multivariate/correlation, standardized-mean-difference, and multilevel meta-analytic models. The function inspects the supplied modeling arguments and routes the data to the appropriate estimator.

Usage

mars(
  data,
  studyID,
  effectID,
  sample_size,
  effectsize_type = NULL,
  formula = NULL,
  scale_formula = NULL,
  variable_names = NULL,
  effectsize_name = NULL,
  estimation_method = "REML",
  variance = NULL,
  varcov_type,
  weights = NULL,
  structure = "UN",
  intercept = FALSE,
  missing = "remove",
  optim_method = "L-BFGS-B",
  robustID = NULL,
  robust_args = list(),
  multivariate_covs = NULL,
  lasso = FALSE,
  lasso_args = list(),
  tau2 = NULL,
  tol = 1e+07,
  control = list(maxit = 1000L),
  vcov_method = c("gls", "observed"),
  ...
)

Arguments

data

Data frame containing the effect sizes, sampling variances or inputs needed to construct sampling covariance matrices, study identifiers, and any moderators.

studyID

Character string naming the study-level cluster column.

effectID

Character string naming an effect-size or outcome identifier column for dependent-effect workflows. Use NULL for one effect size per study or when the structure does not require a separate effect ID.

sample_size

Character string naming the study sample-size column. This is required for correlation and some standardized-mean-difference covariance estimators and can be NULL for formula-based univariate or multilevel models with an observed variance column.

effectsize_type

Optional effect-size family for non-formula workflows. Use "cor" for correlation synthesis. Other values, such as "smd", "md", "rom", "rate", or "reliability", use effectsize_name with the selected varcov_type. Leave NULL for formula-based univariate or multilevel models.

formula

Model formula used for univariate and multilevel models. The left-hand side is the effect-size column. Fixed-effect moderators appear on the right-hand side. Multilevel models can add random effects with lme4-style syntax such as effect ~ 1 + x + (1 | district/study).

scale_formula

Optional one-sided formula for modeling the log-heterogeneity in location-scale models. Currently supported for structure = "univariate" and structure = "multilevel". Univariate scale models require one observation per study. Their fitted variances are aligned to observations when constructing covariance. For multilevel models, this can be either a single one-sided formula applied to every random-effect component or a list of one-sided formulas aligned to the random-effect components. Multilevel scale predictors must be invariant within the top-level studyID cluster.

variable_names

Vector of character strings naming effect-size columns for multivariate/correlation workflows. For correlations, names should identify the variable pair separated by an underscore, for example "Cognitive_Performance".

effectsize_name

Character string representing the name of the effect size column in the data.

estimation_method

Estimation method. Use "REML" for restricted maximum likelihood or "MLE" for maximum likelihood. REML is the default for ordinary model fitting. With lasso=TRUE, omitting this argument uses ML; an explicit value must be MLE.

variance

Character string naming the sampling-variance column for formula-based models.

varcov_type

Type of within-study variance-covariance matrix to use or construct. Common values include "univariate" for one supplied variance per row, "multilevel" for formula-based dependent effects, "weighted" or "cor_weighted" for correlation synthesis, and "smd_outcome" for standardized mean differences. Additional metric-aware options include shared-control continuous outcomes ("mean_diff", "log_response_ratio"), repeated-measures standardized change ("standardized_mean_change"), binary and rate outcomes ("log_rr", "log_or", "log_rate_ratio", "rate_difference"), survival summaries ("log_hr"), transformed proportions ("logit_proportion", "arcsine_proportion", "freeman_tukey_proportion"), partial correlations ("partial_cor", "partial_fisher_z"), reliability coefficients ("reliability", "log_reliability"), and Fisher-z correlation-matrix options ("fisher_z_simple", "fisher_z_weighted", "fisher_z_average"). See the Within-Study-VarCov-Metrics vignette for metric-specific options.

weights

Optional positive-definite inverse sampling covariance matrix, aligned with original input rows. It replaces within-study sampling covariance; fitted heterogeneity is added separately. Matrices coupling study blocks and supplied weights for expanded correlation inputs are unsupported. When supplied, these weights override the internally constructed within-study covariance for the corresponding analysis path.

structure

Between-study heterogeneity structure. Use "univariate" for single-effect models, "multilevel" for random-effect formulas, "UN" for an unstructured multivariate covariance, "DIAG1" for outcome-specific diagonal heterogeneity, or "DIAG2" for a common diagonal heterogeneity component.

intercept

Logical; controls whether the multivariate design matrix includes an intercept. Formula-based univariate and multilevel models use the intercept implied by formula.

missing

Missing-data handling mode. Use "remove" to drop incomplete rows, "keep" to keep rows as-is, or "em" to complete continuous missing moderators after multivariate-normal EM fitting. Repeated studies require study-level invariant moderators. Categorical missingness, unidentified models and nonconvergence are rejected. Other incomplete rows are dropped afterward. A warning identifies single-completion inference: standard errors do not propagate imputation uncertainty. Shared preparation completes source variables before constructing transformed or interaction columns. missing_data$em retains original/completed predictors and their missingness mask in original input row order. Outcome identifiers are excluded from the completion predictors.

optim_method

Optimization method that is passed to the optim function. Default is 'L-BFGS-B'.

robustID

Optional character string naming a cluster variable for cluster-robust standard errors when supported by the fitted workflow.

robust_args

Named list controlling robust covariance and small-sample inference. Defaults to CR2 covariance with Satterthwaite coefficient tests.

multivariate_covs

Optional one-sided formula specifying moderators for multivariate/correlation workflows, for example ~ publication_year + setting.

lasso

Logical. TRUE delegates to mars_lasso() and returns one mars_lasso object with selected point estimates, paths and CV diagnostics. It does not also fit an ordinary model. Both interfaces use the same unpenalized baselines, sampling covariance, preprocessing and penalty scale.

lasso_args

Named list of tuning arguments accepted by mars_lasso(), such as lambda_grid, folds, selection, lambda, penalty_factor, standardize, heterogeneity, prediction_scale, outcome_specific, seed, maxit and tol. An empty list uses that function's defaults, including selection='1se'. K is an alias for folds; supplying both is an error. All fold diagnostics are retained. all_lasso_metrics=FALSE and lambda_tolerance=0 are accepted as inert controls; other values are rejected. No smaller-lambda tolerance rule is applied: selection='min' resolves exact ties toward larger lambda.

tau2

Optional user-supplied between-study variance or covariance. If NULL, heterogeneity is estimated. For univariate models, supply one non-negative value. For multilevel models, supply one non-negative value per random-effect component. For multivariate DIAG2 models, supply one common value; for DIAG1, one value per outcome; and for UN, a positive semidefinite covariance matrix.

tol

Optimization tolerance forwarded to the L-BFGS-B factr control for ordinary fitting. With lasso=TRUE, an explicitly supplied tol is the numerical convergence tolerance in mars_lasso(); its default is 1e-7. Supply it either here or in lasso_args, not both.

control

Named ordinary-optimizer controls. The default allows 1000 iterations. For example, list(maxit=2000) increases that allowance. An explicit control$factr overrides tol. Nonconvergence emits a warning and is printed in summaries; downstream correlation synthesis rejects it.

vcov_method

Model-based coefficient covariance: "gls" (default) uses conditional GLS/expected information; "observed" uses the coefficient block of the inverse full observed ML information. Observed information requires a converged ML fit and a positive-definite full Hessian, and is withheld at heterogeneity boundaries. With supplied fixed tau2, both methods use the conditional coefficient covariance. This choice is retained for summaries, Wald intervals/tests and downstream correlation/CFA models. Cluster-robust covariance remains a separate inference choice.

...

Reserved for future extensions.

Value

With lasso=TRUE, a mars_lasso() object. Otherwise, a list with class "mars". Common ordinary-model components include:

  • data: analysis data after the selected missing-data handling.

  • formula, study_id, outcome_name, and structure: stored model specification.

  • beta_r and varcov_beta: fixed-effect estimates and their estimated covariance matrix.

  • est_values: estimated heterogeneity, covariance, or scale-location parameters.

  • fit_stats: model-fit statistics such as deviance, AIC, BIC, and related criteria when available.

  • QE: sampling-weighted common-effect homogeneity statistic. Multivariate fits additionally store QE$components (separate marginal outcome tests) and QE$joint_contributions (signed, additive outcome allocations of joint Q, with no separate tests). Marginal tests do not generally sum to joint Q for correlated outcomes. These data frames can be exported with utils::write.csv().

  • residuals, fitted_values, relative_weights, and heterogeneity summaries used by diagnostics and plotting helpers.

The exact component set varies by analysis path because univariate, multivariate and multilevel fits retain different intermediate matrices for downstream diagnostics and summaries.

Details

With lasso=TRUE, the fit is exactly the mars_lasso() analysis for the same inputs and tuning controls. Formula inputs default to structure='univariate'; specify 'multilevel' for a nested random-intercept formula. Effect-size inputs accept the omitted structure or an explicit 'multivariate' or 'DIAG1', all using outcome-specific diagonal heterogeneity. Explicit UN and DIAG2 structures are unsupported for LASSO. Only cor and smd effect-size families are supported. Correlations use Fisher-z fitting by default, with matched transformed sampling covariance and response-scale predictions. Responses in formula fits are not automatically standardized; reported coefficients retain the supplied response and predictor units. See mars_lasso() for the normalized penalized ML objective, grouped CV, convergence checks and selection interpretation.

LASSO does not support scale_formula, weights, tau2, robustID, nonempty robust_args, intercept=TRUE or optimizers other than L-BFGS-B. These options are rejected rather than ignored. Use heterogeneity='none' in lasso_args to fix all heterogeneity components at zero. Its result supports summary(), coef(), predict() and plot() methods for mars_lasso; ordinary mars inference and diagnostics do not apply. An ordinary fit of selected terms requires a separate lasso=FALSE call and does not account for moderator selection.

The main analysis paths are:

  • Formula-based univariate models: provide formula, variance, varcov_type = "univariate", and structure = "univariate".

  • Formula-based multilevel models: provide a random-effect formula, variance, varcov_type = "multilevel", and structure = "multilevel".

  • Correlation synthesis: provide effectsize_type = "cor", sample_size, variable_names, and an appropriate correlation varcov_type.

  • Non-correlation metric workflows: provide effectsize_type, effectsize_name, and the columns required by the selected metric-specific varcov_type.

When multiple effect sizes are available within a study, effectID, variable_names, random-effect terms, and the selected varcov_type determine how within-study dependence and between-study heterogeneity are represented. If a user-supplied weights matrix or tau2 value is provided, mars() treats those as fixed inputs for the corresponding part of the model rather than estimating or constructing them internally.

The core estimator treats the observed effect-size vector in study \(i\) as approximately multivariate normal, $$ y_i \sim N(X_i \beta, V_i), $$ where \(X_i\) is the fixed-effect design matrix and \(V_i\) is the model-implied marginal covariance matrix. The matrix \(V_i\) is the sum of the within-study sampling covariance matrix \(S_i\) and a between-study heterogeneity component. For univariate models this component is a scalar \(\tau^2\); for multivariate models it is the selected covariance structure across outcomes; and for multilevel models it is assembled from random-effect design matrices as $$ V_i = S_i + \sum_j \tau_j^2 Z_{ij} Z_{ij}'. $$ Location-scale models replace constant heterogeneity components with log-linear variance models, so study-specific components are computed as \(\tau_i^2 = \exp(W_i \gamma)\).

For maximum likelihood (estimation_method = "MLE"), mars() minimizes the deviance-scale objective $$ \sum_i \left\{\log |V_i| + (y_i - X_i \beta)' V_i^{-1} (y_i - X_i \beta)\right\}, $$ omitting constants that do not affect the optimizer. For restricted maximum likelihood (estimation_method = "REML"), the objective adds the usual fixed-effect adjustment $$ \log |X' V^{-1} X|, $$ where \(X' V^{-1} X = \sum_i X_i' V_i^{-1} X_i\). This penalizes the likelihood for estimating the fixed effects and is the default estimator.

Optimization is performed with optim. The default optim_method = "L-BFGS-B" is used because variance components and covariance-structure parameters require box constraints. Variance parameters are constrained to be positive with a lower bound of 1e-6; correlation parameters in structured covariance models are bounded to their allowable ranges when the structure supplies such bounds. The objective is evaluated using Cholesky decompositions, so \(\log |V_i|\) is computed from the Cholesky diagonal and quadratic forms are computed by triangular solves rather than by explicitly inverting \(V_i\). The main likelihood paths pass analytic gradients to optim(), and the fitted Hessian is retained for downstream uncertainty calculations when available. The tol argument is forwarded to the L-BFGS-B factr control; smaller values request tighter convergence.

References

Harville, D. A. (1977). Maximum likelihood approaches to variance component estimation and to related problems. Journal of the American Statistical Association, 72(358), 320–338. doi:10.1080/01621459.1977.10480998 .

Patterson, H. D., and Thompson, R. (1971). Recovery of inter-block information when block sizes are unequal. Biometrika, 58(3), 545–554. doi:10.1093/biomet/58.3.545 .

Viechtbauer, W. (2005). Bias and efficiency of meta-analytic variance estimators in the random-effects model. Journal of Educational and Behavioral Statistics, 30(3), 261–293. doi:10.3102/10769986030003261 .

Dempster, A. P., Laird, N. M., and Rubin, D. B. (1977). Maximum likelihood from incomplete data via the EM algorithm. Journal of the Royal Statistical Society: Series B (Methodological), 39(1), 1–22. doi:10.1111/j.2517-6161.1977.tb01600.x .

Sidik, K., and Jonkman, J. N. (2007). A comparison of heterogeneity variance estimators in combining results of studies. Statistics in Medicine, 26(9), 1964–1981. doi:10.1002/sim.2688 .

See also

mars_lasso() for a dedicated penalized meta-regression interface with unpenalized baselines and grouped cross-validation.

Examples

# \donttest{
fit <- mars(
  data = teacher_expectancy,
  studyID = "study",
  effectID = NULL,
  sample_size = NULL,
  formula = yi ~ 1,
  variance = "vi",
  varcov_type = "univariate",
  structure = "univariate"
)
summary(fit)
#> Results generated with MARS:v 0.6.0.8 
#> Friday, November 20, 2026
#> 
#> Model Type: 
#> univariate
#> 
#> Estimation Method: 
#> Restricted Maximum Likelihood
#> 
#> Coefficient covariance: gls
#> Optimizer convergence code: 0
#> 
#> 
#> Model Formula: 
#> yi ~ 1
#> <environment: 0x5c66b66d3fa8>
#> 
#> Data Summary: 
#> Number of Effect Sizes: 19
#> Number of Fixed Effects: 1
#> Number of Random Effects: 1
#> 
#> Random Components: 
#>       term     var     SD
#>  intercept 0.01882 0.1372
#> 
#> Fixed Effects Estimates: 
#>    attribute estimate      SE z_test p_value    lower  upper
#>  (Intercept)   0.0837 0.05164  1.621  0.1051 -0.01751 0.1849
#> 
#> Model Fit Statistics: 
#>  logLik   Dev   AIC   BIC  AICc
#>  -3.736 7.472 11.47 13.25 16.09
#> 
#> Q Error: 35.83 (18), p = 0.0074
#> 
#> I2 (General): 41.84668
#> 
#> Residual Diagnostics:
#>  Diagnostic                            Value  
#>  Observations                          19     
#>  Finite raw residuals                  19     
#>  Mean raw residual                     0.07998
#>  SD of raw residuals                   0.3589 
#>  Root mean squared residual            0.3583 
#>  Mean absolute residual                0.2491 
#>  Sum of squared Pearson residuals      25.6   
#>  Mean |studentized residual|           0.9379 
#>  Maximum |studentized residual|        2.782  
#>  Proportion |studentized residual| > 2 0.1053 
#>  Proportion |studentized residual| > 3 0      
#> 
#> Normality screen (Shapiro-Wilk, whitened residuals):
#>   N      W p-value
#>  19 0.9381  0.2432

mv_fit <- 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: Hessian inversion failed: Hessian is singular, indefinite, or numerically unidentified.
summary(mv_fit)
#> 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

ml_fit <- mars(
  data = school,
  formula = effect ~ 1 + (1 | district/study),
  studyID = "district",
  effectID = NULL,
  sample_size = NULL,
  variance = "var",
  varcov_type = "multilevel",
  structure = "multilevel",
  estimation_method = "MLE"
)
summary(ml_fit)
#> 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)
#> <environment: 0x5c66b66d3fa8>
#> 
#> 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
# }