# 统计函数

用于分析价格分布、相关性和趋势的统计和基于回归的指标。

---

## STDDEV - 标准差

标准差衡量价格在指定周期内围绕其均值的离散程度。

### 公式

$$\mu = \frac{1}{n}\sum_{i=0}^{n-1} price_i$$

$$\sigma = nbdev \times \sqrt{\frac{1}{n}\sum_{i=0}^{n-1}(price_i - \mu)^2}$$

其中 $nbdev$ 是标准差倍数（默认值：1.0）。

### 参数

| 参数 | 类型 | 默认值 | 范围 | 描述 |
|------|------|--------|------|------|
| period | int | 5 | 1-100000 | 周期数 |
| nbdev | double | 1.0 | > 0 | 标准差倍数 |

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 收盘价 |
| 输出 | 单个值（标准差） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

::::{tab-set}

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

stddev = STDDEV(period=20, nbdev=1.0)
result = stddev.update(close_price)
if result.valid:
    print(f"Std Dev: {result.value:.2f}")
```
:::

:::{tab-item} Node.js
```javascript
const stddev = tk.stddev(20, 1.0);
const result = stddev.update(close);
```
:::

:::{tab-item} C++
```cpp
techkit::STDDEV stddev(20, 1.0);
auto result = stddev.update(close);
```
:::

:::{tab-item} C
```c
tk_indicator stddev = tk_stddev_new(20, 1.0);
tk_result r = tk_update(stddev, close);
```
:::

::::

### 交易用法

- **波动率衡量**：标准差越高 = 波动率越高
- **布林带**：用于 BBANDS 计算（标准差 × 倍数）
- **风险评估**：标准差越高 = 风险越高
- **均值回归**：价格远离均值（多个标准差）可能回归

---

## VAR - 方差

方差是标准差的平方，衡量价格的离散程度。

### 公式

$$\mu = \frac{1}{n}\sum_{i=0}^{n-1} price_i$$

$$VAR = \frac{1}{n}\sum_{i=0}^{n-1}(price_i - \mu)^2$$

**注意**：使用总体方差（除以 n，而非 n-1）。

### 参数

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

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 收盘价 |
| 输出 | 单个值（方差） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

```python
from techkit import VAR

var = VAR(period=20)
result = var.update(close_price)
if result.valid:
    print(f"Variance: {result.value:.4f}")
    # Standard deviation = sqrt(variance)
    stddev = result.value ** 0.5
```

### 交易用法

- **波动率代理**：方差是波动率的衡量指标
- **风险模型**：用于投资组合风险计算
- **关系**：STDDEV = sqrt(VAR)

---

## 线性回归函数

线性回归使用最小二乘法在周期内对价格数据拟合一条直线。

### 通用公式

对于线性回归线 $y = a + bx$：

- $a$ = 截距（LINEARREG_INTERCEPT）
- $b$ = 斜率（LINEARREG_SLOPE）
- 末端 $y$ = 预测值（LINEARREG）
- 角度 = atan(b) × 180/π（LINEARREG_ANGLE）

---

## LINEARREG - 线性回归

返回回归周期末端的预测值。

### 公式

$$LINEARREG = a + b \times (period - 1)$$

其中 $a$ 和 $b$ 通过最小二乘回归计算得出。

### 参数

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

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 收盘价 |
| 输出 | 单个值（预测价格） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

```python
from techkit import LINEARREG

linearreg = LINEARREG(period=14)
result = linearreg.update(close_price)
if result.valid:
    print(f"Predicted value: {result.value:.2f}")
```

### 交易用法

- **趋势投影**：向前投影趋势
- **支撑/阻力**：可作为动态支撑/阻力位
- **入场信号**：价格穿越回归线 = 趋势变化

---

## LINEARREG_SLOPE - 线性回归斜率

返回回归线的斜率系数（b），表示趋势方向和强度。

### 公式

$$b = \frac{n\sum xy - \sum x \sum y}{n\sum x^2 - (\sum x)^2}$$

其中 $x$ = 柱索引（0 到 period-1），$y$ = 价格。

### 参数

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

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 收盘价 |
| 输出 | 单个值（每柱斜率） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

```python
from techkit import LINEARREG_SLOPE

slope = LINEARREG_SLOPE(period=14)
result = slope.update(close_price)
if result.valid:
    if result.value > 0:
        print("Uptrend")
    elif result.value < 0:
        print("Downtrend")
    else:
        print("Sideways")
```

### 交易用法

- **趋势方向**：
  - 正斜率 = 上升趋势
  - 负斜率 = 下降趋势
  - 接近零 = 横盘
- **趋势强度**：绝对值越大 = 趋势越强
- **入场信号**：斜率穿越零 = 趋势反转

---

## LINEARREG_INTERCEPT - 线性回归截距

返回回归线的截距系数（a）。

### 公式

$$a = \bar{y} - b \times \bar{x}$$

其中 $\bar{x}$ 和 $\bar{y}$ 是均值。

### 参数

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

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 收盘价 |
| 输出 | 单个值（截距） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

```python
from techkit import LINEARREG_INTERCEPT

intercept = LINEARREG_INTERCEPT(period=14)
result = intercept.update(close_price)
if result.valid:
    print(f"Intercept: {result.value:.2f}")
```

### 交易用法

- **基准水平**：回归线的起点
- **组合使用**：与斜率一起使用以重建完整回归线
- **分析**：截距 + 斜率 × 索引 = 预测值

---

## LINEARREG_ANGLE - 线性回归角度

返回回归线的角度（度），提供趋势陡峭度的直观衡量。

### 公式

$$\text{angle} = \arctan(b) \times \frac{180}{\pi}$$

其中 $b$ 是斜率。

### 参数

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

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 收盘价 |
| 输出 | 单个值（角度，-90 到 +90 度） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

```python
from techkit import LINEARREG_ANGLE

