
User-Specified Heterogeneity in MARS
mars authors
2026-11-20
User-Specified-Heterogeneity.Rmdmars() usually estimates between-study heterogeneity
from the data. In some workflows, the analyst may want to fix
heterogeneity at a known or user-selected value instead. Common examples
include sensitivity analyses, comparisons against an external estimate,
or network meta-analysis models that use a prespecified common
heterogeneity value.
The tau2 argument fixes the between-study variance or
covariance and estimates the fixed effects conditional on that value.
When tau2 = NULL, the default, MARS estimates
heterogeneity.
Univariate Meta-analysis
For univariate models, tau2 is one non-negative
value.
fit_uni <- mars(
data = teacher_expectancy,
studyID = "study",
effectID = NULL,
sample_size = NULL,
formula = yi ~ 1,
variance = "vi",
varcov_type = "univariate",
structure = "univariate",
estimation_method = "MLE",
tau2 = 0.04
)
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: 19
#> Number of Fixed Effects: 1
#> Number of Random Effects: 1
#>
#> Random Components:
#> Between-study variance/covariance fixed by user-supplied tau2.
#> term var SD
#> intercept 0.04 0.2
#>
#> Fixed Effects Estimates:
#> attribute estimate SE z_test p_value lower upper
#> (Intercept) 0.09817 0.06296 1.559 0.119 -0.02523 0.2216
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -3.622 13.24 9.244 10.19 13.86
#>
#> Q Error: 35.83 (18), p = 0.0074
#>
#> I2 (General): 60.46742
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 19
#> Finite raw residuals 19
#> Mean raw residual 0.06551
#> SD of raw residuals 0.3589
#> Root mean squared residual 0.3554
#> Mean absolute residual 0.2499
#> Sum of squared Pearson residuals 20.06
#> Mean |studentized residual| 0.8197
#> Maximum |studentized residual| 2.585
#> Proportion |studentized residual| > 2 0.1053
#> Proportion |studentized residual| > 3 0
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 19 0.9302 0.1747
fit_uni$est_values$Tau
#> [,1]
#> [1,] 0.04The summary notes that the random component was fixed by the
user-supplied tau2 value.
Multilevel Meta-analysis
For multilevel models, supply one value per random-effect component. Named vectors are matched to the random-effect component names.
fit_ml <- 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",
tau2 = c(district = 0.03, study = 0.01)
)
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:
#> Between-study variance/covariance fixed by user-supplied tau2.
#> term var SD
#> district 0.03 0.1732
#> study 0.01 0.1000
#>
#> Fixed Effects Estimates:
#> attribute estimate SE z_test p_value lower upper
#> (Intercept) 0.1926 0.05859 3.287 0.001012 0.07776 0.3074
#>
#> Model Fit Statistics:
#> logLik Dev AIC BIC AICc
#> -15.07 38.14 32.14 34.16 33.85
#>
#> Q Error: 578.864 (55), p < 0.0001
#>
#> I2 (General):
#> names values
#> district 85.85
#> study 66.91
#>
#> I2 (Jackson): 97.5396
#> I2 (Between): 73.67202
#>
#> Residual Diagnostics:
#> Diagnostic Value
#> Observations 56
#> Finite raw residuals 56
#> Mean raw residual -0.07259
#> SD of raw residuals 0.3258
#> Root mean squared residual 0.331
#> Mean absolute residual 0.266
#> Sum of squared Pearson residuals 202.7
#> Mean |studentized residual| 1.544
#> Maximum |studentized residual| 6.034
#> Proportion |studentized residual| > 2 0.3214
#> Proportion |studentized residual| > 3 0.08929
#>
#> Normality screen (Shapiro-Wilk, whitened residuals):
#> N W p-value
#> 56 0.955 0.03593
fit_ml$est_values$Tau
#> district study
#> district 0.03 0.00
#> study 0.00 0.01Multivariate Meta-analysis
For multivariate models, the expected tau2 shape follows
the selected between-study covariance structure:
-
DIAG2: one common variance value -
DIAG1: one variance value per outcome -
UN: a full positive semidefinite covariance matrix
The next examples use the Becker data and are shown as templates because the model can take longer on some systems.
vars <- c(
"Cognitive_Performance",
"Somatic_Performance",
"Selfconfidence_Performance",
"Somatic_Cognitive",
"Selfconfidence_Cognitive",
"Selfconfidence_Somatic"
)
fit_mv_common <- mars(
data = becker09,
studyID = "ID",
effectID = "numID",
sample_size = "N",
effectsize_type = "cor",
varcov_type = "weighted",
variable_names = vars,
structure = "DIAG2",
estimation_method = "MLE",
tau2 = 0.02
)
Tau_user <- diag(0.03, length(vars))
Tau_user[lower.tri(Tau_user)] <- 0.005
Tau_user[upper.tri(Tau_user)] <- 0.005
fit_mv_un <- mars(
data = becker09,
studyID = "ID",
effectID = "numID",
sample_size = "N",
effectsize_type = "cor",
varcov_type = "weighted",
variable_names = vars,
structure = "UN",
estimation_method = "MLE",
tau2 = Tau_user
)
fit_mv_un$est_values$TauNetwork Meta-analysis
A scalar tau2 fixes common pairwise treatment-contrast
variance. Multilevel models take one named variance per grouping level.
Multivariate models accept a named positive-semidefinite basic-effect
covariance in the selected reference coordinates. This covariance is
separate from sampling covariance.
d <- data.frame(study=1:6,a=rep(c("A","A","B"),2),
b=rep(c("B","C","C"),2),effect=c(.2,.5,.3,.3,.6,.2),variance=.04)
fixed <- network_meta(d,"study","a","b","effect","variance",
heterogeneity="common",tau2=.03,reference="A")
fixed$heterogeneity_summary
#> $tau2
#> component tau2
#> study study 0.03
#>
#> $covariance
#> NULL
#>
#> $boundary
#> [1] FALSE
Omega <- matrix(c(.03,.01,.01,.04),2,
dimnames=list(c("d_B","d_C"),c("d_B","d_C")))
multivariate <- network_meta(d,"study","a","b","effect","variance",
model_type="multivariate",tau2=Omega,reference="A")
multivariate$fit$Omega
#> d_B d_C
#> d_B 0.03 0.01
#> d_C 0.01 0.04Changing reference requires transforming a supplied basic-effect covariance; keeping its numerical entries unchanged would specify a different model.
Practical Notes
Fixed tau2 values are treated as user inputs, not
estimated parameters. They are therefore not assigned heterogeneity
standard errors, and model comparisons should be interpreted as
conditional on the supplied heterogeneity values.
tau2 cannot be combined with scale_formula,
because scale-location models estimate heterogeneity as a function of
predictors. It also cannot be combined with lasso = TRUE in
the current implementation.