Create sequence of evenly-spaced points

Description

Usage

pl$linear_space(
  start,
  end,
  num_samples,
  ...,
  closed = c("both", "left", "none", "right")
)

Arguments

start Lower bound of the range.

end Upper bound of the range.

num_samples Number of samples in the output sequence.

… These dots are for future extensions and must be empty.

closed Define which sides of the range are closed (inclusive). One of the following: “both” (default), “left”, “right”, “none”.

Details

linear_space works with numeric and temporal dtypes. When the start and end parameters are Date dtypes, the output sequence consists of equally-spaced Datetime elements with millisecond precision.

Value

A polars expression

Examples

library("polars")

pl$select(
  pl$linear_space(start = 0, end = 1, num_samples = 3)
)

#> shape: (3, 1)
#> ┌─────────┐
#> │ literal │
#> │ ---     │
#> │ f64     │
#> ╞═════════╡
#> │ 0.0     │
#> │ 0.5     │
#> │ 1.0     │
#> └─────────┘

pl$select(
  pl$linear_space(start = 0, end = 1, num_samples = 3, closed = "left")
)

#> shape: (3, 1)
#> ┌──────────┐
#> │ literal  │
#> │ ---      │
#> │ f64      │
#> ╞══════════╡
#> │ 0.0      │
#> │ 0.333333 │
#> │ 0.666667 │
#> └──────────┘

pl$select(
  pl$linear_space(start = 0, end = 1, num_samples = 3, closed = "right")
)

#> shape: (3, 1)
#> ┌──────────┐
#> │ literal  │
#> │ ---      │
#> │ f64      │
#> ╞══════════╡
#> │ 0.333333 │
#> │ 0.666667 │
#> │ 1.0      │
#> └──────────┘

pl$select(
  pl$linear_space(start = 0, end = 1, num_samples = 3, closed = "none")
)

#> shape: (3, 1)
#> ┌─────────┐
#> │ literal │
#> │ ---     │
#> │ f64     │
#> ╞═════════╡
#> │ 0.25    │
#> │ 0.5     │
#> │ 0.75    │
#> └─────────┘

# Date endpoints generate a sequence of Datetime values:
pl$select(
  pl$linear_space(
    start = as.Date("2025-01-01"),
    end = as.Date("2025-02-01"),
    num_samples = 3,
    closed = "right"
  )
)

#> shape: (3, 1)
#> ┌─────────────────────┐
#> │ literal             │
#> │ ---                 │
#> │ datetime[ms]        │
#> ╞═════════════════════╡
#> │ 2025-01-11 08:00:00 │
#> │ 2025-01-21 16:00:00 │
#> │ 2025-02-01 00:00:00 │
#> └─────────────────────┘

# You can generate a sequence using the length of the dataframe:
df <- pl$DataFrame(a = c(1, 2, 3, 4, 5))
df$with_columns(ls = pl$linear_space(0, 1, pl$len()))

#> shape: (5, 2)
#> ┌─────┬──────┐
#> │ a   ┆ ls   │
#> │ --- ┆ ---  │
#> │ f64 ┆ f64  │
#> ╞═════╪══════╡
#> │ 1.0 ┆ 0.0  │
#> │ 2.0 ┆ 0.25 │
#> │ 3.0 ┆ 0.5  │
#> │ 4.0 ┆ 0.75 │
#> │ 5.0 ┆ 1.0  │
#> └─────┴──────┘