Imported from nutdnuy/pairs-trading-research-skill (SKILL.md). Install upstream with npx skills add nutdnuy/pairs-trading-research-skill. Copyright stays with the author.

Pairs Trading Research

Run pairs-trading work as a research pipeline with explicit formation and out-of-sample periods. Prefer interpretable statistical baselines before adding machine learning.

Setup

Require Python 3.10 or newer. Install runtime dependencies in an isolated environment:

python -m pip install -r requirements.txt

Workflow

1. Confirm the input is a wide CSV with one date column and one adjusted-close column per instrument. Reject non-positive prices, duplicate dates, sparse series, and a present-day universe used as if it were point-in-time.
2. Discover candidates with scripts/pairs_research.py discover. Use PCA and DBSCAN to reduce a large universe; test all pairs directly only for a small, economically coherent universe.
3. Retain pairs only after multiple-testing correction, residual-stationarity, half-life, zero-crossing, and rolling-stability checks. Treat economic rationale and borrow/liquidity feasibility as mandatory external checks.
4. Backtest with scripts/pairs_research.py backtest. Keep formation data separate, estimate every rolling parameter from information available at the signal timestamp, and apply the resulting position to the next return.
5. Read audit.json before interpreting performance. Report failed checks and limitations alongside returns.
6. Add a classifier only as an optional meta-labeler after the statistical baseline survives out-of-sample testing. Use time-aware purged or walk-forward validation; do not make LSTM the default.

Commands

Discover and rank candidates:

python scripts/pairs_research.py discover \
  --prices prices.csv --date-col Date --output-dir run/discovery \
  --cluster auto --alpha 0.05 --fdr 0.10

Backtest one candidate:

python scripts/pairs_research.py backtest \
  --prices prices.csv --date-col Date --y NDAQ --x ICE \
  --formation-ratio 0.60 --lookback 60 --z-window 20 \
  --entry-z 2 --exit-z 0 --stop-z 4 \
  --cost-bps 5 --borrow-bps-annual 100 \
  --output-dir run/ndaq-ice

Use --help on the command or subcommand for all parameters.

Decision Rules

• Do not call correlation cointegration.
• Do not accept raw p-values after searching many pairs; use the reported Benjamini-Hochberg q-values.
• Reject a non-negative or implausibly long half-life.
• Reject pairs that pass only one historical window or lose their economic link.
• Treat hedge-ratio-neutral and dollar-neutral sizing as different choices.
• Include transaction, borrow, and turnover costs; label results that omit slippage, market impact, dividends, corporate actions, or locate failures.
• Do not optimize entry thresholds on the final holdout.
• Do not claim tradability from a single backtest, Sharpe ratio, or classifier accuracy.

References

• Read references/methodology.md for statistical definitions, candidate gates, validation requirements, and model-extension guidance.
• Read references/data-and-outputs.md for the input schema and artifact contract.

The bundled implementation is research-only and does not place orders.