
Standardized Report for Correlation Synthesis and Latent Factors
synthesis_factor_report.RdBuilds 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 validreliabilityobject (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.
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.
# }