Expressions#

This page gives an overview of all public polars expressions.

class polars.Expr[source]

Expressions that can be used in various contexts.

Methods:

`abs`	Compute absolute values.
`add`	Method equivalent of operator expression `expr + other`.
`agg_groups`	Get the group indexes of the group by operation.
`alias`	Rename the output of an expression.
`all`	Check if all boolean values in a Boolean column are True.
`and_`	Method equivalent of operator expression `expr & other1 & other2 & ...`.
`any`	Check if any boolean value in a Boolean column is True.
`append`	Append expressions.
`apply`	Apply a custom/user-defined function (UDF) in a GroupBy or Projection context.
`arccos`	Compute the element-wise value for the inverse cosine.
`arccosh`	Compute the element-wise value for the inverse hyperbolic cosine.
`arcsin`	Compute the element-wise value for the inverse sine.
`arcsinh`	Compute the element-wise value for the inverse hyperbolic sine.
`arctan`	Compute the element-wise value for the inverse tangent.
`arctanh`	Compute the element-wise value for the inverse hyperbolic tangent.
`arg_max`	Get the index of the maximal value.
`arg_min`	Get the index of the minimal value.
`arg_sort`	Get the index values that would sort this column.
`arg_true`	Return indices where expression evaluates True.
`arg_unique`	Get index of first unique value.
`argsort`	Get the index values that would sort this column.
`backward_fill`	Fill missing values with the next to be seen values.
`cast`	Cast between data types.
`ceil`	Rounds up to the nearest integer value.
`clip`	Clip (limit) the values in an array to a min and max boundary.
`clip_max`	Clip (limit) the values in an array to a max boundary.
`clip_min`	Clip (limit) the values in an array to a min boundary.
`cos`	Compute the element-wise value for the cosine.
`cosh`	Compute the element-wise value for the hyperbolic cosine.
`count`	Count the number of values in this expression.
`cumcount`	Get an array with the cumulative count computed at every element.
`cummax`	Get an array with the cumulative max computed at every element.
`cummin`	Get an array with the cumulative min computed at every element.
`cumprod`	Get an array with the cumulative product computed at every element.
`cumsum`	Get an array with the cumulative sum computed at every element.
`cumulative_eval`	Run an expression over a sliding window that increases 1 slot every iteration.
`diff`	Calculate the n-th discrete difference.
`dot`	Compute the dot/inner product between two Expressions.
`drop_nans`	Drop floating point NaN values.
`drop_nulls`	Drop all null values.
`entropy`	Computes the entropy.
`eq`	Method equivalent of operator expression `expr == other`.
`ewm_mean`	Exponentially-weighted moving average.
`ewm_std`	Exponentially-weighted moving standard deviation.
`ewm_var`	Exponentially-weighted moving variance.
`exclude`	Exclude columns from a multi-column expression.
`exp`	Compute the exponential, element-wise.
`explode`	Explode a list or utf8 Series.
`extend_constant`	Extremely fast method for extending the Series with 'n' copies of a value.
`fill_nan`	Fill floating point NaN value with a fill value.
`fill_null`	Fill null values using the specified value or strategy.
`filter`	Filter a single column.
`first`	Get the first value.
`flatten`	Flatten a list or string column.
`floor`	Rounds down to the nearest integer value.
`floordiv`	Method equivalent of operator expression `expr // other`.
`forward_fill`	Fill missing values with the latest seen values.
`ge`	Method equivalent of operator expression `expr >= other`.
`gt`	Method equivalent of operator expression `expr > other`.
`hash`	Hash the elements in the selection.
`head`	Get the first n rows.
`inspect`	Print the value that this expression evaluates to and pass on the value.
`interpolate`	Fill nulls with linear interpolation over missing values.
`is_between`	Check if this expression is between the given start and end values.
`is_duplicated`	Get mask of duplicated values.
`is_finite`	Returns a boolean Series indicating which values are finite.
`is_first`	Get a mask of the first unique value.
`is_in`	Check if elements of this expression are present in the other Series.
`is_infinite`	Returns a boolean Series indicating which values are infinite.
`is_nan`	Returns a boolean Series indicating which values are NaN.
`is_not`	Negate a boolean expression.
`is_not_nan`	Returns a boolean Series indicating which values are not NaN.
`is_not_null`	Returns a boolean Series indicating which values are not null.
`is_null`	Returns a boolean Series indicating which values are null.
`is_unique`	Get mask of unique values.
`keep_name`	Keep the original root name of the expression.
`kurtosis`	Compute the kurtosis (Fisher or Pearson) of a dataset.
`last`	Get the last value.
`le`	Method equivalent of operator expression `expr <= other`.
`len`	Count the number of values in this expression.
`limit`	Get the first n rows.
`list`	Aggregate to list.
`log`	Compute the logarithm to a given base.
`log10`	Compute the base 10 logarithm of the input array, element-wise.
`lower_bound`	Calculate the lower bound.
`lt`	Method equivalent of operator expression `expr < other`.
`map`	Apply a custom python function to a Series or sequence of Series.
`map_alias`	Rename the output of an expression by mapping a function over the root name.
`map_dict`	Replace values in column according to remapping dictionary.
`max`	Get maximum value.
`mean`	Get mean value.
`median`	Get median value using linear interpolation.
`min`	Get minimum value.
`mod`	Method equivalent of operator expression `expr % other`.
`mode`	Compute the most occurring value(s).
`mul`	Method equivalent of operator expression `expr * other`.
`n_unique`	Count unique values.
`nan_max`	Get maximum value, but propagate/poison encountered NaN values.
`nan_min`	Get minimum value, but propagate/poison encountered NaN values.
`ne`	Method equivalent of operator expression `expr != other`.
`null_count`	Count null values.
`or_`	Method equivalent of operator expression `expr \| other1 \| other2 \| ...`.
`over`	Compute expressions over the given groups.
`pct_change`	Computes percentage change between values.
`pipe`	Offers a structured way to apply a sequence of user-defined functions (UDFs).
`pow`	Raise expression to the power of exponent.
`prefix`	Add a prefix to the root column name of the expression.
`product`	Compute the product of an expression.
`quantile`	Get quantile value.
`rank`	Assign ranks to data, dealing with ties appropriately.
`rechunk`	Create a single chunk of memory for this Series.
`reinterpret`	Reinterpret the underlying bits as a signed/unsigned integer.
`repeat_by`	Repeat the elements in this Series as specified in the given expression.
`reshape`	Reshape this Expr to a flat Series or a Series of Lists.
`reverse`	Reverse the selection.
`rolling_apply`	Apply a custom rolling window function.
`rolling_max`	Apply a rolling max (moving max) over the values in this array.
`rolling_mean`	Apply a rolling mean (moving mean) over the values in this array.
`rolling_median`	Compute a rolling median.
`rolling_min`	Apply a rolling min (moving min) over the values in this array.
`rolling_quantile`	Compute a rolling quantile.
`rolling_skew`	Compute a rolling skew.
`rolling_std`	Compute a rolling standard deviation.
`rolling_sum`	Apply a rolling sum (moving sum) over the values in this array.
`rolling_var`	Compute a rolling variance.
`round`	Round underlying floating point data by decimals digits.
`sample`	Sample from this expression.
`search_sorted`	Find indices where elements should be inserted to maintain order.
`set_sorted`	Flags the expression as 'sorted'.
`shift`	Shift the values by a given period.
`shift_and_fill`	Shift the values by a given period and fill the resulting null values.
`shrink_dtype`	Shrink numeric columns to the minimal required datatype.
`shuffle`	Shuffle the contents of this expression.
`sign`	Compute the element-wise indication of the sign.
`sin`	Compute the element-wise value for the sine.
`sinh`	Compute the element-wise value for the hyperbolic sine.
`skew`	Compute the sample skewness of a data set.
`slice`	Get a slice of this expression.
`sort`	Sort this column.
`sort_by`	Sort this column by the ordering of other columns.
`sqrt`	Compute the square root of the elements.
`std`	Get standard deviation.
`sub`	Method equivalent of operator expression `expr - other`.
`suffix`	Add a suffix to the root column name of the expression.
`sum`	Get sum value.
`tail`	Get the last n rows.
`take`	Take values by index.
`take_every`	Take every nth value in the Series and return as a new Series.
`tan`	Compute the element-wise value for the tangent.
`tanh`	Compute the element-wise value for the hyperbolic tangent.
`to_physical`	Cast to physical representation of the logical dtype.
`top_k`	Return the k largest elements.
`truediv`	Method equivalent of operator expression `expr / other`.
`unique`	Get unique values of this expression.
`unique_counts`	Return a count of the unique values in the order of appearance.
`upper_bound`	Calculate the upper bound.
`value_counts`	Count all unique values and create a struct mapping value to count.
`var`	Get variance.
`where`	Filter a single column.
`xor`	Method equivalent of operator expression `expr ^ other`.

