Class StatisticalFunctions

Namespace

SignalSharp.Utilities

Assembly

SignalSharp.dll

Provides a set of statistical functions for numerical data processing, automatically leveraging SIMD acceleration for supported types where available.

public static class StatisticalFunctions

Inheritance

object

StatisticalFunctions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This class offers optimized implementations for common statistical calculations. It primarily exposes generic methods working with INumber<TSelf>. Internally, it dispatches to SIMD-optimized code for types like double when hardware acceleration is enabled, falling back to generic implementations otherwise.

Methods

Max<T>(ReadOnlySpan<T>)

Calculates the maximum value in a set of values.

public static T Max<T>(ReadOnlySpan<T> values) where T : INumber<T>

Parameters

values ReadOnlySpan<T>

The set of values.

Returns

T

The maximum value in the set.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf>.

Remarks

NaN handling is positional: if the first value is NaN the result is NaN, while NaN values appearing later are ignored because every comparison against NaN is false.

Exceptions

InvalidOperationException

Thrown when the input sequence is empty.

Mean<T>(ReadOnlySpan<T>)

Calculates the mean (average) of a set of values.

public static T Mean<T>(ReadOnlySpan<T> values) where T : struct, INumber<T>

Parameters

values ReadOnlySpan<T>

The set of values.

Returns

T

The mean of the values. Returns T.Zero if the input span is empty.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf>.

Examples

var doubleValues = new[] { 1.0, 2.0, 3.0 };
var doubleMean = StatisticalFunctions.Mean(doubleValues.AsSpan()); // Uses SIMD if available
Console.WriteLine(doubleMean); // Output: 2.0

var floatValues = new[] { 1.0f, 2.0f, 3.0f };
var floatMean = StatisticalFunctions.Mean(floatValues.AsSpan()); // Uses SIMD if available
Console.WriteLine(floatMean); // Output: 2.0f

var intValues = new[] { 1, 2, 3 };
var intMean = StatisticalFunctions.Mean(intValues.AsSpan()); // Uses generic implementation
Console.WriteLine(intMean); // Output: 2 (integer division)

Remarks

For integral numeric types the running sum is accumulated in T and can overflow for large values; use a floating-point element type when values are large. Integer element types also divide with integer (truncating) semantics.

Median<T>(ReadOnlySpan<T>, bool)

Calculates the median of a set of values.

public static T Median<T>(ReadOnlySpan<T> values, bool useQuickSelect = false) where T : INumber<T>

Parameters

values ReadOnlySpan<T>

The set of values.

useQuickSelect bool

A flag indicating whether to use the QuickSelect algorithm (potentially faster, modifies input array copy) or sort-based method.

Returns

T

The median of the values.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf>.

Examples

var values = new[] { 1.0, 5.0, 2.0, 4.0, 3.0 };
var median = StatisticalFunctions.Median(values.AsSpan());
Console.WriteLine(median); // Output: 3.0

Remarks

The values are copied before sorting, so the caller's data is never mutated. For integral numeric types the even-count midpoint is computed without overflow, but the values themselves must be representable in T.

Exceptions

ArgumentException

Thrown when the values span is empty.

Min<T>(ReadOnlySpan<T>)

Calculates the minimum value in a set of values.

public static T Min<T>(ReadOnlySpan<T> values) where T : INumber<T>

Parameters

values ReadOnlySpan<T>

The set of values.

Returns

T

The minimum value in the set.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf>.

Remarks

NaN handling is positional: if the first value is NaN the result is NaN, while NaN values appearing later are ignored because every comparison against NaN is false.

Exceptions

InvalidOperationException

Thrown when the input sequence is empty.

Normalize<T>(ReadOnlySpan<T>)

Normalizes a set of values to the range [0, 1]. Allocates and returns a new array.

public static T[] Normalize<T>(ReadOnlySpan<T> values) where T : struct, INumber<T>

Parameters

values ReadOnlySpan<T>

The source values to normalize.

Returns

T[]

A new array of type T containing the normalized values. If all input values are the same, returns an array filled with T.Zero. Returns an empty array when the input is empty.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf>.

Remarks

Normalization scales the values such that the minimum value becomes 0 and the maximum value becomes 1. Empty input yields an empty result rather than throwing.

Normalize<T>(ReadOnlySpan<T>, Span<T>)

Normalizes a set of values to the range [0, 1], writing the result into a pre-allocated destination span. This method avoids internal allocations.

public static void Normalize<T>(ReadOnlySpan<T> values, Span<T> destination) where T : struct, INumber<T>

Parameters

values ReadOnlySpan<T>

The source values to normalize.

destination Span<T>

The span to write the normalized values into. Must have the same length as values.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf>.

Remarks

Normalization scales the values such that the minimum value becomes 0 and the maximum value becomes 1. If all input values are the same, the destination span is filled with T.Zero. Empty input is a no-op rather than an error.

Exceptions

ArgumentException

Thrown if destination length does not match values length.

PopulationExcessKurtosis<T>(ReadOnlySpan<T>)

