polars-df 0.15.0 → 0.26.0

data/lib/polars/functions/datatype.rb

@@ -0,0 +1,62 @@
+module Polars
+  module Functions
+    # Get a lazily evaluated :class:`DataType` of a column or expression.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @return [DataTypeExpr]
+    def dtype_of(col_or_expr)
+      e = nil
+      if col_or_expr.is_a?(::String)
+        e = F.col(col_or_expr)
+      else
+        e = col_or_expr
+      end
+
+      DataTypeExpr._from_rbdatatype_expr(RbDataTypeExpr.of_expr(e._rbexpr))
+    end
+
+    # Get the dtype of `self` in `map_elements` and `map_batches`.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @return [DataTypeExpr]
+    def self_dtype
+      DataTypeExpr._from_rbdatatype_expr(RbDataTypeExpr.self_dtype)
+    end
+
+    # Create a new datatype expression that represents a Struct datatype.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @return [DataTypeExpr]
+    def struct_with_fields(
+      mapping
+    )
+      preprocess = lambda do |dtype_expr|
+        if dtype_expr.is_a?(DataType)
+          dtype_expr.to_dtype_expr._rbdatatype_expr
+        elsif dtype_expr < DataType
+          dtype_expr.to_dtype_expr._rbdatatype_expr
+        elsif dtype_expr.is_a?(DataTypeExpr)
+          dtype_expr._rbdatatype_expr
+        else
+          msg = "mapping item must be a datatype or datatype expression; found #{dtype_expr.inspect}"
+          raise TypeError, msg
+        end
+      end
+
+      fields = mapping.map { |name, dtype_expr| [name.to_s, preprocess.(dtype_expr)]  }
+
+      DataTypeExpr._from_rbdatatype_expr(
+        RbDataTypeExpr.struct_with_fields(fields)
+      )
+    end
+  end
+end

data/lib/polars/functions/eager.rb

@@ -6,8 +6,7 @@ module Polars
     #   DataFrames/Series/LazyFrames to concatenate.
     # @param rechunk [Boolean]
     #   Make sure that all data is in contiguous memory.
-    # @param how ["vertical", "vertical_relaxed", "diagonal", "horizontal"]
-    #   LazyFrames do not support the `horizontal` strategy.
+    # @param how ["vertical", "vertical_relaxed", "diagonal", "diagonal_relaxed", "horizontal"]
     #
     #   - Vertical: applies multiple `vstack` operations.
     #   - Diagonal: finds a union between the column schemas and fills missing column values with null.
@@ -15,13 +14,15 @@ module Polars
     # @param parallel [Boolean]
     #   Only relevant for LazyFrames. This determines if the concatenated
     #   lazy computations may be executed in parallel.
+    # @param strict [Boolean]
+    #   When how=`horizontal`, require all DataFrames to be the same height, raising an error if not.
     #
     # @return [Object]
     #
     # @example
     #   df1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
     #   df2 = Polars::DataFrame.new({"a" => [2], "b" => [4]})
-    #   Polars.concat([df1, df2])
+    #   Polars.concat([df1, df2])  # default is 'vertical' strategy
     #   # =>
     #   # shape: (2, 2)
     #   # ┌─────┬─────┐
@@ -32,38 +33,168 @@ module Polars
     #   # │ 1   ┆ 3   │
     #   # │ 2   ┆ 4   │
     #   # └─────┴─────┘
