# Volatility Indicators

Volatility indicators measure the degree of price variation over time. Higher volatility indicates greater price uncertainty and risk.

---

## ATR - Average True Range

The Average True Range measures market volatility by averaging the true range over a specified period. True Range accounts for gaps between periods.

### Formula

$$TR = \max(high - low, |high - close_{prev}|, |low - close_{prev}|)$$

$$ATR = \text{Wilder's Smoothing}(TR, period)$$

where Wilder's Smoothing uses $\alpha = \frac{1}{period}$.

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 14 | 1-100000 | Number of periods for averaging |

### Characteristics

| Property | Value |
|----------|-------|
| Input | OHLC (high, low, close) |
| Output | Single value (ATR in price units) |
| Lookback | period |
| Memory | O(period) |

### API Usage

::::{tab-set}

:::{tab-item} Python
```python
from techkit import ATR

# Object-oriented
atr = ATR(period=14)
result = atr.update_ohlcv(open, high, low, close)
if result.valid:
    print(f"ATR: {result.value:.2f}")

# Batch
from techkit import talib_compat as ta
atr_values = ta.ATR(high, low, close, timeperiod=14)
```
:::

:::{tab-item} Node.js
```javascript
const tk = require('techkit');

// Streaming
const atr = tk.atr(14);
const result = atr.updateOHLCV({open, high, low, close});

// Batch
const values = tk.ATR(high, low, close, 14);
```
:::

:::{tab-item} C++
```cpp
#include <techkit/techkit.hpp>

techkit::ATR atr(14);
techkit::OHLCV bar{open, high, low, close, volume};
auto result = atr.update(bar);
```
:::

:::{tab-item} C
```c
tk_indicator atr = tk_atr_new(14);
tk_ohlcv bar = {open, high, low, close, volume};
tk_result r = tk_update_ohlcv(atr, &bar);
tk_free(atr);
```
:::

::::

### Trading Usage

- **Stop Loss**: ATR × multiplier (e.g., 2× ATR) for dynamic stop placement
- **Position Sizing**: Higher ATR = larger position risk, adjust size accordingly
- **Volatility Breakouts**: ATR expansion often precedes significant moves
- **Average ATR Values**:
  - Stocks: 1-3% of price
  - Forex: 50-150 pips
  - Crypto: 2-5% of price

### Common Periods

| Period | Use Case |
|--------|----------|
| 7 | Short-term volatility |
| 14 | Standard (most common) |
| 21 | Medium-term volatility |
| 30 | Long-term volatility |

---

## NATR - Normalized Average True Range

The Normalized ATR expresses ATR as a percentage of the closing price, making it comparable across different price levels.

### Formula

$$NATR = 100 \times \frac{ATR}{close}$$

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 14 | 1-100000 | Number of periods for ATR calculation |

### Characteristics

| Property | Value |
|----------|-------|
| Input | OHLC (high, low, close) |
| Output | Single value (percentage, e.g., 2.5 = 2.5%) |
| Lookback | period |
| Memory | O(period) |

### API Usage

::::{tab-set}

:::{tab-item} Python
```python
from techkit import NATR

natr = NATR(period=14)
result = natr.update_ohlcv(open, high, low, close)
if result.valid:
    print(f"NATR: {result.value:.2f}%")
```
:::

:::{tab-item} Node.js
```javascript
const natr = tk.natr(14);
const result = natr.updateOHLCV({open, high, low, close});
```
:::

:::{tab-item} C++
```cpp
techkit::NATR natr(14);
auto result = natr.update(bar);
```
:::

:::{tab-item} C
```c
tk_indicator natr = tk_natr_new(14);
tk_result r = tk_update_ohlcv(natr, &bar);
```
:::

::::

### Trading Usage

- **Cross-Asset Comparison**: Compare volatility across different instruments
- **Relative Volatility**: NATR > 3% = high volatility, < 1% = low volatility
- **Mean Reversion**: High NATR often reverts to mean over time

---

## TRANGE - True Range

The True Range is the raw volatility measure for a single period, without smoothing. It's the building block for ATR.

### Formula

$$TR = \max(high - low, |high - close_{prev}|, |low - close_{prev}|)$$

### Characteristics

| Property | Value |
|----------|-------|
| Input | OHLC (high, low, close) |
| Output | Single value (TR in price units) |
| Lookback | 1 (needs previous close) |
| Memory | O(1) |

### API Usage

::::{tab-set}

:::{tab-item} Python
```python
from techkit import TRANGE

trange = TRANGE()
result = trange.update_ohlcv(open, high, low, close)
if result.valid:
    print(f"True Range: {result.value:.2f}")
```
:::

:::{tab-item} Node.js
```javascript
const trange = tk.trange();
const result = trange.updateOHLCV({open, high, low, close});
```
:::

:::{tab-item} C++
```cpp
techkit::TRANGE trange;
auto result = trange.update(bar);
```
:::

:::{tab-item} C
```c
tk_indicator trange = tk_trange_new();
tk_result r = tk_update_ohlcv(trange, &bar);
```
:::

::::

### Trading Usage

- **Raw Volatility**: Use when you need unsmoothed volatility
- **Gap Detection**: Large TR with small high-low range indicates gap
- **ATR Calculation**: TRANGE is the input for ATR calculation

### Comparison: ATR vs NATR vs TRANGE

| Indicator | Smoothing | Normalized | Use Case |
|-----------|-----------|------------|----------|
| TRANGE | No | No | Raw volatility, gap detection |
| ATR | Yes (Wilder's) | No | Standard volatility measure |
| NATR | Yes (Wilder's) | Yes | Cross-asset comparison |

---

## Related Indicators

- **BBANDS**: Uses standard deviation for volatility bands
- **STDDEV**: Standard deviation of returns
- **EWMA_VOL**: Exponentially weighted volatility
- **GARCH_VOL**: GARCH model for conditional volatility