Data & Code

The datasets behind the five papers, the files behind this site’s figures, and the NA-IPCA toolkit: what it does, how it is verified, and how to request it.

Request the toolkit (email) · Source and wheels available on request

NA-IPCA v1.2.0 and GCDE v1.2.0 · released 4 July 2026, frozen and self-certified 5 July 2026 · code on request to academic users while the papers are unpublished · request the code · updated October 2026

The papers use licensed U.S. equity data that most universities hold. The NA-IPCA estimation code is checked against a second implementation and is shared on request while the papers are unpublished. Below: each dataset, the files behind the site’s figures, and what the NA-IPCA toolkit does.

Data

Stock-level panels are not redistributed here. Each entry says where the data come from, which paper uses them and on which page.

Datasets

Jensen–Kelly–Pedersen characteristics

153 characteristics of U.S. stocks in 13 themes, constructed by Jensen, Kelly and Pedersen from CRSP and Compustat. The stock-level files are on WRDS (contrib.global_factor); factor returns and code are at jkpfactors.com. The estimation panel of The Ruler Matters, which compares the full library with a fixed subset of 36 (Section II.A, p. 8; Table I, p. 10), and of Interpreting Pricing Errors (Section 3.1, p. 8). Same Forecasts, Different Portfolios uses the 132 characteristics available in its processed panel, which cannot be redistributed (Section III.A, p. 16; p. 43; Internet Appendix IA.K, p. IA-54). Characteristic-Space Metrics uses a panel with these definitions, January 1962 to December 2025, only to calibrate its simulations (Section 8.1, p. 30; Table I, p. 31).

Cite: Jensen, T. I., B. Kelly and L. H. Pedersen (2023). “Is There a Replication Crisis in Finance?” Journal of Finance 78(5), 2465–2518. doi:10.1111/jofi.13249

CRSP and Compustat, following Kelly, Pruitt and Su (2019)

Monthly stock returns from the Center for Research in Security Prices and firm accounts from S&P Global Compustat, accessed through WRDS. Geometric Framework builds its panel following the replication dataset of the paper that introduced IPCA (instrumented principal component analysis, in which characteristics serve as instruments for each stock’s time-varying factor loadings, or betas: how strongly it moves with the common factors), with its timing convention and cross-sectional rank transformation (Section 6.1, pp. 26–27). The panel has 36 characteristics plus a constant (L = 37). It covers 12,813 firms and 599 months. The sample runs from July 1964 to May 2014. Table 6 (p. 32) maps each characteristic to its WRDS/Neuhierl variable code. The Ruler Matters pairs its characteristics with CRSP monthly returns and trading status, and splits stocks into source and target groups by a fixed hash of the CRSP identifier (Section II.A, p. 9; Internet Appendix IA.2, p. 58).

Cite: Center for Research in Security Prices, University of Chicago Booth School of Business; S&P Global Compustat; both via Wharton Research Data Services. Kelly, B. T., S. Pruitt and Y. Su (2019). “Characteristics Are Covariances: A Unified Model of Risk and Return.” Journal of Financial Economics 134(3), 501–524. doi:10.1016/j.jfineco.2019.05.001

Fama–French factors and portfolios

Monthly factor returns, the risk-free rate and 25 double-sorted portfolios from Kenneth R. French’s Data Library. Same Forecasts, Different Portfolios uses the five factors as observed factors (Section III.A, pp. 16–17). The Ruler Matters uses the five factors plus momentum (FFC6) as observed factors (Section II.B, p. 11).

Cite: Fama, E. F. and K. R. French (1993). “Common Risk Factors in the Returns on Stocks and Bonds.” Journal of Financial Economics 33(1), 3–56. doi:10.1016/0304-405X(93)90023-5. Fama, E. F. and K. R. French (2015). “A Five-Factor Asset Pricing Model.” Journal of Financial Economics 116(1), 1–22. doi:10.1016/j.jfineco.2014.10.010

NBER recession dates

Peak and trough months of U.S. business cycles from the NBER Business Cycle Dating Committee. Same Forecasts, Different Portfolios shades recessions in Figure 2 (p. 23) and reports its portfolios in both business-cycle regimes (Section VI.C, p. 39); on this site they are used for shading only, in that paper’s Internet Appendix comparison figure.

Cite: National Bureau of Economic Research. “US Business Cycle Expansions and Contractions.”

Site data

Each interactive results figure loads one JSON file from /data/, built by a Python pipeline in the site’s public repository from the papers’ research releases and, for Home Figure 1, the author’s research tables (aggregate results only; these sources are not public). Each is checked against a fresh build before every publish; its meta block names its sources.

