percentileBy

Returns the element of this DataColumn at the given percentile of the values that the given selector returns for each element.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

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

Don't confuse percentileBy with percentileOf, which returns the percentile of the selector values itself instead of the element it belongs to.

See also:

• percentileByOrNull — returns null instead of throwing for a column with nothing to compute the percentile of.

• medianBy — the element at the median (50th percentile) of the values a selector returns.

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

For more information: See percentile on the documentation website.

Example

// The first name at the first quartile of the lengths of all names in the "name"/"firstName" column
df.name.firstName.percentileBy(25.0) { it.length }

Parameters

Throws

Returns the row of this DataFrame at the given percentile of the values that the given expression returns for each row.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

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

Don't confuse percentileBy with percentileOf, which returns the percentile of the expression values itself instead of the row it belongs to.

See also:

• percentileByOrNull — returns null instead of throwing when there's nothing to compute the percentile of.

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

• sortBy — orders all rows instead of taking just one.

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

For more information: See percentile on the documentation website.

Example

// The row at the first quartile of "age"
df.percentileBy(25.0) { age }
// The row at the 90th percentile of the weight-to-age ratios
df.percentileBy(90.0) { (weight ?: 0) / age }

Parameters

Throws

Returns the row of this DataFrame at the given percentile of the values in the column with the given name.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

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

Don't confuse percentileBy with percentile, which returns the percentile value itself instead of the row it belongs to.

See also:

• percentileByOrNull — returns null instead of throwing when there's nothing to compute the percentile of.

• medianBy — the row at the median (50th percentile) of the values in a column.

• sortBy — orders all rows instead of taking just one.

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

For more information: See percentile on the documentation website.

Example

// The row at the first quartile of "age"
df.percentileBy(25.0, "age")

Parameters

Throws

Reduces each group of this GroupBy to the row at the given percentile of the values that the given rowExpression returns for each row of that group.

This operation does not produce a result right away. Instead, it returns a ReducedGroupBy — an intermediate step which can be finished with concat (to get a DataFrame with the selected rows), values, or into.

See GroupBy reducing for more details.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

Groups that have no values to compute the percentile of cannot select a row, and produce null values instead.

Don't confuse percentileBy with percentileOf, which returns the percentile value itself instead of the row it belongs to.

See also:

• medianBy — the row at the median (50th percentile), per group.

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

For more information: See percentile on the documentation website.

Example

// For each city, the full row of the person at the first quartile of "age"
df.groupBy { city }.percentileBy(25.0) { age }.concat()

Parameters

Reduces each group of this GroupBy to the row at the given percentile of the values in the column with the given name.

This operation does not produce a result right away. Instead, it returns a ReducedGroupBy — an intermediate step which can be finished with concat (to get a DataFrame with the selected rows), values, or into.

See GroupBy reducing for more details.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

Groups that have no values to compute the percentile of cannot select a row, and produce null values instead.

Don't confuse percentileBy with percentile, which returns the percentile value itself instead of the row it belongs to.

See also:

• medianBy — the row at the median (50th percentile), per group.

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

For more information: See percentile on the documentation website.

Example

// For each city, the full row of the person at the first quartile of "age"
df.groupBy { city }.percentileBy(25.0, "age").concat()

Parameters

Reduces this Pivot by taking from each group the row at the given percentile of the values that the given rowExpression returns for each row of that group.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

Groups that have no values to compute the percentile of cannot select a row, and produce null values instead.

This operation does not produce a result right away. Instead, it returns a ReducedPivot — an intermediate step which can be finished with values or with.

Don't confuse percentileBy with percentileOf, which returns the percentile of the values the expression returns itself, instead of the row.

Check out the Pivot Grammar.

See also:

• medianBy — the row at the median (50th percentile), per group.

• Pivot reducing — all other ways to reduce a Pivot.

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

For more information: See percentile on the documentation website.

Example

// For each city, the "name" of the person at the third quartile of the weight-to-age ratios
df.pivot { city }.percentileBy(75.0) { (weight ?: 0) / age }.with { name }

Parameters

Reduces this Pivot by taking from each group the row at the given percentile of the values in the given column.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

Groups that have no values to compute the percentile of cannot select a row, and produce null values instead.

This operation does not produce a result right away. Instead, it returns a ReducedPivot — an intermediate step which can be finished with values or with.

Don't confuse percentileBy with percentile, which returns the percentile value itself, instead of the row.

Check out the Pivot Grammar.

See also:

• medianBy — the row at the median (50th percentile), per group.

• Pivot reducing — all other ways to reduce a Pivot.

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

For more information: See percentile on the documentation website.

Example

// For each city, the "name" of the person at the first quartile of "age"
df.pivot { city }.percentileBy(25.0, "age").with { name }

Parameters

Reduces this PivotGroupBy by taking from each group the row at the given percentile of the values that the given rowExpression returns for each row of that group.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

Groups that have no values to compute the percentile of cannot select a row, and produce null values instead.

This operation does not produce a result right away. Instead, it returns a ReducedPivotGroupBy — an intermediate step which can be finished with values or with.

Don't confuse percentileBy with percentileOf, which returns the percentile of the values the expression returns itself, instead of the row.

Check out the PivotGroupBy Grammar.

See also:

• medianBy — the row at the median (50th percentile), per group.

• PivotGroupBy reducing — all other ways to reduce a PivotGroupBy.

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

For more information: See percentile on the documentation website.

Example

// Per city and last name, the "firstName" of the person at the third quartile of the weight-to-age ratios
df.pivot { city }.groupBy { name.lastName }.percentileBy(75.0) { (weight ?: 0) / age }.with { name.firstName }

Parameters

Reduces this PivotGroupBy by taking from each group the row at the given percentile of the values in the given column.

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.

Which value lies at the percentile is determined using quantile estimation method R3, so no interpolation takes place, not even for numbers. If skipNaN is false and NaN values are encountered, the first one with a NaN value is selected.

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

Groups that have no values to compute the percentile of cannot select a row, and produce null values instead.

This operation does not produce a result right away. Instead, it returns a ReducedPivotGroupBy — an intermediate step which can be finished with values or with.

Don't confuse percentileBy with percentile, which returns the percentile value itself, instead of the row.

Check out the PivotGroupBy Grammar.

See also:

• medianBy — the row at the median (50th percentile), per group.

• PivotGroupBy reducing — all other ways to reduce a PivotGroupBy.

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

For more information: See percentile on the documentation website.

Example

// Per city and last name, the "firstName" of the person at the first quartile of "age"
df.pivot { city }.groupBy { name.lastName }.percentileBy(25.0, "age").with { name.firstName }

Parameters