Every score in corrscore takes a forecast as a plain dict tagged by a "kind" key, rather than a class hierarchy, so that a caller’s own forecasting code needs no dependency on the package beyond producing this shape:

These four kinds span a genuine closed-form tractability spectrum, not an arbitrary API choice. A "point" forecast is a single deterministic matrix ( M=1). A "mixture" is any number of discrete atoms with associated probabilities – exactly determined, so every expectation in Equation (1) reduces to a finite weighted sum, at O(J2) cost, where J is the number of atoms, with no simulation. An "isotropic_gaussian_mixture" adds an isotropic Gaussian scatter around each atom in the K(K−1)/2-dimensional space of free (upper-triangle) matrix entries; for the energy score this remains exactly computable, via the mean-norm formula for a noncentral chi distribution (Johnson et al., 1994), evaluated through the confluent hypergeometric function 1F1 (scipy.special.hyp1f1) rather than simulated. The convention is as follows. A draw is a symmetric, zero-diagonal perturbation of an atom: a vector u∼𝒩(μ,σ2In) with n=K(K−1)/2, placed into both triangles. The Frobenius norm of such a matrix counts each free entry twice, so ‖A‖F=2‖u‖2. The noncentral-chi mean is therefore taken with n degrees of freedom and scale σ, and multiplied by 2. Because the scatter lives in the free-entry space, a draw need not be positive semidefinite or lie in [−1,1]. The forecast is thus a distribution over symmetric matrices that may leave the set of valid correlation matrices, and the score remains well defined because the realized outcome y is valid. An "ensemble" is a general Monte Carlo draw set with no assumed structure – the only kind with no closed form, falling back to the direct O(M2) pairwise sum in Equation (1).

matrix_energy_score(forecast, y) implements Equation (1) with ψ the Frobenius distance between two K×K matrices, dispatched across all four forecast kinds of Section 3.1. For a "point" forecast this reduces to plain Frobenius distance to the realized outcome y; for a "mixture" forecast with components (pj,Qj), j=1,…,J, SES(F,y)=∑jpj‖Qj−y‖F−12∑j,lpjpl‖Qj−Ql‖F.

implements the variogram score (Scheuerer & Hamill, 2015), SVS(F,y)=∑i<jwij(|yi−yj|p−𝖤F|Xi−Xj|p)2,(2) adapted to index i,j over the K(K−1)/2 free upper-triangle entries of the correlation matrix, rather than over the original K-vector the published formula was defined for: the diagonal (always exactly 1 for a correlation matrix) and the mirrored lower triangle both carry no information and are excluded. p defaults to 0.5, matching Scheuerer & Hamill (2015)’s own recommended default; weights defaults to uniform. The score is exact (no sampling) for "point" and "mixture" forecasts, since both are fully determined by a finite set of deterministic atoms. For "ensemble" and "isotropic_gaussian_mixture" forecasts, 𝖤F|Xi−Xj|p has no known closed form for general p and is instead estimated by Monte Carlo with n_samples draws (default 500); cost and memory scale as O(nsamples×K2(K−1)2/4), which the default keeps modest through K=16.

The Monte Carlo path is slightly biased upward. Equation (2) squares a residual that contains the estimated 𝖤F|Xi−Xj|p, and squaring a noisy estimate adds its variance, so the expected Monte Carlo score exceeds the exact one by ∑i<jwijVarF(|Xi−Xj|p)/M, where M is the number of draws (n_samples, or the ensemble size for an "ensemble" forecast). This is always nonnegative and shrinks as 1/M. For an outcome drawn from the forecast itself, the exact expected score equals ∑i<jwijVarF(|Xi−Xj|p), so the relative inflation is 1/M, or 0.2% at the default M=500. A simulation with K=4 and an isotropic Gaussian mixture matched this to within Monte Carlo error at M=50 to 2000. The bias is negligible against typical score gaps, but it tilts a backtest that compares a Monte Carlo–scored forecast against a closed-form one ("point" or "mixture") against the former. When the forecasts being compared differ by less than about 1/M in relative score, give every candidate the same kind or raise M.

