Commodity Market Structure Suite

The Commodity Market Structure Suite is a unified indicator combining three powerful analytical frameworks into one comprehensive tool for analyzing commodity markets. It integrates term structure analysis, spot-futures spread dynamics, and Commitment of Traders positioning data into a scientifically-weighted composite score.

This indicator consolidates the functionality of three separate tools into one:
1. Futures Basis Suite (term structure, contango/backwardation)
2. Spot-Futures Spread (premium/discount, arbitrage)
3. Commodity Crowded Trade Suite (COT positioning)

The composite score is calculated using weights derived from academic research on commodity futures returns.


SCIENTIFIC FOUNDATION

The indicator is built on established financial theory and recent academic research.

THEORY OF STORAGE (Working 1933, Kaldor 1939)

The Theory of Storage explains the relationship between spot and futures prices through the cost-of-carry model. The futures price equals the spot price plus storage costs, insurance, and financing costs, minus the convenience yield. The convenience yield represents the benefit of holding physical inventory, which increases when supplies are tight.

When convenience yield exceeds carrying costs, the market enters backwardation. When carrying costs dominate, the market is in contango. This relationship provides fundamental signals about physical supply and demand conditions.

TERM STRUCTURE TRADING STRATEGIES (Erb and Harvey 2006, Gorton and Rouwenhorst 2006)

Academic research has documented significant risk premiums associated with futures term structure. A 2011 study in the Journal of Banking and Finance found that combining momentum signals with term structure signals generated annualized returns of 21 percent, significantly outperforming single-signal strategies. The strategy involves buying commodities in backwardation and selling commodities in contango.

LIMITS TO ARBITRAGE

Recent academic work reveals that arbitrage does not fully eliminate pricing distortions in commodity futures markets. Institutional investors and index traders introduce persistent distortions, especially in distant expiration contracts. This creates exploitable inefficiencies that the indicator helps identify.

CONVENIENCE YIELD AND INVENTORY

Empirical studies confirm that convenience yield is inversely related to physical inventory levels across 21 different commodities. Low inventory correlates with backwardation and high convenience yield. High inventory correlates with contango and low convenience yield. Price volatility decreases as inventory increases, with this effect being more pronounced in backwardated markets.

COT POSITIONING AND PRICE PREDICTION

Research shows that commercial hedger positions provide valuable information about future price direction. Commercials tend to be net buyers before price increases and net sellers before decreases. Extreme speculator positioning often precedes reversals, as crowded trades unwind.


DATA ARCHITECTURE

The indicator fetches data from multiple sources:

TERM STRUCTURE DATA
Compares front month futures (e.g., GC1!) with second month futures (e.g., GC2!) to determine the shape of the futures curve. Positive spread (front > back) indicates backwardation. Negative spread (front < back) indicates contango.

SPOT-FUTURES DATA
Compares spot or cash market prices (e.g., XAUUSD) with front month futures to determine premium or discount. Positive spread indicates futures premium. Negative spread indicates futures discount.

COT DATA
Uses TradingView LibraryCOT to fetch Commitment of Traders data including commercial positions, speculator positions, and open interest. Supports Legacy, Disaggregated, and Financial report types.


COMPOSITE SCORE CALCULATION

The composite score combines four normalized signals using configurable weights:

Composite = (TermSignal x W1) + (SpotFutSignal x W2) + (COTSignal x W3) + (PhysicalSignal x W4)

Default weights based on research: Term=0.25, SpotFut=0.30, COT=0.30, Physical=0.15

TERM SIGNAL
The z-score of the term structure spread. Flattening contango (higher z-score) is bullish. Deepening contango (lower z-score) is bearish. Backwardation is bullish.

SPOT-FUTURES SIGNAL
The inverted z-score of the spot-futures spread. Futures discount (physical demand) is bullish. Futures premium is bearish.

COT SIGNAL
The z-score of commercial net positioning. Commercial buying (positive z-score) is bullish. Commercial selling is bearish.

PHYSICAL STRESS SIGNAL
Triggered when spread volatility or spread extremes exceed thresholds. Adds to signal in direction of other indicators when physical market stress is detected.


ANALYSIS MODES

1. MARKET STRUCTURE COMPOSITE
The default mode showing the weighted composite score. Positive values indicate bullish market structure. Negative values indicate bearish structure. Values beyond plus or minus 2 sigma indicate extreme conditions.

2. TERM STRUCTURE
Shows the z-score of the futures curve spread. Visualizes whether the market is in contango or backwardation relative to historical norms.

3. SPOT-FUTURES PREMIUM
Shows the z-score of the spot-futures spread. Visualizes whether futures trade at premium or discount to spot.

4. COT POSITIONING
Shows the z-score of commercial net positioning. Visualizes whether commercials are accumulating or distributing.

5. PHYSICAL STRESS INDEX
Shows combined stress indicators from spread volatility and extremes. Alerts when physical delivery conditions become strained.

6. DIVERGENCE SCANNER
Detects price-positioning divergences. Bullish divergence occurs when price makes new lows but positioning improves. Bearish divergence occurs when price makes new highs but positioning deteriorates.

7. RAW DEBUG
Shows underlying calculations for troubleshooting.


SIGNAL INTERPRETATION

The dashboard provides automatic signal interpretation based on the combination of readings:

