polars-df 0.23.0 → 0.24.0

data/lib/polars/series_plot.rb

@@ -0,0 +1,72 @@
+module Polars
+  # Series.plot namespace.
+  class SeriesPlot
+    # @private
+    def initialize(s)
+      require "vega"
+
+      name = s.name || "value"
+      @df = s.to_frame(name)
+      @series_name = name
+    end
+
+    # Draw histogram.
+    #
+    # @return [Vega::LiteChart]
+    def hist
+      encoding = {
+        x: {field: @series_name, bin: true},
+        y: {aggregate: "count"}
+      }
+
+      Vega.lite
+        .data(@df.rows(named: true))
+        .mark(type: "bar", tooltip: true)
+        .encoding(encoding)
+        .config(axis: {labelFontSize: 12})
+    end
+
+    # Draw kernel density estimate plot.
+    #
+    # @return [Vega::LiteChart]
+    def kde
+      if @series_name == "density"
+        msg = "cannot use `plot.kde` when Series name is `'density'`"
+        raise ArgumentError, msg
+      end
+
+      encoding = {
+        x: {field: @series_name, type: "quantitative"},
+        y: {field: "density", type: "quantitative"}
+      }
+
+      Vega.lite
+        .data(@df.rows(named: true))
+        .transform(density: @series_name, as: [@series_name, "density"])
+        .mark(type: "area", tooltip: true)
+        .encoding(encoding)
+        .config(axis: {labelFontSize: 12})
+    end
+
+    # Draw line plot.
+    #
+    # @return [Vega::LiteChart]
+    def line
+      if @series_name == "index"
+        msg = "cannot call `plot.line` when Series name is 'index'"
+        raise ArgumentError, msg
+      end
+
+      encoding = {
+        x: {field: "index", type: "quantitative"},
+        y: {field: @series_name, type: "quantitative"}
+      }
+
+      Vega.lite
+        .data(@df.with_row_index.rows(named: true))
+        .mark(type: "line", tooltip: true)
+        .encoding(encoding)
+        .config(axis: {labelFontSize: 12})
+    end
+  end
+end

data/lib/polars/slice.rb

@@ -12,7 +12,7 @@ module Polars
 
       # check for fast-paths / single-operation calls
       if @slice_length == 0
-        @obj.cleared
+        @obj.clear
       elsif @is_unbounded && [-1, 1].include?(@stride)
         @stride < 0 ? @obj.reverse : @obj.clone
       elsif @start >= 0 && @stop >= 0 && @stride == 1

data/lib/polars/sql_context.rb

@@ -5,11 +5,17 @@ module Polars
     attr_accessor :_ctxt, :_eager_execution
 
     # Initialize a new `SQLContext`.
-    def initialize(frames = nil, eager_execution: false, **named_frames)
+    def initialize(frames = nil, register_globals: false, eager: false, **named_frames)
+      Utils.issue_unstable_warning(
+        "`SQLContext` is considered **unstable**, although it is close to being considered stable."
+      )
       self._ctxt = RbSQLContext.new
-      self._eager_execution = eager_execution
+      self._eager_execution = eager
 
       frames = (frames || {}).to_h
+      if register_globals
+        raise Todo
+      end
 
       if frames.any? || named_frames.any?
         register_many(frames, **named_frames)
@@ -37,7 +43,8 @@ module Polars
     #       ["Pulp Fiction", 1994, 8_000_000, 107_930_000, 8.9],
     #       ["The Shawshank Redemption", 1994, 25_000_000, 28_341_469, 9.3],
     #     ],
-    #     schema: ["title", "release_year", "budget", "gross", "imdb_score"]
+    #     schema: ["title", "release_year", "budget", "gross", "imdb_score"],
+    #     orient: "row"
     #   )
     #   ctx = Polars::SQLContext.new(films: df)
     #   ctx.execute(
@@ -129,7 +136,7 @@ module Polars
     #   Named eager/lazy frames, provided as kwargs.
     #
     # @return [SQLContext]
-    def register_many(frames, **named_frames)
+    def register_many(frames = nil, **named_frames)
       frames = (frames || {}).to_h
       frames = frames.merge(named_frames)
       frames.each do |name, frame|

data/lib/polars/string_expr.rb

@@ -154,9 +154,13 @@ module Polars
     #   - If false, allow the format to match anywhere in the target string.
     # @param cache [Boolean]
     #   Use a cache of unique, converted dates to apply the datetime conversion.
-    # @param utc [Boolean]
-    #   Parse timezone aware datetimes as UTC. This may be useful if you have data
-    #   with mixed offsets.
+    # @param ambiguous ['raise', 'earliest', 'latest', 'null']
+    #   Determine how to deal with ambiguous datetimes:
+    #
+    #   - `'raise'` (default): raise
+    #   - `'earliest'`: use the earliest datetime
+    #   - `'latest'`: use the latest datetime
+    #   - `'null'`: set to null
     #
     # @return [Expr]
     #
