polars-df 0.3.1-x86_64-linux → 0.5.0-x86_64-linux

data/lib/polars/date_time_expr.rb

@@ -218,6 +218,25 @@ module Polars
       )
     end
 
+    # Create a naive Datetime from an existing Date/Datetime expression and a Time.
+    #
+    # If the underlying expression is a Datetime then its time component is replaced,
+    # and if it is a Date then a new Datetime is created by combining the two values.
+    #
+    # @param time [Object]
+    #   A Ruby time literal or Polars expression/column that resolves to a time.
+    # @param time_unit ["ns", "us", "ms"]
+    #   Unit of time.
+    #
+    # @return [Expr]
+    def combine(time, time_unit: "us")
+      unless time.is_a?(Time) || time.is_a?(Expr)
+        raise TypeError, "expected 'time' to be a Ruby time or Polars expression, found #{time}"
+      end
+      time = Utils.expr_to_lit_or_expr(time)
+      Utils.wrap_expr(_rbexpr.dt_combine(time._rbexpr, time_unit))
+    end
+
     # Format Date/datetime with a formatting rule.
     #
     # See [chrono strftime/strptime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
@@ -270,6 +289,34 @@ module Polars
       Utils.wrap_expr(_rbexpr.year)
     end
 
+    # Determine whether the year of the underlying date is a leap year.
+    #
+    # Applies to Date and Datetime columns.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   start = DateTime.new(2000, 1, 1)
+    #   stop = DateTime.new(2002, 1, 1)
+    #   df = Polars::DataFrame.new(
+    #     {"date" => Polars.date_range(start, stop, "1y")}
+    #   )
+    #   df.select(Polars.col("date").dt.is_leap_year)
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌───────┐
+    #   # │ date  │
+    #   # │ ---   │
+    #   # │ bool  │
+    #   # ╞═══════╡
+    #   # │ true  │
+    #   # │ false │
+    #   # │ false │
+    #   # └───────┘
+    def is_leap_year
+      Utils.wrap_expr(_rbexpr.dt_is_leap_year)
+    end
+
     # Extract ISO year from underlying Date representation.
     #
     # Applies to Date and Datetime columns.
@@ -550,6 +597,27 @@ module Polars
       Utils.wrap_expr(_rbexpr.ordinal_day)
     end
 
+    # Time
+    #
+    # @return [Expr]
+    def time
+      Utils.wrap_expr(_rbexpr.dt_time)
+    end
+
+    # Date
+    #
+    # @return [Expr]
+    def date
+      Utils.wrap_expr(_rbexpr.dt_date)
+    end
+
+    # Datetime
+    #
+    # @return [Expr]
+    def datetime
+      Utils.wrap_expr(_rbexpr.dt_datetime)
+    end
+
     # Extract hour from underlying DateTime representation.
     #
     # Applies to Datetime columns.
@@ -958,8 +1026,8 @@ module Polars
     #   Time zone for the `Datetime` Series.
     #
     # @return [Expr]
-    def replace_time_zone(tz)
-      Utils.wrap_expr(_rbexpr.dt_replace_time_zone(tz))
+    def replace_time_zone(tz, use_earliest: nil)
+      Utils.wrap_expr(_rbexpr.dt_replace_time_zone(tz, use_earliest))
     end
 
     # Localize tz-naive Datetime Series to tz-aware Datetime Series.
@@ -1130,7 +1198,7 @@ module Polars
     #     ]
     #   )
     #   # =>
-    #   # shape: (1001, 2)
+    #   # shape: (1_001, 2)
     #   # ┌─────────────────────────┬───────────────────┐
     #   # │ date                    ┆ milliseconds_diff │
     #   # │ ---                     ┆ ---               │
@@ -1140,7 +1208,7 @@ module Polars
     #   # │ 2020-01-01 00:00:00.001 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.002 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.003 ┆ 1                 │
-    #   # │ ...                     ┆ ...               │
+    #   # │ …                       ┆ …                 │
     #   # │ 2020-01-01 00:00:00.997 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.998 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.999 ┆ 1                 │
@@ -1169,7 +1237,7 @@ module Polars
     #     ]
     #   )
     #   # =>
-    #   # shape: (1001, 2)
+    #   # shape: (1_001, 2)
     #   # ┌─────────────────────────┬───────────────────┐
     #   # │ date                    ┆ microseconds_diff │
     #   # │ ---                     ┆ ---               │
