# Statistical Functions

Statistical and regression-based indicators for analyzing price distributions, correlations, and trends.

---

## STDDEV - Standard Deviation

The Standard Deviation measures the dispersion of prices around their mean over a specified period.

### Formula

$$\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}$$

where $nbdev$ is the number of standard deviations multiplier (default: 1.0).

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 5 | 1-100000 | Number of periods |
| nbdev | double | 1.0 | > 0 | Standard deviation multiplier |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Close price |
| Output | Single value (standard deviation) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

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

::::

### Trading Usage

- **Volatility Measure**: Higher stddev = higher volatility
- **Bollinger Bands**: Used in BBANDS calculation (stddev × multiplier)
- **Risk Assessment**: Higher stddev = higher risk
- **Mean Reversion**: Prices far from mean (multiple stddevs) may revert

---

## VAR - Variance

The Variance is the square of standard deviation, measuring price dispersion.

### Formula

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

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

**Note**: Uses population variance (divide by n, not n-1).

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 5 | 1-100000 | Number of periods |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Close price |
| Output | Single value (variance) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

```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
```

### Trading Usage

- **Volatility Proxy**: Variance is a measure of volatility
- **Risk Models**: Used in portfolio risk calculations
- **Relationship**: STDDEV = sqrt(VAR)

---

## Linear Regression Functions

Linear regression fits a straight line to price data over a period using least squares method.

### General Formula

For a linear regression line $y = a + bx$:

- $a$ = intercept (LINEARREG_INTERCEPT)
- $b$ = slope (LINEARREG_SLOPE)
- $y$ at end = predicted value (LINEARREG)
- Angle = atan(b) × 180/π (LINEARREG_ANGLE)

---

## LINEARREG - Linear Regression

Returns the predicted value at the end of the regression period.

### Formula

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

where $a$ and $b$ are calculated from least squares regression.

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 14 | 2-100000 | Number of periods |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Close price |
| Output | Single value (predicted price) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

```python
from techkit import LINEARREG

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

### Trading Usage

- **Trend Projection**: Projects trend forward
- **Support/Resistance**: Can act as dynamic S/R level
- **Entry Signals**: Price crossing regression line = trend change

---

## LINEARREG_SLOPE - Linear Regression Slope

Returns the slope coefficient (b) of the regression line, indicating trend direction and strength.

### Formula

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

where $x$ = bar index (0 to period-1), $y$ = price.

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 14 | 2-100000 | Number of periods |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Close price |
| Output | Single value (slope per bar) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

```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")
```

### Trading Usage

- **Trend Direction**: 
  - Positive slope = uptrend
  - Negative slope = downtrend
  - Near zero = sideways
- **Trend Strength**: Larger absolute value = stronger trend
- **Entry Signals**: Slope crossing zero = trend reversal

---

## LINEARREG_INTERCEPT - Linear Regression Intercept

Returns the intercept coefficient (a) of the regression line.

### Formula

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

where $\bar{x}$ and $\bar{y}$ are the means.

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 14 | 2-100000 | Number of periods |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Close price |
| Output | Single value (intercept) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

```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}")
```

### Trading Usage

- **Base Level**: Starting point of regression line
- **Combined Use**: Use with slope to reconstruct full regression line
- **Analysis**: Intercept + slope × index = predicted value

---

## LINEARREG_ANGLE - Linear Regression Angle

Returns the angle of the regression line in degrees, providing an intuitive measure of trend steepness.

### Formula

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

where $b$ is the slope.

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 14 | 2-100000 | Number of periods |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Close price |
| Output | Single value (angle in degrees, -90 to +90) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

```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")
```

### Trading Usage

- **Trend Steepness**: 
  - > 45°: Very steep uptrend
  - 0-45°: Moderate uptrend
  - -45° to 0°: Moderate downtrend
  - < -45°: Very steep downtrend
- **Entry Timing**: Steeper angles = stronger trends
- **Visualization**: Easier to interpret than raw slope

---

## TSF - Time Series Forecast

The Time Series Forecast extrapolates the linear regression one period ahead, providing a forecasted price.

### Formula

$$TSF = LINEARREG + LINEARREG\_SLOPE$$

Essentially: $TSF = a + b \times period$ (one step ahead of LINEARREG).

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 14 | 2-100000 | Number of periods |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Close price |
| Output | Single value (forecasted price) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

```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)")
```

### Trading Usage

- **Price Forecast**: Predicts next period's price
- **Expectation vs. Reality**: Compare forecast to actual price
- **Entry Signals**: Price crossing forecast = momentum shift
- **Trend Continuation**: Forecast above price = uptrend expected

---

## BETA - Beta Coefficient

The Beta coefficient measures the sensitivity of one asset's returns to another asset's returns (typically a benchmark).

### Formula

$$\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}$$

where:
- $X$ = asset returns
- $Y$ = benchmark returns

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 5 | 2-100000 | Number of periods |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Two close price arrays (asset, benchmark) |
| Output | Single value (beta coefficient) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

```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")
```

### Trading Usage

- **Risk Assessment**: 
  - β > 1: More volatile than benchmark
  - β = 1: Moves with benchmark
  - β < 1: Less volatile than benchmark
  - β < 0: Moves opposite to benchmark (rare)
- **Portfolio Analysis**: Measure systematic risk
- **Hedging**: Use beta to calculate hedge ratios

---

## CORREL - Pearson Correlation

The Pearson Correlation measures the linear relationship between two price series, ranging from -1 to +1.

### Formula

$$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}}$$

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 30 | 2-100000 | Number of periods |

### Characteristics

| Property | Value |
|----------|-------|
| Input | Two close price arrays |
| Output | Single value (correlation, -1 to +1) |
| Lookback | period - 1 |
| Memory | O(period) |

### API Usage

```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")
```

### Trading Usage

- **Correlation Strength**:
  - |r| > 0.7: Strong correlation
  - 0.3 < |r| < 0.7: Moderate correlation
  - |r| < 0.3: Weak correlation
- **Direction**:
  - r > 0: Positive (move together)
  - r < 0: Negative (move opposite)
- **Pairs Trading**: Find highly correlated pairs
- **Diversification**: Low correlation = better diversification

---

## Statistical Functions Summary

| Function | Purpose | Output Range |
|----------|---------|--------------|
| STDDEV | Price dispersion | 0 to +∞ |
| VAR | Price dispersion squared | 0 to +∞ |
| LINEARREG | Trend projection | Price units |
| LINEARREG_SLOPE | Trend direction/strength | -∞ to +∞ |
| LINEARREG_INTERCEPT | Regression base level | Price units |
| LINEARREG_ANGLE | Trend angle | -90° to +90° |
| TSF | Price forecast | Price units |
| BETA | Relative volatility | -∞ to +∞ |
| CORREL | Price relationship | -1 to +1 |

---

## Related Indicators

- **BBANDS**: Uses STDDEV for band calculation
- **ATR**: Alternative volatility measure
- **MAMA**: Adaptive moving average using regression concepts