A correlation matrix is constrained to a curved region (the elliptope), not an ordinary Euclidean cube, and that constraint becomes increasingly binding as any entry approaches ±1. Pinson & Tastu (2013) show the energy score is close to blind to this kind of boundary-proximate danger for Gaussian forecasts; Nguyen (2026) shows the flat variogram score of Section 3.3 inherits a related blind spot – its concave power transform saturates once two entries are already far apart, which is exactly what happens near the boundary. A second, unrelated blind spot follows directly from Equation (2)’s reindexing over free entries: because the score is built entirely from differences between entries, it is exactly invariant to a uniform shift in the overall level of correlation – a forecast that is systematically biased high or low by the same amount across every pair scores identically to one that is not, since only the relative structure across pairs, never the shared level, is compared. Nguyen (2026) derives a fix for the saturation blind spot: matrix_geodesic_variogram_score runs the identical machinery of Equation (2), but with every free entry ρ first passed through ϕ(ρ)=sign⁡(ρ)12[log⁡(1+|ρ|)2+log⁡(1−|ρ|)2], the signed affine-invariant (Fisher–Rao) geodesic distance from independence, treating each entry as its own isolated 2×2 correlation matrix. ϕ is smooth, odd, and strictly increasing on (−1,1)→ℝ, and stretches the scale specifically near ±1 where the untransformed score has already saturated – a close cousin of the century-old Fisher z-transform arctanh⁡(ρ). Both diverge logarithmically as ρ→±1, at the same order: ϕ(ρ)/arctanh⁡(ρ)→2. Because ϕ is nonlinear, matrix_geodesic_variogram_score does not leave the level-shift blind spot above fully intact either, but the repair is asymmetric: it is strongest for a shift that pushes correlations further from independence, where ϕ’s slope is steepest, and weakest for one that pulls them toward independence, where ϕ is nearly linear and the flat score’s exact invariance is closely approximated. Because Equation (2)’s propriety argument holds for any fixed measurable per-entry transform, not only ones with a metric interpretation (Nguyen, 2026), matrix_geodesic_variogram_score needs no separate propriety proof: it is matrix_variogram_score itself, unmodified, called on ϕ-transformed entries, and shares that function’s exact/Monte-Carlo split by forecast kind and its p/weights/ n_samples semantics. Nguyen (2026) validates this construction on real, walk-forward regime-switching correlation forecasts. The geometric variant’s advantage over the flat variogram score is real but conditional: it is concentrated in market episodes where the realized correlation genuinely approaches the boundary, and is not present uniformly across an unconditional average. We report this precisely rather than claim an unconditional improvement. For the full propriety proof, the open questions it leaves, and the complete empirical picture, we refer the reader to that paper. One such open question is that a companion geometric energy score does not, to date, demonstrate a comparable real-data advantage.

All three scores are proper, so none rewards a dishonest forecast, but they penalize different errors, and the choice should follow what the evaluation is meant to catch. The energy score compares whole matrices through the Frobenius distance, so it is sensitive to the overall level of correlation: a forecast biased uniformly high or low is penalized. It is the natural choice when the level itself matters, as in a risk forecast that should not be systematically too optimistic, and it is the only one of the three with an exact form for an isotropic Gaussian mixture (Section 3.1). The flat variogram score compares differences between entries, so it is built to judge the relative structure across pairs and is exactly blind to a uniform shift in level (Section 3.4). It suits a question about which pairs move together more than others, and it should not be used alone where a common bias would matter. The geometric variogram score keeps that focus on relative structure and corrects the flat score’s saturation near the boundary, so it is the better candidate when forecasts are compared during episodes where correlations approach ±1. Its advantage there is conditional (Nguyen, 2026), and it only partly repairs the level-shift blind spot. Because the scores answer different questions, a backtest that reports the energy score alongside one variogram score is more informative than either alone, and a disagreement between them is itself a finding about where a forecast is wrong. Where a forecast has to be scored by sampling, the variogram scores’ small upward bias (Section 3.3) is a further reason to compare candidates of the same forecast kind.

backtest_zero_overlap runs a walk-forward evaluation across a sequence of forecast origins and scores one or more named forecasting methods against a shared, model-independent ground truth:

