Skip to contents

Fit path or latent-variable models to a synthesized correlation matrix and optionally propagate uncertainty from the meta-analytic synthesis into the path coefficients.

Usage

path_model(
  mars_object,
  model,
  num_obs = NULL,
  adjust_se = TRUE,
  se_method = c("delta", "simulation", "bootstrap"),
  vcov_source = c("model", "robust"),
  se_draws = 1000,
  se_seed = NULL,
  method_null = "sem",
  synthesis_method = c("model", "average", "weighted"),
  synthesis_transform = c("none", "fisher_z"),
  missing_corr = c("available", "pairwise", "em"),
  attenuation = c("none", "correct"),
  reliability = NULL,
  reliability_missing = c("error", "skip", "impute_mean", "assume_1"),
  pd_adjust = c("none", "eigen_clip", "nearpd"),
  pd_tol = 1e-08,
  fit_method = c("auto", "wls", "descriptive"),
  ...
)

Arguments

mars_object

The mars fitted object, or an object returned by mixed_corr_meta.

model

Model syntax in a lavaan-like format. Regression paths use ~, latent measurement paths use =~, and residual variances or covariances use ~~.

num_obs

Optional size used only by internal descriptive calculations. It does not calibrate fit tests for synthesized correlations. WLS uses the supplied sampling covariance and does not use this argument.

adjust_se

Logical; if TRUE, compute standard errors that reflect uncertainty in the synthesized correlation matrix when supported by se_method.

se_method

"delta" uses expected WLS information for a WLS fit, or propagates the full correlation covariance through observed-variable descriptive regression coefficients. Descriptive latent delta SEs are withheld. "simulation" refits draws from the joint normal approximation to the pooled correlations; "bootstrap" refits named correlation draws or resamples independent studies/clusters and refits the original synthesis. Resampling requires at least 50 admissible fits and an 80 percent success rate. Failure counts and source-bootstrap diagnostics are returned.

vcov_source

Source of pooled-correlation uncertainty. "model" uses the model-based covariance and "robust" uses the selected cluster-robust covariance stored in the MARS fit.

se_draws

Number of draws/resamples used when se_method = "simulation" or "bootstrap".

se_seed

Optional random seed for se_method.

method_null

Null-model method for observed-variable path models. Currently "sem" uses the SEM-style independence model implemented by model_fit. Latent-variable models use their internal independence-model calculation and ignore this argument.

synthesis_method

Correlation synthesis method used to build the matrix supplied to latent/path modeling. One of "model" (default, use the fitted MARS coefficients), "average", or "weighted".

synthesis_transform

Optional transform applied for "average"/"weighted" pooling. One of "none" or "fisher_z".

missing_corr

Missing-correlation handling for synthesized matrices. One of "available" (fallback to model-estimated pair), "pairwise" (pairwise pooling with simple fill for absent pairs), or "em" (iterative matrix completion, not likelihood-based EM).

attenuation

Attenuation-correction mode for synthesized correlations. One of "none" or "correct".

reliability

Reliability input used when attenuation = "correct". Accepts either a named numeric vector by variable or a data frame with variable/reliability columns (optionally with a study column).

reliability_missing

Strategy for missing reliability values. One of "error", "skip", "impute_mean", or "assume_1".

pd_adjust

Positive-definite repair applied to the synthesized correlation matrix prior to model fitting. One of "none", "eigen_clip", or "nearpd".

pd_tol

Minimum eigenvalue tolerance used by pd_adjust = "eigen_clip".

fit_method

"auto" selects "wls" when matched pooled-correlation sampling covariance is available, otherwise "descriptive". Explicit WLS requires finite symmetric positive-definite sampling covariance. Singular weights cause an error; they are not silently regularized.

...

Reserved for future extensions.

Value

List output with class path; The output is the parameter estimates from the fitted path model, joint directed-coefficient covariance, fitting method, uncertainty diagnostics and standardized factor details.

Details

The synthesized correlation vector is ordered by the column-major lower triangle. The model and its sampling covariance must describe the same estimator and variable pairs. Model pooling uses fitted means; average and sample-size-weighted pooling reconstruct correlations from study data. Alternative pooling, attenuation correction or positive-definite repair has no matched sampling covariance in this workflow, so auto fitting is descriptive and corresponding uncertainty is withheld. Repair magnitude and eigenvalues are recorded in synthesis.

WLS minimizes $$Q(\theta)=(\hat r-r(\theta))^T V_{\hat r}^{-1}(\hat r-r(\theta)).$$ RAM matrices define the model-implied covariance. Observed residual variances are computed to constrain all observed variances to one. Latent factors use a marker loading of one unless a nonzero loading or positive factor variance is fixed explicitly. Numeric fixed loadings and residual covariances are supported; fixed endogenous variances, mean structures and equality labels are not supported by this WLS interface. Variance bounds, covariance validity, optimization convergence and local Jacobian rank are checked. All specified paths are fit jointly; overidentified WLS coefficients need not equal coefficients from separate regressions on the pooled matrix.

