Compute between-level factor-score correlations

The centerpiece of the bass-ackwards algebra. For any engine whose scoring is a linear map S = Z W, the cross-level correlation matrix is:

Usage

compute_edges(
  levels,
  R,
  edge_method = c("auto", "algebra", "scores"),
  pairs = c("adjacent", "all"),
  data = NULL,
  use = "pairwise.complete.obs",
  cut_show = 0.3,
  build_tidy = TRUE
)

Arguments

levels

Named list (indexed by k) of per-level objects produced by an engine. Each must contain a scoring sub-list with fields linear, weights, and score_var.

R

Square correlation matrix (p x p). Required for the algebra path.

edge_method

One of "auto" (algebra when possible, scores otherwise), "algebra" (force, and error if conditions are not met), or "scores" (always materialise).

pairs

"adjacent" (classic Goldberg) or "all" (Forbes extension).

data

Optional data frame / matrix of raw observations. Required only when edge_method = "scores" or the scores path is triggered.

use

Passed to stats::cor() when materialising scores.

cut_show

Edges with |r| >= cut_show are flagged above_cut in the tidy tibble.

build_tidy

Build the tidy edge data frame? FALSE returns tidy = NULL for matrices-only callers (lineage pass, .cross_cor(), .boot_replicate()), which would otherwise build and discard it (M60).

Value

A list with:

matrices

Named list of (k_a x k_b) edge matrices, keyed "k_a:k_b".

tidy

A data frame with one row per directed edge: from, to, level_from, level_to, r, is_primary, and above_cut. It is NULL when build_tidy = FALSE.

Details

E(a,b) = D_a^{-1/2} (W_a' R W_b) D_b^{-1/2}

where R is the input correlation matrix and D_x = diag(W_x' R W_x) are the actual score variances (not assumed to be 1). This avoids materialising scores while remaining exact for PCA and EFA (regression, Bartlett, or tenBerge). All of those produce linear score maps.

When the algebra cannot be used (nonlinear scoring, missing R, or the user forces edge_method = "scores"), scores are materialised from data instead.