Skip to contents

Builds a standardized report object with pooled correlations, uncertainty, heterogeneity summaries, latent-factor solution tables, publication-ready tables, plot-ready matrices, reproducibility metadata, and limitations.

Usage

synthesis_factor_report(
  mars_object,
  factor_method = c("none", "efa", "cfa"),
  n_factors = 1L,
  cfa_model = NULL,
  group_var = NULL,
  loading_threshold = 0.3,
  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"),
  missing_sensitivity = FALSE,
  attenuation_sensitivity = FALSE,
  reliability_scenarios = NULL,
  pd_adjust = c("none", "eigen_clip", "nearpd"),
  pd_tol = 1e-08,
  include_publication_bias = TRUE,
  vcov_source = c("model", "robust"),
  ...
)

# S3 method for class 'synthesis_report'
summary(object, ...)

# S3 method for class 'synthesis_report'
print(x, digits = max(3, getOption("digits") - 3), ...)

# S3 method for class 'synthesis_report'
plot(
  x,
  type = c("pooled_r", "heterogeneity", "residuals", "calibration", "loadings", "path",
    "influence", "influence_heatmap", "invariance"),
  main = NULL,
  main_adj = 0.5,
  main_line = NULL,
  invariance_legend_position = "bottomleft",
  invariance_legend_title = NULL,
  path_center_latent = TRUE,
  path_latent_x = NULL,
  path_observed_x = NULL,
  path_latent_span = c(0.2, 0.8),
  path_observed_span = c(0.1, 0.9),
  path_latent_y = 0.8,
  path_observed_y = 0.2,
  path_latent_cex = 1,
  path_observed_cex = 0.9,
  path_arrow_col = "gray40",
  path_arrow_lwd = 1,
  path_arrow_length = 0.08,
  path_loading_cex = 0.75,
  path_latent_min_gap = 0.06,
  path_covariances = TRUE,
  path_residuals = TRUE,
  path_factor_variances = TRUE,
  path_digits = 3,
  ...
)

Arguments

mars_object

A fitted object returned by mars.

factor_method

One of "none", "efa", or "cfa".

n_factors

Number of factors when factor_method = "efa".

cfa_model

Lavaan-style latent model syntax when factor_method = "cfa".

group_var

Retained for compatibility. When supplied, the report explains that multi-group invariance testing is unavailable. Separate group synthesis and joint estimation are required.

loading_threshold

Absolute-value threshold used to flag salient loadings in publication-ready tables.

synthesis_method

Correlation synthesis method: "model", "average", or "weighted".

synthesis_transform

Optional pooling transform for "average"/"weighted": "none" or "fisher_z".

missing_corr

Missing-correlation handling for synthesized matrices. One of "available", "pairwise", or "em".

attenuation

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

reliability

Reliability input used when attenuation = "correct".

reliability_missing

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

missing_sensitivity

Logical; if TRUE, computes pooled-correlation sensitivity across missing-correlation handling methods.

attenuation_sensitivity

Logical; if TRUE, computes pooled-correlation sensitivity across attenuation settings.

reliability_scenarios

Optional named list of reliability inputs used when attenuation_sensitivity = TRUE. Each element should be a valid reliability object (named vector or data frame).

pd_adjust

Positive-definite repair for synthesized correlations: "none", "eigen_clip", or "nearpd".

pd_tol

Minimum eigenvalue tolerance used by pd_adjust = "eigen_clip".

include_publication_bias

Logical; if TRUE, attempts an Egger-type small-study-effects check.

vcov_source

"model" or "robust" pooled-correlation covariance, used consistently for reported intervals and downstream factor inference.

...

Additional graphical arguments passed to the underlying plotting functions.

object

An object of class "synthesis_report".

x

An object of class "synthesis_report".

digits

Number of digits used when printing numeric tables.

type

Plot type to display. One of "pooled_r", "heterogeneity", "residuals", "calibration", "loadings", "path", "influence", "influence_heatmap", or "invariance".

main

Optional plot title.

main_adj

Horizontal title alignment in [0, 1].

main_line

Optional title line. If NULL, the graphics default is used.

invariance_legend_position

Legend position for the invariance plot, or "none" to suppress it.

invariance_legend_title

Optional legend title for the invariance plot.

path_center_latent

