Module: Polars::Functions
- Included in:
- Polars
- Defined in:
- lib/polars/functions.rb,
lib/polars/string_cache.rb,
lib/polars/functions/col.rb,
lib/polars/functions/len.rb,
lib/polars/functions/lit.rb,
lib/polars/functions/lazy.rb,
lib/polars/functions/eager.rb,
lib/polars/functions/random.rb,
lib/polars/functions/repeat.rb,
lib/polars/functions/whenthen.rb,
lib/polars/functions/as_datatype.rb,
lib/polars/functions/range/int_range.rb,
lib/polars/functions/range/date_range.rb,
lib/polars/functions/range/time_range.rb,
lib/polars/functions/aggregation/vertical.rb,
lib/polars/functions/range/datetime_range.rb,
lib/polars/functions/aggregation/horizontal.rb
Instance Method Summary collapse
-
#align_frames(*frames, on:, select: nil, reverse: false) ⇒ Object
Align a sequence of frames using the uique values from one or more columns as a key.
-
#all(*names, ignore_nulls: true) ⇒ Expr
Either return an expression representing all columns, or evaluate a bitwise AND operation.
-
#all_horizontal(*exprs) ⇒ Expr
Compute the bitwise AND horizontally across columns.
-
#any(*names, ignore_nulls: true) ⇒ Expr
Evaluate a bitwise OR operation.
-
#any_horizontal(*exprs) ⇒ Expr
Compute the bitwise OR horizontally across columns.
-
#approx_n_unique(*columns) ⇒ Expr
Approximate count of unique values.
-
#arctan2(y, x) ⇒ Expr
Compute two argument arctan in radians.
-
#arctan2d(y, x) ⇒ Expr
Compute two argument arctan in degrees.
-
#arg_sort_by(exprs, reverse: false) ⇒ Expr
(also: #argsort_by)
Find the indexes that would sort the columns.
-
#arg_where(condition, eager: false) ⇒ Expr, Series
Return indices where
condition
evaluatestrue
. -
#coalesce(exprs, *more_exprs) ⇒ Expr
Folds the columns from left to right, keeping the first non-null value.
-
#col(name, *more_names) ⇒ Expr
Return an expression representing a column in a DataFrame.
-
#collect_all(lazy_frames, type_coercion: true, predicate_pushdown: true, projection_pushdown: true, simplify_expression: true, string_cache: false, no_optimization: false, slice_pushdown: true, common_subplan_elimination: true, allow_streaming: false) ⇒ Array
Collect multiple LazyFrames at the same time.
-
#concat(items, rechunk: true, how: "vertical", parallel: true) ⇒ Object
Aggregate multiple Dataframes/Series to a single DataFrame/Series.
-
#concat_list(exprs) ⇒ Expr
Concat the arrays in a Series dtype List in linear time.
-
#concat_str(exprs, sep: "", ignore_nulls: false) ⇒ Expr
Horizontally concat Utf8 Series in linear time.
-
#corr(a, b, method: "pearson", ddof: 1, propagate_nans: false) ⇒ Expr
Compute the Pearson's or Spearman rank correlation correlation between two columns.
-
#count(*columns) ⇒ Expr
Return the number of non-null values in the column.
-
#cov(a, b, ddof: 1) ⇒ Expr
Compute the covariance between two columns/ expressions.
-
#cum_count(*columns, reverse: false) ⇒ Expr
Return the cumulative count of the non-null values in the column.
-
#cum_fold(acc, f, exprs, include_init: false) ⇒ Object
(also: #cumfold)
Cumulatively accumulate over multiple columns horizontally/row wise with a left fold.
-
#cum_sum(*names) ⇒ Expr
(also: #cumsum)
Cumulatively sum all values.
-
#cum_sum_horizontal(*exprs) ⇒ Expr
(also: #cumsum_horizontal)
Cumulatively sum all values horizontally across columns.
-
#date_range(start, stop, interval = "1d", closed: "both", eager: false) ⇒ Object
Create a range of type
Datetime
(orDate
). -
#date_ranges(start, stop, interval = "1d", closed: "both", eager: false) ⇒ Object
Create a column of date ranges.
-
#datetime_range(start, stop, interval = "1d", closed: "both", time_unit: nil, time_zone: nil, eager: false) ⇒ Object
Generate a datetime range.
-
#datetime_ranges(start, stop, interval: "1d", closed: "both", time_unit: nil, time_zone: nil, eager: false) ⇒ Object
Create a column of datetime ranges.
-
#disable_string_cache ⇒ nil
Disable and clear the global string cache.
-
#duration(weeks: nil, days: nil, hours: nil, minutes: nil, seconds: nil, milliseconds: nil, microseconds: nil, nanoseconds: nil, time_unit: "us") ⇒ Expr
Create polars
Duration
from distinct time components. -
#element ⇒ Expr
Alias for an element in evaluated in an
eval
expression. -
#enable_string_cache ⇒ nil
Enable the global string cache.
-
#exclude(columns) ⇒ Object
Exclude certain columns from a wildcard/regex selection.
-
#first(*columns) ⇒ Expr
Get the first value.
-
#fold(acc, f, exprs) ⇒ Expr
Accumulate over multiple columns horizontally/row wise with a left fold.
-
#format(f_string, *args) ⇒ Expr
Format expressions as a string.
-
#from_epoch(column, unit: "s", eager: false) ⇒ Object
Utility function that parses an epoch timestamp (or Unix time) to Polars Date(time).
-
#get_dummies(df, columns: nil) ⇒ DataFrame
Convert categorical variables into dummy/indicator variables.
-
#groups(column) ⇒ Object
Syntactic sugar for
Polars.col("foo").agg_groups
. -
#head(column, n = 10) ⇒ Expr
Get the first
n
rows. -
#implode(*columns) ⇒ Expr
Aggregate all column values into a list.
-
#int_range(start, stop = nil, step: 1, eager: false, dtype: nil) ⇒ Expr, Series
(also: #arange)
Create a range expression (or Series).
-
#last(*columns) ⇒ Expr
Get the last value.
-
#len ⇒ Expr
(also: #length)
Return the number of rows in the context.
-
#lit(value, dtype: nil, allow_object: nil) ⇒ Expr
Return an expression representing a literal value.
-
#max(*names) ⇒ Expr
Get the maximum value.
-
#max_horizontal(*exprs) ⇒ Expr
Get the maximum value horizontally across columns.
-
#mean(*columns) ⇒ Expr
(also: #avg)
Get the mean value.
-
#mean_horizontal(*exprs) ⇒ Expr
Compute the mean of all values horizontally across columns.
-
#median(*columns) ⇒ Expr
Get the median value.
-
#min(*names) ⇒ Expr
Get the minimum value.
-
#min_horizontal(*exprs) ⇒ Expr
Get the minimum value horizontally across columns.
-
#n_unique(*columns) ⇒ Expr
Count unique values.
-
#nth(*indices) ⇒ Expr
Get the nth column(s) of the context.
-
#ones(n, dtype: nil, eager: true) ⇒ Object
Construct a column of length
n
filled with ones. -
#pearson_corr(a, b, ddof: 1) ⇒ Expr
Compute the pearson's correlation between two columns.
-
#quantile(column, quantile, interpolation: "nearest") ⇒ Expr
Syntactic sugar for
Polars.col("foo").quantile(...)
. -
#repeat(value, n, dtype: nil, eager: false, name: nil) ⇒ Object
Repeat a single value n times.
-
#select(*exprs, **named_exprs) ⇒ DataFrame
Run polars expressions without a context.
-
#set_random_seed(seed) ⇒ nil
Set the global random seed for Polars.
-
#spearman_rank_corr(a, b, ddof: 1, propagate_nans: false) ⇒ Expr
Compute the spearman rank correlation between two columns.
-
#sql_expr(sql) ⇒ Expr
Parse one or more SQL expressions to polars expression(s).
-
#std(column, ddof: 1) ⇒ Expr
Get the standard deviation.
-
#struct(*exprs, schema: nil, eager: false, **named_exprs) ⇒ Object
Collect several columns into a Series of dtype Struct.
-
#sum(*names) ⇒ Expr
Sum all values.
-
#sum_horizontal(*exprs) ⇒ Expr
Sum all values horizontally across columns.
-
#tail(column, n = 10) ⇒ Expr
Get the last
n
rows. -
#time_range(start = nil, stop = nil, interval = "1h", closed: "both", eager: false) ⇒ Object
Generate a time range.
-
#time_ranges(start = nil, stop = nil, interval = "1h", closed: "both", eager: false) ⇒ Object
Create a column of time ranges.
-
#to_list(name) ⇒ Expr
Aggregate to list.
-
#using_string_cache ⇒ Boolean
Check whether the global string cache is enabled.
-
#var(column, ddof: 1) ⇒ Expr
Get the variance.
-
#when(*predicates, **constraints) ⇒ When
Start a "when, then, otherwise" expression.
-
#zeros(n, dtype: nil, eager: true) ⇒ Object
Construct a column of length
n
filled with zeros.
Instance Method Details
#align_frames(*frames, on:, select: nil, reverse: false) ⇒ Object
Align a sequence of frames using the uique 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.
The original column order of input frames is not changed unless select
is
specified (in which case the final column order is determined from that).
Note that this does not result in a joined frame - you receive the same number of frames back that you passed in, but each is now aligned by key and has the same number of rows.
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 |
# File 'lib/polars/functions/eager.rb', line 144 def align_frames( *frames, on:, select: nil, reverse: false ) if frames.empty? return [] elsif frames.map(&:class).uniq.length != 1 raise TypeError, "Input frames must be of a consistent type (all LazyFrame or all DataFrame)" end # establish the superset of all "on" column values, sort, and cache eager = frames[0].is_a?(DataFrame) alignment_frame = ( concat(frames.map { |df| df.lazy.select(on) }) .unique(maintain_order: false) .sort(on, reverse: reverse) ) alignment_frame = ( eager ? alignment_frame.collect.lazy : alignment_frame.cache ) # finally, align all frames aligned_frames = frames.map do |df| alignment_frame.join( df.lazy, on: alignment_frame.columns, how: "left" ).select(df.columns) end if !select.nil? aligned_frames = aligned_frames.map { |df| df.select(select) } end eager ? aligned_frames.map(&:collect) : aligned_frames end |
#all(*names, ignore_nulls: true) ⇒ Expr
Either return an expression representing all columns, or evaluate a bitwise AND operation.
If no arguments are passed, this function is syntactic sugar for col("*")
.
Otherwise, this function is syntactic sugar for col(names).all
.
44 45 46 47 48 49 50 |
# File 'lib/polars/functions/aggregation/vertical.rb', line 44 def all(*names, ignore_nulls: true) if names.empty? return col("*") end col(*names).all(drop_nulls: ignore_nulls) end |
#all_horizontal(*exprs) ⇒ Expr
Compute the bitwise AND horizontally across columns.
34 35 36 37 |
# File 'lib/polars/functions/aggregation/horizontal.rb', line 34 def all_horizontal(*exprs) rbexprs = Utils.parse_into_list_of_expressions(*exprs) Utils.wrap_expr(Plr.all_horizontal(rbexprs)) end |
#any(*names, ignore_nulls: true) ⇒ Expr
Evaluate a bitwise OR operation.
Syntactic sugar for col(names).any
.
80 81 82 |
# File 'lib/polars/functions/aggregation/vertical.rb', line 80 def any(*names, ignore_nulls: true) col(*names).any(drop_nulls: ignore_nulls) end |
#any_horizontal(*exprs) ⇒ Expr
Compute the bitwise OR horizontally across columns.
70 71 72 73 |
# File 'lib/polars/functions/aggregation/horizontal.rb', line 70 def any_horizontal(*exprs) rbexprs = Utils.parse_into_list_of_expressions(*exprs) Utils.wrap_expr(Plr.any_horizontal(rbexprs)) end |
#approx_n_unique(*columns) ⇒ Expr
Approximate count of unique values.
This function is syntactic sugar for col(columns).approx_n_unique
, and
uses the HyperLogLog++ algorithm for cardinality estimation.
403 404 405 |
# File 'lib/polars/functions/lazy.rb', line 403 def approx_n_unique(*columns) col(*columns).approx_n_unique end |
#arctan2(y, x) ⇒ Expr
Compute two argument arctan in radians.
Returns the angle (in radians) in the plane between the positive x-axis and the ray from the origin to (x,y).
876 877 878 879 880 881 882 883 884 |
# File 'lib/polars/functions/lazy.rb', line 876 def arctan2(y, x) if Utils.strlike?(y) y = col(y) end if Utils.strlike?(x) x = col(x) end Utils.wrap_expr(Plr.arctan2(y._rbexpr, x._rbexpr)) end |
#arctan2d(y, x) ⇒ Expr
Compute two argument arctan in degrees.
Returns the angle (in degrees) in the plane between the positive x-axis and the ray from the origin to (x,y).
921 922 923 924 925 926 927 928 929 |
# File 'lib/polars/functions/lazy.rb', line 921 def arctan2d(y, x) if Utils.strlike?(y) y = col(y) end if Utils.strlike?(x) x = col(x) end Utils.wrap_expr(Plr.arctan2d(y._rbexpr, x._rbexpr)) end |
#arg_sort_by(exprs, reverse: false) ⇒ Expr Also known as: argsort_by
Find the indexes that would sort the columns.
Argsort by multiple columns. The first column will be used for the ordering. If there are duplicates in the first column, the second column will be used to determine the ordering and so on.
1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 |
# File 'lib/polars/functions/lazy.rb', line 1027 def arg_sort_by(exprs, reverse: false) if !exprs.is_a?(::Array) exprs = [exprs] end if reverse == true || reverse == false reverse = [reverse] * exprs.length end exprs = Utils.parse_into_list_of_expressions(exprs) Utils.wrap_expr(Plr.arg_sort_by(exprs, reverse)) end |
#arg_where(condition, eager: false) ⇒ Expr, Series
Return indices where condition
evaluates true
.
1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 |
# File 'lib/polars/functions/lazy.rb', line 1164 def arg_where(condition, eager: false) if eager if !condition.is_a?(Series) raise ArgumentError, "expected 'Series' in 'arg_where' if 'eager: true', got #{condition.class.name}" end condition.to_frame.select(arg_where(Polars.col(condition.name))).to_series else condition = Utils.parse_into_expression(condition, str_as_lit: true) Utils.wrap_expr(Plr.arg_where(condition)) end end |
#coalesce(exprs, *more_exprs) ⇒ Expr
Folds the columns from left to right, keeping the first non-null value.
1222 1223 1224 1225 |
# File 'lib/polars/functions/lazy.rb', line 1222 def coalesce(exprs, *more_exprs) exprs = Utils.parse_into_list_of_expressions(exprs, *more_exprs) Utils.wrap_expr(Plr.coalesce(exprs)) end |
#col(name, *more_names) ⇒ Expr
Return an expression representing a column in a DataFrame.
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
# File 'lib/polars/functions/col.rb', line 6 def col(name, *more_names) if more_names.any? if Utils.strlike?(name) names_str = [name] names_str.concat(more_names) return Utils.wrap_expr(Plr.cols(names_str.map(&:to_s))) elsif Utils.is_polars_dtype(name) dtypes = [name] dtypes.concat(more_names) return Utils.wrap_expr(Plr.dtype_cols(dtypes)) else msg = "invalid input for `col`\n\nExpected `str` or `DataType`, got #{name.class.name}." raise TypeError, msg end end if Utils.strlike?(name) Utils.wrap_expr(Plr.col(name.to_s)) elsif Utils.is_polars_dtype(name) Utils.wrap_expr(Plr.dtype_cols([name])) elsif name.is_a?(::Array) names = Array(name) if names.empty? return Utils.wrap_expr(Plr.cols(names)) end item = names[0] if Utils.strlike?(item) Utils.wrap_expr(Plr.cols(names.map(&:to_s))) elsif Utils.is_polars_dtype(item) Utils.wrap_expr(Plr.dtype_cols(names)) else msg = "invalid input for `col`\n\nExpected iterable of type `str` or `DataType`, got iterable of type #{item.class.name}." raise TypeError, msg end else msg = "invalid input for `col`\n\nExpected `str` or `DataType`, got #{name.class.name}." raise TypeError, msg end end |
#collect_all(lazy_frames, type_coercion: true, predicate_pushdown: true, projection_pushdown: true, simplify_expression: true, string_cache: false, no_optimization: false, slice_pushdown: true, common_subplan_elimination: true, allow_streaming: false) ⇒ Array
Collect multiple LazyFrames at the same time.
This runs all the computation graphs in parallel on Polars threadpool.
1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 |
# File 'lib/polars/functions/lazy.rb', line 1065 def collect_all( lazy_frames, type_coercion: true, predicate_pushdown: true, projection_pushdown: true, simplify_expression: true, string_cache: false, no_optimization: false, slice_pushdown: true, common_subplan_elimination: true, allow_streaming: false ) if no_optimization predicate_pushdown = false projection_pushdown = false slice_pushdown = false common_subplan_elimination = false end prepared = [] lazy_frames.each do |lf| ldf = lf._ldf.optimization_toggle( type_coercion, predicate_pushdown, projection_pushdown, simplify_expression, slice_pushdown, common_subplan_elimination, allow_streaming, false ) prepared << ldf end out = Plr.collect_all(prepared) # wrap the rbdataframes into dataframe result = out.map { |rbdf| Utils.wrap_df(rbdf) } result end |
#concat(items, rechunk: true, how: "vertical", parallel: true) ⇒ Object
Aggregate multiple Dataframes/Series to a single DataFrame/Series.
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
# File 'lib/polars/functions/eager.rb', line 35 def concat(items, rechunk: true, how: "vertical", parallel: true) if items.empty? raise ArgumentError, "cannot concat empty list" end first = items[0] if first.is_a?(DataFrame) if how == "vertical" out = Utils.wrap_df(Plr.concat_df(items)) elsif how == "diagonal" out = Utils.wrap_df(Plr.concat_df_diagonal(items)) elsif how == "horizontal" out = Utils.wrap_df(Plr.concat_df_horizontal(items)) else raise ArgumentError, "how must be one of {{'vertical', 'diagonal', 'horizontal'}}, got #{how}" end elsif first.is_a?(LazyFrame) if how == "vertical" return Utils.wrap_ldf(Plr.concat_lf(items, rechunk, parallel, false)) elsif how == "vertical_relaxed" return Utils.wrap_ldf(Plr.concat_lf(items, rechunk, parallel, true)) elsif how == "diagonal" return Utils.wrap_ldf(Plr.concat_lf_diagonal(items, rechunk, parallel, false)) else raise ArgumentError, "Lazy only allows 'vertical', 'vertical_relaxed', and 'diagonal' concat strategy." end elsif first.is_a?(Series) # TODO out = Utils.wrap_s(Plr.concat_series(items)) elsif first.is_a?(Expr) out = first items[1..-1].each do |e| out = out.append(e) end else raise ArgumentError, "did not expect type: #{first.class.name} in 'Polars.concat'." end if rechunk out.rechunk else out end end |
#concat_list(exprs) ⇒ Expr
Concat the arrays in a Series dtype List in linear time.
89 90 91 92 |
# File 'lib/polars/functions/as_datatype.rb', line 89 def concat_list(exprs) exprs = Utils.parse_into_list_of_expressions(exprs) Utils.wrap_expr(Plr.concat_list(exprs)) end |
#concat_str(exprs, sep: "", ignore_nulls: false) ⇒ Expr
Horizontally concat Utf8 Series in linear time. Non-Utf8 columns are cast to Utf8.
213 214 215 216 |
# File 'lib/polars/functions/as_datatype.rb', line 213 def concat_str(exprs, sep: "", ignore_nulls: false) exprs = Utils.parse_into_list_of_expressions(exprs) Utils.wrap_expr(Plr.concat_str(exprs, sep, ignore_nulls)) end |
#corr(a, b, method: "pearson", ddof: 1, propagate_nans: false) ⇒ Expr
Compute the Pearson's or Spearman rank correlation correlation between two columns.
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 |
# File 'lib/polars/functions/lazy.rb', line 728 def corr( a, b, method: "pearson", ddof: 1, propagate_nans: false ) a = Utils.parse_into_expression(a) b = Utils.parse_into_expression(b) if method == "pearson" Utils.wrap_expr(Plr.pearson_corr(a, b, ddof)) elsif method == "spearman" Utils.wrap_expr(Plr.spearman_rank_corr(a, b, ddof, propagate_nans)) else msg = "method must be one of {{'pearson', 'spearman'}}, got #{method}" raise ArgumentError, msg end end |
#count(*columns) ⇒ Expr
Return the number of non-null values in the column.
This function is syntactic sugar for col(columns).count
.
Calling this function without any arguments returns the number of rows in the
context. This way of using the function is deprecated. Please use len
instead.
70 71 72 73 74 75 76 77 |
# File 'lib/polars/functions/lazy.rb', line 70 def count(*columns) if columns.empty? warn "`Polars.count` is deprecated. Use `Polars.length` instead." return Utils.wrap_expr(Plr.len._alias("count")) end col(*columns).count end |
#cov(a, b, ddof: 1) ⇒ Expr
Compute the covariance between two columns/ expressions.
779 780 781 782 783 |
# File 'lib/polars/functions/lazy.rb', line 779 def cov(a, b, ddof: 1) a = Utils.parse_into_expression(a) b = Utils.parse_into_expression(b) Utils.wrap_expr(Plr.cov(a, b, ddof)) end |
#cum_count(*columns, reverse: false) ⇒ Expr
Return the cumulative count of the non-null values in the column.
This function is syntactic sugar for col(columns).cum_count
.
If no arguments are passed, returns the cumulative count of a context. Rows containing null values count towards the result.
107 108 109 |
# File 'lib/polars/functions/lazy.rb', line 107 def cum_count(*columns, reverse: false) col(*columns).cum_count(reverse: reverse) end |
#cum_fold(acc, f, exprs, include_init: false) ⇒ Object Also known as: cumfold
If you simply want the first encountered expression as accumulator,
consider using cumreduce
.
Cumulatively accumulate over multiple columns horizontally/row wise with a left fold.
Every cumulative result is added as a separate field in a Struct column.
827 828 829 830 831 832 833 834 835 |
# File 'lib/polars/functions/lazy.rb', line 827 def cum_fold(acc, f, exprs, include_init: false) acc = Utils.parse_into_expression(acc, str_as_lit: true) if exprs.is_a?(Expr) exprs = [exprs] end exprs = Utils.parse_into_list_of_expressions(exprs) Utils.wrap_expr(Plr.cum_fold(acc, f, exprs, include_init)) end |
#cum_sum(*names) ⇒ Expr Also known as: cumsum
Cumulatively sum all values.
Syntactic sugar for col(names).cum_sum
.
277 278 279 |
# File 'lib/polars/functions/aggregation/vertical.rb', line 277 def cum_sum(*names) col(*names).cum_sum end |
#cum_sum_horizontal(*exprs) ⇒ Expr Also known as: cumsum_horizontal
Cumulatively sum all values horizontally across columns.
235 236 237 238 239 240 241 242 243 |
# File 'lib/polars/functions/aggregation/horizontal.rb', line 235 def cum_sum_horizontal(*exprs) rbexprs = Utils.parse_into_list_of_expressions(*exprs) exprs_wrapped = rbexprs.map { |e| Utils.wrap_expr(e) } # (Expr): use u32 as that will not cast to float as eagerly Polars.cum_fold(Polars.lit(0).cast(UInt32), ->(a, b) { a + b }, exprs_wrapped).alias( "cum_sum" ) end |
#date_range(start, stop, interval = "1d", closed: "both", eager: false) ⇒ Object
If both low
and high
are passed as date types (not datetime), and the
interval granularity is no finer than 1d, the returned range is also of
type date. All other permutations return a datetime Series.
Create a range of type Datetime
(or Date
).
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
# File 'lib/polars/functions/range/date_range.rb', line 37 def date_range( start, stop, interval = "1d", closed: "both", eager: false ) interval = Utils.parse_interval_argument(interval) start_rbexpr = Utils.parse_into_expression(start) end_rbexpr = Utils.parse_into_expression(stop) result = Utils.wrap_expr( Plr.date_range(start_rbexpr, end_rbexpr, interval, closed) ) if eager return F.select(result).to_series end result end |
#date_ranges(start, stop, interval = "1d", closed: "both", eager: false) ⇒ Object
interval
is created according to the following string language:
- 1ns (1 nanosecond)
- 1us (1 microsecond)
- 1ms (1 millisecond)
- 1s (1 second)
- 1m (1 minute)
- 1h (1 hour)
- 1d (1 calendar day)
- 1w (1 calendar week)
- 1mo (1 calendar month)
- 1q (1 calendar quarter)
- 1y (1 calendar year)
Or combine them: "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
By "calendar day", we mean the corresponding time on the next day (which may not be 24 hours, due to daylight savings). Similarly for "calendar week", "calendar month", "calendar quarter", and "calendar year".
Create a column of date ranges.
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 |
# File 'lib/polars/functions/range/date_range.rb', line 116 def date_ranges( start, stop, interval = "1d", closed: "both", eager: false ) interval = Utils.parse_interval_argument(interval) start_rbexpr = Utils.parse_into_expression(start) end_rbexpr = Utils.parse_into_expression(stop) result = Utils.wrap_expr(Plr.date_ranges(start_rbexpr, end_rbexpr, interval, closed)) if eager return F.select(result).to_series end result end |
#datetime_range(start, stop, interval = "1d", closed: "both", time_unit: nil, time_zone: nil, eager: false) ⇒ Object
Generate a datetime range.
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 |
# File 'lib/polars/functions/range/datetime_range.rb', line 52 def datetime_range( start, stop, interval = "1d", closed: "both", time_unit: nil, time_zone: nil, eager: false ) interval = Utils.parse_interval_argument(interval) if time_unit.nil? && interval.include?("ns") time_unit = "ns" end start_rbexpr = Utils.parse_into_expression(start) end_rbexpr = Utils.parse_into_expression(stop) result = Utils.wrap_expr( Plr.datetime_range( start_rbexpr, end_rbexpr, interval, closed, time_unit, time_zone ) ) if eager return Polars.select(result).to_series end result end |
#datetime_ranges(start, stop, interval: "1d", closed: "both", time_unit: nil, time_zone: nil, eager: false) ⇒ Object
Create a column of datetime ranges.
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 |
# File 'lib/polars/functions/range/datetime_range.rb', line 119 def datetime_ranges( start, stop, interval: "1d", closed: "both", time_unit: nil, time_zone: nil, eager: false ) interval = Utils.parse_interval_argument(interval) if time_unit.nil? && interval.include?("ns") time_unit = "ns" end start_rbexpr = Utils.parse_into_expression(start) end_rbexpr = Utils.parse_into_expression(stop) result = Utils.wrap_expr( Plr.datetime_ranges( start_rbexpr, end_rbexpr, interval, closed, time_unit, time_zone ) ) if eager return Polars.select(result).to_series end result end |
#disable_string_cache ⇒ nil
Disable and clear the global string cache.
64 65 66 |
# File 'lib/polars/string_cache.rb', line 64 def disable_string_cache Plr.disable_string_cache end |
#duration(weeks: nil, days: nil, hours: nil, minutes: nil, seconds: nil, milliseconds: nil, microseconds: nil, nanoseconds: nil, time_unit: "us") ⇒ Expr
Create polars Duration
from distinct time components.
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 |
# File 'lib/polars/functions/as_datatype.rb', line 35 def duration( weeks: nil, days: nil, hours: nil, minutes: nil, seconds: nil, milliseconds: nil, microseconds: nil, nanoseconds: nil, time_unit: "us" ) if !weeks.nil? weeks = Utils.parse_into_expression(weeks, str_as_lit: false) end if !days.nil? days = Utils.parse_into_expression(days, str_as_lit: false) end if !hours.nil? hours = Utils.parse_into_expression(hours, str_as_lit: false) end if !minutes.nil? minutes = Utils.parse_into_expression(minutes, str_as_lit: false) end if !seconds.nil? seconds = Utils.parse_into_expression(seconds, str_as_lit: false) end if !milliseconds.nil? milliseconds = Utils.parse_into_expression(milliseconds, str_as_lit: false) end if !microseconds.nil? microseconds = Utils.parse_into_expression(microseconds, str_as_lit: false) end if !nanoseconds.nil? nanoseconds = Utils.parse_into_expression(nanoseconds, str_as_lit: false) end Utils.wrap_expr( Plr.duration( weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds, time_unit ) ) end |
#element ⇒ Expr
Alias for an element in evaluated in an eval
expression.
23 24 25 |
# File 'lib/polars/functions/lazy.rb', line 23 def element col("") end |
#enable_string_cache ⇒ nil
Enable the global string cache.
Categorical
columns created under the same global string cache have
the same underlying physical value when string values are equal. This allows the
columns to be concatenated or used in a join operation, for example.
37 38 39 |
# File 'lib/polars/string_cache.rb', line 37 def enable_string_cache Plr.enable_string_cache end |
#exclude(columns) ⇒ Object
Exclude certain columns from a wildcard/regex selection.
990 991 992 |
# File 'lib/polars/functions/lazy.rb', line 990 def exclude(columns) col("*").exclude(columns) end |
#first(*columns) ⇒ Expr
Get the first value.
459 460 461 462 463 464 465 |
# File 'lib/polars/functions/lazy.rb', line 459 def first(*columns) if columns.empty? return Utils.wrap_expr(Plr.first) end col(*columns).first end |
#fold(acc, f, exprs) ⇒ Expr
Accumulate over multiple columns horizontally/row wise with a left fold.
794 795 796 797 798 799 800 801 802 |
# File 'lib/polars/functions/lazy.rb', line 794 def fold(acc, f, exprs) acc = Utils.parse_into_expression(acc, str_as_lit: true) if exprs.is_a?(Expr) exprs = [exprs] end exprs = Utils.parse_into_list_of_expressions(exprs) Utils.wrap_expr(Plr.fold(acc, f, exprs)) end |
#format(f_string, *args) ⇒ Expr
Format expressions as a string.
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 |
# File 'lib/polars/functions/as_datatype.rb', line 251 def format(f_string, *args) if f_string.scan("{}").length != args.length raise ArgumentError, "number of placeholders should equal the number of arguments" end exprs = [] arguments = args.each f_string.split(/(\{\})/).each do |s| if s == "{}" e = Utils.wrap_expr(Utils.parse_into_expression(arguments.next)) exprs << e elsif s.length > 0 exprs << lit(s) end end concat_str(exprs, sep: "") end |
#from_epoch(column, unit: "s", eager: false) ⇒ Object
Utility function that parses an epoch timestamp (or Unix time) to Polars Date(time).
Depending on the unit
provided, this function will return a different dtype:
- unit: "d" returns pl.Date
- unit: "s" returns pl.Datetime"us"
- unit: "ms" returns pl.Datetime["ms"]
- unit: "us" returns pl.Datetime["us"]
- unit: "ns" returns pl.Datetime["ns"]
1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 |
# File 'lib/polars/functions/lazy.rb', line 1258 def from_epoch(column, unit: "s", eager: false) if Utils.strlike?(column) column = col(column) elsif !column.is_a?(Series) && !column.is_a?(Expr) column = Series.new(column) end if unit == "d" expr = column.cast(Date) elsif unit == "s" expr = (column.cast(Int64) * 1_000_000).cast(Datetime.new("us")) elsif Utils::DTYPE_TEMPORAL_UNITS.include?(unit) expr = column.cast(Datetime.new(unit)) else raise ArgumentError, "'unit' must be one of {{'ns', 'us', 'ms', 's', 'd'}}, got '#{unit}'." end if eager if !column.is_a?(Series) raise ArgumentError, "expected Series or Array if eager: true, got #{column.class.name}" else column.to_frame.select(expr).to_series end else expr end end |
#get_dummies(df, columns: nil) ⇒ DataFrame
Convert categorical variables into dummy/indicator variables.
12 13 14 |
# File 'lib/polars/functions.rb', line 12 def get_dummies(df, columns: nil) df.to_dummies(columns: columns) end |
#groups(column) ⇒ Object
Syntactic sugar for Polars.col("foo").agg_groups
.
997 998 999 |
# File 'lib/polars/functions/lazy.rb', line 997 def groups(column) col(column).agg_groups end |
#head(column, n = 10) ⇒ Expr
Get the first n
rows.
This function is syntactic sugar for col(column).head(n)
.
620 621 622 |
# File 'lib/polars/functions/lazy.rb', line 620 def head(column, n = 10) col(column).head(n) end |
#implode(*columns) ⇒ Expr
Aggregate all column values into a list.
This function is syntactic sugar for col(name).implode
.
150 151 152 |
# File 'lib/polars/functions/lazy.rb', line 150 def implode(*columns) col(*columns).implode end |
#int_range(start, stop = nil, step: 1, eager: false, dtype: nil) ⇒ Expr, Series Also known as: arange
Create a range expression (or Series).
This can be used in a select
, with_column
, etc. Be sure that the resulting
range size is equal to the length of the DataFrame you are collecting.
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
# File 'lib/polars/functions/range/int_range.rb', line 31 def int_range(start, stop = nil, step: 1, eager: false, dtype: nil) if stop.nil? stop = start start = 0 end start = Utils.parse_into_expression(start) stop = Utils.parse_into_expression(stop) dtype ||= Int64 dtype = dtype.to_s if dtype.is_a?(Symbol) result = Utils.wrap_expr(Plr.int_range(start, stop, step, dtype)).alias("arange") if eager return select(result).to_series end result end |
#last(*columns) ⇒ Expr
Get the last value.
519 520 521 522 523 524 525 |
# File 'lib/polars/functions/lazy.rb', line 519 def last(*columns) if columns.empty? return Utils.wrap_expr(Plr.last) end col(*columns).last end |
#len ⇒ Expr Also known as: length
Return the number of rows in the context.
This is similar to COUNT(*)
in SQL.
44 45 46 |
# File 'lib/polars/functions/len.rb', line 44 def len Utils.wrap_expr(Plr.len) end |
#lit(value, dtype: nil, allow_object: nil) ⇒ Expr
Return an expression representing a literal value.
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
# File 'lib/polars/functions/lit.rb', line 6 def lit(value, dtype: nil, allow_object: nil) if value.is_a?(::Time) || value.is_a?(::DateTime) time_unit = dtype&.time_unit || "ns" time_zone = dtype.&time_zone e = lit(Utils.datetime_to_int(value, time_unit)).cast(Datetime.new(time_unit)) if time_zone return e.dt.replace_time_zone(time_zone.to_s) else return e end elsif value.is_a?(::Date) return lit(::Time.utc(value.year, value.month, value.day)).cast(Date) elsif value.is_a?(Polars::Series) name = value.name value = value._s e = Utils.wrap_expr(Plr.lit(value, allow_object)) if name == "" return e end return e.alias(name) elsif (defined?(Numo::NArray) && value.is_a?(Numo::NArray)) || value.is_a?(::Array) return lit(Series.new("", value)) elsif dtype return Utils.wrap_expr(Plr.lit(value, allow_object)).cast(dtype) end Utils.wrap_expr(Plr.lit(value, allow_object)) end |
#max(*names) ⇒ Expr
Get the maximum value.
Syntactic sugar for col(names).max
.
135 136 137 |
# File 'lib/polars/functions/aggregation/vertical.rb', line 135 def max(*names) col(*names).max end |
#max_horizontal(*exprs) ⇒ Expr
Get the maximum value horizontally across columns.
103 104 105 106 |
# File 'lib/polars/functions/aggregation/horizontal.rb', line 103 def max_horizontal(*exprs) rbexprs = Utils.parse_into_list_of_expressions(*exprs) Utils.wrap_expr(Plr.max_horizontal(rbexprs)) end |
#mean(*columns) ⇒ Expr Also known as: avg
Get the mean value.
This function is syntactic sugar for col(columns).mean
.
272 273 274 |
# File 'lib/polars/functions/lazy.rb', line 272 def mean(*columns) col(*columns).mean end |
#mean_horizontal(*exprs) ⇒ Expr
Compute the mean of all values horizontally across columns.
202 203 204 205 |
# File 'lib/polars/functions/aggregation/horizontal.rb', line 202 def mean_horizontal(*exprs) rbexprs = Utils.parse_into_list_of_expressions(*exprs) Utils.wrap_expr(Plr.mean_horizontal(rbexprs)) end |
#median(*columns) ⇒ Expr
Get the median value.
This function is syntactic sugar for pl.col(columns).median
.
316 317 318 |
# File 'lib/polars/functions/lazy.rb', line 316 def median(*columns) col(*columns).median end |
#min(*names) ⇒ Expr
Get the minimum value.
Syntactic sugar for col(names).min
.
190 191 192 |
# File 'lib/polars/functions/aggregation/vertical.rb', line 190 def min(*names) col(*names).min end |
#min_horizontal(*exprs) ⇒ Expr
Get the minimum value horizontally across columns.
136 137 138 139 |
# File 'lib/polars/functions/aggregation/horizontal.rb', line 136 def min_horizontal(*exprs) rbexprs = Utils.parse_into_list_of_expressions(*exprs) Utils.wrap_expr(Plr.min_horizontal(rbexprs)) end |
#n_unique(*columns) ⇒ Expr
Count unique values.
This function is syntactic sugar for col(columns).n_unique
.
359 360 361 |
# File 'lib/polars/functions/lazy.rb', line 359 def n_unique(*columns) col(*columns).n_unique end |
#nth(*indices) ⇒ Expr
Get the nth column(s) of the context.
568 569 570 571 572 573 574 |
# File 'lib/polars/functions/lazy.rb', line 568 def nth(*indices) if indices.length == 1 && indices[0].is_a?(Array) indices = indices[0] end Utils.wrap_expr(Plr.index_cols(indices)) end |
#ones(n, dtype: nil, eager: true) ⇒ Object
Construct a column of length n
filled with ones.
This is syntactic sugar for the repeat
function.
81 82 83 84 85 86 87 88 |
# File 'lib/polars/functions/repeat.rb', line 81 def ones(n, dtype: nil, eager: true) if (zero = _one_or_zero_by_dtype(1, dtype)).nil? msg = "invalid dtype for `ones`; found #{dtype}" raise TypeError, msg end repeat(zero, n, dtype: dtype, eager: eager).alias("ones") end |
#pearson_corr(a, b, ddof: 1) ⇒ Expr
Compute the pearson's correlation between two columns.
53 54 55 |
# File 'lib/polars/functions.rb', line 53 def pearson_corr(a, b, ddof: 1) corr(a, b, method: "pearson", ddof: ddof) end |
#quantile(column, quantile, interpolation: "nearest") ⇒ Expr
Syntactic sugar for Polars.col("foo").quantile(...)
.
1011 1012 1013 |
# File 'lib/polars/functions/lazy.rb', line 1011 def quantile(column, quantile, interpolation: "nearest") col(column).quantile(quantile, interpolation: interpolation) end |
#repeat(value, n, dtype: nil, eager: false, name: nil) ⇒ Object
Repeat a single value n times.
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 |
# File 'lib/polars/functions/repeat.rb', line 37 def repeat(value, n, dtype: nil, eager: false, name: nil) if !name.nil? warn "the `name` argument is deprecated. Use the `alias` method instead." end if n.is_a?(Integer) n = lit(n) end value = Utils.parse_into_expression(value, str_as_lit: true) expr = Utils.wrap_expr(Plr.repeat(value, n._rbexpr, dtype)) if !name.nil? expr = expr.alias(name) end if eager return select(expr).to_series end expr end |
#select(*exprs, **named_exprs) ⇒ DataFrame
Run polars expressions without a context.
This is syntactic sugar for running df.select
on an empty DataFrame.
1137 1138 1139 |
# File 'lib/polars/functions/lazy.rb', line 1137 def select(*exprs, **named_exprs) DataFrame.new([]).select(*exprs, **named_exprs) end |
#set_random_seed(seed) ⇒ nil
Set the global random seed for Polars.
This random seed is used to determine things such as shuffle ordering.
12 13 14 |
# File 'lib/polars/functions/random.rb', line 12 def set_random_seed(seed) Plr.set_random_seed(seed) end |
#spearman_rank_corr(a, b, ddof: 1, propagate_nans: false) ⇒ Expr
Compute the spearman rank correlation between two columns.
Missing data will be excluded from the computation.
39 40 41 |
# File 'lib/polars/functions.rb', line 39 def spearman_rank_corr(a, b, ddof: 1, propagate_nans: false) corr(a, b, method: "spearman", ddof: ddof, propagate_nans: propagate_nans) end |
#sql_expr(sql) ⇒ Expr
Parse one or more SQL expressions to polars expression(s).
1321 1322 1323 1324 1325 1326 1327 |
# File 'lib/polars/functions/lazy.rb', line 1321 def sql_expr(sql) if sql.is_a?(::String) Utils.wrap_expr(Plr.sql_expr(sql)) else sql.map { |q| Utils.wrap_expr(Plr.sql_expr(q)) } end end |
#std(column, ddof: 1) ⇒ Expr
Get the standard deviation.
This function is syntactic sugar for col(column).std(ddof: ddof)
.
189 190 191 |
# File 'lib/polars/functions/lazy.rb', line 189 def std(column, ddof: 1) col(column).std(ddof: ddof) end |
#struct(*exprs, schema: nil, eager: false, **named_exprs) ⇒ Object
Collect several columns into a Series of dtype Struct.
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 |
# File 'lib/polars/functions/as_datatype.rb', line 149 def struct(*exprs, schema: nil, eager: false, **named_exprs) rbexprs = Utils.parse_into_list_of_expressions(*exprs, **named_exprs) expr = Utils.wrap_expr(Plr.as_struct(rbexprs)) if !schema.nil? && !schema.empty? if !exprs.any? # no columns or expressions provided; create one from schema keys expr = Utils.wrap_expr( Plr.as_struct(Utils.parse_into_list_of_expressions(schema.keys)) ) expr = expr.cast(Struct.new(schema), strict: false) end end if eager Polars.select(expr).to_series else expr end end |
#sum(*names) ⇒ Expr
Sum all values.
Syntactic sugar for col(name).sum
.
245 246 247 |
# File 'lib/polars/functions/aggregation/vertical.rb', line 245 def sum(*names) col(*names).sum end |
#sum_horizontal(*exprs) ⇒ Expr
Sum all values horizontally across columns.
169 170 171 172 |
# File 'lib/polars/functions/aggregation/horizontal.rb', line 169 def sum_horizontal(*exprs) rbexprs = Utils.parse_into_list_of_expressions(*exprs) Utils.wrap_expr(Plr.sum_horizontal(rbexprs)) end |
#tail(column, n = 10) ⇒ Expr
Get the last n
rows.
This function is syntactic sugar for col(column).tail(n)
.
668 669 670 |
# File 'lib/polars/functions/lazy.rb', line 668 def tail(column, n = 10) col(column).tail(n) end |
#time_range(start = nil, stop = nil, interval = "1h", closed: "both", eager: false) ⇒ Object
Generate a time range.
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
# File 'lib/polars/functions/range/time_range.rb', line 35 def time_range( start = nil, stop = nil, interval = "1h", closed: "both", eager: false ) interval = Utils.parse_interval_argument(interval) ["y", "mo", "w", "d"].each do |unit| if interval.include?(unit) msg = "invalid interval unit for time_range: found #{unit.inspect}" raise ArgumentError, msg end end if start.nil? # start = time(0, 0, 0) raise Todo end if stop.nil? # stop = time(23, 59, 59, 999999) raise Todo end start_rbexpr = Utils.parse_into_expression(start) end_rbexpr = Utils.parse_into_expression(stop) result = Utils.wrap_expr(Plr.time_range(start_rbexpr, end_rbexpr, interval, closed)) if eager return Polars.select(result).to_series end result end |
#time_ranges(start = nil, stop = nil, interval = "1h", closed: "both", eager: false) ⇒ Object
Create a column of time ranges.
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 |
# File 'lib/polars/functions/range/time_range.rb', line 105 def time_ranges( start = nil, stop = nil, interval = "1h", closed: "both", eager: false ) interval = Utils.parse_interval_argument(interval) ["y", "mo", "w", "d"].each do |unit| if interval.include?(unit) msg = "invalid interval unit for time_range: found #{unit.inspect}" raise ArgumentError, msg end end if start.nil? # start = time(0, 0, 0) raise Todo end if stop.nil? # stop = time(23, 59, 59, 999999) raise Todo end start_rbexpr = Utils.parse_into_expression(start) end_rbexpr = Utils.parse_into_expression(stop) result = Utils.wrap_expr(Plr.time_ranges(start_rbexpr, end_rbexpr, interval, closed)) if eager return Polars.select(result).to_series end result end |
#to_list(name) ⇒ Expr
Aggregate to list.
19 20 21 |
# File 'lib/polars/functions.rb', line 19 def to_list(name) col(name).list end |
#using_string_cache ⇒ Boolean
Check whether the global string cache is enabled.
71 72 73 |
# File 'lib/polars/string_cache.rb', line 71 def using_string_cache Plr.using_string_cache end |
#var(column, ddof: 1) ⇒ Expr
Get the variance.
This function is syntactic sugar for col(column).var(ddof: ddof)
.
228 229 230 |
# File 'lib/polars/functions/lazy.rb', line 228 def var(column, ddof: 1) col(column).var(ddof: ddof) end |
#when(*predicates, **constraints) ⇒ When
Start a "when, then, otherwise" expression.
91 92 93 94 |
# File 'lib/polars/functions/whenthen.rb', line 91 def when(*predicates, **constraints) condition = Utils.parse_predicates_constraints_into_expression(*predicates, **constraints) When.new(Plr.when(condition)) end |
#zeros(n, dtype: nil, eager: true) ⇒ Object
Construct a column of length n
filled with zeros.
This is syntactic sugar for the repeat
function.
114 115 116 117 118 119 120 121 |
# File 'lib/polars/functions/repeat.rb', line 114 def zeros(n, dtype: nil, eager: true) if (zero = _one_or_zero_by_dtype(0, dtype)).nil? msg = "invalid dtype for `zeros`; found #{dtype}" raise TypeError, msg end repeat(zero, n, dtype: dtype, eager: eager).alias("zeros") end |