Calculates the population excess kurtosis.

public static T PopulationExcessKurtosis<T>(ReadOnlySpan<T> values) where T : struct, INumber<T>, IRootFunctions<T>

Parameters

values ReadOnlySpan<T>

The set of values.

Returns

T

The population excess kurtosis of the values.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf> and IRootFunctions<TSelf>.

Remarks

Population excess kurtosis measures the "tailedness" relative to a normal distribution (Kurtosis - 3). Formula: (Sum[(x_i - mean)^4] / n) / variance^2 - 3.

Exceptions

ArgumentException

Thrown when the number of values is less than 4 or if the population variance is effectively zero.

SampleKurtosisG2<T>(ReadOnlySpan<T>)

Calculates the sample excess kurtosis (G2), an unbiased estimator for normal distributions.

public static T SampleKurtosisG2<T>(ReadOnlySpan<T> values) where T : struct, INumber<T>, IRootFunctions<T>

Parameters

values ReadOnlySpan<T>

The sample set of values.

Returns

T

The sample excess kurtosis (G2) of the values.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf> and IRootFunctions<TSelf>.

Remarks

Sample excess kurtosis (G2) is an unbiased estimator for data from a normal distribution. Formula involves terms like n(n+1)/((n-1)(n-2)(n-3)) * Sum[((x_i-mean)/s)^4] and 3(n-1)^2/((n-2)(n-3)), where s is the sample standard deviation. The implementation uses population standard deviation internally and applies adjustment factors. Check implementation for details.

Exceptions

ArgumentException

Thrown when the number of values is less than 4 or if the population standard deviation is effectively zero.

Skewness<T>(ReadOnlySpan<T>)

Calculates a sample skewness estimator (unbiased for normal distribution, G1).

public static T Skewness<T>(ReadOnlySpan<T> values) where T : struct, INumber<T>, IRootFunctions<T>

Parameters

values ReadOnlySpan<T>

The sample set of values.

Returns

T

The sample skewness (G1) of the values. Returns 0 if variance is effectively zero.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf> and IRootFunctions<TSelf>.

Remarks

Skewness measures the asymmetry of the value distribution relative to the mean. Uses the adjusted Fisher-Pearson standardized moment coefficient (G1). Formula: [n / ((n-1)*(n-2))] * Sum[(x_i - mean) / stdDev]^3

Exceptions

ArgumentException

Thrown when the number of values is less than 3.

StandardDeviation<T>(ReadOnlySpan<T>)

Calculates the population standard deviation of a set of values.

public static T StandardDeviation<T>(ReadOnlySpan<T> values) where T : struct, INumber<T>, IRootFunctions<T>

Parameters

values ReadOnlySpan<T>

The set of values.

Returns

T

The population standard deviation of the values. Returns T.Zero if the input span has 0 or 1 elements.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf> and IRootFunctions<TSelf>.

Remarks

Population standard deviation is the square root of the population variance. Standard deviation provides a measure of the spread of values.

Variance<T>(ReadOnlySpan<T>)

Calculates the population variance of a set of values.

public static T Variance<T>(ReadOnlySpan<T> values) where T : struct, INumber<T>

Parameters

values ReadOnlySpan<T>

The set of values.

Returns

T

The population variance of the values. Returns T.Zero if the input span has 0 or 1 elements.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf>.

Remarks

Population variance uses division by N (number of elements). Variance measures the dispersion of a set of values from their mean. For integral numeric types the intermediate squared deviations are accumulated in T and can overflow; use a floating-point element type when values are large.

ZScoreNormalization<T>(ReadOnlySpan<T>)

Performs Z-score normalization on a set of values. Allocates and returns a new array.

public static T[] ZScoreNormalization<T>(ReadOnlySpan<T> values) where T : struct, INumber<T>, IRootFunctions<T>

Parameters

values ReadOnlySpan<T>

The set of values.

Returns

T[]

A new array containing the Z-score normalized values. If all input values are identical, returns an array filled with T.Zero.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf> and IRootFunctions<TSelf>.

Remarks

Z-score normalization transforms the data such that it has a mean of 0 and a population standard deviation of 1. Z = (value - mean) / stdDev

ZScoreNormalization<T>(ReadOnlySpan<T>, Span<T>)

Performs Z-score normalization on a set of values, writing the result into a pre-allocated destination span. This method avoids internal allocations.

public static void ZScoreNormalization<T>(ReadOnlySpan<T> values, Span<T> destination) where T : struct, INumber<T>, IRootFunctions<T>

Parameters

values ReadOnlySpan<T>

The source values to normalize.

destination Span<T>

The span to write the normalized values into. Must have the same length as values.

Type Parameters

T

The numeric type of the values, implementing INumber<TSelf> and IRootFunctions<TSelf>.

Remarks

Z-score normalization transforms the data such that it has a mean of 0 and a population standard deviation of 1. Z = (value - mean) / stdDev. If all input values are identical, the destination span is filled with T.Zero.

Exceptions

ArgumentException

Thrown if destination length does not match values length.