sort_by

Sort this column by the ordering of another column, or multiple other columns.

Description

If used in a groupby context, values within each group are sorted.

Usage

<Expr>$sort_by(
  ...,
  descending = FALSE,
  nulls_last = FALSE,
  multithreaded = TRUE,
  maintain_order = FALSE
)

Arguments

…	\<dynamic-dots\> Column(s) to sort by. Accepts expression input. Strings are parsed as column names.
descending	Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans.
nulls_last	Place null values last; can specify a single boolean applying to all columns or a sequence of booleans for per-column control.
multithreaded	Sort using multiple threads.
maintain_order	Whether the order should be maintained if elements are equal.

Value

A polars expression

Examples

library("polars")

df <- pl$DataFrame(
  group = c("a", "a", "b", "b"),
  value1 = c(1, 3, 4, 2),
  value2 = c(8, 7, 6, 5)
)

# by one column/expression
df$with_columns(
  sorted = pl$col("group")$sort_by("value1")
)

#> shape: (4, 4)
#> ┌───────┬────────┬────────┬────────┐
#> │ group ┆ value1 ┆ value2 ┆ sorted │
#> │ ---   ┆ ---    ┆ ---    ┆ ---    │
#> │ str   ┆ f64    ┆ f64    ┆ str    │
#> ╞═══════╪════════╪════════╪════════╡
#> │ a     ┆ 1.0    ┆ 8.0    ┆ a      │
#> │ a     ┆ 3.0    ┆ 7.0    ┆ b      │
#> │ b     ┆ 4.0    ┆ 6.0    ┆ a      │
#> │ b     ┆ 2.0    ┆ 5.0    ┆ b      │
#> └───────┴────────┴────────┴────────┘

# by two columns/expressions
df$with_columns(
  sorted = pl$col("group")$sort_by(
    "value2", pl$col("value1"),
    descending = c(TRUE, FALSE)
  )
)

#> shape: (4, 4)
#> ┌───────┬────────┬────────┬────────┐
#> │ group ┆ value1 ┆ value2 ┆ sorted │
#> │ ---   ┆ ---    ┆ ---    ┆ ---    │
#> │ str   ┆ f64    ┆ f64    ┆ str    │
#> ╞═══════╪════════╪════════╪════════╡
#> │ a     ┆ 1.0    ┆ 8.0    ┆ a      │
#> │ a     ┆ 3.0    ┆ 7.0    ┆ a      │
#> │ b     ┆ 4.0    ┆ 6.0    ┆ b      │
#> │ b     ┆ 2.0    ┆ 5.0    ┆ b      │
#> └───────┴────────┴────────┴────────┘

# by some expression
df$with_columns(
  sorted = pl$col("group")$sort_by(pl$col("value1") + pl$col("value2"))
)

#> shape: (4, 4)
#> ┌───────┬────────┬────────┬────────┐
#> │ group ┆ value1 ┆ value2 ┆ sorted │
#> │ ---   ┆ ---    ┆ ---    ┆ ---    │
#> │ str   ┆ f64    ┆ f64    ┆ str    │
#> ╞═══════╪════════╪════════╪════════╡
#> │ a     ┆ 1.0    ┆ 8.0    ┆ b      │
#> │ a     ┆ 3.0    ┆ 7.0    ┆ a      │
#> │ b     ┆ 4.0    ┆ 6.0    ┆ a      │
#> │ b     ┆ 2.0    ┆ 5.0    ┆ b      │
#> └───────┴────────┴────────┴────────┘

# in an aggregation context, values are sorted within groups
df$group_by("group")$agg(
  pl$col("value1")$sort_by("value2")
)

#> shape: (2, 2)
#> ┌───────┬────────────┐
#> │ group ┆ value1     │
#> │ ---   ┆ ---        │
#> │ str   ┆ list[f64]  │
#> ╞═══════╪════════════╡
#> │ a     ┆ [3.0, 1.0] │
#> │ b     ┆ [2.0, 4.0] │
#> └───────┴────────────┘