abs() → Self[source]

Compute absolute values.

Same as abs(expr).

Examples

>>> df = pl.DataFrame(
...     {
...         "A": [-1.0, 0.0, 1.0, 2.0],
...     }
... )
>>> df.select(pl.col("A").abs())
shape: (4, 1)
┌─────┐
│ A   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
│ 0.0 │
│ 1.0 │
│ 2.0 │
└─────┘

add(other: Any) → Self[source]: Method equivalent of operator expression expr + other.

agg_groups() → Self[source]

Get the group indexes of the group by operation.

Should be used in aggregation context only.

Examples

>>> df = pl.DataFrame(
...     {
...         "group": [
...             "one",
...             "one",
...             "one",
...             "two",
...             "two",
...             "two",
...         ],
...         "value": [94, 95, 96, 97, 97, 99],
...     }
... )
>>> df.groupby("group", maintain_order=True).agg(pl.col("value").agg_groups())
shape: (2, 2)
┌───────┬───────────┐
│ group ┆ value     │
│ ---   ┆ ---       │
│ str   ┆ list[u32] │
╞═══════╪═══════════╡
│ one   ┆ [0, 1, 2] │
│ two   ┆ [3, 4, 5] │
└───────┴───────────┘

alias(name: str) → Self[source]

Rename the output of an expression.

Parameters:

name: New name.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": ["a", "b", None],
...     }
... )
>>> df
shape: (3, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ str  │
╞═════╪══════╡
│ 1   ┆ a    │
│ 2   ┆ b    │
│ 3   ┆ null │
└─────┴──────┘
>>> df.select(
...     [
...         pl.col("a").alias("bar"),
...         pl.col("b").alias("foo"),
...     ]
... )
shape: (3, 2)
┌─────┬──────┐
│ bar ┆ foo  │
│ --- ┆ ---  │
│ i64 ┆ str  │
╞═════╪══════╡
│ 1   ┆ a    │
│ 2   ┆ b    │
│ 3   ┆ null │
└─────┴──────┘

all() → Self[source]

Check if all boolean values in a Boolean column are True.

This method is an expression - not to be confused with polars.all() which is a function to select all columns.

Returns:

Boolean literal

Examples

>>> df = pl.DataFrame(
...     {"TT": [True, True], "TF": [True, False], "FF": [False, False]}
... )
>>> df.select(pl.col("*").all())
shape: (1, 3)
┌──────┬───────┬───────┐
│ TT   ┆ TF    ┆ FF    │
│ ---  ┆ ---   ┆ ---   │
│ bool ┆ bool  ┆ bool  │
╞══════╪═══════╪═══════╡
│ true ┆ false ┆ false │
└──────┴───────┴───────┘

and_(*others: Any) → Self[source]: Method equivalent of operator expression expr & other1 & other2 & ....

any() → Self[source]

Check if any boolean value in a Boolean column is True.

Returns:

Boolean literal

Examples

>>> df = pl.DataFrame({"TF": [True, False], "FF": [False, False]})
>>> df.select(pl.all().any())
shape: (1, 2)
┌──────┬───────┐
│ TF   ┆ FF    │
│ ---  ┆ ---   │
│ bool ┆ bool  │
╞══════╪═══════╡
│ true ┆ false │
└──────┴───────┘

append(other: Expr, upcast: bool = True) → Self[source]

Append expressions.

This is done by adding the chunks of other to this Series.

Parameters:

other: Expression to append.
upcast: Cast both Series to the same supertype.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [8, 9, 10],
...         "b": [None, 4, 4],
...     }
... )
>>> df.select(pl.all().head(1).append(pl.all().tail(1)))
shape: (2, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ i64  │
╞═════╪══════╡
│ 8   ┆ null │
│ 10  ┆ 4    │
└─────┴──────┘

apply(function: Callable[[Series], Series] | Callable[[Any], Any], return_dtype: PolarsDataType | None = None, *, skip_nulls: bool = True, pass_name: bool = False, strategy: ApplyStrategy = 'thread_local') → Self[source]

Apply a custom/user-defined function (UDF) in a GroupBy or Projection context.

Depending on the context it has the following behavior:

Selection
Expects f to be of type Callable[[Any], Any]. Applies a python function over each individual value in the column.
GroupBy
Expects f to be of type Callable[[Series], Series]. Applies a python function over each group.

Parameters:

function

Lambda/ function to apply.

return_dtype

Dtype of the output Series. If not set, polars will assume that the dtype remains unchanged.

skip_nulls

Don’t apply the function over values that contain nulls. This is faster.

pass_name

Pass the Series name to the custom function This is more expensive.

strategy{‘thread_local’, ‘threading’}

This functionality is in alpha stage. This may be removed /changed without it being considered a breaking change.

‘thread_local’: run the python function on a single thread.
‘threading’: run the python function on separate threads. Use with
care as this can slow performance. This might only speed up your code if the amount of work per element is significant and the python function releases the GIL (e.g. via calling a c function)

Notes

Using apply is strongly discouraged as you will be effectively running python “for” loops. This will be very slow. Wherever possible you should strongly prefer the native expression API to achieve the best performance.
If your function is expensive and you don’t want it to be called more than once for a given input, consider applying an @lru_cache decorator to it. With suitable data you may achieve order-of-magnitude speedups (or more).

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 1],
...         "b": ["a", "b", "c", "c"],
...     }
... )

