Skip to content

Apply a custom R function to a whole Series or sequence of Series.

Source code

Description

[Experimental]

The output of this custom function is presumed to be either a Series, or an R vector that will be converted into a Series by as_polars_series(). By default, the function is applied to the complete Series, rather than element by element. Set is_elementwise to TRUE when the function can be safely applied element by element.

Usage

<Expr>$map_batches(
  lambda,
  return_dtype = NULL,
  ...,
  is_elementwise = FALSE,
  returns_scalar = FALSE
)

Arguments

lambda Function to apply.
return_dtype Dtype of the output Series. Can be a DataType or a DataTypeExpr, such as one returned by pl$dtype_of(). It is recommended to set this whenever possible. If this is NULL, it tries to infer the datatype by calling the function with dummy data and looking at the output.
… These dots are for future extensions and must be empty.
is_elementwise Whether the function can be applied element by element. If TRUE, the function may be optimized by the query engine. Defaults to FALSE.
returns_scalar Whether the function returns a single scalar value. Defaults to FALSE.

Value

A polars expression

Examples

library("polars")

df <- pl$DataFrame(
  sine = c(0.0, 1.0, 0.0, -1.0),
  cosine = c(1.0, 0.0, -1.0, 0.0)
)
df$select(pl$all()$map_batches(\(x) {
  x$to_r_vector() |>
    which.max()
}))

#> shape: (1, 2)
#> ┌──────┬────────┐
#> │ sine ┆ cosine │
#> │ ---  ┆ ---    │
#> │ i32  ┆ i32    │
#> ╞══════╪════════╡
#> │ 2    ┆ 1      │
#> └──────┴────────┘

# Call a function that takes multiple arguments by creating a struct and
# referencing its fields inside the function call.
df <- pl$DataFrame(
  a = c(5, 1, 0, 3),
  b = c(4, 2, 3, 4),
)
df$with_columns(
  a_times_b = pl$struct("a", "b")$map_batches(
    \(x) x$struct$field("a") * x$struct$field("b")
  )
)

#> shape: (4, 3)
#> ┌─────┬─────┬───────────┐
#> │ a   ┆ b   ┆ a_times_b │
#> │ --- ┆ --- ┆ ---       │
#> │ f64 ┆ f64 ┆ f64       │
#> ╞═════╪═════╪═══════════╡
#> │ 5.0 ┆ 4.0 ┆ 20.0      │
#> │ 1.0 ┆ 2.0 ┆ 2.0       │
#> │ 0.0 ┆ 3.0 ┆ 0.0       │
#> │ 3.0 ┆ 4.0 ┆ 12.0      │
#> └─────┴─────┴───────────┘