@@ -203,7 +207,14 @@ module Polars
     #   #         2022-01-31
     #   #         2001-07-08
     #   # ]
-    def strptime(dtype, format = nil, strict: true, exact: true, cache: true, utc: false)
+    def strptime(
+      dtype,
+      format = nil,
+      strict: true,
+      exact: true,
+      cache: true,
+      ambiguous: "raise"
+    )
       _validate_format_argument(format)
 
       if dtype == Date
@@ -212,7 +223,15 @@ module Polars
         dtype = Datetime.new if dtype == Datetime
         time_unit = dtype.time_unit
         time_zone = dtype.time_zone
-        to_datetime(format, time_unit: time_unit, time_zone: time_zone, strict: strict, exact: exact, cache: cache)
+        to_datetime(
+          format,
+          time_unit: time_unit,
+          time_zone: time_zone,
+          strict: strict,
+          exact: exact,
+          cache: cache,
+          ambiguous: ambiguous
+        )
       elsif dtype == Time
         to_time(format, strict: strict, cache: cache)
       else
@@ -292,7 +311,6 @@ module Polars
     def len_bytes
       Utils.wrap_expr(_rbexpr.str_len_bytes)
     end
-    alias_method :lengths, :len_bytes
 
     # Get length of the strings as `:u32` (as number of chars).
     #
@@ -325,7 +343,6 @@ module Polars
     def len_chars
       Utils.wrap_expr(_rbexpr.str_len_chars)
     end
-    alias_method :n_chars, :len_chars
 
     # Vertically concat the values in the Series to a single string value.
     #
@@ -361,10 +378,15 @@ module Polars
     #   # ╞══════╡
     #   # │ null │
     #   # └──────┘
-    def join(delimiter = "-", ignore_nulls: true)
+    def join(delimiter = nil, ignore_nulls: true)
+      # TODO update
+      if delimiter.nil?
+        warn "The default `delimiter` for `join` method will change from `-` to empty string in a future version"
+        delimiter = "-"
+      end
+
       Utils.wrap_expr(_rbexpr.str_join(delimiter, ignore_nulls))
     end
-    alias_method :concat, :join
 
     # Returns string values with all regular expression meta characters escaped.
     #
@@ -505,7 +527,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
-    #   df.select(Polars.col("foo").str.strip)
+    #   df.select(Polars.col("foo").str.strip_chars)
     #   # =>
     #   # shape: (3, 1)
     #   # ┌───────┐
@@ -521,7 +543,6 @@ module Polars
       characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars(characters))
     end
-    alias_method :strip, :strip_chars
 
     # Remove leading whitespace.
     #
@@ -532,7 +553,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
-    #   df.select(Polars.col("foo").str.lstrip)
+    #   df.select(Polars.col("foo").str.strip_chars_start)
     #   # =>
     #   # shape: (3, 1)
     #   # ┌────────┐
@@ -548,7 +569,6 @@ module Polars
       characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars_start(characters))
     end
-    alias_method :lstrip, :strip_chars_start
 
     # Remove trailing whitespace.
     #
@@ -559,7 +579,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
-    #   df.select(Polars.col("foo").str.rstrip)
+    #   df.select(Polars.col("foo").str.strip_chars_end)
     #   # =>
     #   # shape: (3, 1)
     #   # ┌───────┐
@@ -575,7 +595,6 @@ module Polars
       characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars_end(characters))
     end
-    alias_method :rstrip, :strip_chars_end
 
     # Remove prefix.
     #
@@ -665,7 +684,6 @@ module Polars
       length = Utils.parse_into_expression(length)
       Utils.wrap_expr(_rbexpr.str_pad_start(length, fill_char))
     end
-    alias_method :rjust, :pad_start
 
     # Pad the end of the string until it reaches the given length.
     #
@@ -696,7 +714,6 @@ module Polars
       length = Utils.parse_into_expression(length)
       Utils.wrap_expr(_rbexpr.str_pad_end(length, fill_char))
     end
-    alias_method :ljust, :pad_end
 
     # Fills the string with zeroes.
     #
@@ -834,14 +851,14 @@ module Polars
 
     # Check if string values end with a substring.
     #
-    # @param sub [String]
+    # @param suffix [String]
     #   Suffix substring.
     #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new({"fruits" => ["apple", "mango", nil]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("fruits").str.ends_with("go").alias("has_suffix")
     #   )
     #   # =>
@@ -867,21 +884,21 @@ module Polars
     #   # ╞════════╡
     #   # │ mango  │
     #   # └────────┘
-    def ends_with(sub)
-      sub = Utils.parse_into_expression(sub, str_as_lit: true)
-      Utils.wrap_expr(_rbexpr.str_ends_with(sub))
+    def ends_with(suffix)
+      suffix_rbexpr = Utils.parse_into_expression(suffix, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_ends_with(suffix_rbexpr))
     end
 
     # Check if string values start with a substring.
     #