For each origin in origins, the harness computes ground truth from a window starting strictly after the origin:

then scores every forecast_fns[name](origin) against that same y. The specific design choice worth calling out is what the harness cannot and does not attempt to police: how much history a caller’s own forecast_fn consults internally is opaque to it (a full-history discounted filter and a short trailing window are both permitted), exactly the same responsibility boundary scikit-learn’s TimeSeriesSplit leaves to its own caller. What the harness does enforce, unconditionally and by construction, is that ground_truth_fn is only ever called with a start point strictly after the origin. This specific guarantee exists because of a real bug. An earlier walk-forward evaluation, in the companion regime-switching correlation study this package grew out of, computed “realized” ground truth from a window ending near the forecast origin, not one starting strictly after it. That silently leaked information back into the evaluation. It made a naive persistence forecast look decisively better than a genuine forecasting model, the opposite of the study’s eventual, correctly-measured finding. backtest_zero_overlap’s API makes that specific mistake structurally impossible to reproduce: the caller never controls, and never sees, the start point passed to ground_truth_fn.

One cost of this design deserves stating. The realized outcome that ground_truth_fn returns is itself a windowed sample estimate of the correlation, not the true correlation, so it carries its own sampling error, which is larger the shorter the horizon. Scoring-rule theory treats the outcome as a draw from the true law, whereas here that estimation error is added to the forecast’s own error and enters every reported score. It also adds noise to the per-origin score differences, so a short horizon calls for more origins before two forecasts can be separated. The horizon=10 window of K=4 series in Section 5 is short in exactly this sense.

Three complementary significance tests operate on the per-origin score arrays a BacktestResult returns.

runs a percentile circular block bootstrap (Politis & Romano, 1992) on the paired differential di=ai−bi, where ai,bi are the ith entries of scores_a, scores_b, via arch’s CircularBlockBootstrap (Sheppard, 2024), swept across a list of candidate block lengths as a sensitivity check rather than relying on one automatically “optimal” length. The range of p-values and intervals across the swept lengths is the result to report. If a single headline entry is wanted, the largest- p one is a conservative choice, but it is a choice made after looking at the sweep, and a block length picked by a data-driven rule (for example arch’s optimal_block_length) is the cleaner alternative to state in advance.

implements the Diebold–Mariano test (Diebold & Mariano, 1995) on the same paired differential, including the Harvey–Leybourne–Newbold small-sample correction (Harvey et al., 1997) and a Student- t (not asymptotic normal) reference distribution with n−1 degrees of freedom, matching R’s forecast::dm.test (Hyndman & Khandakar, 2008) formula for formula rather than following the original 1995 paper’s asymptotic-normal reference directly. The h argument sets how many autocovariance lags enter the long-run variance ( h−1), and it also drives the correction factor. It should reflect the serial dependence in the per-origin score differences, not be set mechanically to the forecast horizon. When origins are spaced so that evaluation windows are adjacent and do not overlap, the differences are close to serially independent and h near 1 is appropriate, while a larger h widens the variance estimate and costs power. This vendored implementation is deliberately cross-checked against forecast::dm.test’s own output on fixed synthetic data as a development-time oracle: doing so caught a genuine normalization bug during development, where the package’s long-run-variance estimator initially normalized each sample autocovariance by n−lag (the textbook “unbiased” convention) rather than by the full sample size n at every lag, the convention R’s own acf() function – and hence forecast::dm.test – actually uses. The two conventions coincide at lag 0, so this discrepancy was invisible at horizon h=1 and only surfaced once the test suite exercised 1]]> h>1 against the oracle. The oracle is stored with the package as fixed data (tests/_reference/): six cases at h∈{1,5,10} with both variance estimators, giving R’s own random draws together with the statistic and p-value forecast::dm.test returned, which the test suite matches to 10−6. The comparison therefore runs from Python alone, with no R installation. With R 4.6.0 and forecast 9.0.2, regenerating the fixture reproduces it byte for byte (make check-oracles).

