polars-df 0.15.0 → 0.26.0

data/lib/polars/array_expr.rb

@@ -9,6 +9,181 @@ module Polars
       self._rbexpr = expr._rbexpr
     end
 
+    # Return the number of elements in each array.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.len)
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌─────┐
+    #   # │ a   │
+    #   # │ --- │
+    #   # │ u32 │
+    #   # ╞═════╡
+    #   # │ 2   │
+    #   # │ 2   │
+    #   # └─────┘
+    def len
+      Utils.wrap_expr(_rbexpr.arr_len)
+    end
+
+    # Slice every subarray.
+    #
+    # @param offset [Integer]
+    #   Start index. Negative indexing is supported.
+    # @param length [Integer]
+    #   Length of the slice. If set to `nil` (default), the slice is taken to the
+    #   end of the list.
+    # @param as_array [Boolean]
+    #   Return result as a fixed-length `Array`, otherwise as a `List`.
+    #   If true `length` and `offset` must be constant values.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.slice(0, 1))
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌───────────┐
+    #   # │ a         │
+    #   # │ ---       │
+    #   # │ list[i64] │
+    #   # ╞═══════════╡
+    #   # │ [1]       │
+    #   # │ [4]       │
+    #   # └───────────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.slice(0, 1, as_array: true))
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌───────────────┐
+    #   # │ a             │
+    #   # │ ---           │
+    #   # │ array[i64, 1] │
+    #   # ╞═══════════════╡
+    #   # │ [1]           │
+    #   # │ [4]           │
+    #   # └───────────────┘
+    def slice(
+      offset,
+      length = nil,
+      as_array: false
+    )
+      offset = Utils.parse_into_expression(offset)
+      length = !length.nil? ? Utils.parse_into_expression(length) : nil
+      Utils.wrap_expr(_rbexpr.arr_slice(offset, length, as_array))
+    end
+
+    # Get the first `n` elements of the sub-arrays.
+    #
+    # @param n [Integer]
+    #   Number of values to return for each sublist.
+    # @param as_array [Boolean]
+    #   Return result as a fixed-length `Array`, otherwise as a `List`.
+    #   If true `n` must be a constant value.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.head(1))
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌───────────┐
+    #   # │ a         │
+    #   # │ ---       │
+    #   # │ list[i64] │
+    #   # ╞═══════════╡
+    #   # │ [1]       │
+    #   # │ [4]       │
+    #   # └───────────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.head(1, as_array: true))
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌───────────────┐
+    #   # │ a             │
+    #   # │ ---           │
+    #   # │ array[i64, 1] │
+    #   # ╞═══════════════╡
+    #   # │ [1]           │
+    #   # │ [4]           │
+    #   # └───────────────┘
+    def head(n = 5, as_array: false)
+      slice(0, n, as_array: as_array)
+    end
+
+    # Slice the last `n` values of every sublist.
+    #
+    # @param n [Integer]
+    #   Number of values to return for each sublist.
+    # @param as_array [Boolean]
+    #   Return result as a fixed-length `Array`, otherwise as a `List`.
+    #   If true `n` must be a constant value.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.tail(1))
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌───────────┐
+    #   # │ a         │
+    #   # │ ---       │
+    #   # │ list[i64] │
+    #   # ╞═══════════╡
+    #   # │ [2]       │
+    #   # │ [3]       │
+    #   # └───────────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.tail(1, as_array: true))
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌───────────────┐
+    #   # │ a             │
+    #   # │ ---           │
+    #   # │ array[i64, 1] │
+    #   # ╞═══════════════╡
+    #   # │ [2]           │
+    #   # │ [3]           │
+    #   # └───────────────┘
+    def tail(n = 5, as_array: false)
+      n = Utils.parse_into_expression(n)
+      Utils.wrap_expr(_rbexpr.arr_tail(n, as_array))
+    end
+
     # Compute the min values of the sub-arrays.
     #
     # @return [Expr]
@@ -16,7 +191,7 @@ module Polars
     # @example
     #   df = Polars::DataFrame.new(
     #     {"a" => [[1, 2], [4, 3]]},
-    #     schema: {"a" => Polars::Array.new(2, Polars::Int64)}
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
     #   )
     #   df.select(Polars.col("a").arr.min)
     #   # =>