-    def concat(items, rechunk: true, how: "vertical", parallel: true)
-      if items.empty?
+    #
+    # @example
+    #   df1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
+    #   df2 = Polars::DataFrame.new({"a" => [2.5], "b" => [4]})
+    #   Polars.concat([df1, df2], how: "vertical_relaxed")  # 'a' coerced into f64
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ f64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1.0 ┆ 3   │
+    #   # │ 2.5 ┆ 4   │
+    #   # └─────┴─────┘
+    #
+    # @example
+    #   df_h1 = Polars::DataFrame.new({"l1" => [1, 2], "l2" => [3, 4]})
+    #   df_h2 = Polars::DataFrame.new({"r1" => [5, 6], "r2" => [7, 8], "r3" => [9, 10]})
+    #   Polars.concat([df_h1, df_h2], how: "horizontal")
+    #   # =>
+    #   # shape: (2, 5)
+    #   # ┌─────┬─────┬─────┬─────┬─────┐
+    #   # │ l1  ┆ l2  ┆ r1  ┆ r2  ┆ r3  │
+    #   # │ --- ┆ --- ┆ --- ┆ --- ┆ --- │
+    #   # │ i64 ┆ i64 ┆ i64 ┆ i64 ┆ i64 │
+    #   # ╞═════╪═════╪═════╪═════╪═════╡
+    #   # │ 1   ┆ 3   ┆ 5   ┆ 7   ┆ 9   │
+    #   # │ 2   ┆ 4   ┆ 6   ┆ 8   ┆ 10  │
+    #   # └─────┴─────┴─────┴─────┴─────┘
+    #
+    # @example
+    #   df_d1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
+    #   df_d2 = Polars::DataFrame.new({"a" => [2], "c" => [4]})
+    #   Polars.concat([df_d1, df_d2], how: "diagonal")
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌─────┬──────┬──────┐
+    #   # │ a   ┆ b    ┆ c    │
+    #   # │ --- ┆ ---  ┆ ---  │
+    #   # │ i64 ┆ i64  ┆ i64  │
+    #   # ╞═════╪══════╪══════╡
+    #   # │ 1   ┆ 3    ┆ null │
+    #   # │ 2   ┆ null ┆ 4    │
+    #   # └─────┴──────┴──────┘
+    #
+    # @example
+    #   df_a1 = Polars::DataFrame.new({"id" => [1, 2], "x" => [3, 4]})
+    #   df_a2 = Polars::DataFrame.new({"id" => [2, 3], "y" => [5, 6]})
+    #   df_a3 = Polars::DataFrame.new({"id" => [1, 3], "z" => [7, 8]})
+    #   Polars.concat([df_a1, df_a2, df_a3], how: "align")
+    #   # =>
+    #   # shape: (3, 4)
+    #   # ┌─────┬──────┬──────┬──────┐
+    #   # │ id  ┆ x    ┆ y    ┆ z    │
+    #   # │ --- ┆ ---  ┆ ---  ┆ ---  │
+    #   # │ i64 ┆ i64  ┆ i64  ┆ i64  │
+    #   # ╞═════╪══════╪══════╪══════╡
+    #   # │ 1   ┆ 3    ┆ null ┆ 7    │
+    #   # │ 2   ┆ 4    ┆ 5    ┆ null │
+    #   # │ 3   ┆ null ┆ 6    ┆ 8    │
+    #   # └─────┴──────┴──────┴──────┘
+    def concat(items, rechunk: false, how: "vertical", parallel: true, strict: false)
+      elems = items.to_a
+
+      if elems.empty?
         raise ArgumentError, "cannot concat empty list"
       end
 
-      first = items[0]
+      if how == "align"
+        if !elems[0].is_a?(DataFrame) && !elems[0].is_a?(LazyFrame)
+          msg = "'align' strategy is not supported for #{elems[0].class.name}"
+          raise TypeError, msg
+        end
+
+        # establish common columns, maintaining the order in which they appear
+        all_columns = elems.flat_map { |e| e.collect_schema.names }
+        key = all_columns.uniq.map.with_index.to_h
+        common_cols = elems.map { |e| e.collect_schema.names }
+          .reduce { |x, y| Set.new(x) & Set.new(y) }
+          .sort_by { |k| key[k] }
+        # we require at least one key column for 'align'
+        if common_cols.empty?
+          msg = "'align' strategy requires at least one common column"
+          raise InvalidOperationError, msg
+        end
+
+        # align the frame data using a full outer join with no suffix-resolution
+        # (so we raise an error in case of column collision, like "horizontal")
+        lf = elems.map { |df| df.lazy }.reduce do |x, y|
+          x.join(
+            y,
+            how: "full",
+            on: common_cols,
+            suffix: "_PL_CONCAT_RIGHT",
+            maintain_order: "right_left"
+          )
+          # Coalesce full outer join columns
+          .with_columns(
+            common_cols.map { |name| F.coalesce([name, "#{name}_PL_CONCAT_RIGHT"]) }
+          )
+          .drop(common_cols.map { |name| "#{name}_PL_CONCAT_RIGHT" })
+        end.sort(common_cols)
+
+        eager = elems[0].is_a?(DataFrame)
+        return eager ? lf.collect : lf
+      end
+
+      first = elems[0]
+
       if first.is_a?(DataFrame)
         if how == "vertical"
