
Fit MARS Meta-Analytic Models
mars.RdPrimary 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
NULLfor 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
NULLfor formula-based univariate or multilevel models with an observedvariancecolumn.- 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", useeffectsize_namewith the selectedvarcov_type. LeaveNULLfor 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"andstructure = "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-levelstudyIDcluster.- 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 theWithin-Study-VarCov-Metricsvignette 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$emretains 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 multivariateDIAG2models, supply one common value; forDIAG1, one value per outcome; and forUN, a positive semidefinite covariance matrix.- tol
Optimization tolerance forwarded to the L-BFGS-B
factrcontrol 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 explicitcontrol$factroverridestol. 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 fixedtau2, 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, andstructure: stored model specification.beta_randvarcov_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 storeQE$components(separate marginal outcome tests) andQE$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 withutils::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", andstructure = "univariate".Formula-based multilevel models: provide a random-effect
formula,variance,varcov_type = "multilevel", andstructure = "multilevel".Correlation synthesis: provide
effectsize_type = "cor",sample_size,variable_names, and an appropriate correlationvarcov_type.Non-correlation metric workflows: provide
effectsize_type,effectsize_name, and the columns required by the selected metric-specificvarcov_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
# }