Package io.jenetics.stat
Class Quantile
- java.lang.Object
-
- io.jenetics.stat.Quantile
-
- All Implemented Interfaces:
DoubleConsumer
public class Quantile extends Object implements DoubleConsumer
Implementation of the quantile estimation algorithm published byRaj JAIN and Imrich CHLAMTAC: The P2 Algorithm for Dynamic Calculation of Quantiles and Histograms Without Storing Observations
[Communications of the ACM; October 1985, Volume 28, Number 10]This class is designed to work with (though does not require) streams. For example, you can compute the quantile with:
final DoubleStream stream = ... final Quantile quantile = stream.collect( () -> new Quantile(0.23), Quantile::accept, Quantile::combine );
- Since:
- 1.0
- Version:
- 6.0
- See Also:
- Wikipedia: Quantile
- Implementation Note:
- This implementation is not thread safe. However, it is safe to use on a
parallel stream, because the parallel implementation of
Stream.collect()
provides the necessary partitioning, isolation, and merging of results for safe and efficient parallel execution. Using this class in thecollect
method of an parallel stream can lead to an reduced accuracy of the quantile value. Since this implementation is an estimation algorithm, combining the estimations will only work for large streams (size >> 1000
).
-
-
Constructor Summary
Constructors Constructor Description Quantile(double quantile)
Create a new quantile accumulator with the given value.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
accept(double value)
Quantile
combine(Quantile other)
Combine twoQuantile
objects.long
count()
Return the number of samples the quantile value was calculated of.double
quantile()
Return the quantilethis
object has been parametrized with.void
reset()
Reset this object to its initial state.boolean
sameState(Quantile other)
Compares the state of twoQuantile
objects.static <T> Collector<T,?,Quantile>
toMedian(ToDoubleFunction<? super T> mapper)
Return aCollector
which applies an double-producing mapping function to each input element, and returns the median for the resulting values.static <T> Collector<T,?,Quantile>
toQuantile(double quantile, ToDoubleFunction<? super T> mapper)
Return aCollector
which applies an double-producing mapping function to each input element, and returns quantiles for the resulting values.String
toString()
double
value()
Return the computed quantile value.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface java.util.function.DoubleConsumer
andThen
-
-
-
-
Constructor Detail
-
Quantile
public Quantile(double quantile)
Create a new quantile accumulator with the given value.- Parameters:
quantile
- the wished quantile value.- Throws:
IllegalArgumentException
- if thequantile
is not in the range[0, 1]
.
-
-
Method Detail
-
reset
public void reset()
Reset this object to its initial state.
-
quantile
public double quantile()
Return the quantilethis
object has been parametrized with.- Returns:
- the quantile
this
object has been parametrized with - Since:
- 3.1
-
value
public double value()
Return the computed quantile value.- Returns:
- the quantile value.
-
count
public long count()
Return the number of samples the quantile value was calculated of.- Returns:
- the number of samples the quantile value was calculated of
-
accept
public void accept(double value)
- Specified by:
accept
in interfaceDoubleConsumer
-
combine
public Quantile combine(Quantile other)
Combine twoQuantile
objects.- Parameters:
other
- the otherQuantile
object to combine- Returns:
this
- Throws:
NullPointerException
- if theother
object isnull
.IllegalArgumentException
- if thequantile()
of theother
object differs fromthis
one.- Since:
- 3.1
-
sameState
public boolean sameState(Quantile other)
Compares the state of twoQuantile
objects. This is a replacement for theObject.equals(Object)
which is not advisable to implement for this mutable object. If two object have the same state, it has still the same state when updated with the same value.final Quantile q1 = ...; final Quantile q2 = ...; if (q1.sameState(q2)) { final double value = random.nextDouble(); q1.accept(value); q2.accept(value); assert q1.sameState(q2); assert q2.sameState(q1); assert q1.sameState(q1); }
- Parameters:
other
- the other object for the test- Returns:
true
thethis
and theother
objects have the same state,false
otherwise- Since:
- 3.7
-
toQuantile
public static <T> Collector<T,?,Quantile> toQuantile(double quantile, ToDoubleFunction<? super T> mapper)
Return aCollector
which applies an double-producing mapping function to each input element, and returns quantiles for the resulting values.final Stream<SomeObject> stream = ... final Quantile quantile = stream .collect(toQuantile(0.25, v -> v.doubleValue()));
- Type Parameters:
T
- the type of the input elements- Parameters:
quantile
- the wished quantile value.mapper
- a mapping function to apply to each element- Returns:
- a
Collector
implementing the quantiles reduction - Throws:
NullPointerException
- if the givenmapper
isnull
IllegalArgumentException
- if thequantile
is not in the range[0, 1]
.
-
toMedian
public static <T> Collector<T,?,Quantile> toMedian(ToDoubleFunction<? super T> mapper)
Return aCollector
which applies an double-producing mapping function to each input element, and returns the median for the resulting values.final Stream<SomeObject> stream = ... final Quantile median = stream.collect(toMedian(v -> v.doubleValue()));
- Type Parameters:
T
- the type of the input elements- Parameters:
mapper
- a mapping function to apply to each element- Returns:
- a
Collector
implementing the quantiles reduction - Throws:
NullPointerException
- if the givenmapper
isnull
-
-