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

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)

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

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

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.

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.

Exceptions

InvalidOperationException

Thrown when the input sequence is empty.

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. Requires values to be non-empty.

Exceptions

ArgumentException

Thrown if destination length does not match values length.

InvalidOperationException

Thrown when the input sequence values is empty.

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.

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 the standard deviation is effectively zero, 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 the standard deviation is effectively zero, the destination span is filled with T.Zero.

Exceptions

ArgumentException

Thrown if destination length does not match values length.