PHYSICAL SQUEEZE
Occurs when backwardation coincides with futures discount. This is the strongest bullish signal, indicating severe physical supply tightness. Historically associated with significant price rallies.

ACCUMULATION
Occurs when contango is flattening and commercials are buying (positive commercial z-score). Indicates smart money accumulation.

DISTRIBUTION
Occurs when contango is deepening and speculator positioning is extremely long. Indicates potential distribution phase before decline.

REGIME CHANGE
Occurs when multiple z-scores reach extreme levels simultaneously. Indicates high probability of significant market shift.

BULLISH SETUP
Occurs when composite score exceeds plus 1 sigma without extreme conditions. Favorable market structure for long positions.

BEARISH SETUP
Occurs when composite score falls below minus 1 sigma without extreme conditions. Unfavorable market structure for long positions.


INTERPRETING FOR PRECIOUS METALS

Gold and silver are almost always in contango. This is normal and expected. The key signals for precious metals are:

FLATTENING CONTANGO
When the term structure spread becomes less negative, physical supply is tightening. This is bullish. The z-score will rise toward positive territory.

DEEPENING CONTANGO
When the term structure spread becomes more negative, supply is ample. This is neutral to bearish. The z-score will fall toward negative territory.

BACKWARDATION
Extremely rare for precious metals. When it occurs, it signals severe physical market stress and is strongly bullish. Historical examples include the Hunt Brothers silver squeeze in 1980 and the October 2025 silver squeeze.

FUTURES DISCOUNT
When futures trade below spot, physical demand exceeds paper market supply. This is bullish and indicates real buying pressure.


SETTINGS GUIDE

SYMBOL SELECTION
Auto-Detect reads the chart symbol and configures all data sources automatically. Dropdown provides preset configurations for common commodities. Manual allows custom symbol entry.

DATA SOURCES
Individual data sources can be enabled or disabled. Disabling a source removes its contribution from the composite score.

COMPOSITE WEIGHTS
Adjust the relative importance of each signal. Weights should sum to approximately 1.0 for proper scaling, though the indicator normalizes automatically.

STATISTICAL ENGINE
Z-Score Length determines the lookback period for normalization. Default of 52 represents approximately one year on daily charts. Extreme Z-Score sets the threshold for flagging extreme conditions. Physical Stress Z sets the threshold for physical market stress alerts.


ALERTS

COMPOSITE FLIP
Triggers when the composite score crosses zero, indicating a shift from bullish to bearish structure or vice versa.

PHYSICAL STRESS
Triggers when physical market stress is first detected, indicating potential delivery squeeze conditions.

REGIME CHANGE
Triggers when the market shifts between contango and backwardation.

COT EXTREME
Triggers when commercial or speculator positioning reaches historical extremes, indicating elevated reversal risk.

DIVERGENCE ALERTS
Triggers when price-positioning divergences are detected.


SUPPORTED COMMODITIES

Gold: Spot OANDA:XAUUSD, Futures COMEX:GC1!, CFTC 088691
Silver: Spot OANDA:XAGUSD, Futures COMEX:SI1!, CFTC 084691
Crude Oil: Spot TVC:USOIL, Futures NYMEX:CL1!, CFTC 067651
Natural Gas: Futures NYMEX:NG1!, CFTC 023651
Copper: Futures COMEX:HG1!, CFTC 085692
Wheat: Futures CBOT:ZW1!, CFTC 001602
Corn: Futures CBOT:ZC1!, CFTC 002602
Soybeans: Futures CBOT:ZS1!, CFTC 005602


PRACTICAL APPLICATION

For best results, use this indicator on daily or weekly timeframes. Commodity data, especially COT data, is updated weekly and works best on longer timeframes.

When analyzing a commodity:
1. Check the composite score for overall market structure
2. Review the signal interpretation for context
3. Examine individual components (term structure, spot-futures, COT) for confirmation
4. Watch for physical stress alerts indicating delivery conditions
5. Monitor divergences for potential reversal signals

Combine this indicator with price action analysis and fundamental research for complete market analysis.


LIMITATIONS

The indicator relies on multiple data sources that may have different update frequencies. COT data is updated weekly. Some spot price sources may have gaps during certain hours. Term structure and spot-futures spreads work best for commodities with liquid continuous futures contracts. Very short timeframes may produce noisy signals.


REFERENCES

Working, H. (1933). Price Relations between July and September Wheat Futures at Chicago since 1885. Wheat Studies.

Kaldor, N. (1939). Speculation and Economic Stability. Review of Economic Studies.

Erb, C. and Harvey, C. (2006). The Strategic and Tactical Value of Commodity Futures. Financial Analysts Journal.

Gorton, G. and Rouwenhorst, K. (2006). Facts and Fantasies about Commodity Futures. Financial Analysts Journal.

Miffre, J. and Rallis, G. (2007). Momentum Strategies in Commodity Futures Markets. Journal of Banking and Finance.

Various (2024). Limits to Arbitrage in Commodity Futures Markets. SSRN Working Paper.


VERSION HISTORY

Version 1 released as unified indicator combining term structure, spot-futures spread, and COT positioning analysis with scientifically-weighted composite score.


CREDITS

Developed by Robinhodl21. Released under Mozilla Public License 2.0.