Single-Market CoT Diagnostics

A structured framework for analysing futures positioning, flow, and reversal risk for an individual market, with optional price overlays from yfinance.

Contents

Abstract

The Single-Market CoT Diagnostics framework turns weekly Commitment of Traders (CoT) data into a compact, trade-focused view for one market at a time. It combines net positioning, positioning stretch, recent flow, and a composite reversal score with regime flags (crowding, squeeze risk, exhaustion risk, hedger extremes). When available, daily prices from yfinance are aligned to CoT dates and displayed both as an overlay and as a dedicated price panel, enabling visual inspection of how positioning regimes interact with price trends.

1. Objective

The goal is to answer: “Who controls the market, how stretched are they, what is the recent flow doing, and is there evidence of a tactical reversal setup?” The tool is:

2. Inputs & Data Sources

The tool expects a per-market dataframe with fields such as:

3. Pre‑processing & Lookback

Data is sorted, coerced to datetime, and trimmed to a rolling window (default 52 weeks). This focuses the visualisation on the most relevant trading conditions.

4. Price Integration (yfinance)

If a ticker is supplied, daily prices are fetched, aligned to CoT dates, and forward‑filled. This places positioning signals directly beside price behaviour. 

start = df["Report_Date"].min() - pd.Timedelta(days=10)
end   = df["Report_Date"].max() + pd.Timedelta(days=2)
data = yf.download(ticker, start=start, end=end, auto_adjust=True)
price = data["Adj Close"]
df = df.set_index("Report_Date")
df["Price"] = price.reindex(df.index).ffill()

5. Panel 1 — Net % of Open Interest

Shows whether speculative traders or hedgers are in control. Price overlay adds context for whether crowding occurs at highs, lows, or mid‑trend.

6. Panel 2 — Positioning Stretch (Z‑Scores)

±2 z‑score bands highlight extreme positioning. Shading makes stretched markets easy to identify.

7. Panel 3 — 4‑Week Flow & Momentum

Tracks whether traders are adding to positions or backing off. Acceleration and fading markers provide early indications of flow turning points.

8. Panel 4 — Reversal Score & Regime Flags

Combines stretch, crowding, flow, and hedger signals into a reversal score, with layered binary flags beneath it to highlight tactical setup conditions.

9. Panel 5 — Price with Regime Signals

When price is available, squeeze and exhaustion risk points are marked directly on the price trend. This enables visual back‑testing of whether CoT conditions coincide with turning points.

10. Implementation Sketch

df = df_signal.copy()
df["Report_Date"] = pd.to_datetime(df["Report_Date"])
if ticker is not None:
    price = self._get_yf_price_series(ticker, start, end)
    df = df.set_index("Report_Date")
    df["Price"] = price.reindex(df.index).ffill()
    df = df.reset_index()
cutoff = df["Report_Date"].max() - pd.Timedelta(weeks=self.lookback_weeks)
df_plot = df[df["Report_Date"] >= cutoff]

11. Interpretation Rulebook (Market‑Agnostic)

This rulebook standardises how to interpret the diagnostics across markets. It is designed to be context for interpretation (not a trading system), answering: who is in control, how stretched are they, what is the recent flow doing, and is a reversal setup forming?

11.1 Prime directive

  • CoT is positioning + flow + fragility, not a price-level model.
  • Use it to describe setup quality and tail‑risk, not deterministic timing.

11.2 Inputs & normalization rules

  • Interpret positioning as % of Open Interest to normalise by market size.
  • Use z‑scores to measure stretch (extremeness), not direction.
  • Use 4‑week flow to measure near‑term pressure (acceleration vs fading).
  • Use a rolling lookback (default 52w) so “extreme” reflects the current regime context.

11.3 Role‑based interpretation

Spec_Net_%OI (spec dominance)

  • Positive = net long; negative = net short.
  • Higher absolute values imply greater spec control and potential fragility.

Hedger_Net_%OI (commercial dominance)

  • Positive = hedgers net long; negative = hedgers net short.
  • Interpret hedger extremes primarily as imbalance / mean‑reversion pressure, not momentum.

11.4 Stretch rules (z‑score)

  • |z| < 1: normal / un‑stretched
  • 1 ≤ |z| < 2: stretched
  • |z| ≥ 2: extreme (crowding‑risk regime)
  • Stretch identifies conditions, not reversal timing. Combine with flow and regime flags.

11.5 Flow rules (4‑week change)

  • Flow aligned with net direction = reinforcement (conviction building).
  • Flow opposing net direction = de‑risking / early turn risk (conviction fading).
  • For short‑horizon interpretation, weight flow > levels. For regime, weight stretch + hedger extremes.

11.6 Crowding / squeeze / exhaustion regimes

Treat these as fragility regimes (tail‑risk up), not standalone trade calls.

  • Crowded Long: spec stretch strongly positive (often z ≥ +2). Trend can persist, but drawdown sensitivity rises.
  • Crowded Short: spec stretch strongly negative (often z ≤ −2). Upside convexity rises; avoid adding fresh shorts without confirmation.
  • Squeeze Risk: crowded short + signs of short covering (flow fading) and/or stabilising price (if available). Non‑linear upside possible.
  • Exhaustion Risk: crowded long + flows fading (long build slows/reverses). Consolidation/reversal probability rises.

11.7 Divergence rule (when price overlay is available)

  • Price up, positioning momentum down → rally losing sponsorship (vulnerability rising).
  • Price down, positioning momentum up → selloff losing sponsorship (bottoming risk rising).
  • Use divergence as a confirmation filter, not a standalone trigger.

11.8 Reversal score / positioning tension

The reversal score synthesises stretch, crowding, flow, and hedger signals into a single setup intensity measure.

  • Use spikes as “setup present”, not “entry now”.
  • Highest‑quality setups occur when extreme stretch + flow turn + aligned flags + hedger confirmation coincide.

11.9 Confidence grading

Level Condition Interpretation stance
Low Directional net position, no stretch, no flow turn Describe state; avoid strong reversal claims
Medium Stretch present (|z| ≥ 1) or flow turn present Flag rising fragility; monitor for confirmation
High Extreme stretch (|z| ≥ 2) + supporting regime flag(s) Setup likely; de‑risk trend continuation assumptions
Very High (setup) Extreme stretch + flow reversal + aligned flags + hedger confirmation Strong setup context; timing still uncertain

11.10 Standard output language (LLM‑friendly)

  • Neutral / trending: “Positioning is directionally aligned but not stretched; conviction is supported/unsupported by recent flow.”
  • Crowded long: “Positioning is stretched to the long side, implying elevated fragility; continuation remains possible but drawdown risk is rising.”
  • Crowded short / squeeze setup: “Positioning is stretched to the short side, creating convex upside risk via short‑covering; timing is uncertain and volatility risk is elevated.”
  • Exhaustion setup: “Long crowding is present and flows are fading, consistent with late‑trend fragility and higher consolidation/reversal probability.”
  • High reversal‑score regime: “Composite reversal/tension is elevated, indicating a stretched and flow‑sensitive setup rather than a deterministic turning point.”

12. Interpretation & Trading Use

13. Limitations & Extensions

14. Full Panel Logic Summary

15. Recommended Enhancements