# 波动率指标

波动率指标衡量价格随时间变化的程度。较高的波动率表示更大的价格不确定性和风险。

---

## ATR - 平均真实波幅

平均真实波幅通过计算指定周期内真实波幅的平均值来衡量市场波动率。真实波幅考虑了周期之间的跳空。

### 公式

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

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

其中 Wilder 平滑使用 $\alpha = \frac{1}{period}$。

### 参数

| 参数 | 类型 | 默认值 | 范围 | 描述 |
|------|------|--------|------|------|
| period | int | 14 | 1-100000 | 平均周期数 |

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | OHLC (high, low, close) |
| 输出 | 单个值（ATR，价格单位） |
| 回看期 | period |
| 内存 | O(period) |

### API 用法

::::{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);
```
:::

::::

### 交易用法

- **止损**: ATR × 倍数（例如，2× ATR）用于动态止损设置
- **仓位大小**: 较高的 ATR = 更大的仓位风险，相应调整仓位大小
- **波动率突破**: ATR 扩张通常预示着重大走势
- **平均 ATR 值**:
  - 股票: 价格的 1-3%
  - 外汇: 50-150 点
  - 加密货币: 价格的 2-5%

### 常用周期

| 周期 | 用途 |
|------|------|
| 7 | 短期波动率 |
| 14 | 标准（最常用） |
| 21 | 中期波动率 |
| 30 | 长期波动率 |

---

## NATR - 归一化平均真实波幅

归一化 ATR 将 ATR 表示为收盘价的百分比，使其在不同价格水平之间具有可比性。

### 公式

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

### 参数

| 参数 | 类型 | 默认值 | 范围 | 描述 |
|------|------|--------|------|------|
| period | int | 14 | 1-100000 | ATR 计算的周期数 |

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | OHLC (high, low, close) |
| 输出 | 单个值（百分比，例如 2.5 = 2.5%） |
| 回看期 | period |
| 内存 | O(period) |

### API 用法

::::{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);
```
:::

::::

### 交易用法

- **跨资产比较**: 比较不同工具的波动率
- **相对波动率**: NATR > 3% = 高波动率，< 1% = 低波动率
- **均值回归**: 高 NATR 通常会随时间回归均值

---

## TRANGE - 真实波幅

真实波幅是单个周期的原始波动率指标，未经平滑处理。它是 ATR 的基础构建块。

### 公式

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

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | OHLC (high, low, close) |
| 输出 | 单个值（TR，价格单位） |
| 回看期 | 1（需要前一个收盘价） |
| 内存 | O(1) |

### API 用法

::::{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);
```
:::

::::

### 交易用法

- **原始波动率**: 当需要未平滑的波动率时使用
- **跳空检测**: 较大的 TR 配合较小的最高最低价差表示跳空
- **ATR 计算**: TRANGE 是 ATR 计算的输入

### 比较: ATR vs NATR vs TRANGE

| 指标 | 平滑 | 归一化 | 用途 |
|------|------|--------|------|
| TRANGE | 否 | 否 | 原始波动率，跳空检测 |
| ATR | 是（Wilder） | 否 | 标准波动率指标 |
| NATR | 是（Wilder） | 是 | 跨资产比较 |

---

## 相关指标

- **BBANDS**: 使用标准差计算波动率带
- **STDDEV**: 收益率的标准差
- **EWMA_VOL**: 指数加权波动率
- **GARCH_VOL**: 条件波动率的 GARCH 模型