In a selection context, the function is applied by row.

>>> df.with_columns(
...     pl.col("a").apply(lambda x: x * 2).alias("a_times_2"),
... )
shape: (4, 3)
┌─────┬─────┬───────────┐
│ a   ┆ b   ┆ a_times_2 │
│ --- ┆ --- ┆ ---       │
│ i64 ┆ str ┆ i64       │
╞═════╪═════╪═══════════╡
│ 1   ┆ a   ┆ 2         │
│ 2   ┆ b   ┆ 4         │
│ 3   ┆ c   ┆ 6         │
│ 1   ┆ c   ┆ 2         │
└─────┴─────┴───────────┘

It is better to implement this with an expression:

>>> df.with_columns(
...     (pl.col("a") * 2).alias("a_times_2"),
... )  

In a GroupBy context the function is applied by group:

>>> df.lazy().groupby("b", maintain_order=True).agg(
...     pl.col("a").apply(lambda x: x.sum())
... ).collect()
shape: (3, 2)
┌─────┬─────┐
│ b   ┆ a   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ a   ┆ 1   │
│ b   ┆ 2   │
│ c   ┆ 4   │
└─────┴─────┘

It is better to implement this with an expression:

>>> df.groupby("b", maintain_order=True).agg(
...     pl.col("a").sum(),
... )  

arccos() → Self[source]

Compute the element-wise value for the inverse cosine.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [0.0]})
>>> df.select(pl.col("a").arccos())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.570796 │
└──────────┘

arccosh() → Self[source]

Compute the element-wise value for the inverse hyperbolic cosine.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").arccosh())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
└─────┘

arcsin() → Self[source]

Compute the element-wise value for the inverse sine.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").arcsin())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.570796 │
└──────────┘

arcsinh() → Self[source]

Compute the element-wise value for the inverse hyperbolic sine.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").arcsinh())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.881374 │
└──────────┘

arctan() → Self[source]

Compute the element-wise value for the inverse tangent.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").arctan())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.785398 │
└──────────┘

arctanh() → Self[source]

Compute the element-wise value for the inverse hyperbolic tangent.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").arctanh())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ inf │
└─────┘

arg_max() → Self[source]

Get the index of the maximal value.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [20, 10, 30],
...     }
... )
>>> df.select(pl.col("a").arg_max())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 2   │
└─────┘

arg_min() → Self[source]

Get the index of the minimal value.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [20, 10, 30],
...     }
... )
>>> df.select(pl.col("a").arg_min())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 1   │
└─────┘

arg_sort(*, descending: bool = False, nulls_last: bool = False) → Self[source]

Get the index values that would sort this column.

Parameters:

descending: Sort in descending (descending) order.
nulls_last: Place null values last instead of first.

Returns:

Expr: Series of dtype UInt32.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [20, 10, 30],
...     }
... )
>>> df.select(pl.col("a").arg_sort())
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 1   │
│ 0   │
│ 2   │
└─────┘

arg_true() → Self[source]

Return indices where expression evaluates True.

Warning

Modifies number of rows returned, so will fail in combination with other expressions. Use as only expression in select / with_columns.

See also

ExprListNameSpace.explode: Explode a list column.

Examples

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5, 6, 7, 8, 9]})
>>> df.select(pl.col("foo").reshape((3, 3)))
shape: (3, 1)
┌───────────┐
│ foo       │
│ ---       │
│ list[i64] │
╞═══════════╡
│ [1, 2, 3] │
│ [4, 5, 6] │
│ [7, 8, 9] │
└───────────┘

reverse() → Self[source]

Reverse the selection.

Examples

>>> df = pl.DataFrame(
...     {
...         "A": [1, 2, 3, 4, 5],
...         "fruits": ["banana", "banana", "apple", "apple", "banana"],
...         "B": [5, 4, 3, 2, 1],
...         "cars": ["beetle", "audi", "beetle", "beetle", "beetle"],
...     }
... )
>>> df.select(
...     [
...         pl.all(),
...         pl.all().reverse().suffix("_reverse"),
...     ]
... )
shape: (5, 8)
┌─────┬────────┬─────┬────────┬───────────┬────────────────┬───────────┬──────────────┐
│ A   ┆ fruits ┆ B   ┆ cars   ┆ A_reverse ┆ fruits_reverse ┆ B_reverse ┆ cars_reverse │
│ --- ┆ ---    ┆ --- ┆ ---    ┆ ---       ┆ ---            ┆ ---       ┆ ---          │
│ i64 ┆ str    ┆ i64 ┆ str    ┆ i64       ┆ str            ┆ i64       ┆ str          │
╞═════╪════════╪═════╪════════╪═══════════╪════════════════╪═══════════╪══════════════╡
│ 1   ┆ banana ┆ 5   ┆ beetle ┆ 5         ┆ banana         ┆ 1         ┆ beetle       │
│ 2   ┆ banana ┆ 4   ┆ audi   ┆ 4         ┆ apple          ┆ 2         ┆ beetle       │
│ 3   ┆ apple  ┆ 3   ┆ beetle ┆ 3         ┆ apple          ┆ 3         ┆ beetle       │
│ 4   ┆ apple  ┆ 2   ┆ beetle ┆ 2         ┆ banana         ┆ 4         ┆ audi         │
│ 5   ┆ banana ┆ 1   ┆ beetle ┆ 1         ┆ banana         ┆ 5         ┆ beetle       │
└─────┴────────┴─────┴────────┴───────────┴────────────────┴───────────┴──────────────┘

rolling_apply(function: Callable[[Series], Any], window_size: int, weights: list[float] | None = None, min_periods: int | None = None, center: bool = False) → Self[source]

Apply a custom rolling window function.

Prefer the specific rolling window functions over this one, as they are faster.

Prefer:

rolling_min

rolling_max

rolling_mean

rolling_sum

Parameters:

function: Aggregation function
window_size: The length of the window.
weights: An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.
min_periods: The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.
center: Set the labels at the center of the window

Examples

>>> df = pl.DataFrame(
...     {
...         "A": [1.0, 2.0, 9.0, 2.0, 13.0],
...     }
... )
>>> df.select(
...     [
...         pl.col("A").rolling_apply(lambda s: s.std(), window_size=3),
...     ]
... )
 shape: (5, 1)
┌──────────┐
│ A        │
│ ---      │
│ f64      │
╞══════════╡
│ null     │
│ null     │
│ 4.358899 │
│ 4.041452 │
│ 5.567764 │
└──────────┘

Apply a rolling max (moving max) over the values in this array.

A window of length window_size will traverse the array. The values that fill this window will (optionally) be multiplied with the weights given by the weight vector. The resulting values will be aggregated to their sum.