File Figure Source
hero_overlap.json Home Figure 1 descriptive tables computed by the author on the 153-characteristic Jensen–Kelly–Pedersen library (20-year windows); not from a paper on this site
ruler_holdings.json The Ruler Matters: hedging with each ruler working paper, Table IA.2 (p. 63)
ruler_updating.json The Ruler Matters: current versus annual-origin ruler working paper, Figure 6 (p. 35), Table IA.31 (p. 97)
ruler_partial_hedge.json The Ruler Matters: partial hedges working paper, Table VII (p. 46)
sf_penalty_curves.json Same Forecasts, Different Portfolios: Sharpe ratio along the penalty working paper, Figure 1 (p. 4), Tables I–II (pp. 19, 24)
sf_mean_input.json Same Forecasts, Different Portfolios: which part of the fitted mean the portfolio uses working paper, Table III (p. 30)
hero_geometry.json no figure; kept for the ruler statistics quoted in a note on the Same Forecasts, Different Portfolios page research release of 2026-09-09 (Table IA.L.1, p. IA-62)
portfolio_formation.json Same Forecasts, Different Portfolios: Internet Appendix comparison same release (Table IA.G.1, p. IA-35)
csm_coverage.json Characteristic-Space Metrics Figure 2 recorded simulation evidence (Table II, Figure 2)
pe_specifications.json Interpreting Pricing Errors Figure 3 working paper, Table G.1

The JSON files behind the research tools are listed in each tool’s data contract below. They are built in the same way from the author’s archives and hold aggregate results only.

Research tools: data contracts

Each research tool in the Research Toolkit is demonstrated on one archived example. For each, the contract states what the function reads and writes, how far its code is tested, and what stays private. Maturity labels as on the tool pages: Implemented & tested Archived research example Planned extension.

Return-State Behavior Profile

Item Contract
Inputs Monthly rows: date (sorted, unique, consecutive), strategy_return and benchmark_return as decimal returns for the same months, optional cash_return; metadata on source, currency, cost convention (net or gross), last update and permission to publish. Only the benchmark defines the market states; no factor, signal or stock characteristic enters.
Configuration Return stream (seven: four archived, three built from public market and Treasury-bill returns) and state definition (deciles 10/90 with a 5% tail; quintiles 20/80 with a 10% tail; deciles 10/90 with a −10% recovery drawdown), on the full sample only. Half-sample results are not published: they would let single months of the private stream be reconstructed from the aggregates.
Outputs For each stream and definition: eight state-conditional metrics (raw value, units, standard error and 95% interval, normalised radar score with a clipping flag), state rule, n per state, thresholds, date range, benchmark, and a warning wherever n is below 15. A CSV export of the current view on the page; all 21 results in return_state.json.
Site file return_state.json, behind the interactive figures on the tool page: built from the archived strategy white paper’s monthly backtest tables (2026); aggregates only.
Example Archived systematic long–short U.S. equity strategy backtest (the white paper’s title calls it “Regime-Aware”; the portfolio rule itself has no regime switch): monthly data Apr 2007 – Nov 2025 (224 months), net of a bid-ask cost proxy charged on rebalancing months (on average 0.73 percentage points a month). The proxy excludes borrow, financing and market-impact costs; the portfolio is equal-weighted across the whole stock universe, and its capacity was not assessed. A historical backtest, not live or audited trading. The configuration was selected from several in an earlier study (selection bias not corrected), and the estimation sample of its signal loadings may overlap the backtest period, so it is not an out-of-sample result.
Code status Implemented & tested pipeline/exhibits/return_state.py in the site’s public repository, with tests for input validation, parity with the archived radar table to within 1 × 10⁻⁸, state counts, intervals, aggregates-only output and a disclosure screen under which no single month of the private stream is exactly solvable from the published linear aggregates (an author-set heuristic limit, not a privacy guarantee). Validated on this archive only; other return streams and a different factor behind the stream are a Planned extension.
Public The aggregates (per-state counts, thresholds and the eight metrics) and the code.
Private The monthly return streams and the white-paper tables they come from; the upstream signal, portfolio and backtest code. None of these is published.
How to request Hiring teams may ask at yang.liu19@imperial.ac.uk for a walkthrough of the code and its tests. Please do not send proprietary return data: this site has no secure handling for it.

Macro Forecast Evaluation & Regime Diagnostics

