polars-df 0.21.0 → 0.21.1

data/lib/polars/array_name_space.rb

@@ -74,6 +74,60 @@ module Polars
       super
     end
 
+    # Compute the std of the values of the sub-arrays.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2], [4, 3]], dtype: Polars::Array.new(Polars::Int64, 2))
+    #   s.arr.std
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [f64]
+    #   # [
+    #   #         0.707107
+    #   #         0.707107
+    #   # ]
+    def std(ddof: 1)
+      super
+    end
+
+    # Compute the var of the values of the sub-arrays.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2], [4, 3]], dtype: Polars::Array.new(Polars::Int64, 2))
+    #   s.arr.var
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [f64]
+    #   # [
+    #   #         0.5
+    #   #         0.5
+    #   # ]
+    def var(ddof: 1)
+      super
+    end
+
+    # Compute the median of the values of the sub-arrays.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2], [4, 3]], dtype: Polars::Array.new(Polars::Int64, 2))
+    #   s.arr.median
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [f64]
+    #   # [
+    #   #         1.5
+    #   #         3.5
+    #   # ]
+    def median
+      super
+    end
+
     # Get the unique/distinct values in the array.
     #
     # @param maintain_order [Boolean]
@@ -102,6 +156,24 @@ module Polars
       super
     end
 
+    # Count the number of unique values in every sub-arrays.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2], [4, 4]], dtype: Polars::Array.new(Polars::Int64, 2))
+    #   s.arr.n_unique
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [u32]
+    #   # [
+    #   #         2
+    #   #         1
+    #   # ]
+    def n_unique
+      super
+    end
+
     # Convert an Array column into a List column with the same inner data type.
     #
     # @return [Series]
@@ -144,6 +216,148 @@ module Polars
       super
     end
 
