Class Median

java.lang.Object
org.apache.commons.statistics.descriptive.Median
public final class Median extends Object
Returns the median of the available values.

For values of length n, let k = n / 2:

  • The result is NaN if n = 0.
  • The result is values[k] if n is odd.
  • The result is (values[k - 1] + values[k]) / 2 if n is even.

This implementation respects the ordering imposed by Double.compare(double, double) for NaN values. If a NaN occurs in the selected positions in the fully sorted values then the result is NaN.

The NaNPolicy can be used to change the behaviour on NaN values.

Instances of this class are immutable and thread-safe.

Since:
1.1
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final boolean
    copy
    Flag to indicate if the data should be copied.
    private static final Median
    DEFAULT
    Default instance.
    private final NaNPolicy
    nanPolicy
    NaN policy for floating point data.
    private final NaNTransformer
    nanTransformer
    Transformer for NaN data.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Median(boolean copy, NaNPolicy nanPolicy)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    private double
    compute(double[] values, int from, int to)
    Compute the median of the specified range.
    private double
    compute(int[] values, int from, int to)
    Compute the median of the specified range.
    double
    evaluate(double[] values)
    Evaluate the median.
    double
    evaluate(int[] values)
    Evaluate the median.
    double
    evaluateRange(double[] values, int from, int to)
    Evaluate the median of the specified range.
    double
    evaluateRange(int[] values, int from, int to)
    Evaluate the median of the specified range.
    Median
    with(NaNPolicy v)
    Return an instance with the configured NaNPolicy.
    Median
    withCopy(boolean v)
    Return an instance with the configured copy behaviour.
    static Median
    withDefaults()
    Return a new instance with the default options.

    Methods inherited from class Object

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

  • Field Details

    • DEFAULT

      private static final Median DEFAULT
      Default instance.

    • copy

      private final boolean copy
      Flag to indicate if the data should be copied.

    • nanPolicy

      private final NaNPolicy nanPolicy
      NaN policy for floating point data.

    • nanTransformer

      private final NaNTransformer nanTransformer
      Transformer for NaN data.

  • Constructor Details

    • Median

      private Median(boolean copy, NaNPolicy nanPolicy)
      Parameters:
      copy - Flag to indicate if the data should be copied.
      nanPolicy - NaN policy.

  • Method Details

    • withDefaults

      public static Median withDefaults()
      Return a new instance with the default options.

      Note: The default options configure for processing in-place and including NaN values in the data. This is the most efficient mode and has the smallest memory consumption.

      Returns:
      the median implementation
      See Also:

    • withCopy

      public Median withCopy(boolean v)
      Return an instance with the configured copy behaviour. If false then the input array will be modified by the call to evaluate the median; otherwise the computation uses a copy of the data.
      Parameters:
      v - Value.
      Returns:
      an instance

    • with

      public Median with(NaNPolicy v)
      Return an instance with the configured NaNPolicy.

      Note: This implementation respects the ordering imposed by Double.compare(double, double) for NaN values: NaN is considered greater than all other values, and all NaN values are equal. The NaNPolicy changes the computation of the statistic in the presence of NaN values.

      • NaNPolicy.INCLUDE: NaN values are moved to the end of the data; the size of the data includes the NaN values and the median will be NaN if any value used for median interpolation is NaN.
      • NaNPolicy.EXCLUDE: NaN values are moved to the end of the data; the size of the data excludes the NaN values and the median will never be NaN for non-zero size. If all data are NaN then the size is zero and the result is NaN.
      • NaNPolicy.ERROR: An exception is raised if the data contains NaN values.

      Note that the result is identical for all policies if no NaN values are present.

      Parameters:
      v - Value.
      Returns:
      an instance

    • evaluate

      public double evaluate(double[] values)
      Evaluate the median.

      Note: This method may partially sort the input values if not configured to copy the input data.

      Parameters:
      values - Values.
      Returns:
      the median
      Throws:
      IllegalArgumentException - if the values contain NaN and the configuration is NaNPolicy.ERROR
      See Also:

    • evaluateRange

      public double evaluateRange(double[] values, int from, int to)
      Evaluate the median of the specified range.

      Note: This method may partially sort the input values if not configured to copy the input data.

      Parameters:
      values - Values.
      from - Inclusive start of the range.
      to - Exclusive end of the range.
      Returns:
      the median
      Throws:
      IllegalArgumentException - if the values contain NaN and the configuration is NaNPolicy.ERROR
      IndexOutOfBoundsException - if the sub-range is out of bounds
      Since:
      1.2
      See Also:

    • compute

      private double compute(double[] values, int from, int to)
      Compute the median of the specified range.
      Parameters:
      values - Values.
      from - Inclusive start of the range.
      to - Exclusive end of the range.
      Returns:
      the median

    • evaluate

      public double evaluate(int[] values)
      Evaluate the median.

      Note: This method may partially sort the input values if not configured to copy the input data.

      Parameters:
      values - Values.
      Returns:
      the median

    • evaluateRange

      public double evaluateRange(int[] values, int from, int to)
      Evaluate the median of the specified range.

      Note: This method may partially sort the input values if not configured to copy the input data.

      Parameters:
      values - Values.
      from - Inclusive start of the range.
      to - Exclusive end of the range.
      Returns:
      the median
      Throws:
      IndexOutOfBoundsException - if the sub-range is out of bounds
      Since:
      1.2

    • compute

      private double compute(int[] values, int from, int to)
      Compute the median of the specified range.
      Parameters:
      values - Values.
      from - Inclusive start of the range.
      to - Exclusive end of the range.
      Returns:
      the median