Skip to contents

Fits a study-bootstrap random forest for meta-analytic data without modifying the core estimation() pipeline. The function borrows the same data preparation patterns used in mars for univariate, multivariate, and multilevel inputs, then trains a forest-style ensemble of weighted regression trees with random predictor subsampling.

Usage

mars_rf(
  data,
  studyID,
  effectID = NULL,
  sample_size = NULL,
  effectsize_type = NULL,
  formula = NULL,
  variable_names = NULL,
  effectsize_name = NULL,
  variance = NULL,
  varcov_type,
  structure = "univariate",
  intercept = FALSE,
  missing = "remove",
  multivariate_covs = NULL,
  num_trees = 500L,
  mtry = NULL,
  minsplit = 10L,
  minbucket = 5L,
  cp = 0.001,
  maxdepth = 30L,
  sample_fraction = 1,
  seed = NULL,
  importance = TRUE,
  weighting = c("sampling", "uniform", "random"),
  selection = c("node", "tree"),
  min_studies = 2L,
  prediction_scale = c("fisher_z", "raw"),
  ...
)

Arguments

data

Data used for analysis.

studyID

Character string representing the study ID.

effectID

Effect ID column for long-form SMD inputs. Correlation inputs generate canonical pair identities from variable_names and expose them as numID.

sample_size

Character string representing study sample size.

effectsize_type

Type of effect size being analyzed, such as "cor" or "smd".

formula

Predictor formula for univariate models. Multilevel models additionally require one nested random-intercept term, such as (1 | district/study), with studyID naming the outermost group. Random slopes and crossed random terms are currently rejected.

variable_names

Vector of variables used for correlation synthesis in multivariate models.

effectsize_name

Character string naming the effect size column.

variance

Character string naming the variance column for formula-based fits.

varcov_type

Type of within-study sampling covariance. Correlation forests require raw-correlation simple, weighted, or average covariance (including their cor_ aliases). Sampling covariance must be positive definite; invalid variances are rejected.

structure

Structure label. Use "univariate" or "multilevel" for formula-based models. Multivariate models are inferred from effectsize_type.

intercept

Coding option for the stored multivariate design matrix. Terminal prediction models always include a baseline.

missing

Missing-data handling mode. Use "remove", "keep", or "em". EM completes continuous missing moderators, using one record per study when moderators are study-level invariant. Within-study variation with missingness requires external multilevel imputation. EM completion does not propagate imputation uncertainty, and disables OOB evaluation. With keep, missing predictors follow a direction learned at each split; all observations contribute to split loss. Terminal linear models fill missing predictors using their training-leaf median or modal level.

multivariate_covs

One-sided formula specifying moderator covariates for multivariate models.

num_trees

Number of trees in the forest.

mtry

Number of candidate moderators selected at each node (default) or once per tree. Defaults to \(\max(1,\lfloor\sqrt{p}\rfloor)\) for \(p\) moderators, or zero for multivariate models without moderators. Effect identity is retained separately and does not consume this budget. Explicit interaction columns count as predictors.

minsplit, minbucket

Tree-growing control parameters.

cp

Nonnegative fraction of the root weighted squared error required for a split. The same absolute penalty is used for cost-complexity pruning.

maxdepth

Maximum tree depth.

sample_fraction

Fraction of studies sampled with replacement for each tree.

seed

Optional random seed; the caller's RNG state is restored afterward.

importance

Logical; if TRUE, aggregate split-based variable importance across trees.

weighting

Split-loss weights: "sampling" (default) uses inverse sampling variances; "uniform" weights each observation equally; "random" is univariate-only and uses inverse sampling variance plus a nonnegative profiled ML intercept-model heterogeneity estimate, fitted separately to each in-bag sample. A sample with fewer than two distinct studies uses sampling weights and records an unavailable weight_tau. Terminal covariance fits retain the specified sampling covariance regardless of split weighting.

selection

"node" selects candidates at each split; "tree" selects a subset once for the entire tree. Terminal linear models use all available tree predictors, so node selection also yields a model-tree ensemble.

min_studies

Minimum distinct original resampling groups in each child node and for leaf variance estimation (which also requires at least two). Bootstrap copies do not count as additional independent groups.

prediction_scale

Correlation-only fitting scale: "fisher_z" (default) fits \(\operatorname{atanh}(r)\), using the delta covariance \(JSJ^T\), with diagonal \(J=1/(1-r^2)\), and returns \(\tanh(\hat z)\). This is a back-transformed location, not an integrated raw-scale random-effects expectation. "raw" fits r directly and can extrapolate beyond [-1,1].

...

Additional arguments are rejected.

Value

A list of class "mars_rf" containing the fitted forest, fitted and OOB predictions, variable importance, preprocessed data, and fit_diagnostics for terminal fits. Each tree records sampled units, their draw counts and its root variance estimates. random_tau is the componentwise median of multilevel tree-root estimates, not a confirmatory full-data variance estimate. Unsupported root fits are excluded; a component with no successful root fits is NA. Outcome-specific OOB metrics are returned in oob_by_effect. The stored refit_args permit grouped validation.

Details

All three paths use one additive weighted squared error criterion for growing and pruning trees. Terminal leaves in multivariate and multilevel forests are subsequently refined with GLS or profiled marginal ML fits. Within-study covariance and random effects enter leaf fitting, not the split criterion. The forest is an exploratory predictor, not a joint likelihood model for all leaves.