-    # @param sub [String]
+    # @param prefix [String]
     #   Prefix substring.
     #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new({"fruits" => ["apple", "mango", nil]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("fruits").str.starts_with("app").alias("has_prefix")
     #   )
     #   # =>
@@ -907,9 +924,9 @@ module Polars
     #   # ╞════════╡
     #   # │ apple  │
     #   # └────────┘
-    def starts_with(sub)
-      sub = Utils.parse_into_expression(sub, str_as_lit: true)
-      Utils.wrap_expr(_rbexpr.str_starts_with(sub))
+    def starts_with(prefix)
+      prefix_rbexpr = Utils.parse_into_expression(prefix, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_starts_with(prefix_rbexpr))
     end
 
     # Parse string values as JSON.
@@ -949,7 +966,6 @@ module Polars
       dtype_expr = Utils.parse_into_datatype_expr(dtype)._rbdatatype_expr
       Utils.wrap_expr(_rbexpr.str_json_decode(dtype_expr))
     end
-    alias_method :json_extract, :json_decode
 
     # Extract the first match of json string with provided JSONPath expression.
     #
@@ -1188,7 +1204,7 @@ module Polars
     #   df = Polars::DataFrame.new({"foo" => ["123 bla 45 asd", "xyz 678 910t"]})
     #   df.select(
     #     [
-    #       Polars.col("foo").str.count_match('\d').alias("count_digits")
+    #       Polars.col("foo").str.count_matches('\d').alias("count_digits")
     #     ]
     #   )
     #   # =>
@@ -1205,7 +1221,6 @@ module Polars
       pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_count_matches(pattern, literal))
     end
-    alias_method :count_match, :count_matches
 
     # Split the string by a substring.
     #
@@ -1329,7 +1344,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"id" => [1, 2], "text" => ["123abc", "abc456"]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("text").str.replace('abc\b', "ABC")
     #   )
     #   # =>
@@ -1361,7 +1376,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"id" => [1, 2], "text" => ["abcabc", "123a123"]})
-    #   df.with_column(Polars.col("text").str.replace_all("a", "-"))
+    #   df.with_columns(Polars.col("text").str.replace_all("a", "-"))
     #   # =>
     #   # shape: (2, 2)
     #   # ┌─────┬─────────┐
@@ -1412,7 +1427,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"s" => ["pear", nil, "papaya", "dragonfruit"]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("s").str.slice(-3).alias("s_sliced")
     #   )
     #   # =>
@@ -1604,38 +1619,6 @@ module Polars
       Utils.wrap_expr(_rbexpr.str_to_integer(base, dtype, strict))
     end
 
-    # Parse integers with base radix from strings.
-    #
-    # By default base 2. ParseError/Overflows become Nulls.
-    #
-    # @param radix [Integer]
-    #   Positive integer which is the base of the string we are parsing.
-    #   Default: 2.
-    # @param strict [Boolean]
-    #   Bool, Default=true will raise any ParseError or overflow as ComputeError.
-    #   False silently convert to Null.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new({"bin" => ["110", "101", "010", "invalid"]})
-    #   df.select(Polars.col("bin").str.parse_int(2, strict: false))
-    #   # =>
-    #   # shape: (4, 1)
-    #   # ┌──────┐
-    #   # │ bin  │
-    #   # │ ---  │
-    #   # │ i32  │
-    #   # ╞══════╡
-    #   # │ 6    │
-    #   # │ 5    │
-    #   # │ 2    │
-    #   # │ null │
-    #   # └──────┘
-    def parse_int(radix = 2, strict: true)
-      to_integer(base: 2, strict: strict).cast(Int32, strict: strict)
-    end
-
     # Use the aho-corasick algorithm to find matches.
     #
     # This version determines if any of the patterns find a match.
@@ -1744,8 +1727,8 @@ module Polars
     #   # │ Tell me what you want, what yo… ┆ Tell you what me want, what me… │
     #   # │ Can you feel the love tonight   ┆ Can me feel the love tonight    │
     #   # └─────────────────────────────────┴─────────────────────────────────┘
-    def replace_many(patterns, replace_with = Expr::NO_DEFAULT, ascii_case_insensitive: false)
-      if replace_with == Expr::NO_DEFAULT
+    def replace_many(patterns, replace_with = NO_DEFAULT, ascii_case_insensitive: false)
+      if replace_with == NO_DEFAULT
         if !patterns.is_a?(Hash)
           msg = "`replace_with` argument is required if `patterns` argument is not a Hash type"
           raise TypeError, msg
@@ -1913,7 +1896,15 @@ module Polars
     private
 
     def _validate_format_argument(format)
-      # TODO
+      if !format.nil? && format.include?(".%f")
+        message = (
+          "Detected the pattern `.%f` in the chrono format string." +
+          " This pattern should not be used to parse values after a decimal point." +
+          " Use `%.f` instead." +
+          " See the full specification: https://docs.rs/chrono/latest/chrono/format/strftime"
+        )
+        warn message
+      end
     end
   end
 end