polars-df 0.13.0-x86_64-linux → 0.15.0-x86_64-linux

data/lib/polars/date_time_expr.rb

@@ -269,6 +269,50 @@ module Polars
     # See [chrono strftime/strptime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "datetime" => [
+    #         Time.utc(2020, 3, 1),
+    #         Time.utc(2020, 4, 1),
+    #         Time.utc(2020, 5, 1)
+    #       ]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     Polars.col("datetime")
+    #     .dt.strftime("%Y/%m/%d %H:%M:%S")
+    #     .alias("datetime_string")
+    #   )
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────────────────────┬─────────────────────┐
+    #   # │ datetime            ┆ datetime_string     │
+    #   # │ ---                 ┆ ---                 │
+    #   # │ datetime[ns]        ┆ str                 │
+    #   # ╞═════════════════════╪═════════════════════╡
+    #   # │ 2020-03-01 00:00:00 ┆ 2020/03/01 00:00:00 │
+    #   # │ 2020-04-01 00:00:00 ┆ 2020/04/01 00:00:00 │
+    #   # │ 2020-05-01 00:00:00 ┆ 2020/05/01 00:00:00 │
+    #   # └─────────────────────┴─────────────────────┘
+    #
+    # @example If you're interested in the day name / month name, you can use `'%A'` / `'%B'`:
+    #   df.with_columns(
+    #     day_name: Polars.col("datetime").dt.strftime("%A"),
+    #     month_name: Polars.col("datetime").dt.strftime("%B")
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────────────────────┬───────────┬────────────┐
+    #   # │ datetime            ┆ day_name  ┆ month_name │
+    #   # │ ---                 ┆ ---       ┆ ---        │
+    #   # │ datetime[ns]        ┆ str       ┆ str        │
+    #   # ╞═════════════════════╪═══════════╪════════════╡
+    #   # │ 2020-03-01 00:00:00 ┆ Sunday    ┆ March      │
+    #   # │ 2020-04-01 00:00:00 ┆ Wednesday ┆ April      │
+    #   # │ 2020-05-01 00:00:00 ┆ Friday    ┆ May        │
+    #   # └─────────────────────┴───────────┴────────────┘
     def strftime(fmt)
       Utils.wrap_expr(_rbexpr.strftime(fmt))
     end
