RainbowStats Command Reference

SPECTRAL_KL

Compare two multivariate samples using a spectral lower bound for Kullback-Leibler divergence. SPECTRAL_KL measures how strongly the joint distributions differ and decomposes that difference into interpretable multivariate directions.

Syntax

SPECTRAL_KL(P,Q)
SPECTRAL_KL(P,Q,Ridge)

Argument	Description
`P`	A DataSeriesList containing the first multivariate sample. Each series represents one feature.
`Q`	A DataSeriesList containing the comparison sample. Q must contain the same features, in the same order, as P. The two samples may contain different numbers of observations and need not cover the same dates.
`Ridge`	Optional nonnegative regularization added to the second-moment matrices. The default is 1e-8. Increase the ridge when the generalized eigenvalue problem is poorly conditioned.

The command returns an extractable RainbowStats object containing the spectral KL lower bound, generalized eigenvalues, component contributions, mean projections, component loadings, scaling information, and a diagnostic slideshow.

What SPECTRAL_KL measures

SPECTRAL_KL asks whether two samples differ in their joint multivariate distribution. Instead of comparing each series independently, it searches for combinations of the variables that distinguish P from Q.

Spectral here refers to a generalized eigenvalue decomposition. It does not refer to frequency-domain spectral analysis.

RainbowStats pooled-standardizes each feature using P and Q together. The same transformation is therefore applied to both samples. Standardizing the samples separately would remove some of the distributional differences the command is intended to measure.

How the calculation works

After pooled standardization, RainbowStats calculates the feature means and uncentered second-moment matrices for P and Q:

μ_P, μ_Q, Σ_P, Σ_Q.

The matrices are uncentered second moments, not covariance matrices. A ridge term is added for numerical stability.

RainbowStats then solves the generalized eigenvalue problem:

Σ_Pv = λΣ_Qv

Each eigenvector defines a multivariate direction. Its generalized eigenvalue describes how second-moment behavior along that direction differs between P and Q.

For KL divergence the component weighting function is:

h(λ) = [λ ln(λ) - λ + 1] / (λ - 1)²

with the limiting value h(1) = 1/2 used near λ = 1 for numerical stability.

The reported statistic is the sum of the component contributions. It is a feature-based spectral lower bound for KL(P || Q), not an exact nonparametric KL divergence.

Example

macro=LIST(UNRATE,CPIAUCSL,PAYEMS,INDPRO)
pre=SERIES_BETWEEN(macro,20150101,20191231)
post=SERIES_BETWEEN(macro,20210101,20251231)

K=SPECTRAL_KL(post,pre,0.000001)
SLIDESHOW(K)

The example compares the joint behavior of unemployment, consumer prices, payroll employment, and industrial production across two economic periods.

The slideshow reports the overall spectral KL estimate, the contribution of each spectral component, and the normalized feature loadings defining those components.

Extracting results

EXTRACT(K,divergence)
EXTRACT(K,eigenvalues)
EXTRACT(K,contributions)
EXTRACT(K,projections)
EXTRACT(K,mean_difference)
EXTRACT(K,means)
EXTRACT(K,loadings)
EXTRACT(K,raw_loadings)
EXTRACT(K,scaling)
EXTRACT(K,summary)
EXTRACT(K,slideshow)

Extraction	Result
`divergence`	Total spectral KL lower bound.
`eigenvalues`	Generalized eigenvalues for the spectral directions.
`contributions`	Eigenvalue, mean projection, and KL contribution for each component.
`projections`	Projection of the difference in feature means onto each generalized eigenvector.
`mean_difference`	Difference between the transformed P and Q feature means.
`means`	Feature means used by the estimator.
`loadings`	Euclidean-normalized component loadings for interpretation.
`raw_loadings`	Generalized eigenvectors used by the KL calculation.
`scaling`	Pooled means and standard deviations used for standardization.
`summary`	HTML summary of the analysis.
`slideshow`	Complete diagnostic slideshow.

Interpreting the components

A large component contribution means that the corresponding multivariate direction accounts for an important part of the measured difference between P and Q.

Displayed loadings are Euclidean-normalized so that v'v = 1, making their relative magnitudes easier to compare. The underlying KL calculation continues to use the appropriately normalized generalized eigenvectors.

Eigenvector signs are arbitrary. Interpret the relative signs and magnitudes within a component rather than attaching meaning to the overall sign of the component.

A useful result may show that most of the divergence is concentrated in only one or two components. In that case, the loadings identify the combinations of variables primarily responsible for the distributional change.

Direction matters

KL divergence is directional. Consequently:

SPECTRAL_KL(P,Q)

will generally differ from:

SPECTRAL_KL(Q,P)

When the direction has no natural interpretation, examining both orders can be informative.

Good practice

Use the same variables in the same order in P and Q.
Choose features that have an economic or statistical interpretation.
Inspect component contributions together with their loadings.
Check whether conclusions are stable across reasonable sample periods.
Examine sensitivity to the ridge when the feature matrices are poorly conditioned.
Remember that SPECTRAL_KL measures differences represented by the selected features; it is not an exact unrestricted KL divergence.
Do not interpret eigenvector signs by themselves—the orientation of an eigenvector is arbitrary.

RainbowStats™ · Reproducible economic and statistical analysis