Stress-test your alpha before the market does.
Open-source quantitative research validation for finding where alpha breaks.
Lacuna is the evidence layer between quantitative research and confidence in a backtest. Give it signals, returns, trades, events, or experiment history; it looks for leakage, instability, overfitting, unrealistic costs, and missing point-in-time evidence.
It complements your research stack instead of replacing it. Results are returned as structured, versioned evidence that can be inspected, audited, rendered, and archived.
Important
v0.14.1 is current. Lacuna is alpha, pre-1.0 software. This patch corrects signal-audit IC inference, which could pass an uninformative signal; regenerate audits produced by v0.14.0 or earlier. It preserves the v0.13/v0.14 public signatures.
Install the core distribution and verify the runtime:
python -m pip install --upgrade lacuna-quant
lacuna doctor --strictNote
The distribution is lacuna-quant; the Python import and CLI remain lacuna. The PyPI project
named lacuna is unrelated.
Given explicit signal and price frames, a complete study is deliberately small:
import lacuna as lc
study = lc.SignalStudy(
signal=signal,
prices=prices,
horizons=("1D", "5D", "20D"),
signal_observed_at="open",
entry="current_close",
price_adjustment="total_return_adjusted",
)
report = study.audit(bootstrap_resamples=2_000, seed=42)
print(report.summary())
report.to_html("lacuna-audit.html")
report.bundle("study.lacuna")Lacuna preserves weak or missing evidence as UNKNOWN; it never silently turns uncertainty into a
pass. See the
copy-pasteable guided signal audit
for runnable data, output inspection, CLI usage, and bundle verification.
Optional method families stay explicit:
python -m pip install "lacuna-quant[statistics,report,pandas]"
python -m pip install lacuna-optionsStable-ABI wheels support CPython 3.11+ on Linux x86-64/arm64, macOS arm64, and Windows x86-64.
| Research risk | Evidence Lacuna provides |
|---|---|
| Weak signals | Group-aware IC, flexible buckets, neutralization, decay, multi-lag turnover, and diagnostic portfolio projections |
| Leakage and bad timing | Availability-safe joins, explicit label boundaries, purged/CPCV splits, revisions, membership history, and future-data checks |
| Overfitting | Bootstrap and permutation inference, PBO/CSCV, PSR/DSR, Reality Check, SPA, and multiple-testing correction |
| Fragile conclusions | Parameter surfaces, perturbations, subperiods, regimes, universe transitions, and append-only trial history |
| Unrealistic trading assumptions | Commission, spread, slippage, impact, borrow, stress, break-even, liquidity, and capacity evidence |
| Unreproducible research | Immutable AnalysisResult values, standardized audits, deterministic JSON/HTML, and verifiable .lacuna bundles |
Additional support includes availability-anchored event studies, generic factor-panel ingestion, DuckDB and scikit-learn adapters, Arrow-compatible and optional pandas boundaries, and an independently versioned options-research extension.
Warning
Lacuna does not source market data, generate signals, compound portfolios, resolve overlapping holdings, simulate orders or fills, route trades, or run live strategies. It is a validation library, not a backtester or execution engine.
signals · returns · trades · events · trials
│
▼
explicit Python policy
│
Polars · NumPy/SciPy · Rust
│
▼
AnalysisResult
│
audit · report · JSON · bundle
Python owns methodology, temporal semantics, validation, provenance, findings, and public result construction. Renderers only present stored evidence; they do not recalculate statistics.
Findings keep state separate from severity:
PASS: the supplied evidence satisfies the declared rule;WARN/FAIL: weakness or a violated contract is visible;UNKNOWN: the source cannot establish the claim;NOT_APPLICABLE: the methodology does not apply.
Most work belongs in optimized Polars or NumPy. Rust ships only when full-call benchmarks beat an already optimized reference without changing public semantics.
In v0.14, grouped rank IC and built-in PBO/CSCV cleared that admission gate. Other candidates either
improved without Rust or closed with a documented negative decision. Native execution remains
single-threaded, reference implementations remain directly testable, and cp311-abi3 portability
is a release requirement.
See the native decision ledger for workloads, measurements, correctness evidence, and rejected migrations.
| Start here | Use it for |
|---|---|
| Getting started | Installation and a first complete audit |
| Concepts | Architecture, data semantics, and evidence contracts |
| Subsystems | Method contracts, formulas, edge cases, and failure behavior |
| Public API | Import paths and callable reference |
| Alphalens migration | Moving factor workflows without importing hidden semantics |
| Engineering handbook | Development, testing, native work, performance, and releases |
The technical specification defines the full product boundary. The roadmap and v1 readiness ledger separate completed work from the remaining independent-user evidence requirement.
Development setup
git clone https://github.com/eyenoticeall/Lacuna.git
cd Lacuna
uv sync --group dev --group docs --extra all
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
uv run mkdocs build --strictRead CONTRIBUTING.md before submitting changes. Security reports follow SECURITY.md.
Lacuna is released under the MIT License. Artifacts published before the MIT-only change retain their original grants.
Bring the research. Lacuna will look for the gaps in the evidence.