@@ -30,7 +205,7 @@ module Polars
     #   # │ 3   │
     #   # └─────┘
     def min
-      Utils.wrap_expr(_rbexpr.array_min)
+      Utils.wrap_expr(_rbexpr.arr_min)
     end
 
     # Compute the max values of the sub-arrays.
@@ -40,7 +215,7 @@ module Polars
     # @example
     #   df = Polars::DataFrame.new(
     #     {"a" => [[1, 2], [4, 3]]},
-    #     schema: {"a" => Polars::Array.new(2, Polars::Int64)}
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
     #   )
     #   df.select(Polars.col("a").arr.max)
     #   # =>
@@ -54,7 +229,7 @@ module Polars
     #   # │ 4   │
     #   # └─────┘
     def max
-      Utils.wrap_expr(_rbexpr.array_max)
+      Utils.wrap_expr(_rbexpr.arr_max)
     end
 
     # Compute the sum values of the sub-arrays.
@@ -64,7 +239,7 @@ module Polars
     # @example
     #   df = Polars::DataFrame.new(
     #     {"a" => [[1, 2], [4, 3]]},
-    #     schema: {"a" => Polars::Array.new(2, Polars::Int64)}
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
     #   )
     #   df.select(Polars.col("a").arr.sum)
     #   # =>
@@ -78,7 +253,103 @@ module Polars
     #   # │ 7   │
     #   # └─────┘
     def sum
-      Utils.wrap_expr(_rbexpr.array_sum)
+      Utils.wrap_expr(_rbexpr.arr_sum)
+    end
+
+    # Compute the std of the values of the sub-arrays.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.std)
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌──────────┐
+    #   # │ a        │
+    #   # │ ---      │
+    #   # │ f64      │
+    #   # ╞══════════╡
+    #   # │ 0.707107 │
+    #   # │ 0.707107 │
+    #   # └──────────┘
+    def std(ddof: 1)
+      Utils.wrap_expr(_rbexpr.arr_std(ddof))
+    end
+
+    # Compute the var of the values of the sub-arrays.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.var)
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌─────┐
+    #   # │ a   │
+    #   # │ --- │
+    #   # │ f64 │
+    #   # ╞═════╡
+    #   # │ 0.5 │
+    #   # │ 0.5 │
+    #   # └─────┘
+    def var(ddof: 1)
+      Utils.wrap_expr(_rbexpr.arr_var(ddof))
+    end
+
+    # Compute the mean of the values of the sub-arrays.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2, 3], [1, 1, 16]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 3)}
+    #   )
+    #   df.select(Polars.col("a").arr.mean)
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌─────┐
+    #   # │ a   │
+    #   # │ --- │
+    #   # │ f64 │
+    #   # ╞═════╡
+    #   # │ 2.0 │
+    #   # │ 6.0 │
+    #   # └─────┘
+    def mean
+      Utils.wrap_expr(_rbexpr.arr_mean)
+    end
+
+    # Compute the median of the values of the sub-arrays.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [4, 3]]},
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
+    #   )
+    #   df.select(Polars.col("a").arr.median)
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌─────┐
+    #   # │ a   │
+    #   # │ --- │
+    #   # │ f64 │
+    #   # ╞═════╡
+    #   # │ 1.5 │
+    #   # │ 3.5 │
+    #   # └─────┘
+    def median
+      Utils.wrap_expr(_rbexpr.arr_median)
     end
 
     # Get the unique/distinct values in the array.
@@ -106,7 +377,35 @@ module Polars
     #   # │ [1, 2]    │
     #   # └───────────┘
     def unique(maintain_order: false)
-      Utils.wrap_expr(_rbexpr.arr_unique(maintain_order))
+      eval(
+        F.element.unique(maintain_order: maintain_order), as_list: true
+      )
+    end
+
+    # Count the number of unique values in every sub-arrays.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [[1, 1, 2], [2, 3, 4]],
+    #     },
+    #     schema: {"a" => Polars::Array.new(Polars::Int64, 3)}
+    #   )
+    #   df.with_columns(n_unique: Polars.col("a").arr.n_unique)
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌───────────────┬──────────┐
+    #   # │ a             ┆ n_unique │
+    #   # │ ---           ┆ ---      │
+    #   # │ array[i64, 3] ┆ u32      │
+    #   # ╞═══════════════╪══════════╡
+    #   # │ [1, 1, 2]     ┆ 2        │
+    #   # │ [2, 3, 4]     ┆ 3        │
+    #   # └───────────────┴──────────┘
+    def n_unique
+      agg(F.element.n_unique)
     end
 
     # Convert an Array column into a List column with the same inner data type.
