polars-df 0.21.0-arm64-darwin → 0.22.0-arm64-darwin

data/lib/polars/list_expr.rb

@@ -80,10 +80,10 @@ module Polars
     #   # │ 2   │
     #   # │ 1   │
     #   # └─────┘
-    def lengths
+    def len
       Utils.wrap_expr(_rbexpr.list_len)
     end
-    alias_method :len, :lengths
+    alias_method :lengths, :len
 
     # Drop all null values in the list.
     #
@@ -243,6 +243,79 @@ 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 reverse [Boolean]
@@ -322,6 +395,31 @@ module Polars
       Utils.wrap_expr(_rbexpr.list_unique(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
+      Utils.wrap_expr(_rbexpr.list_n_unique)
+    end
+
     # Concat the arrays in a Series dtype List in linear time.
     #
     # @param other [Object]
@@ -366,7 +464,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
@@ -438,6 +536,48 @@ module Polars
     end
     alias_method :take, :gather
 
+    # 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
+
     # Get the first value of the sublists.
     #
     # @return [Expr]
@@ -702,7 +842,32 @@ 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.
+    #
+    # @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
+      Utils.wrap_expr(_rbexpr.explode)
+    end
+
+    # Count how often the value produced by `element` occurs.
     #
     # @param element [Expr]
     #   An expression that produces a single value
@@ -730,10 +895,37 @@ module Polars
     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.
+    #   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.
@@ -753,20 +945,28 @@ module Polars
     # @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} │
-    #   # └────────────┘
+    #   # shape: (2, 2)
+    #   # ┌───────────┬───────────┐
+    #   # │ n         ┆ struct    │
+    #   # │ ---       ┆ ---       │
+    #   # │ list[i64] ┆ struct[2] │
+    #   # ╞═══════════╪═══════════╡
+    #   # │ [0, 1]    ┆ {0,1}     │
+    #   # │ [0, 1, 2] ┆ {0,1}     │
+    #   # └───────────┴───────────┘
     def to_struct(n_field_strategy: "first_non_null", fields: nil, upper_bound: nil)
-      Utils.wrap_expr(_rbexpr.list_to_struct(n_field_strategy, fields, 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.

data/lib/polars/list_name_space.rb

@@ -66,7 +66,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new([[1, 2, 3], [5]])
-    #   s.list.lengths
+    #   s.list.len
     #   # =>
     #   # shape: (2,)
     #   # Series: '' [u32]
@@ -74,9 +74,10 @@ module Polars
     #   #         3
     #   #         1
     #   # ]
-    def lengths
+    def len
       super
     end
+    alias_method :lengths, :len
 
     # Drop all null values in the list.
     #
@@ -202,6 +203,60 @@ module Polars
       super
     end
 
+    # Compute the median value of the arrays in the list.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("values", [[-1, 0, 1], [1, 10]])
+    #   s.list.median
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'values' [f64]
+    #   # [
+    #   #         0.0
+    #   #         5.5
+    #   # ]
+    def median
+      super
+    end
+
+    # Compute the std value of the arrays in the list.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("values", [[-1, 0, 1], [1, 10]])
+    #   s.list.std
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'values' [f64]
+    #   # [
+    #   #         1.0
+    #   #         6.363961
+    #   # ]
+    def std(ddof: 1)
+      super
+    end
+
+    # Compute the var value of the arrays in the list.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("values", [[-1, 0, 1], [1, 10]])
+    #   s.list.var
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'values' [f64]
+    #   # [
+    #   #         1.0
+    #   #         40.5
+    #   # ]
+    def var(ddof: 1)
+      super
+    end
+
     # Sort the arrays in the list.
     #
     # @return [Series]
@@ -254,7 +309,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [[1, 1, 2], [2, 3, 3]])
-    #   s.list.unique()
+    #   s.list.unique
     #   # =>
     #   # shape: (2,)
     #   # Series: 'a' [list[i64]]
@@ -266,6 +321,24 @@ module Polars
       super
     end
 
+    # Count the number of unique values in every sub-lists.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 1, 2], [2, 3, 4]])
+    #   s.list.n_unique
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [u32]
+    #   # [
+    #   #         2
+    #   #         3
+    #   # ]
+    def n_unique
+      super
+    end
+
     # Concat the arrays in a Series dtype List in linear time.
     #
     # @param other [Object]
@@ -292,7 +365,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
@@ -318,6 +391,63 @@ module Polars
       super
     end
 
+    # Take sublists by multiple indices.
+    #
+    # The indices may be defined in a single column, or by sublists in another
+    # column of dtype `List`.
+    #
+    # @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
+    #   Note that defaulting to raising an error is much cheaper
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[3, 2, 1], [], [1, 2]])
+    #   s.list.gather([0, 2], null_on_oob: true)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [list[i64]]
+    #   # [
+    #   #         [3, 1]
+    #   #         [null, null]
+    #   #         [1, null]
+    #   # ]
+    def gather(
+      indices,
+      null_on_oob: false
+    )
+      super
+    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 [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2, 3], [], [6, 7, 8, 9]])
+    #   s.list.gather_every(2, 1)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [list[i64]]
+    #   # [
+    #   #         [2]
+    #   #         []
+    #   #         [7, 9]
+    #   # ]
+    def gather_every(n, offset = 0)
+      super
+    end
+
     # Get the value by index in the sublists.
     #
     # @return [Series]
