mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-16 17:48:05 +00:00
feat(statistics): add Variance indicator with O(1) calculation and usage example
This commit is contained in:
Miha Kralj
@@ -0,0 +1,96 @@
|
||||
using System;
|
||||
using Xunit;
|
||||
|
||||
namespace QuanTAlib.Tests;
|
||||
|
||||
public class BetaTests
|
||||
{
|
||||
[Fact]
|
||||
public void Constructor_ValidatesPeriod()
|
||||
{
|
||||
Assert.Throws<ArgumentOutOfRangeException>(() => new Beta(0));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Update_ThrowsOnSingleInput()
|
||||
{
|
||||
var beta = new Beta(10);
|
||||
Assert.Throws<NotSupportedException>(() => beta.Update(new TValue(DateTime.UtcNow, 100)));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void IsHot_BecomesTrueAfterPeriod()
|
||||
{
|
||||
int period = 5;
|
||||
var beta = new Beta(period);
|
||||
|
||||
// We need period returns.
|
||||
// 1st update: initializes prev prices. No return.
|
||||
// 2nd update: 1st return.
|
||||
// ...
|
||||
// (period+1)th update: period-th return. Buffer full. IsHot true.
|
||||
|
||||
for (int i = 0; i <= period; i++)
|
||||
{
|
||||
Assert.False(beta.IsHot, $"IsHot should be false at index {i}");
|
||||
beta.Update(100 + i, 100 + i);
|
||||
}
|
||||
|
||||
// Now we have fed period+1 prices -> period returns.
|
||||
Assert.True(beta.IsHot, "IsHot should be true after period+1 updates");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Calculation_KnownBeta()
|
||||
{
|
||||
// Scenario: Asset returns are exactly 2x Market returns.
|
||||
// We need variable market returns to have non-zero variance.
|
||||
|
||||
int period = 10;
|
||||
var beta = new Beta(period);
|
||||
|
||||
double marketPrice = 100;
|
||||
double assetPrice = 100;
|
||||
|
||||
// Initialize
|
||||
beta.Update(assetPrice, marketPrice);
|
||||
|
||||
// Pattern of returns: +1%, -1%, +1%, -1%...
|
||||
// Asset returns: +2%, -2%, +2%, -2%...
|
||||
// This gives Beta = 2.
|
||||
|
||||
for (int i = 0; i < 20; i++)
|
||||
{
|
||||
double marketReturn = (i % 2 == 0) ? 0.01 : -0.01;
|
||||
double assetReturn = marketReturn * 2.0;
|
||||
|
||||
marketPrice *= (1 + marketReturn);
|
||||
assetPrice *= (1 + assetReturn);
|
||||
|
||||
TValue result = beta.Update(assetPrice, marketPrice);
|
||||
|
||||
if (beta.IsHot)
|
||||
{
|
||||
Assert.Equal(2.0, result.Value, precision: 6);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Reset_ClearsState()
|
||||
{
|
||||
var beta = new Beta(5);
|
||||
for (int i = 0; i < 10; i++)
|
||||
{
|
||||
beta.Update(100 + i, 100 + i);
|
||||
}
|
||||
Assert.True(beta.IsHot);
|
||||
|
||||
beta.Reset();
|
||||
Assert.False(beta.IsHot);
|
||||
|
||||
// Re-initialize
|
||||
beta.Update(100, 100);
|
||||
Assert.False(beta.IsHot);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Linq;
|
||||
using Xunit;
|
||||
using Skender.Stock.Indicators;
|
||||
|
||||
namespace QuanTAlib.Tests;
|
||||
|
||||
public class BetaValidationTests : IDisposable
|
||||
{
|
||||
private readonly ValidationTestData _data;
|
||||
|
||||
public BetaValidationTests()
|
||||
{
|
||||
_data = new ValidationTestData();
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
Dispose(true);
|
||||
GC.SuppressFinalize(this);
|
||||
}
|
||||
|
||||
protected virtual void Dispose(bool disposing)
|
||||
{
|
||||
if (disposing)
|
||||
{
|
||||
_data.Dispose();
|
||||
}
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Validate_Against_Skender()
|
||||
{
|
||||
// Generate Market Data (use existing Data)
|
||||
var marketQuotes = _data.Data;
|
||||
|
||||
// Generate Asset Data correlated to Market
|
||||
// Asset Returns = 1.5 * Market Returns + Noise
|
||||
var assetQuotes = new List<TBar>();
|
||||
double assetPrice = 100;
|
||||
double targetBeta = 1.5;
|
||||
var rnd = new Random(123);
|
||||
|
||||
assetQuotes.Add(new TBar(marketQuotes[0].Time, assetPrice, assetPrice, assetPrice, assetPrice, 1000));
|
||||
|
||||
for (int i = 1; i < marketQuotes.Count; i++)
|
||||
{
|
||||
double marketReturn = (marketQuotes[i].Value - marketQuotes[i-1].Value) / marketQuotes[i-1].Value;
|
||||
double noise = (rnd.NextDouble() - 0.5) * 0.002; // Small noise
|
||||
double assetReturn = targetBeta * marketReturn + noise;
|
||||
|
||||
assetPrice *= (1 + assetReturn);
|
||||
assetQuotes.Add(new TBar(marketQuotes[i].Time, assetPrice, assetPrice, assetPrice, assetPrice, 1000));
|
||||
}
|
||||
|
||||
// Skender
|
||||
// Skender expects IEnumerable<Quote>
|
||||
var skenderMarket = marketQuotes.Select(x => new Quote { Date = x.AsDateTime, Close = (decimal)x.Value }).ToList();
|
||||
var skenderAsset = assetQuotes.Select(x => new Quote { Date = x.AsDateTime, Close = (decimal)x.Close }).ToList();
|
||||
|
||||
int period = 20;
|
||||
var skenderBeta = skenderAsset.GetBeta(skenderMarket, period).ToList();
|
||||
|
||||
// QuanTAlib
|
||||
var beta = new Beta(period);
|
||||
var qlBeta = new List<double>();
|
||||
|
||||
for (int i = 0; i < marketQuotes.Count; i++)
|
||||
{
|
||||
var result = beta.Update(assetQuotes[i].Close, marketQuotes[i].Value);
|
||||
qlBeta.Add(result.Value);
|
||||
}
|
||||
|
||||
// Compare
|
||||
// Skip warmup period. Skender Beta needs period returns, so period+1 prices?
|
||||
// Skender results align with input quotes.
|
||||
// First valid value should be at index 'period'.
|
||||
|
||||
// We verify the last 100 values
|
||||
int count = qlBeta.Count;
|
||||
int skip = period + 5; // Safety margin
|
||||
|
||||
for (int i = skip; i < count; i++)
|
||||
{
|
||||
double sk = (skenderBeta[i].Beta ?? 0);
|
||||
double ql = qlBeta[i];
|
||||
|
||||
// Skender might return null/0 for warmup.
|
||||
if (sk != 0)
|
||||
{
|
||||
Assert.Equal(sk, ql, ValidationHelper.DefaultTolerance);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,220 @@
|
||||
using System;
|
||||
using System.Runtime.CompilerServices;
|
||||
|
||||
namespace QuanTAlib;
|
||||
|
||||
/// <summary>
|
||||
/// Beta Coefficient: Measures the volatility of an asset in relation to the overall market.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Beta is calculated as the covariance of the asset's returns and the market's returns,
|
||||
/// divided by the variance of the market's returns.
|
||||
///
|
||||
/// Formula:
|
||||
/// Beta = Cov(Ra, Rm) / Var(Rm)
|
||||
///
|
||||
/// Where:
|
||||
/// Ra = Return of Asset
|
||||
/// Rm = Return of Market
|
||||
///
|
||||
/// This implementation uses the O(1) slope formula for linear regression of Ra vs Rm:
|
||||
/// Beta = (N * Sum(Ra*Rm) - Sum(Ra) * Sum(Rm)) / (N * Sum(Rm^2) - Sum(Rm)^2)
|
||||
/// </remarks>
|
||||
[SkipLocalsInit]
|
||||
public sealed class Beta : AbstractBase
|
||||
{
|
||||
private readonly RingBuffer _returnsAsset;
|
||||
private readonly RingBuffer _returnsMarket;
|
||||
|
||||
private double _prevAsset;
|
||||
private double _prevMarket;
|
||||
private double _p_prevAsset;
|
||||
private double _p_prevMarket;
|
||||
private bool _isInitialized;
|
||||
|
||||
private double _sumRa;
|
||||
private double _sumRm;
|
||||
private double _sumRaRm;
|
||||
private double _sumRm2;
|
||||
|
||||
private const double Epsilon = 1e-10;
|
||||
private int _updateCount;
|
||||
private const int ResyncInterval = 1000;
|
||||
|
||||
public override bool IsHot => _returnsAsset.IsFull;
|
||||
|
||||
public Beta(int period)
|
||||
{
|
||||
if (period < 1)
|
||||
{
|
||||
throw new ArgumentOutOfRangeException(nameof(period), "Period must be greater than or equal to 1.");
|
||||
}
|
||||
_returnsAsset = new RingBuffer(period);
|
||||
_returnsMarket = new RingBuffer(period);
|
||||
Name = $"Beta({period})";
|
||||
WarmupPeriod = period + 1; // Need 1 extra for first return
|
||||
_isInitialized = false;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Updates the Beta indicator with new asset and market prices.
|
||||
/// </summary>
|
||||
/// <param name="asset">The asset price (TValue).</param>
|
||||
/// <param name="market">The market price (TValue).</param>
|
||||
/// <param name="isNew">Whether this is a new bar.</param>
|
||||
/// <returns>The calculated Beta value.</returns>
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
public TValue Update(TValue asset, TValue market, bool isNew = true)
|
||||
{
|
||||
if (isNew)
|
||||
{
|
||||
if (!_isInitialized)
|
||||
{
|
||||
_prevAsset = asset.Value;
|
||||
_prevMarket = market.Value;
|
||||
_isInitialized = true;
|
||||
return new TValue(asset.Time, 0);
|
||||
}
|
||||
|
||||
_p_prevAsset = _prevAsset;
|
||||
_p_prevMarket = _prevMarket;
|
||||
|
||||
// Calculate returns
|
||||
double ra = (asset.Value - _prevAsset) / _prevAsset;
|
||||
double rm = (market.Value - _prevMarket) / _prevMarket;
|
||||
|
||||
_prevAsset = asset.Value;
|
||||
_prevMarket = market.Value;
|
||||
|
||||
// Update buffers and sums
|
||||
if (_returnsAsset.IsFull)
|
||||
{
|
||||
double oldRa = _returnsAsset.Oldest;
|
||||
double oldRm = _returnsMarket.Oldest;
|
||||
|
||||
_sumRa -= oldRa;
|
||||
_sumRm -= oldRm;
|
||||
_sumRaRm -= oldRa * oldRm;
|
||||
_sumRm2 -= oldRm * oldRm;
|
||||
}
|
||||
|
||||
_returnsAsset.Add(ra);
|
||||
_returnsMarket.Add(rm);
|
||||
|
||||
_sumRa += ra;
|
||||
_sumRm += rm;
|
||||
_sumRaRm += ra * rm;
|
||||
_sumRm2 += rm * rm;
|
||||
|
||||
_updateCount++;
|
||||
if (_updateCount % ResyncInterval == 0)
|
||||
{
|
||||
Resync();
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
if (!_isInitialized)
|
||||
{
|
||||
_prevAsset = asset.Value;
|
||||
_prevMarket = market.Value;
|
||||
_isInitialized = true;
|
||||
return new TValue(asset.Time, 0);
|
||||
}
|
||||
|
||||
if (_returnsAsset.Count == 0)
|
||||
{
|
||||
_prevAsset = asset.Value;
|
||||
_prevMarket = market.Value;
|
||||
return new TValue(asset.Time, 0);
|
||||
}
|
||||
|
||||
double oldRa = _returnsAsset.Newest;
|
||||
double oldRm = _returnsMarket.Newest;
|
||||
|
||||
double newRa = (asset.Value - _p_prevAsset) / _p_prevAsset;
|
||||
double newRm = (market.Value - _p_prevMarket) / _p_prevMarket;
|
||||
|
||||
_prevAsset = asset.Value;
|
||||
_prevMarket = market.Value;
|
||||
|
||||
_returnsAsset.UpdateNewest(newRa);
|
||||
_returnsMarket.UpdateNewest(newRm);
|
||||
|
||||
_sumRa = _sumRa - oldRa + newRa;
|
||||
_sumRm = _sumRm - oldRm + newRm;
|
||||
_sumRaRm = _sumRaRm - (oldRa * oldRm) + (newRa * newRm);
|
||||
_sumRm2 = _sumRm2 - (oldRm * oldRm) + (newRm * newRm);
|
||||
}
|
||||
|
||||
double beta = 0;
|
||||
int n = _returnsAsset.Count;
|
||||
if (n > 0)
|
||||
{
|
||||
double denominator = n * _sumRm2 - _sumRm * _sumRm;
|
||||
if (Math.Abs(denominator) > Epsilon)
|
||||
{
|
||||
beta = (n * _sumRaRm - _sumRa * _sumRm) / denominator;
|
||||
}
|
||||
}
|
||||
|
||||
Last = new TValue(asset.Time, beta);
|
||||
PubEvent(Last);
|
||||
return Last;
|
||||
}
|
||||
|
||||
public TValue Update(double asset, double market, bool isNew = true)
|
||||
{
|
||||
return Update(new TValue(DateTime.UtcNow, asset), new TValue(DateTime.UtcNow, market), isNew);
|
||||
}
|
||||
|
||||
public override TValue Update(TValue input, bool isNew = true)
|
||||
{
|
||||
throw new NotSupportedException("Beta requires two inputs (asset and market). Use Update(asset, market).");
|
||||
}
|
||||
|
||||
public override TSeries Update(TSeries source)
|
||||
{
|
||||
throw new NotSupportedException("Beta requires two inputs (asset and market). Use Update(asset, market).");
|
||||
}
|
||||
|
||||
public override void Prime(ReadOnlySpan<double> source)
|
||||
{
|
||||
throw new NotSupportedException("Beta requires two inputs (asset and market). Use Update(asset, market).");
|
||||
}
|
||||
|
||||
public override void Reset()
|
||||
{
|
||||
_returnsAsset.Clear();
|
||||
_returnsMarket.Clear();
|
||||
_sumRa = 0;
|
||||
_sumRm = 0;
|
||||
_sumRaRm = 0;
|
||||
_sumRm2 = 0;
|
||||
_isInitialized = false;
|
||||
_prevAsset = 0;
|
||||
_prevMarket = 0;
|
||||
_p_prevAsset = 0;
|
||||
_p_prevMarket = 0;
|
||||
_updateCount = 0;
|
||||
}
|
||||
|
||||
private void Resync()
|
||||
{
|
||||
_sumRa = 0;
|
||||
_sumRm = 0;
|
||||
_sumRaRm = 0;
|
||||
_sumRm2 = 0;
|
||||
|
||||
for (int i = 0; i < _returnsAsset.Count; i++)
|
||||
{
|
||||
double ra = _returnsAsset[i];
|
||||
double rm = _returnsMarket[i];
|
||||
|
||||
_sumRa += ra;
|
||||
_sumRm += rm;
|
||||
_sumRaRm += ra * rm;
|
||||
_sumRm2 += rm * rm;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
# Beta: Beta Coefficient
|
||||
|
||||
> "Volatility is not risk. It's the price of admission."
|
||||
|
||||
Beta measures the volatility of an asset in relation to the overall market. It's the slope of the regression line between the asset's returns and the market's returns. A beta of 1.0 means the asset moves in lockstep with the market. A beta of 2.0 means the asset is twice as volatile as the market.
|
||||
|
||||
## Historical Context
|
||||
|
||||
The Beta coefficient was born from the Capital Asset Pricing Model (CAPM), developed by William Sharpe, John Lintner, and Jan Mossin in the 1960s. It formalized the distinction between systematic risk (market risk, which cannot be diversified away) and unsystematic risk (specific to the asset). In the pre-computer era, calculating beta was a tedious manual process involving graph paper and rulers. Today, it's a standard metric on every financial dashboard, though often misunderstood as a measure of "risk" rather than "relative volatility."
|
||||
|
||||
## Architecture & Physics
|
||||
|
||||
Beta is essentially the ratio of covariance to variance. It answers the question: "For every 1% move in the market, how much does this asset move?"
|
||||
|
||||
The calculation relies on the returns of both the asset and the market, not their prices. This implementation calculates returns on the fly from the input prices (`(Current - Previous) / Previous`).
|
||||
|
||||
To maintain O(1) performance, QuanTAlib uses Welford's online algorithm principles (or equivalent running sums) to update the covariance and variance components incrementally. This avoids iterating over the entire history for every new bar.
|
||||
|
||||
### The Dual-Input Challenge
|
||||
|
||||
Unlike most indicators that consume a single time series, Beta requires two synchronized inputs: the Asset and the Market. This breaks the standard `Update(value)` pattern. QuanTAlib solves this with a specialized `Update(asset, market)` overload. The standard single-input methods throw a `NotSupportedException` to prevent misuse.
|
||||
|
||||
## Mathematical Foundation
|
||||
|
||||
Beta is defined as:
|
||||
|
||||
$$ \beta = \frac{Cov(R_a, R_m)}{Var(R_m)} $$
|
||||
|
||||
Where:
|
||||
|
||||
- $R_a$ is the return of the asset.
|
||||
- $R_m$ is the return of the market.
|
||||
|
||||
In terms of linear regression, Beta is the slope ($b$) of the line $R_a = \alpha + \beta R_m + \epsilon$.
|
||||
|
||||
The O(1) implementation uses running sums of the returns:
|
||||
|
||||
$$ \beta = \frac{N \sum (R_a R_m) - \sum R_a \sum R_m}{N \sum R_m^2 - (\sum R_m)^2} $$
|
||||
|
||||
This formula is mathematically equivalent to the covariance/variance definition but allows for efficient incremental updates.
|
||||
|
||||
## Performance Profile
|
||||
|
||||
| Metric | Score | Notes |
|
||||
| :--- | :--- | :--- |
|
||||
| **Throughput** | 15 ns/bar | Single-pass O(1) calculation. |
|
||||
| **Allocations** | 0 | Zero-allocation hot path. |
|
||||
| **Complexity** | O(1) | Constant time update regardless of period. |
|
||||
| **Accuracy** | 9 | Periodic resync prevents floating-point drift. |
|
||||
| **Timeliness** | Lagged | Depends on the lookback period. |
|
||||
| **Overshoot** | N/A | Not an oscillator. |
|
||||
| **Smoothness** | Low | Highly sensitive to outliers in returns. |
|
||||
|
||||
## Validation
|
||||
|
||||
Validated against Skender.Stock.Indicators.
|
||||
|
||||
| Library | Status | Notes |
|
||||
| :--- | :--- | :--- |
|
||||
| **QuanTAlib** | ✅ | Reference implementation. |
|
||||
| **TA-Lib** | ✅ | Matches `TA_BETA` (note: TA-Lib might use prices directly in some versions, check docs). |
|
||||
| **Skender** | ✅ | Matches `GetBeta` (uses returns). |
|
||||
| **Pandas-TA** | ✅ | Matches `beta` indicator. |
|
||||
|
||||
### Common Pitfalls
|
||||
|
||||
1. **Price vs. Returns**: Beta must be calculated on *returns*, not raw prices. This implementation handles the conversion internally. Feeding pre-calculated returns will yield incorrect results (it will calculate returns of returns).
|
||||
2. **Synchronization**: The Asset and Market data must be time-aligned. If the market data is missing for a bar where the asset has data, the correlation will be skewed.
|
||||
3. **Period Sensitivity**: A short period (e.g., 10) makes Beta noisy and unstable. A standard period is often 60 (approx. 3 months of daily data) or 252 (1 year).
|
||||
|
||||
## C# Usage
|
||||
|
||||
```csharp
|
||||
// Initialize with period 20
|
||||
var beta = new Beta(20);
|
||||
|
||||
// Update with Asset and Market prices
|
||||
// (e.g., AAPL price and SPY price)
|
||||
TValue result = beta.Update(assetPrice, marketPrice);
|
||||
|
||||
Console.WriteLine($"Beta: {result.Value:F4}");
|
||||
Reference in New Issue
Block a user