@@ -135,12 +434,19 @@ module Polars
 
     # Evaluate whether any boolean value is true for every subarray.
     #
+    # @param ignore_nulls [Boolean]
+    #   * If set to `true` (default), null values are ignored. If there
+    #     are no non-null values, the output is `false`.
+    #   * If set to `false`, [Kleene logic](https://en.wikipedia.org/wiki/Three-valued_logic) is used to deal with nulls:
+    #     if the column contains any null values and no `true` values,
+    #     the output is null.
+    #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new(
     #     {
-    #       "a": [
+    #       "a" => [
     #         [true, true],
     #         [false, true],
     #         [false, false],
@@ -164,18 +470,25 @@ module Polars
     #   # │ [null, null]   ┆ false │
     #   # │ null           ┆ null  │
     #   # └────────────────┴───────┘
-    def any
-      Utils.wrap_expr(_rbexpr.arr_any)
+    def any(ignore_nulls: true)
+      agg(F.element.any(ignore_nulls: ignore_nulls))
     end
 
     # Evaluate whether all boolean values are true for every subarray.
     #
+    # @param ignore_nulls [Boolean]
+    #   * If set to `true` (default), null values are ignored. If there
+    #     are no non-null values, the output is `true`.
+    #   * If set to `false`, [Kleene logic](https://en.wikipedia.org/wiki/Three-valued_logic) is used to deal with nulls:
+    #     if the column contains any null values and no `false` values,
+    #     the output is null.
+    #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new(
     #     {
-    #       "a": [
+    #       "a" => [
     #         [true, true],
     #         [false, true],
     #         [false, false],
@@ -199,8 +512,8 @@ module Polars
     #   # │ [null, null]   ┆ true  │
     #   # │ null           ┆ null  │
     #   # └────────────────┴───────┘
-    def all
-      Utils.wrap_expr(_rbexpr.arr_all)
+    def all(ignore_nulls: true)
+      agg(F.element.all(ignore_nulls: ignore_nulls))
     end
 
     # Sort the arrays in this column.
@@ -270,7 +583,7 @@ module Polars
     #   # │ [9, 1, 2]     ┆ [2, 1, 9]     │
     #   # └───────────────┴───────────────┘
     def reverse
-      Utils.wrap_expr(_rbexpr.arr_reverse)
+      eval(F.element.reverse)
     end
 
     # Retrieve the index of the minimal value in every sub-array.
@@ -345,7 +658,7 @@ module Polars
     #     {"arr" => [[1, 2, 3], [4, 5, 6], [7, 8, 9]], "idx" => [1, -2, 4]},
     #     schema: {"arr" => Polars::Array.new(Polars::Int32, 3), "idx" => Polars::Int32}
     #   )
-    #   df.with_columns(get: Polars.col("arr").arr.get("idx"))
+    #   df.with_columns(get: Polars.col("arr").arr.get("idx", null_on_oob: true))
     #   # =>
     #   # shape: (3, 3)
     #   # ┌───────────────┬─────┬──────┐
@@ -357,7 +670,7 @@ module Polars
     #   # │ [4, 5, 6]     ┆ -2  ┆ 5    │
     #   # │ [7, 8, 9]     ┆ 4   ┆ null │
     #   # └───────────────┴─────┴──────┘
-    def get(index, null_on_oob: true)
+    def get(index, null_on_oob: false)
       index = Utils.parse_into_expression(index)
       Utils.wrap_expr(_rbexpr.arr_get(index, null_on_oob))
     end
@@ -384,7 +697,7 @@ module Polars
     #   # │ [7, 8, 9]     ┆ 7     │
     #   # └───────────────┴───────┘
     def first
-      get(0)
+      get(0, null_on_oob: true)
     end
 
     # Get the last value of the sub-arrays.
@@ -409,7 +722,7 @@ module Polars
     #   # │ [7, 8, 9]     ┆ 9    │
     #   # └───────────────┴──────┘
     def last
-      get(-1)
+      get(-1, null_on_oob: true)
     end
 
     # Join all string items in a sub-array and place a separator between them.