@@ -554,33 +684,112 @@ module Polars
       super
     end
 
-    # Convert the series of type `List` to a series of type `Struct`.
+    # Returns a column with a separate row for every list element.
     #
-    # @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`
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2, 3], [4, 5, 6]])
+    #   s.list.explode
+    #   # =>
+    #   # shape: (6,)
+    #   # Series: 'a' [i64]
+    #   # [
+    #   #         1
+    #   #         2
+    #   #         3
+    #   #         4
+    #   #         5
+    #   #         6
+    #   # ]
+    def explode
+      super
+    end
+
+    # Count how often the value produced by `element` occurs.
+    #
+    # @param element [Object]
+    #   An expression that produces a single value
     #
     # @return [Series]
     #
     # @example
-    #   df = Polars::DataFrame.new({"a" => [[1, 2, 3], [1, 2]]})
-    #   df.select([Polars.col("a").list.to_struct])
+    #   s = Polars::Series.new("a", [[0], [1], [1, 2, 3, 2], [1, 2, 1], [4, 4]])
+    #   s.list.count_matches(1)
     #   # =>
-    #   # shape: (2, 1)
-    #   # ┌────────────┐
-    #   # │ a          │
-    #   # │ ---        │
-    #   # │ struct[3]  │
-    #   # ╞════════════╡
-    #   # │ {1,2,3}    │
-    #   # │ {1,2,null} │
-    #   # └────────────┘
-    def to_struct(n_field_strategy: "first_non_null", name_generator: nil)
+    #   # shape: (5,)
+    #   # Series: 'a' [u32]
+    #   # [
+    #   #         0
+    #   #         1
+    #   #         1
+    #   #         2
+    #   #         0
+    #   # ]
+    def count_matches(element)
       super
     end
 
+    # Convert a List column into an Array column with the same inner data type.
+    #
+    # @param width [Integer]
+    #   Width of the resulting Array column.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([[1, 2], [3, 4]], dtype: Polars::List.new(Polars::Int8))
+    #   s.list.to_array(2)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [array[i8, 2]]
+    #   # [
+    #   #         [1, 2]
+    #   #         [3, 4]
+    #   # ]
+    def to_array(width)
+      super
+    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 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 [Series]
+    #
+    # @example Convert list to struct with field name assignment by index from a list of names:
+    #   s1 = Polars::Series.new("n", [[0, 1, 2], [0, 1]])
+    #   s1.list.to_struct(fields: ["one", "two", "three"]).struct.unnest
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌─────┬─────┬───────┐
+    #   # │ one ┆ two ┆ three │
+    #   # │ --- ┆ --- ┆ ---   │
+    #   # │ i64 ┆ i64 ┆ i64   │
+    #   # ╞═════╪═════╪═══════╡
+    #   # │ 0   ┆ 1   ┆ 2     │
+    #   # │ 0   ┆ 1   ┆ null  │
+    #   # └─────┴─────┴───────┘
+    def to_struct(n_field_strategy: "first_non_null", fields: nil)
+      if fields.is_a?(::Array)
+        s = Utils.wrap_s(_s)
+        return (
+          s.to_frame
+          .select_seq(F.col(s.name).list.to_struct(fields: fields))
+          .to_series
+        )
+      end
+
+      raise Todo
+      # Utils.wrap_s(_s.list_to_struct(n_field_strategy, fields))
+    end
+
     # Run any polars expression against the lists' elements.
     #
     # @param expr [Expr]