implements the Model Confidence Set (Hansen et al., 2011) via its range-statistic elimination algorithm: repeatedly test whether the current candidate set of models is statistically distinguishable from its own best member, and if so, drop the single worst-performing model and repeat, until the surviving set cannot be rejected at level alpha. The null distribution and each round’s studentizing standard errors both come from the same joint circular block bootstrap of the full loss matrix, reusing the identical arch machinery Section 4.2’s bootstrap function depends on. This is the package’s own reasonable operationalization of Hansen et al.’s procedure, not a line-by-line port of any specific existing implementation’s internal choices – R’s MCS package’s automatic block-length selection, for instance, is not reproduced, and block_len is instead a required, caller-chosen parameter, swept manually if robustness to it matters. The test suite accordingly cross-checks this implementation’s verdict (which models survive) against R’s MCS::MCSprocedure on fixed synthetic data where the correct verdict is unambiguous by construction, rather than requiring byte-exact statistic or p-value agreement. The fixed loss matrix, drawn in R, and R’s full output for it (MCS 0.2.0) are stored alongside the Diebold–Mariano fixture. On that matrix both implementations keep the same two models and drop the same two, and the final Model Confidence Set p-value is about 0.89 here against 0.90 in R, although the two eliminate the dropped models in a different order.

The following example simulates a K=4 asset panel whose true pairwise correlation drifts slowly between roughly 0.15 and 0.50 over 900 trading days, and compares two deliberately simple forecasting rules: persistence, which forecasts tomorrow’s correlation matrix as the sample correlation of the trailing 60-day window, and shrinkage, which additionally shrinks that estimate 30% of the way toward the identity matrix. Because the underlying process has real, substantial, slowly-varying correlation, shrinking toward independence is the wrong thing to do here by construction – the example is deliberately built so that one forecast is genuinely worse, to show what a decisive verdict from the full toolchain looks like end to end.

The output below was produced with corrscore 0.1.2 on Python 3.12.7 with NumPy 1.26.4, SciPy 1.13.1 and arch 7.0.0. Every random draw is seeded (the data with default_rng(0), the bootstrap with seed=1, the Model Confidence Set with seed=2) and every forecast is a "point" forecast, so the output is deterministic for fixed library versions on a fixed platform. It does depend on both. NumPy 2.x draws different returns from the same seed, and the same script then prints a mean variogram score of 3.0639 for persistence, not 3.0274. The numbers below were produced on macOS (Apple silicon, arm64). On Linux (aarch64) with the same pinned versions, 13 of the 29 printed lines differ: the mean variogram score of persistence is 3.0974, and in the near-tie of Section 5.3 the Model Confidence Set drops win35 at all three block lengths, while the verdict of this first example is unchanged. The cause is the draw: Generator.multivariate_normal factorises the correlation matrix by a singular value decomposition, the matrix here has an eigenvalue of multiplicity three, and the macOS and Linux builds of NumPy 1.26.4 return different bases for it on 16 of the 900 simulated days. Passing method="cholesky" makes both platforms print the same lines, but the numbers reported here are those of the default method. The script is examples/section5_example.py in the repository, and running make paper-example from the repository root builds the pinned environment of requirements-paper.txt and prints the numbers below, followed by those of Sections 5.2 and 5.3. Release 0.1.2 is archived at https://doi.org/10.5281/zenodo.23078623, so these results attach to a fixed snapshot.

All three significance tools agree that shrinkage scores worse than persistence on this panel, and the Model Confidence Set eliminates it at α=0.10. The bootstrap p-values are upper bounds. With n_boot=2000 the smallest nonzero two-sided value is 2/2000=0.001, and a smaller reported value means no resample crossed zero. The Model Confidence Set’s p-value of 0.0 is limited by its own resample count in the same way (its default of 1000 resamples resolves no finer than 1/1000). The Diebold–Mariano p-value comes from a Student- t reference distribution and is not limited by a resample count.

