[codex] add russell 1000 research toolchain (#5)

* add russell 1000 research toolchain

* fix lint issues in russell 1000 toolchain

Author: Pigbibi

examples/russell_1000_snapshot/prices.sample.csv

@@ -0,0 +1,9 @@
+symbol,as_of,close,volume
+AAPL,2026-03-30,220.73,60273300
+AAPL,2026-03-31,221.10,57500100
+MSFT,2026-03-30,438.20,19544000
+MSFT,2026-03-31,441.05,20133500
+JNJ,2026-03-30,163.44,7231100
+JNJ,2026-03-31,164.02,7012500
+SPY,2026-03-30,589.11,61233400
+SPY,2026-03-31,592.48,65510200

examples/russell_1000_snapshot/universe.sample.csv

@@ -0,0 +1,4 @@
+symbol,sector
+AAPL,Information Technology
+MSFT,Information Technology
+JNJ,Health Care

examples/russell_1000_universe_snapshots/r1000_2024-06-28.csv

@@ -0,0 +1,4 @@
+symbol,sector
+AAPL,Information Technology
+MSFT,Information Technology
+JNJ,Health Care

examples/russell_1000_universe_snapshots/r1000_2025-06-27.csv

@@ -0,0 +1,4 @@
+symbol,sector
+AAPL,Information Technology
+MSFT,Information Technology
+LLY,Health Care

scripts/__init__.py

@@ -0,0 +1 @@
+"""Local helper scripts for UsEquityStrategies."""

scripts/backtest_russell_1000_multi_factor_defensive.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import pandas as pd
+
+from us_equity_strategies.backtests.russell_1000_multi_factor_defensive import (
+    BACKTEST_SUMMARY_COLUMNS,
+    run_backtest,
+)
+from us_equity_strategies.snapshots.russell_1000_multi_factor_defensive import read_table
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Backtest the Russell 1000 price-only multi-factor defensive strategy.",
+    )
+    parser.add_argument("--prices", required=True, help="Input price history file")
+    parser.add_argument("--universe", required=True, help="Input universe file")
+    parser.add_argument("--start", dest="start_date", help="Backtest start date")
+    parser.add_argument("--end", dest="end_date", help="Backtest end date")
+    parser.add_argument("--output-dir", help="Optional output directory for summary/equity/weights csv")
+    parser.add_argument("--benchmark-symbol", default="SPY")
+    parser.add_argument("--safe-haven", default="BOXX")
+    parser.add_argument("--holdings-count", type=int, default=24)
+    parser.add_argument("--single-name-cap", type=float, default=0.06)
+    parser.add_argument("--sector-cap", type=float, default=0.20)
+    parser.add_argument("--hold-bonus", type=float, default=0.15)
+    parser.add_argument("--turnover-cost-bps", type=float, default=0.0)
+    return parser
+
+
+def _format_summary(summary: dict[str, float | str]) -> pd.DataFrame:
+    return pd.DataFrame([{column: summary.get(column) for column in BACKTEST_SUMMARY_COLUMNS}])
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    result = run_backtest(
+        read_table(args.prices),
+        read_table(args.universe),
+        start_date=args.start_date,
+        end_date=args.end_date,
+        benchmark_symbol=args.benchmark_symbol,
+        safe_haven=args.safe_haven,
+        holdings_count=args.holdings_count,
+        single_name_cap=args.single_name_cap,
+        sector_cap=args.sector_cap,
+        hold_bonus=args.hold_bonus,
+        turnover_cost_bps=args.turnover_cost_bps,
+    )
+
+    summary_frame = _format_summary(result["summary"])
+    print(summary_frame.to_string(index=False))
+
+    if args.output_dir:
+        output_dir = Path(args.output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        summary_frame.to_csv(output_dir / "summary.csv", index=False)
+        result["portfolio_returns"].rename("portfolio_return").to_csv(output_dir / "portfolio_returns.csv")
+        result["weights_history"].to_csv(output_dir / "weights_history.csv")
+        result["turnover_history"].to_csv(output_dir / "turnover_history.csv")
+        print(f"wrote backtest outputs -> {output_dir}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/build_russell_1000_universe_history.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import argparse
+
+from us_equity_strategies.data_prep.russell_1000_history import (
+    backfill_universe_history_start,
+    build_interval_universe_history_from_directory,
+    write_interval_universe_history,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Build interval-form Russell 1000 universe history from dated snapshot files.",
+    )
+    parser.add_argument("--input-dir", required=True, help="Directory containing dated constituent snapshots")
+    parser.add_argument("--output", required=True, help="Output universe history path")
+    parser.add_argument(
+        "--backfill-start-date",
+        help="Optional date used to backfill the earliest snapshot start_date (useful when the first PIT snapshot starts after the backtest start)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    history = build_interval_universe_history_from_directory(args.input_dir)
+    if args.backfill_start_date:
+        history = backfill_universe_history_start(history, args.backfill_start_date)
+    write_interval_universe_history(history, args.output)
+    print(f"wrote {len(history)} rows -> {args.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/fetch_russell_1000_price_history.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+
+from us_equity_strategies.data_prep.russell_1000_history import (
+    build_symbol_alias_candidates_from_directory,
+    build_symbol_alias_table,
+    collect_symbol_universe,
+)
+from us_equity_strategies.data_prep.yfinance_prices import download_price_history
+from us_equity_strategies.snapshots.russell_1000_multi_factor_defensive import read_table, write_table
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Fetch Russell 1000 price history from yfinance using universe-history symbols.",
+    )
+    parser.add_argument("--universe-history", required=True, help="Universe history file")
+    parser.add_argument("--output", required=True, help="Output price history file")
+    parser.add_argument("--start", required=True, help="Price download start date")
+    parser.add_argument("--end", help="Price download end date")
+    parser.add_argument("--benchmark-symbol", default="SPY")
+    parser.add_argument("--safe-haven", default="BOXX")
+    parser.add_argument("--chunk-size", type=int, default=100)
+    parser.add_argument(
+        "--snapshot-dir",
+        help="Optional directory of dated universe snapshots; when provided, build ticker alias candidates from snapshot identifiers",
+    )
+    parser.add_argument(
+        "--alias-output",
+        help="Optional output path for derived ticker alias candidates (.csv/.json/.jsonl/.parquet)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    universe_history = read_table(args.universe_history)
+    symbols = collect_symbol_universe(
+        universe_history,
+        benchmark_symbol=args.benchmark_symbol,
+        safe_haven=args.safe_haven,
+    )
+    symbol_aliases = (
+        build_symbol_alias_candidates_from_directory(args.snapshot_dir)
+        if str(args.snapshot_dir or "").strip()
+        else {}
+    )
+    alias_table = build_symbol_alias_table(symbol_aliases)
+    prices = download_price_history(
+        symbols,
+        start=args.start,
+        end=args.end,
+        chunk_size=args.chunk_size,
+        symbol_aliases=symbol_aliases,
+    )
+    write_table(prices, args.output)
+    if args.alias_output:
+        write_table(alias_table, args.alias_output)
+    print(f"downloaded {len(symbols)} symbols, wrote {len(prices)} rows -> {args.output}")
+    if args.alias_output:
+        print(f"wrote {len(alias_table)} ticker alias rows across {len(symbol_aliases)} symbols -> {args.alias_output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/fetch_russell_1000_universe_snapshots.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from us_equity_strategies.data_prep.russell_1000_history import (
+    download_ishares_historical_universe_snapshots,
+    download_ishares_universe_snapshots,
+)
+from us_equity_strategies.snapshots.russell_1000_multi_factor_defensive import write_table
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Fetch Russell 1000 proxy universe snapshots from iShares IWB holdings history.",
+    )
+    parser.add_argument("--output-dir", required=True, help="Directory where dated snapshot files will be written")
+    parser.add_argument(
+        "--metadata-output",
+        help="Optional metadata output path (.csv/.json/.jsonl/.parquet)",
+    )
+    parser.add_argument(
+        "--source",
+        choices=("official_monthly", "wayback"),
+        default="official_monthly",
+        help="official_monthly = iShares official dated JSON history; wayback = archived live CSV captures",
+    )
+    parser.add_argument("--start-date", help="Earliest date to request for official monthly history (defaults from --from-year)")
+    parser.add_argument("--end-date", help="Latest date to request for official monthly history")
+    parser.add_argument(
+        "--max-lookback-days",
+        type=int,
+        default=7,
+        help="When an exact requested date has no holdings, step back up to this many days to find the latest available trading date",
+    )
+    parser.add_argument("--from-year", type=int, default=2020, help="Earliest Wayback capture year to query")
+    parser.add_argument("--to-year", type=int, help="Latest Wayback capture year to query")
+    parser.add_argument(
+        "--no-live",
+        action="store_true",
+        help="Skip the current live IWB holdings file",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.source == "official_monthly":
+        start_date = args.start_date or f"{args.from_year:04d}-01-01"
+        end_date = args.end_date or (f"{args.to_year:04d}-12-31" if args.to_year else None)
+        snapshot_tables, metadata = download_ishares_historical_universe_snapshots(
+            start_date=start_date,
+            end_date=end_date,
+            max_lookback_days=args.max_lookback_days,
+        )
+    else:
+        snapshot_tables, metadata = download_ishares_universe_snapshots(
+            from_year=args.from_year,
+            to_year=args.to_year,
+            include_live=not args.no_live,
+        )
+
+    for as_of_date, snapshot in snapshot_tables:
+        output_path = output_dir / f"r1000_{as_of_date:%Y-%m-%d}.csv"
+        write_table(snapshot, output_path)
+
+    if args.metadata_output:
+        write_table(metadata, args.metadata_output)
+
+    print(f"wrote {len(snapshot_tables)} snapshot files -> {output_dir}")
+    if args.metadata_output:
+        print(f"wrote snapshot metadata -> {args.metadata_output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/generate_russell_1000_feature_snapshot.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from us_equity_strategies.snapshots.russell_1000_multi_factor_defensive import (
+    build_feature_snapshot,
+    read_table,
+    write_table,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate a Russell 1000 price-only feature snapshot.",
+    )
+    parser.add_argument("--prices", required=True, help="Input price history file (.csv/.json/.jsonl/.parquet)")
+    parser.add_argument("--universe", required=True, help="Input universe file (.csv/.json/.jsonl/.parquet)")
+    parser.add_argument("--output", required=True, help="Output feature snapshot path")
+    parser.add_argument("--as-of", dest="as_of_date", help="Snapshot date (defaults to latest price date)")
+    parser.add_argument("--benchmark-symbol", default="SPY")
+    parser.add_argument("--min-price-usd", type=float, default=10.0)
+    parser.add_argument("--min-adv20-usd", type=float, default=20_000_000.0)
+    parser.add_argument("--min-history-days", type=int, default=252)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    price_history = read_table(args.prices)
+    universe_snapshot = read_table(args.universe)
+    snapshot = build_feature_snapshot(
+        price_history,
+        universe_snapshot,
+        as_of_date=args.as_of_date,
+        benchmark_symbol=args.benchmark_symbol,
+        min_price_usd=args.min_price_usd,
+        min_adv20_usd=args.min_adv20_usd,
+        min_history_days=args.min_history_days,
+    )
+    write_table(snapshot, args.output)
+    print(f"wrote {len(snapshot)} rows -> {Path(args.output)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())