-          out = Utils.wrap_df(Plr.concat_df(items))
+          out = Utils.wrap_df(Plr.concat_df(elems))
+        elsif how == "vertical_relaxed"
+          out = Utils.wrap_ldf(
+            Plr.concat_lf(
+              elems.map { |df| df.lazy },
+              rechunk,
+              parallel,
+              true
+            )
+          ).collect(optimizations: QueryOptFlags._eager)
         elsif how == "diagonal"
-          out = Utils.wrap_df(Plr.concat_df_diagonal(items))
+          out = Utils.wrap_df(Plr.concat_df_diagonal(elems))
+        elsif how == "diagonal_relaxed"
+          out = Utils.wrap_ldf(
+            Plr.concat_lf_diagonal(
+              elems.map { |df| df.lazy },
+              rechunk,
+              parallel,
+              true
+            )
+          ).collect(optimizations: QueryOptFlags._eager)
         elsif how == "horizontal"
-          out = Utils.wrap_df(Plr.concat_df_horizontal(items))
+          out = Utils.wrap_df(Plr.concat_df_horizontal(elems, strict))
         else
-          raise ArgumentError, "how must be one of {{'vertical', 'diagonal', 'horizontal'}}, got #{how}"
+          raise ArgumentError, "how must be one of {{'vertical', 'vertical_relaxed', 'diagonal', 'diagonal_relaxed', 'horizontal'}}, got #{how}"
         end
       elsif first.is_a?(LazyFrame)
         if how == "vertical"
-          return Utils.wrap_ldf(Plr.concat_lf(items, rechunk, parallel, false))
+          return Utils.wrap_ldf(Plr.concat_lf(elems, rechunk, parallel, false))
         elsif how == "vertical_relaxed"
-          return Utils.wrap_ldf(Plr.concat_lf(items, rechunk, parallel, true))
+          return Utils.wrap_ldf(Plr.concat_lf(elems, rechunk, parallel, true))
         elsif how == "diagonal"
-          return Utils.wrap_ldf(Plr.concat_lf_diagonal(items, rechunk, parallel, false))
+          return Utils.wrap_ldf(Plr.concat_lf_diagonal(elems, rechunk, parallel, false))
+        elsif how == "diagonal_relaxed"
+          return Utils.wrap_ldf(Plr.concat_lf_diagonal(elems, rechunk, parallel, true))
+        elsif how == "horizontal"
+          return Utils.wrap_ldf(Plr.concat_lf_horizontal(elems, parallel, strict))
         else
-          raise ArgumentError, "Lazy only allows 'vertical', 'vertical_relaxed', and 'diagonal' concat strategy."
+          raise ArgumentError, "Lazy only allows 'vertical', 'vertical_relaxed', 'diagonal', and 'diagonal_relaxed' concat strategy."
         end
       elsif first.is_a?(Series)
-        # TODO
-        out = Utils.wrap_s(Plr.concat_series(items))
+        if how == "vertical"
+          out = Utils.wrap_s(Plr.concat_series(elems))
+        else
+          msg = "Series only supports 'vertical' concat strategy"
+          raise ArgumentError, msg
+        end
       elsif first.is_a?(Expr)
         out = first
-        items[1..-1].each do |e|
+        elems[1..-1].each do |e|
           out = out.append(e)
         end
       else
@@ -77,7 +208,277 @@ module Polars
       end
     end
 