Parameters:

window_size

The length of the window. Can be a fixed integer size, or a dynamic temporal size indicated by a timedelta or the following string language:

1ns (1 nanosecond)
1us (1 microsecond)
1ms (1 millisecond)
1s (1 second)
1m (1 minute)
1h (1 hour)
1d (1 day)
1w (1 week)
1mo (1 calendar month)
1y (1 calendar year)
1i (1 index count)

If a timedelta or the dynamic string language is used, the by and closed arguments must also be set.

weights

An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

min_periods

The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.

center

Set the labels at the center of the window

by

If the window_size is temporal, for instance “5h” or “3s, you must set the column that will be used to determine the windows. This column must be of dtype {Date, Datetime}

closed{‘left’, ‘right’, ‘both’, ‘none’}

Define which sides of the temporal interval are closed (inclusive).

Warning

This functionality is experimental and may change without it being considered a breaking change.

Notes

If you want to compute multiple aggregation statistics over the same dynamic window, consider using groupby_rolling this method can cache the window size computation.

Examples

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.select(
...     [
...         pl.col("A").rolling_max(window_size=2),
...     ]
... )
shape: (6, 1)
┌──────┐
│ A    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ 2.0  │
│ 3.0  │
│ 4.0  │
│ 5.0  │
│ 6.0  │
└──────┘

Apply a rolling mean (moving mean) over the values in this array.

Parameters:

window_size

The length of the window. Can be a fixed integer size, or a dynamic temporal size indicated by a timedelta or the following string language:

1ns (1 nanosecond)
1us (1 microsecond)
1ms (1 millisecond)
1s (1 second)
1m (1 minute)
1h (1 hour)
1d (1 day)
1w (1 week)
1mo (1 calendar month)
1y (1 calendar year)
1i (1 index count)

If a timedelta or the dynamic string language is used, the by and closed arguments must also be set.

weights

An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

min_periods

The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.

center

Set the labels at the center of the window

by

If the window_size is temporal for instance “5h” or “3s, you must set the column that will be used to determine the windows. This column must be of dtype {Date, Datetime}

closed{‘left’, ‘right’, ‘both’, ‘none’}

Define which sides of the temporal interval are closed (inclusive).

Warning

This functionality is experimental and may change without it being considered a breaking change.

Notes

If you want to compute multiple aggregation statistics over the same dynamic window, consider using groupby_rolling this method can cache the window size computation.

Examples

>>> df = pl.DataFrame({"A": [1.0, 8.0, 6.0, 2.0, 16.0, 10.0]})
>>> df.select(
...     [
...         pl.col("A").rolling_mean(window_size=2),
...     ]
... )
shape: (6, 1)
┌──────┐
│ A    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ 4.5  │
│ 7.0  │
│ 4.0  │
│ 9.0  │
│ 13.0 │
└──────┘

Compute a rolling median.

Parameters:

window_size

The length of the window. Can be a fixed integer size, or a dynamic temporal size indicated by a timedelta or the following string language:

1ns (1 nanosecond)
1us (1 microsecond)
1ms (1 millisecond)
1s (1 second)
1m (1 minute)
1h (1 hour)
1d (1 day)
1w (1 week)
1mo (1 calendar month)
1y (1 calendar year)
1i (1 index count)

If a timedelta or the dynamic string language is used, the by and closed arguments must also be set.

weights

An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

min_periods

The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.

center

Set the labels at the center of the window

by

If the window_size is temporal for instance “5h” or “3s, you must set the column that will be used to determine the windows. This column must be of dtype {Date, Datetime}

closed{‘left’, ‘right’, ‘both’, ‘none’}

Define which sides of the temporal interval are closed (inclusive).

Warning

This functionality is experimental and may change without it being considered a breaking change.

Notes

If you want to compute multiple aggregation statistics over the same dynamic window, consider using groupby_rolling this method can cache the window size computation.

Examples

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 6.0, 8.0]})
>>> df.select(
...     [
...         pl.col("A").rolling_median(window_size=3),
...     ]
... )
shape: (6, 1)
┌──────┐
│ A    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ null │
│ 2.0  │
│ 3.0  │
│ 4.0  │
│ 6.0  │
└──────┘

Apply a rolling min (moving min) over the values in this array.

Parameters:

window_size

The length of the window. Can be a fixed integer size, or a dynamic temporal size indicated by a timedelta or the following string language:

1ns (1 nanosecond)
1us (1 microsecond)
1ms (1 millisecond)
1s (1 second)
1m (1 minute)
1h (1 hour)
1d (1 day)
1w (1 week)
1mo (1 calendar month)
1y (1 calendar year)
1i (1 index count)

If a timedelta or the dynamic string language is used, the by and closed arguments must also be set.

weights

An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

min_periods

The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.

center

Set the labels at the center of the window

by

If the window_size is temporal for instance “5h” or “3s, you must set the column that will be used to determine the windows. This column must be of dtype {Date, Datetime}

closed{‘left’, ‘right’, ‘both’, ‘none’}

Define which sides of the temporal interval are closed (inclusive).

Warning

This functionality is experimental and may change without it being considered a breaking change.

Notes

If you want to compute multiple aggregation statistics over the same dynamic window, consider using groupby_rolling this method can cache the window size computation.

Examples

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.select(
...     [
...         pl.col("A").rolling_min(window_size=2),
...     ]
... )
shape: (6, 1)
┌──────┐
│ A    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ 1.0  │
│ 2.0  │
│ 3.0  │
│ 4.0  │
│ 5.0  │
└──────┘

rolling_quantile(quantile: float, interpolation: RollingInterpolationMethod = 'nearest', window_size: int | timedelta | str = 2, weights: list[float] | None = None, min_periods: int | None = None, center: bool = False, by: str | None = None, closed: ClosedInterval = 'left') → Self[source]

Compute a rolling quantile.

Parameters:

quantile

Quantile between 0.0 and 1.0.

interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’}

Interpolation method.

window_size

The length of the window. Can be a fixed integer size, or a dynamic temporal size indicated by a timedelta or the following string language:

1ns (1 nanosecond)
1us (1 microsecond)
1ms (1 millisecond)
1s (1 second)
1m (1 minute)
1h (1 hour)
1d (1 day)
1w (1 week)
1mo (1 calendar month)
1y (1 calendar year)
1i (1 index count)

If a timedelta or the dynamic string language is used, the by and closed arguments must also be set.

weights

An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

min_periods

The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.

center

Set the labels at the center of the window

by

If the window_size is temporal for instance “5h” or “3s, you must set the column that will be used to determine the windows. This column must be of dtype {Date, Datetime}

closed{‘left’, ‘right’, ‘both’, ‘none’}

Define which sides of the temporal interval are closed (inclusive).

Warning

This functionality is experimental and may change without it being considered a breaking change.

Notes

If you want to compute multiple aggregation statistics over the same dynamic window, consider using groupby_rolling this method can cache the window size computation.

