Make a when-then-otherwise expression

Description

when-then-otherwise is similar to R ifelse(). Always initiated by a pl$when(<condition>)$then(<value if condition>), and optionally followed by chaining one or more $when(<condition>)$then(<value if condition>) statements.

Usage

pl_when(...)

When_then(statement)

Then_when(...)

Then_otherwise(statement)

ChainedWhen_then(statement)

ChainedThen_when(...)

ChainedThen_otherwise(statement)

Arguments

`…`	Expr or something coercible to an Expr that returns a boolian each row.
`statement`	Expr or something coercible to an Expr value to insert in `$then()` or `$otherwise()`. A character vector is parsed as column names.

Details

Chained when-then operations should be read like if, else if, else if, … in R, not as if, if, if, …, i.e. the first condition that evaluates to true will be picked.

If none of the conditions are true, an optional $otherwise(<value if all statements are false>) can be appended at the end. If not appended, and none of the conditions are true, null will be returned.

RPolarsThen objects and RPolarsChainedThen objects (returned by $then()) stores the same methods as Expr.

Value

pl$when() returns a When object
\$then() returns a Then object
\$when() returns a ChainedWhen object
\$then() returns a ChainedThen object
$otherwise() returns an Expr object.

Examples

library(polars)

df = pl$DataFrame(foo = c(1, 3, 4), bar = c(3, 4, 0))

# Add a column with the value 1, where column "foo" > 2 and the value -1
# where it isn’t.
df$with_columns(
  val = pl$when(pl$col("foo") > 2)$then(1)$otherwise(-1)
)

#> shape: (3, 3)
#> ┌─────┬─────┬──────┐
#> │ foo ┆ bar ┆ val  │
#> │ --- ┆ --- ┆ ---  │
#> │ f64 ┆ f64 ┆ f64  │
#> ╞═════╪═════╪══════╡
#> │ 1.0 ┆ 3.0 ┆ -1.0 │
#> │ 3.0 ┆ 4.0 ┆ 1.0  │
#> │ 4.0 ┆ 0.0 ┆ 1.0  │
#> └─────┴─────┴──────┘

# With multiple when-then chained:
df$with_columns(
  val = pl$when(pl$col("foo") > 2)
  $then(1)
  $when(pl$col("bar") > 2)
  $then(4)
  $otherwise(-1)
)

#> shape: (3, 3)
#> ┌─────┬─────┬─────┐
#> │ foo ┆ bar ┆ val │
#> │ --- ┆ --- ┆ --- │
#> │ f64 ┆ f64 ┆ f64 │
#> ╞═════╪═════╪═════╡
#> │ 1.0 ┆ 3.0 ┆ 4.0 │
#> │ 3.0 ┆ 4.0 ┆ 1.0 │
#> │ 4.0 ┆ 0.0 ┆ 1.0 │
#> └─────┴─────┴─────┘

# The `$otherwise` at the end is optional.
# If left out, any rows where none of the `$when()` expressions are evaluated to `true`,
# are set to `null`
df$with_columns(
  val = pl$when(pl$col("foo") > 2)$then(1)
)

#> shape: (3, 3)
#> ┌─────┬─────┬──────┐
#> │ foo ┆ bar ┆ val  │
#> │ --- ┆ --- ┆ ---  │
#> │ f64 ┆ f64 ┆ f64  │
#> ╞═════╪═════╪══════╡
#> │ 1.0 ┆ 3.0 ┆ null │
#> │ 3.0 ┆ 4.0 ┆ 1.0  │
#> │ 4.0 ┆ 0.0 ┆ 1.0  │
#> └─────┴─────┴──────┘

# Pass multiple predicates, each of which must be met:
df$with_columns(
  val = pl$when(
    pl$col("bar") > 0,
    pl$col("foo") %% 2 != 0
  )
  $then(99)
  $otherwise(-1)
)

#> shape: (3, 3)
#> ┌─────┬─────┬──────┐
#> │ foo ┆ bar ┆ val  │
#> │ --- ┆ --- ┆ ---  │
#> │ f64 ┆ f64 ┆ f64  │
#> ╞═════╪═════╪══════╡
#> │ 1.0 ┆ 3.0 ┆ 99.0 │
#> │ 3.0 ┆ 4.0 ┆ 99.0 │
#> │ 4.0 ┆ 0.0 ┆ -1.0 │
#> └─────┴─────┴──────┘

# In `$then()`, a character vector is parsed as column names
df$with_columns(baz = pl$when(pl$col("foo") %% 2 == 1)$then("bar"))

#> shape: (3, 3)
#> ┌─────┬─────┬──────┐
#> │ foo ┆ bar ┆ baz  │
#> │ --- ┆ --- ┆ ---  │
#> │ f64 ┆ f64 ┆ f64  │
#> ╞═════╪═════╪══════╡
#> │ 1.0 ┆ 3.0 ┆ 3.0  │
#> │ 3.0 ┆ 4.0 ┆ 4.0  │
#> │ 4.0 ┆ 0.0 ┆ null │
#> └─────┴─────┴──────┘

# So use `pl$lit()` to insert a string
df$with_columns(baz = pl$when(pl$col("foo") %% 2 == 1)$then(pl$lit("bar")))

#> shape: (3, 3)
#> ┌─────┬─────┬──────┐
#> │ foo ┆ bar ┆ baz  │
#> │ --- ┆ --- ┆ ---  │
#> │ f64 ┆ f64 ┆ str  │
#> ╞═════╪═════╪══════╡
#> │ 1.0 ┆ 3.0 ┆ bar  │
#> │ 3.0 ┆ 4.0 ┆ bar  │
#> │ 4.0 ┆ 0.0 ┆ null │
#> └─────┴─────┴──────┘