polars-df 0.15.0 → 0.26.0

data/lib/polars/list_expr.rb

@@ -11,6 +11,13 @@ module Polars
 
     # Evaluate whether all boolean values in a list are true.
     #
+    # @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
@@ -32,12 +39,19 @@ module Polars
     #   # │ []             ┆ true  │
     #   # │ null           ┆ null  │
     #   # └────────────────┴───────┘
-    def all
-      Utils.wrap_expr(_rbexpr.list_all)
+    def all(ignore_nulls: true)
+      agg(F.element.all(ignore_nulls: ignore_nulls))
     end
 
     # Evaluate whether any boolean value in a list is true.
     #
+    # @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
@@ -59,8 +73,8 @@ module Polars
     #   # │ []             ┆ false │
     #   # │ null           ┆ null  │
     #   # └────────────────┴───────┘
-    def any
-      Utils.wrap_expr(_rbexpr.list_any)
+    def any(ignore_nulls: true)
+      agg(F.element.any(ignore_nulls: ignore_nulls))
     end
 
     # Get the length of the arrays as `:u32`.
@@ -69,7 +83,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [1, 2], "bar" => [["a", "b"], ["c"]]})
-    #   df.select(Polars.col("bar").list.lengths)
+    #   df.select(Polars.col("bar").list.len)
     #   # =>
     #   # shape: (2, 1)
     #   # ┌─────┐
@@ -80,10 +94,9 @@ module Polars
     #   # │ 2   │
     #   # │ 1   │
     #   # └─────┘
-    def lengths
+    def len
       Utils.wrap_expr(_rbexpr.list_len)
     end
-    alias_method :len, :lengths
 
     # Drop all null values in the list.
     #
@@ -136,7 +149,7 @@ module Polars
     #   # │ ---       ┆ --- ┆ ---       │
     #   # │ list[i64] ┆ i64 ┆ list[i64] │
     #   # ╞═══════════╪═════╪═══════════╡
-    #   # │ [1, 2, 3] ┆ 2   ┆ [2, 1]    │
+    #   # │ [1, 2, 3] ┆ 2   ┆ [2, 3]    │
     #   # │ [4, 5]    ┆ 1   ┆ [5]       │
     #   # └───────────┴─────┴───────────┘
     def sample(n: nil, fraction: nil, with_replacement: false, shuffle: false, seed: nil)
@@ -243,8 +256,86 @@ module Polars
       Utils.wrap_expr(_rbexpr.list_mean)
     end
 
+    # Compute the median value of the lists in the array.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"values" => [[-1, 0, 1], [1, 10]]})
+    #   df.with_columns(Polars.col("values").list.median.alias("median"))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌────────────┬────────┐
+    #   # │ values     ┆ median │
+    #   # │ ---        ┆ ---    │
+    #   # │ list[i64]  ┆ f64    │
+    #   # ╞════════════╪════════╡
+    #   # │ [-1, 0, 1] ┆ 0.0    │
+    #   # │ [1, 10]    ┆ 5.5    │
+    #   # └────────────┴────────┘
+    def median
+      Utils.wrap_expr(_rbexpr.list_median)
+    end
+
+    # Compute the std value of the lists in the array.
+    #
+    # @param ddof [Integer]
+    #   “Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof,
+    #   where N represents the number of elements.
+    #   By default ddof is 1.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"values" => [[-1, 0, 1], [1, 10]]})
+    #   df.with_columns(Polars.col("values").list.std.alias("std"))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌────────────┬──────────┐
+    #   # │ values     ┆ std      │
+    #   # │ ---        ┆ ---      │
+    #   # │ list[i64]  ┆ f64      │
+    #   # ╞════════════╪══════════╡
+    #   # │ [-1, 0, 1] ┆ 1.0      │
+    #   # │ [1, 10]    ┆ 6.363961 │
+    #   # └────────────┴──────────┘
+    def std(ddof: 1)
+      Utils.wrap_expr(_rbexpr.list_std(ddof))
+    end
+
+    # Compute the var value of the lists in the array.
+    #
+    # @param ddof [Integer]
+    #   “Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof,
+    #   where N represents the number of elements.
+    #   By default ddof is 1.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"values" => [[-1, 0, 1], [1, 10]]})
+    #   df.with_columns(Polars.col("values").list.var.alias("var"))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌────────────┬──────┐
+    #   # │ values     ┆ var  │
+    #   # │ ---        ┆ ---  │
+    #   # │ list[i64]  ┆ f64  │
+    #   # ╞════════════╪══════╡
+    #   # │ [-1, 0, 1] ┆ 1.0  │
+    #   # │ [1, 10]    ┆ 40.5 │
+    #   # └────────────┴──────┘
+    def var(ddof: 1)
+      Utils.wrap_expr(_rbexpr.list_var(ddof))
+    end
+
     # Sort the arrays in the list.
     #