Examples

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 6.0, 8.0]})
>>> df.select(
...     [
...         pl.col("A").rolling_quantile(quantile=0.33, window_size=3),
...     ]
... )
shape: (6, 1)
┌──────┐
│ A    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ null │
│ 1.0  │
│ 2.0  │
│ 3.0  │
│ 4.0  │
└──────┘

rolling_skew(window_size: int, bias: bool = True) → Self[source]

Compute a rolling skew.

Parameters:

window_size: Integer size of the rolling window.
bias: If False, the calculations are corrected for statistical bias.

Compute a rolling standard deviation.

Parameters:

window_size

The length of the window. Can be a fixed integer size, or a dynamic temporal size indicated by a timedelta or the following string language:

1ns (1 nanosecond)
1us (1 microsecond)
1ms (1 millisecond)
1s (1 second)
1m (1 minute)
1h (1 hour)
1d (1 day)
1w (1 week)
1mo (1 calendar month)
1y (1 calendar year)
1i (1 index count)

If a timedelta or the dynamic string language is used, the by and closed arguments must also be set.

weights

An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

min_periods

The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.

center

Set the labels at the center of the window

by

If the window_size is temporal for instance “5h” or “3s, you must set the column that will be used to determine the windows. This column must be of dtype {Date, Datetime}

closed{‘left’, ‘right’, ‘both’, ‘none’}

Define which sides of the temporal interval are closed (inclusive).

Warning

This functionality is experimental and may change without it being considered a breaking change.

Notes

If you want to compute multiple aggregation statistics over the same dynamic window, consider using groupby_rolling this method can cache the window size computation.

Examples

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 6.0, 8.0]})
>>> df.select(
...     [
...         pl.col("A").rolling_std(window_size=3),
...     ]
... )
shape: (6, 1)
┌──────────┐
│ A        │
│ ---      │
│ f64      │
╞══════════╡
│ null     │
│ null     │
│ 1.0      │
│ 1.0      │
│ 1.527525 │
│ 2.0      │
└──────────┘

Apply a rolling sum (moving sum) over the values in this array.

Parameters:

window_size

The length of the window. Can be a fixed integer size, or a dynamic temporal size indicated by a timedelta or the following string language:

1ns (1 nanosecond)
1us (1 microsecond)
1ms (1 millisecond)
1s (1 second)
1m (1 minute)
1h (1 hour)
1d (1 day)
1w (1 week)
1mo (1 calendar month)
1y (1 calendar year)
1i (1 index count)

If a timedelta or the dynamic string language is used, the by and closed arguments must also be set.

weights

An optional slice with the same length of the window that will be multiplied elementwise with the values in the window.

min_periods

The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.

center

Set the labels at the center of the window

by

If the window_size is temporal for instance “5h” or “3s, you must set the column that will be used to determine the windows. This column must of dtype {Date, Datetime}

closed{‘left’, ‘right’, ‘both’, ‘none’}

Define which sides of the temporal interval are closed (inclusive).

Warning

This functionality is experimental and may change without it being considered a breaking change.

Notes

If you want to compute multiple aggregation statistics over the same dynamic window, consider using groupby_rolling this method can cache the window size computation.

Examples

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.select(
...     [
...         pl.col("A").rolling_sum(window_size=2),
...     ]
... )
shape: (6, 1)
┌──────┐
│ A    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ 3.0  │
│ 5.0  │
│ 7.0  │
│ 9.0  │
│ 11.0 │
└──────┘

Compute a rolling variance.

Parameters:

window_size

The length of the window. Can be a fixed integer size, or a dynamic temporal size indicated by a timedelta or the following string language:

1ns (1 nanosecond)
1us (1 microsecond)
1ms (1 millisecond)
1s (1 second)
1m (1 minute)
1h (1 hour)
1d (1 day)
1w (1 week)
1mo (1 calendar month)
1y (1 calendar year)
1i (1 index count)

If a timedelta or the dynamic string language is used, the by and closed arguments must also be set.

weights

An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

min_periods

The number of values in the window that should be non-null before computing a result. If None, it will be set equal to window size.

center

Set the labels at the center of the window

by

If the window_size is temporal for instance “5h” or “3s, you must set the column that will be used to determine the windows. This column must be of dtype {Date, Datetime}

closed{‘left’, ‘right’, ‘both’, ‘none’}

Define which sides of the temporal interval are closed (inclusive).

Warning

This functionality is experimental and may change without it being considered a breaking change.

Notes

If you want to compute multiple aggregation statistics over the same dynamic window, consider using groupby_rolling this method can cache the window size computation.

Examples

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 6.0, 8.0]})
>>> df.select(
...     [
...         pl.col("A").rolling_var(window_size=3),
...     ]
... )
shape: (6, 1)
┌──────────┐
│ A        │
│ ---      │
│ f64      │
╞══════════╡
│ null     │
│ null     │
│ 1.0      │
│ 1.0      │
│ 2.333333 │
│ 4.0      │
└──────────┘

round(decimals: int) → Self[source]

Round underlying floating point data by decimals digits.

Parameters:

decimals: Number of decimals to round by.

Examples

>>> df = pl.DataFrame({"a": [0.33, 0.52, 1.02, 1.17]})
>>> df.select(pl.col("a").round(1))
shape: (4, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.3 │
│ 0.5 │
│ 1.0 │
│ 1.2 │
└─────┘

sample(n: int | None = None, frac: float | None = None, with_replacement: bool = False, shuffle: bool = False, seed: int | None = None) → Self[source]

Sample from this expression.

Parameters:

n: Number of items to return. Cannot be used with frac. Defaults to 1 if frac is None.
frac: Fraction of items to return. Cannot be used with n.
with_replacement: Allow values to be sampled more than once.
shuffle: Shuffle the order of sampled data points.
seed: Seed for the random number generator. If set to None (default), a random seed is generated using the random module.

Examples

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").sample(frac=1.0, with_replacement=True, seed=1))
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 3   │
│ 1   │
│ 1   │
└─────┘

search_sorted(element: Expr | int | float | Series, side: SearchSortedSide = 'any') → Self[source]

Find indices where elements should be inserted to maintain order.

\[a[i-1] < v <= a[i]\]

Parameters:

element: Expression or scalar value.
side{‘any’, ‘left’, ‘right’}: If ‘any’, the index of the first suitable location found is given. If ‘left’, the index of the leftmost suitable location found is given. If ‘right’, return the rightmost suitable location found is given.

Examples

>>> df = pl.DataFrame(
...     {
...         "values": [1, 2, 3, 5],
...     }
... )
>>> df.select(
...     [
...         pl.col("values").search_sorted(0).alias("zero"),
...         pl.col("values").search_sorted(3).alias("three"),
...         pl.col("values").search_sorted(6).alias("six"),
...     ]
... )
shape: (1, 3)
┌──────┬───────┬─────┐
│ zero ┆ three ┆ six │
│ ---  ┆ ---   ┆ --- │
│ u32  ┆ u32   ┆ u32 │
╞══════╪═══════╪═════╡
│ 0    ┆ 2     ┆ 4   │
└──────┴───────┴─────┘

set_sorted(descending: bool = False) → Self[source]

Flags the expression as ‘sorted’.

Enables downstream code to user fast paths for sorted arrays.

Parameters:

descending: Whether the Series order is descending.

Warning

This can lead to incorrect results if this Series is not sorted!! Use with care!

Examples

>>> df = pl.DataFrame({"values": [1, 2, 3]})
>>> df.select(pl.col("values").set_sorted().max())
shape: (1, 1)
┌────────┐
│ values │
│ ---    │
│ i64    │
╞════════╡
│ 3      │
└────────┘

shift(periods: int = 1) → Self[source]

Shift the values by a given period.

Parameters:

periods: Number of places to shift (may be negative).

Examples

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4]})
>>> df.select(pl.col("foo").shift(1))
shape: (4, 1)
┌──────┐
│ foo  │
│ ---  │
│ i64  │
╞══════╡
│ null │
│ 1    │
│ 2    │
│ 3    │
└──────┘