Item Contract
Inputs Per-origin forecast records: origin month, horizon, model, outcome and forecast, one record per model, origin and horizon, for a target defined once for every model; a baseline fixed in advance; monthly persistence estimates for the persistence monitor. For a new application, every predictor value needs the date on which it was first available (its vintage or release date).
Configuration Output version, horizon, model and window (each model’s own window or the common window of all models).
Outputs n, RMSE, MAE and direction hit rate per model; RMSE relative to the baseline; the per-origin loss differential and its running sum; Diebold–Mariano tests (equal-weight long-run variance with h − 1 lags as in the original test, Harvey–Leybourne–Newbold small-sample correction; a Newey–West (Bartlett) p-value as a sensitivity check); forecast errors split by signal state. All in forecast_eval.json.
Site file forecast_eval.json, behind the interactive figures and table on the tool page: built from the author’s UK services-inflation runs of February 2026 and ONS data (Open Government Licence). Its meta block records the SHA-256 hash of each archived source file, the parity results and the code version.
Example UK services inflation, February 2026 research snapshot: two archived runs (23 and 24 February 2026) and a re-estimation trained only on outcomes observed by the origin (the smoothed state, full-sample standardisation and latest-vintage data still carry look-ahead); ONS monthly data through Dec 2025 (MM23 release of 18 February 2026). Archived forecasts, not a forecasting service.
Code status Implemented & tested pipeline/exhibits/forecast_eval.py in the site’s public repository, with unit tests on synthetic cases (including invalid input records) and parity with the archived model-comparison tables to 10⁻⁹; its expanding-window forecasting function reproduces the latest run’s stored forecasts to 10⁻¹⁰. From a clean clone of the public repository, the synthetic tests and the page-versus-JSON checks run; the parity tests need the private archive and are skipped. Archived research example data download, the state-space smoother and the rolling regressions, not rerun. Planned extension a loader for new record files; other variables, predictors and countries.
Public The aggregates, the per-origin running sum of the loss differential, the monthly persistence estimates and the ONS CPI series (Open Government Licence v3.0), and the evaluation code.
Private The replication folder: raw downloads, processed inputs, estimation scripts and per-origin forecast files. None of these is published.
How to request The ONS series are public at the Office for National Statistics. For a walkthrough of the evaluation code and its tests, write to yang.liu19@imperial.ac.uk.

Code

The 618 rolling windows of the intercept fit behind Same Forecasts, Different Portfolios were estimated with the two Python packages released together as NA-IPCA v1.2.0, naipca and gcde; its two zero-intercept IPCA fits ran through the separate QZ-IPCA benchmark package (v1.0.1). The same packages implement the NA-IPCA family whose theory Geometric Framework and Characteristic-Space Metrics develop. Interpreting Pricing Errors estimates characteristic-based latent-factor models with an intercept (three factors at baseline; Section 3.2, p. 9), with ridge regressions as comparison benchmarks (p. 8). The Ruler Matters estimates IPCA with three latent factors and FFC6, with and without a characteristic intercept, on 36 and 153 characteristics (Section II.B, p. 11). Same Forecasts, Different Portfolios (p. 43; package available on request), The Ruler Matters (Internet Appendix IA.2, p. 58) and Characteristic-Space Metrics (p. 38) describe their own replication packages, separate from the toolkit.

The model family

Each model has up to three blocks: latent (hidden) factors inferred from the data, observed factors and the intercept (the part of expected return that no factor in this model explains). They differ in the ruler (metric) they measure with and in what they do with the intercept.

Model Ruler Intercept What it adds
IPCA (Kelly, Pruitt and Su, 2019) the plain ruler (the Euclidean or identity metric) optional intercept, no cap the baseline: characteristics instrument the factor loadings (betas), that is, how strongly each stock moves with the common factors
QZ-IPCA the characteristic ruler (the Gram metric) Q_Z, supplied (for example its exponentially weighted moving average (EWMA) version) none the same model measured with the characteristic ruler
NA-IPCA the characteristic ruler Q_Z, supplied estimated jointly under the cap \Gamma_\alpha' Q_Z \Gamma_\alpha \le \delta the intercept as a third block; the cap is the “no-arbitrage” in the name (slack, that is, non-binding, in every window of Same Forecasts, Different Portfolios)

Two packages

naipca estimates NA-IPCA by projected alternating least squares: it solves for the factors and the loading blocks in turn, projects the loadings back onto the constraint set, and stops when the fit to the characteristic-managed portfolio returns stops improving. It refuses an invalid supplied ruler at intake rather than repairing it; if a valid ruler is ill-conditioned, the solver shrinks it toward a scaled identity matrix by the smallest amount that makes it factorisable and reports that amount (QZ.lambda) in the audit record. Missing observations are handled through availability masks, never imputed.