-    # Align a sequence of frames using the uique values from one or more columns as a key.
+    # Combine multiple DataFrames, LazyFrames, or Series into a single object.
+    #
+    # @note
+    #   This function does not guarantee any specific ordering of rows in the result.
+    #   If you need predictable row ordering, use `Polars.concat` instead.
+    #
+    # @param items [Array]
+    #   DataFrames, LazyFrames, or Series to concatenate.
+    # @param how ['vertical', 'vertical_relaxed', 'diagonal', 'diagonal_relaxed', 'horizontal', 'align', 'align_full', 'align_inner', 'align_left', 'align_right']
+    #   Note that `Series` only support the `vertical` strategy.
+    #
+    #   * vertical: Applies multiple `vstack` operations.
+    #   * vertical_relaxed: Same as `vertical`, but additionally coerces columns to
+    #     their common supertype *if* they are mismatched (eg: Int32 → Int64).
+    #   * diagonal: Finds a union between the column schemas and fills missing column
+    #     values with `null`.
+    #   * diagonal_relaxed: Same as `diagonal`, but additionally coerces columns to
+    #     their common supertype *if* they are mismatched (eg: Int32 → Int64).
+    #   * horizontal: Stacks Series from DataFrames horizontally and fills with `null`
+    #     if the lengths don't match.
+    #   * align, align_full, align_left, align_right: Combines frames horizontally,
+    #     auto-determining the common key columns and aligning rows using the same
+    #     logic as `align_frames` (note that "align" is an alias for "align_full").
+    #     The "align" strategy determines the type of join used to align the frames,
+    #     equivalent to the "how" parameter on `align_frames`. Note that the common
+    #     join columns are automatically coalesced, but other column collisions
+    #     will raise an error (if you need more control over this you should use
+    #     a suitable `join` method directly).
+    # @param strict [Boolean]
+    #   When how=`horizontal`, require all DataFrames to be the same height, raising an error if not.
+    #
+    # @return [Object]
+    #
+    # @example
+    #   df1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
+    #   df2 = Polars::DataFrame.new({"a" => [2], "b" => [4]})
+    #   Polars.union([df1, df2])
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 3   │
+    #   # │ 2   ┆ 4   │
+    #   # └─────┴─────┘
+    #
+    # @example
+    #   df1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
+    #   df2 = Polars::DataFrame.new({"a" => [2.5], "b" => [4]})
+    #   Polars.union([df1, df2], how: "vertical_relaxed")
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ f64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1.0 ┆ 3   │
+    #   # │ 2.5 ┆ 4   │
+    #   # └─────┴─────┘
+    #
+    # @example
+    #   df_h1 = Polars::DataFrame.new({"l1" => [1, 2], "l2" => [3, 4]})
+    #   df_h2 = Polars::DataFrame.new({"r1" => [5, 6], "r2" => [7, 8], "r3" => [9, 10]})
+    #   Polars.union([df_h1, df_h2], how: "horizontal")
+    #   # =>
+    #   # shape: (2, 5)
+    #   # ┌─────┬─────┬─────┬─────┬─────┐
+    #   # │ l1  ┆ l2  ┆ r1  ┆ r2  ┆ r3  │
+    #   # │ --- ┆ --- ┆ --- ┆ --- ┆ --- │
+    #   # │ i64 ┆ i64 ┆ i64 ┆ i64 ┆ i64 │
+    #   # ╞═════╪═════╪═════╪═════╪═════╡
+    #   # │ 1   ┆ 3   ┆ 5   ┆ 7   ┆ 9   │
+    #   # │ 2   ┆ 4   ┆ 6   ┆ 8   ┆ 10  │
+    #   # └─────┴─────┴─────┴─────┴─────┘
+    #
+    # @example The "diagonal" strategy allows for some frames to have missing columns, the values for which are filled with `null`:
+    #   df_d1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
+    #   df_d2 = Polars::DataFrame.new({"a" => [2], "c" => [4]})
+    #   Polars.union([df_d1, df_d2], how: "diagonal")
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌─────┬──────┬──────┐
+    #   # │ a   ┆ b    ┆ c    │
+    #   # │ --- ┆ ---  ┆ ---  │
+    #   # │ i64 ┆ i64  ┆ i64  │
+    #   # ╞═════╪══════╪══════╡
+    #   # │ 1   ┆ 3    ┆ null │
+    #   # │ 2   ┆ null ┆ 4    │
+    #   # └─────┴──────┴──────┘
+    def union(
+      items,
+      how: "vertical",
+      strict: false
+    )
+      elems = items.to_a
+
+      if elems.empty?
+        msg = "cannot concat empty list"
+        raise ArgumentError, msg
+      elsif elems.length == 1 && (elems[0].is_a?(DataFrame) || elems[0].is_a?(Series) || elems[0].is_a?(LazyFrame))
+        return elems[0]
+      end
+
+      if how.start_with?("align")
+        raise Todo
+      end
+
+      out = nil
+      first = elems[0]
+
+      if first.is_a?(DataFrame)
+        if ["vertical", "vertical_relaxed"].include?(how)
+          out = Utils.wrap_ldf(
+            Plr.concat_lf(
+              elems.map { |df| df.lazy },
+              false,
+              true,
+              how.end_with?("relaxed")
+            )
+          ).collect(optimizations: QueryOptFlags._eager)
+        elsif ["diagonal", "diagonal_relaxed"].include?(how)
+          out = Utils.wrap_ldf(
+            Plr.concat_lf_diagonal(
+              elems.map { |df| df.lazy },
+              false,
+              true,
+              how.end_with?("relaxed")
+            )
+          ).collect(optimizations: QueryOptFlags._eager)
+        elsif how == "horizontal"
+          out = Utils.wrap_df(Plr.concat_df_horizontal(elems, strict))
+        else
+          raise Todo
+          msg = "DataFrame `how` must be one of {{#{allowed}}}, got #{how.inspect}"
+          raise ArgumentError, msg
+        end
+
+      elsif first.is_a?(LazyFrame)
+        if ["vertical", "vertical_relaxed"].include?(how)
+          return Utils.wrap_ldf(
+            Plr.concat_lf(
+              elems,
+              false,
+              true,
+              how.end_with?("relaxed")
+            )
+          )
+        elsif ["diagonal", "diagonal_relaxed"].include?(how)
+          return Utils.wrap_ldf(
+            Plr.concat_lf_diagonal(
+              elems,
+              false,
+              true,
+              how.end_with?("relaxed")
+            )
+          )
+        elsif how == "horizontal"
+          return Utils.wrap_ldf(
+            Plr.concat_lf_horizontal(
+              elems,
+              true,
+              strict
+            )
+          )
+        else
+          raise Todo
+          msg = "LazyFrame `how` must be one of {{#{allowed}}}, got #{how.inspect}"
+          raise ArgumentError, msg
+        end
+
+      elsif first.is_a?(Series)
+        if how == "vertical"
+          out = Utils.wrap_s(Plr.concat_series(elems))
+        else
+          msg = "Series only supports 'vertical' concat strategy"
+          raise ArgumentError, msg
+        end
+
+      elsif first.is_a?(Expr)
+        return Utils.wrap_expr(Plr.concat_expr(elems.map { |e| e._rbexpr }, false))
+      else
+        msg = "did not expect type: #{first.class.name.inspect} in `concat`"
+        raise TypeError, msg
+      end
+
+      out
+    end
+
+    # Merge multiple sorted DataFrames or LazyFrames by the sorted key.
+    #
+    # The output of this operation will also be sorted.
+    # It is the callers responsibility that the frames
+    # are sorted in ascending order by that key otherwise
+    # the output will not make sense.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param items [Array]
+    #   DataFrames or LazyFrames to merge.
+    # @param key [String]
+    #   Key that is sorted.
+    # @param maintain_order [Boolean]
+    #   If `true`, the output is guaranteed to have left-biased ordering
+    #   for equal keys: rows from the left frame appear before rows from
+    #   the right frame when their keys are equal.
+    #
+    # @return [Object]
+    #
+    # @example
+    #   df0 = Polars::DataFrame.new(
+    #     {"name" => ["steve", "elise", "bob"], "age" => [42, 44, 18]}
+    #   ).sort("age")
+    #   df1 = Polars::DataFrame.new(
+    #     {"name" => ["anna", "megan", "steve", "thomas"], "age" => [21, 33, 17, 20]}
+    #   ).sort("age")
+    #   df2 = Polars::DataFrame.new({"name" => ["ida", "maya"], "age" => [37, 27]}).sort("age")
+    #   Polars.merge_sorted([df0, df1, df2], "age")
+    #   # =>
+    #   # shape: (9, 2)
+    #   # ┌────────┬─────┐
+    #   # │ name   ┆ age │
+    #   # │ ---    ┆ --- │
+    #   # │ str    ┆ i64 │
+    #   # ╞════════╪═════╡
+    #   # │ steve  ┆ 17  │
+    #   # │ bob    ┆ 18  │
+    #   # │ thomas ┆ 20  │
+    #   # │ anna   ┆ 21  │
+    #   # │ maya   ┆ 27  │
+    #   # │ megan  ┆ 33  │
+    #   # │ ida    ┆ 37  │
+    #   # │ steve  ┆ 42  │
+    #   # │ elise  ┆ 44  │
+    #   # └────────┴─────┘
+    def merge_sorted(
+      items,
+      key,
+      maintain_order: false
+    )
+      elems = items.to_a
+
+      if elems.empty?
+        msg = "cannot merge_sort empty list"
+        raise ArgumentError, msg
+      end
+      if elems.length == 1 && (elems[0].is_a?(DataFrame) || elems[0].is_a?(LazyFrame))
+        return elems[0]
+      end
+
+      if !Utils.is_non_empty_sequence_of(elems, DataFrame) && !Utils.is_non_empty_sequence_of(elems, LazyFrame)
+        msg = "merge_sorted is not supported for #{elems[0].inspect}"
+        raise TypeError, msg
+      end
+
+      frames = elems.map { |df| df.lazy }
+
+      reduce_fn = lambda do |x, y|
+        x.merge_sorted(y, key, maintain_order: maintain_order)
+      end
+
+      lf = Utils.reduce_balanced(reduce_fn, frames)
+      eager = elems[0].is_a?(DataFrame)
+      eager ? lf.collect : lf
+    end
+
+    # Align an array of frames using the unique values from one or more columns as a key.
     #
     # Frames that do not contain the given key values have rows injected (with nulls
     # filling the non-key columns), and each resulting frame is sorted by the key.
