Skip to contents

Fits univariate, nested multilevel or multivariate meta-regression with an L1 penalty on moderator coefficients and unpenalized mean baselines.

Usage

mars_lasso(
  data,
  studyID,
  formula = NULL,
  variance = NULL,
  structure = "univariate",
  effectID = NULL,
  sample_size = NULL,
  effectsize_type = NULL,
  variable_names = NULL,
  effectsize_name = NULL,
  varcov_type = NULL,
  multivariate_covs = NULL,
  outcome_specific = FALSE,
  lambda_grid = 10^seq(2, -3, length.out = 20),
  folds = 5L,
  selection = c("1se", "min", "fixed"),
  lambda = NULL,
  penalty_factor = NULL,
  standardize = TRUE,
  heterogeneity = c("estimate", "none"),
  prediction_scale = c("fisher_z", "raw"),
  missing = c("remove", "em"),
  seed = 1L,
  maxit = 200L,
  tol = 1e-07,
  ...
)

mars_lasso_univariate(data, formula, studyID, variance, ...)

mars_lasso_multilevel(data, formula, studyID, variance, ...)

mars_lasso_multivariate(data, studyID, effectsize_type, effectID = NULL, ...)

Arguments

data

Data frame of effect estimates, sampling inputs and moderators.

studyID

Column naming independent studies or the outermost multilevel group.

formula

Two-sided univariate/multilevel formula. One additive nested random-intercept term is supported for multilevel fits; random slopes and crossed terms are unsupported. Parenthesized predictors and response expressions are preserved. Specify predictors explicitly rather than using a dot formula.

variance

Sampling variance column for formula inputs.

structure

univariate or multilevel for formula inputs; multivariate is inferred for effect-size inputs.

effectID

Effect ID column for long-form SMD inputs. Correlation inputs generate canonical pair IDs and do not require this argument.

sample_size

Sample-size column for multivariate inputs.

effectsize_type

cor or smd for multivariate inputs.

variable_names

Complete pair-named correlation columns for wide input.

effectsize_name

Effect estimate column for long-form SMD input.

varcov_type

Sampling-covariance type. Defaults to univariate/multilevel for formula inputs and weighted for correlations. Specify a valid SMD type explicitly. Sampling covariance must be positive definite.

multivariate_covs

Explicit one-sided moderator formula for multivariate input.

outcome_specific

FALSE fits common moderator slopes across outcomes; TRUE fits separate penalized slopes by outcome, retaining unpenalized baselines.

lambda_grid

Distinct finite nonnegative penalties. The default grid is fixed in advance, not computed from held-out outcomes. Fits run in descending order with warm starts. Expand the grid if selection reaches an endpoint.

folds

Number of study/group cross-validation folds, at least three and no greater than independent groups. Each training fold refits all preprocessing and variance components. Use NULL with selection='fixed' to skip tuning.

selection

min minimizes mean held-out Gaussian negative log likelihood; 1se chooses the largest penalty within one fold-score standard error of the minimum. Exact min-score ties prefer the largest lambda. fixed uses lambda directly and skips cross-validation.

lambda

Explicit penalty with selection='fixed'.

penalty_factor

Optional nonnegative weights for fixed design columns, preferably named. Unspecified moderator weights are one; baseline weights are always zero. No rescaling of penalty factors is performed.

standardize

TRUE centers and scales nonbaseline design columns using training-fold sample standard deviations. Encoded categorical contrasts and interaction columns are scaled individually. Baselines remain unscaled; no centering occurs in an explicitly intercept-free formula.

heterogeneity

estimate fits nonnegative ML variance components; none fixes all components at zero, yielding penalized sampling-covariance GLS.

prediction_scale

Correlation fits use fisher_z by default, with \(\operatorname{atanh}(r)\) and delta covariance \(JSJ^T\). Predictions return \(\tanh(\hat z)\). raw fits r directly and can extrapolate beyond correlation bounds.

missing

remove drops incomplete required records (whole matrices for wide correlation input); em supports training-fold continuous-moderator completion. Entirely missing or categorical incomplete EM moderators are unsupported. Imputation uncertainty is not propagated.

seed

Fold assignment seed; the caller's RNG state is restored.

maxit

Maximum alternating mean/covariance iterations per start.

tol

Positive numerical convergence tolerance.

...

Unsupported arguments are rejected.

Value

A mars_lasso object containing selected point estimates, lambda, coefficient and variance-component paths, convergence diagnostics, training preprocessing, fold assignments, group-level validation scores and CV summary. Ordinary Wald standard errors, p-values and confidence intervals are not returned for selected coefficients. These require selection-aware inference.

Details