Logical; if TRUE, center latent nodes above their indicators in path diagrams.

path_latent_x

Optional numeric vector of x positions for latent variables in the path diagram.

path_observed_x

Optional numeric vector of x positions for observed indicators in the path diagram.

path_latent_span

Numeric length-2 vector giving the horizontal span used for latent nodes when positions are generated automatically.

path_observed_span

Numeric length-2 vector giving the horizontal span used for observed nodes when positions are generated automatically.

path_latent_y

Vertical position for latent nodes in the path diagram.

path_observed_y

Vertical position for observed nodes in the path diagram.

path_latent_cex

Text scaling for latent-node labels.

path_observed_cex

Text scaling for observed-node labels.

path_arrow_col

Arrow color for the path diagram.

path_arrow_lwd

Arrow line width for the path diagram.

path_arrow_length

Arrowhead length for the path diagram.

path_loading_cex

Text scaling for path loading labels.

path_latent_min_gap

Minimum horizontal spacing enforced between latent nodes when positions are generated automatically.

path_covariances

Show nonzero latent covariances in CFA path plots.

path_residuals

Show observed-indicator residual variance loops in CFA path plots.

path_factor_variances

Show latent variances in a caption, marking fixed values.

path_digits

Number of decimal places for CFA path parameter labels. Labels use the fitted (unstandardized) parameter scale. Unit factor variances make factor covariances equal correlations. Latent variances are disturbance variances when structural regressions predict factors.

Value

An object of class synthesis_report.

Details

Correlation intervals are pointwise normal intervals centered on each pooled correlation, using the matched coefficient covariance; endpoints may exceed [-1,1] under this approximation. Alternative pooling and repaired matrices have no matched sampling covariance, so their intervals are NA. Heterogeneity entries are between-study standard deviations, not sampling standard errors.

CFA defaults to correlation-structure WLS when matched covariance is available. The loading table distinguishes raw marker-scaled and standardized loadings; salient CFA loadings use the standardized values. EFA communalities and implied matrices include oblique factor correlations. Optional EFA loading uncertainty and CFA WLS uncertainty are retained in the report tables and factor fit.

Model-based leave-one-study-out influence refits the original synthesis specification. Average/weighted pooling is recomputed on the reduced data. Attenuation, missing-correlation and repair options are preserved. Frobenius change measures the matrix-wide shift; maximum absolute change measures the largest cell shift. Neither is a significance test. Failed refits are labelled with NA shifts, estimability and reasons. Objects without a stored model-refit specification cannot provide model-based study influence.

Optional parallel analysis is descriptive sensitivity, not calibrated factor retention inference. Multi-group invariance testing is unavailable: valid tests require separately synthesized group matrices, their joint sampling covariance, and shared-parameter estimation. Supplying group_var returns this explanation. Publication-bias checks are exploratory and do not establish selective reporting. See path_model() and efa_from_synthesis() for inference assumptions and limits.

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.
report <- synthesis_factor_report(fit, factor_method = "efa", n_factors = 1)
#> Warning: Hessian inversion failed: Hessian is singular, indefinite, or numerically unidentified.
summary(report)
#> Synthesis Factor Report
#> Pooled correlation matrix dimension: 4 x 4 
#> Factor method: efa 
#> Model decisions:
#>   method: model 
#>   transform: none 
#>   missing_corr: available 
#>   attenuation: none 
#>   pd_adjust: none | adjusted: FALSE 
#> 
#> Fit indices:
#>  chi_square df p_value
#>          NA  2      NA
#> 
#> Factor loadings table:
#>       indicator Factor1 communality uniqueness salient
#>     Performance -0.1260     0.01589     0.9841   FALSE
#>       Cognitive  0.7715     0.59517     0.4048    TRUE
#>         Somatic  0.6961     0.48458     0.5154    TRUE
#>  Selfconfidence -0.5893     0.34731     0.6527    TRUE
#> 
#> Factor inference:
#>  CFA WLS inference uses the matched estimated correlation sampling covariance. Descriptive fits and EFA have no sample-size-based global fit tests. Alternative pooling/repair has no matched sampling covariance; its SEs and CIs are unavailable. 
#> 
#> Sensitivity:
#>  Leave-one-study-out max Frobenius change = 0.1411; max absolute cell change = 0.07362. 
# }