mars_rf() currently supports three analysis paths:

  • Univariate: weighted tree ensembles using study-level resampling and explicitly selected split-loss weights.

  • Multivariate: weighted trees with terminal ML models for outcome-specific heterogeneity and within-study sampling covariance.

  • Multilevel: weighted trees with nested-group bootstrap sampling and terminal random-intercept ML models. Child IDs are nested within their ancestors, so reused labels in different parents remain distinct.

Bootstrap multiplicities are retained as independent copies of entire study blocks. Correlation covariance pooling is repeated within each tree's training sample. Variance components are fitted only to in-bag observations. OOB predictions therefore exclude the held-out outcomes from tree fitting, but remain conditional on the prepared predictor representation. Use external grouped validation when preprocessing or tuning must also be validated.

Terminal ML minimizes \(\log|V| + (y-Xb)^T V^{-1}(y-Xb)\), profiling \(b\) by GLS and constraining variance components to be nonnegative. Nonconvergence, insufficient residual degrees of freedom, or indistinguishable variance components trigger an explicitly diagnosed sampling-covariance GLS fit. These likelihood values are never compared to choose tree splits. Known groups receive leaf BLUPs; unknown or omitted group IDs receive zero random-effect contributions. Predictor transformations are frozen at training. Split importance averages retained weighted-error reductions over trees and does not measure the additional contribution of terminal linear coefficients.

The function is intended for exploratory moderator detection, nonlinear pattern discovery, and structure-aware prediction inside meta-analytic data. Users who need the exact likelihood-based estimators reported by the core package should continue to use mars() for confirmatory model fitting.

Prediction accepts type = "response", "working" or "matrix". Multilevel re_form = "population" omits all BLUPs; "conditional" uses known groups where available. For complete correlation predictions, provide the internal study and effect columns (see study_id and effect_id). matrix_action = "warn" checks bounds and positive semidefiniteness; "error" rejects invalid matrices; "none" skips checks. Explicit "repair" uses Matrix::nearPD on complete matrices and records minimum eigenvalues and maximum changes. Fisher-z bounds alone do not guarantee a valid joint correlation matrix. Incomplete predictions cannot be repaired.

Multivariate ML leaves assume diagonal between-study heterogeneity by outcome; sampling-error covariance remains fully represented. Leaf-specific likelihoods do not define a single joint likelihood across the ensemble. Split importance does not include terminal linear prediction. OOB errors and grouped validation metrics use inverse raw sampling variances on the response scale, independent of the split weighting option. Use mars_rf_validate() for complete grouped validation and rf_importance() for held-out permutation importance. Tuning against those results requires an additional outer validation loop.

Formulas are parsed structurally. Parentheses retain ordinary predictors; response expressions are evaluated in data; explicit interactions also enter terminal linear models. Outcomes cannot be moderators. Specify moderators explicitly rather than using dot formulas. Correlation moderator names that conflict with generated fields are rejected with instructions to rename them. missing = "remove" removes rows with missing required outcomes, variances or moderators (whole matrices for wide correlation inputs); nonmissing invalid variances are errors. "keep" only permits missing predictors, not targets or covariance inputs. EM completes continuous moderators; future rows use the training conditional-normal moments. Entirely missing categorical predictors under keep are treated as constant predictors.

References

Breiman, L. (2001). Random forests. Machine Learning, 45, 5–32. doi:10.1023/A:1010933404324 .

van Lissa, C. J. (2020). Small sample meta-analyses: Exploring heterogeneity using MetaForest. In R. van de Schoot and M. Miočević (Eds.), Small Sample Size Solutions: A Guide for Applied Researchers and Practitioners (pp. 186–202). Routledge. doi:10.4324/9780429273872-16 .

Examples

rf_uni <- mars_rf(
  data = teacher_expectancy,
  formula = yi ~ year + weeks + factor(setting) + factor(tester),
  studyID = "study",
  variance = "vi",
  varcov_type = "univariate",
  structure = "univariate",
  num_trees = 25,
  seed = 123
)
summary(rf_uni)
#> Random forest meta-analysis
#> Structure: univariate 
#> Trees: 25 
#> Predictor selection: node ; split weighting: sampling 
#> Predictors: year, weeks, factor.setting., factor.tester. 
#> OOB predictions hold out complete resampling units; preprocessing is conditional on the prepared predictor representation. 
#> OOB coverage: 100 %
#> OOB RMSE: 0.172 
#> OOB R-squared: 0.3793 
#> 
#> Top variable importance:
#>        predictor  importance
#>            weeks 0.301833472
#>             year 0.030514171
#>  factor.setting. 0.015163429
#>   factor.tester. 0.007381912

rf_multi <- mars_rf(
  data = becker09,
  studyID = "ID",
  sample_size = "N",
  effectID = "numID",
  effectsize_type = "cor",
  varcov_type = "weighted",
  variable_names = c(
    "Cognitive_Performance",
    "Somatic_Performance",
    "Selfconfidence_Performance",
    "Somatic_Cognitive",
    "Selfconfidence_Cognitive",
    "Selfconfidence_Somatic"
  ),
  multivariate_covs = ~ Team,
  num_trees = 25,
  seed = 123
)
head(rf_importance(rf_multi))
#>   predictor importance
#> 1 effect_id 0.98263881
#> 2      Team 0.01736119