Correlation Matrix

Pairwise Pearson correlation of named series. It is used as input to portfolio optimization, criticality, and cointegration. Unlike the per-ticker transform primitives, correlation_matrix_v1 does not fan out — it aggregates two or more wired symbols into a single N×N matrix.

What (One-liner)

A Layer-1 aggregation transform: consume two or more named series, emit one N×N Pearson correlation matrix. Diagonal is 1.0; matrix is symmetric.

Inputs

• named_series (object, required) — dict of named series, { name: [values] }.

Outputs

• correlation_matrix — N×N Pearson correlation over the named series (nested dict {name_i: {name_j: ρ}}).

How to use

1. Provide named_series (a dict of { name: [values] }), or wire two or more Price Factors.
2. Read the correlation matrix.

from services.analysis.primitives import correlation_matrix
correlation_matrix({
    "SPY": [1, 2, 3, 4, 5],
    "TLT": [5, 4, 3, 2, 1],
})
# → {"SPY": {"SPY": 1.0, "TLT": -1.0}, "TLT": {"SPY": -1.0, "TLT": 1.0}}

Core formulas

ρ_{ij} = Cov(X_i, X_j) / (σ_i × σ_j)   # numpy.corrcoef

Assumptions & applicability

Assumptions: synchronous + same length + n≥2.

Applicable: portfolio covariance, regime, herd-risk criticality; any asset class, any frequency, min 2 observations.

Not applicable: non-linear, pairwise missing, high-dim low sample (use Ledoit-Wolf).

Known limitations

1. Pearson linear assumption (misses non-monotonic relationships).
2. Sensitive to outliers and lookback window.
3. No pairwise complete observations.
4. Underestimation for fat tails.

References

Pearson (1895) original + Ledoit-Wolf (2004) shrinkage improvement.

Golden Test

tests/golden/fixtures/tier1/correlation_matrix/, 1e-12 tolerance, passing as of 2026-05-25. Reference: numpy.corrcoef.

Changelog

• 1.1.0 (2026-05-25) — Promoted to Active as Layer-1 transform; merged rich governance fields from the superseded Layer-0 correlation_matrix card.
• 1.0.0 (2026-05-23) — Initial edge-first Layer-1 Draft card.