For G independent groups, the optimized criterion is $$[\sum_g \{\log|V_g|+(y_g-X_g\beta)^T V_g^{-1}(y_g-X_g\beta)\}]/(2G) + \lambda \sum_j a_j |\beta_j|.$$ Penalties apply on the standardized design scale; reported coefficients are restored to the supplied design units. Transformed predictors retain their transformation units. Intercepts and multivariate outcome baselines have \(a_j=0\). Categorical contrasts are penalized individually, not as a group, so selection can depend on contrast coding. A zero coefficient is a numerical LASSO selection result, not evidence of a zero causal or population effect.

Sampling covariance is represented in every block. Univariate heterogeneity adds an independent effect-level variance; nested multilevel models add random-intercept covariance; multivariate models use diagonal between-study heterogeneity by outcome. They do not estimate an unstructured between-outcome heterogeneity matrix. REML, scale formulas, random slopes and post-selection robust/Wald inference are outside this interface.

Coordinate descent solves the mean LASSO problem conditional on covariance; bounded ML optimization updates variance components. Stationarity diagnostics and multiple deterministic starts are used because joint variance estimation is nonconvex. Final KKT residuals must not exceed \(\max(10^{-5},\sqrt{\mathrm{tol}})\); coordinate updates use tol directly. Convergence does not prove a global optimum. Failed paths or folds are diagnosed, not assigned fabricated scores; a lambda is eligible for selection only when every fold succeeds and its full-data fit converges.

Validation predicts population means for new groups and uses training covariance estimates plus held-out sampling covariance. Correlation pooled covariance is learned from training matrices and transferred to held-out sample sizes. Each group contributes its whole multivariate log-density score; larger blocks can contribute more. The 1se rule uses the standard deviation of fold mean scores divided by \(\sqrt{K}\), an approximate tuning rule rather than a confidence interval. Tuning-fold results are not an independent final performance evaluation; use an outer grouped validation loop for that purpose.

Unknown categorical levels/outcomes fail prediction and are reported in CV diagnostics. Coefficients are mean-model coefficients, not BLUPs. With pooled correlation covariance, held-out Fisher-z derivatives use training pooled correlations; simple sampling covariance uses supplied held-out study sampling inputs. Correlation prediction supports explicit complete-matrix checks and repair; bounded pairs alone do not guarantee a positive-semidefinite matrix. The main mars() interface with lasso=TRUE delegates to this same engine and returns this same class. Place tuning controls in its lasso_args list; folds can also be named K. Both routes share defaults and produce identical estimates, paths, CV scores and predictions for matched inputs. Call records may differ. Explicit estimation_method in mars() must be MLE, and an explicit multivariate structure must be multivariate or DIAG1. See mars() for unsupported ordinary-fitting arguments and argument mapping.

References

Tibshirani, R. (1996). Regression shrinkage and selection via the lasso. Journal of the Royal Statistical Society: Series B (Methodological), 58(1), 267–288. doi:10.1111/j.2517-6161.1996.tb02080.x .

Friedman, J. H., Hastie, T., and Tibshirani, R. (2010). Regularization paths for generalized linear models via coordinate descent. Journal of Statistical Software, 33(1), 1–22. doi:10.18637/jss.v033.i01 .

Examples

fit <- mars_lasso_univariate(teacher_expectancy, yi ~ year + weeks,
  "study", "vi", lambda_grid=c(10,1,.1), folds=3, seed=1)
coef(fit)
#> (Intercept)        year       weeks 
#>  0.07774547  0.00000000  0.00000000 

# The general interface also accepts a fixed penalty.
general <- mars_lasso(teacher_expectancy, "study", yi ~ year + weeks, "vi",
                      selection = "fixed", lambda = .1)
coef(general)
#> (Intercept)        year       weeks 
#> 37.25822746 -0.01882768 -0.01336234 

x <- seq(-2, 2, length.out = 24)
nested <- data.frame(district = rep(1:8, each = 3), study = 1:24,
                     x = x, y = 2 + .6 * x + .05 * sin(1:24), vi = .05)
multilevel <- mars_lasso_multilevel(nested, y ~ x + (1 | district/study),
                                    "district", "vi",
                                    lambda_grid = c(1, .1), folds = 3)
coef(multilevel)
#> (Intercept)           x 
#>   2.0001546   0.5930615 

i <- 1:12
correlations <- data.frame(study = i, n = seq(60, 170, 10), z = i,
                           b_a = .1 + .01 * i, c_a = .2 + .01 * i,
                           c_b = .3 + .01 * i)
multivariate <- mars_lasso_multivariate(
  correlations, "study", "cor", sample_size = "n",
  variable_names = c("b_a", "c_a", "c_b"), multivariate_covs = ~ z,
  lambda_grid = c(1, .1), folds = 3
)
coef(multivariate)
#>   outcome_1   outcome_2   outcome_3           z 
#> 0.104957299 0.210495034 0.322475863 0.009599696