@@ -1179,7 +1247,7 @@ module Polars
     #   # │ 2020-01-01 00:00:00.001 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.002 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.003 ┆ 1000              │
-    #   # │ ...                     ┆ ...               │
+    #   # │ …                       ┆ …                 │
     #   # │ 2020-01-01 00:00:00.997 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.998 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.999 ┆ 1000              │
@@ -1208,7 +1276,7 @@ module Polars
     #     ]
     #   )
     #   # =>
-    #   # shape: (1001, 2)
+    #   # shape: (1_001, 2)
     #   # ┌─────────────────────────┬──────────────────┐
     #   # │ date                    ┆ nanoseconds_diff │
     #   # │ ---                     ┆ ---              │
@@ -1218,7 +1286,7 @@ module Polars
     #   # │ 2020-01-01 00:00:00.001 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.002 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.003 ┆ 1000000          │
-    #   # │ ...                     ┆ ...              │
+    #   # │ …                       ┆ …                │
     #   # │ 2020-01-01 00:00:00.997 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.998 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.999 ┆ 1000000          │
@@ -1282,5 +1350,77 @@ module Polars
     def offset_by(by)
       Utils.wrap_expr(_rbexpr.dt_offset_by(by))
     end
+
+    # Roll backward to the first day of the month.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "dates" => Polars.date_range(
+    #         DateTime.new(2000, 1, 15, 2),
+    #         DateTime.new(2000, 12, 15, 2),
+    #         "1mo"
+    #       )
+    #     }
+    #   )
+    #   df.select(Polars.col("dates").dt.month_start)
+    #   # =>
+    #   # shape: (12, 1)
+    #   # ┌─────────────────────┐
+    #   # │ dates               │
+    #   # │ ---                 │
+    #   # │ datetime[μs]        │
+    #   # ╞═════════════════════╡
+    #   # │ 2000-01-01 02:00:00 │
+    #   # │ 2000-02-01 02:00:00 │
+    #   # │ 2000-03-01 02:00:00 │
+    #   # │ 2000-04-01 02:00:00 │
+    #   # │ …                   │
+    #   # │ 2000-09-01 02:00:00 │
+    #   # │ 2000-10-01 02:00:00 │
+    #   # │ 2000-11-01 02:00:00 │
+    #   # │ 2000-12-01 02:00:00 │
+    #   # └─────────────────────┘
+    def month_start
+      Utils.wrap_expr(_rbexpr.dt_month_start)
+    end
+
+    # Roll forward to the last day of the month.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "dates" => Polars.date_range(
+    #         DateTime.new(2000, 1, 15, 2),
+    #         DateTime.new(2000, 12, 15, 2),
+    #         "1mo"
+    #       )
+    #     }
+    #   )
+    #   df.select(Polars.col("dates").dt.month_end)
+    #   # =>
+    #   # shape: (12, 1)
+    #   # ┌─────────────────────┐
+    #   # │ dates               │
+    #   # │ ---                 │
+    #   # │ datetime[μs]        │
+    #   # ╞═════════════════════╡
+    #   # │ 2000-01-31 02:00:00 │
+    #   # │ 2000-02-29 02:00:00 │
+    #   # │ 2000-03-31 02:00:00 │
+    #   # │ 2000-04-30 02:00:00 │
+    #   # │ …                   │
+    #   # │ 2000-09-30 02:00:00 │
+    #   # │ 2000-10-31 02:00:00 │
+    #   # │ 2000-11-30 02:00:00 │
+    #   # │ 2000-12-31 02:00:00 │
+    #   # └─────────────────────┘
+    def month_end
+      Utils.wrap_expr(_rbexpr.dt_month_end)
+    end
   end
 end

data/lib/polars/expr.rb

@@ -1308,8 +1308,6 @@ module Polars
     #
     # @param k [Integer]
     #   Number of elements to return.
-    # @param reverse [Boolean]
-    #   Return the smallest elements.
     #
     # @return [Expr]
     #
@@ -1322,7 +1320,45 @@ module Polars
     #   df.select(
     #     [
     #       Polars.col("value").top_k.alias("top_k"),
