Skip to contents

mars() 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.04

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

Multivariate 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$Tau

Network 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.04

Changing 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.