For q correlations and Jacobian rank d, the asymptotic global test is chi-square with q-d degrees of freedom, conditional on the estimated sampling covariance. A saturated model has zero degrees of freedom and no global p-value. CFI and TLI use an independence model with the same weights; raw and bounded indices are returned. RMSEA is unavailable because a single effective sample size is not specified for synthesized correlations. SRMR is descriptive. Small numbers of studies, estimated heterogeneity and estimated robust covariances limit the asymptotic calibration.

WLS parameter covariance is the inverse expected information \((J^T V_{\hat r}^{-1}J)^{-1}\), without a residual-scale multiplier. This can differ from observed-Hessian standard errors. All directed paths retain their joint covariance in computed_vcov; path_effects() uses it for direct and indirect effects across equations. CFA also reports raw and standardized loadings and marginal factor correlations. Fixed paths receive no coefficient p-values. Normal Wald inference is pointwise and unadjusted.

Descriptive observed-variable models compute standardized regression coefficients from their correlation submatrices. Descriptive latent models minimize a normal-theory covariance discrepancy, with log-scale variances. Their chi-square, CFI, TLI and RMSEA are withheld for synthesized data even when num_obs is provided. Supplying a sample size does not replace the sampling covariance required for synthesis-aware inference.

Simulation and bootstrap fits use the same fitting objective as the point estimate. Invalid correlations and inadmissible fits are counted, not silently repaired. The reported uncertainty conditions on accepted draws and on the chosen synthesis/model specification; inspect acceptance rates and perform sensitivity analyses when exclusions are substantial.

Examples

# \donttest{
fit <- mars(
  data = becker09,
  studyID = "ID",
  effectID = "numID",
  sample_size = "N",
  effectsize_type = "cor",
  varcov_type = "weighted",
  variable_names = c(
    "Cognitive_Performance",
    "Somatic_Performance",
    "Selfconfidence_Performance",
    "Somatic_Cognitive",
    "Selfconfidence_Cognitive",
    "Selfconfidence_Somatic"
  )
)
#> Warning: Hessian inversion failed: Hessian is singular, indefinite, or numerically unidentified.
path_model(fit, "Performance ~ Cognitive + Somatic + Selfconfidence")
#> Results generated with MARS:v 0.6.0.8 
#> Friday, November 20, 2026
#> 
#> Model Type: 
#> multivariate
#>  
#> Average Correlation Matrix: 
#>                Performance   Cognitive     Somatic Selfconfidence
#> Performance     1.00000000 -0.03392171 -0.07107749      0.2328540
#> Cognitive      -0.03392171  1.00000000  0.54416063     -0.4529783
#> Somatic        -0.07107749  0.54416063  1.00000000     -0.3975680
#> Selfconfidence  0.23285398 -0.45297829 -0.39756797      1.0000000
#> 
#> Synthesis options:
#>   method: model 
#>   pooled coefficient covariance: gls 
#>   transform: none 
#>   missing_corr: available 
#>   attenuation: none 
#>   pd_adjust: none 
#>   pd_adjusted: FALSE 
#>   min eigen (before/after): 0.4405 / 0.4405 
#>   Fit note: Asymptotic WLS chi-square conditional on the matched estimated sampling covariance; RMSEA is unavailable. 
#> 
#>  
#>  Model Fitted: 
#>  Performance ~ Cognitive + Somatic + Selfconfidence 
#>  
#> Fixed Effects: 
#>                                    predictor     outcome    estimate
#> Cognitive -> Performance           Cognitive Performance  0.09768127
#> Somatic -> Performance               Somatic Performance -0.01670561
#> Selfconfidence -> Performance Selfconfidence Performance  0.27045986
#>                               standard_errors test_statistic     p_value
#> Cognitive -> Performance           0.14320353      0.6821149 0.495166283
#> Somatic -> Performance             0.07292266     -0.2290867 0.818801513
#> Selfconfidence -> Performance      0.10449006      2.5883789 0.009642886
#> 
#>  
#>  Fit Statistics: 
#>                    Type      Value
#> 1      Model Chi-Square      0 (0)
#> 2 Null Model Chi-Square 410.49 (6)
#> 3                   CFI          1
#> 4                   TLI       <NA>
#> 5                 RMSEA       <NA>
#> 6                  SRMR          0
#> 7             CFI (raw)          1
#> 8             TLI (raw)       <NA>
# }