Shift the values by a given period and fill the resulting null values.

Parameters:

periods: Number of places to shift (may be negative).
fill_value: Fill None values with the result of this expression.

Examples

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4]})
>>> df.select(pl.col("foo").shift_and_fill(1, "a"))
shape: (4, 1)
┌─────┐
│ foo │
│ --- │
│ str │
╞═════╡
│ a   │
│ 1   │
│ 2   │
│ 3   │
└─────┘

shrink_dtype() → Self[source]

Shrink numeric columns to the minimal required datatype.

Shrink to the dtype needed to fit the extrema of this [Series]. This can be used to reduce memory pressure.

Examples

>>> pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": [1, 2, 2 << 32],
...         "c": [-1, 2, 1 << 30],
...         "d": [-112, 2, 112],
...         "e": [-112, 2, 129],
...         "f": ["a", "b", "c"],
...         "g": [0.1, 1.32, 0.12],
...         "h": [True, None, False],
...     }
... ).select(pl.all().shrink_dtype())
shape: (3, 8)
┌─────┬────────────┬────────────┬──────┬──────┬─────┬──────┬───────┐
│ a   ┆ b          ┆ c          ┆ d    ┆ e    ┆ f   ┆ g    ┆ h     │
│ --- ┆ ---        ┆ ---        ┆ ---  ┆ ---  ┆ --- ┆ ---  ┆ ---   │
│ i8  ┆ i64        ┆ i32        ┆ i8   ┆ i16  ┆ str ┆ f32  ┆ bool  │
╞═════╪════════════╪════════════╪══════╪══════╪═════╪══════╪═══════╡
│ 1   ┆ 1          ┆ -1         ┆ -112 ┆ -112 ┆ a   ┆ 0.1  ┆ true  │
│ 2   ┆ 2          ┆ 2          ┆ 2    ┆ 2    ┆ b   ┆ 1.32 ┆ null  │
│ 3   ┆ 8589934592 ┆ 1073741824 ┆ 112  ┆ 129  ┆ c   ┆ 0.12 ┆ false │
└─────┴────────────┴────────────┴──────┴──────┴─────┴──────┴───────┘

shuffle(seed: int | None = None) → Self[source]

Shuffle the contents of this expression.

Parameters:

seed: Seed for the random number generator. If set to None (default), a random seed is generated using the random module.

Examples

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").shuffle(seed=1))
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 1   │
│ 3   │
└─────┘

sign() → Self[source]

Compute the element-wise indication of the sign.

The returned values can be -1, 0, or 1:

-1 if x < 0.
0 if x == 0.
1 if x > 0.

(null values are preserved as-is).

Examples

>>> df = pl.DataFrame({"a": [-9.0, -0.0, 0.0, 4.0, None]})
>>> df.select(pl.col("a").sign())
shape: (5, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ -1   │
│ 0    │
│ 0    │
│ 1    │
│ null │
└──────┘

sin() → Self[source]

Compute the element-wise value for the sine.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [0.0]})
>>> df.select(pl.col("a").sin())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
└─────┘

sinh() → Self[source]

Compute the element-wise value for the hyperbolic sine.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").sinh())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.175201 │
└──────────┘

skew(bias: bool = True) → Self[source]

Compute the sample skewness of a data set.

For normally distributed data, the skewness should be about zero. For unimodal continuous distributions, a skewness value greater than zero means that there is more weight in the right tail of the distribution. The function skewtest can be used to determine if the skewness value is close enough to zero, statistically speaking.

See scipy.stats for more information.

Parameters:

biasbool, optional: If False, the calculations are corrected for statistical bias.

Notes

The sample skewness is computed as the Fisher-Pearson coefficient of skewness, i.e.

\[g_1=\frac{m_3}{m_2^{3/2}}\]

where

\[m_i=\frac{1}{N}\sum_{n=1}^N(x[n]-\bar{x})^i\]

is the biased sample \(i\texttt{th}\) central moment, and \(\bar{x}\) is the sample mean. If bias is False, the calculations are corrected for bias and the value computed is the adjusted Fisher-Pearson standardized moment coefficient, i.e.

\[G_1 = \frac{k_3}{k_2^{3/2}} = \frac{\sqrt{N(N-1)}}{N-2}\frac{m_3}{m_2^{3/2}}\]

Examples

>>> df = pl.DataFrame({"a": [1, 2, 3, 2, 1]})
>>> df.select(pl.col("a").skew())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.343622 │
└──────────┘

slice(offset: int | Expr, length: int | Expr | None = None) → Self[source]

Get a slice of this expression.

Parameters:

offset: Start index. Negative indexing is supported.
length: Length of the slice. If set to None, all rows starting at the offset will be selected.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [8, 9, 10, 11],
...         "b": [None, 4, 4, 4],
...     }
... )
>>> df.select(pl.all().slice(1, 2))
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 9   ┆ 4   │
│ 10  ┆ 4   │
└─────┴─────┘

sort(*, descending: bool = False, nulls_last: bool = False) → Self[source]

Sort this column.

When used in a projection/selection context, the whole column is sorted. When used in a groupby context, the groups are sorted.

Parameters:

descending: Sort in descending order.
nulls_last: Place null values last.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [1, None, 3, 2],
...     }
... )
>>> df.select(pl.col("a").sort())
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ null │
│ 1    │
│ 2    │
│ 3    │
└──────┘
>>> df.select(pl.col("a").sort(descending=True))
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ null │
│ 3    │
│ 2    │
│ 1    │
└──────┘
>>> df.select(pl.col("a").sort(nulls_last=True))
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ 1    │
│ 2    │
│ 3    │
│ null │
└──────┘

When sorting in a groupby context, the groups are sorted.

