gavindiaz/QuanTAlib
1
0
Fork 0
mirror of https://github.com/mihakralj/QuanTAlib.git synced 2026-08-13 16:18:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

xml doc rewrite

Browse Source
This commit is contained in:
Miha
2024-10-27 09:38:53 -07:00
parent c21b96152c
commit b2fcdda785
71 changed files with 2607 additions and 1102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/statistics/Percentile.cs
+48 -53
View File
@@ -1,40 +1,54 @@
using System;
using System.Linq;
namespace QuanTAlib;
/// <summary>
/// Represents a percentile calculator that determines the value at a specified percentile
/// in a given period of data points.
/// Percentile: Distribution Position Measure
/// A statistical measure that indicates the value below which a given percentage
/// of observations falls. Percentiles provide insights into data distribution
/// and are particularly useful for risk assessment and outlier detection.
/// </summary>
/// <remarks>
/// The Percentile class uses a circular buffer to store values and calculates the
/// percentile efficiently. It uses linear interpolation when the percentile falls
/// between two data points. Before the specified period is reached, it returns the
/// average of the available values as an approximation.
/// The Percentile calculation process:
/// 1. Sorts values in ascending order
/// 2. Calculates position based on percentile
/// 3. Interpolates between adjacent values
/// 4. Uses mean until period filled
///
/// In financial analysis, percentiles are useful for:
/// - Assessing the relative standing of a value within a distribution.
/// - Identifying outliers or extreme values in financial data.
/// - Creating risk measures, such as Value at Risk (VaR) calculations.
/// - Analyzing the distribution of returns, trading volumes, or other financial metrics.
/// Key characteristics:
/// - Range specific value identification
/// - Linear interpolation for precision
/// - Distribution independent
/// - Robust to outliers
/// - Useful for risk metrics
///
/// Formula:
/// position = (percentile/100) * (n-1)
/// value = v[floor(pos)] + (v[ceil(pos)] - v[floor(pos)]) * (pos - floor(pos))
/// where n = number of observations, v = sorted values
///
/// Market Applications:
/// - Value at Risk (VaR) calculation
/// - Risk management metrics
/// - Performance analysis
/// - Volatility assessment
/// - Outlier detection
///
/// Sources:
/// https://en.wikipedia.org/wiki/Percentile
/// "Risk Management in Trading" - Davis Edwards
///
/// Note: Particularly useful for risk metrics like VaR
/// </remarks>
public class Percentile : AbstractBase
{
/// <summary>
/// The number of data points to consider for the percentile calculation.
/// </summary>
private readonly int Period;
/// <summary>
/// The percentile to calculate (between 0 and 100).
/// </summary>
private readonly double Percent;
private readonly CircularBuffer _buffer;
/// <summary>
/// Initializes a new instance of the Percentile class with the specified period and percentile.
/// </summary>
/// <param name="period">The period over which to calculate the percentile.</param>
/// <param name="percent">The percentile to calculate (between 0 and 100).</param>
/// <param name="period">The number of points to consider for percentile calculation.</param>
/// <param name="percent">The percentile to calculate (0-100).</param>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown when period is less than 2 or percent is not between 0 and 100.
/// </exception>
@@ -42,11 +56,13 @@ public class Percentile : AbstractBase
{
if (period < 2)
{
throw new ArgumentOutOfRangeException(nameof(period), "Period must be greater than or equal to 2 for percentile calculation.");
throw new ArgumentOutOfRangeException(nameof(period),
"Period must be greater than or equal to 2 for percentile calculation.");
}
if (percent < 0 || percent > 100)
{
throw new ArgumentOutOfRangeException(nameof(percent), "Percent must be between 0 and 100.");
throw new ArgumentOutOfRangeException(nameof(percent),
"Percent must be between 0 and 100.");
}
Period = period;
Percent = percent;
@@ -56,31 +72,21 @@ public class Percentile : AbstractBase
Init();
}
/// <summary>
/// Initializes a new instance of the Percentile class with the specified source, period, and percentile.
/// </summary>
/// <param name="source">The source object to subscribe to for value updates.</param>
/// <param name="period">The period over which to calculate the percentile.</param>
/// <param name="percent">The percentile to calculate (between 0 and 100).</param>
/// <param name="source">The data source object that publishes updates.</param>
/// <param name="period">The number of points to consider for percentile calculation.</param>
/// <param name="percent">The percentile to calculate (0-100).</param>
public Percentile(object source, int period, double percent) : this(period, percent)
{
var pubEvent = source.GetType().GetEvent("Pub");
pubEvent?.AddEventHandler(source, new ValueSignal(Sub));
}
/// <summary>
/// Initializes the Percentile instance by clearing the buffer.
/// </summary>
public override void Init()
{
base.Init();
_buffer.Clear();
}
/// <summary>
/// Manages the state of the Percentile instance based on whether a new value is being processed.
/// </summary>
/// <param name="isNew">Indicates whether the current input is a new value.</param>
protected override void ManageState(bool isNew)
{
if (isNew)
@@ -90,18 +96,6 @@ public class Percentile : AbstractBase
}
}
/// <summary>
/// Performs the percentile calculation for the current period.
/// </summary>
/// <returns>
/// The calculated percentile value for the current period.
/// </returns>
/// <remarks>
/// This method uses linear interpolation when the percentile falls between two data points.
/// Before the specified period is reached, it returns the average of the available values
/// as an approximation. Once the period is reached, it calculates the true percentile by
/// sorting the values and interpolating as necessary.
/// </remarks>
protected override double Calculation()
{
ManageState(Input.IsNew);
@@ -110,6 +104,7 @@ public class Percentile : AbstractBase
double result;
if (_buffer.Count >= Period)
{
// Sort values and calculate percentile position
var values = _buffer.GetSpan().ToArray();
Array.Sort(values);
@@ -123,7 +118,7 @@ public class Percentile : AbstractBase
}
else
{
// Interpolate between the two nearest values
// Linear interpolation between adjacent values
double lowerValue = values[lowerIndex];
double upperValue = values[upperIndex];
double fraction = position - lowerIndex;
@@ -132,7 +127,7 @@ public class Percentile : AbstractBase
}
else
{
// Use average for insufficient data, like the Median class
// Use average until we have enough data points
result = _buffer.Average();
}