+    # @param descending [Boolean]
+    #   Sort in descending order.
+    # @param nulls_last [Boolean]
+    #   Place null values last.
+    #
     # @return [Expr]
     #
     # @example
@@ -264,8 +355,8 @@ module Polars
     #   # │ [1, 2, 3] │
     #   # │ [1, 2, 9] │
     #   # └───────────┘
-    def sort(reverse: false)
-      Utils.wrap_expr(_rbexpr.list_sort(reverse))
+    def sort(descending: false, nulls_last: false)
+      Utils.wrap_expr(_rbexpr.list_sort(descending, nulls_last))
     end
 
     # Reverse the arrays in the list.
@@ -290,7 +381,7 @@ module Polars
     #   # │ [2, 1, 9] │
     #   # └───────────┘
     def reverse
-      Utils.wrap_expr(_rbexpr.list_reverse)
+      eval(F.element.reverse)
     end
 
     # Get the unique/distinct values in the list.
@@ -314,7 +405,32 @@ module Polars
     #   # │ [1, 2]    │
     #   # └───────────┘
     def unique(maintain_order: false)
-      Utils.wrap_expr(_rbexpr.list_unique(maintain_order))
+      eval(F.element.unique(maintain_order: maintain_order))
+    end
+
+    # Count the number of unique values in every sub-lists.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [[1, 1, 2], [2, 3, 4]]
+    #     }
+    #   )
+    #   df.with_columns(n_unique: Polars.col("a").list.n_unique)
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌───────────┬──────────┐
+    #   # │ a         ┆ n_unique │
+    #   # │ ---       ┆ ---      │
+    #   # │ list[i64] ┆ u32      │
+    #   # ╞═══════════╪══════════╡
+    #   # │ [1, 1, 2] ┆ 2        │
+    #   # │ [2, 3, 4] ┆ 3        │
+    #   # └───────────┴──────────┘
+    def n_unique
+      agg(F.element.n_unique)
     end
 
     # Concat the arrays in a Series dtype List in linear time.
@@ -361,7 +477,7 @@ module Polars
     #
     # So index `0` would return the first item of every sublist
     # and index `-1` would return the last item of every sublist
-    # if an index is out of bounds, it will return a `None`.
+    # if an index is out of bounds, it will return a `nil`.
     #
     # @param index [Integer]
     #   Index to return per sublist
@@ -374,7 +490,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [[3, 2, 1], [], [1, 2]]})
-    #   df.select(Polars.col("foo").list.get(0))
+    #   df.select(Polars.col("foo").list.get(0, null_on_oob: true))
     #   # =>
     #   # shape: (3, 1)
     #   # ┌──────┐
@@ -386,7 +502,7 @@ module Polars
     #   # │ null │
     #   # │ 1    │
     #   # └──────┘
-    def get(index, null_on_oob: true)
+    def get(index, null_on_oob: false)
       index = Utils.parse_into_expression(index)
       Utils.wrap_expr(_rbexpr.list_get(index, null_on_oob))
     end
@@ -403,12 +519,12 @@ module Polars
     # The indices may be defined in a single column, or by sublists in another
     # column of dtype `List`.
     #
-    # @param index [Object]
+    # @param indices [Object]
     #   Indices to return per sublist
     # @param null_on_oob [Boolean]
     #   Behavior if an index is out of bounds:
-    #   True -> set as null
-    #   False -> raise an error
+    #   true -> set as null
+    #   false -> raise an error
     #   Note that defaulting to raising an error is much cheaper
     #
     # @return [Expr]
@@ -427,14 +543,52 @@ module Polars
     #   # │ []          ┆ [null, null] │
     #   # │ [1, 2, … 5] ┆ [1, 5]       │
     #   # └─────────────┴──────────────┘
-    def gather(index, null_on_oob: false)
-      if index.is_a?(::Array)
-        index = Series.new(index)
-      end
-      index = Utils.parse_into_expression(index, str_as_lit: false)
-      Utils.wrap_expr(_rbexpr.list_gather(index, null_on_oob))
+    def gather(indices, null_on_oob: false)
+      indices = Utils.parse_into_expression(indices)
+      Utils.wrap_expr(_rbexpr.list_gather(indices, null_on_oob))
+    end
+
+    # Take every n-th value start from offset in sublists.
+    #
+    # @param n [Integer]
+    #   Gather every n-th element.
+    # @param offset [Integer]
+    #   Starting index.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [[1, 2, 3, 4, 5], [6, 7, 8], [9, 10, 11, 12]],
+    #       "n" => [2, 1, 3],
+    #       "offset" => [0, 1, 0]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     gather_every: Polars.col("a").list.gather_every(
+    #       Polars.col("n"), Polars.col("offset")
+    #     )
+    #   )
+    #   # =>
+    #   # shape: (3, 4)
+    #   # ┌───────────────┬─────┬────────┬──────────────┐
+    #   # │ a             ┆ n   ┆ offset ┆ gather_every │
+    #   # │ ---           ┆ --- ┆ ---    ┆ ---          │
+    #   # │ list[i64]     ┆ i64 ┆ i64    ┆ list[i64]    │
+    #   # ╞═══════════════╪═════╪════════╪══════════════╡
+    #   # │ [1, 2, … 5]   ┆ 2   ┆ 0      ┆ [1, 3, 5]    │
+    #   # │ [6, 7, 8]     ┆ 1   ┆ 1      ┆ [7, 8]       │
+    #   # │ [9, 10, … 12] ┆ 3   ┆ 0      ┆ [9, 12]      │
+    #   # └───────────────┴─────┴────────┴──────────────┘
+    def gather_every(
+      n,
+      offset = 0
+    )
+      n = Utils.parse_into_expression(n)
+      offset = Utils.parse_into_expression(offset)
+      Utils.wrap_expr(_rbexpr.list_gather_every(n, offset))
     end
-    alias_method :take, :gather
 
     # Get the first value of the sublists.
     #
@@ -455,7 +609,7 @@ module Polars
     #   # │ 1    │
     #   # └──────┘
     def first
-      get(0)
+      get(0, null_on_oob: true)
     end
 
     # Get the last value of the sublists.
@@ -477,13 +631,57 @@ module Polars
     #   # │ 2    │
     #   # └──────┘
     def last
-      get(-1)
+      get(-1, null_on_oob: true)
+    end
+
+    # Get the single value of the sublists.
+    #
+    # This errors if the sublist length is not exactly one.
+    #
+    # @param allow_empty [Boolean]
+    #   Allow having no values to return `null`.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [[3], [1], [2]]})
+    #   df.with_columns(item: Polars.col("a").list.item)
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌───────────┬──────┐
+    #   # │ a         ┆ item │
+    #   # │ ---       ┆ ---  │
+    #   # │ list[i64] ┆ i64  │
+    #   # ╞═══════════╪══════╡
+    #   # │ [3]       ┆ 3    │
+    #   # │ [1]       ┆ 1    │
+    #   # │ [2]       ┆ 2    │
+    #   # └───────────┴──────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [[], [1], [2]]})
+    #   df.select(Polars.col("a").list.item(allow_empty: true))
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌──────┐
+    #   # │ a    │
+    #   # │ ---  │
+    #   # │ i64  │
+    #   # ╞══════╡
+    #   # │ null │
+    #   # │ 1    │
+    #   # │ 2    │
+    #   # └──────┘
+    def item(allow_empty: false)
+      agg(F.element.item(allow_empty: allow_empty))
     end
 
     # Check if sublists 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,8 +699,8 @@ module Polars
     #   # │ false │
     #   # │ true  │
     #   # └───────┘