-    #       Polars.col("value").top_k(reverse: true).alias("bottom_k")
+    #       Polars.col("value").bottom_k.alias("bottom_k")
+    #     ]
+    #   )
+    #   # =>
+    #   # shape: (5, 2)
+    #   # ┌───────┬──────────┐
+    #   # │ top_k ┆ bottom_k │
+    #   # │ ---   ┆ ---      │
+    #   # │ i64   ┆ i64      │
+    #   # ╞═══════╪══════════╡
+    #   # │ 99    ┆ 1        │
+    #   # │ 98    ┆ 2        │
+    #   # │ 4     ┆ 3        │
+    #   # │ 3     ┆ 4        │
+    #   # │ 2     ┆ 98       │
+    #   # └───────┴──────────┘
+    def top_k(k: 5)
+      wrap_expr(_rbexpr.top_k(k))
+    end
+
+    # Return the `k` smallest elements.
+    #
+    # If 'reverse: true` the smallest elements will be given.
+    #
+    # @param k [Integer]
+    #   Number of elements to return.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "value" => [1, 98, 2, 3, 99, 4]
+    #     }
+    #   )
+    #   df.select(
+    #     [
+    #       Polars.col("value").top_k.alias("top_k"),
+    #       Polars.col("value").bottom_k.alias("bottom_k")
     #     ]
     #   )
     #   # =>
@@ -1338,8 +1374,8 @@ module Polars
     #   # │ 3     ┆ 4        │
     #   # │ 2     ┆ 98       │
     #   # └───────┴──────────┘
-    def top_k(k: 5, reverse: false)
-      wrap_expr(_rbexpr.top_k(k, reverse))
+    def bottom_k(k: 5)
+      wrap_expr(_rbexpr.bottom_k(k))
     end
 
     # Get the index values that would sort this column.
@@ -2008,6 +2044,28 @@ module Polars
       wrap_expr(_rbexpr.n_unique)
     end
 
+    # Approx count unique values.
+    #
+    # This is done using the HyperLogLog++ algorithm for cardinality estimation.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [1, 1, 2]})
+    #   df.select(Polars.col("a").approx_unique)
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌─────┐
+    #   # │ a   │
+    #   # │ --- │
+    #   # │ u32 │
+    #   # ╞═════╡
+    #   # │ 2   │
+    #   # └─────┘
+    def approx_unique
+      wrap_expr(_rbexpr.approx_unique)
+    end
+
     # Count null values.
     #
     # @return [Expr]
@@ -2194,7 +2252,7 @@ module Polars
     #   # │ 4      │
     #   # │ 6      │
     #   # │ 6      │
-    #   # │ ...    │
+    #   # │ 4      │
     #   # │ 6      │
     #   # │ 6      │
     #   # │ 6      │
@@ -2571,7 +2629,7 @@ module Polars
     #   # │ e   │
     #   # │ l   │
     #   # │ l   │
-    #   # │ ... │
+    #   # │ …   │
     #   # │ o   │
     #   # │ r   │
     #   # │ l   │
@@ -2751,6 +2809,7 @@ module Polars
       end
       wrap_expr(_rbexpr.is_in(other._rbexpr))
     end
+    alias_method :in?, :is_in
 
     # Repeat the elements in this Series as specified in the given expression.
     #
@@ -3914,8 +3973,8 @@ module Polars
     #   # │ 2   │
     #   # │ 5   │
     #   # └─────┘
-    def rank(method: "average", reverse: false)
-      wrap_expr(_rbexpr.rank(method, reverse))
+    def rank(method: "average", reverse: false, seed: nil)
+      wrap_expr(_rbexpr.rank(method, reverse, seed))
     end
 
     # Calculate the n-th discrete difference.
@@ -4916,9 +4975,10 @@ module Polars
     #   # ╞═══════════╪═══════════╡
     #   # │ [1, 2, 3] ┆ [4, 5, 6] │
     #   # └───────────┴───────────┘
-    def list
-      wrap_expr(_rbexpr.list)
+    def implode
+      wrap_expr(_rbexpr.implode)
     end
+    alias_method :list, :implode
 
     # Shrink numeric columns to the minimal required datatype.
     #
@@ -4962,6 +5022,13 @@ module Polars
       ListExpr.new(self)
     end
 
+    # Create an object namespace of all binary related methods.
+    #
+    # @return [BinaryExpr]
+    def bin
+      BinaryExpr.new(self)
+    end
+
     # Create an object namespace of all categorical related methods.
     #
     # @return [CatExpr]