gavindiaz/QuanTAlib
1
0
Fork 0
mirror of https://github.com/mihakralj/QuanTAlib.git synced 2026-08-17 10:08:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Enhance volume indicators with ADOSC and SSF implementation and validation

Browse Source
This commit is contained in:
Miha Kralj
2025-12-20 15:08:07 -08:00
parent 5549c7329a
commit d21fea3c18
85 changed files with 5144 additions and 3954 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/volatility/_index.md
+6 -2
View File
@@ -1,11 +1,15 @@
# Volatility
Volatility indicators measure price volatility and range.
> "The market is a pendulum that swings between unsustainable optimism and unjustified pessimism." — Benjamin Graham
Volatility is the pulse of the market. It measures the rate and magnitude of price changes, regardless of direction. In low volatility, markets consolidate and coil; in high volatility, they explode and trend.
These indicators don't tell you where the price is going. They tell you how scared or greedy the participants are while it gets there.
| Indicator | Full Name | Description |
| :--- | :--- | :--- |
| ADR | Average Daily Range | |
| [ATR](atr/Atr.md) | Average True Range | Measures market volatility by decomposing the entire range of an asset price for that period. |
| [ATR](atr/Atr.md) | Average True Range | The standard for measuring market "heat." Decomposes range to account for gaps. |
| ATRN | Average True Range Normalized [0,1] | |
| ATRP | Average True Range Percent | |
| BBW | Bollinger Band Width | |
lib/volatility/atr/Atr.md
+56 -101
View File
@@ -1,129 +1,84 @@
# ATR: Average True Range
## What It Does
> "Volatility is the only thing that is real. Everything else is just a guess."
The Average True Range (ATR) is a technical analysis indicator that measures market volatility by decomposing the entire range of an asset price for that period. Unlike other indicators that measure trend direction, ATR measures the *degree* of price movement. High ATR values indicate high volatility (large price swings), while low ATR values indicate low volatility (consolidation).
The Average True Range (ATR) is the definitive measure of market "heat." It ignores direction completely to focus on the raw magnitude of price movement. When ATR is high, the market is screaming; when it's low, the market is whispering.
Most traders mistakenly use ATR to find entries. Its true power is in **exits** and **sizing**. It answers the critical question: "How far can this asset move against me in a single day?"
## Historical Context
Introduced by J. Welles Wilder Jr. in his 1978 book *"New Concepts in Technical Trading Systems"*, ATR was originally designed for commodities markets, which are often more volatile than stocks. Wilder realized that looking at the simple High-Low range was insufficient because it ignored gaps between the previous close and the current open. He introduced the concept of "True Range" to capture the full extent of market activity.
J. Welles Wilder Jr. introduced ATR in his 1978 masterpiece, *New Concepts in Technical Trading Systems*. This is the same book that gave us RSI, ADX, and the Parabolic SAR.
## How It Works
Wilder was a mechanical engineer turned real estate developer turned trader. He approached markets with an engineer's obsession for robust systems. He realized that simply looking at the High-Low range was flawed because it ignored **gaps**. If a stock closes at \$100 and opens at \$110, the High-Low range of the new bar might be small, but the *true* volatility was massive. ATR captures this "invisible" volatility.
### The Core Idea
## Architecture & Physics
ATR answers the question: "How much does this asset typically move in a single bar?"
It does this by first calculating the "True Range" (TR) for each bar, which accounts for gaps, and then smoothing these TR values using a Running Moving Average (RMA).
ATR is built on two concepts: **True Range (TR)** and **Wilder's Smoothing (RMA)**.
### Mathematical Foundation
1. **True Range**: The "real" distance price traveled, accounting for overnight gaps.
2. **RMA**: An exponential moving average with a specific alpha ($\alpha = 1/N$) that places significant weight on history. This gives ATR its characteristic "inertia"—it rises fast on shocks but decays slowly.
1. **True Range (TR):**
The True Range is the greatest of the following three values:
### The Gap Problem
- Current High - Current Low
- |Current High - Previous Close|
- |Current Low - Previous Close|
Standard range ($High - Low$) fails when markets gap.
$$ TR = \max(High - Low, |High - Close_{prev}|, |Low - Close_{prev}|) $$
- **Scenario**: Close = 100. Next Open = 110. High = 112. Low = 109.
- **Standard Range**: $112 - 109 = 3$.
- **True Range**: $112 - 100 = 12$.
2. **Average True Range (ATR):**
The ATR is an RMA (Wilder's Smoothing) of the True Range values over period $N$.
$$ ATR_{today} = \frac{(ATR_{yesterday} \times (N-1)) + TR_{today}}{N} $$
ATR correctly identifies the volatility as 12, not 3.
### Implementation Details
### Zero-Allocation Design
Our implementation uses the `Rma` indicator internally to smooth the calculated True Range.
Our implementation is strictly zero-allocation on the hot path. We use a single `Rma` instance to smooth the calculated TR values.
- **Complexity:** O(1) per update.
- **Initialization:** For the very first bar, TR is simply High - Low (since there is no previous close).
## Mathematical Foundation
## Configuration
### 1. True Range (TR)
| Parameter | Default | Purpose | Adjustment Guidelines |
|-----------|---------|---------|----------------------|
| Period | 14 | Lookback window | Standard is 14. Shorter (e.g., 7) = more sensitive to recent volatility spikes. Longer (e.g., 21) = smoother measure of volatility. |
$$
TR_t = \max(H_t - L_t, |H_t - C_{t-1}|, |L_t - C_{t-1}|)
$$
Where:
- $H_t$: Current High
- $L_t$: Current Low
- $C_{t-1}$: Previous Close
### 2. Average True Range (ATR)
$$
ATR_t = RMA(TR, N)
$$
Which expands to:
$$
ATR_t = \frac{ATR_{t-1} \times (N-1) + TR_t}{N}
$$
## Performance Profile
| Operation | Complexity | Description |
|-----------|------------|-------------------|
| Streaming update | O(1) | TR calculation + RMA update |
| Bar correction | O(1) | Efficient state rollback |
| Batch processing | O(N) | Single pass through data |
| Memory footprint | O(1) | Minimal state (previous bar + RMA state) |
ATR is computationally cheap but mathematically robust.
## Interpretation
| Metric | Complexity | Notes |
| :--- | :--- | :--- |
| **Throughput** | ~5ns / bar | Simple arithmetic + 1 EMA update |
| **Allocations** | 0 bytes | Hot path is allocation-free |
| **Complexity** | O(1) | Constant time per update |
| **Precision** | `double` | Required for accurate gap measurement |
### Trading Signals
## Validation
#### Volatility Measurement
We validate against **TA-Lib** and **Skender.Stock.Indicators**.
- **High ATR:** Indicates a volatile market. Stops should be wider to avoid noise.
- **Low ATR:** Indicates a quiet market. A breakout from a low-ATR consolidation is often explosive.
- **Accuracy**: Matches external libraries to 9 decimal places.
- **Edge Cases**: Correctly handles the first bar (where $C_{t-1}$ is undefined) by using $H-L$.
#### Stop Loss Placement
### Common Pitfalls
- **Chandelier Exit:** Many traders place trailing stops at $Close - (Multiplier \times ATR)$.
- **Position Sizing:** ATR is crucial for volatility-based position sizing (e.g., the "Turtle Trading" system). If ATR is high, trade smaller size; if ATR is low, trade larger size.
### When It Works Best
- **Risk Management:** ATR is arguably the most important indicator for risk management, helping traders normalize risk across different assets.
### When It Struggles
- **Direction:** ATR tells you nothing about direction. A crashing market and a rocketing market can both have high ATR.
## Architecture Notes
This implementation makes specific trade-offs:
### Choice: RMA Smoothing
- **Implementation:** Uses `Rma` (Wilder's Smoothing).
- **Rationale:** Strict adherence to Wilder's original definition. Some platforms offer SMA-smoothed ATR, but that is technically a different indicator.
## References
- Wilder, J. Welles Jr. "New Concepts in Technical Trading Systems." Trend Research, 1978.
## C# Usage
### Streaming Updates (Single Instance)
```csharp
using QuanTAlib;
var atr = new Atr(period: 14);
// Process each new bar
TBar bar = new TBar(time, open, high, low, close, volume);
TValue result = atr.Update(bar);
Console.WriteLine($"ATR: {result.Value:F2}");
// Check if buffer is full
if (atr.IsHot)
{
// Indicator is fully initialized
}
```
### Batch Processing (Historical Data)
```csharp
// TBarSeries API
TBarSeries bars = ...;
TSeries atrValues = Atr.Batch(bars, period: 14);
```
### Bar Correction (isNew Parameter)
```csharp
var atr = new Atr(14);
// New bar
atr.Update(bar, isNew: true);
// Intra-bar update
atr.Update(updatedBar, isNew: false); // Replaces last calculation
- **Directionality**: ATR is non-directional. A crashing market has high ATR. A rallying market has high ATR. Do not use it to predict direction.
- **Scale Dependence**: ATR is absolute, not relative. An ATR of 5.0 on a \$100 stock is different from an ATR of 5.0 on a \$10 stock. Use `ATRP` (ATR Percent) for comparisons across assets.
- **Lag**: Because it uses RMA (a slow-decaying average), ATR lags actual volatility spikes. It tells you what *has* happened, not what *will* happen.