-    def contains(item)
-      Utils.wrap_expr(_rbexpr.list_contains(Utils.parse_into_expression(item)))
+    def contains(item, nulls_equal: true)
+      Utils.wrap_expr(_rbexpr.list_contains(Utils.parse_into_expression(item), nulls_equal))
     end
 
     # Join all string items in a sublist and place a separator between them.
@@ -698,7 +896,37 @@ module Polars
       Utils.wrap_expr(_rbexpr.list_tail(n))
     end
 
-    # Count how often the value produced by ``element`` occurs.
+    # Returns a column with a separate row for every list element.
+    #
+    # @param empty_as_null [Boolean]
+    #   Explode an empty list into a `null`.
+    # @param keep_nulls [Boolean]
+    #   Explode a `null` list into a `null`.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [[1, 2, 3], [4, 5, 6]]})
+    #   df.select(Polars.col("a").list.explode)
+    #   # =>
+    #   # shape: (6, 1)
+    #   # ┌─────┐
+    #   # │ a   │
+    #   # │ --- │
+    #   # │ i64 │
+    #   # ╞═════╡
+    #   # │ 1   │
+    #   # │ 2   │
+    #   # │ 3   │
+    #   # │ 4   │
+    #   # │ 5   │
+    #   # │ 6   │
+    #   # └─────┘
+    def explode(empty_as_null: true, keep_nulls: true)
+      Utils.wrap_expr(_rbexpr.explode(empty_as_null, keep_nulls))
+    end
+
+    # Count how often the value produced by `element` occurs.
     #
     # @param element [Expr]
     #   An expression that produces a single value
@@ -707,7 +935,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"listcol" => [[0], [1], [1, 2, 3, 2], [1, 2, 1], [4, 4]]})
-    #   df.select(Polars.col("listcol").list.count_match(2).alias("number_of_twos"))
+    #   df.select(Polars.col("listcol").list.count_matches(2).alias("number_of_twos"))
     #   # =>
     #   # shape: (5, 1)
     #   # ┌────────────────┐
@@ -724,34 +952,79 @@ module Polars
     def count_matches(element)
       Utils.wrap_expr(_rbexpr.list_count_matches(Utils.parse_into_expression(element)))
     end
-    alias_method :count_match, :count_matches
+
+    # Convert a List column into an Array column with the same inner data type.
+    #
+    # @param width [Integer]
+    #   Width of the resulting Array column.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => [[1, 2], [3, 4]]},
+    #     schema: {"a" => Polars::List.new(Polars::Int8)}
+    #   )
+    #   df.with_columns(array: Polars.col("a").list.to_array(2))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌──────────┬──────────────┐
+    #   # │ a        ┆ array        │
+    #   # │ ---      ┆ ---          │
+    #   # │ list[i8] ┆ array[i8, 2] │
+    #   # ╞══════════╪══════════════╡
+    #   # │ [1, 2]   ┆ [1, 2]       │
+    #   # │ [3, 4]   ┆ [3, 4]       │
+    #   # └──────────┴──────────────┘
+    def to_array(width)
+      Utils.wrap_expr(_rbexpr.list_to_array(width))
+    end
 
     # Convert the series of type `List` to a series of type `Struct`.
     #
     # @param n_field_strategy ["first_non_null", "max_width"]
-    #   Strategy to determine the number of fields of the struct.
-    # @param name_generator [Object]
-    #   A custom function that can be used to generate the field names.
-    #   Default field names are `field_0, field_1 .. field_n`
+    #   Deprecated and ignored.
+    # @param fields pArray
+    #   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`.
+    # @param upper_bound [Object]
+    #   A polars `LazyFrame` needs to know the schema at all times, so the
+    #   caller must provide an upper bound of the number of struct fields that
+    #   will be created; if set incorrectly, subsequent operations may fail.
+    #   (For example, an `all.sum` expression will look in the current
+    #   schema to determine which columns to select).
+    #
+    #   When operating on a `DataFrame`, the schema does not need to be
+    #   tracked or pre-determined, as the result will be eagerly evaluated,
+    #   so you can leave this parameter unset.
     #
     # @return [Expr]
     #
     # @example
