percentileOfOrNull

Returns the given percentile of the comparable values that the given expression returns for each element of this DataColumn, or null if there is nothing to compute the percentile of.

This overload is meant for expressions returning non-number self-comparable values, like strings or dates. For expressions returning primitive numbers, the percentileOfOrNull overload with a skipNaN parameter is used, which returns an interpolated Double.

Note: Due to a limitation in Kotlin's overload resolution (KT-76683), calling this overload with a lambda returning non-number comparable values, like strings or dates, requires either explicit type arguments, or passing the lambda inside the parentheses (see the examples below). For a lambda returning primitive numbers, the overload returning a Double is picked automatically.

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.

The result of the expression is considered the 'input' of this operation.

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.

Returns null when there is nothing to compute the percentile of, for instance, when the input is empty or contains only null values.

The resulting percentile is selected from the values using quantile estimation method R3, so it has the same type as the values (minus nullability, if the values were nullable).

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.

Don't confuse percentileOfOrNull with percentileByOrNull, which returns the element the percentile of the expression values belongs to instead of that value.

See also:

• percentileOf — throws instead of returning null for a column with nothing to compute the percentile of.

• medianOfOrNull — the median (50th percentile) of the values an expression returns.

• The Percentile Operation — an overview of all percentile modes.

For more information: See percentile on the documentation website.

Examples

// The first quartile of all last names in the "name" column group, in upper case,
// or `null` if the column group is empty
df.name.percentileOfOrNull<_, String>(25.0) { it.lastName.uppercase() }
// The same, with the lambda inside the parentheses
df.name.percentileOfOrNull(25.0, { it.lastName.uppercase() })

Parameters

Returns the given percentile of the numbers that the given expression returns for each element of this DataColumn, as a Double, or null if there is nothing to compute the percentile of.

The result of the expression is considered the 'input' of this operation.

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.

Returns null when there is nothing to compute the percentile of, for instance, when the input is empty or contains only null values.

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.

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

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.

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

Don't confuse percentileOfOrNull with percentileByOrNull, which returns the element the percentile of the expression values belongs to instead of that value.

See also:

• percentileOf — throws instead of returning null for a column with nothing to compute the percentile of.

• medianOfOrNull — the median (50th percentile) of the values an expression returns.

• The Percentile Operation — an overview of all percentile modes.

For more information: See percentile on the documentation website.

Example

// The 90th percentile of the lengths of all first names in the "name"/"firstName" column,
// or `null` if the column is empty
df.name.firstName.percentileOfOrNull(90.0) { it.length }

Parameters

Returns the given percentile of the comparable values that the given expression returns for each row of this DataFrame, or null if there is nothing to compute the percentile of.

This overload is meant for expressions returning non-number self-comparable values, like strings or dates. For expressions returning primitive numbers, the percentileOfOrNull overload with a skipNaN parameter is used, which returns an interpolated Double.

Note: Due to a limitation in Kotlin's overload resolution (KT-76683), calling this overload with a lambda returning non-number comparable values, like strings or dates, requires either explicit type arguments, or passing the lambda inside the parentheses (see the examples below). For a lambda returning primitive numbers, the overload returning a Double is picked automatically.

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.

The given RowExpression is evaluated for each row of the dataframe. The row is both the receiver and the argument (it) of the expression, so the values in it can be accessed directly.

For more information: See RowExpression on the documentation website.

The result of the expression is considered the 'input' of this operation.

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.

Returns null when there is nothing to compute the percentile of, for instance, when the input is empty or contains only null values.

The resulting percentile is selected from the values using quantile estimation method R3, so it has the same type as the values (minus nullability, if the values were nullable).

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.

Don't confuse percentileOfOrNull with percentileByOrNull, which returns the row the percentile of the expression values belongs to instead of that value.

See also:

• percentileOf — throws instead of returning null when there's nothing to compute the percentile of.

• percentileOrNull — a single percentile of all values in the selected columns.

• medianOfOrNull — the median (50th percentile) of the values a row expression returns.

• The Percentile Operation — an overview of all percentile modes.

For more information: See percentile on the documentation website.

Examples

// The first quartile of the full names of all rows, or `null` if this dataframe is empty
df.percentileOfOrNull<_, String>(25.0) { name.firstName + " " + name.lastName }
// The same, with the lambda inside the parentheses
df.percentileOfOrNull(25.0, { name.firstName + " " + name.lastName })

Parameters

Returns the given percentile of the numbers that the given expression returns for each row of this DataFrame, as a Double, or null if there is nothing to compute the percentile of.

The given RowExpression is evaluated for each row of the dataframe. The row is both the receiver and the argument (it) of the expression, so the values in it can be accessed directly.

For more information: See RowExpression on the documentation website.

The result of the expression is considered the 'input' of this operation.

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.

Returns null when there is nothing to compute the percentile of, for instance, when the input is empty or contains only null values.

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.

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

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.

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

Don't confuse percentileOfOrNull with percentileByOrNull, which returns the row the percentile of the expression values belongs to instead of that value.

See also:

• percentileOf — throws instead of returning null when there's nothing to compute the percentile of.

• percentileOrNull — a single percentile of all values in the selected columns.

• medianOfOrNull — the median (50th percentile) of the values a row expression returns.

• The Percentile Operation — an overview of all percentile modes.

For more information: See percentile on the documentation website.

Example

// The third quartile of the weight-to-age ratios of all rows, or `null` if this dataframe is empty
df.percentileOfOrNull(75.0) { (weight ?: 0) / age }

Parameters