Reproducibility code and derived data for the extended technical report on identification, partial identification, and mechanism evidence in leveraged ETFs.
- A compact Python package implementing the central accounting identities, identification constructions, timing bound, regressions, fixed-coefficient simulations, and exact NAV/market-price accounting.
- Derived datasets used for the public report tables and figures.
- A publication-facing computational companion, an independent release-audit notebook, and focused notebooks for principal-results, NAV/market-price, long-history, and financing analyses.
- Unit tests for the exact covariance bridge, pathwise observational equivalence, price/NAV identities, and frozen empirical validation gates.
- Data provenance files describing public source families and raw-input redistribution boundaries.
Licensed CRSP/WRDS data are not distributed. Raw historical objective-index files are also not redistributed where provider terms or copyright status do not clearly permit redistribution. The synchronized historical market-price series required for a structural NAV/price attribution is not bundled. The repository records the source conventions, expected schemas, and validation gates needed for an authorized reconstruction.
uv sync
uv run python run_all.py --mode public
uv run pytest -qOpen notebooks/00_full_reproduction.ipynb for the publication-facing computational companion. It displays the main equations, provenance, frozen research tables, robustness results, all 16 report figures inline, the claim registry, and the complete bundled-data catalogue without importing the project package. notebooks/99_independent_release_audit.ipynb preserves the earlier minimal machine-audit workflow. Open notebooks/01_quick_reproduction.ipynb for the shortest walkthrough and notebooks/02_nav_price_decomposition.ipynb for the exact NAV/market-price accounting extension.
Place the required local files under data/raw/ as described in data/raw/README.md, then run:
uv run python run_all.py --mode fullThe public release is intentionally usable without restricted raw inputs: the bundled derived tables can be inspected, checked, plotted, and fingerprinted directly.
For synchronized NAV level N_t and market-price level P_t, define q_t = P_t/N_t and rho_t = q_t/q_{t-1} - 1. The package verifies the exact identity
1 + R_price = (1 + R_NAV) (1 + rho)
and therefore
R_price = R_NAV + rho + R_NAV * rho.
On nonzero benchmark-return days the same decomposition holds for the return ratio and its finite-sample covariance. This separates the NAV-level return statistic from the secondary-market premium/discount channel without assigning either component a causal interpretation beyond the measured objects.
The bundled nav_price_cross_source_contrast.csv is deliberately weaker than a synchronized decomposition. It compares Bianchi-Goldberg's published market-price covariance with the public issuer-NAV replication for SSO and UPRO. It is descriptive evidence, not an estimated price/NAV mechanism share.
To run the exact synchronized empirical decomposition after obtaining a convention-matched market-price level CSV:
uv run python run_all.py \
--mode nav-price \
--ticker SSO \
--market-price-file /path/to/sso_market_price.csvThe command uses the authorized issuer-NAV and exact objective-index files already described under data/raw/. Market-price timing, split treatment, and distribution convention must be documented before the output is interpreted structurally.
- Sample: 3 January 2022 through 29 December 2023.
- Annualization constant:
K = 250. - Fund return: issuer NAV change for the public reconstruction.
- Benchmark leg: stated objective index in price/capital-return form.
- Sample covariance:
1/Tconvention. - Fixed simulation seed:
20260811. - External-validation universe: SSO, UPRO, QLD, TQQQ, DDM, UDOW, UWM, URTY.
The bundled validation dataset contains 501 aligned observations per fund. All eight annualized return-ratio covariances are negative, while every intercept-regression beta remains within 0.003 of its stated 2x or 3x target. The release tests these facts automatically.
The v0.2.0 extension also records a cross-source seed comparison. The published market-price versus public NAV covariance gap is approximately -0.023 annualized percentage point for SSO and -0.323 point for UPRO. Because the source conventions differ, these gaps are not interpreted as exact premium/discount contributions.
Citation metadata are provided in CITATION.cff.
The report-linked correction release is v1.0.2. Its exact Zenodo Version DOI must be inserted only after the new immutable Zenodo version is published. Do not reuse the v1.0.1 Version DOI for v1.0.2.
The previous immutable release remains available for provenance only:
Das, Ritwik (2026). Leveraged ETF Return-Ratio Identification: Reproducibility Package, version 1.0.1. Zenodo. https://doi.org/10.5281/zenodo.22066226
Current GitHub correction release: v1.0.2
v1.0.2 Zenodo Version DOI: pending correctly linked Zenodo publication
Previous immutable v1.0.1 DOI: https://doi.org/10.5281/zenodo.22066226
The original source code in this repository is released under the MIT License. Third-party source data remain subject to their original terms. See data/README.md before redistributing any raw input.
This development module rebuilds a longer issuer-NAV/objective-index panel directly from public sources for SSO, UPRO, QLD, TQQQ, DDM, and UDOW. It uses the issuer-reported daily NAV Change (%) field, exact objective-index close series exposed through FRED where available, and the daily effective federal funds rate (DFF). Fixed descriptive regimes are defined before estimation:
- policy rate: below 1%, 1% to below 3%, and 3% or above;
- 21-trading-day annualized benchmark realized volatility: below 15%, 15% to below 25%, and 25% or above.
Run from an internet-connected environment:
uv run python run_all.py --mode long-history --start 2016-08-01Fresh recomputations are written to data/recomputed/ for comparison against the audited release outputs. Audited files promoted for the public release are stored under data/derived/. UWM and URTY are intentionally excluded from the automatic long-history universe until a convention-matched Russell 2000 capital-return history is frozen. They can be analyzed with run_long_history_fund(..., local_benchmark_file=...) after supplying the audited LSEG series.
The long-history module deliberately separates stable return-space objects from ratio diagnostics. Annual mean_w_pp and OLS beta remain the primary descriptive objects. The raw return-ratio covariance is accompanied by minimum-denominator, near-zero-return, ratio-dispersion, and fixed exclusion-threshold diagnostics because near-zero benchmark returns can make ratio moments unstable.
The rate-sensitivity output uses complete calendar years only (at least 240 aligned observations). Partial current-year rows remain available in long_history_by_year_including_partial.csv for audit, but they do not enter the full-year rate-sensitivity summary. The reported slope is descriptive, not a causal financing estimate.
The v0.3.0 audited snapshot covers complete calendar years 2017--2025 for six funds (SSO, UPRO, QLD, TQQQ, DDM, UDOW), with 2016 and 2026 retained only in coverage/partial-year audit files. Across the six fund-level annual regressions, the slope of annual mean target-relative residual on the mean effective federal funds rate is negative, with R-squared between approximately 0.936 and 0.971. After scaling by extra leverage (L - 1), the six slopes lie between approximately -1.25 and -1.12 annualized percentage points per 1 percentage-point increase in the policy rate.
These rate relationships are descriptive mechanism evidence, not structural estimates of financing cost. Raw return-ratio covariance remains explicitly diagnosed for weak-denominator sensitivity and is not substituted for the more stable return-space residual.
The v0.4.0 module converts the long-history rate regularity into a deliberately narrow financing benchmark. Under a stylized one-for-one reference-rate carry convention, one unit of extra leverage per NAV implies an annualized residual/rate slope of -(L - 1) percentage points per 1 percentage-point change in the reference rate. Dividing by (L - 1) therefore gives a normalized benchmark slope of -1.
Across the six audited funds, the observed leverage-normalized slopes lie between approximately -1.25 and -1.12, with a six-fund mean near -1.21. The unit-rate benchmark is therefore roughly 80% to 90% of the observed slope magnitude. The complete-year cross-fund mean normalized residual has a descriptive slope near -1.213 and R-squared near 0.961 against the annual effective federal funds rate.
This is mechanism-consistent evidence, not a structural financing decomposition. Total-return swaps exchange reference-asset total return for an interest-rate leg, but realized fund financing also depends on notional mix, spreads, collateral, cash holdings, fee waivers, and other implementation terms. Current issuer expense-ratio snapshots are bundled only for scale and are not backfilled as historical fee series.
Recompute the bundled benchmark from the audited long-history tables with:
uv run python run_all.py --mode financing-benchmarkThe v0.5.0 module stress-tests the long-history rate-linked residual result without changing the underlying economic interpretation. It adds four complementary checks based on the audited 2017-2025 complete-year panel:
- pooled fund fixed effects, with and without annual benchmark realized volatility as a control;
- leave-one-year-out re-estimation, so no single calendar year can drive the headline slope;
- pooled first differences in the leverage-normalized residual and policy rate;
- within-index 3x-minus-2x residual differences, which isolate exactly one additional unit of contractual extra leverage while differencing benchmark-year shocks common to each pair.
The audited results are unusually coherent. The pooled fund-fixed-effect rate slope is approximately -1.213; adding annual realized volatility leaves the rate slope near -1.248. Leave-one-year-out rate-only slopes remain between approximately -1.270 and -1.159. First-difference slopes are approximately -0.930 without the volatility change and -0.959 with it. The incremental 3x-minus-2x slopes are approximately -1.243 for the S&P 500 pair, -1.338 for the Nasdaq-100 pair, and -1.285 for the DJIA pair, with pair-level R-squared values above 0.95.
These tests strengthen the claim that the annual residual-rate relation scales with extra leverage and is not an artifact of one calendar year or a simple volatility proxy. They still do not identify a unique realized financing charge because fund-specific spreads, fee schedules, collateral economics, cash income, and instrument mix remain incompletely observed.
Recompute the bundled robustness outputs with:
uv run python run_all.py --mode financing-robustnessThe stable notebook suite contains two deliberately different artifacts. notebooks/00_full_reproduction.ipynb is the publication-facing computational companion: it explains the notation and identification logic, exposes provenance and every bundled derived dataset, displays principal tables and robustness outputs, regenerates all 16 report figures inline, and closes with the claim registry and release gates. notebooks/99_independent_release_audit.ipynb retains the earlier compact machine-audit workflow. Both deliberately avoid importing letf_id, so the notebook layer remains independently inspectable while the modular package remains the production research codebase.
Generate all report figures directly from the package with:
uv run python run_all.py --mode report-figuresRun the final repository hygiene and provenance audit with:
uv run python run_all.py --mode final-auditThe final audit checks required Python authorship headers, derived-file fingerprints, release-tree cleanliness, absence of internal runtime paths or LLM authorship signatures in public text/code, and independence of the supplementary notebook from the project package. The purpose is reproducibility discipline, not an additional empirical result.
Version 1.0.2 is a focused reproducibility/visualization correction to v1.0.1. It removes a double percentage scaling in Figure 14: path_share and implementation_share are already stored on a 0-100 percentage-point scale and must not be multiplied by 100 again. No empirical estimate, simulation result, equation, identification conclusion, financing result, or interpretation boundary changes. The v1.0.1 tag and Zenodo record remain immutable historical artifacts.
To validate v1.0.2 on a clean checkout, run:
uv run pytest -q
uv run python run_all.py --mode public
uv run python run_all.py --mode financing-robustness
uv run python run_all.py --mode report-figures
uv run python run_all.py --mode final-auditThen execute notebooks/00_full_reproduction.ipynb top-to-bottom. The notebook must generate all 16 report figures without importing the project package.