Three caveats apply to how this example should be read. First, it demonstrates the toolchain end to end and is not evidence about the geometric score. Every off-diagonal entry shares one true level and shrinkage rescales that level, which is close to the level-shift configuration of Section 3.4, and the panel does not exercise the boundary-proximate case where that section says the geometric variant helps. Second, the bootstrap and Diebold–Mariano tests assume a covariance-stationary loss differential, and a correlation that drifts between 0.15 and 0.50 makes the per-origin differences plausibly nonstationary in mean. The printed p-values therefore demonstrate the toolchain and are not a validated inference. Third, h=10 equals the horizon and origins are spaced 10 apart, so adjacent evaluation windows just abut. The Harvey–Leybourne–Newbold correction and the n−1 degrees of freedom are applied as in forecast::dm.test, but here the h−1=9 lags estimate near-zero autocovariances (the lag-1 autocorrelation of the differential is −0.09), which makes h=10 conservative: h=1 gives a statistic of 14.206 in place of 13.026, with the same verdict.

Passing matrix_geodesic_variogram_score as the score_fn argument to backtest_zero_overlap reuses every other line unchanged, since Section 3.4’s geometric score shares the flat variogram score’s exact call signature – a deliberate design consequence of implementing it as a transform composed with existing machinery rather than a parallel code path.

The example above uses only "point" forecasts. This one exercises the closed-form kinds of Section 3.1. It scores a two-atom forecast (a calm and a stress correlation matrix with probabilities 0.7 and 0.3, K=4) against a fixed outcome y, once through its exact kind and once as an "ensemble" of M=2000 draws from it. For the "isotropic_gaussian_mixture" kind each draw adds symmetric Gaussian scatter with σ=0.05 to the free entries of its atom, following the convention of Section 3.1. The ensemble score is averaged over 50 independent seeds, and the difference from the closed form is expressed in standard errors of that average.

(ensemble_from stands for the draw-and-average loop in the script examples/closed_form_vs_mc.py, which also contains the exact matrices and seeds.) Both energy scores agree with their closed forms to within one standard error, about 0.1% of the score, which checks the isotropic-Gaussian-mixture formula, including its 2 Frobenius bookkeeping, against direct simulation. The variogram score of the discrete mixture agrees within 1.4 standard errors. That row is noisy because the score itself is small, and a run with 600 seeds narrows the gap to 0.8 standard errors. The Monte Carlo bias of Section 3.3 is a 4×10−5 effect in this setting, far below the seed noise. The isotropic-Gaussian-mixture variogram score has no closed form, so the last row compares the kind’s own sampler with an ensemble of independent draws, and the two agree within 0.2 standard errors.

The verdict in Section 5’s first example was decided by construction. This one is not. It uses the same simulated panel and six candidates that differ only in the length of the trailing window of their persistence forecast ( 20, 25, 30, 35, 40 and 60 days). Windows near the best length give score differences that change sign from origin to origin, so the outcome is not known in advance. The win60 model is the persistence model of Section 5, and its mean score of 3.027 matches. Each model is compared with win30, with the bootstrap swept over block lengths 2, 5 and 10 and the Diebold–Mariano test run at h=1, since the evaluation windows are adjacent and do not overlap (Section 4.2).

Three readings follow. First, win20 has the lowest mean score ( 2.496 against 2.550 for win30), but the gap is far from distinguishable from zero (Diebold–Mariano p=0.604, bootstrap p between 0.52 and 0.58), and win25 is a tie as well. The ordering of windows 20, 25 and 30 is not supported by the data. Second, win35 is borderline: the Diebold–Mariano test gives p=0.053 while the bootstrap gives 0.013 to 0.044 depending on block length, so whether it crosses the 5% line depends on a choice the user makes. This is the situation in which Section 4.2’s advice to report the whole sweep, and not one entry, matters. Third, win40 and win60 are worse under every test. The Model Confidence Set drops win60 and then win40 at every block length. It keeps win35 at block lengths 2 and 5 (final p of 0.17 and 0.15) and drops it at block length 10 ( p=0.078). The set at α=0.10 is therefore either four or three models, always containing windows 20, 25 and 30 and never 40 or 60, and membership of win35 is not settled by this panel.

The candidates were chosen to produce a near-tie, so this panel shows how to read the output and is not a finding about window lengths. The stationarity caveat of Section 5’s first example applies here as well.