@@ -574,6 +618,29 @@ module Polars
     # Date
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "datetime" => [
+    #         Time.utc(1978, 1, 1, 1, 1, 1, 0),
+    #         Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
+    #         Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
+    #       ]
+    #     }
+    #   )
+    #   df.with_columns(Polars.col("datetime").dt.date.alias("date"))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────────────────────────┬────────────┐
+    #   # │ datetime                ┆ date       │
+    #   # │ ---                     ┆ ---        │
+    #   # │ datetime[ns]            ┆ date       │
+    #   # ╞═════════════════════════╪════════════╡
+    #   # │ 1978-01-01 01:01:01     ┆ 1978-01-01 │
+    #   # │ 2024-10-13 05:30:14.500 ┆ 2024-10-13 │
+    #   # │ 2065-01-01 10:20:30.060 ┆ 2065-01-01 │
+    #   # └─────────────────────────┴────────────┘
     def date
       Utils.wrap_expr(_rbexpr.dt_date)
     end
@@ -732,6 +799,34 @@ module Polars
     # Applies to Datetime columns.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "datetime": [
+    #         Time.utc(1978, 1, 1, 1, 1, 1, 0),
+    #         Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
+    #         Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
+    #       ]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     Polars.col("datetime").dt.hour.alias("hour"),
+    #     Polars.col("datetime").dt.minute.alias("minute"),
+    #     Polars.col("datetime").dt.second.alias("second"),
+    #     Polars.col("datetime").dt.millisecond.alias("millisecond")
+    #   )
+    #   # =>
+    #   # shape: (3, 5)
+    #   # ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
+    #   # │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
+    #   # │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
+    #   # │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
+    #   # ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
+    #   # │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
+    #   # │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
+    #   # │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
+    #   # └─────────────────────────┴──────┴────────┴────────┴─────────────┘
     def millisecond
       Utils.wrap_expr(_rbexpr.dt_millisecond)
     end
@@ -741,6 +836,34 @@ module Polars
     # Applies to Datetime columns.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "datetime": [
+    #         Time.utc(1978, 1, 1, 1, 1, 1, 0),
+    #         Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
+    #         Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
+    #       ]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     Polars.col("datetime").dt.hour.alias("hour"),
+    #     Polars.col("datetime").dt.minute.alias("minute"),
+    #     Polars.col("datetime").dt.second.alias("second"),
+    #     Polars.col("datetime").dt.microsecond.alias("microsecond")
+    #   )
+    #   # =>
+    #   # shape: (3, 5)
+    #   # ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
+    #   # │ datetime                ┆ hour ┆ minute ┆ second ┆ microsecond │
+    #   # │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
+    #   # │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
+    #   # ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
+    #   # │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
+    #   # │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500000      │
+    #   # │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60000       │
+    #   # └─────────────────────────┴──────┴────────┴────────┴─────────────┘
     def microsecond
       Utils.wrap_expr(_rbexpr.dt_microsecond)
     end
@@ -750,6 +873,34 @@ module Polars
     # Applies to Datetime columns.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "datetime": [
+    #         Time.utc(1978, 1, 1, 1, 1, 1, 0),
+    #         Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
+    #         Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
+    #       ]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     Polars.col("datetime").dt.hour.alias("hour"),
+    #     Polars.col("datetime").dt.minute.alias("minute"),
+    #     Polars.col("datetime").dt.second.alias("second"),
+    #     Polars.col("datetime").dt.nanosecond.alias("nanosecond")
+    #   )
+    #   # =>
+    #   # shape: (3, 5)
+    #   # ┌─────────────────────────┬──────┬────────┬────────┬────────────┐
+    #   # │ datetime                ┆ hour ┆ minute ┆ second ┆ nanosecond │
+    #   # │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---        │
+    #   # │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32        │
+    #   # ╞═════════════════════════╪══════╪════════╪════════╪════════════╡
+    #   # │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0          │
+    #   # │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500000000  │
+    #   # │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60000000   │
+    #   # └─────────────────────────┴──────┴────────┴────────┴────────────┘
     def nanosecond
       Utils.wrap_expr(_rbexpr.dt_nanosecond)
     end
@@ -835,6 +986,34 @@ module Polars
     #   Time unit for the `Datetime` Series.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "date" => Polars.datetime_range(
+    #         Time.utc(2001, 1, 1),
+    #         Time.utc(2001, 1, 3),
+    #         "1d",
+    #         time_unit: "ns",
+    #         eager: true
+    #       )
+    #     }
+    #   )
+    #   df.select(
+    #     Polars.col("date"),
+    #     Polars.col("date").dt.with_time_unit("us").alias("time_unit_us")
+    #   )
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────────────────────┬───────────────────────┐
+    #   # │ date                ┆ time_unit_us          │
+    #   # │ ---                 ┆ ---                   │
+    #   # │ datetime[ns]        ┆ datetime[μs]          │
+    #   # ╞═════════════════════╪═══════════════════════╡
+    #   # │ 2001-01-01 00:00:00 ┆ +32971-04-28 00:00:00 │
+    #   # │ 2001-01-02 00:00:00 ┆ +32974-01-22 00:00:00 │
+    #   # │ 2001-01-03 00:00:00 ┆ +32976-10-18 00:00:00 │
+    #   # └─────────────────────┴───────────────────────┘
     def with_time_unit(time_unit)
       Utils.wrap_expr(_rbexpr.dt_with_time_unit(time_unit))
     end
@@ -931,6 +1110,71 @@ module Polars
     #     Determine how to deal with non-existent datetimes.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "london_timezone": Polars.datetime_range(
+    #         Time.utc(2020, 3, 1),
+    #         Time.utc(2020, 7, 1),
+    #         "1mo",
+    #         time_zone: "UTC",
+    #         eager: true,
+    #       ).dt.convert_time_zone("Europe/London")
+    #     }
+    #   )
+    #   df.select(
+    #     [
+    #       Polars.col("london_timezone"),
+    #       Polars.col("london_timezone")
+    #       .dt.replace_time_zone("Europe/Amsterdam")
+    #       .alias("London_to_Amsterdam")
+    #     ]
+    #   )
+    #   # =>
+    #   # shape: (5, 2)
+    #   # ┌─────────────────────────────┬────────────────────────────────┐
+    #   # │ london_timezone             ┆ London_to_Amsterdam            │
+    #   # │ ---                         ┆ ---                            │
+    #   # │ datetime[ns, Europe/London] ┆ datetime[ns, Europe/Amsterdam] │
+    #   # ╞═════════════════════════════╪════════════════════════════════╡
+    #   # │ 2020-03-01 00:00:00 GMT     ┆ 2020-03-01 00:00:00 CET        │
+    #   # │ 2020-04-01 01:00:00 BST     ┆ 2020-04-01 01:00:00 CEST       │
+    #   # │ 2020-05-01 01:00:00 BST     ┆ 2020-05-01 01:00:00 CEST       │
+    #   # │ 2020-06-01 01:00:00 BST     ┆ 2020-06-01 01:00:00 CEST       │
+    #   # │ 2020-07-01 01:00:00 BST     ┆ 2020-07-01 01:00:00 CEST       │
+    #   # └─────────────────────────────┴────────────────────────────────┘
+    #
+    # @example You can use `ambiguous` to deal with ambiguous datetimes:
+    #   dates = [
+    #     "2018-10-28 01:30",
+    #     "2018-10-28 02:00",
+    #     "2018-10-28 02:30",
+    #     "2018-10-28 02:00"
+    #   ]
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "ts" => Polars::Series.new(dates).str.strptime(Polars::Datetime),
+    #       "ambiguous" => ["earliest", "earliest", "latest", "latest"]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     ts_localized: Polars.col("ts").dt.replace_time_zone(
+    #       "Europe/Brussels", ambiguous: Polars.col("ambiguous")
+    #     )
+    #   )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌─────────────────────┬───────────┬───────────────────────────────┐
+    #   # │ ts                  ┆ ambiguous ┆ ts_localized                  │
+    #   # │ ---                 ┆ ---       ┆ ---                           │
+    #   # │ datetime[μs]        ┆ str       ┆ datetime[μs, Europe/Brussels] │
+    #   # ╞═════════════════════╪═══════════╪═══════════════════════════════╡
+    #   # │ 2018-10-28 01:30:00 ┆ earliest  ┆ 2018-10-28 01:30:00 CEST      │
+    #   # │ 2018-10-28 02:00:00 ┆ earliest  ┆ 2018-10-28 02:00:00 CEST      │
+    #   # │ 2018-10-28 02:30:00 ┆ latest    ┆ 2018-10-28 02:30:00 CET       │
+    #   # │ 2018-10-28 02:00:00 ┆ latest    ┆ 2018-10-28 02:00:00 CET       │
+    #   # └─────────────────────┴───────────┴───────────────────────────────┘
     def replace_time_zone(time_zone, ambiguous: "raise", non_existent: "raise")
       unless ambiguous.is_a?(Expr)
         ambiguous = Polars.lit(ambiguous)

data/lib/polars/date_time_name_space.rb

@@ -1150,6 +1150,47 @@ module Polars
     #   Every interval start and period length.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars.datetime_range(
+    #     Time.utc(2001, 1, 1),
+    #     Time.utc(2001, 1, 2),
+    #     "165m",
+    #     eager: true
+    #   ).alias("datetime")
+    #   s.dt.truncate("1h")
+    #   # =>
+    #   # shape: (9,)
+    #   # Series: 'datetime' [datetime[ns]]
+    #   # [
+    #   #         2001-01-01 00:00:00
+    #   #         2001-01-01 02:00:00
+    #   #         2001-01-01 05:00:00
+    #   #         2001-01-01 08:00:00
+    #   #         2001-01-01 11:00:00
+    #   #         2001-01-01 13:00:00
+    #   #         2001-01-01 16:00:00
+    #   #         2001-01-01 19:00:00
+    #   #         2001-01-01 22:00:00
+    #   # ]
+    #
+    # @example
+    #   s = Polars.datetime_range(
+    #     Time.utc(2001, 1, 1), Time.utc(2001, 1, 1, 1), "10m", eager: true
+    #   ).alias("datetime")
+    #   s.dt.truncate("30m")
+    #   # =>
+    #   # shape: (7,)
+    #   # Series: 'datetime' [datetime[ns]]
+    #   # [
+    #   #         2001-01-01 00:00:00
+    #   #         2001-01-01 00:00:00
+    #   #         2001-01-01 00:00:00
+    #   #         2001-01-01 00:30:00
+    #   #         2001-01-01 00:30:00
+    #   #         2001-01-01 00:30:00
+    #   #         2001-01-01 01:00:00
+    #   # ]
     def truncate(every)
       super
     end
@@ -1185,6 +1226,52 @@ module Polars
     # @note
     #   This functionality is currently experimental and may
     #   change without it being considered a breaking change.
+    #
+    # @example
+    #   start = Time.utc(2001, 1, 1)
+    #   stop = Time.utc(2001, 1, 2)
+    #   s = Polars.datetime_range(
+    #     start, stop, "165m", eager: true
+    #   ).alias("datetime")
+    #   s.dt.round("1h")
+    #   # =>
+    #   # shape: (9,)
+    #   # Series: 'datetime' [datetime[ns]]
+    #   # [
+    #   #         2001-01-01 00:00:00
+    #   #         2001-01-01 03:00:00
+    #   #         2001-01-01 06:00:00
+    #   #         2001-01-01 08:00:00
+    #   #         2001-01-01 11:00:00
+    #   #         2001-01-01 14:00:00
+    #   #         2001-01-01 17:00:00
+    #   #         2001-01-01 19:00:00
+    #   #         2001-01-01 22:00:00
+    #   # ]
+    #
+    # @example
+    #   round_str = s.dt.round("1h")
+    #   round_td = s.dt.round("1h")
+    #   round_str.equals(round_td)
+    #   # => true
+    #
+    # @example
+    #   start = Time.utc(2001, 1, 1)
+    #   stop = Time.utc(2001, 1, 1, 1)
+    #   s = Polars.datetime_range(start, stop, "10m", eager: true).alias("datetime")
+    #   s.dt.round("30m")
+    #   # =>
+    #   # shape: (7,)
+    #   # Series: 'datetime' [datetime[ns]]
+    #   # [
+    #   #         2001-01-01 00:00:00
+    #   #         2001-01-01 00:00:00
+    #   #         2001-01-01 00:30:00
+    #   #         2001-01-01 00:30:00
+    #   #         2001-01-01 00:30:00
+    #   #         2001-01-01 01:00:00
+    #   #         2001-01-01 01:00:00
+    #   # ]
     def round(every)
       super
     end

data/lib/polars/expr.rb

@@ -411,6 +411,26 @@ module Polars
     # Add a prefix to the root column name of the expression.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [1, 2, 3],
+    #       "b" => ["x", "y", "z"]
+    #     }
+    #   )
+    #   df.with_columns(Polars.all.reverse.name.prefix("reverse_"))
+    #   # =>
+    #   # shape: (3, 4)
+    #   # ┌─────┬─────┬───────────┬───────────┐
+    #   # │ a   ┆ b   ┆ reverse_a ┆ reverse_b │
+    #   # │ --- ┆ --- ┆ ---       ┆ ---       │
+    #   # │ i64 ┆ str ┆ i64       ┆ str       │
+    #   # ╞═════╪═════╪═══════════╪═══════════╡
+    #   # │ 1   ┆ x   ┆ 3         ┆ z         │
+    #   # │ 2   ┆ y   ┆ 2         ┆ y         │
+    #   # │ 3   ┆ z   ┆ 1         ┆ x         │
+    #   # └─────┴─────┴───────────┴───────────┘
     def prefix(prefix)
       name.prefix(prefix)
     end
@@ -418,6 +438,26 @@ module Polars
     # Add a suffix to the root column name of the expression.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [1, 2, 3],
+    #       "b" => ["x", "y", "z"]
+    #     }
+    #   )
+    #   df.with_columns(Polars.all.reverse.name.suffix("_reverse"))
+    #   # =>
+    #   # shape: (3, 4)
+    #   # ┌─────┬─────┬───────────┬───────────┐
+    #   # │ a   ┆ b   ┆ a_reverse ┆ b_reverse │
+    #   # │ --- ┆ --- ┆ ---       ┆ ---       │
+    #   # │ i64 ┆ str ┆ i64       ┆ str       │
+    #   # ╞═════╪═════╪═══════════╪═══════════╡
+    #   # │ 1   ┆ x   ┆ 3         ┆ z         │
+    #   # │ 2   ┆ y   ┆ 2         ┆ y         │
+    #   # │ 3   ┆ z   ┆ 1         ┆ x         │
+    #   # └─────┴─────┴───────────┴───────────┘
     def suffix(suffix)
       name.suffix(suffix)
     end
@@ -1182,7 +1222,7 @@ module Polars
     #       "b" => [1, 1, 2, 2]
     #     }
     #   )
-    #   df.select(Polars.all.mode)
+    #   df.select(Polars.all.mode.first)
     #   # =>
     #   # shape: (2, 2)
     #   # ┌─────┬─────┐
@@ -1863,6 +1903,35 @@ module Polars
     # Reverse the selection.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "A" => [1, 2, 3, 4, 5],
+    #       "fruits" => ["banana", "banana", "apple", "apple", "banana"],
+    #       "B" => [5, 4, 3, 2, 1],
+    #       "cars" => ["beetle", "audi", "beetle", "beetle", "beetle"]
+    #     }
+    #   )
+    #   df.select(
+    #     [
+    #       Polars.all,
+    #       Polars.all.reverse.name.suffix("_reverse")
+    #     ]
+    #   )
+    #   # =>
+    #   # shape: (5, 8)
+    #   # ┌─────┬────────┬─────┬────────┬───────────┬────────────────┬───────────┬──────────────┐
+    #   # │ A   ┆ fruits ┆ B   ┆ cars   ┆ A_reverse ┆ fruits_reverse ┆ B_reverse ┆ cars_reverse │
+    #   # │ --- ┆ ---    ┆ --- ┆ ---    ┆ ---       ┆ ---            ┆ ---       ┆ ---          │
+    #   # │ i64 ┆ str    ┆ i64 ┆ str    ┆ i64       ┆ str            ┆ i64       ┆ str          │
+    #   # ╞═════╪════════╪═════╪════════╪═══════════╪════════════════╪═══════════╪══════════════╡
+    #   # │ 1   ┆ banana ┆ 5   ┆ beetle ┆ 5         ┆ banana         ┆ 1         ┆ beetle       │
+    #   # │ 2   ┆ banana ┆ 4   ┆ audi   ┆ 4         ┆ apple          ┆ 2         ┆ beetle       │
+    #   # │ 3   ┆ apple  ┆ 3   ┆ beetle ┆ 3         ┆ apple          ┆ 3         ┆ beetle       │
+    #   # │ 4   ┆ apple  ┆ 2   ┆ beetle ┆ 2         ┆ banana         ┆ 4         ┆ audi         │
+    #   # │ 5   ┆ banana ┆ 1   ┆ beetle ┆ 1         ┆ banana         ┆ 5         ┆ beetle       │
+    #   # └─────┴────────┴─────┴────────┴───────────┴────────────────┴───────────┴──────────────┘
     def reverse
       _from_rbexpr(_rbexpr.reverse)
     end
@@ -2825,7 +2894,7 @@ module Polars
     #   # ╞══════╪════════╡
     #   # │ 1    ┆ 0      │
     #   # └──────┴────────┘
-    # def map_batches(return_dtype: nil, agg_list: false, is_elementwise: false, &f)
+    # def map_batches(return_dtype: nil, agg_list: false, is_elementwise: false, returns_scalar: false, &f)
     #   if !return_dtype.nil?
     #     return_dtype = Utils.rb_type_to_dtype(return_dtype)
     #   end
@@ -2835,7 +2904,8 @@ module Polars
     #       f,
     #       return_dtype,
     #       agg_list,
-    #       is_elementwise
+    #       is_elementwise,
+    #       returns_scalar
     #     )
     #   )
     # end
@@ -3071,6 +3141,21 @@ module Polars
     #   Number of rows to return.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"foo" => [1, 2, 3, 4, 5, 6, 7]})
+    #   df.select(Polars.col("foo").limit(3))
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌─────┐
+    #   # │ foo │
+    #   # │ --- │
+    #   # │ i64 │
+    #   # ╞═════╡
+    #   # │ 1   │
+    #   # │ 2   │
+    #   # │ 3   │
+    #   # └─────┘
     def limit(n = 10)
       head(n)
     end
@@ -5601,6 +5686,22 @@ module Polars
     #   If false, the calculations are corrected for statistical bias.
     #
     # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [1, 4, 2, 9]})
+    #   df.select(Polars.col("a").rolling_skew(3))
+    #   # =>
+    #   # shape: (4, 1)
+    #   # ┌──────────┐
+    #   # │ a        │
+    #   # │ ---      │
+    #   # │ f64      │
+    #   # ╞══════════╡
+    #   # │ null     │
+    #   # │ null     │
+    #   # │ 0.381802 │
+    #   # │ 0.47033  │
+    #   # └──────────┘
     def rolling_skew(window_size, bias: true)
       _from_rbexpr(_rbexpr.rolling_skew(window_size, bias))
     end
@@ -6015,12 +6116,12 @@ module Polars
     #   # ┌──────┐
     #   # │ a    │
     #   # │ ---  │
-    #   # │ i64  │
+    #   # │ f64  │
     #   # ╞══════╡
-    #   # │ -1   │
-    #   # │ 0    │
-    #   # │ 0    │
-    #   # │ 1    │
+    #   # │ -1.0 │
+    #   # │ -0.0 │
+    #   # │ 0.0  │
+    #   # │ 1.0  │
     #   # │ null │
     #   # └──────┘
     def sign

data/lib/polars/functions/as_datatype.rb

@@ -86,8 +86,57 @@ module Polars
     # Concat the arrays in a Series dtype List in linear time.
     #
     # @return [Expr]
-    def concat_list(exprs)
-      exprs = Utils.parse_into_list_of_expressions(exprs)
+    #
+    # @example Concatenate two existing list columns. Null values are propagated.
+    #   df = Polars::DataFrame.new({"a" => [[1, 2], [3], [4, 5]], "b" => [[4], [], nil]})
+    #   df.with_columns(concat_list: Polars.concat_list("a", "b"))
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌───────────┬───────────┬─────────────┐
+    #   # │ a         ┆ b         ┆ concat_list │
+    #   # │ ---       ┆ ---       ┆ ---         │
+    #   # │ list[i64] ┆ list[i64] ┆ list[i64]   │
+    #   # ╞═══════════╪═══════════╪═════════════╡
+    #   # │ [1, 2]    ┆ [4]       ┆ [1, 2, 4]   │
+    #   # │ [3]       ┆ []        ┆ [3]         │
+    #   # │ [4, 5]    ┆ null      ┆ null        │
+    #   # └───────────┴───────────┴─────────────┘
+    #
+    # @example Non-list columns are cast to a list before concatenation. The output data type is the supertype of the concatenated columns.
+    #   df.select("a", concat_list: Polars.concat_list("a", Polars.lit("x")))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌───────────┬─────────────────┐
+    #   # │ a         ┆ concat_list     │
+    #   # │ ---       ┆ ---             │
+    #   # │ list[i64] ┆ list[str]       │
+    #   # ╞═══════════╪═════════════════╡
+    #   # │ [1, 2]    ┆ ["1", "2", "x"] │
+    #   # │ [3]       ┆ ["3", "x"]      │
+    #   # │ [4, 5]    ┆ ["4", "5", "x"] │
+    #   # └───────────┴─────────────────┘
+    #
+    # @example Create lagged columns and collect them into a list. This mimics a rolling window.
+    #   df = Polars::DataFrame.new({"A" => [1.0, 2.0, 9.0, 2.0, 13.0]})
+    #   df = df.select(3.times.map { |i| Polars.col("A").shift(i).alias("A_lag_#{i}") })
+    #   df.select(
+    #     Polars.concat_list(3.times.map { |i| "A_lag_#{i}" }.reverse).alias("A_rolling")
+    #   )
+    #   # =>
+    #   # shape: (5, 1)
+    #   # ┌───────────────────┐
+    #   # │ A_rolling         │
+    #   # │ ---               │
+    #   # │ list[f64]         │
+    #   # ╞═══════════════════╡
+    #   # │ [null, null, 1.0] │
+    #   # │ [null, 1.0, 2.0]  │
+    #   # │ [1.0, 2.0, 9.0]   │
+    #   # │ [2.0, 9.0, 2.0]   │
+    #   # │ [9.0, 2.0, 13.0]  │
+    #   # └───────────────────┘
+    def concat_list(exprs, *more_exprs)
+      exprs = Utils.parse_into_list_of_expressions(exprs, *more_exprs)
       Utils.wrap_expr(Plr.concat_list(exprs))
     end
 

data/lib/polars/functions/col.rb

@@ -23,7 +23,7 @@ module Polars
         Utils.wrap_expr(Plr.col(name.to_s))
       elsif Utils.is_polars_dtype(name)
         Utils.wrap_expr(Plr.dtype_cols([name]))
-      elsif name.is_a?(::Array)
+      elsif name.is_a?(::Array) || name.is_a?(::Set)
         names = Array(name)
         if names.empty?
           return Utils.wrap_expr(Plr.cols(names))

data/lib/polars/functions/eager.rb

@@ -127,7 +127,7 @@ module Polars
     #   af1, af2, af3 = Polars.align_frames(
     #     df1, df2, df3, on: "dt", select: ["x", "y"]
     #   )
-    #   (af1 * af2 * af3).fill_null(0).select(Polars.sum(Polars.col("*")).alias("dot"))
+    #   (af1 * af2 * af3).fill_null(0).select(Polars.sum_horizontal("*").alias("dot"))
     #   # =>
     #   # shape: (3, 1)
     #   # ┌───────┐
@@ -136,9 +136,7 @@ module Polars
     #   # │ f64   │
     #   # ╞═══════╡
     #   # │ 0.0   │
-    #   # ├╌╌╌╌╌╌╌┤
     #   # │ 167.5 │
-    #   # ├╌╌╌╌╌╌╌┤
     #   # │ 47.0  │
     #   # └───────┘
     def align_frames(