gcde (Geometry Construction and Diagnostics Engine) builds the characteristic ruler (the Gram metric Q_Z) from the monthly Gram matrices of the characteristics and reports on it: 37 registered construction methods (counting parameter aliases) in six families (baseline, shrinkage, eigenvalue repair, adaptive conditioning, low-rank, rolling or exponentially weighted). It adds three diagnostic modules (spectrum, subspace, dynamic) and four validation labels (STABLE, WATCH, HIGH_ANISOTROPY, FAIL_NOT_SPD). Because construction and estimation are separate programs, every run records which ruler was used, built how and from which window. No construction is certified as best: a ruler is a measurement convention.

Verification and reproducibility

Verification. All thirty regression-test cases agree with a separate MATLAB reference implementation held by the author to within 2.97 × 10⁻¹⁴. All five invalid rulers (metric matrices) are rejected as designed. The solver has no random element: identical inputs give bit-identical outputs. Its defaults carry a configuration-freeze certificate and are never tuned in place. Every fit attaches an audit record: initialisation source, SHA-256 fingerprints of ruler, dataset and configuration, the stabilisation amount, convergence and runtime. The release is SHA-256 pinned, and its hash is recorded in each of the 618 estimation windows behind Same Forecasts, Different Portfolios; requesters receive the hashes with the certification package.

Rolling estimation

Rolling, expanding and online estimation are one loop: each window’s result is the next window’s warm start. A versioned state object (NAIPCAState) carries loadings, fingerprints and lineage; a warm start with the wrong dimension or factor count is rejected. The toolkit’s runtime benchmark is a small synthetic design of six overlapping windows (60 stocks, 10 characteristics, 36 months each). On it, warm starts cut solver iterations by about 55% and runtime by a factor of about 2.2 over the windows after the first. One window ran slower warm than cold. A same-window refit falls from 14 to 2 iterations.

How it is used

  1. Build the monthly Gram matrices of the rank-transformed characteristics.
  2. Construct the ruler (the Gram metric Q_Z) with gcde (its default averages the monthly Gram matrices; Same Forecasts, Different Portfolios uses the EWMA version, p. 17) and read its diagnostics.
  3. Fit with naipca: data mapping, ruler, numbers of latent and observed factors, cap; read diagnostics_summary.
  4. Roll the window with warm_start, keeping each window’s audit record.
from naipca import fit_naipca, load_frozen_config, diagnostics_summary

# D: data mapping; Q: characteristic geometry from the GCDE toolkit
config = load_frozen_config(overrides={"max_outer": 1000, "tol_outer": 1e-6})
result = fit_naipca(D, geometry={"Q": Q, "method": "raw_mean_w"},
                    K_lat=3, K_obs=5, delta=0.05, opts=config.options)
print(diagnostics_summary(result))

The quick-start sketch from the toolkit’s README. K_lat, K_obs: numbers of latent and observed factors; delta: the cap \delta in \Gamma_\alpha' Q_Z \Gamma_\alpha \le \delta, which limits how much the intercept may carry.

Availability

Available on request. The papers are unpublished, so source code and wheels are not posted publicly. Academic users may request them at yang.liu19@imperial.ac.uk, stating name, institution and intended use. They receive the frozen v1.2.0 release: the naipca and gcde wheels with SHA-256 sidecars, the certification package (release and configuration-freeze certificates, parity and warm-start test logs, release hashes), runnable examples that need no proprietary data, and the research estimation drivers with a one-window audit sample; the licensed characteristics panel is not included. Hiring teams may instead ask by email (subject “NA-IPCA walkthrough”) for a short walkthrough of the code, its test logs and an audit record. Please cite: Liu, M. (2026). NA-IPCA: Geometry-Aware Characteristic-Based Asset Pricing (QZ-IPCA and NA-IPCA toolkits), version 1.2.0.

Handbook and licence

The NA-IPCA Handbook (Draft 4.1, July 2026, 189 pages; not in the release) covers notation, ruler construction and selection, the estimation algorithm, options, diagnostics, debugging and a practitioner’s decision flow. Licence: NA-IPCA Academic Research License v1.0 (July 2026): free for academic research, teaching, replication and benchmarking with citation; commercial use, redistribution and derivative toolkits need written permission; modified copies must not pose as the certified release.

Reuse

Page text and the site's JSON data files: CC BY 4.0, except third-party series inside them, which keep their own terms (ONS series: Open Government Licence v3.0). The toolkit is © the author under the NA-IPCA Academic Research License v1.0 and is not covered by this licence.(View License)