@@ -452,6 +765,11 @@ module Polars
 
     # Returns a column with a separate row for every array element.
     #
+    # @param empty_as_null [Boolean]
+    #   Explode an empty array into a `null`.
+    # @param keep_nulls [Boolean]
+    #   Explode a `null` array into a `null`.
+    #
     # @return [Expr]
     #
     # @example
@@ -473,14 +791,16 @@ module Polars
     #   # │ 5   │
     #   # │ 6   │
     #   # └─────┘
-    def explode
-      Utils.wrap_expr(_rbexpr.explode)
+    def explode(empty_as_null: true, keep_nulls: true)
+      Utils.wrap_expr(_rbexpr.explode(empty_as_null, keep_nulls))
     end
 
     # Check if sub-arrays contain the given item.
     #
     # @param item [Object]
     #   Item that will be checked for membership
+    # @param nulls_equal [Boolean]
+    #   If true, treat null as a distinct value. Null values will not propagate.
     #
     # @return [Expr]
     #
@@ -501,9 +821,9 @@ module Polars
     #   # │ ["x", "y"]    ┆ false    │
     #   # │ ["a", "c"]    ┆ true     │
     #   # └───────────────┴──────────┘
-    def contains(item)
+    def contains(item, nulls_equal: true)
       item = Utils.parse_into_expression(item, str_as_lit: true)
-      Utils.wrap_expr(_rbexpr.arr_contains(item))
+      Utils.wrap_expr(_rbexpr.arr_contains(item, nulls_equal))
     end
 
     # Count how often the value produced by `element` occurs.
@@ -533,5 +853,163 @@ module Polars
       element = Utils.parse_into_expression(element, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.arr_count_matches(element))
     end
