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.

Support for long arrays

The result on long values can be returned as a double or a long using a StatisticResult.

The double result is the closest representable value following floating-point rounding rules. This may be outside the range defined by the minimum and maximum of the input array following rounding to a 53-bit floating point representation. For example the median of an array containing only Long.MAX_VALUE as a double is 2⁶³, which is the closest representation of 2⁶³ - 1.

The long result is returned using the nearest whole number. In the event of ties the result is rounded towards positive infinity. For example the median of [2, 3] is 3, and of [-2, -3] is -2. This value will always be within the range defined by the minimum and maximum of the input array. Due to interpolation it may be a value not observed in the input values.

If the array length n is zero the result as a double is NaN and the result as a long will raise an ArithmeticException.

Since:

1.1

See Also:

• with(NaNPolicy)
• Median (Wikipedia)

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.
private StatisticResult	compute(long[] 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.
StatisticResult	evaluate(long[] 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.
StatisticResult	evaluateRange(long[] 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.

• Copy = false
• NaN policy = include

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(boolean)
• with(NaNPolicy)

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:

• with(NaNPolicy)

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:

• with(NaNPolicy)

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

evaluate

public StatisticResult evaluate(long[] values)

Evaluate the median.

If the input length is even the result requires interpolation of two values. The returned median will interpolate the double or long result on demand. This is more efficient when only one result is required. Consumers of the result should store the appropriate evaluated value if repeated use is required.

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

Parameters:

values - Values.

Returns:

the median

Since:

1.3

evaluateRange

public StatisticResult evaluateRange(long[] values,
 int from,
 int to)

Evaluate the median of the specified range.

If the input sub-range length is even the result requires interpolation of two values. The returned median will interpolate the double or long result on demand. This is more efficient when only one result is required. Consumers of the result should store the appropriate evaluated value if repeated use is required.

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

compute

private StatisticResult compute(long[] 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