>>> df = pl.DataFrame(
...     {
...         "group": ["one", "one", "one", "two", "two", "two"],
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.groupby("group").agg(pl.col("value").sort())  
shape: (2, 2)
┌───────┬────────────┐
│ group ┆ value      │
│ ---   ┆ ---        │
│ str   ┆ list[i64]  │
╞═══════╪════════════╡
│ two   ┆ [3, 4, 99] │
│ one   ┆ [1, 2, 98] │
└───────┴────────────┘

sort_by(by: IntoExpr | Iterable[IntoExpr], *more_by: IntoExpr, descending: bool | Sequence[bool] = False) → Self[source]

Sort this column by the ordering of other columns.

When used in a projection/selection context, the whole column is sorted. When used in a groupby context, the groups are sorted.

Parameters:

by: Column(s) to sort by. Accepts expression input. Strings are parsed as column names.
*more_by: Additional columns to sort by, specified as positional arguments.
descending: Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans.

Examples

Pass a single column name to sort by that column.

>>> df = pl.DataFrame(
...     {
...         "group": ["a", "a", "b", "b"],
...         "value1": [1, 3, 4, 2],
...         "value2": [8, 7, 6, 5],
...     }
... )
>>> df.select(pl.col("group").sort_by("value1"))
shape: (4, 1)
┌───────┐
│ group │
│ ---   │
│ str   │
╞═══════╡
│ a     │
│ b     │
│ a     │
│ b     │
└───────┘

Sorting by expressions is also supported.

>>> df.select(pl.col("group").sort_by(pl.col("value1") + pl.col("value2")))
shape: (4, 1)
┌───────┐
│ group │
│ ---   │
│ str   │
╞═══════╡
│ b     │
│ a     │
│ a     │
│ b     │
└───────┘

Sort by multiple columns by passing a list of columns.

>>> df.select(pl.col("group").sort_by(["value1", "value2"], descending=True))
shape: (4, 1)
┌───────┐
│ group │
│ ---   │
│ str   │
╞═══════╡
│ b     │
│ a     │
│ b     │
│ a     │
└───────┘

Or use positional arguments to sort by multiple columns in the same way.

>>> df.select(pl.col("group").sort_by("value1", "value2"))
shape: (4, 1)
┌───────┐
│ group │
│ ---   │
│ str   │
╞═══════╡
│ a     │
│ b     │
│ a     │
│ b     │
└───────┘

When sorting in a groupby context, the groups are sorted.

>>> df.groupby("group").agg(
...     pl.col("value1").sort_by("value2")
... )  
shape: (2, 2)
┌───────┬───────────┐
│ group ┆ value1    │
│ ---   ┆ ---       │
│ str   ┆ list[i64] │
╞═══════╪═══════════╡
│ a     ┆ [3, 1]    │
│ b     ┆ [2, 4]    │
└───────┴───────────┘

Take a single row from each group where a column attains its minimal value within that group.

>>> df.groupby("group").agg(
...     pl.all().sort_by("value2").first()
... )  
shape: (2, 3)
┌───────┬────────┬────────┐
│ group ┆ value1 ┆ value2 |
│ ---   ┆ ---    ┆ ---    │
│ str   ┆ i64    ┆ i64    |
╞═══════╪════════╪════════╡
│ a     ┆ 3      ┆ 7      |
│ b     ┆ 2      ┆ 5      |
└───────┴────────┴────────┘

sqrt() → Self[source]

Compute the square root of the elements.

Examples

>>> df = pl.DataFrame({"values": [1.0, 2.0, 4.0]})
>>> df.select(pl.col("values").sqrt())
shape: (3, 1)
┌──────────┐
│ values   │
│ ---      │
│ f64      │
╞══════════╡
│ 1.0      │
│ 1.414214 │
│ 2.0      │
└──────────┘

std(ddof: int = 1) → Self[source]

Get standard deviation.

Parameters:

ddof: Degrees of freedom.

Examples

>>> df = pl.DataFrame({"a": [-1, 0, 1]})
>>> df.select(pl.col("a").std())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
└─────┘

sub(other: Any) → Self[source]: Method equivalent of operator expression expr - other.

suffix(suffix: str) → Self[source]

Add a suffix to the root column name of the expression.

Examples

>>> df = pl.DataFrame(
...     {
...         "A": [1, 2, 3, 4, 5],
...         "fruits": ["banana", "banana", "apple", "apple", "banana"],
...         "B": [5, 4, 3, 2, 1],
...         "cars": ["beetle", "audi", "beetle", "beetle", "beetle"],
...     }
... )
>>> df
shape: (5, 4)
┌─────┬────────┬─────┬────────┐
│ A   ┆ fruits ┆ B   ┆ cars   │
│ --- ┆ ---    ┆ --- ┆ ---    │
│ i64 ┆ str    ┆ i64 ┆ str    │
╞═════╪════════╪═════╪════════╡
│ 1   ┆ banana ┆ 5   ┆ beetle │
│ 2   ┆ banana ┆ 4   ┆ audi   │
│ 3   ┆ apple  ┆ 3   ┆ beetle │
│ 4   ┆ apple  ┆ 2   ┆ beetle │
│ 5   ┆ banana ┆ 1   ┆ beetle │
└─────┴────────┴─────┴────────┘
>>> df.select(
...     [
...         pl.all(),
...         pl.all().reverse().suffix("_reverse"),
...     ]
... )
shape: (5, 8)
┌─────┬────────┬─────┬────────┬───────────┬────────────────┬───────────┬──────────────┐
│ A   ┆ fruits ┆ B   ┆ cars   ┆ A_reverse ┆ fruits_reverse ┆ B_reverse ┆ cars_reverse │
│ --- ┆ ---    ┆ --- ┆ ---    ┆ ---       ┆ ---            ┆ ---       ┆ ---          │
│ i64 ┆ str    ┆ i64 ┆ str    ┆ i64       ┆ str            ┆ i64       ┆ str          │
╞═════╪════════╪═════╪════════╪═══════════╪════════════════╪═══════════╪══════════════╡
│ 1   ┆ banana ┆ 5   ┆ beetle ┆ 5         ┆ banana         ┆ 1         ┆ beetle       │
│ 2   ┆ banana ┆ 4   ┆ audi   ┆ 4         ┆ apple          ┆ 2         ┆ beetle       │
│ 3   ┆ apple  ┆ 3   ┆ beetle ┆ 3         ┆ apple          ┆ 3         ┆ beetle       │
│ 4   ┆ apple  ┆ 2   ┆ beetle ┆ 2         ┆ banana         ┆ 4         ┆ audi         │
│ 5   ┆ banana ┆ 1   ┆ beetle ┆ 1         ┆ banana         ┆ 5         ┆ beetle       │
└─────┴────────┴─────┴────────┴───────────┴────────────────┴───────────┴──────────────┘

sum() → Self[source]

Get sum value.

Notes

Dtypes in {Int8, UInt8, Int16, UInt16} are cast to Int64 before summing to prevent overflow issues.

Examples

>>> df = pl.DataFrame({"a": [-1, 0, 1]})
>>> df.select(pl.col("a").sum())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│  0  │
└─────┘

tail(n: int = 10) → Self[source]

Get the last n rows.

Parameters:

n: Number of rows to return.

Examples

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5, 6, 7]})
>>> df.tail(3)
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 5   │
│ 6   │
│ 7   │
└─────┘

