medianOf

Returns the median of the comparable values that the given expression returns for each element of this DataColumn.

This overload is meant for expressions returning non-number self-comparable values, like strings or dates. For expressions returning primitive numbers, the medianOf 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.

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

The resulting median 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 "median Type Conversion" on the documentation website.

Don't confuse medianOf with medianBy, which returns the element the median expression value belongs to instead of that value.

See also:

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

• percentileOf — any other percentile of the values an expression returns.

• The Median Operation — an overview of all median modes.

For more information: See median on the documentation website.

Examples

// The median of all last names in the "name" column group, in upper case
df.name.medianOf<_, String> { it.lastName.uppercase() }
// The same, with the lambda inside the parentheses
df.name.medianOf({ it.lastName.uppercase() })

Parameters

Throws

Returns the median of the numbers that the given expression returns for each element of this DataColumn, as a Double.

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.

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

The resulting median 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 "median Type Conversion" on the documentation website.

Don't confuse medianOf with medianBy, which returns the element the median expression value belongs to instead of that value.

See also:

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

• percentileOf — any other percentile of the values an expression returns.

• meanOf — the average of the values an expression returns.

• The Median Operation — an overview of all median modes.

For more information: See median on the documentation website.

Example

// The median length of all first names in the "name"/"firstName" column
df.name.firstName.medianOf { it.length }

Parameters

Throws

Returns the median of the comparable values that the given expression returns for each row of this DataFrame.

This overload is meant for expressions returning non-number self-comparable values, like strings or dates. For expressions returning primitive numbers, the medianOf 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.

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

The resulting median 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 "median Type Conversion" on the documentation website.

Don't confuse medianOf with medianBy, which returns the row the median expression value belongs to instead of that value.

See also:

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

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

• percentileOf — any other percentile of the values a row expression returns.

• The Median Operation — an overview of all median modes.

For more information: See median on the documentation website.

Examples

// The median of the full names of all rows
df.medianOf<_, String> { name.firstName + " " + name.lastName }
// The same, with the lambda inside the parentheses
df.medianOf({ name.firstName + " " + name.lastName })

Parameters

Throws

Returns the median of the numbers that the given expression returns for each row of this DataFrame, as a Double.

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.

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

The resulting median 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 "median Type Conversion" on the documentation website.

Don't confuse medianOf with medianBy, which returns the row the median expression value belongs to instead of that value.

See also:

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

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

• percentileOf — any other percentile of the values a row expression returns.

• meanOf — the average of the values a row expression returns.

• The Median Operation — an overview of all median modes.

For more information: See median on the documentation website.

Example

// The median weight-to-age ratio of all rows
df.medianOf { (weight ?: 0) / age }

Parameters

Throws

Aggregates this GroupBy by computing the median of the values that the given expression returns for each row of a group.

Returns a new DataFrame with one row per group, containing the group key columns and a single column with the median per group, named name (or "median" if name is null).

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.

For primitive numbers, the resulting median 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 median 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 "median Type Conversion" on the documentation website.

Result cells for which there is nothing to compute the median of (for instance, because the input was empty or contained only null values) simply become null.

Don't confuse medianOf with medianBy, which returns the row of each group at the median of the values the expression returns, instead of that value.

See also:

• median — a single median of all values in the selected columns, per group.

• percentileOf — any other percentile of the values a row expression returns, per group.

• aggregate — the general way to aggregate groups.

• The Median Operation — an overview of all median modes.

For more information: See "groupBy statistics" on the documentation website., and See "GroupBy Aggregation Statistics" on the documentation website.

Example

// For each city, the median weight-to-age ratio, in a column called "medianRatio"
df.groupBy { city }.medianOf("medianRatio") { (weight ?: 0) / age }

Parameters

Aggregates this Pivot by computing the median of the values that the given expression returns for each row, per group.

Returns a single DataRow with the pivot keys as (nested) columns, containing the median of the expression's results for the rows of the corresponding 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.

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

For primitive numbers, the resulting median 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 median 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 "median Type Conversion" on the documentation website.

Result cells for which there is nothing to compute the median of (for instance, because the input was empty or contained only null values) simply become null.

Don't confuse medianOf with medianBy, which returns the row of each group at the median of the values the expression returns, instead of that value.

Check out the Pivot Grammar.

See also:

• median{ columns } — a single median of all values in the selected columns, per group.

• Pivot aggregation — all other ways to aggregate a Pivot.

• The Median Operation — an overview of all median modes.

For more information: See "pivot statistics" on the documentation website., and See "Pivot Aggregation statistics" on the documentation website.

Example

// For each city, the median weight-to-age ratio
df.pivot { city }.medianOf { (weight ?: 0) / age }

Parameters

Aggregates this PivotGroupBy by computing the median of the values that the given expression returns for each row, per group.

Returns a DataFrame where each cell contains the median of the expression's results for the rows of the group corresponding to that pivot key (column) and groupBy key (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.

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

For primitive numbers, the resulting median 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 median 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 "median Type Conversion" on the documentation website.

Result cells for which there exists a group, but there is nothing to compute the median of (for instance, because the group was empty or contained only null values) simply become null.

For empty pivot intersections, null or the set default is used.

Don't confuse medianOf with medianBy, which returns the row of each group at the median of the values the expression returns, instead of that value.

Check out the PivotGroupBy Grammar.

See also:

• median{ columns } — a single median of all values in the selected columns, per group.

• PivotGroupBy aggregation — all other ways to aggregate a PivotGroupBy.

• The Median Operation — an overview of all median modes.

For more information: See "pivot statistics" on the documentation website., and See "Pivot Aggregation statistics" on the documentation website.

Example

// Per city and last name, the median weight-to-age ratio
df.pivot { city }.groupBy { name.lastName }.medianOf { (weight ?: 0) / age }

Parameters