@@ -90,13 +491,13 @@ module Polars
     # the same number of rows.
     #
     # @param frames [Array]
-    #   Sequence of DataFrames or LazyFrames.
+    #   Array of DataFrames or LazyFrames.
     # @param on [Object]
     #   One or more columns whose unique values will be used to align the frames.
     # @param select [Object]
     #   Optional post-alignment column select to constrain and/or order
     #   the columns returned from the newly aligned frames.
-    # @param reverse [Object]
+    # @param descending [Object]
     #   Sort the alignment column values in descending order; can be a single
     #   boolean or a list of booleans associated with each column in `on`.
     #
@@ -125,7 +526,7 @@ module Polars
     #     }
     #   )
     #   af1, af2, af3 = Polars.align_frames(
-    #     df1, df2, df3, on: "dt", select: ["x", "y"]
+    #     df1, df2, df3, on: "dt", how: "left", select: ["x", "y"]
     #   )
     #   (af1 * af2 * af3).fill_null(0).select(Polars.sum_horizontal("*").alias("dot"))
     #   # =>
@@ -142,8 +543,9 @@ module Polars
     def align_frames(
       *frames,
       on:,
+      how: "full",
       select: nil,
-      reverse: false
+      descending: false
     )
       if frames.empty?
         return []
@@ -156,7 +558,7 @@ module Polars
       alignment_frame = (
         concat(frames.map { |df| df.lazy.select(on) })
           .unique(maintain_order: false)
-          .sort(on, reverse: reverse)
+          .sort(on, descending: descending)
       )
       alignment_frame = (
         eager ? alignment_frame.collect.lazy : alignment_frame.cache
@@ -167,7 +569,7 @@ module Polars
           alignment_frame.join(
             df.lazy,
             on: alignment_frame.columns,
-            how: "left"
+            how: how
           ).select(df.columns)
         end
       if !select.nil?

data/lib/polars/functions/escape_regex.rb

@@ -0,0 +1,21 @@
+module Polars
+  module Functions
+    # Escapes string regex meta characters.
+    #
+    # @param s [String]
+    #   The string whose meta characters will be escaped.
+    #
+    # @return [String]
+    def escape_regex(s)
+      if s.is_a?(Expr)
+        msg = "escape_regex function is unsupported for `Expr`, you may want use `Expr.str.escape_regex` instead"
+        raise TypeError, msg
+      elsif !s.is_a?(::String)
+        msg = "escape_regex function supports only `String` type, got `#{s.class.name}`"
+        raise TypeError, msg
+      end
+
+      Plr.escape_regex(s)
+    end
+  end
+end