+
+    # Convert the Series of type `Array` to a Series of type `Struct`.
+    #
+    # @param fields [Object]
+    #   If the name and number of the desired fields is known in advance
+    #   a list of field names can be given, which will be assigned by index.
+    #   Otherwise, to dynamically assign field names, a custom function can be
+    #   used; if neither are set, fields will be `field_0, field_1 .. field_n`.
+    #
+    # @return [Expr]
+    #
+    # @example Convert array to struct with default field name assignment:
+    #   s1 = Polars::Series.new("n", [[0, 1, 2], [3, 4, 5]], dtype: Polars::Array.new(Polars::Int8, 3))
+    #   s2 = s1.arr.to_struct
+    #   s2.struct.fields
+    #   # => ["field_0", "field_1", "field_2"]
+    #
+    # @example Convert array to struct with field name assignment by function/index:
+    #   s3 = s1.arr.to_struct(fields: ->(idx) { "n%02d" % idx })
+    #   s3.struct.fields
+    #   # => ["n00", "n01", "n02"]
+    #
+    # @example Convert array to struct with field name assignment by index from a list of names:
+    #   s1.arr.to_struct(fields: ["one", "two", "three"]).struct.unnest
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌─────┬─────┬───────┐
+    #   # │ one ┆ two ┆ three │
+    #   # │ --- ┆ --- ┆ ---   │
+    #   # │ i8  ┆ i8  ┆ i8    │
+    #   # ╞═════╪═════╪═══════╡
+    #   # │ 0   ┆ 1   ┆ 2     │
+    #   # │ 3   ┆ 4   ┆ 5     │
+    #   # └─────┴─────┴───────┘
+    def to_struct(fields: nil)
+      if fields.is_a?(Enumerable)
+        field_names = fields.to_a
+        rbexpr = _rbexpr.arr_to_struct(nil)
+        Utils.wrap_expr(rbexpr).struct.rename_fields(field_names)
+      else
+        rbexpr = _rbexpr.arr_to_struct(fields)
+        Utils.wrap_expr(rbexpr)
+      end
+    end
+
+    # Shift array values by the given number of indices.
+    #
+    # @param n [Integer]
+    #   Number of indices to shift forward. If a negative value is passed, values
+    #   are shifted in the opposite direction instead.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   This method is similar to the `LAG` operation in SQL when the value for `n`
+    #   is positive. With a negative value for `n`, it is similar to `LEAD`.
+    #
+    # @example By default, array values are shifted forward by one index.
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2, 3], [4, 5, 6]]}, schema: {"a" => Polars::Array.new(Polars::Int64, 3)}
+    #   )
+    #   df.with_columns(shift: Polars.col("a").arr.shift)
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌───────────────┬───────────────┐
+    #   # │ a             ┆ shift         │
+    #   # │ ---           ┆ ---           │
+    #   # │ array[i64, 3] ┆ array[i64, 3] │
+    #   # ╞═══════════════╪═══════════════╡
+    #   # │ [1, 2, 3]     ┆ [null, 1, 2]  │
+    #   # │ [4, 5, 6]     ┆ [null, 4, 5]  │
+    #   # └───────────────┴───────────────┘
+    #
+    # @example Pass a negative value to shift in the opposite direction instead.
+    #   df.with_columns(shift: Polars.col("a").arr.shift(-2))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌───────────────┬─────────────────┐
+    #   # │ a             ┆ shift           │
+    #   # │ ---           ┆ ---             │
+    #   # │ array[i64, 3] ┆ array[i64, 3]   │
+    #   # ╞═══════════════╪═════════════════╡
+    #   # │ [1, 2, 3]     ┆ [3, null, null] │
+    #   # │ [4, 5, 6]     ┆ [6, null, null] │
+    #   # └───────────────┴─────────────────┘
+    def shift(n = 1)
+      n = Utils.parse_into_expression(n)
+      Utils.wrap_expr(_rbexpr.arr_shift(n))
+    end
+
+    # Run any polars expression against the arrays' elements.
+    #
+    # @param expr [Expr]
+    #   Expression to run. Note that you can select an element with `Polars.element`
+    # @param as_list [Boolean]
+    #   Collect the resulting data as a list. This allows for expressions which
+    #   output a variable amount of data.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [1, 8, 3], "b" => [4, 5, 2]})
+    #   df.with_columns(rank: Polars.concat_arr("a", "b").arr.eval(Polars.element.rank))
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬─────┬───────────────┐
+    #   # │ a   ┆ b   ┆ rank          │
+    #   # │ --- ┆ --- ┆ ---           │
+    #   # │ i64 ┆ i64 ┆ array[f64, 2] │
+    #   # ╞═════╪═════╪═══════════════╡
+    #   # │ 1   ┆ 4   ┆ [1.0, 2.0]    │
+    #   # │ 8   ┆ 5   ┆ [2.0, 1.0]    │
+    #   # │ 3   ┆ 2   ┆ [2.0, 1.0]    │
+    #   # └─────┴─────┴───────────────┘
+    def eval(expr, as_list: false)
+      Utils.wrap_expr(_rbexpr.arr_eval(expr._rbexpr, as_list))
+    end
+
+    # Run any polars aggregation expression against the arrays' elements.
+    #
+    # @param expr [Expr]
+    #   Expression to run. Note that you can select an element with `Polars.element`.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::Series.new(
+    #     "a", [[1, nil], [42, 13], [nil, nil]], dtype: Polars::Array.new(Polars::Int64, 2)
+    #   ).to_frame
+    #   df.with_columns(null_count: Polars.col("a").arr.agg(Polars.element.null_count))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌───────────────┬────────────┐
+    #   # │ a             ┆ null_count │
+    #   # │ ---           ┆ ---        │
+    #   # │ array[i64, 2] ┆ u32        │
+    #   # ╞═══════════════╪════════════╡
+    #   # │ [1, null]     ┆ 1          │
+    #   # │ [42, 13]      ┆ 0          │
+    #   # │ [null, null]  ┆ 2          │
+    #   # └───────────────┴────────────┘
+    #
+    # @example
+    #   df.with_columns(no_nulls: Polars.col("a").arr.agg(Polars.element.drop_nulls))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌───────────────┬───────────┐
+    #   # │ a             ┆ no_nulls  │
+    #   # │ ---           ┆ ---       │
+    #   # │ array[i64, 2] ┆ list[i64] │
+    #   # ╞═══════════════╪═══════════╡
+    #   # │ [1, null]     ┆ [1]       │
+    #   # │ [42, 13]      ┆ [42, 13]  │
+    #   # │ [null, null]  ┆ []        │
+    #   # └───────────────┴───────────┘
+    def agg(expr)
+      Utils.wrap_expr(_rbexpr.arr_agg(expr._rbexpr))
+    end
   end
 end