Class Stats

java.lang.Object
com.quantfinlib.stats.Stats
public final class Stats extends Object
Descriptive statistics on primitive arrays, with every convention named.
  • Variance and standard deviation come in two explicit forms: sample divides the sum of squared deviations by n - 1 (the unbiased estimator of the variance) and population divides by n (the second central moment of the data).
  • Quantiles follow Hyndman and Fan (1996), "Sample quantiles in statistical packages", The American Statistician 50(4), 361-365. quantile(double[], double) is their type 7 (the default of R and NumPy): with h = (n - 1) p, Q(p) = x[floor h] + (h - floor h)(x[floor h + 1] - x[floor h]) on the order statistics x[0..n-1]. quantileType1Sorted(double[], double) is their type 1, the inverse of the empirical CDF: Q(p) = x[ceil(n p) - 1] (x[0] at p = 0).
  • The median is the type 7 quantile at p = 0.5, which equals the middle order statistic for odd n and the mean of the two middle ones for even n.
  • Ranks are 1-based midranks: tied values share the average of the positions they occupy (Kendall and Gibbons 1990, Rank Correlation Methods, 5th ed., chapter 3).

Edge cases: an empty input gives NaN for the mean, the quantiles and the median; fewer than two points gives NaN for the sample variance and standard deviation. NaN elements propagate through the moments (the result is NaN) and sort above every number in the quantile functions, as Double.compare(double, double) orders them. A probability outside [0, 1] or a NaN probability is rejected with IllegalArgumentException.

