aether-quant 0.0.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- aether_quant-0.0.1.dist-info/METADATA +7 -0
- aether_quant-0.0.1.dist-info/RECORD +99 -0
- aether_quant-0.0.1.dist-info/WHEEL +5 -0
- aether_quant-0.0.1.dist-info/entry_points.txt +2 -0
- aether_quant-0.0.1.dist-info/licenses/LICENSE +133 -0
- aether_quant-0.0.1.dist-info/top_level.txt +13 -0
- analyzer/README.md +69 -0
- analyzer/__init__.py +17 -0
- analyzer/market_analyzer.py +521 -0
- aq_cli.py +3633 -0
- audit/README.md +47 -0
- audit/__init__.py +38 -0
- audit/hash_chain.py +52 -0
- audit/postgres_audit.py +61 -0
- audit/postgres_worker.py +402 -0
- audit/redis_queue.py +124 -0
- audit/status_export.py +62 -0
- data_pipeline/README.md +257 -0
- data_pipeline/__init__.py +6 -0
- data_pipeline/bar_synthesis.py +97 -0
- data_pipeline/dividend_backfill.py +243 -0
- data_pipeline/factor_file_backfill.py +276 -0
- data_pipeline/fetch.py +206 -0
- data_pipeline/fred_backfill.py +435 -0
- data_pipeline/ib_backfill.py +287 -0
- data_pipeline/v2_manifest.py +75 -0
- data_pipeline/yfinance_backfill.py +501 -0
- evaluation/README.md +152 -0
- evaluation/__init__.py +73 -0
- evaluation/ablation.py +310 -0
- evaluation/benchmark_comparison.py +195 -0
- evaluation/confidence_threshold_calibration.py +157 -0
- evaluation/factor_neutralization_check.py +94 -0
- evaluation/feature_parity.py +321 -0
- evaluation/feature_reconciliation.py +286 -0
- evaluation/impact_model.py +77 -0
- evaluation/kill_switch_replay.py +186 -0
- evaluation/limit_fill_simulator.py +152 -0
- evaluation/model_predictions.py +192 -0
- evaluation/monte_carlo.py +161 -0
- evaluation/public_benchmarks.py +117 -0
- evaluation/rank_book_simulator.py +494 -0
- evaluation/rank_ic_core.py +204 -0
- evaluation/rank_signal_calibration.py +690 -0
- evaluation/rolling_ic_gate_calibration.py +190 -0
- evaluation/rolling_ic_gate_replay.py +138 -0
- execution/README.md +281 -0
- execution/__init__.py +80 -0
- execution/config_cache.py +48 -0
- execution/cost_model.py +213 -0
- execution/lean_config_render.py +131 -0
- execution/live_credentials.py +38 -0
- execution/live_credentials_io.py +52 -0
- execution/order_gate.py +388 -0
- execution/paper_readiness.py +181 -0
- execution/paper_readiness_io.py +54 -0
- execution/paper_readiness_report.py +103 -0
- execution/paper_readiness_scheduler.py +137 -0
- execution/reconciliation.py +160 -0
- execution/runtime_config_io.py +38 -0
- execution/secret_scan.py +73 -0
- features/README.md +77 -0
- features/__init__.py +137 -0
- features/alt_data_features.py +154 -0
- features/bond_features.py +275 -0
- features/cross_asset_sensitivity.py +79 -0
- features/derivatives_macro_features.py +72 -0
- features/macro_features.py +79 -0
- features/options_greeks.py +329 -0
- features/sector_map.py +53 -0
- features/technical_indicators.py +185 -0
- generate_backtest_report.py +311 -0
- generate_evaluation_report.py +712 -0
- inference/README.md +105 -0
- inference/__init__.py +36 -0
- inference/exported_model.py +929 -0
- inference/parallel_inference.py +160 -0
- inference/strategy_selector_inference.py +75 -0
- json_safety.py +130 -0
- portfolio/README.md +447 -0
- portfolio/__init__.py +41 -0
- portfolio/book_construction.py +786 -0
- portfolio/book_neutrality.py +178 -0
- portfolio/hrp_allocation.py +159 -0
- portfolio/options_arbitrage_detector.py +232 -0
- portfolio/options_assignment_risk.py +119 -0
- portfolio/options_margin_sizing.py +333 -0
- portfolio/options_strategy.py +1999 -0
- portfolio/rank_signal.py +219 -0
- portfolio/rolling_ic_gate.py +183 -0
- risk/README.md +275 -0
- risk/__init__.py +38 -0
- risk/asset_class_router.py +584 -0
- risk/forex_risk.py +158 -0
- risk/futures_risk.py +202 -0
- risk/kill_switch.py +261 -0
- risk/manual_override.py +118 -0
- risk/position_sizing.py +303 -0
- risk/rl_sizing.py +189 -0
|
@@ -0,0 +1,494 @@
|
|
|
1
|
+
"""Cost-aware offline simulation of the cross-sectional rank book (V5.1
|
|
2
|
+
Phase 0). Reuses the EXACT selection/neutrality machinery main.py's live
|
|
3
|
+
decision path uses - portfolio.book_construction.build_rank_based_book()
|
|
4
|
+
and portfolio.book_neutrality.apply_book_neutrality() - so this module's
|
|
5
|
+
numbers are the offline mirror of live behavior, not an independently
|
|
6
|
+
re-derived approximation. Both of those are pure Python/dataclasses (no
|
|
7
|
+
torch, no pandas), so importing them here does not compromise this
|
|
8
|
+
package's torch-free contract (see evaluation/__init__.py's docstring).
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import math
|
|
14
|
+
from dataclasses import asdict, dataclass, field, replace
|
|
15
|
+
|
|
16
|
+
import numpy as np
|
|
17
|
+
import pandas as pd
|
|
18
|
+
|
|
19
|
+
from portfolio.book_construction import BookAllocation, build_rank_based_book
|
|
20
|
+
from portfolio.book_neutrality import apply_book_neutrality
|
|
21
|
+
|
|
22
|
+
DEFAULT_SECTOR_MAX_NET_WEIGHT = 0.05
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass(frozen=True)
|
|
26
|
+
class RankBookSimulationResult:
|
|
27
|
+
gross_sharpe: float
|
|
28
|
+
net_sharpe: float
|
|
29
|
+
gross_total_return: float
|
|
30
|
+
net_total_return: float
|
|
31
|
+
net_max_drawdown: float
|
|
32
|
+
annualized_turnover: float
|
|
33
|
+
cost_drag_annual_bps: float
|
|
34
|
+
num_rebalances: int
|
|
35
|
+
num_dates_used: int
|
|
36
|
+
mean_names_long: float
|
|
37
|
+
mean_names_short: float
|
|
38
|
+
per_date_net_return: list = field(default_factory=list)
|
|
39
|
+
per_date: list = field(default_factory=list)
|
|
40
|
+
|
|
41
|
+
def to_dict(self) -> dict:
|
|
42
|
+
return asdict(self)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _annualized_sharpe(returns: np.ndarray, trading_days_per_year: int) -> float:
|
|
46
|
+
"""Same convention as train.py::compute_strategy_metrics() -
|
|
47
|
+
(mean/std) * sqrt(trading_days_per_year) - kept identical so this
|
|
48
|
+
simulator's Sharpe is directly comparable to every other Sharpe number
|
|
49
|
+
already reported by this codebase."""
|
|
50
|
+
if len(returns) < 2:
|
|
51
|
+
return 0.0
|
|
52
|
+
std = float(returns.std(ddof=1))
|
|
53
|
+
if std <= 0.0:
|
|
54
|
+
return 0.0
|
|
55
|
+
return float(returns.mean() / std) * math.sqrt(trading_days_per_year)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _empty_result(trading_days_per_year: int) -> RankBookSimulationResult:
|
|
59
|
+
return RankBookSimulationResult(
|
|
60
|
+
gross_sharpe=0.0,
|
|
61
|
+
net_sharpe=0.0,
|
|
62
|
+
gross_total_return=0.0,
|
|
63
|
+
net_total_return=0.0,
|
|
64
|
+
net_max_drawdown=0.0,
|
|
65
|
+
annualized_turnover=0.0,
|
|
66
|
+
cost_drag_annual_bps=0.0,
|
|
67
|
+
num_rebalances=0,
|
|
68
|
+
num_dates_used=0,
|
|
69
|
+
mean_names_long=0.0,
|
|
70
|
+
mean_names_short=0.0,
|
|
71
|
+
per_date_net_return=[],
|
|
72
|
+
per_date=[],
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _simulate_rank_book_core(
|
|
77
|
+
frame: pd.DataFrame,
|
|
78
|
+
*,
|
|
79
|
+
prediction_column: str,
|
|
80
|
+
forward_return_column: str = "target_return_1d",
|
|
81
|
+
ticker_column: str = "ticker",
|
|
82
|
+
date_column: str = "date",
|
|
83
|
+
top_n: int,
|
|
84
|
+
bottom_n: int,
|
|
85
|
+
rebalance_every_bars: int,
|
|
86
|
+
cost_bps_per_side: float,
|
|
87
|
+
commission_bps: float,
|
|
88
|
+
gross_exposure: float,
|
|
89
|
+
dollar_neutral: bool,
|
|
90
|
+
sector_neutral: bool,
|
|
91
|
+
sector_by_ticker: dict[str, str] | None = None,
|
|
92
|
+
hysteresis_rank_margin: float = 0.0,
|
|
93
|
+
max_weight_per_name: float,
|
|
94
|
+
min_universe_size: int = 20,
|
|
95
|
+
sector_max_net_weight: float = DEFAULT_SECTOR_MAX_NET_WEIGHT,
|
|
96
|
+
trading_days_per_year: int = 252,
|
|
97
|
+
entry_lag_bars: int = 0,
|
|
98
|
+
min_commission_usd: float = 0.0,
|
|
99
|
+
assumed_portfolio_value_usd: float = 0.0,
|
|
100
|
+
impact_model_config: dict | None = None,
|
|
101
|
+
) -> tuple[RankBookSimulationResult, dict[str, int]]:
|
|
102
|
+
"""The real implementation, shared by simulate_rank_book() (public,
|
|
103
|
+
returns just the result) and capacity_curve() (needs held_days_by_ticker
|
|
104
|
+
too, to estimate which held name is the liquidity bottleneck). See
|
|
105
|
+
simulate_rank_book()'s docstring for the full parameter/behavior
|
|
106
|
+
contract - this function is not itself part of the public API.
|
|
107
|
+
|
|
108
|
+
Per date, in sorted order: dates with fewer than min_universe_size
|
|
109
|
+
eligible (non-NaN prediction AND forward-return) rows are SKIPPED
|
|
110
|
+
entirely (no selection, no return accrual) - same convention as
|
|
111
|
+
train.py::build_cross_sectional_rank_targets()'s min_universe_size
|
|
112
|
+
gate; the book silently carries over across a skipped date, as if it
|
|
113
|
+
did not exist for accounting purposes. On a rebalance date (every
|
|
114
|
+
rebalance_every_bars-th non-skipped date, first date always rebalances),
|
|
115
|
+
predictions are handed to build_rank_based_book() (with hysteresis
|
|
116
|
+
against the previous allocation) for top/bottom-N selection, each leg
|
|
117
|
+
is equal-weighted to gross_exposure/2, then apply_book_neutrality()
|
|
118
|
+
applies the sector/dollar/gross constraints. Cost
|
|
119
|
+
(cost_bps_per_side + commission_bps, in bps) is charged on the turnover
|
|
120
|
+
of that single rebalance event only - held-and-unchanged positions
|
|
121
|
+
between rebalances accrue zero cost, matching main.py's own
|
|
122
|
+
hold-until-next-rebalance contract (portfolio/book_construction.py::
|
|
123
|
+
should_rebalance_this_bar()).
|
|
124
|
+
|
|
125
|
+
entry_lag_bars (V5.2.1, development/Problems.md - default 0, today's
|
|
126
|
+
exact behavior): a Daily-resolution market order decided off bar N's
|
|
127
|
+
close fills at bar N+1's open, not bar N's close (main.py's own
|
|
128
|
+
documented behavior) - this function previously credited a newly-
|
|
129
|
+
selected position with that SAME date's forward return, an implicit
|
|
130
|
+
zero-lag fill assumption no live system can achieve. When > 0, return
|
|
131
|
+
accrual for a given date reads the book state as it stood
|
|
132
|
+
entry_lag_bars dates EARLIER (a rolling snapshot history), not the
|
|
133
|
+
state as of the current date's own rebalance - so a position selected
|
|
134
|
+
today does not start earning return until entry_lag_bars dates from
|
|
135
|
+
now, mirroring the live fill delay. Affects ONLY which return a held
|
|
136
|
+
weight earns; turnover/cost accounting stays keyed to the unlagged
|
|
137
|
+
rebalance transition (cost is incurred at order-submission time, not
|
|
138
|
+
fill time). A position held unchanged across the lag window has an
|
|
139
|
+
identical snapshot at both indices, so nothing is falsely penalized -
|
|
140
|
+
only genuinely CHANGED positions are affected.
|
|
141
|
+
|
|
142
|
+
min_commission_usd / assumed_portfolio_value_usd (default 0.0 - a
|
|
143
|
+
no-op, today's exact bps-of-turnover-only cost model): an
|
|
144
|
+
honestly-approximate per-order minimum-commission floor, layered on
|
|
145
|
+
top of the existing cost_bps_per_side/commission_bps bps-of-turnover
|
|
146
|
+
term. Real broker commissions are often floor-dominated for small
|
|
147
|
+
orders (see execution/cost_model.py's own min_commission_usd), which a
|
|
148
|
+
pure bps-of-notional model never captures. Requires an assumed NAV to
|
|
149
|
+
convert a per-order dollar floor into a return-fraction - a deliberate
|
|
150
|
+
approximation (uniform order size, fixed NAV across the whole run),
|
|
151
|
+
not a precision claim, same "honestly-approximate" convention
|
|
152
|
+
capacity_curve()'s own docstring uses. Only applied on rebalance
|
|
153
|
+
dates, charged once per name whose weight actually changed."""
|
|
154
|
+
sector_by_ticker = sector_by_ticker or {}
|
|
155
|
+
working = frame.dropna(subset=[prediction_column]).copy()
|
|
156
|
+
unique_dates = sorted(working[date_column].unique())
|
|
157
|
+
|
|
158
|
+
held_weights: dict[str, float] = {}
|
|
159
|
+
held_allocations: dict[str, BookAllocation] = {}
|
|
160
|
+
held_days_by_ticker: dict[str, int] = {}
|
|
161
|
+
|
|
162
|
+
gross_returns: list[float] = []
|
|
163
|
+
net_returns: list[float] = []
|
|
164
|
+
per_date_used: list = []
|
|
165
|
+
names_long_series: list[int] = []
|
|
166
|
+
names_short_series: list[int] = []
|
|
167
|
+
total_turnover = 0.0
|
|
168
|
+
total_cost_return = 0.0
|
|
169
|
+
num_rebalances = 0
|
|
170
|
+
rebalance_counter = 0
|
|
171
|
+
# V5.2.1 - one held_weights snapshot per processed date, appended AFTER
|
|
172
|
+
# that date's own rebalance (if any) - see entry_lag_bars's docstring.
|
|
173
|
+
weights_history: list[dict[str, float]] = []
|
|
174
|
+
|
|
175
|
+
net_cumprod = 1.0
|
|
176
|
+
gross_cumprod = 1.0
|
|
177
|
+
net_running_peak = 1.0
|
|
178
|
+
net_max_drawdown = 0.0
|
|
179
|
+
|
|
180
|
+
for date in unique_dates:
|
|
181
|
+
date_frame = working[working[date_column] == date]
|
|
182
|
+
eligible = date_frame.dropna(subset=[forward_return_column])
|
|
183
|
+
if len(eligible) < min_universe_size:
|
|
184
|
+
continue
|
|
185
|
+
|
|
186
|
+
is_rebalance = (rebalance_counter % max(1, rebalance_every_bars)) == 0
|
|
187
|
+
rebalance_counter += 1
|
|
188
|
+
cost_this_date = 0.0
|
|
189
|
+
|
|
190
|
+
if is_rebalance:
|
|
191
|
+
book_candidates = {
|
|
192
|
+
str(ticker): {"predicted_rank_20d": float(rank), "trading_eligible": True, "asset_class": None}
|
|
193
|
+
for ticker, rank in zip(eligible[ticker_column], eligible[prediction_column])
|
|
194
|
+
}
|
|
195
|
+
# min_rank_confidence_spread=0.0 is DELIBERATE, not an
|
|
196
|
+
# oversight: this simulator measures book QUALITY (what would
|
|
197
|
+
# this rank prediction have earned, net of costs) uncapped by
|
|
198
|
+
# the live entry gate's conviction filter - those are two
|
|
199
|
+
# different questions. Do not "fix" this into reading
|
|
200
|
+
# phase_v2.portfolio_book.min_rank_confidence_spread to try to
|
|
201
|
+
# mirror live engagement; that number is calibrated
|
|
202
|
+
# specifically for the RAW pre-normalization score scale
|
|
203
|
+
# (aq evaluate --calibrate-book-spread, portfolio/rank_signal.py),
|
|
204
|
+
# which this function's `prediction_column` is not guaranteed
|
|
205
|
+
# to be (callers may pass an already-normalized column). A
|
|
206
|
+
# healthy net_sharpe here is evidence the RANKING has value,
|
|
207
|
+
# never evidence the live gate will engage on any given day.
|
|
208
|
+
allocations = build_rank_based_book(
|
|
209
|
+
book_candidates,
|
|
210
|
+
top_n=top_n,
|
|
211
|
+
bottom_n=bottom_n,
|
|
212
|
+
min_rank_confidence_spread=0.0,
|
|
213
|
+
previous_allocations=held_allocations or None,
|
|
214
|
+
hysteresis_rank_margin=hysteresis_rank_margin,
|
|
215
|
+
)
|
|
216
|
+
|
|
217
|
+
if allocations:
|
|
218
|
+
long_symbols = [symbol for symbol, allocation in allocations.items() if allocation.role == "long"]
|
|
219
|
+
short_symbols = [symbol for symbol, allocation in allocations.items() if allocation.role == "short"]
|
|
220
|
+
raw_weights: dict[str, float] = {}
|
|
221
|
+
if long_symbols:
|
|
222
|
+
per_name = (gross_exposure / 2.0) / len(long_symbols)
|
|
223
|
+
raw_weights.update({symbol: per_name for symbol in long_symbols})
|
|
224
|
+
if short_symbols:
|
|
225
|
+
per_name = (gross_exposure / 2.0) / len(short_symbols)
|
|
226
|
+
raw_weights.update({symbol: -per_name for symbol in short_symbols})
|
|
227
|
+
|
|
228
|
+
new_weights, _diagnostics = apply_book_neutrality(
|
|
229
|
+
raw_weights,
|
|
230
|
+
sector_by_symbol=sector_by_ticker,
|
|
231
|
+
dollar_neutral=dollar_neutral,
|
|
232
|
+
sector_neutral=sector_neutral,
|
|
233
|
+
gross_exposure_cap=gross_exposure,
|
|
234
|
+
max_weight_per_name=max_weight_per_name,
|
|
235
|
+
sector_max_net_weight=sector_max_net_weight,
|
|
236
|
+
)
|
|
237
|
+
held_allocations = {
|
|
238
|
+
symbol: replace(allocation, target_weight=new_weights.get(symbol, 0.0))
|
|
239
|
+
for symbol, allocation in allocations.items()
|
|
240
|
+
}
|
|
241
|
+
else:
|
|
242
|
+
new_weights = {}
|
|
243
|
+
held_allocations = {}
|
|
244
|
+
|
|
245
|
+
all_symbols = set(new_weights) | set(held_weights)
|
|
246
|
+
deltas_by_symbol = {
|
|
247
|
+
symbol: new_weights.get(symbol, 0.0) - held_weights.get(symbol, 0.0) for symbol in all_symbols
|
|
248
|
+
}
|
|
249
|
+
turnover_this_rebalance = sum(abs(delta) for delta in deltas_by_symbol.values())
|
|
250
|
+
total_turnover += turnover_this_rebalance
|
|
251
|
+
cost_this_date = turnover_this_rebalance * (cost_bps_per_side + commission_bps) / 1e4
|
|
252
|
+
# V5.2.1 (development/Problems.md) - honestly-approximate
|
|
253
|
+
# per-order minimum-commission floor, see this function's own
|
|
254
|
+
# docstring. No-op (0.0) unless both inputs are configured.
|
|
255
|
+
if min_commission_usd > 0.0 and assumed_portfolio_value_usd > 0.0:
|
|
256
|
+
names_traded = sum(1 for delta in deltas_by_symbol.values() if delta != 0.0)
|
|
257
|
+
cost_this_date += names_traded * min_commission_usd / assumed_portfolio_value_usd
|
|
258
|
+
total_cost_return += cost_this_date
|
|
259
|
+
|
|
260
|
+
# V5.4.2 - Almgren-style impact model (optional, off by default).
|
|
261
|
+
# Simplified date-level estimate: uses aggregate turnover and a
|
|
262
|
+
# configured daily vol + eta to approximate sqrt-impact cost.
|
|
263
|
+
if impact_model_config and impact_model_config.get("enabled", False):
|
|
264
|
+
from evaluation.impact_model import compute_sqrt_impact_bps
|
|
265
|
+
|
|
266
|
+
eta = float(impact_model_config.get("eta", 0.5))
|
|
267
|
+
daily_vol = float(impact_model_config.get("daily_volatility", 0.02))
|
|
268
|
+
adv = float(impact_model_config.get("avg_daily_dollar_volume", 50_000_000))
|
|
269
|
+
pv = assumed_portfolio_value_usd if assumed_portfolio_value_usd > 0 else 1e6
|
|
270
|
+
impact_bps = compute_sqrt_impact_bps(
|
|
271
|
+
trade_size_fraction=turnover_this_rebalance,
|
|
272
|
+
daily_volatility=daily_vol,
|
|
273
|
+
avg_daily_dollar_volume=adv,
|
|
274
|
+
portfolio_value=pv,
|
|
275
|
+
eta=eta,
|
|
276
|
+
)
|
|
277
|
+
impact_cost = impact_bps / 1e4
|
|
278
|
+
cost_this_date += impact_cost
|
|
279
|
+
total_cost_return += impact_cost
|
|
280
|
+
|
|
281
|
+
num_rebalances += 1
|
|
282
|
+
held_weights = new_weights
|
|
283
|
+
|
|
284
|
+
for symbol in held_weights:
|
|
285
|
+
held_days_by_ticker[symbol] = held_days_by_ticker.get(symbol, 0) + 1
|
|
286
|
+
names_long_series.append(sum(1 for weight in held_weights.values() if weight > 0.0))
|
|
287
|
+
names_short_series.append(sum(1 for weight in held_weights.values() if weight < 0.0))
|
|
288
|
+
|
|
289
|
+
date_returns = dict(zip(eligible[ticker_column], eligible[forward_return_column]))
|
|
290
|
+
# V5.2.1 - entry_lag_bars=0 (default) uses held_weights directly,
|
|
291
|
+
# byte-identical to before this parameter existed. > 0 looks back
|
|
292
|
+
# into weights_history instead - see this function's own docstring.
|
|
293
|
+
if entry_lag_bars > 0:
|
|
294
|
+
lag_index = len(weights_history) - entry_lag_bars
|
|
295
|
+
effective_weights = weights_history[lag_index] if lag_index >= 0 else {}
|
|
296
|
+
else:
|
|
297
|
+
effective_weights = held_weights
|
|
298
|
+
bar_return = sum(
|
|
299
|
+
weight * float(date_returns.get(symbol, 0.0)) for symbol, weight in effective_weights.items()
|
|
300
|
+
)
|
|
301
|
+
net_return = bar_return - cost_this_date
|
|
302
|
+
|
|
303
|
+
gross_returns.append(bar_return)
|
|
304
|
+
net_returns.append(net_return)
|
|
305
|
+
per_date_used.append(str(date))
|
|
306
|
+
weights_history.append(dict(held_weights))
|
|
307
|
+
gross_cumprod *= 1.0 + bar_return
|
|
308
|
+
net_cumprod *= 1.0 + net_return
|
|
309
|
+
net_running_peak = max(net_running_peak, net_cumprod)
|
|
310
|
+
net_max_drawdown = min(net_max_drawdown, net_cumprod / net_running_peak - 1.0)
|
|
311
|
+
|
|
312
|
+
if not per_date_used:
|
|
313
|
+
return _empty_result(trading_days_per_year), held_days_by_ticker
|
|
314
|
+
|
|
315
|
+
num_dates_used = len(per_date_used)
|
|
316
|
+
years = num_dates_used / trading_days_per_year
|
|
317
|
+
gross_array = np.asarray(gross_returns, dtype=float)
|
|
318
|
+
net_array = np.asarray(net_returns, dtype=float)
|
|
319
|
+
|
|
320
|
+
result = RankBookSimulationResult(
|
|
321
|
+
gross_sharpe=_annualized_sharpe(gross_array, trading_days_per_year),
|
|
322
|
+
net_sharpe=_annualized_sharpe(net_array, trading_days_per_year),
|
|
323
|
+
gross_total_return=float(gross_cumprod - 1.0),
|
|
324
|
+
net_total_return=float(net_cumprod - 1.0),
|
|
325
|
+
net_max_drawdown=float(net_max_drawdown),
|
|
326
|
+
annualized_turnover=float(total_turnover / years) if years > 0 else 0.0,
|
|
327
|
+
cost_drag_annual_bps=float(total_cost_return / years * 10_000.0) if years > 0 else 0.0,
|
|
328
|
+
num_rebalances=num_rebalances,
|
|
329
|
+
num_dates_used=num_dates_used,
|
|
330
|
+
mean_names_long=float(np.mean(names_long_series)) if names_long_series else 0.0,
|
|
331
|
+
mean_names_short=float(np.mean(names_short_series)) if names_short_series else 0.0,
|
|
332
|
+
per_date_net_return=[float(value) for value in net_returns],
|
|
333
|
+
per_date=per_date_used,
|
|
334
|
+
)
|
|
335
|
+
return result, held_days_by_ticker
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
def simulate_rank_book(frame: pd.DataFrame, **kwargs) -> RankBookSimulationResult:
|
|
339
|
+
"""Public entry point - see _simulate_rank_book_core()'s docstring for
|
|
340
|
+
the full algorithm. Discards held_days_by_ticker (only capacity_curve()
|
|
341
|
+
needs it)."""
|
|
342
|
+
result, _held_days_by_ticker = _simulate_rank_book_core(frame, **kwargs)
|
|
343
|
+
return result
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
def capacity_curve(
|
|
347
|
+
frame: pd.DataFrame,
|
|
348
|
+
*,
|
|
349
|
+
dollar_volume_column: str = "liquidity_log_dollar_volume",
|
|
350
|
+
participation_cap: float,
|
|
351
|
+
base_kwargs: dict,
|
|
352
|
+
top_n_sweep: list[int],
|
|
353
|
+
) -> dict:
|
|
354
|
+
"""Breadth + capacity check (V5.1 Phase 0, an addition beyond the
|
|
355
|
+
original roadmap table - see the V5.1 plan's own §1 "one thing missing
|
|
356
|
+
from the list"): sweeps top_n==bottom_n across top_n_sweep, holding
|
|
357
|
+
every other simulate_rank_book() kwarg fixed via base_kwargs, so a
|
|
358
|
+
rank-IC concentrated in a handful of names (net_sharpe collapses as
|
|
359
|
+
top_n shrinks toward the extreme) is visibly distinguishable from one
|
|
360
|
+
genuinely spread across the cross-section.
|
|
361
|
+
|
|
362
|
+
capacity_usd is a deliberately simple, honestly-approximate estimate,
|
|
363
|
+
not a precision claim: among names actually held during the BASE run
|
|
364
|
+
(base_kwargs's own top_n/bottom_n), the one with the lowest average
|
|
365
|
+
dollar volume (dollar_volume_column, a log1p value - inverted with
|
|
366
|
+
expm1 here, the correct inverse) is the binding constraint; scaling its
|
|
367
|
+
average dollar volume by participation_cap and by the number of held
|
|
368
|
+
names gives a rough total-book capacity ceiling. binding_ticker names
|
|
369
|
+
exactly which held name limits it, so this is auditable rather than a
|
|
370
|
+
black-box number.
|
|
371
|
+
|
|
372
|
+
A held ticker with dollar_volume_column == 0.0 exactly (e.g. a forex
|
|
373
|
+
pair - Yahoo Finance reports no real Volume for FX, so
|
|
374
|
+
log1p(close*volume) is always 0.0 for them, see development/Problems.md)
|
|
375
|
+
is EXCLUDED from the binding-ticker search: a true zero here means "no
|
|
376
|
+
real liquidity signal for this asset," not "zero capacity," and letting
|
|
377
|
+
it win the minimum would make one data-quality artifact dictate the
|
|
378
|
+
whole book's capacity regardless of every other held name's real
|
|
379
|
+
liquidity. If every held ticker lacks real volume data, this honestly
|
|
380
|
+
degrades to capacity_usd=0.0 / binding_ticker=None, the same "can't
|
|
381
|
+
estimate" result already returned when the base run holds nothing."""
|
|
382
|
+
per_top_n: list[dict] = []
|
|
383
|
+
base_held_days: dict[str, int] | None = None
|
|
384
|
+
base_top_n = base_kwargs.get("top_n")
|
|
385
|
+
|
|
386
|
+
for n in top_n_sweep:
|
|
387
|
+
sweep_kwargs = dict(base_kwargs)
|
|
388
|
+
sweep_kwargs["top_n"] = n
|
|
389
|
+
sweep_kwargs["bottom_n"] = n
|
|
390
|
+
result, held_days = _simulate_rank_book_core(frame, **sweep_kwargs)
|
|
391
|
+
per_top_n.append({"top_n": n, "net_sharpe": result.net_sharpe})
|
|
392
|
+
if n == base_top_n:
|
|
393
|
+
base_held_days = held_days
|
|
394
|
+
|
|
395
|
+
if base_held_days is None:
|
|
396
|
+
_, base_held_days = _simulate_rank_book_core(frame, **base_kwargs)
|
|
397
|
+
|
|
398
|
+
if not base_held_days:
|
|
399
|
+
return {"capacity_usd": 0.0, "binding_ticker": None, "per_top_n": per_top_n}
|
|
400
|
+
|
|
401
|
+
ticker_column = base_kwargs.get("ticker_column", "ticker")
|
|
402
|
+
avg_log_dollar_volume = frame.groupby(ticker_column)[dollar_volume_column].mean()
|
|
403
|
+
held_avg_dollar_volume = {
|
|
404
|
+
ticker: float(np.expm1(avg_log_dollar_volume.get(ticker, 0.0))) for ticker in base_held_days
|
|
405
|
+
}
|
|
406
|
+
if not held_avg_dollar_volume:
|
|
407
|
+
return {"capacity_usd": 0.0, "binding_ticker": None, "per_top_n": per_top_n}
|
|
408
|
+
|
|
409
|
+
# Zero means "no real volume data for this ticker" (e.g. forex - see
|
|
410
|
+
# this function's own docstring), not "zero liquidity" - exclude it
|
|
411
|
+
# from the binding-ticker search so a data-quality artifact can't
|
|
412
|
+
# dictate the whole book's capacity.
|
|
413
|
+
tickers_with_real_volume = {ticker: value for ticker, value in held_avg_dollar_volume.items() if value > 0.0}
|
|
414
|
+
if not tickers_with_real_volume:
|
|
415
|
+
return {"capacity_usd": 0.0, "binding_ticker": None, "per_top_n": per_top_n}
|
|
416
|
+
|
|
417
|
+
binding_ticker = min(tickers_with_real_volume, key=tickers_with_real_volume.get)
|
|
418
|
+
capacity_usd = float(tickers_with_real_volume[binding_ticker] * participation_cap * len(held_avg_dollar_volume))
|
|
419
|
+
return {"capacity_usd": capacity_usd, "binding_ticker": binding_ticker, "per_top_n": per_top_n}
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
def stress_test_costs(frame: pd.DataFrame, *, base_kwargs: dict, cost_multipliers: tuple = (1.0, 2.0, 3.0)) -> list[dict]:
|
|
423
|
+
"""One simulate_rank_book() run per cost multiplier, scaling BOTH
|
|
424
|
+
cost_bps_per_side and commission_bps - answers "does the edge survive
|
|
425
|
+
if real-world costs turn out to be 2x/3x the calibrated estimate",
|
|
426
|
+
the robustness check item 12 of the V5.1 roadmap asks for."""
|
|
427
|
+
results = []
|
|
428
|
+
for multiplier in cost_multipliers:
|
|
429
|
+
stressed_kwargs = dict(base_kwargs)
|
|
430
|
+
stressed_kwargs["cost_bps_per_side"] = float(base_kwargs.get("cost_bps_per_side", 0.0)) * multiplier
|
|
431
|
+
stressed_kwargs["commission_bps"] = float(base_kwargs.get("commission_bps", 0.0)) * multiplier
|
|
432
|
+
result = simulate_rank_book(frame, **stressed_kwargs)
|
|
433
|
+
results.append({"cost_multiplier": multiplier, **result.to_dict()})
|
|
434
|
+
return results
|
|
435
|
+
|
|
436
|
+
|
|
437
|
+
def _bootstrap_mean_confidence_interval(
|
|
438
|
+
values: list[float], n_resamples: int = 2000, confidence: float = 0.95, seed: int = 42
|
|
439
|
+
) -> dict:
|
|
440
|
+
"""Torch-free duplicate of train.py::bootstrap_ic_confidence_interval()'s
|
|
441
|
+
resample-with-replacement bootstrap over a plain float series - same
|
|
442
|
+
algorithm and defaults, deliberately reimplemented here (not imported)
|
|
443
|
+
since train.py imports torch and this package must stay torch-free (see
|
|
444
|
+
evaluation/__init__.py's docstring)."""
|
|
445
|
+
if not values:
|
|
446
|
+
return {"lower_bound": 0.0, "upper_bound": 0.0, "mean": 0.0}
|
|
447
|
+
rng = np.random.default_rng(seed)
|
|
448
|
+
array = np.asarray(values, dtype=float)
|
|
449
|
+
resampled_means = np.empty(n_resamples)
|
|
450
|
+
for i in range(n_resamples):
|
|
451
|
+
resampled_means[i] = rng.choice(array, size=len(array), replace=True).mean()
|
|
452
|
+
alpha = (1.0 - confidence) / 2.0
|
|
453
|
+
return {
|
|
454
|
+
"lower_bound": float(np.quantile(resampled_means, alpha)),
|
|
455
|
+
"upper_bound": float(np.quantile(resampled_means, 1.0 - alpha)),
|
|
456
|
+
"mean": float(array.mean()),
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
|
|
460
|
+
def summarize_metric_stability(per_window_values: list[float], *, min_windows: int, max_sign_flip_fraction: float) -> dict:
|
|
461
|
+
"""Cross-window stability summary (used by Phase 4's walk-forward
|
|
462
|
+
evaluation and Phase 5's ablation) - mirrors
|
|
463
|
+
train.py::assess_ranking_quality()'s era-sign-instability check, one
|
|
464
|
+
level up: a window whose sign disagrees with the overall mean's sign is
|
|
465
|
+
a "flip", same concept as an opposite-sign era. num_windows below
|
|
466
|
+
min_windows or a sign-flip fraction above max_sign_flip_fraction both
|
|
467
|
+
fail "stable"."""
|
|
468
|
+
values = [float(value) for value in per_window_values]
|
|
469
|
+
num_windows = len(values)
|
|
470
|
+
if num_windows == 0:
|
|
471
|
+
return {
|
|
472
|
+
"num_windows": 0, "mean": 0.0, "sign_flip_fraction": 0.0, "stable": False,
|
|
473
|
+
"failures": ["no_windows"], "bootstrap": _bootstrap_mean_confidence_interval([]),
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
mean_value = float(np.mean(values))
|
|
477
|
+
overall_positive = mean_value >= 0.0
|
|
478
|
+
flips = sum(1 for value in values if (value >= 0.0) != overall_positive)
|
|
479
|
+
sign_flip_fraction = flips / num_windows
|
|
480
|
+
|
|
481
|
+
failures = []
|
|
482
|
+
if num_windows < min_windows:
|
|
483
|
+
failures.append("insufficient_windows")
|
|
484
|
+
if sign_flip_fraction > max_sign_flip_fraction:
|
|
485
|
+
failures.append("sign_flip_fraction_above_gate")
|
|
486
|
+
|
|
487
|
+
return {
|
|
488
|
+
"num_windows": num_windows,
|
|
489
|
+
"mean": mean_value,
|
|
490
|
+
"sign_flip_fraction": sign_flip_fraction,
|
|
491
|
+
"stable": not failures,
|
|
492
|
+
"failures": failures,
|
|
493
|
+
"bootstrap": _bootstrap_mean_confidence_interval(values),
|
|
494
|
+
}
|