QuanTAlib/lib/statistics/variance/Variance.md

# Variance (VAR)

> *Volatility is the price of admission for high returns.*

| Property         | Value                            |
| ---------------- | -------------------------------- |
| **Category**     | Statistic                        |
| **Inputs**       | Source (close)                          |
| **Parameters**   | `period`, `isPopulation` (default false)                      |
| **Outputs**      | Single series (Variance)                       |
| **Output range** | Varies (see docs)                     |
| **Warmup**       | `period` bars                          |
| **PineScript**   | [variance.pine](variance.pine)                       |

- Variance measures how far a set of numbers is spread out from their average value.
- **Similar:** [StdDev](../stddev/StdDev.md), [MeanDev](../meandev/MeanDev.md) | **Trading note:** Rolling variance; squared deviation from mean. Foundation of portfolio risk calculations.
- Validated against TA-Lib, Skender, and Tulip reference implementations where available.

Variance measures how far a set of numbers is spread out from their average value. In finance, it is a key measure of volatility and risk.

## Historical Context

Variance is a fundamental concept in statistics, formalized by Ronald Fisher in 1918. In finance, it gained prominence with Modern Portfolio Theory (Markowitz, 1952), where it serves as the standard measure of risk.

## Architecture & Physics

The Variance indicator uses a sliding window (RingBuffer) to maintain the last `N` data points. It calculates the variance using an O(1) running sum of squares algorithm, ensuring constant time complexity regardless of the period length.

### O(1) Calculation

The algorithm maintains two running sums:

1. Sum of values ($\sum x$)
2. Sum of squared values ($\sum x^2$)

When a new value enters and an old value leaves:
$$ \sum x_{new} = \sum x_{old} - x_{out} + x_{in} $$
$$ \sum x^2_{new} = \sum x^2_{old} - x^2_{out} + x^2_{in} $$

This avoids iterating over the entire window for each update.

## Mathematical Foundation

Variance ($\sigma^2$ or $s^2$) is defined as:

### Population Variance (N)

$$ \sigma^2 = \frac{\sum_{i=1}^{N} (x_i - \mu)^2}{N} $$

Using the computational formula:

$$ \sigma^2 = \frac{\sum x^2 - \frac{(\sum x)^2}{N}}{N} $$

### Sample Variance (N-1)

$$ s^2 = \frac{\sum_{i=1}^{N} (x_i - \bar{x})^2}{N-1} $$

Using the computational formula:

$$ s^2 = \frac{\sum x^2 - \frac{(\sum x)^2}{N}}{N-1} $$

Where:

* $N$ is the period.
* $\mu$ or $\bar{x}$ is the mean.

## Performance Profile

### Operation Count (Streaming Mode)

Variance uses Welford-style running sums of x and x^2 for exact O(1) update (no sqrt needed).

| Operation | Count | Cost (cycles) | Subtotal |
| :--- | :---: | :---: | :---: |
| Ring buffer add/evict | 1 | 3 cy | ~3 cy |
| Update sum_x and sum_x2 | 2 | 2 cy | ~4 cy |
| Compute variance via shortcut formula | 1 | 5 cy | ~5 cy |
| NaN guard + state update | 1 | 2 cy | ~2 cy |
| **Total** | **O(1)** | — | **~14 cy** |

O(1) per update. Slightly faster than StdDev (no sqrt). Periodic resync prevents floating-point drift in long series where sum_x2 >> (sum_x)^2/N.

| Metric | Score | Notes |
| :--- | :--- | :--- |
| **Throughput** | 5 ns/bar | O(1) complexity using running sums. |
| **Allocations** | 0 | Zero-allocation in hot path. |
| **Complexity** | O(1) | Constant time update. |
| **Accuracy** | 9 | High accuracy, though running sums can accumulate floating point errors over very long periods (mitigated by periodic resync if needed, though not strictly implemented here as window is finite). |

## Validation

| Library | Status | Notes |
| :--- | :--- | :--- |
| **Skender** | ✅ | Matches `StdDev^2` (Sample Variance). |
| **TA-Lib** | ✅ | Matches `VAR` (Population Variance usually, check specific implementation). |

## Usage

```csharp
using QuanTAlib;

// Create a 20-period Sample Variance indicator
var variance = new Variance(20, isPopulation: false);

// Update with a new value
var result = variance.Update(new TValue(DateTime.UtcNow, 100.0));

// Access the last calculated value
Console.WriteLine($"Variance: {variance.Last.Value}");