Example: for {1, 2, 3, 4}, mean is 2.5, sampleVariance is 5/3, populationVariance is 1.25, quantile(v, 0.25) is 1.75 (type 7) and quantileType1Sorted(v, 0.25) is 1.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    kurtosis(double[] v)
    Population kurtosis m4 / m2^2 (3 for a normal distribution, not excess); 0 when the data have no dispersion.
    static double
    mean(double[] v)
    Arithmetic mean; NaN for an empty array.
    static double
    mean(double[] v, int from, int to)
    Arithmetic mean of v[from, to); NaN for an empty range.
    static double
    median(double[] values)
    Median (type 7 quantile at 0.5); copies the input; NaN when empty.
    static double
    pearson(double[] a, double[] b)
    Pearson product-moment correlation: the sample covariance over the product of the sample standard deviations (the n - 1 factors cancel).
    static double
    pearsonOrZero(double[] a, double[] b)
    Pearson correlation with a zero convention.
    static double
    populationStdDev(double[] v)
    Square root of populationVariance(double[]).
    static double
    populationStdDev(double[] v, int from, int to)
    Square root of populationVariance(double[], int, int).
    static double
    populationVariance(double[] v)
    Population variance, n denominator; NaN for an empty array.
    static double
    populationVariance(double[] v, int from, int to)
    Population variance of v[from, to); NaN for an empty range.
    static double
    quantile(double[] values, double p)
    Hyndman-Fan type 7 quantile of an unsorted sample; copies and sorts the input, which is not modified.
    static double
    quantileSorted(double[] sorted, double p)
    Hyndman-Fan type 7 quantile of a sample already sorted ascending (linear interpolation between order statistics at h = (n - 1) p).
    static double
    quantileType1Sorted(double[] sorted, double p)
    Hyndman-Fan type 1 quantile (inverse empirical CDF, no interpolation) of a sample already sorted ascending: the smallest order statistic x with F_n(x) >= p.
    static double[]
    ranks(double[] values)
    1-based midranks: tied values share the average of their positions.
    static double
    sampleCovariance(double[] a, double[] b)
    Sample covariance of two equal-length series, n - 1 denominator.
    static double
    sampleStdDev(double[] v)
    Square root of sampleVariance(double[]).
    static double
    sampleStdDev(double[] v, int from, int to)
    Square root of sampleVariance(double[], int, int).
    static double
    sampleVariance(double[] v)
    Sample variance, n - 1 denominator; NaN for fewer than two points.
    static double
    sampleVariance(double[] v, int from, int to)
    Sample variance of v[from, to); NaN for fewer than two points.
    static double
    skewness(double[] v)
    Population skewness m3 / m2^1.5; 0 when the data have no dispersion.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • mean

      public static double mean(double[] v)
      Arithmetic mean; NaN for an empty array.

    • mean

      public static double mean(double[] v, int from, int to)
      Arithmetic mean of v[from, to); NaN for an empty range.

    • sampleVariance

      public static double sampleVariance(double[] v)
      Sample variance, n - 1 denominator; NaN for fewer than two points.

    • sampleVariance

      public static double sampleVariance(double[] v, int from, int to)
      Sample variance of v[from, to); NaN for fewer than two points.

    • populationVariance

      public static double populationVariance(double[] v)
      Population variance, n denominator; NaN for an empty array.

    • populationVariance

      public static double populationVariance(double[] v, int from, int to)
      Population variance of v[from, to); NaN for an empty range.

    • sampleStdDev

      public static double sampleStdDev(double[] v)
      Square root of sampleVariance(double[]).

    • sampleStdDev

      public static double sampleStdDev(double[] v, int from, int to)
      Square root of sampleVariance(double[], int, int).

    • populationStdDev

      public static double populationStdDev(double[] v)
      Square root of populationVariance(double[]).

    • populationStdDev

      public static double populationStdDev(double[] v, int from, int to)
      Square root of populationVariance(double[], int, int).

    • sampleCovariance

      public static double sampleCovariance(double[] a, double[] b)
      Sample covariance of two equal-length series, n - 1 denominator.
      Throws:
      IllegalArgumentException - if the lengths differ or there are fewer than two observations

    • pearson

      public static double pearson(double[] a, double[] b)
      Pearson product-moment correlation: the sample covariance over the product of the sample standard deviations (the n - 1 factors cancel). NaN when either series has zero dispersion, where the coefficient is undefined.
      Throws:
      IllegalArgumentException - if the lengths differ or there are fewer than two observations

    • quantile

      public static double quantile(double[] values, double p)
      Hyndman-Fan type 7 quantile of an unsorted sample; copies and sorts the input, which is not modified.
      Parameters:
      values - the sample
      p - probability in [0, 1]
      Returns:
      the quantile, NaN for an empty array

    • quantileSorted

      public static double quantileSorted(double[] sorted, double p)
      Hyndman-Fan type 7 quantile of a sample already sorted ascending (linear interpolation between order statistics at h = (n - 1) p).
      Parameters:
      sorted - the sample, ascending
      p - probability in [0, 1]
      Returns:
      the quantile, NaN for an empty array

    • quantileType1Sorted

      public static double quantileType1Sorted(double[] sorted, double p)
      Hyndman-Fan type 1 quantile (inverse empirical CDF, no interpolation) of a sample already sorted ascending: the smallest order statistic x with F_n(x) >= p.
      Parameters:
      sorted - the sample, ascending
      p - probability in [0, 1]
      Returns:
      the quantile, NaN for an empty array

    • median

      public static double median(double[] values)
      Median (type 7 quantile at 0.5); copies the input; NaN when empty.

    • ranks

      public static double[] ranks(double[] values)
      1-based midranks: tied values share the average of their positions. Values are ordered as Double.compare(double, double) orders them except that -0.0 and 0.0 tie; NaN entries rank above every number, each NaN on its own rank in input order.

      Example: {10, 20, 20, 5} ranks to {2, 3.5, 3.5, 1}.

      Parameters:
      values - the sample (not modified)
      Returns:
      a new array of ranks aligned with values

    • pearsonOrZero

      public static double pearsonOrZero(double[] a, double[] b)
      Pearson correlation with a zero convention. Unlike pearson(double[], double[]), which returns NaN, this returns 0 when either series has zero dispersion; callers such as risk.CorrelationMatrix rely on that convention.
      Since:
      2.4.0

    • skewness

      public static double skewness(double[] v)
      Population skewness m3 / m2^1.5; 0 when the data have no dispersion.
      Since:
      2.4.0

    • kurtosis

      public static double kurtosis(double[] v)
      Population kurtosis m4 / m2^2 (3 for a normal distribution, not excess); 0 when the data have no dispersion.
      Since:
      2.4.0