diff --git a/src/Numerics/Statistics/ArrayStatistics.cs b/src/Numerics/Statistics/ArrayStatistics.cs index 76152f3e..980dd472 100644 --- a/src/Numerics/Statistics/ArrayStatistics.cs +++ b/src/Numerics/Statistics/ArrayStatistics.cs @@ -106,69 +106,69 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the unbiased population or sample variance from the unsorted data array. - /// On a dataset of size N will use an N-1 normalizer - /// Returns NaN if data is empty or any entry is NaN. + /// Estimates the unbiased population variance from the provided samples as unsorted array. + /// On a dataset of size N will use an N-1 normalizer. + /// Returns NaN if data has less than two entries or if any entry is NaN. /// - /// Sample array, no sorting is assumed. - public static double Variance(double[] data) + /// Sample array, no sorting is assumed. + public static double Variance(double[] samples) { - if (data == null) throw new ArgumentNullException("data"); - if (data.Length <= 1) return double.NaN; + if (samples == null) throw new ArgumentNullException("samples"); + if (samples.Length <= 1) return double.NaN; double variance = 0; - double t = data[0]; - for (int i = 1; i < data.Length; i++) + double t = samples[0]; + for (int i = 1; i < samples.Length; i++) { - t += data[i]; - double diff = ((i + 1)*data[i]) - t; + t += samples[i]; + double diff = ((i + 1)*samples[i]) - t; variance += (diff*diff)/((i + 1)*i); } - return variance/(data.Length - 1); + return variance/(samples.Length - 1); } /// - /// Estimates the unbiased population or sample standard deviation from the unsorted data array. - /// On a dataset of size N will use an N-1 normalizer - /// Returns NaN if data is empty or any entry is NaN. + /// Estimates the unbiased population standard deviation from the provided samples as unsorted array. + /// On a dataset of size N will use an N-1 normalizer. + /// Returns NaN if data has less than two entries or if any entry is NaN. /// - /// Sample array, no sorting is assumed. - public static double StandardDeviation(double[] data) + /// Sample array, no sorting is assumed. + public static double StandardDeviation(double[] samples) { - return Math.Sqrt(Variance(data)); + return Math.Sqrt(Variance(samples)); } /// - /// Estimates the biased population variance from the unsorted data array. - /// On a dataset of size N will use an N normalizer - /// Returns NaN if data is empty or any entry is NaN. + /// Evaluates the biased population variance from the provided full population as unsorted array. + /// On a dataset of size N will use an N normalizer. + /// Returns NaN if data is empty or if any entry is NaN. /// - /// Sample array, no sorting is assumed. - public static double PopulationVariance(double[] data) + /// Sample array, no sorting is assumed. + public static double PopulationVariance(double[] population) { - if (data == null) throw new ArgumentNullException("data"); - if (data.Length == 0) return double.NaN; + if (population == null) throw new ArgumentNullException("population"); + if (population.Length == 0) return double.NaN; double variance = 0; - double t = data[0]; - for (int i = 1; i < data.Length; i++) + double t = population[0]; + for (int i = 1; i < population.Length; i++) { - t += data[i]; - double diff = ((i + 1)*data[i]) - t; + t += population[i]; + double diff = ((i + 1)*population[i]) - t; variance += (diff*diff)/((i + 1)*i); } - return variance/data.Length; + return variance/population.Length; } /// - /// Estimates the biased population standard deviation from the unsorted data array. - /// On a dataset of size N will use an N normalizer - /// Returns NaN if data is empty or any entry is NaN. + /// Evaluates the biased population standard deviation from the provided full population as unsorted array. + /// On a dataset of size N will use an N normalizer. + /// Returns NaN if data is empty or if any entry is NaN. /// - /// Sample array, no sorting is assumed. - public static double PopulationStandardDeviation(double[] data) + /// Sample array, no sorting is assumed. + public static double PopulationStandardDeviation(double[] population) { - return Math.Sqrt(PopulationVariance(data)); + return Math.Sqrt(PopulationVariance(population)); } /// diff --git a/src/Numerics/Statistics/Statistics.cs b/src/Numerics/Statistics/Statistics.cs index b0fd1638..fdaf0069 100644 --- a/src/Numerics/Statistics/Statistics.cs +++ b/src/Numerics/Statistics/Statistics.cs @@ -41,6 +41,7 @@ namespace MathNet.Numerics.Statistics { /// /// Returns the minimum value in the sample data. + /// Returns NaN if data is empty or if any entry is NaN. /// /// The sample data. /// The minimum value in the sample data. @@ -53,6 +54,8 @@ namespace MathNet.Numerics.Statistics } /// /// Returns the minimum value in the sample data. + /// Returns NaN if data is empty or if any entry is NaN. + /// Null-entries are ignored. /// /// The sample data. /// The minimum value in the sample data. @@ -64,6 +67,7 @@ namespace MathNet.Numerics.Statistics /// /// Returns the maximum value in the sample data. + /// Returns NaN if data is empty or if any entry is NaN. /// /// The sample data. /// The maximum value in the sample data. @@ -77,6 +81,8 @@ namespace MathNet.Numerics.Statistics /// /// Returns the maximum value in the sample data. + /// Returns NaN if data is empty or if any entry is NaN. + /// Null-entries are ignored. /// /// The sample data. /// The maximum value in the sample data. @@ -88,6 +94,7 @@ namespace MathNet.Numerics.Statistics /// /// Estimates the sample mean. + /// Returns NaN if data is empty or if any entry is NaN. /// /// The data to calculate the mean of. /// The mean of the sample. @@ -101,6 +108,8 @@ namespace MathNet.Numerics.Statistics /// /// Estimates the sample mean. + /// Returns NaN if data is empty or if any entry is NaN. + /// Null-entries are ignored. /// /// The data to calculate the mean of. /// The mean of the sample. @@ -111,99 +120,111 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the unbiased population (sample) variance estimator (on a dataset of size N will use an N-1 normalizer). + /// Estimates the unbiased population variance from the provided samples. + /// On a dataset of size N will use an N-1 normalizer. + /// Returns NaN if data has less than two entries or if any entry is NaN. /// - /// The data to calculate the variance of. - /// The unbiased population variance of the sample. - public static double Variance(this IEnumerable data) + /// A subset of samples, sampled from the full population. + public static double Variance(this IEnumerable samples) { - var array = data as double[]; + var array = samples as double[]; return array != null ? ArrayStatistics.Variance(array) - : StreamingStatistics.Variance(data); + : StreamingStatistics.Variance(samples); } /// - /// Estimates the unbiased population (sample) variance estimator (on a dataset of size N will use an N-1 normalizer) for nullable data. + /// Estimates the unbiased population variance from the provided samples. + /// On a dataset of size N will use an N-1 normalizer. + /// Returns NaN if data has less than two entries or if any entry is NaN. + /// Null-entries are ignored. /// - /// The data to calculate the variance of. - /// The population variance of the sample. - public static double Variance(this IEnumerable data) + /// A subset of samples, sampled from the full population. + public static double Variance(this IEnumerable samples) { - if (data == null) throw new ArgumentNullException("data"); - return StreamingStatistics.Variance(data.Where(d => d.HasValue).Select(d => d.Value)); + if (samples == null) throw new ArgumentNullException("samples"); + return StreamingStatistics.Variance(samples.Where(d => d.HasValue).Select(d => d.Value)); } /// - /// Estimates the biased population variance estimator (on a dataset of size N will use an N normalizer). + /// Evaluates the biased population variance from the provided full population. + /// On a dataset of size N will use an N normalizer. + /// Returns NaN if data is empty or if any entry is NaN. /// - /// The data to calculate the variance of. - /// The biased population variance of the sample. - public static double PopulationVariance(this IEnumerable data) + /// The full population data. + public static double PopulationVariance(this IEnumerable population) { - var array = data as double[]; + var array = population as double[]; return array != null ? ArrayStatistics.PopulationVariance(array) - : StreamingStatistics.PopulationVariance(data); + : StreamingStatistics.PopulationVariance(population); } /// - /// Estimates the biased population variance estimator (on a dataset of size N will use an N normalizer) for nullable data. + /// Evaluates the biased population variance from the provided full population. + /// On a dataset of size N will use an N normalizer. + /// Returns NaN if data is empty or if any entry is NaN. + /// Null-entries are ignored. /// - /// The data to calculate the variance of. - /// The population variance of the sample. - public static double PopulationVariance(this IEnumerable data) + /// The full population data. + public static double PopulationVariance(this IEnumerable population) { - if (data == null) throw new ArgumentNullException("data"); - return StreamingStatistics.PopulationVariance(data.Where(d => d.HasValue).Select(d => d.Value)); + if (population == null) throw new ArgumentNullException("population"); + return StreamingStatistics.PopulationVariance(population.Where(d => d.HasValue).Select(d => d.Value)); } /// - /// Estimates the unbiased sample standard deviation (on a dataset of size N will use an N-1 normalizer). + /// Estimates the unbiased population standard deviation from the provided samples. + /// On a dataset of size N will use an N-1 normalizer. + /// Returns NaN if data has less than two entries or if any entry is NaN. /// - /// The data to calculate the standard deviation of. - /// The standard deviation of the sample. - public static double StandardDeviation(this IEnumerable data) + /// A subset of samples, sampled from the full population. + public static double StandardDeviation(this IEnumerable samples) { - var array = data as double[]; + var array = samples as double[]; return array != null ? ArrayStatistics.StandardDeviation(array) - : StreamingStatistics.StandardDeviation(data); + : StreamingStatistics.StandardDeviation(samples); } /// - /// Estimates the unbiased sample standard deviation (on a dataset of size N will use an N-1 normalizer). + /// Estimates the unbiased population standard deviation from the provided samples. + /// On a dataset of size N will use an N-1 normalizer. + /// Returns NaN if data has less than two entries or if any entry is NaN. + /// Null-entries are ignored. /// - /// The data to calculate the standard deviation of. - /// The standard deviation of the sample. - public static double StandardDeviation(this IEnumerable data) + /// A subset of samples, sampled from the full population. + public static double StandardDeviation(this IEnumerable samples) { - if (data == null) throw new ArgumentNullException("data"); - return StreamingStatistics.StandardDeviation(data.Where(d => d.HasValue).Select(d => d.Value)); + if (samples == null) throw new ArgumentNullException("samples"); + return StreamingStatistics.StandardDeviation(samples.Where(d => d.HasValue).Select(d => d.Value)); } /// - /// Estimates the biased sample standard deviation (on a dataset of size N will use an N normalizer). + /// Evaluates the biased population standard deviation from the provided full population. + /// On a dataset of size N will use an N normalizer. + /// Returns NaN if data is empty or if any entry is NaN. /// - /// The data to calculate the standard deviation of. - /// The standard deviation of the sample. - public static double PopulationStandardDeviation(this IEnumerable data) + /// The full population data. + public static double PopulationStandardDeviation(this IEnumerable population) { - var array = data as double[]; + var array = population as double[]; return array != null ? ArrayStatistics.PopulationStandardDeviation(array) - : StreamingStatistics.PopulationStandardDeviation(data); + : StreamingStatistics.PopulationStandardDeviation(population); } /// - /// Estimates the biased sample standard deviation (on a dataset of size N will use an N normalizer). + /// Evaluates the biased population standard deviation from the provided full population. + /// On a dataset of size N will use an N normalizer. + /// Returns NaN if data is empty or if any entry is NaN. + /// Null-entries are ignored. /// - /// The data to calculate the standard deviation of. - /// The standard deviation of the sample. - public static double PopulationStandardDeviation(this IEnumerable data) + /// The full population data. + public static double PopulationStandardDeviation(this IEnumerable population) { - if (data == null) throw new ArgumentNullException("data"); - return StreamingStatistics.PopulationStandardDeviation(data.Where(d => d.HasValue).Select(d => d.Value)); + if (population == null) throw new ArgumentNullException("population"); + return StreamingStatistics.PopulationStandardDeviation(population.Where(d => d.HasValue).Select(d => d.Value)); } /// @@ -290,7 +311,7 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the empiric inverse CDF at tau from the provided samples. + /// Estimates the empirical inverse CDF at tau from the provided samples. /// /// The data sample sequence. /// Quantile selector, between 0.0 and 1.0 (inclusive). @@ -302,7 +323,7 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the empiric inverse CDF at tau from the provided samples. + /// Estimates the empirical inverse CDF at tau from the provided samples. /// /// The data sample sequence. /// Quantile selector, between 0.0 and 1.0 (inclusive). @@ -314,7 +335,7 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the empiric inverse CDF at tau from the provided samples. + /// Estimates the empirical inverse CDF at tau from the provided samples. /// /// The data sample sequence. public static Func InverseCDFFunc(this IEnumerable data) @@ -326,7 +347,7 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the empiric inverse CDF at tau from the provided samples. + /// Estimates the empirical inverse CDF at tau from the provided samples. /// /// The data sample sequence. public static Func InverseCDFFunc(this IEnumerable data) diff --git a/src/Numerics/Statistics/StreamingStatistics.cs b/src/Numerics/Statistics/StreamingStatistics.cs index f264be90..e18bec7b 100644 --- a/src/Numerics/Statistics/StreamingStatistics.cs +++ b/src/Numerics/Statistics/StreamingStatistics.cs @@ -107,19 +107,19 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the unbiased population or sample variance from the enumerable, in a single pass without memoization. - /// On a dataset of size N will use an N-1 normalizer - /// Returns NaN if data is empty or any entry is NaN. + /// Estimates the unbiased population variance from the provided samples as enumerable sequence, in a single pass without memoization. + /// On a dataset of size N will use an N-1 normalizer. + /// Returns NaN if data has less than two entries or if any entry is NaN. /// - /// Sample stream, no sorting is assumed. - public static double Variance(IEnumerable stream) + /// Sample stream, no sorting is assumed. + public static double Variance(IEnumerable samples) { - if (stream == null) throw new ArgumentNullException("stream"); + if (samples == null) throw new ArgumentNullException("samples"); double variance = 0; double t = 0; ulong j = 0; - using (var iterator = stream.GetEnumerator()) + using (var iterator = samples.GetEnumerator()) { if (iterator.MoveNext()) { @@ -140,30 +140,30 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the unbiased population or sample standard deviation from the enumerable, in a single pass without memoization. - /// On a dataset of size N will use an N-1 normalizer - /// Returns NaN if data is empty or any entry is NaN. + /// Estimates the unbiased population standard deviation from the provided samples as enumerable sequence, in a single pass without memoization. + /// On a dataset of size N will use an N-1 normalizer. + /// Returns NaN if data has less than two entries or if any entry is NaN. /// - /// Sample stream, no sorting is assumed. - public static double StandardDeviation(IEnumerable stream) + /// Sample stream, no sorting is assumed. + public static double StandardDeviation(IEnumerable samples) { - return Math.Sqrt(Variance(stream)); + return Math.Sqrt(Variance(samples)); } /// - /// Estimates the biased population variance from the enumerable, in a single pass without memoization. - /// On a dataset of size N will use an N normalizer - /// Returns NaN if data is empty or any entry is NaN. + /// Evaluates the biased population variance from the provided full population as enumerable sequence, in a single pass without memoization. + /// On a dataset of size N will use an N normalizer. + /// Returns NaN if data is empty or if any entry is NaN. /// - /// Sample stream, no sorting is assumed. - public static double PopulationVariance(IEnumerable stream) + /// Sample stream, no sorting is assumed. + public static double PopulationVariance(IEnumerable population) { - if (stream == null) throw new ArgumentNullException("stream"); + if (population == null) throw new ArgumentNullException("population"); double variance = 0; double t = 0; ulong j = 0; - using (var iterator = stream.GetEnumerator()) + using (var iterator = population.GetEnumerator()) { if (iterator.MoveNext()) { @@ -184,14 +184,14 @@ namespace MathNet.Numerics.Statistics } /// - /// Estimates the biased population standard deviation from the enumerable, in a single pass without memoization. - /// On a dataset of size N will use an N normalizer - /// Returns NaN if data is empty or any entry is NaN. + /// Evaluates the biased population standard deviation from the provided full population as enumerable sequence, in a single pass without memoization. + /// On a dataset of size N will use an N normalizer. + /// Returns NaN if data is empty or if any entry is NaN. /// - /// Sample stream, no sorting is assumed. - public static double PopulationStandardDeviation(IEnumerable stream) + /// Sample stream, no sorting is assumed. + public static double PopulationStandardDeviation(IEnumerable population) { - return Math.Sqrt(PopulationVariance(stream)); + return Math.Sqrt(PopulationVariance(population)); } } }