-    #   df = Polars::DataFrame.new({"a" => [[1, 2, 3], [1, 2]]})
-    #   df.select([Polars.col("a").list.to_struct])
+    #   df = Polars::DataFrame.new({"n" => [[0, 1], [0, 1, 2]]})
+    #   df.with_columns(struct: Polars.col("n").list.to_struct(upper_bound: 2))
     #   # =>
-    #   # shape: (2, 1)
-    #   # ┌────────────┐
-    #   # │ a          │
-    #   # │ ---        │
-    #   # │ struct[3]  │
-    #   # ╞════════════╡
-    #   # │ {1,2,3}    │
-    #   # │ {1,2,null} │
-    #   # └────────────┘
-    def to_struct(n_field_strategy: "first_non_null", name_generator: nil)
-      raise Todo if name_generator
-      Utils.wrap_expr(_rbexpr.list_to_struct(n_field_strategy, name_generator, 0))
+    #   # shape: (2, 2)
+    #   # ┌───────────┬───────────┐
+    #   # │ n         ┆ struct    │
+    #   # │ ---       ┆ ---       │
+    #   # │ list[i64] ┆ struct[2] │
+    #   # ╞═══════════╪═══════════╡
+    #   # │ [0, 1]    ┆ {0,1}     │
+    #   # │ [0, 1, 2] ┆ {0,1}     │
+    #   # └───────────┴───────────┘
+    def to_struct(n_field_strategy: nil, fields: nil, upper_bound: nil)
+      if !fields.is_a?(::Array)
+        if fields.nil?
+          fields = upper_bound.times.map { |i| "field_#{i}" }
+        else
+          fields = upper_bound.times.map { |i| fields.(i) }
+        end
+      end
+
+      Utils.wrap_expr(_rbexpr.list_to_struct(fields))
     end
 
     # Run any polars expression against the lists' elements.
@@ -759,18 +1032,12 @@ module Polars
     # @param expr [Expr]
     #   Expression to run. Note that you can select an element with `Polars.first`, or
     #   `Polars.col`
-    # @param parallel [Boolean]
-    #   Run all expression parallel. Don't activate this blindly.
-    #   Parallelism is worth it if there is enough work to do per thread.
-    #
-    #   This likely should not be use in the group by context, because we already
-    #   parallel execution per group
     #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new({"a" => [1, 8, 3], "b" => [4, 5, 2]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.concat_list(["a", "b"]).list.eval(Polars.element.rank).alias("rank")
     #   )
     #   # =>
@@ -784,8 +1051,233 @@ module Polars
     #   # │ 8   ┆ 5   ┆ [2.0, 1.0] │
     #   # │ 3   ┆ 2   ┆ [2.0, 1.0] │
     #   # └─────┴─────┴────────────┘
