PercentileDocs

The Percentile Operation

Computes the given percentile of values: the value below which the given percentage of the sorted values falls. This is also called the "centile", or the 100-quantile.

The 25th percentile is also known as the first quartile (Q1), the 50th percentile as the median or second quartile (Q2), and the 75th percentile as the third quartile (Q3).

Only self-comparable values are supported: values of a type T : Comparable<T> that are mutually comparable (like strings, primitive numbers, or dates). This includes all primitive number types, but no mix of different number types, which would result in a ClassCastException.

null values in the input are always ignored.

If the input contains NaN values, the result will be NaN, unless skipNaN is set to true.

For primitive numbers, the resulting percentile is a Double, interpolated between the values using quantile estimation method R8. Converting Long values to Double may lose precision for very large values. For all other self-comparable values, the resulting percentile is selected from the values using quantile estimation method R3, so it has the same type as those values.

Currently, only the default quantile estimation methods can be used. In the future, it might become possible to choose a different one, see #1121.

For more information about the resulting types: See "percentile Type Conversion" on the documentation website.

Big numbers (BigInteger, BigDecimal) are not explicitly supported. They are self-comparable, so some overloads select a value without interpolating it, while others throw an exception at runtime. Don't rely on this; convert them to a primitive number type first.

Percentile Modes

Depending on what exactly you want the percentile of, there are several modes. They are shown here for DataFrame, but they exist for the other receivers too:

• percentile(percentile) — the percentile of each suitable column separately.

• percentile(percentile) { columns } — a single percentile of all values in all selected columns.

• percentileFor(percentile) { columns } — the percentile of each selected column separately.

• percentileOf(percentile) { expression } — the percentile of the values that the given expression returns for each row.

• percentileBy(percentile) { expression } — the row at the percentile of the values that the given expression returns for each row.

percentile(percentile) { columns }, percentileOf, and percentileBy all have an -OrNull counterpart which returns null instead of throwing an exception when there is nothing to compute the percentile of.

Due to a limitation in Kotlin's overload resolution (KT-76683), computing the percentile of non-number comparable values with percentile(percentile) { columns } or percentileOf requires either explicit type arguments, like df.percentile<_, String>(25.0) { name.firstName }, or passing the lambda inside the parentheses, like df.percentile(25.0, { name.firstName }).

From Kotlin 2.5, this limitation can be lifted by enabling eager lambda analysis (KT-51107) with the compiler option -XXLanguage:+EagerLambdaAnalysis, like kotlin { compilerOptions { freeCompilerArgs.add("-XXLanguage:+EagerLambdaAnalysis") } } in Gradle. Then, the right overload is picked for lambdas returning non-number comparable values too, without explicit type arguments. Note that this is an internal compiler option without any stability guarantees, so it is not recommended for production use yet.

Related operation:

• median — the 50th percentile; the same as percentile(50.0).

For more information: See percentile on the documentation website.

See all summary statistics: See "Summary statistics" on the documentation website.