Volumetric Expansion/Contraction

### Indicator Title: Volumetric Expansion/Contraction [PCC]

### Summary

The Volumetric Expansion/Contraction (PCC) indicator is a comprehensive momentum oscillator designed to identify high-conviction price moves. Unlike traditional oscillators that only look at price, the PCC integrates four critical dimensions of market activity: **Price Change**, **Relative Volume (RVOL)**, **Cumulative Volume Delta (CVD)**, and **Average True Range (ATR)**.

Its primary purpose is to help traders distinguish between meaningful, volume-backed market expansions and noisy, unsustainable price action. It gives more weight to moves that occur in a controlled, low-volatility environment, highlighting potential starts of new trends or significant shifts in market sentiment.

### Key Concepts & Purpose

The indicator's unique formula synthesizes the following concepts:

1. **Price Change:** Measures the magnitude and direction of the primary move.
2. **Relative Volume (RVOL):** Confirms that the move is backed by significant volume compared to its recent average, indicating institutional participation.
3. **Cumulative Volume Delta (CVD):** Measures the underlying buying and selling pressure, confirming that the price move is aligned with the net flow of market orders.
4. **Inverse Volatility (ATR):** This is the indicator's unique twist. It normalizes the signal by the inverse of the Average True Range. This means the indicator's value is **amplified** when volatility (ATR) is low (signifying a controlled, confident expansion) and **dampened** when volatility is high (filtering out chaotic, less predictable moves).

The goal is to provide a single, easy-to-read oscillator that signals when price, volume, and order flow are all in alignment, especially during a breakout from a period of contraction.

### Features

* **Main Oscillator Line:** A single line plotted in a separate pane that represents the calculated strength of the volumetric expansion or contraction.
* **Zero Line:** A dotted reference line to easily distinguish between bullish (above zero) and bearish (below zero) regimes.
* **Visual Threshold Zones:** The background automatically changes color to highlight periods of significant strength:
* **Bright Green:** Indicates a "Strong Up Move" when the oscillator crosses above the user-defined upper threshold.
* **Bright Fuchsia:** Indicates a "Strong Down Move" when the oscillator crosses below the user-defined lower threshold.

### Configurable Settings & Filters

The indicator is fully customizable to allow for extensive testing and adaptation to different assets and timeframes.

#### Main Calculation Inputs
* **Price Change Lookback:** Sets the period for calculating the primary price change.
* **CVD Normalization Length:** The lookback period for normalizing the Cumulative Volume Delta.
* **RVOL Avg Volume Length:** The lookback for the simple moving average of volume, used to calculate RVOL.
* **RVOL Normalization Length:** The lookback period for normalizing the RVOL score.
* **ATR Length & Normalization Length:** Sets the periods for calculating the ATR and its longer-term average for normalization.

#### Weights
* Fine-tune the impact of each core component on the final calculation, allowing you to emphasize what matters most to your strategy (e.g., give more weight to CVD or RVOL).

#### External Market Filter (Powerful Feature)
* **Enable SPY/QQQ Filter for Up Moves?:** A checkbox to activate a powerful regime filter.
* **Symbol:** A dropdown to choose whether to filter signals based on the trend of **SPY** or **QQQ**.
* **SMA Period:** Sets the lookback period for the Simple Moving Average (default is 50).
* **How it works:** When enabled, this filter will **only allow "Strong Up Move" signals to appear if the chosen symbol (SPY or QQQ) is currently trading above its specified SMA**. This is an excellent tool for aligning your signals with the broader market trend and avoiding bullish entries in a bearish market.

#### Visuals
* **Upper/Lower Threshold:** Allows you to define what level the oscillator must cross to trigger the colored background zones, letting you customize the indicator's sensitivity.

***
**Disclaimer:** This tool is designed for market analysis and confluence. It is not a standalone trading system. Always use this indicator in conjunction with your own trading strategy, risk management, and other forms of analysis.