+    # Return the number of elements in each array.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2], [4, 3]], dtype: Polars::Array.new(Polars::Int8, 2))
+    #   s.arr.len
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [u32]
+    #   # [
+    #   #         2
+    #   #         2
+    #   # ]
+    def len
+      super
+    end
+
+    # Slice the sub-arrays.
+    #
+    # @param offset [Integer]
+    #   The starting index of the slice.
+    # @param length [Integer]
+    #   The length of the slice.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(
+    #     [[1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12]],
+    #     dtype: Polars::Array.new(Polars::Int64, 6)
+    #   )
+    #   s.arr.slice(1)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [list[i64]]
+    #   # [
+    #   #         [2, 3, … 6]
+    #   #         [8, 9, … 12]
+    #   # ]
+    #
+    # @example
+    #   s.arr.slice(1, 3, as_array: true)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [array[i64, 3]]
+    #   # [
+    #   #         [2, 3, 4]
+    #   #         [8, 9, 10]
+    #   # ]
+    #
+    # @example
+    #   s.arr.slice(-2)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [list[i64]]
+    #   # [
+    #   #         [5, 6]
+    #   #         [11, 12]
+    #   # ]
+    def slice(
+      offset,
+      length = nil,
+      as_array: false
+    )
+      super
+    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 [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(
+    #     [[1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12]],
+    #     dtype: Polars::Array.new(Polars::Int64, 6)
+    #   )
+    #   s.arr.head
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [list[i64]]
+    #   # [
+    #   #         [1, 2, … 5]
+    #   #         [7, 8, … 11]
+    #   # ]
+    #
+    # @example
+    #   s.arr.head(3, as_array: true)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [array[i64, 3]]
+    #   # [
+    #   #         [1, 2, 3]
+    #   #         [7, 8, 9]
+    #   # ]
+    def head(n = 5, as_array: false)
+      super
+    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 [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(
+    #     [[1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12]],
+    #     dtype: Polars::Array.new(Polars::Int64, 6)
+    #   )
+    #   s.arr.tail
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [list[i64]]
+    #   # [
+    #   #         [2, 3, … 6]
+    #   #         [8, 9, … 12]
+    #   # ]
+    #
+    # @example
+    #   s.arr.tail(3, as_array: true)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [array[i64, 3]]
+    #   # [
+    #   #         [4, 5, 6]
+    #   #         [10, 11, 12]
+    #   # ]
+    def tail(n = 5, as_array: false)
+      super
+    end
+
     # Evaluate whether all boolean values are true for every subarray.
     #
     # @return [Series]
@@ -419,5 +633,72 @@ module Polars
     def count_matches(element)
       super
     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 [Series]
+    #
+    # @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
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'n' [struct[3]]
+    #   # [
+    #   #         {0,1,2}
+    #   #         {3,4,5}
+    #   # ]
+    #
+    # @example
+    #   s2.struct.fields
+    #   # => ["field_0", "field_1", "field_2"]
+    def to_struct(
+      fields: nil
+    )
+      s = Utils.wrap_s(_s)
+      s.to_frame.select(F.col(s.name).arr.to_struct(fields: fields)).to_series
+    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 [Series]
+    #
+    # @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.
+    #   s = Polars::Series.new([[1, 2, 3], [4, 5, 6]], dtype: Polars::Array.new(Polars::Int64, 3))
+    #   s.arr.shift
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [array[i64, 3]]
+    #   # [
+    #   #         [null, 1, 2]
+    #   #         [null, 4, 5]
+    #   # ]
+    #
+    # @example Pass a negative value to shift in the opposite direction instead.
+    #   s.arr.shift(-2)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [array[i64, 3]]
+    #   # [
+    #   #         [3, null, null]
+    #   #         [6, null, null]
+    #   # ]
+    def shift(n = 1)
+      super
+    end
   end
 end

data/lib/polars/binary_expr.rb

@@ -197,5 +197,72 @@ module Polars
         raise ArgumentError, "encoding must be one of {{'hex', 'base64'}}, got #{encoding}"
       end
     end
+
+    # Get the size of binary values in the given unit.
+    #
+    # @param unit ['b', 'kb', 'mb', 'gb', 'tb']
+    #   Scale the returned size to the given unit.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"data" => [512, 256, 1024].map { |n| "\x00".b * n }})
+    #   df.with_columns(
+    #     n_bytes: Polars.col("data").bin.size,
+    #     n_kilobytes: Polars.col("data").bin.size("kb")
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────────────────────────────────┬─────────┬─────────────┐
+    #   # │ data                            ┆ n_bytes ┆ n_kilobytes │
+    #   # │ ---                             ┆ ---     ┆ ---         │
+    #   # │ binary                          ┆ u32     ┆ f64         │
+    #   # ╞═════════════════════════════════╪═════════╪═════════════╡
+    #   # │ b"\x00\x00\x00\x00\x00\x00\x00… ┆ 512     ┆ 0.5         │
+    #   # │ b"\x00\x00\x00\x00\x00\x00\x00… ┆ 256     ┆ 0.25        │
+    #   # │ b"\x00\x00\x00\x00\x00\x00\x00… ┆ 1024    ┆ 1.0         │
+    #   # └─────────────────────────────────┴─────────┴─────────────┘
+    def size(unit = "b")
+      sz = Utils.wrap_expr(_rbexpr.bin_size_bytes)
+      sz = Utils.scale_bytes(sz, to: unit)
+      sz
+    end
+
+    # Interpret a buffer as a numerical Polars type.
+    #
+    # @param dtype [Object]
+    #   Which type to interpret binary column into.
+    # @param endianness : ["big", "little"]
+    #   Which endianness to use when interpreting bytes, by default "little".
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"data" => ["\x05\x00\x00\x00".b, "\x10\x00\x01\x00".b]})
+    #   df.with_columns(
+    #     bin2int: Polars.col("data").bin.reinterpret(
+    #      dtype: Polars::Int32, endianness: "little"
+    #     )
+    #   )
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────────────────────┬─────────┐
+    #   # │ data                ┆ bin2int │
+    #   # │ ---                 ┆ ---     │
+    #   # │ binary              ┆ i32     │
+    #   # ╞═════════════════════╪═════════╡
+    #   # │ b"\x05\x00\x00\x00" ┆ 5       │
+    #   # │ b"\x10\x00\x01\x00" ┆ 65552   │
+    #   # └─────────────────────┴─────────┘
+    def reinterpret(
+      dtype:,
+      endianness: "little"
+    )
+      dtype = Utils.parse_into_datatype_expr(dtype)
+
+      Utils.wrap_expr(
+        _rbexpr.bin_reinterpret(dtype._rbdatatype_expr, endianness)
+      )
+    end
   end
 end

data/lib/polars/binary_name_space.rb

@@ -157,5 +157,48 @@ module Polars
     def encode(encoding)
       super
     end
+
+    # Get the size of the binary values in a Series in the given unit.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("data", [512, 256, 2560, 1024].map { |n| "\x00".b * n })
+    #   s.bin.size("kb")
+    #   # =>
+    #   # shape: (4,)
+    #   # Series: 'data' [f64]
+    #   # [
+    #   #         0.5
+    #   #         0.25
+    #   #         2.5
+    #   #         1.0
+    #   # ]
+    def size(unit = "b")
+      super
+    end
+
+    # Interpret a buffer as a numerical polars type.
+    #
+    # @param dtype [Object]
+    #   Which type to interpret binary column into.
+    # @param endianness ["big", "little"]
+    #   Which endianness to use when interpreting bytes, by default "little".
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("data", ["\x05\x00\x00\x00".b, "\x10\x00\x01\x00".b])
+    #   s.bin.reinterpret(dtype: Polars::Int32, endianness: "little")
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'data' [i32]
+    #   # [
+    #   #         5
+    #   #         65552
+    #   # ]
+    def reinterpret(dtype:, endianness: "little")
+      super
+    end
   end
 end

data/lib/polars/cat_expr.rb

@@ -32,5 +32,229 @@ module Polars
     def get_categories
       Utils.wrap_expr(_rbexpr.cat_get_categories)
     end
+
+    # Return the byte-length of the string representation of each value.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   When working with non-ASCII text, the length in bytes is not the same as the
+    #   length in characters. You may want to use `len_chars` instead.
+    #   Note that `len_bytes` is much more performant (_O(1)_) than
+    #   `len_chars` (_O(n)_).
+    #
+    # @example
+    #     df = Polars::DataFrame.new(
+    #       {"a" => Polars::Series.new(["Café", "345", "東京", nil], dtype: Polars::Categorical)}
+    #     )
+    #     df.with_columns(
+    #       Polars.col("a").cat.len_bytes.alias("n_bytes"),
+    #       Polars.col("a").cat.len_chars.alias("n_chars")
+    #     )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌──────┬─────────┬─────────┐
+    #   # │ a    ┆ n_bytes ┆ n_chars │
+    #   # │ ---  ┆ ---     ┆ ---     │
+    #   # │ cat  ┆ u32     ┆ u32     │
+    #   # ╞══════╪═════════╪═════════╡
+    #   # │ Café ┆ 5       ┆ 4       │
+    #   # │ 345  ┆ 3       ┆ 3       │
+    #   # │ 東京 ┆ 6       ┆ 2       │
+    #   # │ null ┆ null    ┆ null    │
+    #   # └──────┴─────────┴─────────┘
+    def len_bytes
+      Utils.wrap_expr(_rbexpr.cat_len_bytes)
+    end
+
+    # Return the number of characters of the string representation of each value.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   When working with ASCII text, use `len_bytes` instead to achieve
+    #   equivalent output with much better performance:
+    #   `len_bytes` runs in _O(1)_, while `len_chars` runs in (_O(n)_).
+    #
+    #   A character is defined as a [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value). A single character is
+    #   represented by a single byte when working with ASCII text, and a maximum of
+    #   4 bytes otherwise.
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => Polars::Series.new(["Café", "345", "東京", nil], dtype: Polars::Categorical)}
+    #   )
+    #   df.with_columns(
+    #     Polars.col("a").cat.len_chars.alias("n_chars"),
+    #     Polars.col("a").cat.len_bytes.alias("n_bytes")
+    #   )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌──────┬─────────┬─────────┐
+    #   # │ a    ┆ n_chars ┆ n_bytes │
+    #   # │ ---  ┆ ---     ┆ ---     │
+    #   # │ cat  ┆ u32     ┆ u32     │
+    #   # ╞══════╪═════════╪═════════╡
+    #   # │ Café ┆ 4       ┆ 5       │
+    #   # │ 345  ┆ 3       ┆ 3       │
+    #   # │ 東京 ┆ 2       ┆ 6       │
+    #   # │ null ┆ null    ┆ null    │
+    #   # └──────┴─────────┴─────────┘
+    def len_chars
+      Utils.wrap_expr(_rbexpr.cat_len_chars)
+    end
+
+    # Check if string representations of values start with a substring.
+    #
+    # @param prefix [String]
+    #   Prefix substring.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   Whereas `str.starts_with` allows expression inputs, `cat.starts_with` requires
+    #   a literal string value.
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"fruits" => Polars::Series.new(["apple", "mango", nil], dtype: Polars::Categorical)}
+    #   )
+    #   df.with_columns(
+    #     Polars.col("fruits").cat.starts_with("app").alias("has_prefix")
+    #   )
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌────────┬────────────┐
+    #   # │ fruits ┆ has_prefix │
+    #   # │ ---    ┆ ---        │
+    #   # │ cat    ┆ bool       │
+    #   # ╞════════╪════════════╡
+    #   # │ apple  ┆ true       │
+    #   # │ mango  ┆ false      │
+    #   # │ null   ┆ null       │
+    #   # └────────┴────────────┘
+    #
+    # @example Using `starts_with` as a filter condition:
+    #   df.filter(Polars.col("fruits").cat.starts_with("app"))
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌────────┐
+    #   # │ fruits │
+    #   # │ ---    │
+    #   # │ cat    │
+    #   # ╞════════╡
+    #   # │ apple  │
+    #   # └────────┘
+    def starts_with(prefix)
+      if !prefix.is_a?(::String)
+        msg = "'prefix' must be a string; found #{prefix.inspect}"
+        raise TypeError, msg
+      end
+      Utils.wrap_expr(_rbexpr.cat_starts_with(prefix))
+    end
+
+    # Check if string representations of values end with a substring.
+    #
+    # @param suffix [String]
+    #   Suffix substring.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   Whereas `str.ends_with` allows expression inputs, `cat.ends_with` requires a
+    #   literal string value.
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"fruits" => Polars::Series.new(["apple", "mango", nil], dtype: Polars::Categorical)}
+    #   )
+    #   df.with_columns(Polars.col("fruits").cat.ends_with("go").alias("has_suffix"))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌────────┬────────────┐
+    #   # │ fruits ┆ has_suffix │
+    #   # │ ---    ┆ ---        │
+    #   # │ cat    ┆ bool       │
+    #   # ╞════════╪════════════╡
+    #   # │ apple  ┆ false      │
+    #   # │ mango  ┆ true       │
+    #   # │ null   ┆ null       │
+    #   # └────────┴────────────┘
+    #
+    # @example Using `ends_with` as a filter condition:
+    #   df.filter(Polars.col("fruits").cat.ends_with("go"))
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌────────┐
+    #   # │ fruits │
+    #   # │ ---    │
+    #   # │ cat    │
+    #   # ╞════════╡
+    #   # │ mango  │
+    #   # └────────┘
+    def ends_with(suffix)
+      if !suffix.is_a?(::String)
+        msg = "'suffix' must be a string; found #{suffix.inspect}"
+        raise TypeError, msg
+      end
+      Utils.wrap_expr(_rbexpr.cat_ends_with(suffix))
+    end
+
+    # Extract a substring from the string representation of each value.
+    #
+    # @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 string.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   Both the `offset` and `length` inputs are defined in terms of the number
+    #   of characters in the (UTF8) string. A character is defined as a
+    #   [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value). A single character is represented by a single byte
+    #   when working with ASCII text, and a maximum of 4 bytes otherwise.
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "s" => Polars::Series.new(
+    #         ["pear", nil, "papaya", "dragonfruit"],
+    #         dtype: Polars::Categorical
+    #       )
+    #     }
+    #   )
+    #   df.with_columns(Polars.col("s").cat.slice(-3).alias("slice"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────────────┬───────┐
+    #   # │ s           ┆ slice │
+    #   # │ ---         ┆ ---   │
+    #   # │ cat         ┆ str   │
+    #   # ╞═════════════╪═══════╡
+    #   # │ pear        ┆ ear   │
+    #   # │ null        ┆ null  │
+    #   # │ papaya      ┆ aya   │
+    #   # │ dragonfruit ┆ uit   │
+    #   # └─────────────┴───────┘
+    #
+    # @example Using the optional `length` parameter
+    #   df.with_columns(Polars.col("s").cat.slice(4, 3).alias("slice"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────────────┬───────┐
+    #   # │ s           ┆ slice │
+    #   # │ ---         ┆ ---   │
+    #   # │ cat         ┆ str   │
+    #   # ╞═════════════╪═══════╡
+    #   # │ pear        ┆       │
+    #   # │ null        ┆ null  │
+    #   # │ papaya      ┆ ya    │
+    #   # │ dragonfruit ┆ onf   │
+    #   # └─────────────┴───────┘
+    def slice(offset, length = nil)
+      Utils.wrap_expr(_rbexpr.cat_slice(offset, length))
+    end
   end
 end