angle = LINEARREG_ANGLE(period=14)
result = angle.update(close_price)
if result.valid:
    if result.value > 45:
        print("Very steep uptrend")
    elif result.value > 0:
        print("Moderate uptrend")
    elif result.value < -45:
        print("Very steep downtrend")
    elif result.value < 0:
        print("Moderate downtrend")
```

### 交易用法

- **趋势陡峭度**：
  - > 45°：非常陡峭的上升趋势
  - 0-45°：中等上升趋势
  - -45° 到 0°：中等下降趋势
  - < -45°：非常陡峭的下降趋势
- **入场时机**：角度越陡 = 趋势越强
- **可视化**：比原始斜率更容易理解

---

## TSF - 时间序列预测

时间序列预测将线性回归向前外推一个周期，提供预测价格。

### 公式

$$TSF = LINEARREG + LINEARREG\_SLOPE$$

本质上：$TSF = a + b \times period$（比 LINEARREG 提前一步）。

### 参数

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

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 收盘价 |
| 输出 | 单个值（预测价格） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

```python
from techkit import TSF

tsf = TSF(period=14)
result = tsf.update(close_price)
if result.valid:
    print(f"Forecast: {result.value:.2f}")
    # Compare with actual
    if close_price > result.value:
        print("Price above forecast (stronger than expected)")
```

### 交易用法

- **价格预测**：预测下一周期的价格
- **预期 vs 现实**：比较预测与实际价格
- **入场信号**：价格穿越预测 = 动量变化
- **趋势延续**：预测高于价格 = 预期上升趋势

---

## BETA - 贝塔系数

贝塔系数衡量一个资产收益对另一个资产收益（通常是基准）的敏感性。

### 公式

$$\beta = \frac{\text{Cov}(X, Y)}{\text{Var}(Y)} = \frac{\sum(x_i - \bar{x})(y_i - \bar{y})}{\sum(y_i - \bar{y})^2}$$

其中：
- $X$ = 资产收益
- $Y$ = 基准收益

### 参数

| 参数 | 类型 | 默认值 | 范围 | 描述 |
|------|------|--------|------|------|
| period | int | 5 | 2-100000 | 周期数 |

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 两个收盘价数组（资产、基准） |
| 输出 | 单个值（贝塔系数） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

```python
from techkit import BETA

beta = BETA(period=20)
result = beta.update(asset_price, benchmark_price)
if result.valid:
    beta_value = result.value
    if beta_value > 1:
        print(f"Asset is {beta_value:.2f}x more volatile than benchmark")
    elif beta_value < 1:
        print(f"Asset is {beta_value:.2f}x less volatile than benchmark")
    else:
        print("Asset moves with benchmark")
```

### 交易用法

- **风险评估**：
  - β > 1：比基准波动更大
  - β = 1：与基准同步移动
  - β < 1：比基准波动更小
  - β < 0：与基准反向移动（罕见）
- **投资组合分析**：衡量系统性风险
- **对冲**：使用贝塔计算对冲比率

---

## CORREL - 皮尔逊相关性

皮尔逊相关性衡量两个价格序列之间的线性关系，范围从 -1 到 +1。

### 公式

$$r = \frac{\text{Cov}(X, Y)}{\sigma_X \times \sigma_Y} = \frac{\sum(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum(x_i - \bar{x})^2 \sum(y_i - \bar{y})^2}}$$

### 参数

| 参数 | 类型 | 默认值 | 范围 | 描述 |
|------|------|--------|------|------|
| period | int | 30 | 2-100000 | 周期数 |

### 特性

| 属性 | 值 |
|------|-----|
| 输入 | 两个收盘价数组 |
| 输出 | 单个值（相关性，-1 到 +1） |
| 回看 | period - 1 |
| 内存 | O(period) |

### API 用法

```python
from techkit import CORREL

correl = CORREL(period=30)
result = correl.update(price1, price2)
if result.valid:
    r = result.value
    if r > 0.7:
        print("Strong positive correlation")
    elif r > 0.3:
        print("Moderate positive correlation")
    elif r > -0.3:
        print("Weak correlation")
    elif r > -0.7:
        print("Moderate negative correlation")
    else:
        print("Strong negative correlation")
```

### 交易用法

- **相关性强度**：
  - |r| > 0.7：强相关
  - 0.3 < |r| < 0.7：中等相关
  - |r| < 0.3：弱相关
- **方向**：
  - r > 0：正相关（同向移动）
  - r < 0：负相关（反向移动）
- **配对交易**：寻找高度相关的配对
- **分散化**：低相关性 = 更好的分散化

---

## 统计函数总结

| 函数 | 用途 | 输出范围 |
|------|------|----------|
| STDDEV | 价格离散度 | 0 到 +∞ |
| VAR | 价格离散度的平方 | 0 到 +∞ |
| LINEARREG | 趋势投影 | 价格单位 |
| LINEARREG_SLOPE | 趋势方向/强度 | -∞ 到 +∞ |
| LINEARREG_INTERCEPT | 回归基准水平 | 价格单位 |
| LINEARREG_ANGLE | 趋势角度 | -90° 到 +90° |
| TSF | 价格预测 | 价格单位 |
| BETA | 相对波动率 | -∞ 到 +∞ |
| CORREL | 价格关系 | -1 到 +1 |

---

## 相关指标

- **BBANDS**：使用 STDDEV 进行带计算
- **ATR**：替代波动率衡量指标
- **MAMA**：使用回归概念的自适应移动平均