Crate yuzu_research 

Multi-run backtest research over yuzu-core.

yuzu-core runs one backtest; the research primitives (factor IC/ICIR, event study, forward/daily returns) live in yuzu-core::research. This crate is the layer above: it composes those into multi-run analyses over a synced data-layout tree — parameter sweeps, grids, walk-forward selection, and lookahead-bias detection — plus the data-loading glue that turns a prices/ tree into an EvalContext.

It sits between the data/engine crates and the front ends: pomelo-* / yuzu-core → yuzu-research → yuzu-cli (or a backend research service). Everything returns serializable report structs; no CLI, no argument parsing.

One module per analysis (plus the shared [ctx] loader); the public API is flattened by the re-exports below.

Structs

GridSpec

A grid file: a spec template plus parameter value lists. Inside spec, any JSON string equal to "$name" is a placeholder for the parameter name.

LookaheadLeg

Headline metrics of one leg of the lookahead comparison.

LookaheadProfile

Decay profile across several shifts. The SHAPE is the diagnosis: a cliff at shift 1 that then flattens = same-close execution dependence; smooth decay = genuinely fast alpha; performance that holds until shift ≈ N then drops = data stamped ~N days ahead of its real publication (fundamentals lookahead); flat = robust to execution timing.

LookaheadProfilePoint

One shift level of the lookahead decay profile.

LookaheadReport

Baseline vs signal-lagged comparison (issue #23). A strategy whose edge survives executing shift_days later is robust to same-close execution assumptions and same-day data timestamps; one that collapses is living on lookahead (or on fills it could never get).

SweepEntry

One row in the sweep leaderboard.

WalkForwardParams

Window/selection settings for run_walkforward.

WalkForwardReport

Stitched out-of-sample result across all walk-forward windows.

WalkForwardWindow

One walk-forward window: variant selection happened on the train range, evaluation on the (out-of-sample) test range.

Enums

SortKey

Which metric to rank by in a sweep (also the walk-forward selection metric).

Constants

PROFILE_SHIFTS

Default shift ladder for run_lookahead_profile.

Functions

expand_grid

Expand a GridSpec into one named variant per parameter combination (cartesian product, parameter order = alphabetical by name). Names look like "n=10,thresh=0.5". A grid with no params yields the spec itself.

max_lookback

Largest window argument anywhere in a spec tree (the n / nwindow / d fields) — the auto value for walk-forward warmup.

run_event

Event study (#45): evaluate spec to a 0/1 event panel, take daily returns from close, and average the return path over [-pre, +post] around each event. JSON out; not a strategy run.

run_factor

Factor report (#45): evaluate spec to a factor panel, form horizon-day forward returns from close, and return rank-IC / quantile diagnostics as JSON. Not a strategy run — no positions, no NAV. --neutralize-industry demeans the factor within sector first (needs an industry map in the tree).

run_lookahead

Run the strategy twice — as-is, and with the position matrix lagged by shift_days (signals executed N days late) — and report the metric deltas.

run_lookahead_profile

Run the strategy once, then re-price it under each shifts lag and report the metric decay curve. Signals are evaluated once — only the position matrix is shifted per level, so an N-level profile costs ~N NAV loops, not N strategy evaluations.

run_single

Run one strategy over the full universe, or over an explicit symbols subset (None = every symbol under prices/). Scoping changes what every cross-sectional op sees, so a requested symbol missing from the data tree is an error, not a silent drop. Note: a symbol list frozen today implies survivorship bias in a historical run — see docs/strategy-envelope.md.

run_sweep

Run many strategy variants in parallel (Rayon) and return a ranked leaderboard.

run_walkforward

Walk-forward analysis: roll a train_days/test_days window (in trading days) over the close panel’s date axis; in each window run every variant on the train slice, pick the best by sort_by, run it on the test slice, and chain the out-of-sample equity segments into one curve.