-    def eval(expr, parallel: false)
-      Utils.wrap_expr(_rbexpr.list_eval(expr._rbexpr, parallel))
+    def eval(expr)
+      Utils.wrap_expr(_rbexpr.list_eval(expr._rbexpr))
+    end
+
+    # Run any polars aggregation expression against the lists' elements.
+    #
+    # @param expr [Expr]
+    #   Expression to run. Note that you can select an element with `Polars.element`.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [[1, nil], [42, 13], [nil, nil]]})
+    #   df.with_columns(null_count: Polars.col("a").list.agg(Polars.element.null_count))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌──────────────┬────────────┐
+    #   # │ a            ┆ null_count │
+    #   # │ ---          ┆ ---        │
+    #   # │ list[i64]    ┆ u32        │
+    #   # ╞══════════════╪════════════╡
+    #   # │ [1, null]    ┆ 1          │
+    #   # │ [42, 13]     ┆ 0          │
+    #   # │ [null, null] ┆ 2          │
+    #   # └──────────────┴────────────┘
+    #
+    # @example
+    #   df.with_columns(no_nulls: Polars.col("a").list.agg(Polars.element.drop_nulls))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌──────────────┬───────────┐
+    #   # │ a            ┆ no_nulls  │
+    #   # │ ---          ┆ ---       │
+    #   # │ list[i64]    ┆ list[i64] │
+    #   # ╞══════════════╪═══════════╡
+    #   # │ [1, null]    ┆ [1]       │
+    #   # │ [42, 13]     ┆ [42, 13]  │
+    #   # │ [null, null] ┆ []        │
+    #   # └──────────────┴───────────┘
+    def agg(expr)
+      Utils.wrap_expr(_rbexpr.list_agg(expr._rbexpr))
+    end
+
+    # Filter elements in each list by a boolean expression.
+    #
+    # @param predicate [Object]
+    #   A boolean expression that is evaluated per list element.
+    #   You can refer to the current element with `Polars.element`.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [1, 8, 3], "b" => [4, 5, 2]})
+    #   df.with_columns(
+    #     evens: Polars.concat_list("a", "b").list.filter(Polars.element % 2 == 0)
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬─────┬───────────┐
+    #   # │ a   ┆ b   ┆ evens     │
+    #   # │ --- ┆ --- ┆ ---       │
+    #   # │ i64 ┆ i64 ┆ list[i64] │
+    #   # ╞═════╪═════╪═══════════╡
+    #   # │ 1   ┆ 4   ┆ [4]       │
+    #   # │ 8   ┆ 5   ┆ [8]       │
+    #   # │ 3   ┆ 2   ┆ [2]       │
+    #   # └─────┴─────┴───────────┘
+    def filter(predicate)
+      Utils.wrap_expr(_rbexpr.list_filter(predicate._rbexpr))
+    end
+
+    # Compute the SET UNION between the elements in this list and the elements of `other`.
+    #
+    # @param other [Object]
+    #   Right hand side of the set operation.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [[1, 2, 3], [], [nil, 3], [5, 6, 7]],
+    #       "b" => [[2, 3, 4], [3], [3, 4, nil], [6, 8]]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     union: Polars.col("a").list.set_union("b")
+    #   )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌───────────┬──────────────┬──────────────┐
+    #   # │ a         ┆ b            ┆ union        │
+    #   # │ ---       ┆ ---          ┆ ---          │
+    #   # │ list[i64] ┆ list[i64]    ┆ list[i64]    │
+    #   # ╞═══════════╪══════════════╪══════════════╡
+    #   # │ [1, 2, 3] ┆ [2, 3, 4]    ┆ [1, 2, … 4]  │
+    #   # │ []        ┆ [3]          ┆ [3]          │
+    #   # │ [null, 3] ┆ [3, 4, null] ┆ [null, 3, 4] │
+    #   # │ [5, 6, 7] ┆ [6, 8]       ┆ [5, 6, … 8]  │
+    #   # └───────────┴──────────────┴──────────────┘
+    def set_union(other)
+      if other.respond_to?(:each)
+        if !other.is_a?(::Array) && !other.is_a?(Series) && !other.is_a?(DataFrame)
+          other = other.to_a
+        end
+        other = F.lit(other)._rbexpr
+      else
+        other = Utils.parse_into_expression(other)
+      end
+      Utils.wrap_expr(_rbexpr.list_set_operation(other, "union"))
+    end
+
+    # Compute the SET DIFFERENCE between the elements in this list and the elements of `other`.
+    #
+    # @param other [Object]
+    #   Right hand side of the set operation.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [[1, 2, 3], [], [nil, 3], [5, 6, 7]],
+    #       "b" => [[2, 3, 4], [3], [3, 4, nil], [6, 8]]
+    #     }
+    #   )
+    #   df.with_columns(difference: Polars.col("a").list.set_difference("b"))
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌───────────┬──────────────┬────────────┐
+    #   # │ a         ┆ b            ┆ difference │
+    #   # │ ---       ┆ ---          ┆ ---        │
+    #   # │ list[i64] ┆ list[i64]    ┆ list[i64]  │
+    #   # ╞═══════════╪══════════════╪════════════╡
+    #   # │ [1, 2, 3] ┆ [2, 3, 4]    ┆ [1]        │
+    #   # │ []        ┆ [3]          ┆ []         │
+    #   # │ [null, 3] ┆ [3, 4, null] ┆ []         │
+    #   # │ [5, 6, 7] ┆ [6, 8]       ┆ [5, 7]     │
+    #   # └───────────┴──────────────┴────────────┘
+    def set_difference(other)
+      if other.respond_to?(:each)
+        if !other.is_a?(::Array) && !other.is_a?(Series) && !other.is_a?(DataFrame)
+          other = other.to_a
+        end
+        other = F.lit(other)._rbexpr
+      else
+        other = Utils.parse_into_expression(other)
+      end
+      Utils.wrap_expr(_rbexpr.list_set_operation(other, "difference"))
+    end
+
+    # Compute the SET INTERSECTION between the elements in this list and the elements of `other`.
+    #
+    # @param other [Object]
+    #   Right hand side of the set operation.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [[1, 2, 3], [], [nil, 3], [5, 6, 7]],
+    #       "b" => [[2, 3, 4], [3], [3, 4, nil], [6, 8]]
+    #     }
+    #   )
+    #   df.with_columns(intersection: Polars.col("a").list.set_intersection("b"))
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌───────────┬──────────────┬──────────────┐
+    #   # │ a         ┆ b            ┆ intersection │
+    #   # │ ---       ┆ ---          ┆ ---          │
+    #   # │ list[i64] ┆ list[i64]    ┆ list[i64]    │
+    #   # ╞═══════════╪══════════════╪══════════════╡
+    #   # │ [1, 2, 3] ┆ [2, 3, 4]    ┆ [2, 3]       │
+    #   # │ []        ┆ [3]          ┆ []           │
+    #   # │ [null, 3] ┆ [3, 4, null] ┆ [null, 3]    │
+    #   # │ [5, 6, 7] ┆ [6, 8]       ┆ [6]          │
+    #   # └───────────┴──────────────┴──────────────┘
+    def set_intersection(other)
+      if other.respond_to?(:each)
+        if !other.is_a?(::Array) && !other.is_a?(Series) && !other.is_a?(DataFrame)
+          other = other.to_a
+        end
+        other = F.lit(other)._rbexpr
+      else
+        other = Utils.parse_into_expression(other)
+      end
+      Utils.wrap_expr(_rbexpr.list_set_operation(other, "intersection"))
+    end
+
+    # Compute the SET SYMMETRIC DIFFERENCE between the elements in this list and the elements of `other`.
+    #
+    # @param other [Object]
+    #   Right hand side of the set operation.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [[1, 2, 3], [], [nil, 3], [5, 6, 7]],
+    #       "b" => [[2, 3, 4], [3], [3, 4, nil], [6, 8]]
+    #     }
+    #   )
+    #   df.with_columns(sdiff: Polars.col("b").list.set_symmetric_difference("a"))
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌───────────┬──────────────┬───────────┐
+    #   # │ a         ┆ b            ┆ sdiff     │
+    #   # │ ---       ┆ ---          ┆ ---       │
+    #   # │ list[i64] ┆ list[i64]    ┆ list[i64] │
+    #   # ╞═══════════╪══════════════╪═══════════╡
+    #   # │ [1, 2, 3] ┆ [2, 3, 4]    ┆ [4, 1]    │
+    #   # │ []        ┆ [3]          ┆ [3]       │
+    #   # │ [null, 3] ┆ [3, 4, null] ┆ [4]       │
+    #   # │ [5, 6, 7] ┆ [6, 8]       ┆ [8, 5, 7] │
+    #   # └───────────┴──────────────┴───────────┘
+    def set_symmetric_difference(other)
+      if other.respond_to?(:each)
+        if !other.is_a?(::Array) && !other.is_a?(Series) && !other.is_a?(DataFrame)
+          other = other.to_a
+        end
+        other = F.lit(other)._rbexpr
+      else
+        other = Utils.parse_into_expression(other)
+      end
+      Utils.wrap_expr(_rbexpr.list_set_operation(other, "symmetric_difference"))
     end
   end
 end