Master Estimation Function — estimation • mars

The primary estimation function for conducting the optimization. The function is typically called through the mars function, but can be called here directly.

Usage

estimation(
  formula = NULL,
  scale_formula = NULL,
  effect_name = NULL,
  studyID = NULL,
  effectID = NULL,
  variance = NULL,
  data,
  estimation_method = "REML",
  optim_method = "L-BFGS-B",
  structure = "UN",
  varcov_type,
  weights = NULL,
  intercept = FALSE,
  N = NULL,
  missing = "remove",
  robustID = NULL,
  unique_n = NULL,
  lasso = FALSE,
  lasso_args = list(lambda_grid = 10^seq(1, -3, length.out = 5), K = 5, all_lasso_metrics
    = FALSE, lambda_tolerance = 0),
  multivariate_covs = NULL,
  tau2 = NULL,
  tol = 1e-10,
  ...
)

Arguments

formula: The formula used for specifying the fixed and random structure. Used for univariate and multilevel structures.
scale_formula: Optional one-sided formula for modeling the log-heterogeneity in location-scale models. Currently supported for structure = "univariate" and structure = "multilevel". 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-level studyID cluster.
effect_name: Character string representing the name of the effect size column in the data.
studyID: Character string representing the study ID
effectID: Character string representing the effect size ID
variance: Character string representing the name of the variance of the effect size in the data.
data: Data used for analysis
estimation_method: Type of estimation used, either "REML" or "MLE", REML is the default
optim_method: Optimization method that is passed to the optim function. Default is 'L-BFGS-B'.
structure: Between studies covariance structure, default is "UN" or unstructured. See details for more specifics.
varcov_type: Type of variance covariance matrix computed. Default is 'cor_weighted' for correlations or 'smd_outcome' for standardized mean differences.
weights: User specified matrix of weights.
intercept: Whether a model intercept should be specified, default is FALSE meaning no intercept. See details for more information.
N: Character string representing the sample size of the studies.
missing: What to do with missing data. Use "remove" to drop incomplete rows, "keep" to keep rows as-is, or "em" to impute missing moderator values via a multivariate-normal EM routine before dropping any remaining incomplete rows.
robustID: A character vector specifying the cluster group to use for computing the robust standard errors.
unique_n: A numeric vector of unique sample sizes, calculated internally.
lasso: TRUE/FALSE indicator that specifies if lasso results are returned. TRUE means lasso results will be run, if number of predictors is less than number of effect sizes, both lasso and non-lasso results will be returned, if number of predictors is equal to or greater than the number of effect sizes, the lasso results will only be returned.
lasso_args: A list of LASSO specific arguments. lambda_tolerance controls tie-breaking across lambda values by choosing the smaller lambda when CV metrics are within this tolerance.
multivariate_covs: A one-sided formula to specify the covariates used in a multivariate analysis.
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 multivariate DIAG2 models, supply one common value; for DIAG1, one value per outcome; and for UN, a positive semidefinite covariance matrix.
tol: Tolerance for estimating, passed to optim
...: Additional arguments to pass to optim.

Value

Output is a named list; The output returns the estimated parameters, fit statistics, estimation inputs.

Examples

if (FALSE) { # \dontrun{
fit <- estimation(
  formula = yi ~ 1,
  effect_name = "yi",
  studyID = "study",
  variance = "vi",
  data = teacher_expectancy,
  structure = "univariate",
  varcov_type = "univariate"
)
fit$coefficients
} # }