take(indices: int | list[int] | Expr | Series | np.ndarray[Any, Any]) → Self[source]

Take values by index.

Parameters:

indices: An expression that leads to a UInt32 dtyped Series.

Returns:

Values taken by index

Examples

>>> df = pl.DataFrame(
...     {
...         "group": [
...             "one",
...             "one",
...             "one",
...             "two",
...             "two",
...             "two",
...         ],
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.groupby("group", maintain_order=True).agg(pl.col("value").take(1))
shape: (2, 2)
┌───────┬───────┐
│ group ┆ value │
│ ---   ┆ ---   │
│ str   ┆ i64   │
╞═══════╪═══════╡
│ one   ┆ 98    │
│ two   ┆ 99    │
└───────┴───────┘

take_every(n: int) → Self[source]

Take every nth value in the Series and return as a new Series.

Examples

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5, 6, 7, 8, 9]})
>>> df.select(pl.col("foo").take_every(3))
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 4   │
│ 7   │
└─────┘

tan() → Self[source]

Compute the element-wise value for the tangent.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").tan().round(2))
shape: (1, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 1.56 │
└──────┘

tanh() → Self[source]

Compute the element-wise value for the hyperbolic tangent.

Returns:

Series of dtype Float64

Examples

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").tanh())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.761594 │
└──────────┘

to_physical() → Self[source]

Cast to physical representation of the logical dtype.

polars.datatypes.Date() -> polars.datatypes.Int32()
polars.datatypes.Datetime() -> polars.datatypes.Int64()
polars.datatypes.Time() -> polars.datatypes.Int64()
polars.datatypes.Duration() -> polars.datatypes.Int64()
polars.datatypes.Categorical() -> polars.datatypes.UInt32()
Other data types will be left unchanged.

Examples

Replicating the pandas pd.factorize function.

>>> pl.DataFrame({"vals": ["a", "x", None, "a"]}).with_columns(
...     [
...         pl.col("vals").cast(pl.Categorical),
...         pl.col("vals")
...         .cast(pl.Categorical)
...         .to_physical()
...         .alias("vals_physical"),
...     ]
... )
shape: (4, 2)
┌──────┬───────────────┐
│ vals ┆ vals_physical │
│ ---  ┆ ---           │
│ cat  ┆ u32           │
╞══════╪═══════════════╡
│ a    ┆ 0             │
│ x    ┆ 1             │
│ null ┆ null          │
│ a    ┆ 0             │
└──────┴───────────────┘

top_k(k: int = 5, descending: bool = False) → Self[source]

Return the k largest elements.

If ‘descending=True` the smallest elements will be given.

This has time complexity:

\[\begin{split}O(n + k \\log{}n - \frac{k}{2})\end{split}\]

Parameters:

k: Number of elements to return.
descending: Return the smallest elements.

Examples

>>> df = pl.DataFrame(
...     {
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.select(
...     [
...         pl.col("value").top_k().alias("top_k"),
...         pl.col("value").top_k(descending=True).alias("bottom_k"),
...     ]
... )
shape: (5, 2)
┌───────┬──────────┐
│ top_k ┆ bottom_k │
│ ---   ┆ ---      │
│ i64   ┆ i64      │
╞═══════╪══════════╡
│ 99    ┆ 1        │
│ 98    ┆ 2        │
│ 4     ┆ 3        │
│ 3     ┆ 4        │
│ 2     ┆ 98       │
└───────┴──────────┘

truediv(other: Any) → Self[source]: Method equivalent of operator expression expr / other.

unique(maintain_order: bool = False) → Self[source]

Get unique values of this expression.

Parameters:

maintain_order: Maintain order of data. This requires more work.

Examples

>>> df = pl.DataFrame({"a": [1, 1, 2]})
>>> df.select(pl.col("a").unique())  
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 1   │
└─────┘
>>> df.select(pl.col("a").unique(maintain_order=True))
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
└─────┘

unique_counts() → Self[source]

Return a count of the unique values in the order of appearance.

This method differs from value_counts in that it does not return the values, only the counts and might be faster

Examples

>>> df = pl.DataFrame(
...     {
...         "id": ["a", "b", "b", "c", "c", "c"],
...     }
... )
>>> df.select(
...     [
...         pl.col("id").unique_counts(),
...     ]
... )
shape: (3, 1)
┌─────┐
│ id  │
│ --- │
│ u32 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

upper_bound() → Self[source]

Calculate the upper bound.

Returns a unit Series with the highest value possible for the dtype of this expression.

Examples

>>> df = pl.DataFrame({"a": [1, 2, 3, 2, 1]})
>>> df.select(pl.col("a").upper_bound())
shape: (1, 1)
┌─────────────────────┐
│ a                   │
│ ---                 │
│ i64                 │
╞═════════════════════╡
│ 9223372036854775807 │
└─────────────────────┘

value_counts(multithreaded: bool = False, sort: bool = False) → Self[source]

Count all unique values and create a struct mapping value to count.

Parameters:

multithreaded:: Better to turn this off in the aggregation context, as it can lead to contention.
sort:: Ensure the output is sorted from most values to least.

Returns:

Dtype Struct

Examples

>>> df = pl.DataFrame(
...     {
...         "id": ["a", "b", "b", "c", "c", "c"],
...     }
... )
>>> df.select(
...     [
...         pl.col("id").value_counts(sort=True),
...     ]
... )
shape: (3, 1)
┌───────────┐
│ id        │
│ ---       │
│ struct[2] │
╞═══════════╡
│ {"c",3}   │
│ {"b",2}   │
│ {"a",1}   │
└───────────┘

var(ddof: int = 1) → Self[source]

Get variance.

Parameters:

ddof: Degrees of freedom.

Examples

>>> df = pl.DataFrame({"a": [-1, 0, 1]})
>>> df.select(pl.col("a").var())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
└─────┘

where(predicate: Expr) → Self[source]

Filter a single column.

Alias for filter().

Parameters:

predicate: Boolean expression.

Examples

>>> df = pl.DataFrame(
...     {
...         "group_col": ["g1", "g1", "g2"],
...         "b": [1, 2, 3],
...     }
... )
>>> df.groupby("group_col").agg(
...     [
...         pl.col("b").where(pl.col("b") < 2).sum().alias("lt"),
...         pl.col("b").where(pl.col("b") >= 2).sum().alias("gte"),
...     ]
... ).sort("group_col")
shape: (2, 3)
┌───────────┬──────┬─────┐
│ group_col ┆ lt   ┆ gte │
│ ---       ┆ ---  ┆ --- │
│ str       ┆ i64  ┆ i64 │
╞═══════════╪══════╪═════╡
│ g1        ┆ 1    ┆ 2   │
│ g2        ┆ null ┆ 3   │
└───────────┴──────┴─────┘

xor(other: Any) → Self[source]: Method equivalent of operator expression expr ^ other.