表达式#

本页面提供了所有公共Polars表达式的概述。

class polars.Expr[source]

可以在各种上下文中使用的表达式。

方法:

`abs`	计算绝对值。
`add`	方法等效于加法运算符 `expr + other`。
`agg_groups`	获取分组操作的分组索引。
`alias`	重命名表达式。
`all`	返回列中的所有值是否都为`True`。
`and_`	方法等效于按位“与”运算符 `expr & other & ...`。
`any`	返回列中的任何值是否为`True`。
`append`	追加表达式。
`approx_n_unique`	唯一值的近似计数。
`arccos`	计算元素级的反余弦值。
`arccosh`	计算元素级的反双曲余弦值。
`arcsin`	计算元素级的反正弦值。
`arcsinh`	计算元素级的反双曲正弦值。
`arctan`	计算元素级的反正切值。
`arctanh`	计算元素级的反双曲正切值。
`arg_max`	获取最大值的索引。
`arg_min`	获取最小值的索引。
`arg_sort`	获取将对此列进行排序的索引值。
`arg_true`	返回表达式评估为`True`的索引。
`arg_unique`	获取第一个唯一值的索引。
`backward_fill`	用下一个非空值填充缺失值。
`bitwise_and`	执行按位与的聚合操作。
`bitwise_count_ones`	评估设置的位数。
`bitwise_count_zeros`	评估未设置的位数。
`bitwise_leading_ones`	评估在遇到未设置的位之前的最重要的设置位数。
`bitwise_leading_zeros`	评估在遇到设置位之前最高有效未设置位的数量。
`bitwise_or`	执行按位或的聚合操作。
`bitwise_trailing_ones`	评估在遇到未设置的位之前的最不重要的设置位数。
`bitwise_trailing_zeros`	评估在遇到设置位之前的最不重要的未设置位的数量。
`bitwise_xor`	执行按位异或的聚合操作。
`bottom_k`	返回`k`个最小的元素。
`bottom_k_by`	返回与`by`列中`k`个最小元素对应的元素。
`cast`	在数据类型之间进行转换。
`cbrt`	计算元素的立方根。
`ceil`	向上取整到最接近的整数值。
`clip`	将给定边界之外的值设置为边界值。
`cos`	计算元素级别的余弦值。
`cosh`	计算双曲余弦的逐元素值。
`cot`	计算元素级的余切值。
`count`	返回列中非空元素的数量。
`cum_count`	返回列中非空值的累计计数。
`cum_max`	获取一个数组，其中包含在每个元素处计算的累积最大值。
`cum_min`	获取一个数组，其中包含在每个元素处计算的累积最小值。
`cum_prod`	获取一个数组，其中包含在每个元素处计算的累积乘积。
`cum_sum`	获取一个数组，其中每个元素都计算了累积和。
`cumulative_eval`	在每次迭代增加`1`个槽的滑动窗口上运行表达式。
`cut`	将连续值分箱为离散类别。
`degrees`	将弧度转换为角度。
`deserialize`	从文件中读取序列化表达式。
`diff`	计算偏移项之间的第一个离散差异。
`dot`	计算两个表达式之间的点积/内积。
`drop_nans`	删除所有浮点数的NaN值。
`drop_nulls`	删除所有空值。
`entropy`	计算熵。
`eq`	等同于相等运算符 `expr == other` 的方法。
`eq_missing`	等同于相等运算符 `expr == other` 的方法，其中 `None == None`。
`ewm_mean`	计算指数加权移动平均。
`ewm_mean_by`	计算基于时间的指数加权移动平均。
`ewm_std`	计算指数加权移动标准差。
`ewm_var`	计算指数加权移动方差。
`exclude`	从多列表达式中排除列。
`exp`	计算指数，逐元素。
`explode`	展开一个列表表达式。
`extend_constant`	用于使用值的'n'个副本扩展Series的极快方法。
`fill_nan`	用填充值填充浮点数的NaN值。
`fill_null`	使用指定的值或策略填充空值。
`filter`	根据一个或多个谓词表达式过滤表达式。
`first`	获取第一个值。
`flatten`	展平一个列表或字符串列。
`floor`	向下舍入到最接近的整数值。
`floordiv`	整数除法运算符的方法等价于 `expr // other`。
`forward_fill`	用最后一个非空值填充缺失值。
`from_json`	从JSON编码的字符串中读取表达式以构建一个表达式。
`gather`	按索引取值。
`gather_every`	取Series中的每第n个值并返回一个新的Series。
`ge`	方法等同于“大于或等于”运算符 `expr >= other`。
`get`	通过索引返回单个值。
`gt`	方法等同于“大于”运算符 `expr > other`。
`has_nulls`	检查表达式是否包含一个或多个空值。
`hash`	对选择中的元素进行哈希处理。
`head`	获取前`n`行。
`hist`	将值分入桶中并计算它们的出现次数。
`implode`	将值聚合到一个列表中。
`inspect`	打印此表达式求值的结果并传递该值。
`interpolate`	使用插值填充空值。
`interpolate_by`	使用基于另一列的插值来填充空值。
`is_between`	检查此表达式是否在给定的下限和上限之间。
`is_duplicated`	返回一个布尔掩码，指示重复的值。
`is_finite`	返回一个布尔系列，指示哪些值是有限的。
`is_first_distinct`	返回一个布尔掩码，指示每个不同值的首次出现。
`is_in`	检查此表达式的元素是否存在于另一个Series中。
`is_infinite`	返回一个布尔系列，指示哪些值是无限的。
`is_last_distinct`	返回一个布尔掩码，指示每个不同值的最后一次出现。
`is_nan`	返回一个布尔系列，指示哪些值是NaN。
`is_not_nan`	返回一个布尔系列，指示哪些值不是NaN。
`is_not_null`	返回一个布尔系列，指示哪些值不为空。
`is_null`	返回一个布尔系列，指示哪些值为空。
`is_unique`	获取唯一值的掩码。
`kurtosis`	计算数据集的峰度（Fisher 或 Pearson）。
`last`	获取最后一个值。
`le`	方法等同于“小于或等于”运算符 `expr <= other`。
`len`	返回列中元素的数量。
`limit`	获取前 `n` 行（`Expr.head()` 的别名）。
`log`	计算给定底数的对数。
`log10`	计算输入数组的以10为底的对数，逐元素进行。
`log1p`	计算每个元素加一后的自然对数。
`lower_bound`	计算下限。
`lt`	方法等同于“小于”运算符 `expr < other`。
`map_batches`	对整个Series或Series序列应用自定义的python函数。
`map_elements`	将自定义/用户定义的函数（UDF）映射到列的每个元素。
`max`	获取最大值。
`mean`	获取平均值。
`median`	使用线性插值获取中位数值。
`min`	获取最小值。
`mod`	方法等同于模运算符 `expr % other`。
`mode`	计算出现频率最高的值。
`mul`	方法等同于乘法运算符 `expr * other`。
`n_unique`	计算唯一值。
`nan_max`	获取最大值，但传播/污染遇到的NaN值。
`nan_min`	获取最小值，但传播/污染遇到的NaN值。
`ne`	方法等同于不等式运算符 `expr != other`。
`ne_missing`	等价于等式运算符 `expr != other` 的方法，其中 `None == None`。
`neg`	一元减号运算符的方法等效于 `-expr`。
`not_`	否定一个布尔表达式。
`null_count`	计算空值。
`or_`	方法等效于按位“或”运算符 `expr \| other \| ...`。
`over`	计算给定组上的表达式。
`pct_change`	计算值之间的百分比变化。
`peak_max`	获取局部最大峰的布尔掩码。
`peak_min`	获取局部最小峰的布尔掩码。
`pipe`	提供了一种结构化的方式来应用一系列用户定义的函数（UDFs）。
`pow`	方法等同于指数运算符 `expr ** exponent`。
`product`	计算表达式的乘积。
`qcut`	将连续值根据其分位数分箱到离散类别中。
`quantile`	获取分位数值。
`radians`	将角度转换为弧度。
`rank`	为数据分配排名，适当处理并列情况。
`rechunk`	为这个系列创建一个单一的内存块。
`register_plugin`	注册一个插件函数。
`reinterpret`	将底层位重新解释为有符号/无符号整数。
`repeat_by`	按照给定表达式中的指定重复此系列中的元素。
`replace`	用相同数据类型的其他值替换给定的值。
`replace_strict`	用不同的值替换所有值。
`reshape`	将此表达式重塑为扁平列或数组列。
`reverse`	反转选择。
`rle`	使用游程编码压缩列数据。
`rle_id`	为每次运行的相同值获取一个唯一的整数ID。
`rolling`	基于时间或整数列创建滚动组。
`rolling_map`	计算自定义滚动窗口函数。
`rolling_max`	对此数组中的值应用滚动最大值（移动最大值）。
`rolling_max_by`	基于另一列应用滚动最大值。
`rolling_mean`	对此数组中的值应用滚动平均值（移动平均值）。
`rolling_mean_by`	基于另一列应用滚动平均值。
`rolling_median`	计算滚动中位数。
`rolling_median_by`	基于另一列计算滚动中位数。
`rolling_min`	对此数组中的值应用滚动最小值（移动最小值）。
`rolling_min_by`	基于另一列应用滚动最小值。
`rolling_quantile`	计算滚动分位数。
`rolling_quantile_by`	基于另一列计算滚动分位数。
`rolling_skew`	计算滚动偏度。
`rolling_std`	计算滚动标准差。
`rolling_std_by`	基于另一列计算滚动标准差。
`rolling_sum`	对此数组中的值应用滚动求和（移动求和）。
`rolling_sum_by`	基于另一列应用滚动求和。
`rolling_var`	计算滚动方差。
`rolling_var_by`	基于另一列计算滚动方差。
`round`	将底层浮点数据四舍五入到 `decimals` 位小数。
`round_sig_figs`	四舍五入到指定的有效数字位数。
`sample`	从这个表达式中取样。
`search_sorted`	找到应插入元素以保持顺序的索引。
`set_sorted`	将表达式标记为“已排序”。
`shift`	将值按给定的索引数进行移动。
`shrink_dtype`	将数值列缩小到所需的最小数据类型。
`shuffle`	打乱此表达式的内容。
`sign`	计算数值类型的逐元素符号函数。
`sin`	计算元素的正弦值。
`sinh`	计算双曲正弦的逐元素值。
`skew`	计算数据集的样本偏度。
`slice`	获取此表达式的一个切片。
`sort`	对此列进行排序。
`sort_by`	按其他列的排序对此列进行排序。
`sqrt`	计算元素的平方根。
`std`	获取标准差。
`sub`	方法等同于减法运算符 `expr - other`。
`sum`	获取总和值。
`tail`	获取最后 `n` 行。
`tan`	计算元素的正切值。
`tanh`	计算双曲正切的逐元素值。
`to_physical`	将逻辑数据类型转换为物理表示。
`top_k`	返回`k`个最大的元素。
`top_k_by`	返回与`by`列中`k`个最大元素对应的元素。
`truediv`	方法等同于浮点除法运算符 `expr / other`。
`unique`	获取此表达式的唯一值。
`unique_counts`	返回按出现顺序排列的唯一值的计数。
`upper_bound`	计算上限。
`value_counts`	计算唯一值的出现次数。
`var`	获取方差。
`where`	过滤单个列。
`xor`	方法等效于按位异或运算符 `expr ^ other`。

abs() → Expr[source]

计算绝对值。

与 abs(expr) 相同。

示例

>>> 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) → Expr[source]

方法等效于加法运算符 expr + other。

Parameters:

other: 数值或字符串值；接受表达式输入。

示例

>>> df = pl.DataFrame({"x": [1, 2, 3, 4, 5]})
>>> df.with_columns(
...     pl.col("x").add(2).alias("x+int"),
...     pl.col("x").add(pl.col("x").cum_prod()).alias("x+expr"),
... )
shape: (5, 3)
┌─────┬───────┬────────┐
│ x   ┆ x+int ┆ x+expr │
│ --- ┆ ---   ┆ ---    │
│ i64 ┆ i64   ┆ i64    │
╞═════╪═══════╪════════╡
│ 1   ┆ 3     ┆ 2      │
│ 2   ┆ 4     ┆ 4      │
│ 3   ┆ 5     ┆ 9      │
│ 4   ┆ 6     ┆ 28     │
│ 5   ┆ 7     ┆ 125    │
└─────┴───────┴────────┘

>>> df = pl.DataFrame(
...     {"x": ["a", "d", "g"], "y": ["b", "e", "h"], "z": ["c", "f", "i"]}
... )
>>> df.with_columns(pl.col("x").add(pl.col("y")).add(pl.col("z")).alias("xyz"))
shape: (3, 4)
┌─────┬─────┬─────┬─────┐
│ x   ┆ y   ┆ z   ┆ xyz │
│ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ str ┆ str │
╞═════╪═════╪═════╪═════╡
│ a   ┆ b   ┆ c   ┆ abc │
│ d   ┆ e   ┆ f   ┆ def │
│ g   ┆ h   ┆ i   ┆ ghi │
└─────┴─────┴─────┴─────┘

agg_groups() → Expr[source]

获取分组操作的分组索引。

仅应在聚合上下文中使用。

示例

>>> df = pl.DataFrame(
...     {
...         "group": [
...             "one",
...             "one",
...             "one",
...             "two",
...             "two",
...             "two",
...         ],
...         "value": [94, 95, 96, 97, 97, 99],
...     }
... )
>>> df.group_by("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) → Expr[source]

重命名表达式。

Parameters:

name: 新名称。

另请参阅

name.map
name.prefix
name.suffix

示例

重命名表达式以避免覆盖现有列。

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": ["x", "y", "z"],
...     }
... )
>>> df.with_columns(
...     pl.col("a") + 10,
...     pl.col("b").str.to_uppercase().alias("c"),
... )
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 11  ┆ x   ┆ X   │
│ 12  ┆ y   ┆ Y   │
│ 13  ┆ z   ┆ Z   │
└─────┴─────┴─────┘

覆盖字面量列的默认名称，以防止由于列名重复导致的错误。

>>> df.with_columns(
...     pl.lit(True).alias("c"),
...     pl.lit(4.0).alias("d"),
... )
shape: (3, 4)
┌─────┬─────┬──────┬─────┐
│ a   ┆ b   ┆ c    ┆ d   │
│ --- ┆ --- ┆ ---  ┆ --- │
│ i64 ┆ str ┆ bool ┆ f64 │
╞═════╪═════╪══════╪═════╡
│ 1   ┆ x   ┆ true ┆ 4.0 │
│ 2   ┆ y   ┆ true ┆ 4.0 │
│ 3   ┆ z   ┆ true ┆ 4.0 │
└─────┴─────┴──────┴─────┘

all(*, ignore_nulls: bool = True) → Expr[source]

返回列中的所有值是否都为True。

仅适用于数据类型为 Boolean 的列。

注意

此方法不应与函数 polars.all() 混淆，该函数可用于选择所有列。

Parameters:

ignore_nulls

忽略空值（默认）。

如果设置为False，则使用Kleene逻辑来处理空值：如果列包含任何空值且没有False值，则输出为空。

Returns:

Expr: 数据类型 Boolean 的表达式。

示例

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

通过设置ignore_nulls=False来启用Kleene逻辑。

>>> df.select(pl.col("*").all(ignore_nulls=False))
shape: (1, 3)
┌──────┬───────┬──────┐
│ a    ┆ b     ┆ c    │
│ ---  ┆ ---   ┆ ---  │
│ bool ┆ bool  ┆ bool │
╞══════╪═══════╪══════╡
│ true ┆ false ┆ null │
└──────┴───────┴──────┘

and_(*others: Any) → Expr[source]

方法等效于按位“与”运算符 expr & other & ...。

Parameters:

*others: 要评估/组合的一个或多个整数或布尔表达式。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [5, 6, 7, 4, 8],
...         "y": [1.5, 2.5, 1.0, 4.0, -5.75],
...         "z": [-9, 2, -1, 4, 8],
...     }
... )
>>> df.select(
...     (pl.col("x") >= pl.col("z"))
...     .and_(
...         pl.col("y") >= pl.col("z"),
...         pl.col("y") == pl.col("y"),
...         pl.col("z") <= pl.col("x"),
...         pl.col("y") != pl.col("x"),
...     )
...     .alias("all")
... )
shape: (5, 1)
┌───────┐
│ all   │
│ ---   │
│ bool  │
╞═══════╡
│ true  │
│ true  │
│ true  │
│ false │
│ false │
└───────┘

any(*, ignore_nulls: bool = True) → Expr[source]

返回列中的任何值是否为True。

仅适用于数据类型为 Boolean 的列。

Parameters:

ignore_nulls

忽略空值（默认）。

如果设置为False，则使用Kleene逻辑来处理空值：如果列包含任何空值且没有True值，则输出为空。

Returns:

Expr: 数据类型 Boolean 的表达式。

示例

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

通过设置ignore_nulls=False来启用Kleene逻辑。

>>> df.select(pl.col("*").any(ignore_nulls=False))
shape: (1, 3)
┌──────┬───────┬──────┐
│ a    ┆ b     ┆ c    │
│ ---  ┆ ---   ┆ ---  │
│ bool ┆ bool  ┆ bool │
╞══════╪═══════╪══════╡
│ true ┆ false ┆ null │
└──────┴───────┴──────┘

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

追加表达式。

这是通过将other的块添加到这个Series中来完成的。

Parameters:

other: 要附加的表达式。
upcast: 将两个Series转换为相同的超类型。

示例

>>> 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    │
└─────┴──────┘

approx_n_unique() → Expr[source]

唯一值的近似计数。

这是使用HyperLogLog++算法进行基数估计的。

示例

>>> df = pl.DataFrame({"n": [1, 1, 2]})
>>> df.select(pl.col("n").approx_n_unique())
shape: (1, 1)
┌─────┐
│ n   │
│ --- │
│ u32 │
╞═════╡
│ 2   │
└─────┘
>>> df = pl.DataFrame({"n": range(1000)})
>>> df.select(
...     exact=pl.col("n").n_unique(),
...     approx=pl.col("n").approx_n_unique(),
... )  
shape: (1, 2)
┌───────┬────────┐
│ exact ┆ approx │
│ ---   ┆ ---    │
│ u32   ┆ u32    │
╞═══════╪════════╡
│ 1000  ┆ 1005   │
└───────┴────────┘

arccos() → Expr[source]

计算元素级的反余弦值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

arccosh() → Expr[source]

计算元素级的反双曲余弦值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

arcsin() → Expr[source]

计算元素级的反正弦值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

arcsinh() → Expr[source]

计算元素级的反双曲正弦值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

arctan() → Expr[source]

计算元素级的反正切值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

arctanh() → Expr[source]

计算元素级的反双曲正切值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

arg_max() → Expr[source]

获取最大值的索引。

示例

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

arg_min() → Expr[source]

获取最小值的索引。

示例

>>> 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, ) → Expr[source]

获取将对此列进行排序的索引值。

Parameters:

descending: 按降序（descending）排序。
nulls_last: 将空值放在最后而不是最前面。

Returns:

Expr: 数据类型 UInt32 的表达式。

另请参阅

Expr.gather: 按索引取值。
Expr.rank: 获取每行的排名。

示例

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

使用 gather 将参数排序应用于其他列。

>>> df.select(pl.col("b").gather(pl.col("a").arg_sort()))
shape: (3, 1)
┌─────┐
│ b   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 1   │
│ 3   │
└─────┘

arg_true() → Expr[source]

返回表达式评估为True的索引。

警告

修改返回的行数，因此与其他表达式结合使用时会失败。仅在select / with_columns中作为唯一表达式使用。

另请参阅

Series.arg_true: 返回Series为True的索引
polars.arg_where

示例

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

arg_unique() → Expr[source]

获取第一个唯一值的索引。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [8, 9, 10],
...         "b": [None, 4, 4],
...     }
... )
>>> df.select(pl.col("a").arg_unique())
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 0   │
│ 1   │
│ 2   │
└─────┘
>>> df.select(pl.col("b").arg_unique())
shape: (2, 1)
┌─────┐
│ b   │
│ --- │
│ u32 │
╞═════╡
│ 0   │
│ 1   │
└─────┘

backward_fill(limit: int | None = None) → Expr[source]

用下一个非空值填充缺失值。

Parameters:

limit: 要向后填充的连续空值的数量。

另请参阅

forward_fill
shift

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None],
...         "b": [4, None, 6],
...         "c": [None, None, 2],
...     }
... )
>>> df.select(pl.all().backward_fill())
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ i64 ┆ i64 │
╞══════╪═════╪═════╡
│ 1    ┆ 4   ┆ 2   │
│ 2    ┆ 6   ┆ 2   │
│ null ┆ 6   ┆ 2   │
└──────┴─────┴─────┘
>>> df.select(pl.all().backward_fill(limit=1))
shape: (3, 3)
┌──────┬─────┬──────┐
│ a    ┆ b   ┆ c    │
│ ---  ┆ --- ┆ ---  │
│ i64  ┆ i64 ┆ i64  │
╞══════╪═════╪══════╡
│ 1    ┆ 4   ┆ null │
│ 2    ┆ 6   ┆ 2    │
│ null ┆ 6   ┆ 2    │
└──────┴─────┴──────┘

bitwise_and() → Expr[source]

执行按位与的聚合操作。

示例

>>> df = pl.DataFrame({"n": [-1, 0, 1]})
>>> df.select(pl.col("n").bitwise_and())
shape: (1, 1)
┌─────┐
│ n   │
│ --- │
│ i64 │
╞═════╡
│ 0   │
└─────┘
>>> df = pl.DataFrame(
...     {"grouper": ["a", "a", "a", "b", "b"], "n": [-1, 0, 1, -1, 1]}
... )
>>> df.group_by("grouper", maintain_order=True).agg(pl.col("n").bitwise_and())
shape: (2, 2)
┌─────────┬─────┐
│ grouper ┆ n   │
│ ---     ┆ --- │
│ str     ┆ i64 │
╞═════════╪═════╡
│ a       ┆ 0   │
│ b       ┆ 1   │
└─────────┴─────┘

bitwise_count_ones() → Expr[source]: 评估设置的位数。

bitwise_count_zeros() → Expr[source]: 评估未设置的位数。

bitwise_leading_ones() → Expr[source]: 评估在遇到未设置的位之前的最重要的设置位数。

bitwise_leading_zeros() → Expr[source]: 评估在遇到设置位之前最高有效未设置位的数量。

bitwise_or() → Expr[source]

执行按位或的聚合操作。

示例

>>> df = pl.DataFrame({"n": [-1, 0, 1]})
>>> df.select(pl.col("n").bitwise_or())
shape: (1, 1)
┌─────┐
│ n   │
│ --- │
│ i64 │
╞═════╡
│ -1  │
└─────┘
>>> df = pl.DataFrame(
...     {"grouper": ["a", "a", "a", "b", "b"], "n": [-1, 0, 1, -1, 1]}
... )
>>> df.group_by("grouper", maintain_order=True).agg(pl.col("n").bitwise_or())
shape: (2, 2)
┌─────────┬─────┐
│ grouper ┆ n   │
│ ---     ┆ --- │
│ str     ┆ i64 │
╞═════════╪═════╡
│ a       ┆ -1  │
│ b       ┆ -1  │
└─────────┴─────┘

bitwise_trailing_ones() → Expr[source]: 评估在遇到未设置的位之前的最不重要的设置位数。

bitwise_trailing_zeros() → Expr[source]: 评估在遇到设置位之前的最不重要的未设置位的数量。

bitwise_xor() → Expr[source]

执行按位异或的聚合操作。

示例

>>> df = pl.DataFrame({"n": [-1, 0, 1]})
>>> df.select(pl.col("n").bitwise_xor())
shape: (1, 1)
┌─────┐
│ n   │
│ --- │
│ i64 │
╞═════╡
│ -2  │
└─────┘
>>> df = pl.DataFrame(
...     {"grouper": ["a", "a", "a", "b", "b"], "n": [-1, 0, 1, -1, 1]}
... )
>>> df.group_by("grouper", maintain_order=True).agg(pl.col("n").bitwise_xor())
shape: (2, 2)
┌─────────┬─────┐
│ grouper ┆ n   │
│ ---     ┆ --- │
│ str     ┆ i64 │
╞═════════╪═════╡
│ a       ┆ -2  │
│ b       ┆ -2  │
└─────────┴─────┘

bottom_k(k: int | IntoExprColumn = 5) → Expr[source]

返回k个最小的元素。

非空元素总是优先于空元素。输出不保证按任何特定顺序排列，如果您希望输出排序，请在此函数后调用sort()。

这具有时间复杂度：

\[O(n)\]

Parameters:

k: 返回的元素数量。

另请参阅

top_k
top_k_by
bottom_k_by

示例

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

bottom_k_by( by: IntoExpr | Iterable[IntoExpr], k: int | IntoExprColumn = 5, *, reverse: bool | Sequence[bool] = False, ) → Expr[source]

返回与by列中k个最小元素对应的元素。

非空元素总是优先于空元素，无论reverse的值如何。输出不保证按任何特定顺序排列，如果您希望输出排序，请在此函数后调用sort()。

这具有时间复杂度：

\[O(n \log{n})\]

Parameters:

by: 用于确定最小元素的列。接受表达式输入。字符串被解析为列名。
k: 返回的元素数量。
reverse: 考虑by列中的k个最大元素（而不是k个最小元素）。可以通过传递一个布尔值序列来为每列指定这一点。

另请参阅

top_k
top_k_by
bottom_k

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [6, 5, 4, 3, 2, 1],
...         "c": ["Apple", "Orange", "Apple", "Apple", "Banana", "Banana"],
...     }
... )
>>> df
shape: (6, 3)
┌─────┬─────┬────────┐
│ a   ┆ b   ┆ c      │
│ --- ┆ --- ┆ ---    │
│ i64 ┆ i64 ┆ str    │
╞═════╪═════╪════════╡
│ 1   ┆ 6   ┆ Apple  │
│ 2   ┆ 5   ┆ Orange │
│ 3   ┆ 4   ┆ Apple  │
│ 4   ┆ 3   ┆ Apple  │
│ 5   ┆ 2   ┆ Banana │
│ 6   ┆ 1   ┆ Banana │
└─────┴─────┴────────┘

通过列 a 或 b 获取底部的2行。

>>> df.select(
...     pl.all().bottom_k_by("a", 2).name.suffix("_btm_by_a"),
...     pl.all().bottom_k_by("b", 2).name.suffix("_btm_by_b"),
... )
shape: (2, 6)
┌────────────┬────────────┬────────────┬────────────┬────────────┬────────────┐
│ a_btm_by_a ┆ b_btm_by_a ┆ c_btm_by_a ┆ a_btm_by_b ┆ b_btm_by_b ┆ c_btm_by_b │
│ ---        ┆ ---        ┆ ---        ┆ ---        ┆ ---        ┆ ---        │
│ i64        ┆ i64        ┆ str        ┆ i64        ┆ i64        ┆ str        │
╞════════════╪════════════╪════════════╪════════════╪════════════╪════════════╡
│ 1          ┆ 6          ┆ Apple      ┆ 6          ┆ 1          ┆ Banana     │
│ 2          ┆ 5          ┆ Orange     ┆ 5          ┆ 2          ┆ Banana     │
└────────────┴────────────┴────────────┴────────────┴────────────┴────────────┘

通过给定的顺序按多列获取底部2行。

>>> df.select(
...     pl.all()
...     .bottom_k_by(["c", "a"], 2, reverse=[False, True])
...     .name.suffix("_by_ca"),
...     pl.all()
...     .bottom_k_by(["c", "b"], 2, reverse=[False, True])
...     .name.suffix("_by_cb"),
... )
shape: (2, 6)
┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐
│ a_by_ca ┆ b_by_ca ┆ c_by_ca ┆ a_by_cb ┆ b_by_cb ┆ c_by_cb │
│ ---     ┆ ---     ┆ ---     ┆ ---     ┆ ---     ┆ ---     │
│ i64     ┆ i64     ┆ str     ┆ i64     ┆ i64     ┆ str     │
╞═════════╪═════════╪═════════╪═════════╪═════════╪═════════╡
│ 4       ┆ 3       ┆ Apple   ┆ 1       ┆ 6       ┆ Apple   │
│ 3       ┆ 4       ┆ Apple   ┆ 3       ┆ 4       ┆ Apple   │
└─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘

获取每组中按列 a 排序的底部2行。

>>> (
...     df.group_by("c", maintain_order=True)
...     .agg(pl.all().bottom_k_by("a", 2))
...     .explode(pl.all().exclude("c"))
... )
shape: (5, 3)
┌────────┬─────┬─────┐
│ c      ┆ a   ┆ b   │
│ ---    ┆ --- ┆ --- │
│ str    ┆ i64 ┆ i64 │
╞════════╪═════╪═════╡
│ Apple  ┆ 1   ┆ 6   │
│ Apple  ┆ 3   ┆ 4   │
│ Orange ┆ 2   ┆ 5   │
│ Banana ┆ 5   ┆ 2   │
│ Banana ┆ 6   ┆ 1   │
└────────┴─────┴─────┘

cast( dtype: PolarsDataType | type[Any], *, strict: bool = True, wrap_numerical: bool = False, ) → Expr[source]

在数据类型之间进行转换。

Parameters:

dtype: 要转换到的数据类型。
strict: 如果在谓词下推后对行的转换无效，则引发异常。如果False，无效的转换将产生空值。
wrap_numerical: 如果为True，数值转换将包裹溢出值，而不是将转换标记为无效。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": ["4", "5", "6"],
...     }
... )
>>> df.with_columns(
...     pl.col("a").cast(pl.Float64),
...     pl.col("b").cast(pl.Int32),
... )
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ i32 │
╞═════╪═════╡
│ 1.0 ┆ 4   │
│ 2.0 ┆ 5   │
│ 3.0 ┆ 6   │
└─────┴─────┘

cbrt() → Expr[source]

计算元素的立方根。

示例

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

ceil() → Expr[source]

向上取整到最接近的整数值。

仅适用于浮点型Series。

示例

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

将给定边界之外的值设置为边界值。

Parameters:

lower_bound: 下界。接受表达式输入。非表达式输入被解析为字面量。字符串被解析为列名。
upper_bound: 上限。接受表达式输入。非表达式输入被解析为字面量。字符串被解析为列名。

另请参阅

when

注释

此方法仅适用于数值和时间列。要裁剪其他数据类型，请考虑编写一个when-then-otherwise表达式。参见when()。

示例

指定下限和上限：

>>> df = pl.DataFrame({"a": [-50, 5, 50, None]})
>>> df.with_columns(clip=pl.col("a").clip(1, 10))
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ clip │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ -50  ┆ 1    │
│ 5    ┆ 5    │
│ 50   ┆ 10   │
│ null ┆ null │
└──────┴──────┘

仅指定单个边界：

>>> df.with_columns(clip=pl.col("a").clip(upper_bound=10))
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ clip │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ -50  ┆ -50  │
│ 5    ┆ 5    │
│ 50   ┆ 10   │
│ null ┆ null │
└──────┴──────┘

使用列作为边界：

>>> df = pl.DataFrame(
...     {"a": [-50, 5, 50, None], "low": [10, 1, 0, 0], "up": [20, 4, 3, 2]}
... )
>>> df.with_columns(clip=pl.col("a").clip("low", "up"))
shape: (4, 4)
┌──────┬─────┬─────┬──────┐
│ a    ┆ low ┆ up  ┆ clip │
│ ---  ┆ --- ┆ --- ┆ ---  │
│ i64  ┆ i64 ┆ i64 ┆ i64  │
╞══════╪═════╪═════╪══════╡
│ -50  ┆ 10  ┆ 20  ┆ 10   │
│ 5    ┆ 1   ┆ 4   ┆ 4    │
│ 50   ┆ 0   ┆ 3   ┆ 3    │
│ null ┆ 0   ┆ 2   ┆ null │
└──────┴─────┴─────┴──────┘

cos() → Expr[source]

计算元素级别的余弦值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

cosh() → Expr[source]

计算双曲余弦的逐元素值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

cot() → Expr[source]

计算元素级的余切值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

count() → Expr[source]

返回列中非空元素的数量。

Returns:

Expr: 数据类型 UInt32 的表达式。

另请参阅

len

示例

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

cum_count(*, reverse: bool = False) → Expr[source]

返回列中非空值的累计计数。

Parameters:

reverse: 反转操作。

示例

>>> df = pl.DataFrame({"a": ["x", "k", None, "d"]})
>>> df.with_columns(
...     pl.col("a").cum_count().alias("cum_count"),
...     pl.col("a").cum_count(reverse=True).alias("cum_count_reverse"),
... )
shape: (4, 3)
┌──────┬───────────┬───────────────────┐
│ a    ┆ cum_count ┆ cum_count_reverse │
│ ---  ┆ ---       ┆ ---               │
│ str  ┆ u32       ┆ u32               │
╞══════╪═══════════╪═══════════════════╡
│ x    ┆ 1         ┆ 3                 │
│ k    ┆ 2         ┆ 2                 │
│ null ┆ 2         ┆ 1                 │
│ d    ┆ 3         ┆ 1                 │
└──────┴───────────┴───────────────────┘

cum_max(*, reverse: bool = False) → Expr[source]

获取一个数组，其中包含在每个元素处计算的累积最大值。

Parameters:

reverse: 反转操作。

示例

>>> df = pl.DataFrame({"a": [1, 3, 2]})
>>> df.with_columns(
...     pl.col("a").cum_max().alias("cum_max"),
...     pl.col("a").cum_max(reverse=True).alias("cum_max_reverse"),
... )
shape: (3, 3)
┌─────┬─────────┬─────────────────┐
│ a   ┆ cum_max ┆ cum_max_reverse │
│ --- ┆ ---     ┆ ---             │
│ i64 ┆ i64     ┆ i64             │
╞═════╪═════════╪═════════════════╡
│ 1   ┆ 1       ┆ 3               │
│ 3   ┆ 3       ┆ 3               │
│ 2   ┆ 3       ┆ 2               │
└─────┴─────────┴─────────────────┘

空值被排除在外，但也可以通过调用forward_fill来填充。

>>> df = pl.DataFrame({"values": [None, 10, None, 8, 9, None, 16, None]})
>>> df.with_columns(
...     pl.col("values").cum_max().alias("cum_max"),
...     pl.col("values").cum_max().forward_fill().alias("cum_max_all_filled"),
... )
shape: (8, 3)
┌────────┬─────────┬────────────────────┐
│ values ┆ cum_max ┆ cum_max_all_filled │
│ ---    ┆ ---     ┆ ---                │
│ i64    ┆ i64     ┆ i64                │
╞════════╪═════════╪════════════════════╡
│ null   ┆ null    ┆ null               │
│ 10     ┆ 10      ┆ 10                 │
│ null   ┆ null    ┆ 10                 │
│ 8      ┆ 10      ┆ 10                 │
│ 9      ┆ 10      ┆ 10                 │
│ null   ┆ null    ┆ 10                 │
│ 16     ┆ 16      ┆ 16                 │
│ null   ┆ null    ┆ 16                 │
└────────┴─────────┴────────────────────┘

cum_min(*, reverse: bool = False) → Expr[source]

获取一个数组，其中包含在每个元素处计算的累积最小值。

Parameters:

reverse: 反转操作。

示例

>>> df = pl.DataFrame({"a": [3, 1, 2]})
>>> df.with_columns(
...     pl.col("a").cum_min().alias("cum_min"),
...     pl.col("a").cum_min(reverse=True).alias("cum_min_reverse"),
... )
shape: (3, 3)
┌─────┬─────────┬─────────────────┐
│ a   ┆ cum_min ┆ cum_min_reverse │
│ --- ┆ ---     ┆ ---             │
│ i64 ┆ i64     ┆ i64             │
╞═════╪═════════╪═════════════════╡
│ 3   ┆ 3       ┆ 1               │
│ 1   ┆ 1       ┆ 1               │
│ 2   ┆ 1       ┆ 2               │
└─────┴─────────┴─────────────────┘

cum_prod(*, reverse: bool = False) → Expr[source]

获取一个数组，其中包含在每个元素处计算的累积乘积。

Parameters:

reverse: 反转操作。

注释

{Int8, UInt8, Int16, UInt16} 中的数据类型在求和之前会被转换为 Int64，以防止溢出问题。

示例

>>> df = pl.DataFrame({"a": [1, 2, 3, 4]})
>>> df.with_columns(
...     pl.col("a").cum_prod().alias("cum_prod"),
...     pl.col("a").cum_prod(reverse=True).alias("cum_prod_reverse"),
... )
shape: (4, 3)
┌─────┬──────────┬──────────────────┐
│ a   ┆ cum_prod ┆ cum_prod_reverse │
│ --- ┆ ---      ┆ ---              │
│ i64 ┆ i64      ┆ i64              │
╞═════╪══════════╪══════════════════╡
│ 1   ┆ 1        ┆ 24               │
│ 2   ┆ 2        ┆ 24               │
│ 3   ┆ 6        ┆ 12               │
│ 4   ┆ 24       ┆ 4                │
└─────┴──────────┴──────────────────┘

cum_sum(*, reverse: bool = False) → Expr[source]

获取一个数组，其中每个元素都计算了累积和。

Parameters:

reverse: 反转操作。

注释

{Int8, UInt8, Int16, UInt16} 中的数据类型在求和之前会被转换为 Int64，以防止溢出问题。

示例

>>> df = pl.DataFrame({"a": [1, 2, 3, 4]})
>>> df.with_columns(
...     pl.col("a").cum_sum().alias("cum_sum"),
...     pl.col("a").cum_sum(reverse=True).alias("cum_sum_reverse"),
... )
shape: (4, 3)
┌─────┬─────────┬─────────────────┐
│ a   ┆ cum_sum ┆ cum_sum_reverse │
│ --- ┆ ---     ┆ ---             │
│ i64 ┆ i64     ┆ i64             │
╞═════╪═════════╪═════════════════╡
│ 1   ┆ 1       ┆ 10              │
│ 2   ┆ 3       ┆ 9               │
│ 3   ┆ 6       ┆ 7               │
│ 4   ┆ 10      ┆ 4               │
└─────┴─────────┴─────────────────┘

空值被排除在外，但也可以通过调用forward_fill来填充。

>>> df = pl.DataFrame({"values": [None, 10, None, 8, 9, None, 16, None]})
>>> df.with_columns(
...     pl.col("values").cum_sum().alias("value_cum_sum"),
...     pl.col("values")
...     .cum_sum()
...     .forward_fill()
...     .alias("value_cum_sum_all_filled"),
... )
shape: (8, 3)
┌────────┬───────────────┬──────────────────────────┐
│ values ┆ value_cum_sum ┆ value_cum_sum_all_filled │
│ ---    ┆ ---           ┆ ---                      │
│ i64    ┆ i64           ┆ i64                      │
╞════════╪═══════════════╪══════════════════════════╡
│ null   ┆ null          ┆ null                     │
│ 10     ┆ 10            ┆ 10                       │
│ null   ┆ null          ┆ 10                       │
│ 8      ┆ 18            ┆ 18                       │
│ 9      ┆ 27            ┆ 27                       │
│ null   ┆ null          ┆ 27                       │
│ 16     ┆ 43            ┆ 43                       │
│ null   ┆ null          ┆ 43                       │
└────────┴───────────────┴──────────────────────────┘

cumulative_eval( expr: Expr, *, min_periods: int = 1, parallel: bool = False, ) → Expr[source]

在每次迭代增加1个槽的滑动窗口上运行表达式。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

Parameters:

expr: 要评估的表达式
min_periods: 在表达式被评估之前，窗口中应该存在的有效值的数量。有效值 = length - null_count
parallel: 并行运行。不要在已经具有大量并行化的分组或其他操作中执行此操作。

警告

这可能会非常慢，因为它可能具有O(n^2)的复杂度。不要在对所有元素进行操作的场景中使用此方法。

示例

>>> df = pl.DataFrame({"values": [1, 2, 3, 4, 5]})
>>> df.select(
...     [
...         pl.col("values").cumulative_eval(
...             pl.element().first() - pl.element().last() ** 2
...         )
...     ]
... )
shape: (5, 1)
┌────────┐
│ values │
│ ---    │
│ i64    │
╞════════╡
│ 0      │
│ -3     │
│ -8     │
│ -15    │
│ -24    │
└────────┘

cut( breaks: Sequence[float], *, labels: Sequence[str] | None = None, left_closed: bool = False, include_breaks: bool = False, ) → Expr[source]

将连续值分箱为离散类别。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

Parameters:

breaks: 唯一分割点的列表。
labels: 类别的名称。标签的数量必须等于切点的数量加一。
left_closed: 将间隔设置为左闭而不是右闭。
include_breaks: 包含一个列，显示每个观察值所属区间的右端点。这将把输出的数据类型从Categorical更改为Struct。

Returns:

Expr: 如果include_breaks设置为False（默认），则数据类型为Categorical的表达式，否则为数据类型Struct的表达式。

另请参阅

qcut

示例

将一列分为三类。

>>> df = pl.DataFrame({"foo": [-2, -1, 0, 1, 2]})
>>> df.with_columns(
...     pl.col("foo").cut([-1, 1], labels=["a", "b", "c"]).alias("cut")
... )
shape: (5, 2)
┌─────┬─────┐
│ foo ┆ cut │
│ --- ┆ --- │
│ i64 ┆ cat │
╞═════╪═════╡
│ -2  ┆ a   │
│ -1  ┆ a   │
│ 0   ┆ b   │
│ 1   ┆ b   │
│ 2   ┆ c   │
└─────┴─────┘

添加类别和断点。

>>> df.with_columns(
...     pl.col("foo").cut([-1, 1], include_breaks=True).alias("cut")
... ).unnest("cut")
shape: (5, 3)
┌─────┬────────────┬────────────┐
│ foo ┆ breakpoint ┆ category   │
│ --- ┆ ---        ┆ ---        │
│ i64 ┆ f64        ┆ cat        │
╞═════╪════════════╪════════════╡
│ -2  ┆ -1.0       ┆ (-inf, -1] │
│ -1  ┆ -1.0       ┆ (-inf, -1] │
│ 0   ┆ 1.0        ┆ (-1, 1]    │
│ 1   ┆ 1.0        ┆ (-1, 1]    │
│ 2   ┆ inf        ┆ (1, inf]   │
└─────┴────────────┴────────────┘

degrees() → Expr[source]

将弧度转换为角度。

Returns:

Expr: 数据类型 Float64 的表达。

示例

>>> import math
>>> df = pl.DataFrame({"a": [x * math.pi for x in range(-4, 5)]})
>>> df.select(pl.col("a").degrees())
shape: (9, 1)
┌────────┐
│ a      │
│ ---    │
│ f64    │
╞════════╡
│ -720.0 │
│ -540.0 │
│ -360.0 │
│ -180.0 │
│ 0.0    │
│ 180.0  │
│ 360.0  │
│ 540.0  │
│ 720.0  │
└────────┘

classmethod deserialize( source: str | Path | IOBase | bytes, *, format: SerializationFormat = 'binary', ) → Expr[source]

从文件中读取序列化表达式。

Parameters:

source

文件路径或类文件对象（类文件对象指的是具有read()方法的对象，例如文件句柄（如通过内置的open函数）或BytesIO）。

format

Expr 被序列化的格式。选项：

"binary": 从二进制格式（字节）反序列化。这是默认设置。
"json": 从JSON格式（字符串）反序列化。

警告

如果逻辑计划包含Python UDFs，此函数将使用pickle，因此继承了相关的安全影响。反序列化可以执行任意代码，因此应仅在受信任的数据上尝试。

另请参阅

Expr.meta.serialize

注释

序列化在Polars版本之间不稳定：在一个Polars版本中序列化的LazyFrame可能无法在另一个Polars版本中反序列化。

示例

>>> import io
>>> expr = pl.col("foo").sum().over("bar")
>>> bytes = expr.meta.serialize()
>>> pl.Expr.deserialize(io.BytesIO(bytes))  
<Expr ['col("foo").sum().over([col("ba…'] at ...>

diff(n: int = 1, null_behavior: NullBehavior = 'ignore') → Expr[source]

计算偏移项之间的第一个离散差异。

Parameters:

n: 要移动的槽位数。
null_behavior{‘ignore’, ‘drop’}: 如何处理空值。

示例

>>> df = pl.DataFrame({"int": [20, 10, 30, 25, 35]})
>>> df.with_columns(change=pl.col("int").diff())
shape: (5, 2)
┌─────┬────────┐
│ int ┆ change │
│ --- ┆ ---    │
│ i64 ┆ i64    │
╞═════╪════════╡
│ 20  ┆ null   │
│ 10  ┆ -10    │
│ 30  ┆ 20     │
│ 25  ┆ -5     │
│ 35  ┆ 10     │
└─────┴────────┘

>>> df.with_columns(change=pl.col("int").diff(n=2))
shape: (5, 2)
┌─────┬────────┐
│ int ┆ change │
│ --- ┆ ---    │
│ i64 ┆ i64    │
╞═════╪════════╡
│ 20  ┆ null   │
│ 10  ┆ null   │
│ 30  ┆ 10     │
│ 25  ┆ 15     │
│ 35  ┆ 5      │
└─────┴────────┘

>>> df.select(pl.col("int").diff(n=2, null_behavior="drop").alias("diff"))
shape: (3, 1)
┌──────┐
│ diff │
│ ---  │
│ i64  │
╞══════╡
│ 10   │
│ 15   │
│ 5    │
└──────┘

dot(other: Expr | str) → Expr[source]

计算两个表达式之间的点积/内积。

Parameters:

other: 用于计算点积的表达式。

示例

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

drop_nans() → Expr[source]

删除所有浮点数的NaN值。

剩余元素的原始顺序被保留。

另请参阅

drop_nulls

注释

NaN 值与空值不同。要删除空值，请使用 drop_nulls()。

示例

>>> df = pl.DataFrame({"a": [1.0, None, 3.0, float("nan")]})
>>> df.select(pl.col("a").drop_nans())
shape: (3, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 1.0  │
│ null │
│ 3.0  │
└──────┘

drop_nulls() → Expr[source]

删除所有空值。

剩余元素的原始顺序被保留。

另请参阅

drop_nans

注释

空值与NaN值不同。要删除NaN值，请使用drop_nans()。

示例

>>> df = pl.DataFrame({"a": [1.0, None, 3.0, float("nan")]})
>>> df.select(pl.col("a").drop_nulls())
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
│ 3.0 │
│ NaN │
└─────┘

entropy( base: float = 2.718281828459045, *, normalize: bool = True, ) → Expr[source]

计算熵。

使用公式 -sum(pk * log(pk)，其中 pk 是离散概率。

Parameters:

base: 给定基数，默认为 e
normalize: 如果pk的总和不为1，则对其进行归一化。

示例

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

eq(other: Any) → Expr[source]

等同于相等运算符 expr == other 的方法。

Parameters:

other: 要与字面量或表达式值进行比较。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 4.0],
...         "y": [2.0, 2.0, float("nan"), 4.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").eq(pl.col("y")).alias("x == y"),
... )
shape: (4, 3)
┌─────┬─────┬────────┐
│ x   ┆ y   ┆ x == y │
│ --- ┆ --- ┆ ---    │
│ f64 ┆ f64 ┆ bool   │
╞═════╪═════╪════════╡
│ 1.0 ┆ 2.0 ┆ false  │
│ 2.0 ┆ 2.0 ┆ true   │
│ NaN ┆ NaN ┆ true   │
│ 4.0 ┆ 4.0 ┆ true   │
└─────┴─────┴────────┘

eq_missing(other: Any) → Expr[source]

等同于相等运算符 expr == other 的方法，其中 None == None。

这与默认的 eq 不同，在默认情况下，空值会被传播。

Parameters:

other: 要与字面量或表达式值进行比较。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 4.0, None, None],
...         "y": [2.0, 2.0, float("nan"), 4.0, 5.0, None],
...     }
... )
>>> df.with_columns(
...     pl.col("x").eq(pl.col("y")).alias("x eq y"),
...     pl.col("x").eq_missing(pl.col("y")).alias("x eq_missing y"),
... )
shape: (6, 4)
┌──────┬──────┬────────┬────────────────┐
│ x    ┆ y    ┆ x eq y ┆ x eq_missing y │
│ ---  ┆ ---  ┆ ---    ┆ ---            │
│ f64  ┆ f64  ┆ bool   ┆ bool           │
╞══════╪══════╪════════╪════════════════╡
│ 1.0  ┆ 2.0  ┆ false  ┆ false          │
│ 2.0  ┆ 2.0  ┆ true   ┆ true           │
│ NaN  ┆ NaN  ┆ true   ┆ true           │
│ 4.0  ┆ 4.0  ┆ true   ┆ true           │
│ null ┆ 5.0  ┆ null   ┆ false          │
│ null ┆ null ┆ null   ┆ true           │
└──────┴──────┴────────┴────────────────┘

ewm_mean( *, com: float | None = None, span: float | None = None, half_life: float | None = None, alpha: float | None = None, adjust: bool = True, min_periods: int = 1, ignore_nulls: bool = False, ) → Expr[source]

计算指数加权移动平均。

Parameters:

com

以质心为中心指定衰减，$\gamma$，使用

\[\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0\]

span

根据跨度$\theta$指定衰减

\[\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1\]

half_life

以半衰期$\tau$来指定衰减，使用

\[\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \tau } \right\} \; \forall \; \tau > 0\]

alpha

直接指定平滑因子alpha，$0 < \alpha \leq 1$。

adjust

在初始阶段通过衰减调整因子进行除法，以考虑相对权重的不平衡

当 adjust=True（默认值）时，EW 函数使用权重 $w_i = (1 - \alpha)^i$ 计算

当 adjust=False 时，EW 函数通过递归计算

\[\begin{split}y_0 &= x_0 \\ y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t\end{split}\]

min_periods

窗口中需要的最小观察次数才能有值（否则结果为null）。

ignore_nulls

在计算权重时忽略缺失值。

当 ignore_nulls=False（默认）时，权重基于绝对位置。例如，在计算 [$x_0$, None, $x_2$] 的最终加权平均值时，$x_0$ 和 $x_2$ 的权重分别为 $(1-\alpha)^2$ 和 $1$（如果 adjust=True），以及 $(1-\alpha)^2$ 和 $\alpha$（如果 adjust=False）。

当 ignore_nulls=True 时，权重基于相对位置。例如，在计算 [$x_0$, None, $x_2$] 的最终加权平均值时，$x_0$ 和 $x_2$ 的权重分别为 $1-\alpha$ 和 $1$（如果 adjust=True），或者 $1-\alpha$ 和 $\alpha$（如果 adjust=False）。

示例

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").ewm_mean(com=1, ignore_nulls=False))
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.0      │
│ 1.666667 │
│ 2.428571 │
└──────────┘

ewm_mean_by(by: str | IntoExpr, *, half_life: str | timedelta) → Expr[source]

计算基于时间的指数加权移动平均。

给定在时间 $t_0, t_1, \ldots, t_{n-1}$ 的观测值 $x_0, x_1, \ldots, x_{n-1}$，EWMA 的计算方式为

\[ \begin{align}\begin{aligned}y_0 &= x_0\\\alpha_i &= 1 - \exp \left\{ \frac{ -\ln(2)(t_i-t_{i-1}) } { \tau } \right\}\\y_i &= \alpha_i x_i + (1 - \alpha_i) y_{i-1}; \quad i > 0\end{aligned}\end{align} \]

其中 $\tau$ 是 half_life。

Parameters:

by

用于计算平均值的时间。应为 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型。

half_life

观察值衰减到其一半值的时间单位。

可以从一个时间差创建，或者通过使用以下字符串语言来创建：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1天 (1 天)
1周 (1 周)
1i (1 索引计数)

或者将它们组合起来： “3d12h4m25s” # 3天，12小时，4分钟，25秒

请注意，half_life被视为一个固定的持续时间 - 不支持日历持续时间，如月份（或在时区感知的情况下甚至天数），请以大约等效的小时数表示您的持续时间（例如，使用'370h'而不是'1mo'）。

Returns:

Expr: 如果输入是Float32，则为Float32，否则为Float64。

示例

>>> from datetime import date, timedelta
>>> df = pl.DataFrame(
...     {
...         "values": [0, 1, 2, None, 4],
...         "times": [
...             date(2020, 1, 1),
...             date(2020, 1, 3),
...             date(2020, 1, 10),
...             date(2020, 1, 15),
...             date(2020, 1, 17),
...         ],
...     }
... ).sort("times")
>>> df.with_columns(
...     result=pl.col("values").ewm_mean_by("times", half_life="4d"),
... )
shape: (5, 3)
┌────────┬────────────┬──────────┐
│ values ┆ times      ┆ result   │
│ ---    ┆ ---        ┆ ---      │
│ i64    ┆ date       ┆ f64      │
╞════════╪════════════╪══════════╡
│ 0      ┆ 2020-01-01 ┆ 0.0      │
│ 1      ┆ 2020-01-03 ┆ 0.292893 │
│ 2      ┆ 2020-01-10 ┆ 1.492474 │
│ null   ┆ 2020-01-15 ┆ null     │
│ 4      ┆ 2020-01-17 ┆ 3.254508 │
└────────┴────────────┴──────────┘

ewm_std( *, com: float | None = None, span: float | None = None, half_life: float | None = None, alpha: float | None = None, adjust: bool = True, bias: bool = False, min_periods: int = 1, ignore_nulls: bool = False, ) → Expr[source]

计算指数加权移动标准差。

Parameters:

com

以质心为中心指定衰减，$\gamma$，使用

\[\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0\]

span

根据跨度$\theta$指定衰减

\[\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1\]

half_life

以半衰期$\lambda$来指定衰减，

\[\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \; \forall \; \lambda > 0\]

alpha

直接指定平滑因子alpha，$0 < \alpha \leq 1$。

adjust

在初始阶段通过衰减调整因子进行除法，以考虑相对权重的不平衡

当 adjust=True（默认值）时，EW 函数使用权重 $w_i = (1 - \alpha)^i$ 计算

当 adjust=False 时，EW 函数通过递归计算

\[\begin{split}y_0 &= x_0 \\ y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t\end{split}\]

bias

当 bias=False 时，应用校正以使估计在统计上无偏。

min_periods

窗口中需要的最小观察次数才能有值（否则结果为null）。

ignore_nulls

在计算权重时忽略缺失值。

当 ignore_nulls=False（默认）时，权重基于绝对位置。例如，在计算 [$x_0$, None, $x_2$] 的最终加权平均值时，$x_0$ 和 $x_2$ 的权重分别为 $(1-\alpha)^2$ 和 $1$（如果 adjust=True），以及 $(1-\alpha)^2$ 和 $\alpha$（如果 adjust=False）。

当 ignore_nulls=True 时，权重基于相对位置。例如，在计算 [$x_0$, None, $x_2$] 的最终加权平均值时，$x_0$ 和 $x_2$ 的权重分别为 $1-\alpha$ 和 $1$（如果 adjust=True），或者 $1-\alpha$ 和 $\alpha$（如果 adjust=False）。

示例

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").ewm_std(com=1, ignore_nulls=False))
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.0      │
│ 0.707107 │
│ 0.963624 │
└──────────┘

ewm_var( *, com: float | None = None, span: float | None = None, half_life: float | None = None, alpha: float | None = None, adjust: bool = True, bias: bool = False, min_periods: int = 1, ignore_nulls: bool = False, ) → Expr[source]

计算指数加权移动方差。

Parameters:

com

以质心为中心指定衰减，$\gamma$，使用

\[\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0\]

span

根据跨度$\theta$指定衰减

\[\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1\]

half_life

以半衰期$\lambda$来指定衰减，

\[\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \; \forall \; \lambda > 0\]

alpha

直接指定平滑因子alpha，$0 < \alpha \leq 1$。

adjust

在初始阶段通过衰减调整因子进行除法，以考虑相对权重的不平衡

当 adjust=True（默认值）时，EW 函数使用权重 $w_i = (1 - \alpha)^i$ 计算

当 adjust=False 时，EW 函数通过递归计算

\[\begin{split}y_0 &= x_0 \\ y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t\end{split}\]

bias

当 bias=False 时，应用校正以使估计在统计上无偏。

min_periods

窗口中需要的最小观察次数才能有值（否则结果为null）。

ignore_nulls

在计算权重时忽略缺失值。

当 ignore_nulls=False（默认）时，权重基于绝对位置。例如，在计算 [$x_0$, None, $x_2$] 的最终加权平均值时，$x_0$ 和 $x_2$ 的权重分别为 $(1-\alpha)^2$ 和 $1$（如果 adjust=True），以及 $(1-\alpha)^2$ 和 $\alpha$（如果 adjust=False）。

当 ignore_nulls=True 时，权重基于相对位置。例如，在计算 [$x_0$, None, $x_2$] 的最终加权平均值时，$x_0$ 和 $x_2$ 的权重分别为 $1-\alpha$ 和 $1$（如果 adjust=True），或者 $1-\alpha$ 和 $\alpha$（如果 adjust=False）。

示例

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").ewm_var(com=1, ignore_nulls=False))
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.0      │
│ 0.5      │
│ 0.928571 │
└──────────┘

exclude( columns: str | PolarsDataType | Collection[str] | Collection[PolarsDataType], *more_columns: str | PolarsDataType, ) → Expr[source]

从多列表达式中排除列。

仅在通配符或正则表达式列选择后有效，并且你不能同时提供字符串列名和数据类型（你可能更倾向于使用选择器）。

Parameters:

columns: 要排除的列的名称或数据类型。接受正则表达式输入。正则表达式应以^开头并以$结尾。
*more_columns: 要排除的列的其他名称或数据类型，作为位置参数指定。

示例

>>> df = pl.DataFrame(
...     {
...         "aa": [1, 2, 3],
...         "ba": ["a", "b", None],
...         "cc": [None, 2.5, 1.5],
...     }
... )
>>> df
shape: (3, 3)
┌─────┬──────┬──────┐
│ aa  ┆ ba   ┆ cc   │
│ --- ┆ ---  ┆ ---  │
│ i64 ┆ str  ┆ f64  │
╞═════╪══════╪══════╡
│ 1   ┆ a    ┆ null │
│ 2   ┆ b    ┆ 2.5  │
│ 3   ┆ null ┆ 1.5  │
└─────┴──────┴──────┘

按列名排除：

>>> df.select(pl.all().exclude("ba"))
shape: (3, 2)
┌─────┬──────┐
│ aa  ┆ cc   │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ null │
│ 2   ┆ 2.5  │
│ 3   ┆ 1.5  │
└─────┴──────┘

通过正则表达式排除，例如删除所有名称以字母“a”结尾的列：

>>> df.select(pl.all().exclude("^.*a$"))
shape: (3, 1)
┌──────┐
│ cc   │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ 2.5  │
│ 1.5  │
└──────┘

按数据类型排除，例如移除所有类型为Int64或Float64的列：

>>> df.select(pl.all().exclude([pl.Int64, pl.Float64]))
shape: (3, 1)
┌──────┐
│ ba   │
│ ---  │
│ str  │
╞══════╡
│ a    │
│ b    │
│ null │
└──────┘

exp() → Expr[source]

计算指数，逐元素。

示例

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

explode() → Expr[source]

展开一个列表表达式。

这意味着每个项目都被扩展到一个新行。

Returns:

Expr: 表达式，具有列表元素的数据类型。

另请参阅

Expr.list.explode: 展开一个列表列。

示例

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

extend_constant(value: IntoExpr, n: int | IntoExprColumn) → Expr[source]

用于使用值的'n'个副本扩展Series的极快方法。

Parameters:

value: 一个常量字面值或单位表达式，用于扩展表达式结果系列；可以传递None以用空值扩展。
n: 将要添加的额外值的数量。

示例

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

fill_nan( value: int | float | Expr | None, ) → Expr[source]

用填充值填充浮点数的NaN值。

Parameters:

value: 用于填充NaN值的值。

警告

请注意，浮点数的NaN（非数字）不是缺失值。要替换缺失值，请使用 fill_null()。

另请参阅

fill_null

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1.0, None, float("nan")],
...         "b": [4.0, float("nan"), 6],
...     }
... )
>>> df.with_columns(pl.col("b").fill_nan(0))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ f64  ┆ f64 │
╞══════╪═════╡
│ 1.0  ┆ 4.0 │
│ null ┆ 0.0 │
│ NaN  ┆ 6.0 │
└──────┴─────┘

fill_null( value: Any | Expr | None = None, strategy: FillNullStrategy | None = None, limit: int | None = None, ) → Expr[source]

使用指定的值或策略填充空值。

要插值空值，请参阅interpolate。请参阅以下示例，使用表达式填充空值。

Parameters:

value: 用于填充空值的值。
strategy{None, ‘forward’, ‘backward’, ‘min’, ‘max’, ‘mean’, ‘zero’, ‘one’}: 用于填充空值的策略。
limit: 使用‘forward’或‘backward’策略时，要填充的连续空值的数量。

另请参阅

fill_nan

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None],
...         "b": [4, None, 6],
...     }
... )
>>> df.with_columns(pl.col("b").fill_null(strategy="zero"))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ i64  ┆ i64 │
╞══════╪═════╡
│ 1    ┆ 4   │
│ 2    ┆ 0   │
│ null ┆ 6   │
└──────┴─────┘
>>> df.with_columns(pl.col("b").fill_null(99))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ i64  ┆ i64 │
╞══════╪═════╡
│ 1    ┆ 4   │
│ 2    ┆ 99  │
│ null ┆ 6   │
└──────┴─────┘
>>> df.with_columns(pl.col("b").fill_null(strategy="forward"))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ i64  ┆ i64 │
╞══════╪═════╡
│ 1    ┆ 4   │
│ 2    ┆ 4   │
│ null ┆ 6   │
└──────┴─────┘
>>> df.with_columns(pl.col("b").fill_null(pl.col("b").median()))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ i64  ┆ f64 │
╞══════╪═════╡
│ 1    ┆ 4.0 │
│ 2    ┆ 5.0 │
│ null ┆ 6.0 │
└──────┴─────┘
>>> df.with_columns(pl.all().fill_null(pl.all().median()))
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 1.0 ┆ 4.0 │
│ 2.0 ┆ 5.0 │
│ 1.5 ┆ 6.0 │
└─────┴─────┘

filter(

*predicates: IntoExprColumn | Iterable[IntoExprColumn],

**constraints: Any,

) → Expr[source]

根据一个或多个谓词表达式过滤表达式。

剩余元素的原始顺序被保留。

过滤器未评估为True的元素将被丢弃，包括空值。

在聚合上下文中非常有用。如果你想在DataFrame级别进行过滤，请使用LazyFrame.filter。

Parameters:

predicates: 评估为布尔系列的表达式。
constraints: 列过滤器；使用 name = value 通过提供的值过滤列。每个约束的行为将与 pl.col(name).eq(value) 相同，并且将使用 & 隐式地与其他过滤条件连接。

示例

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

过滤表达式也可以将约束作为关键字参数。

>>> df = pl.DataFrame(
...     {
...         "key": ["a", "a", "a", "a", "b", "b", "b", "b", "b"],
...         "n": [1, 2, 2, 3, 1, 3, 3, 2, 3],
...     },
... )
>>> df.group_by("key").agg(
...     n_1=pl.col("n").filter(n=1).sum(),
...     n_2=pl.col("n").filter(n=2).sum(),
...     n_3=pl.col("n").filter(n=3).sum(),
... ).sort(by="key")
shape: (2, 4)
┌─────┬─────┬─────┬─────┐
│ key ┆ n_1 ┆ n_2 ┆ n_3 │
│ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╪═════╡
│ a   ┆ 1   ┆ 4   ┆ 3   │
│ b   ┆ 1   ┆ 2   ┆ 9   │
└─────┴─────┴─────┴─────┘

first() → Expr[source]

获取第一个值。

示例

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

flatten() → Expr[source]

展平一个列表或字符串列。

Expr.list.explode() 的别名。

示例

>>> df = pl.DataFrame(
...     {
...         "group": ["a", "b", "b"],
...         "values": [[1, 2], [2, 3], [4]],
...     }
... )
>>> df.group_by("group").agg(pl.col("values").flatten())  
shape: (2, 2)
┌───────┬───────────┐
│ group ┆ values    │
│ ---   ┆ ---       │
│ str   ┆ list[i64] │
╞═══════╪═══════════╡
│ a     ┆ [1, 2]    │
│ b     ┆ [2, 3, 4] │
└───────┴───────────┘

floor() → Expr[source]

向下舍入到最接近的整数值。

仅适用于浮点型Series。

示例

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

floordiv(other: Any) → Expr[source]

整数除法运算符的方法等价于 expr // other。

Parameters:

other: 数值字面量或表达式值。

另请参阅

truediv

示例

>>> df = pl.DataFrame({"x": [1, 2, 3, 4, 5]})
>>> df.with_columns(
...     pl.col("x").truediv(2).alias("x/2"),
...     pl.col("x").floordiv(2).alias("x//2"),
... )
shape: (5, 3)
┌─────┬─────┬──────┐
│ x   ┆ x/2 ┆ x//2 │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ f64 ┆ i64  │
╞═════╪═════╪══════╡
│ 1   ┆ 0.5 ┆ 0    │
│ 2   ┆ 1.0 ┆ 1    │
│ 3   ┆ 1.5 ┆ 1    │
│ 4   ┆ 2.0 ┆ 2    │
│ 5   ┆ 2.5 ┆ 2    │
└─────┴─────┴──────┘

请注意，Polars的floordiv与Python的地板除法略有不同。例如，考虑6.0除以0.1的地板除法。 Python给出：

>>> 6.0 // 0.1
59.0

因为 0.1 在内部并不是以那个精确值表示的，而是一个略大的值。所以除法的结果略小于60，这意味着取整操作返回59.0。

Polars 首先进行浮点数除法，结果得到一个浮点数值 60.0，然后使用 floor 进行取整操作：

>>> df = pl.DataFrame({"x": [6.0, 6.03]})
>>> df.with_columns(
...     pl.col("x").truediv(0.1).alias("x/0.1"),
... ).with_columns(
...     pl.col("x/0.1").floor().alias("x/0.1 floor"),
... )
shape: (2, 3)
┌──────┬───────┬─────────────┐
│ x    ┆ x/0.1 ┆ x/0.1 floor │
│ ---  ┆ ---   ┆ ---         │
│ f64  ┆ f64   ┆ f64         │
╞══════╪═══════╪═════════════╡
│ 6.0  ┆ 60.0  ┆ 60.0        │
│ 6.03 ┆ 60.3  ┆ 60.0        │
└──────┴───────┴─────────────┘

产生更直观的结果60.0。包含x = 6.03的行是为了演示地板操作的效果。

floordiv 将这两个步骤结合起来，用一个表达式给出相同的结果：

>>> df.with_columns(
...     pl.col("x").floordiv(0.1).alias("x//0.1"),
... )
shape: (2, 2)
┌──────┬────────┐
│ x    ┆ x//0.1 │
│ ---  ┆ ---    │
│ f64  ┆ f64    │
╞══════╪════════╡
│ 6.0  ┆ 60.0   │
│ 6.03 ┆ 60.0   │
└──────┴────────┘

forward_fill(limit: int | None = None) → Expr[source]

用最后一个非空值填充缺失值。

Parameters:

limit: 要向前填充的连续空值的数量。

另请参阅

backward_fill
shift

示例

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

classmethod from_json(value: str) → Expr[source]

从JSON编码的字符串中读取表达式以构建一个表达式。

自版本 0.20.11 起已弃用：此方法已重命名为 deserialize()。请注意，新方法操作的是类似文件的对象而不是字符串。将您的输入包裹在 io.StringIO 中以保持相同的行为。

Parameters:

value: JSON编码的字符串值

gather( indices: int | Sequence[int] | IntoExpr | Series | np.ndarray[Any, Any], ) → Expr[source]

按索引取值。

Parameters:

indices: 一个导致UInt32类型Series的表达式。

Returns:

Expr: 相同数据类型的表达式。

另请参阅

Expr.get: 获取单个值

示例

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

gather_every(n: int, offset: int = 0) → Expr[source]

取Series中的每第n个值并返回一个新的Series。

Parameters:

n: 收集每n行。
offset: 起始索引。

示例

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

>>> df.select(pl.col("foo").gather_every(3, offset=1))
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 5   │
│ 8   │
└─────┘

ge(other: Any) → Expr[source]

方法等同于“大于或等于”运算符 expr >= other。

Parameters:

other: 要与字面量或表达式值进行比较。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [5.0, 4.0, float("nan"), 2.0],
...         "y": [5.0, 3.0, float("nan"), 1.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").ge(pl.col("y")).alias("x >= y"),
... )
shape: (4, 3)
┌─────┬─────┬────────┐
│ x   ┆ y   ┆ x >= y │
│ --- ┆ --- ┆ ---    │
│ f64 ┆ f64 ┆ bool   │
╞═════╪═════╪════════╡
│ 5.0 ┆ 5.0 ┆ true   │
│ 4.0 ┆ 3.0 ┆ true   │
│ NaN ┆ NaN ┆ true   │
│ 2.0 ┆ 1.0 ┆ true   │
└─────┴─────┴────────┘

get(index: int | Expr) → Expr[source]

通过索引返回单个值。

Parameters:

index: 一个导致UInt32索引的表达式。

Returns:

Expr: 相同数据类型的表达式。

示例

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

gt(other: Any) → Expr[source]

方法等同于“大于”运算符 expr > other。

Parameters:

other: 要与字面量或表达式值进行比较。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [5.0, 4.0, float("nan"), 2.0],
...         "y": [5.0, 3.0, float("nan"), 1.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").gt(pl.col("y")).alias("x > y"),
... )
shape: (4, 3)
┌─────┬─────┬───────┐
│ x   ┆ y   ┆ x > y │
│ --- ┆ --- ┆ ---   │
│ f64 ┆ f64 ┆ bool  │
╞═════╪═════╪═══════╡
│ 5.0 ┆ 5.0 ┆ false │
│ 4.0 ┆ 3.0 ┆ true  │
│ NaN ┆ NaN ┆ false │
│ 2.0 ┆ 1.0 ┆ true  │
└─────┴─────┴───────┘

has_nulls() → Expr[source]

检查表达式是否包含一个或多个空值。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [None, 1, None],
...         "b": [10, None, 300],
...         "c": [350, 650, 850],
...     }
... )
>>> df.select(pl.all().has_nulls())
shape: (1, 3)
┌──────┬──────┬───────┐
│ a    ┆ b    ┆ c     │
│ ---  ┆ ---  ┆ ---   │
│ bool ┆ bool ┆ bool  │
╞══════╪══════╪═══════╡
│ true ┆ true ┆ false │
└──────┴──────┴───────┘

hash( seed: int = 0, seed_1: int | None = None, seed_2: int | None = None, seed_3: int | None = None, ) → Expr[source]

对选择中的元素进行哈希处理。

哈希值的类型为 UInt64。

Parameters:

seed: 随机种子参数。默认为0。
seed_1: 随机种子参数。如果未设置，默认为 seed。
seed_2: 随机种子参数。如果未设置，默认为 seed。
seed_3: 随机种子参数。如果未设置，默认为 seed。

注释

此hash的实现不保证在不同Polars版本之间的结果稳定性。其稳定性仅在单个版本内得到保证。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None],
...         "b": ["x", None, "z"],
...     }
... )
>>> df.with_columns(pl.all().hash(10, 20, 30, 40))  
shape: (3, 2)
┌──────────────────────┬──────────────────────┐
│ a                    ┆ b                    │
│ ---                  ┆ ---                  │
│ u64                  ┆ u64                  │
╞══════════════════════╪══════════════════════╡
│ 9774092659964970114  ┆ 13614470193936745724 │
│ 1101441246220388612  ┆ 11638928888656214026 │
│ 11638928888656214026 ┆ 13382926553367784577 │
└──────────────────────┴──────────────────────┘

head(n: int | Expr = 10) → Expr[source]

获取前n行。

Parameters:

n: 返回的行数。

示例

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

hist( bins: IntoExpr | None = None, *, bin_count: int | None = None, include_category: bool = False, include_breakpoint: bool = False, ) → Expr[source]

将值分入桶中并计算它们的出现次数。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

Parameters:

bins: 需要进行的离散化处理。如果未给出，我们将根据数据确定边界。
bin_count: 如果没有提供bins，这将用于确定bins的距离
include_breakpoint: 包含一个指示上断点的列。
include_category: 包含一个显示区间为类别的列。

Returns:

DataFrame

示例

>>> df = pl.DataFrame({"a": [1, 3, 8, 8, 2, 1, 3]})
>>> df.select(pl.col("a").hist(bins=[1, 2, 3]))
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 1   │
│ 2   │
└─────┘
>>> df.select(
...     pl.col("a").hist(
...         bins=[1, 2, 3], include_breakpoint=True, include_category=True
...     )
... )
shape: (2, 1)
┌──────────────────────┐
│ a                    │
│ ---                  │
│ struct[3]            │
╞══════════════════════╡
│ {2.0,"(1.0, 2.0]",1} │
│ {3.0,"(2.0, 3.0]",2} │
└──────────────────────┘

implode() → Expr[source]

将值聚合到一个列表中。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": [4, 5, 6],
...     }
... )
>>> df.select(pl.all().implode())
shape: (1, 2)
┌───────────┬───────────┐
│ a         ┆ b         │
│ ---       ┆ ---       │
│ list[i64] ┆ list[i64] │
╞═══════════╪═══════════╡
│ [1, 2, 3] ┆ [4, 5, 6] │
└───────────┴───────────┘

inspect(fmt: str = '{}') → Expr[source]

打印此表达式求值的结果并传递该值。

示例

>>> df = pl.DataFrame({"foo": [1, 1, 2]})
>>> df.select(pl.col("foo").cum_sum().inspect("value is: {}").alias("bar"))
value is: shape: (3,)
Series: 'foo' [i64]
[
    1
    2
    4
]
shape: (3, 1)
┌─────┐
│ bar │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 4   │
└─────┘

interpolate(method: InterpolationMethod = 'linear') → Expr[source]

使用插值填充空值。

Parameters:

method{‘linear’, ‘nearest’}: 插值方法。

示例

使用线性插值填充空值。

>>> df = pl.DataFrame(
...     {
...         "a": [1, None, 3],
...         "b": [1.0, float("nan"), 3.0],
...     }
... )
>>> df.select(pl.all().interpolate())
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 1.0 ┆ 1.0 │
│ 2.0 ┆ NaN │
│ 3.0 ┆ 3.0 │
└─────┴─────┘

使用最近邻插值填充空值。

>>> df.select(pl.all().interpolate("nearest"))
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 1.0 │
│ 3   ┆ NaN │
│ 3   ┆ 3.0 │
└─────┴─────┘

将数据重新网格化到新网格。

>>> df_original_grid = pl.DataFrame(
...     {
...         "grid_points": [1, 3, 10],
...         "values": [2.0, 6.0, 20.0],
...     }
... )  # Interpolate from this to the new grid
>>> df_new_grid = pl.DataFrame({"grid_points": range(1, 11)})
>>> df_new_grid.join(
...     df_original_grid, on="grid_points", how="left", coalesce=True
... ).with_columns(pl.col("values").interpolate())
shape: (10, 2)
┌─────────────┬────────┐
│ grid_points ┆ values │
│ ---         ┆ ---    │
│ i64         ┆ f64    │
╞═════════════╪════════╡
│ 1           ┆ 2.0    │
│ 2           ┆ 4.0    │
│ 3           ┆ 6.0    │
│ 4           ┆ 8.0    │
│ 5           ┆ 10.0   │
│ 6           ┆ 12.0   │
│ 7           ┆ 14.0   │
│ 8           ┆ 16.0   │
│ 9           ┆ 18.0   │
│ 10          ┆ 20.0   │
└─────────────┴────────┘

interpolate_by(by: IntoExpr) → Expr[source]

使用基于另一列的插值来填充空值。

Parameters:

by: 基于插值的列。

示例

使用线性插值填充空值。

>>> df = pl.DataFrame(
...     {
...         "a": [1, None, None, 3],
...         "b": [1, 2, 7, 8],
...     }
... )
>>> df.with_columns(a_interpolated=pl.col("a").interpolate_by("b"))
shape: (4, 3)
┌──────┬─────┬────────────────┐
│ a    ┆ b   ┆ a_interpolated │
│ ---  ┆ --- ┆ ---            │
│ i64  ┆ i64 ┆ f64            │
╞══════╪═════╪════════════════╡
│ 1    ┆ 1   ┆ 1.0            │
│ null ┆ 2   ┆ 1.285714       │
│ null ┆ 7   ┆ 2.714286       │
│ 3    ┆ 8   ┆ 3.0            │
└──────┴─────┴────────────────┘

is_between( lower_bound: IntoExpr, upper_bound: IntoExpr, closed: ClosedInterval = 'both', ) → Expr[source]

检查此表达式是否在给定的下限和上限之间。

Parameters:

lower_bound: 下限值。接受表达式输入。字符串被解析为列名，其他非表达式输入被解析为字面量。
upper_bound: 上限值。接受表达式输入。字符串被解析为列名，其他非表达式输入被解析为字面量。
closed{‘both’, ‘left’, ‘right’, ‘none’}: 定义区间的哪些边是闭合的（包含的）。

Returns:

Expr: 数据类型 Boolean 的表达式。

注释

如果lower_bound的值大于upper_bound的值，那么结果将为False，因为没有值可以满足条件。

示例

>>> df = pl.DataFrame({"num": [1, 2, 3, 4, 5]})
>>> df.with_columns(pl.col("num").is_between(2, 4).alias("is_between"))
shape: (5, 2)
┌─────┬────────────┐
│ num ┆ is_between │
│ --- ┆ ---        │
│ i64 ┆ bool       │
╞═════╪════════════╡
│ 1   ┆ false      │
│ 2   ┆ true       │
│ 3   ┆ true       │
│ 4   ┆ true       │
│ 5   ┆ false      │
└─────┴────────────┘

使用 closed 参数来包含或排除边界值：

>>> df.with_columns(
...     pl.col("num").is_between(2, 4, closed="left").alias("is_between")
... )
shape: (5, 2)
┌─────┬────────────┐
│ num ┆ is_between │
│ --- ┆ ---        │
│ i64 ┆ bool       │
╞═════╪════════════╡
│ 1   ┆ false      │
│ 2   ┆ true       │
│ 3   ┆ true       │
│ 4   ┆ false      │
│ 5   ┆ false      │
└─────┴────────────┘

你也可以使用字符串以及数值/时间值（注意：确保字符串字面量用lit包裹，以免与列名混淆）：

>>> df = pl.DataFrame({"a": ["a", "b", "c", "d", "e"]})
>>> df.with_columns(
...     pl.col("a")
...     .is_between(pl.lit("a"), pl.lit("c"), closed="both")
...     .alias("is_between")
... )
shape: (5, 2)
┌─────┬────────────┐
│ a   ┆ is_between │
│ --- ┆ ---        │
│ str ┆ bool       │
╞═════╪════════════╡
│ a   ┆ true       │
│ b   ┆ true       │
│ c   ┆ true       │
│ d   ┆ false      │
│ e   ┆ false      │
└─────┴────────────┘

使用列表达式作为下限/上限，与字面值进行比较：

>>> df = pl.DataFrame({"a": [1, 2, 3, 4, 5], "b": [5, 4, 3, 2, 1]})
>>> df.with_columns(
...     pl.lit(3).is_between(pl.col("a"), pl.col("b")).alias("between_ab")
... )
shape: (5, 3)
┌─────┬─────┬────────────┐
│ a   ┆ b   ┆ between_ab │
│ --- ┆ --- ┆ ---        │
│ i64 ┆ i64 ┆ bool       │
╞═════╪═════╪════════════╡
│ 1   ┆ 5   ┆ true       │
│ 2   ┆ 4   ┆ true       │
│ 3   ┆ 3   ┆ true       │
│ 4   ┆ 2   ┆ false      │
│ 5   ┆ 1   ┆ false      │
└─────┴─────┴────────────┘

is_duplicated() → Expr[source]

返回一个布尔掩码，指示重复的值。

Returns:

Expr: 数据类型 Boolean 的表达式。

示例

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

is_finite() → Expr[source]

返回一个布尔系列，指示哪些值是有限的。

Returns:

Expr: 数据类型 Boolean 的表达式。

示例

>>> df = pl.DataFrame(
...     {
...         "A": [1.0, 2],
...         "B": [3.0, float("inf")],
...     }
... )
>>> df.select(pl.all().is_finite())
shape: (2, 2)
┌──────┬───────┐
│ A    ┆ B     │
│ ---  ┆ ---   │
│ bool ┆ bool  │
╞══════╪═══════╡
│ true ┆ true  │
│ true ┆ false │
└──────┴───────┘

is_first_distinct() → Expr[source]

返回一个布尔掩码，指示每个不同值的首次出现。

Returns:

Expr: 数据类型 Boolean 的表达式。

示例

>>> df = pl.DataFrame({"a": [1, 1, 2, 3, 2]})
>>> df.with_columns(pl.col("a").is_first_distinct().alias("first"))
shape: (5, 2)
┌─────┬───────┐
│ a   ┆ first │
│ --- ┆ ---   │
│ i64 ┆ bool  │
╞═════╪═══════╡
│ 1   ┆ true  │
│ 1   ┆ false │
│ 2   ┆ true  │
│ 3   ┆ true  │
│ 2   ┆ false │
└─────┴───────┘

is_in(other: Expr | Collection[Any] | Series) → Expr[source]

检查此表达式的元素是否存在于另一个Series中。

Parameters:

other: 原始类型的系列或序列。

Returns:

Expr: 数据类型 Boolean 的表达式。

示例

>>> df = pl.DataFrame(
...     {"sets": [[1, 2, 3], [1, 2], [9, 10]], "optional_members": [1, 2, 3]}
... )
>>> df.with_columns(contains=pl.col("optional_members").is_in("sets"))
shape: (3, 3)
┌───────────┬──────────────────┬──────────┐
│ sets      ┆ optional_members ┆ contains │
│ ---       ┆ ---              ┆ ---      │
│ list[i64] ┆ i64              ┆ bool     │
╞═══════════╪══════════════════╪══════════╡
│ [1, 2, 3] ┆ 1                ┆ true     │
│ [1, 2]    ┆ 2                ┆ true     │
│ [9, 10]   ┆ 3                ┆ false    │
└───────────┴──────────────────┴──────────┘

is_infinite() → Expr[source]

返回一个布尔系列，指示哪些值是无限的。

Returns:

Expr: 数据类型 Boolean 的表达式。

示例

>>> df = pl.DataFrame(
...     {
...         "A": [1.0, 2],
...         "B": [3.0, float("inf")],
...     }
... )
>>> df.select(pl.all().is_infinite())
shape: (2, 2)
┌───────┬───────┐
│ A     ┆ B     │
│ ---   ┆ ---   │
│ bool  ┆ bool  │
╞═══════╪═══════╡
│ false ┆ false │
│ false ┆ true  │
└───────┴───────┘

is_last_distinct() → Expr[source]

返回一个布尔掩码，指示每个不同值的最后一次出现。

Returns:

Expr: 数据类型 Boolean 的表达式。

示例

>>> df = pl.DataFrame({"a": [1, 1, 2, 3, 2]})
>>> df.with_columns(pl.col("a").is_last_distinct().alias("last"))
shape: (5, 2)
┌─────┬───────┐
│ a   ┆ last  │
│ --- ┆ ---   │
│ i64 ┆ bool  │
╞═════╪═══════╡
│ 1   ┆ false │
│ 1   ┆ true  │
│ 2   ┆ false │
│ 3   ┆ true  │
│ 2   ┆ true  │
└─────┴───────┘

is_nan() → Expr[source]

返回一个布尔系列，指示哪些值是NaN。

注释

浮点数 NaN（非数字）不应与表示为 Null/None 的缺失数据混淆。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 1, 5],
...         "b": [1.0, 2.0, float("nan"), 1.0, 5.0],
...     }
... )
>>> df.with_columns(pl.col(pl.Float64).is_nan().name.suffix("_isnan"))
shape: (5, 3)
┌──────┬─────┬─────────┐
│ a    ┆ b   ┆ b_isnan │
│ ---  ┆ --- ┆ ---     │
│ i64  ┆ f64 ┆ bool    │
╞══════╪═════╪═════════╡
│ 1    ┆ 1.0 ┆ false   │
│ 2    ┆ 2.0 ┆ false   │
│ null ┆ NaN ┆ true    │
│ 1    ┆ 1.0 ┆ false   │
│ 5    ┆ 5.0 ┆ false   │
└──────┴─────┴─────────┘

is_not_nan() → Expr[source]

返回一个布尔系列，指示哪些值不是NaN。

注释

浮点数 NaN（非数字）不应与表示为 Null/None 的缺失数据混淆。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 1, 5],
...         "b": [1.0, 2.0, float("nan"), 1.0, 5.0],
...     }
... )
>>> df.with_columns(pl.col(pl.Float64).is_not_nan().name.suffix("_is_not_nan"))
shape: (5, 3)
┌──────┬─────┬──────────────┐
│ a    ┆ b   ┆ b_is_not_nan │
│ ---  ┆ --- ┆ ---          │
│ i64  ┆ f64 ┆ bool         │
╞══════╪═════╪══════════════╡
│ 1    ┆ 1.0 ┆ true         │
│ 2    ┆ 2.0 ┆ true         │
│ null ┆ NaN ┆ false        │
│ 1    ┆ 1.0 ┆ true         │
│ 5    ┆ 5.0 ┆ true         │
└──────┴─────┴──────────────┘

is_not_null() → Expr[source]

返回一个布尔系列，指示哪些值不为空。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 1, 5],
...         "b": [1.0, 2.0, float("nan"), 1.0, 5.0],
...     }
... )
>>> df.with_columns(
...     pl.all().is_not_null().name.suffix("_not_null")  # nan != null
... )
shape: (5, 4)
┌──────┬─────┬────────────┬────────────┐
│ a    ┆ b   ┆ a_not_null ┆ b_not_null │
│ ---  ┆ --- ┆ ---        ┆ ---        │
│ i64  ┆ f64 ┆ bool       ┆ bool       │
╞══════╪═════╪════════════╪════════════╡
│ 1    ┆ 1.0 ┆ true       ┆ true       │
│ 2    ┆ 2.0 ┆ true       ┆ true       │
│ null ┆ NaN ┆ false      ┆ true       │
│ 1    ┆ 1.0 ┆ true       ┆ true       │
│ 5    ┆ 5.0 ┆ true       ┆ true       │
└──────┴─────┴────────────┴────────────┘

is_null() → Expr[source]

返回一个布尔系列，指示哪些值为空。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 1, 5],
...         "b": [1.0, 2.0, float("nan"), 1.0, 5.0],
...     }
... )
>>> df.with_columns(pl.all().is_null().name.suffix("_isnull"))  # nan != null
shape: (5, 4)
┌──────┬─────┬──────────┬──────────┐
│ a    ┆ b   ┆ a_isnull ┆ b_isnull │
│ ---  ┆ --- ┆ ---      ┆ ---      │
│ i64  ┆ f64 ┆ bool     ┆ bool     │
╞══════╪═════╪══════════╪══════════╡
│ 1    ┆ 1.0 ┆ false    ┆ false    │
│ 2    ┆ 2.0 ┆ false    ┆ false    │
│ null ┆ NaN ┆ true     ┆ false    │
│ 1    ┆ 1.0 ┆ false    ┆ false    │
│ 5    ┆ 5.0 ┆ false    ┆ false    │
└──────┴─────┴──────────┴──────────┘

is_unique() → Expr[source]

获取唯一值的掩码。

示例

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

kurtosis(*, fisher: bool = True, bias: bool = True) → Expr[source]

计算数据集的峰度（Fisher 或 Pearson）。

峰度是第四中心矩除以方差的平方。如果使用费舍尔定义，则从结果中减去3.0，以使正态分布的峰度为0.0。如果bias为False，则使用k统计量计算峰度，以消除来自有偏矩估计器的偏差。

有关更多信息，请参阅 scipy.stats

Parameters:

fisherbool, optional: 如果为True，则使用Fisher的定义（正常 ==> 0.0）。如果为False，则使用Pearson的定义（正常 ==> 3.0）。
biasbool, optional: 如果为False，则计算会针对统计偏差进行校正。

示例

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

last() → Expr[source]

获取最后一个值。

示例

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

le(other: Any) → Expr[source]

方法等同于“小于或等于”运算符 expr <= other。

Parameters:

other: 要与字面量或表达式值进行比较。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [5.0, 4.0, float("nan"), 0.5],
...         "y": [5.0, 3.5, float("nan"), 2.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").le(pl.col("y")).alias("x <= y"),
... )
shape: (4, 3)
┌─────┬─────┬────────┐
│ x   ┆ y   ┆ x <= y │
│ --- ┆ --- ┆ ---    │
│ f64 ┆ f64 ┆ bool   │
╞═════╪═════╪════════╡
│ 5.0 ┆ 5.0 ┆ true   │
│ 4.0 ┆ 3.5 ┆ false  │
│ NaN ┆ NaN ┆ true   │
│ 0.5 ┆ 2.0 ┆ true   │
└─────┴─────┴────────┘

len() → Expr[source]

返回列中元素的数量。

空值计入总数。

Returns:

Expr: 数据类型 UInt32 的表达式。

另请参阅

count

示例

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

limit(n: int | Expr = 10) → Expr[source]

获取前 n 行（Expr.head() 的别名）。

Parameters:

n: 返回的行数。

示例

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

log(base: float = 2.718281828459045) → Expr[source]

计算给定底数的对数。

Parameters:

base: 给定基数，默认为 e

示例

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

log10() → Expr[source]

计算输入数组的以10为底的对数，逐元素进行。

示例

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

log1p() → Expr[source]

计算每个元素加一后的自然对数。

这计算了 log(1 + x)，但对于接近零的 x 在数值上更稳定。

示例

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

lower_bound() → Expr[source]

计算下限。

返回一个单位Series，其值为该表达式dtype可能的最低值。

示例

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

lt(other: Any) → Expr[source]

方法等同于“小于”运算符 expr < other。

Parameters:

other: 要与字面量或表达式值进行比较。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 3.0],
...         "y": [2.0, 2.0, float("nan"), 4.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").lt(pl.col("y")).alias("x < y"),
... )
shape: (4, 3)
┌─────┬─────┬───────┐
│ x   ┆ y   ┆ x < y │
│ --- ┆ --- ┆ ---   │
│ f64 ┆ f64 ┆ bool  │
╞═════╪═════╪═══════╡
│ 1.0 ┆ 2.0 ┆ true  │
│ 2.0 ┆ 2.0 ┆ false │
│ NaN ┆ NaN ┆ false │
│ 3.0 ┆ 4.0 ┆ true  │
└─────┴─────┴───────┘

map_batches( function: Callable[[Series], Series | Any], return_dtype: PolarsDataType | None = None, *, agg_list: bool = False, is_elementwise: bool = False, returns_scalar: bool = False, ) → Expr[source]

对整个Series或Series序列应用自定义的python函数。

此自定义函数的输出假定为Series，或NumPy数组（在这种情况下将自动转换为Series），或将被转换为Series的标量。如果结果是标量并且您希望它保持为标量，请传入returns_scalar=True。如果您希望对单个值逐元素应用自定义函数，请参阅map_elements()。map函数的合理用例是使用第三方库转换表达式表示的值。

Parameters:

function: 要应用的Lambda/函数。
return_dtype: 输出Series的数据类型。如果未设置，将根据函数返回的第一个非空值推断数据类型。
agg_list: 在应用函数之前，将表达式的值聚合到一个列表中。此参数仅在分组上下文中有效。该函数将在分组列表上仅调用一次，而不是每个组调用一次。
is_elementwise: 如果设置为true，这可以在流式引擎中运行，但可能在分组时产生不正确的结果。请确保你知道你在做什么！
returns_scalar: 如果函数返回一个标量，默认情况下它会被包装在输出中的一个列表中，因为假设是函数总是返回类似Series的内容。如果你想保持结果为标量，请将此参数设置为True。

警告

如果未提供return_dtype，可能会导致意外结果。我们允许这种情况，但这被视为用户查询中的错误。

另请参阅

map_elements
replace

示例

>>> df = pl.DataFrame(
...     {
...         "sine": [0.0, 1.0, 0.0, -1.0],
...         "cosine": [1.0, 0.0, -1.0, 0.0],
...     }
... )
>>> df.select(pl.all().map_batches(lambda x: x.to_numpy().argmax()))
shape: (1, 2)
┌──────┬────────┐
│ sine ┆ cosine │
│ ---  ┆ ---    │
│ i64  ┆ i64    │
╞══════╪════════╡
│ 1    ┆ 0      │
└──────┴────────┘

在分组上下文中，如果正确使用agg_list参数，可以提高性能。以下示例将agg_list设置为False，这会导致函数在每个组中应用一次。函数的输入是一个类型为Int64的Series。这样效率较低。

>>> df = pl.DataFrame(
...     {
...         "a": [0, 1, 0, 1],
...         "b": [1, 2, 3, 4],
...     }
... )
>>> df.group_by("a").agg(
...     pl.col("b").map_batches(lambda x: x + 2, agg_list=False)
... )  
shape: (2, 2)
┌─────┬───────────┐
│ a   ┆ b         │
│ --- ┆ ---       │
│ i64 ┆ list[i64] │
╞═════╪═══════════╡
│ 1   ┆ [4, 6]    │
│ 0   ┆ [3, 5]    │
└─────┴───────────┘

使用 agg_list=True 会更高效。在这个例子中，函数的输入是一个类型为 List(Int64) 的 Series。

>>> df.group_by("a").agg(
...     pl.col("b").map_batches(
...         lambda x: x.list.eval(pl.element() + 2), agg_list=True
...     )
... )  
shape: (2, 2)
┌─────┬───────────┐
│ a   ┆ b         │
│ --- ┆ ---       │
│ i64 ┆ list[i64] │
╞═════╪═══════════╡
│ 0   ┆ [3, 5]    │
│ 1   ┆ [4, 6]    │
└─────┴───────────┘

这是一个返回标量的函数示例，我们希望它保持为标量：

>>> df = pl.DataFrame(
...     {
...         "a": [0, 1, 0, 1],
...         "b": [1, 2, 3, 4],
...     }
... )
>>> df.group_by("a").agg(
...     pl.col("b").map_batches(lambda x: x.max(), returns_scalar=True)
... )  
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 4   │
│ 0   ┆ 3   │
└─────┴─────┘

通过创建一个struct并在函数调用中引用其字段来调用一个接受多个参数的函数。

>>> df = pl.DataFrame(
...     {
...         "a": [5, 1, 0, 3],
...         "b": [4, 2, 3, 4],
...     }
... )
>>> df.with_columns(
...     a_times_b=pl.struct("a", "b").map_batches(
...         lambda x: np.multiply(x.struct.field("a"), x.struct.field("b"))
...     )
... )
shape: (4, 3)
┌─────┬─────┬───────────┐
│ a   ┆ b   ┆ a_times_b │
│ --- ┆ --- ┆ ---       │
│ i64 ┆ i64 ┆ i64       │
╞═════╪═════╪═══════════╡
│ 5   ┆ 4   ┆ 20        │
│ 1   ┆ 2   ┆ 2         │
│ 0   ┆ 3   ┆ 0         │
│ 3   ┆ 4   ┆ 12        │
└─────┴─────┴───────────┘

map_elements( function: Callable[[Any], Any], return_dtype: PolarsDataType | None = None, *, skip_nulls: bool = True, pass_name: bool = False, strategy: MapElementsStrategy = 'thread_local', returns_scalar: bool = False, ) → Expr[source]

将自定义/用户定义的函数（UDF）映射到列的每个元素。

警告

此方法比原生表达式API慢得多。只有在无法以其他方式实现逻辑时才使用它。

假设函数是：x ↦ sqrt(x):

对于映射系列的元素，考虑： pl.col("col_name").sqrt()。
对于映射列表的内部元素，考虑： pl.col("col_name").list.eval(pl.element().sqrt())。
对于映射结构体字段的元素，考虑： pl.col("col_name").struct.field("field_name").sqrt()。

如果你想替换原始列或字段，考虑使用 .with_columns 和 .with_fields。

UDF 应用于列的每个元素。请注意，在 GroupBy 上下文中，列将被预先聚合，因此每个元素本身将是一个 Series。因此，根据上下文，function 的要求有所不同：

Selection
期望 function 的类型为 Callable[[Any], Any]。将 Python 函数应用于列中的每个单独值。
GroupBy
期望 function 的类型为 Callable[[Series], Any]。对于每个组，将 Python 函数应用于与该组对应的列切片。

Parameters:

function

用于映射的Lambda/函数。

return_dtype

输出Series的数据类型。如果未设置，将根据函数返回的第一个非空值推断数据类型。

skip_nulls

不要对包含空值的值应用函数（这样更快）。

pass_name

将Series名称传递给自定义函数（这更昂贵）。

returns_scalar

如果传递的函数执行了归约操作（例如求和、最小值等），必须告知Polars，否则模式可能会不正确。

strategy{‘thread_local’, ‘threading’}

使用的线程策略。

‘thread_local’：在单个线程上运行python函数。
‘threading’：在单独的线程上运行python函数。请谨慎使用，因为这可能会降低性能。如果每个元素的工作量很大并且python函数释放了GIL（例如通过调用c函数），这可能只会加速你的代码。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

警告

如果未提供return_dtype，可能会导致意外结果。我们允许这种情况，但这被视为用户查询中的错误。

注释

强烈不建议使用map_elements，因为你实际上是在运行Python的“for”循环，这将非常慢。在可能的情况下，你应该优先使用原生表达式API以实现最佳性能。
如果你的函数计算成本高，并且你不希望它在给定输入时被多次调用，考虑对其应用@lru_cache装饰器。如果你的数据适合，你可能会实现显著的加速。
在这里，使用over的窗口函数应用被视为GroupBy上下文，因此可以使用map_elements来映射窗口组上的函数。

示例

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

该函数应用于列 'a' 的每个元素：

>>> df.with_columns(  
...     pl.col("a")
...     .map_elements(lambda x: x * 2, return_dtype=pl.Int64)
...     .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         │
└─────┴─────┴───────────┘

提示：最好使用表达式来实现这一点：

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

在 GroupBy 上下文中，列的每个元素本身都是一个 Series：

>>> (
...     df.lazy().group_by("b").agg(pl.col("a")).collect()
... )  
shape: (3, 2)
┌─────┬───────────┐
│ b   ┆ a         │
│ --- ┆ ---       │
│ str ┆ list[i64] │
╞═════╪═══════════╡
│ a   ┆ [1]       │
│ b   ┆ [2]       │
│ c   ┆ [3, 1]    │
└─────┴───────────┘

因此，从用户的角度来看，该函数是按组应用的：

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

提示：再次强调，最好使用表达式来实现这一点：

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

使用 over 的窗口函数应用将表现为 GroupBy 上下文，您的函数将接收单独的窗口组：

>>> df = pl.DataFrame(
...     {
...         "key": ["x", "x", "y", "x", "y", "z"],
...         "val": [1, 1, 1, 1, 1, 1],
...     }
... )
>>> df.with_columns(
...     scaled=pl.col("val")
...     .map_elements(lambda s: s * len(s), return_dtype=pl.List(pl.Int64))
...     .over("key"),
... ).sort("key")
shape: (6, 3)
┌─────┬─────┬────────┐
│ key ┆ val ┆ scaled │
│ --- ┆ --- ┆ ---    │
│ str ┆ i64 ┆ i64    │
╞═════╪═════╪════════╡
│ x   ┆ 1   ┆ 3      │
│ x   ┆ 1   ┆ 3      │
│ x   ┆ 1   ┆ 3      │
│ y   ┆ 1   ┆ 2      │
│ y   ┆ 1   ┆ 2      │
│ z   ┆ 1   ┆ 1      │
└─────┴─────┴────────┘

请注意，这个函数也最好以原生方式实现：

>>> df.with_columns(
...     scaled=(pl.col("val") * pl.col("val").count()).over("key"),
... ).sort("key")  

max() → Expr[source]

获取最大值。

示例

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

mean() → Expr[source]

获取平均值。

示例

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

median() → Expr[source]

使用线性插值获取中位数值。

示例

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

min() → Expr[source]

获取最小值。

示例

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

mod(other: Any) → Expr[source]

方法等同于模运算符 expr % other。

Parameters:

other: 数值字面量或表达式值。

示例

>>> df = pl.DataFrame({"x": [0, 1, 2, 3, 4]})
>>> df.with_columns(pl.col("x").mod(2).alias("x%2"))
shape: (5, 2)
┌─────┬─────┐
│ x   ┆ x%2 │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 0   ┆ 0   │
│ 1   ┆ 1   │
│ 2   ┆ 0   │
│ 3   ┆ 1   │
│ 4   ┆ 0   │
└─────┴─────┘

mode() → Expr[source]

计算出现频率最高的值。

可以返回多个值。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 1, 2, 3],
...         "b": [1, 1, 2, 2],
...     }
... )
>>> df.select(pl.all().mode().first())  
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 1   │
└─────┴─────┘

mul(other: Any) → Expr[source]

方法等同于乘法运算符 expr * other。

Parameters:

other: 数值字面量或表达式值。

示例

>>> df = pl.DataFrame({"x": [1, 2, 4, 8, 16]})
>>> df.with_columns(
...     pl.col("x").mul(2).alias("x*2"),
...     pl.col("x").mul(pl.col("x").log(2)).alias("x * xlog2"),
... )
shape: (5, 3)
┌─────┬─────┬───────────┐
│ x   ┆ x*2 ┆ x * xlog2 │
│ --- ┆ --- ┆ ---       │
│ i64 ┆ i64 ┆ f64       │
╞═════╪═════╪═══════════╡
│ 1   ┆ 2   ┆ 0.0       │
│ 2   ┆ 4   ┆ 2.0       │
│ 4   ┆ 8   ┆ 8.0       │
│ 8   ┆ 16  ┆ 24.0      │
│ 16  ┆ 32  ┆ 64.0      │
└─────┴─────┴───────────┘

n_unique() → Expr[source]

计算唯一值。

注释

null 在此操作中被视为一个唯一值。

示例

>>> df = pl.DataFrame({"x": [1, 1, 2, 2, 3], "y": [1, 1, 1, None, None]})
>>> df.select(
...     x_unique=pl.col("x").n_unique(),
...     y_unique=pl.col("y").n_unique(),
... )
shape: (1, 2)
┌──────────┬──────────┐
│ x_unique ┆ y_unique │
│ ---      ┆ ---      │
│ u32      ┆ u32      │
╞══════════╪══════════╡
│ 3        ┆ 2        │
└──────────┴──────────┘

nan_max() → Expr[source]

获取最大值，但传播/污染遇到的NaN值。

这与numpy的nanmax不同，因为numpy默认传播NaN值，而polars默认忽略它们。

示例

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

nan_min() → Expr[source]

获取最小值，但传播/污染遇到的NaN值。

这与numpy的nanmax不同，因为numpy默认传播NaN值，而polars默认忽略它们。

示例

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

ne(other: Any) → Expr[source]

方法等同于不等式运算符 expr != other。

Parameters:

other: 要与字面量或表达式值进行比较。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 4.0],
...         "y": [2.0, 2.0, float("nan"), 4.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").ne(pl.col("y")).alias("x != y"),
... )
shape: (4, 3)
┌─────┬─────┬────────┐
│ x   ┆ y   ┆ x != y │
│ --- ┆ --- ┆ ---    │
│ f64 ┆ f64 ┆ bool   │
╞═════╪═════╪════════╡
│ 1.0 ┆ 2.0 ┆ true   │
│ 2.0 ┆ 2.0 ┆ false  │
│ NaN ┆ NaN ┆ false  │
│ 4.0 ┆ 4.0 ┆ false  │
└─────┴─────┴────────┘

ne_missing(other: Any) → Expr[source]

等价于等式运算符 expr != other 的方法，其中 None == None。

这与默认的 ne 不同，在默认情况下，空值会被传播。

Parameters:

other: 要与字面量或表达式值进行比较。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 4.0, None, None],
...         "y": [2.0, 2.0, float("nan"), 4.0, 5.0, None],
...     }
... )
>>> df.with_columns(
...     pl.col("x").ne(pl.col("y")).alias("x ne y"),
...     pl.col("x").ne_missing(pl.col("y")).alias("x ne_missing y"),
... )
shape: (6, 4)
┌──────┬──────┬────────┬────────────────┐
│ x    ┆ y    ┆ x ne y ┆ x ne_missing y │
│ ---  ┆ ---  ┆ ---    ┆ ---            │
│ f64  ┆ f64  ┆ bool   ┆ bool           │
╞══════╪══════╪════════╪════════════════╡
│ 1.0  ┆ 2.0  ┆ true   ┆ true           │
│ 2.0  ┆ 2.0  ┆ false  ┆ false          │
│ NaN  ┆ NaN  ┆ false  ┆ false          │
│ 4.0  ┆ 4.0  ┆ false  ┆ false          │
│ null ┆ 5.0  ┆ null   ┆ true           │
│ null ┆ null ┆ null   ┆ false          │
└──────┴──────┴────────┴────────────────┘

neg() → Expr[source]

一元减号运算符的方法等效于 -expr。

示例

>>> df = pl.DataFrame({"a": [-1, 0, 2, None]})
>>> df.with_columns(pl.col("a").neg())
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ 1    │
│ 0    │
│ -2   │
│ null │
└──────┘

not_() → Expr[source]

否定一个布尔表达式。

示例

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

null_count() → Expr[source]

计算空值。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [None, 1, None],
...         "b": [10, None, 300],
...         "c": [350, 650, 850],
...     }
... )
>>> df.select(pl.all().null_count())
shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ u32 ┆ u32 ┆ u32 │
╞═════╪═════╪═════╡
│ 2   ┆ 1   ┆ 0   │
└─────┴─────┴─────┘

or_(*others: Any) → Expr[source]

方法等效于按位“或”运算符 expr | other | ...。

Parameters:

*others: 要评估/组合的一个或多个整数或布尔表达式。

示例

>>> df = pl.DataFrame(
...     data={
...         "x": [5, 6, 7, 4, 8],
...         "y": [1.5, 2.5, 1.0, 4.0, -5.75],
...         "z": [-9, 2, -1, 4, 8],
...     }
... )
>>> df.select(
...     (pl.col("x") == pl.col("y"))
...     .or_(
...         pl.col("x") == pl.col("y"),
...         pl.col("y") == pl.col("z"),
...         pl.col("y").cast(int) == pl.col("z"),
...     )
...     .alias("any")
... )
shape: (5, 1)
┌───────┐
│ any   │
│ ---   │
│ bool  │
╞═══════╡
│ false │
│ true  │
│ false │
│ true  │
│ false │
└───────┘

over( partition_by: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr, order_by: IntoExpr | Iterable[IntoExpr] | None = None, mapping_strategy: WindowMappingStrategy = 'group_to_rows', ) → Expr[source]

计算给定组上的表达式。

这个表达式类似于执行一个分组聚合操作并将结果连接回原始的DataFrame。

结果类似于窗口函数在PostgreSQL中的工作方式。

Parameters:

partition_by

用于分组的列。接受表达式输入。字符串被解析为列名。

*more_exprs

用于分组的额外列，指定为位置参数。

order_by:

根据传递给order_by的表达式结果，对窗口函数/聚合进行排序。

mapping_strategy: {‘group_to_rows’, ‘join’, ‘explode’}

group_to_rows
如果聚合结果包含多个值，将它们分配回它们在DataFrame中的位置。这只有在分组在聚合前后产生相同元素的情况下才能完成。
join
将组作为‘List’加入到行位置。警告：这可能会占用大量内存。
explode
将分组数据展开为新的行，类似于group_by + agg + explode的结果。如果分组不是窗口操作的一部分，则需要对给定的分组进行排序，否则结果将没有意义。此操作会改变行数。

示例

传递列的名称以计算该列上的表达式。

>>> df = pl.DataFrame(
...     {
...         "a": ["a", "a", "b", "b", "b"],
...         "b": [1, 2, 3, 5, 3],
...         "c": [5, 4, 3, 2, 1],
...     }
... )
>>> df.with_columns(c_max=pl.col("c").max().over("a"))
shape: (5, 4)
┌─────┬─────┬─────┬───────┐
│ a   ┆ b   ┆ c   ┆ c_max │
│ --- ┆ --- ┆ --- ┆ ---   │
│ str ┆ i64 ┆ i64 ┆ i64   │
╞═════╪═════╪═════╪═══════╡
│ a   ┆ 1   ┆ 5   ┆ 5     │
│ a   ┆ 2   ┆ 4   ┆ 5     │
│ b   ┆ 3   ┆ 3   ┆ 3     │
│ b   ┆ 5   ┆ 2   ┆ 3     │
│ b   ┆ 3   ┆ 1   ┆ 3     │
└─────┴─────┴─────┴───────┘

表达式输入也被支持。

>>> df.with_columns(c_max=pl.col("c").max().over(pl.col("b") // 2))
shape: (5, 4)
┌─────┬─────┬─────┬───────┐
│ a   ┆ b   ┆ c   ┆ c_max │
│ --- ┆ --- ┆ --- ┆ ---   │
│ str ┆ i64 ┆ i64 ┆ i64   │
╞═════╪═════╪═════╪═══════╡
│ a   ┆ 1   ┆ 5   ┆ 5     │
│ a   ┆ 2   ┆ 4   ┆ 4     │
│ b   ┆ 3   ┆ 3   ┆ 4     │
│ b   ┆ 5   ┆ 2   ┆ 2     │
│ b   ┆ 3   ┆ 1   ┆ 4     │
└─────┴─────┴─────┴───────┘

通过传递多个列名或表达式来按多列分组。

>>> df.with_columns(c_min=pl.col("c").min().over("a", pl.col("b") % 2))
shape: (5, 4)
┌─────┬─────┬─────┬───────┐
│ a   ┆ b   ┆ c   ┆ c_min │
│ --- ┆ --- ┆ --- ┆ ---   │
│ str ┆ i64 ┆ i64 ┆ i64   │
╞═════╪═════╪═════╪═══════╡
│ a   ┆ 1   ┆ 5   ┆ 5     │
│ a   ┆ 2   ┆ 4   ┆ 4     │
│ b   ┆ 3   ┆ 3   ┆ 1     │
│ b   ┆ 5   ┆ 2   ┆ 1     │
│ b   ┆ 3   ┆ 1   ┆ 1     │
└─────┴─────┴─────┴───────┘

你也可以使用非元素表达式与over。默认情况下，它们会按行顺序进行评估，但你可以使用order_by指定不同的顺序。

>>> from datetime import date
>>> df = pl.DataFrame(
...     {
...         "store_id": ["a", "a", "b", "b"],
...         "date": [
...             date(2024, 9, 18),
...             date(2024, 9, 17),
...             date(2024, 9, 18),
...             date(2024, 9, 16),
...         ],
...         "sales": [7, 9, 8, 10],
...     }
... )
>>> df.with_columns(
...     cumulative_sales=pl.col("sales")
...     .cum_sum()
...     .over("store_id", order_by="date")
... )
shape: (4, 4)
┌──────────┬────────────┬───────┬──────────────────┐
│ store_id ┆ date       ┆ sales ┆ cumulative_sales │
│ ---      ┆ ---        ┆ ---   ┆ ---              │
│ str      ┆ date       ┆ i64   ┆ i64              │
╞══════════╪════════════╪═══════╪══════════════════╡
│ a        ┆ 2024-09-18 ┆ 7     ┆ 16               │
│ a        ┆ 2024-09-17 ┆ 9     ┆ 9                │
│ b        ┆ 2024-09-18 ┆ 8     ┆ 18               │
│ b        ┆ 2024-09-16 ┆ 10    ┆ 10               │
└──────────┴────────────┴───────┴──────────────────┘

如果您不需要保留组的顺序，那么性能更好的选择是使用mapping_strategy='explode' - 但请注意，仅在select语句中使用此选项，而不是在with_columns中使用。

>>> window = {
...     "partition_by": "store_id",
...     "order_by": "date",
...     "mapping_strategy": "explode",
... }
>>> df.select(
...     pl.all().over(**window),
...     cumulative_sales=pl.col("sales").cum_sum().over(**window),
... )
shape: (4, 4)
┌──────────┬────────────┬───────┬──────────────────┐
│ store_id ┆ date       ┆ sales ┆ cumulative_sales │
│ ---      ┆ ---        ┆ ---   ┆ ---              │
│ str      ┆ date       ┆ i64   ┆ i64              │
╞══════════╪════════════╪═══════╪══════════════════╡
│ a        ┆ 2024-09-17 ┆ 9     ┆ 9                │
│ a        ┆ 2024-09-18 ┆ 7     ┆ 16               │
│ b        ┆ 2024-09-16 ┆ 10    ┆ 10               │
│ b        ┆ 2024-09-18 ┆ 8     ┆ 18               │
└──────────┴────────────┴───────┴──────────────────┘

pct_change(n: int | IntoExprColumn = 1) → Expr[source]

计算值之间的百分比变化。

当前元素与至少n个周期之前的最远非空元素之间的百分比变化（以分数表示）。

默认情况下计算与前一行的变化。

Parameters:

n: 用于形成百分比变化的周期偏移。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [10, 11, 12, None, 12],
...     }
... )
>>> df.with_columns(pl.col("a").pct_change().alias("pct_change"))
shape: (5, 2)
┌──────┬────────────┐
│ a    ┆ pct_change │
│ ---  ┆ ---        │
│ i64  ┆ f64        │
╞══════╪════════════╡
│ 10   ┆ null       │
│ 11   ┆ 0.1        │
│ 12   ┆ 0.090909   │
│ null ┆ 0.0        │
│ 12   ┆ 0.0        │
└──────┴────────────┘

peak_max() → Expr[source]

获取局部最大峰的布尔掩码。

示例

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

peak_min() → Expr[source]

获取局部最小峰的布尔掩码。

示例

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

pipe(

function: Callable[Concatenate[Expr, P], T],

*args: P.args,

**kwargs: P.kwargs,

) → T[source]

提供了一种结构化的方式来应用一系列用户定义的函数（UDFs）。

Parameters:

function: 可调用的；将接收表达式作为第一个参数，后面跟随任何给定的args/kwargs。
*args: 传递给UDF的参数。
**kwargs: 传递给UDF的关键字参数。

示例

>>> def extract_number(expr: pl.Expr) -> pl.Expr:
...     """Extract the digits from a string."""
...     return expr.str.extract(r"\d+", 0).cast(pl.Int64)
>>>
>>> def scale_negative_even(expr: pl.Expr, *, n: int = 1) -> pl.Expr:
...     """Set even numbers negative, and scale by a user-supplied value."""
...     expr = pl.when(expr % 2 == 0).then(-expr).otherwise(expr)
...     return expr * n
>>>
>>> df = pl.DataFrame({"val": ["a: 1", "b: 2", "c: 3", "d: 4"]})
>>> df.with_columns(
...     udfs=(
...         pl.col("val").pipe(extract_number).pipe(scale_negative_even, n=5)
...     ),
... )
shape: (4, 2)
┌──────┬──────┐
│ val  ┆ udfs │
│ ---  ┆ ---  │
│ str  ┆ i64  │
╞══════╪══════╡
│ a: 1 ┆ 5    │
│ b: 2 ┆ -10  │
│ c: 3 ┆ 15   │
│ d: 4 ┆ -20  │
└──────┴──────┘

pow(exponent: IntoExprColumn | int | float) → Expr[source]

方法等同于指数运算符 expr ** exponent。

如果指数是浮点数，结果遵循指数的dtype。否则，它遵循基数的dtype。

Parameters:

exponent: 数值字面量或表达式指数值。

示例

>>> df = pl.DataFrame({"x": [1, 2, 4, 8]})
>>> df.with_columns(
...     pl.col("x").pow(3).alias("cube"),
...     pl.col("x").pow(pl.col("x").log(2)).alias("x ** xlog2"),
... )
shape: (4, 3)
┌─────┬──────┬────────────┐
│ x   ┆ cube ┆ x ** xlog2 │
│ --- ┆ ---  ┆ ---        │
│ i64 ┆ i64  ┆ f64        │
╞═════╪══════╪════════════╡
│ 1   ┆ 1    ┆ 1.0        │
│ 2   ┆ 8    ┆ 2.0        │
│ 4   ┆ 64   ┆ 16.0       │
│ 8   ┆ 512  ┆ 512.0      │
└─────┴──────┴────────────┘

将一个整数提升为正整数结果仍为整数 - 为了提升为负整数，你可以先将基数或指数转换为浮点数：

>>> df.with_columns(
...     x_squared=pl.col("x").pow(2),
...     x_inverse=pl.col("x").pow(-1.0),
... )
shape: (4, 3)
┌─────┬───────────┬───────────┐
│ x   ┆ x_squared ┆ x_inverse │
│ --- ┆ ---       ┆ ---       │
│ i64 ┆ i64       ┆ f64       │
╞═════╪═══════════╪═══════════╡
│ 1   ┆ 1         ┆ 1.0       │
│ 2   ┆ 4         ┆ 0.5       │
│ 4   ┆ 16        ┆ 0.25      │
│ 8   ┆ 64        ┆ 0.125     │
└─────┴───────────┴───────────┘

product() → Expr[source]

计算表达式的乘积。

示例

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

qcut( quantiles: Sequence[float] | int, *, labels: Sequence[str] | None = None, left_closed: bool = False, allow_duplicates: bool = False, include_breaks: bool = False, ) → Expr[source]

将连续值根据其分位数分箱到离散类别中。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

Parameters:

quantiles: 要么是0到1之间的分位数概率列表，要么是确定具有均匀概率的箱数的正整数。
labels: 类别的名称。标签的数量必须与类别的数量相等。
left_closed: 将间隔设置为左闭而不是右闭。
allow_duplicates: 如果设置为True，结果中的重复分位数将被删除，而不是引发DuplicateError。即使概率是唯一的，这种情况也可能发生，具体取决于数据。
include_breaks: 包含一个列，显示每个观察值所属区间的右端点。这将把输出的数据类型从Categorical更改为Struct。

Returns:

Expr: 如果include_breaks设置为False（默认），则数据类型为Categorical的表达式，否则为数据类型Struct的表达式。

另请参阅

cut

示例

根据预定义的分位数概率将列分为三类。

>>> df = pl.DataFrame({"foo": [-2, -1, 0, 1, 2]})
>>> df.with_columns(
...     pl.col("foo").qcut([0.25, 0.75], labels=["a", "b", "c"]).alias("qcut")
... )
shape: (5, 2)
┌─────┬──────┐
│ foo ┆ qcut │
│ --- ┆ ---  │
│ i64 ┆ cat  │
╞═════╪══════╡
│ -2  ┆ a    │
│ -1  ┆ a    │
│ 0   ┆ b    │
│ 1   ┆ b    │
│ 2   ┆ c    │
└─────┴──────┘

使用均匀分位数概率将列分为两类。

>>> df.with_columns(
...     pl.col("foo")
...     .qcut(2, labels=["low", "high"], left_closed=True)
...     .alias("qcut")
... )
shape: (5, 2)
┌─────┬──────┐
│ foo ┆ qcut │
│ --- ┆ ---  │
│ i64 ┆ cat  │
╞═════╪══════╡
│ -2  ┆ low  │
│ -1  ┆ low  │
│ 0   ┆ high │
│ 1   ┆ high │
│ 2   ┆ high │
└─────┴──────┘

添加类别和断点。

>>> df.with_columns(
...     pl.col("foo").qcut([0.25, 0.75], include_breaks=True).alias("qcut")
... ).unnest("qcut")
shape: (5, 3)
┌─────┬────────────┬────────────┐
│ foo ┆ breakpoint ┆ category   │
│ --- ┆ ---        ┆ ---        │
│ i64 ┆ f64        ┆ cat        │
╞═════╪════════════╪════════════╡
│ -2  ┆ -1.0       ┆ (-inf, -1] │
│ -1  ┆ -1.0       ┆ (-inf, -1] │
│ 0   ┆ 1.0        ┆ (-1, 1]    │
│ 1   ┆ 1.0        ┆ (-1, 1]    │
│ 2   ┆ inf        ┆ (1, inf]   │
└─────┴────────────┴────────────┘

quantile( quantile: float | Expr, interpolation: RollingInterpolationMethod = 'nearest', ) → Expr[source]

获取分位数值。

Parameters:

quantile: 分位数在0.0到1.0之间。
interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’}: 插值方法。

示例

>>> df = pl.DataFrame({"a": [0, 1, 2, 3, 4, 5]})
>>> df.select(pl.col("a").quantile(0.3))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 2.0 │
└─────┘
>>> df.select(pl.col("a").quantile(0.3, interpolation="higher"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 2.0 │
└─────┘
>>> df.select(pl.col("a").quantile(0.3, interpolation="lower"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
└─────┘
>>> df.select(pl.col("a").quantile(0.3, interpolation="midpoint"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.5 │
└─────┘
>>> df.select(pl.col("a").quantile(0.3, interpolation="linear"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.5 │
└─────┘

radians() → Expr[source]

将角度转换为弧度。

Returns:

Expr: 数据类型 Float64 的表达。

示例

>>> df = pl.DataFrame({"a": [-720, -540, -360, -180, 0, 180, 360, 540, 720]})
>>> df.select(pl.col("a").radians())
shape: (9, 1)
┌────────────┐
│ a          │
│ ---        │
│ f64        │
╞════════════╡
│ -12.566371 │
│ -9.424778  │
│ -6.283185  │
│ -3.141593  │
│ 0.0        │
│ 3.141593   │
│ 6.283185   │
│ 9.424778   │
│ 12.566371  │
└────────────┘

rank( method: RankMethod = 'average', *, descending: bool = False, seed: int | None = None, ) → Expr[source]

为数据分配排名，适当处理并列情况。

Parameters:

method{‘average’, ‘min’, ‘max’, ‘dense’, ‘ordinal’, ‘random’}

用于为相同元素分配排名的方法。以下方法可用（默认为‘average’）：

‘average’ : 将分配给所有相同值的排名的平均值分配给每个值。
'min'：将分配给所有相同值的最小排名分配给每个值。（这也被称为“竞争”排名。）
‘max’ : 将分配给所有相同值的最大排名分配给每个值。
‘dense’：类似于‘min’，但下一个最高元素的排名被分配为紧接在那些被分配给并列元素的排名之后。
‘ordinal’ : 所有值都被赋予一个独特的排名，对应于值在Series中出现的顺序。
‘random’ : 类似于‘ordinal’，但对于相同值的排名不依赖于它们在Series中出现的顺序。

descending

按降序排列。

seed

如果 method="random"，使用此作为种子。

示例

‘average’ 方法：

>>> df = pl.DataFrame({"a": [3, 6, 1, 1, 6]})
>>> df.select(pl.col("a").rank())
shape: (5, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 3.0 │
│ 4.5 │
│ 1.5 │
│ 1.5 │
│ 4.5 │
└─────┘

‘ordinal’ 方法：

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

使用‘rank’与‘over’在组内进行排名：

>>> df = pl.DataFrame({"a": [1, 1, 2, 2, 2], "b": [6, 7, 5, 14, 11]})
>>> df.with_columns(pl.col("b").rank().over("a").alias("rank"))
shape: (5, 3)
┌─────┬─────┬──────┐
│ a   ┆ b   ┆ rank │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ i64 ┆ f64  │
╞═════╪═════╪══════╡
│ 1   ┆ 6   ┆ 1.0  │
│ 1   ┆ 7   ┆ 2.0  │
│ 2   ┆ 5   ┆ 1.0  │
│ 2   ┆ 14  ┆ 3.0  │
│ 2   ┆ 11  ┆ 2.0  │
└─────┴─────┴──────┘

rechunk() → Expr[source]

为这个系列创建一个单一的内存块。

示例

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

创建一个包含3个空值的Series，然后附加列a并重新分块

>>> df.select(pl.repeat(None, 3).append(pl.col("a")).rechunk())
shape: (6, 1)
┌────────┐
│ repeat │
│ ---    │
│ i64    │
╞════════╡
│ null   │
│ null   │
│ null   │
│ 1      │
│ 1      │
│ 2      │
└────────┘

register_plugin( *, lib: str, symbol: str, args: list[IntoExpr] | None = None, kwargs: dict[Any, Any] | None = None, is_elementwise: bool = False, input_wildcard_expansion: bool = False, returns_scalar: bool = False, cast_to_supertypes: bool = False, pass_name_to_apply: bool = False, changes_length: bool = False, ) → Expr[source]

注册一个插件函数。

自版本0.20.16起已弃用：请改用polars.plugins.register_plugin_function()。

查看用户指南以获取有关插件的更多信息。

Parameters:

lib: 要加载的库。
symbol: 要加载的函数。
args: 传递给此函数的参数（除了self）。这些参数必须是Expression类型。
kwargs: 非表达式参数。它们必须是可JSON序列化的。
is_elementwise: 如果函数仅对标量进行操作，这将触发快速路径。
input_wildcard_expansion: 扩展表达式作为此函数的输入。
returns_scalar: 如果作为最终聚合运行，则在单位长度上自动展开。这是针对像sum、min、covariance等聚合的情况。
cast_to_supertypes: 将输入数据类型转换为其超类型。
pass_name_to_apply: 如果设置，则在 group_by 操作中传递给函数的 Series 将确保名称已设置。这是每个组的额外堆分配。
changes_length: 例如一个 unique 或一个 slice

警告

此方法已弃用。请改用新的 polars.plugins.register_plugin_function 函数。

这是非常不安全的，因为这将调用由 lib::symbol加载的C函数。

您设置的参数决定了Polars将如何处理该函数。请确保它们是正确的！

reinterpret(*, signed: bool = True) → Expr[source]

将底层位重新解释为有符号/无符号整数。

此操作仅允许用于64位整数。对于较低位的整数，您可以安全地使用该转换操作。

Parameters:

signed: 如果为True，则重新解释为pl.Int64。否则，重新解释为pl.UInt64。

示例

>>> s = pl.Series("a", [1, 1, 2], dtype=pl.UInt64)
>>> df = pl.DataFrame([s])
>>> df.select(
...     [
...         pl.col("a").reinterpret(signed=True).alias("reinterpreted"),
...         pl.col("a").alias("original"),
...     ]
... )
shape: (3, 2)
┌───────────────┬──────────┐
│ reinterpreted ┆ original │
│ ---           ┆ ---      │
│ i64           ┆ u64      │
╞═══════════════╪══════════╡
│ 1             ┆ 1        │
│ 1             ┆ 1        │
│ 2             ┆ 2        │
└───────────────┴──────────┘

repeat_by( by: Series | Expr | str | int, ) → Expr[source]

按照给定表达式中的指定重复此系列中的元素。

重复的元素被扩展成一个List。

Parameters:

by: 确定值将重复频率的数值列。该列将被强制转换为UInt32。提供此数据类型以使强制转换成为无操作。

Returns:

Expr: 数据类型 List 的表达式，其中内部数据类型等于原始数据类型。

示例

>>> df = pl.DataFrame(
...     {
...         "a": ["x", "y", "z"],
...         "n": [1, 2, 3],
...     }
... )
>>> df.select(pl.col("a").repeat_by("n"))
shape: (3, 1)
┌─────────────────┐
│ a               │
│ ---             │
│ list[str]       │
╞═════════════════╡
│ ["x"]           │
│ ["y", "y"]      │
│ ["z", "z", "z"] │
└─────────────────┘

用相同数据类型的其他值替换给定的值。

Parameters:

old: 要替换的值或值的序列。接受表达式输入。序列被解析为Series，其他非表达式输入被解析为字面量。还接受一个值到其替换的映射，作为replace(old=Series(mapping.keys()), new=Series(mapping.values()))的语法糖。
new: 要替换的值或值序列。接受表达式输入。序列被解析为Series，其他非表达式输入被解析为字面量。长度必须与old的长度匹配或长度为1。
default: 将未替换的值设置为此值。默认情况下保留原始值。接受表达式输入。非表达式输入将被解析为字面量。

自版本1.0.0起已弃用：请改用replace_strict()来设置默认值并替换值。
return_dtype: 结果表达式的数据类型。如果设置为None（默认值），则保留原始列的数据类型。

自版本 1.0.0 起已弃用：请改用 replace_strict() 来设置返回数据类型，同时在替换值时，或显式调用 cast() 在输出上。

另请参阅

replace_strict
str.replace

注释

在替换分类值时，必须启用全局字符串缓存。

示例

用一个值替换另一个值。未被替换的值保持不变。

>>> df = pl.DataFrame({"a": [1, 2, 2, 3]})
>>> df.with_columns(replaced=pl.col("a").replace(2, 100))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 1        │
│ 2   ┆ 100      │
│ 2   ┆ 100      │
│ 3   ┆ 3        │
└─────┴──────────┘

通过将序列传递给old和new参数来替换多个值。

>>> df.with_columns(replaced=pl.col("a").replace([2, 3], [100, 200]))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 1        │
│ 2   ┆ 100      │
│ 2   ┆ 100      │
│ 3   ┆ 200      │
└─────┴──────────┘

传递带有替换的映射也作为语法糖支持。

>>> mapping = {2: 100, 3: 200}
>>> df.with_columns(replaced=pl.col("a").replace(mapping))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 1        │
│ 2   ┆ 100      │
│ 2   ┆ 100      │
│ 3   ┆ 200      │
└─────┴──────────┘

当用不同数据类型替换时，原始数据类型保持不变。使用 replace_strict() 来替换并更改返回数据类型。

>>> df = pl.DataFrame({"a": ["x", "y", "z"]})
>>> mapping = {"x": 1, "y": 2, "z": 3}
>>> df.with_columns(replaced=pl.col("a").replace(mapping))
shape: (3, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ str ┆ str      │
╞═════╪══════════╡
│ x   ┆ 1        │
│ y   ┆ 2        │
│ z   ┆ 3        │
└─────┴──────────┘

支持表达式输入。

>>> df = pl.DataFrame({"a": [1, 2, 2, 3], "b": [1.5, 2.5, 5.0, 1.0]})
>>> df.with_columns(
...     replaced=pl.col("a").replace(
...         old=pl.col("a").max(),
...         new=pl.col("b").sum(),
...     )
... )
shape: (4, 3)
┌─────┬─────┬──────────┐
│ a   ┆ b   ┆ replaced │
│ --- ┆ --- ┆ ---      │
│ i64 ┆ f64 ┆ i64      │
╞═════╪═════╪══════════╡
│ 1   ┆ 1.5 ┆ 1        │
│ 2   ┆ 2.5 ┆ 2        │
│ 2   ┆ 5.0 ┆ 2        │
│ 3   ┆ 1.0 ┆ 10       │
└─────┴─────┴──────────┘

用不同的值替换所有值。

Parameters:

old: 要替换的值或值序列。接受表达式输入。序列被解析为Series，其他非表达式输入被解析为字面量。还接受一个值到其替换的映射，作为 replace_all(old=Series(mapping.keys()), new=Series(mapping.values()))的语法糖。
new: 要替换的值或值序列。接受表达式输入。序列被解析为Series，其他非表达式输入被解析为字面量。长度必须与old的长度匹配或长度为1。
default: 将未替换的值设置为此值。如果未指定默认值（默认情况下），如果任何值未被替换，则会引发错误。接受表达式输入。非表达式输入将被解析为字面量。
return_dtype: 结果表达式的数据类型。如果设置为None（默认值），则数据类型将根据其他输入自动确定。

Raises:

InvalidOperationError: 如果原始列中的任何非空值未被替换，且未指定default。

另请参阅

replace
str.replace

注释

在替换分类值时，必须启用全局字符串缓存。

示例

通过将序列传递给old和new参数来替换值。

>>> df = pl.DataFrame({"a": [1, 2, 2, 3]})
>>> df.with_columns(
...     replaced=pl.col("a").replace_strict([1, 2, 3], [100, 200, 300])
... )
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 100      │
│ 2   ┆ 200      │
│ 2   ┆ 200      │
│ 3   ┆ 300      │
└─────┴──────────┘

传递带有替换的映射也作为语法糖支持。

>>> mapping = {1: 100, 2: 200, 3: 300}
>>> df.with_columns(replaced=pl.col("a").replace_strict(mapping))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 100      │
│ 2   ┆ 200      │
│ 2   ┆ 200      │
│ 3   ┆ 300      │
└─────┴──────────┘

默认情况下，如果任何非空值未被替换，则会引发错误。指定一个默认值以设置所有未匹配的值。

>>> mapping = {2: 200, 3: 300}
>>> df.with_columns(
...     replaced=pl.col("a").replace_strict(mapping)
... )  
Traceback (most recent call last):
...
polars.exceptions.InvalidOperationError: incomplete mapping specified for `replace_strict`
>>> df.with_columns(replaced=pl.col("a").replace_strict(mapping, default=-1))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ -1       │
│ 2   ┆ 200      │
│ 2   ┆ 200      │
│ 3   ┆ 300      │
└─────┴──────────┘

通过不同数据类型的值替换，基于new数据类型和default数据类型的组合设置返回类型。

>>> df = pl.DataFrame({"a": ["x", "y", "z"]})
>>> mapping = {"x": 1, "y": 2, "z": 3}
>>> df.with_columns(replaced=pl.col("a").replace_strict(mapping))
shape: (3, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ str ┆ i64      │
╞═════╪══════════╡
│ x   ┆ 1        │
│ y   ┆ 2        │
│ z   ┆ 3        │
└─────┴──────────┘
>>> df.with_columns(replaced=pl.col("a").replace_strict(mapping, default="x"))
shape: (3, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ str ┆ str      │
╞═════╪══════════╡
│ x   ┆ 1        │
│ y   ┆ 2        │
│ z   ┆ 3        │
└─────┴──────────┘

设置return_dtype参数以直接控制结果的数据类型。

>>> df.with_columns(
...     replaced=pl.col("a").replace_strict(mapping, return_dtype=pl.UInt8)
... )
shape: (3, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ str ┆ u8       │
╞═════╪══════════╡
│ x   ┆ 1        │
│ y   ┆ 2        │
│ z   ┆ 3        │
└─────┴──────────┘

所有参数都支持表达式输入。

>>> df = pl.DataFrame({"a": [1, 2, 2, 3], "b": [1.5, 2.5, 5.0, 1.0]})
>>> df.with_columns(
...     replaced=pl.col("a").replace_strict(
...         old=pl.col("a").max(),
...         new=pl.col("b").sum(),
...         default=pl.col("b"),
...     )
... )
shape: (4, 3)
┌─────┬─────┬──────────┐
│ a   ┆ b   ┆ replaced │
│ --- ┆ --- ┆ ---      │
│ i64 ┆ f64 ┆ f64      │
╞═════╪═════╪══════════╡
│ 1   ┆ 1.5 ┆ 1.5      │
│ 2   ┆ 2.5 ┆ 2.5      │
│ 2   ┆ 5.0 ┆ 5.0      │
│ 3   ┆ 1.0 ┆ 10.0     │
└─────┴─────┴──────────┘

reshape(dimensions: tuple[int, ...]) → Expr[source]

将此表达式重塑为扁平列或数组列。

Parameters:

dimensions: 维度大小的元组。如果在任何维度中使用-1，则该维度将被推断。

Returns:

Expr: 如果给出单个维度，则结果为原始数据类型的表达式。如果给出多个维度，则结果为数据类型为Array且形状为dimensions的表达式。

另请参阅

Expr.list.explode: 展开一个列表列。

示例

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

reverse() → Expr[source]

反转选择。

示例

>>> 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().name.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       │
└─────┴────────┴─────┴────────┴───────────┴────────────────┴───────────┴──────────────┘

rle() → Expr[source]

使用游程编码压缩列数据。

游程编码（RLE）通过将每个相同值的游程存储为单个值及其长度来编码数据。

Returns:

Expr: 数据类型 Struct 的表达式，包含数据类型为 UInt32 的字段 len 和原始数据类型的字段 value。

另请参阅

rle_id

示例

>>> df = pl.DataFrame({"a": [1, 1, 2, 1, None, 1, 3, 3]})
>>> df.select(pl.col("a").rle()).unnest("a")
shape: (6, 2)
┌─────┬───────┐
│ len ┆ value │
│ --- ┆ ---   │
│ u32 ┆ i64   │
╞═════╪═══════╡
│ 2   ┆ 1     │
│ 1   ┆ 2     │
│ 1   ┆ 1     │
│ 1   ┆ null  │
│ 1   ┆ 1     │
│ 2   ┆ 3     │
└─────┴───────┘

rle_id() → Expr[source]

为每次运行的相同值获取一个唯一的整数ID。

ID从0开始，每次列的值发生变化时增加1。

Returns:

Expr: 数据类型 UInt32 的表达式。

另请参阅

rle

注释

此功能特别适用于每次列的值发生变化时定义一个新组，而不是为该列的每个不同值定义新组。

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 1, 1, 1],
...         "b": ["x", "x", None, "y", "y"],
...     }
... )
>>> df.with_columns(
...     rle_id_a=pl.col("a").rle_id(),
...     rle_id_ab=pl.struct("a", "b").rle_id(),
... )
shape: (5, 4)
┌─────┬──────┬──────────┬───────────┐
│ a   ┆ b    ┆ rle_id_a ┆ rle_id_ab │
│ --- ┆ ---  ┆ ---      ┆ ---       │
│ i64 ┆ str  ┆ u32      ┆ u32       │
╞═════╪══════╪══════════╪═══════════╡
│ 1   ┆ x    ┆ 0        ┆ 0         │
│ 2   ┆ x    ┆ 1        ┆ 1         │
│ 1   ┆ null ┆ 2        ┆ 2         │
│ 1   ┆ y    ┆ 2        ┆ 3         │
│ 1   ┆ y    ┆ 2        ┆ 3         │
└─────┴──────┴──────────┴───────────┘

rolling( index_column: str, *, period: str | timedelta, offset: str | timedelta | None = None, closed: ClosedInterval = 'right', ) → Expr[source]

基于时间或整数列创建滚动组。

如果你有一个时间序列 t_1, ..., t_n>，那么默认创建的窗口将是

(t_0 - 周期, t_0]

(t_1 - 周期, t_1]

…

(t_n - 周期, t_n]

而如果你传递一个非默认的 offset，那么窗口将会是

(t_0 + offset, t_0 + offset + period]

(t_1 + offset, t_1 + offset + period]

…

(t_n + offset, t_n + offset + period]

period 和 offset 参数可以通过 timedelta 创建，或者使用以下字符串语言创建：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

或者将它们组合起来： “3d12h4m25s” # 3天，12小时，4分钟，25秒

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

Parameters:

index_column: 用于基于时间窗口进行分组的列。通常为日期/日期时间类型。此列必须按升序排序。如果是在索引上进行滚动分组，数据类型需要是 {UInt32, UInt64, Int32, Int64}之一。请注意，前三种类型会暂时转换为Int64，因此如果性能很重要，请使用Int64列。
period: 窗口的长度 - 必须为非负数。
offset: 窗口的偏移量。默认是 -period。
closed{‘right’, ‘left’, ‘both’, ‘none’}: 定义时间间隔的哪些边是闭合的（包含的）。

示例

>>> dates = [
...     "2020-01-01 13:45:48",
...     "2020-01-01 16:42:13",
...     "2020-01-01 16:45:09",
...     "2020-01-02 18:12:48",
...     "2020-01-03 19:45:32",
...     "2020-01-08 23:16:43",
... ]
>>> df = pl.DataFrame({"dt": dates, "a": [3, 7, 5, 9, 2, 1]}).with_columns(
...     pl.col("dt").str.strptime(pl.Datetime).set_sorted()
... )
>>> df.with_columns(
...     sum_a=pl.sum("a").rolling(index_column="dt", period="2d"),
...     min_a=pl.min("a").rolling(index_column="dt", period="2d"),
...     max_a=pl.max("a").rolling(index_column="dt", period="2d"),
... )
shape: (6, 5)
┌─────────────────────┬─────┬───────┬───────┬───────┐
│ dt                  ┆ a   ┆ sum_a ┆ min_a ┆ max_a │
│ ---                 ┆ --- ┆ ---   ┆ ---   ┆ ---   │
│ datetime[μs]        ┆ i64 ┆ i64   ┆ i64   ┆ i64   │
╞═════════════════════╪═════╪═══════╪═══════╪═══════╡
│ 2020-01-01 13:45:48 ┆ 3   ┆ 3     ┆ 3     ┆ 3     │
│ 2020-01-01 16:42:13 ┆ 7   ┆ 10    ┆ 3     ┆ 7     │
│ 2020-01-01 16:45:09 ┆ 5   ┆ 15    ┆ 3     ┆ 7     │
│ 2020-01-02 18:12:48 ┆ 9   ┆ 24    ┆ 3     ┆ 9     │
│ 2020-01-03 19:45:32 ┆ 2   ┆ 11    ┆ 2     ┆ 9     │
│ 2020-01-08 23:16:43 ┆ 1   ┆ 1     ┆ 1     ┆ 1     │
└─────────────────────┴─────┴───────┴───────┴───────┘

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

计算自定义滚动窗口函数。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

Parameters:

function: 自定义聚合函数。
window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。

警告

计算自定义函数非常慢。如果可能的话，请使用专门的滚动函数，例如 Expr.rolling_sum()。

示例

>>> from numpy import nansum
>>> df = pl.DataFrame({"a": [11.0, 2.0, 9.0, float("nan"), 8.0]})
>>> df.select(pl.col("a").rolling_map(nansum, window_size=3))
shape: (5, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ null │
│ 22.0 │
│ 11.0 │
│ 17.0 │
└──────┘

rolling_max( window_size: int, weights: list[float] | None = None, *, min_periods: int | None = None, center: bool = False, ) → Expr[source]

对此数组中的值应用滚动最大值（移动最大值）。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

一个长度为 window_size 的窗口将遍历数组。填充此窗口的值将（可选地）与由 weights 向量给出的权重相乘。结果值将聚合为其最大值。

给定行的窗口将包括该行本身及其前面的window_size - 1个元素。

Parameters:

window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

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

指定权重以与窗口中的值相乘：

>>> df.with_columns(
...     rolling_max=pl.col("A").rolling_max(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_max │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.5         │
│ 3.0 ┆ 2.25        │
│ 4.0 ┆ 3.0         │
│ 5.0 ┆ 3.75        │
│ 6.0 ┆ 4.5         │
└─────┴─────────────┘

将窗口中的值居中

>>> df.with_columns(
...     rolling_max=pl.col("A").rolling_max(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_max │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 3.0         │
│ 3.0 ┆ 4.0         │
│ 4.0 ┆ 5.0         │
│ 5.0 ┆ 6.0         │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_max_by( by: IntoExpr, window_size: timedelta | str, *, min_periods: int = 1, closed: ClosedInterval = 'right', ) → Expr[source]

基于另一列应用滚动最大值。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定一个by列 t_1, ..., t_n>，那么closed="right"（默认值）意味着窗口将是：

(t_0 - 窗口大小, t_0]

(t_1 - window_size, t_1]

…

(t_n - 窗口大小, t_n]

Parameters:

by

应该是 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型（注意，整数类型需要使用 'i' 在 window size 中）。

window_size

窗口的长度。可以是一个由timedelta表示的动态时间大小，也可以是以下字符串语言：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

min_periods

在计算结果之前，窗口中应该为非空值的数量。

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

定义时间间隔的哪些边是闭合的（包含的），默认为 'right'。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

创建一个带有日期时间列和行号列的DataFrame

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

计算时间窗口在右侧关闭的滚动最大值（默认）

>>> df_temporal.with_columns(
...     rolling_row_max=pl.col("index").rolling_max_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_max │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 1               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 2               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 3               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 4               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 20              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 21              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 22              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 23              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 24              │
└───────┴─────────────────────┴─────────────────┘

计算两侧窗口闭合的滚动最大值

>>> df_temporal.with_columns(
...     rolling_row_max=pl.col("index").rolling_max_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_max │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 1               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 2               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 3               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 4               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 20              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 21              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 22              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 23              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 24              │
└───────┴─────────────────────┴─────────────────┘

rolling_mean( window_size: int, weights: list[float] | None = None, *, min_periods: int | None = None, center: bool = False, ) → Expr[source]

对此数组中的值应用滚动平均值（移动平均值）。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

一个长度为 window_size 的窗口将遍历数组。填充此窗口的值将（可选地）与由 weights 向量给出的权重相乘。结果值将被聚合为其平均值。

给定行的窗口将包括该行本身，以及其前面的window_size - 1个元素。

Parameters:

window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_mean=pl.col("A").rolling_mean(window_size=2),
... )
shape: (6, 2)
┌─────┬──────────────┐
│ A   ┆ rolling_mean │
│ --- ┆ ---          │
│ f64 ┆ f64          │
╞═════╪══════════════╡
│ 1.0 ┆ null         │
│ 2.0 ┆ 1.5          │
│ 3.0 ┆ 2.5          │
│ 4.0 ┆ 3.5          │
│ 5.0 ┆ 4.5          │
│ 6.0 ┆ 5.5          │
└─────┴──────────────┘

指定权重以与窗口中的值相乘：

>>> df.with_columns(
...     rolling_mean=pl.col("A").rolling_mean(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬──────────────┐
│ A   ┆ rolling_mean │
│ --- ┆ ---          │
│ f64 ┆ f64          │
╞═════╪══════════════╡
│ 1.0 ┆ null         │
│ 2.0 ┆ 1.75         │
│ 3.0 ┆ 2.75         │
│ 4.0 ┆ 3.75         │
│ 5.0 ┆ 4.75         │
│ 6.0 ┆ 5.75         │
└─────┴──────────────┘

将窗口中的值居中

>>> df.with_columns(
...     rolling_mean=pl.col("A").rolling_mean(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬──────────────┐
│ A   ┆ rolling_mean │
│ --- ┆ ---          │
│ f64 ┆ f64          │
╞═════╪══════════════╡
│ 1.0 ┆ null         │
│ 2.0 ┆ 2.0          │
│ 3.0 ┆ 3.0          │
│ 4.0 ┆ 4.0          │
│ 5.0 ┆ 5.0          │
│ 6.0 ┆ null         │
└─────┴──────────────┘

rolling_mean_by( by: IntoExpr, window_size: timedelta | str, *, min_periods: int = 1, closed: ClosedInterval = 'right', ) → Expr[source]

基于另一列应用滚动平均值。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定一个by列 t_1, ..., t_n>，那么closed="right"（默认值）意味着窗口将是：

(t_0 - 窗口大小, t_0]

(t_1 - window_size, t_1]

…

(t_n - 窗口大小, t_n]

Parameters:

by

应该是 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型（注意，整数类型需要在 window size 中使用 'i'）。

window_size

窗口的长度。可以是一个由timedelta表示的动态时间大小，也可以是以下字符串语言：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

min_periods

在计算结果之前，窗口中应该为非空值的数量。

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

定义时间间隔的哪些边是闭合的（包含的），默认为 'right'。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

创建一个带有日期时间列和行号列的DataFrame

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

计算时间窗口右侧关闭的滚动平均值（默认）

>>> df_temporal.with_columns(
...     rolling_row_mean=pl.col("index").rolling_mean_by(
...         "date", window_size="2h"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬──────────────────┐
│ index ┆ date                ┆ rolling_row_mean │
│ ---   ┆ ---                 ┆ ---              │
│ u32   ┆ datetime[μs]        ┆ f64              │
╞═══════╪═════════════════════╪══════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0.0              │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5              │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.5              │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2.5              │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3.5              │
│ …     ┆ …                   ┆ …                │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19.5             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20.5             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21.5             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22.5             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23.5             │
└───────┴─────────────────────┴──────────────────┘

计算两侧窗口闭合的滚动平均值

>>> df_temporal.with_columns(
...     rolling_row_mean=pl.col("index").rolling_mean_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬──────────────────┐
│ index ┆ date                ┆ rolling_row_mean │
│ ---   ┆ ---                 ┆ ---              │
│ u32   ┆ datetime[μs]        ┆ f64              │
╞═══════╪═════════════════════╪══════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0.0              │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5              │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.0              │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2.0              │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3.0              │
│ …     ┆ …                   ┆ …                │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19.0             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20.0             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21.0             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22.0             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23.0             │
└───────┴─────────────────────┴──────────────────┘

rolling_median( window_size: int, weights: list[float] | None = None, *, min_periods: int | None = None, center: bool = False, ) → Expr[source]

计算滚动中位数。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

一个长度为 window_size 的窗口将遍历数组。填充此窗口的值将（可选地）与由 weights 向量给出的权重相乘。结果值将被聚合为其中位数。

给定行的窗口将包括该行本身及其前面的window_size - 1个元素。

Parameters:

window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_median=pl.col("A").rolling_median(window_size=2),
... )
shape: (6, 2)
┌─────┬────────────────┐
│ A   ┆ rolling_median │
│ --- ┆ ---            │
│ f64 ┆ f64            │
╞═════╪════════════════╡
│ 1.0 ┆ null           │
│ 2.0 ┆ 1.5            │
│ 3.0 ┆ 2.5            │
│ 4.0 ┆ 3.5            │
│ 5.0 ┆ 4.5            │
│ 6.0 ┆ 5.5            │
└─────┴────────────────┘

为每个窗口中的值指定权重：

>>> df.with_columns(
...     rolling_median=pl.col("A").rolling_median(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬────────────────┐
│ A   ┆ rolling_median │
│ --- ┆ ---            │
│ f64 ┆ f64            │
╞═════╪════════════════╡
│ 1.0 ┆ null           │
│ 2.0 ┆ 1.5            │
│ 3.0 ┆ 2.5            │
│ 4.0 ┆ 3.5            │
│ 5.0 ┆ 4.5            │
│ 6.0 ┆ 5.5            │
└─────┴────────────────┘

将窗口中的值居中

>>> df.with_columns(
...     rolling_median=pl.col("A").rolling_median(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬────────────────┐
│ A   ┆ rolling_median │
│ --- ┆ ---            │
│ f64 ┆ f64            │
╞═════╪════════════════╡
│ 1.0 ┆ null           │
│ 2.0 ┆ 2.0            │
│ 3.0 ┆ 3.0            │
│ 4.0 ┆ 4.0            │
│ 5.0 ┆ 5.0            │
│ 6.0 ┆ null           │
└─────┴────────────────┘

rolling_median_by( by: IntoExpr, window_size: timedelta | str, *, min_periods: int = 1, closed: ClosedInterval = 'right', ) → Expr[source]

基于另一列计算滚动中位数。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定一个by列 t_1, ..., t_n>，那么closed="right"（默认值）意味着窗口将是：

(t_0 - 窗口大小, t_0]

(t_1 - window_size, t_1]

…

(t_n - 窗口大小, t_n]

Parameters:

by

应该是 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型（注意，整数类型需要在 window size 中使用 'i'）。

window_size

窗口的长度。可以是一个由timedelta表示的动态时间大小，也可以是以下字符串语言：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

min_periods

在计算结果之前，窗口中应该为非空值的数量。

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

定义时间间隔的哪些边是闭合的（包含的），默认为 'right'。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

创建一个带有日期时间列和行号列的DataFrame

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

计算时间窗口右侧关闭的滚动中位数：

>>> df_temporal.with_columns(
...     rolling_row_median=pl.col("index").rolling_median_by(
...         "date", window_size="2h"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬────────────────────┐
│ index ┆ date                ┆ rolling_row_median │
│ ---   ┆ ---                 ┆ ---                │
│ u32   ┆ datetime[μs]        ┆ f64                │
╞═══════╪═════════════════════╪════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0.0                │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5                │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.5                │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2.5                │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3.5                │
│ …     ┆ …                   ┆ …                  │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19.5               │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20.5               │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21.5               │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22.5               │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23.5               │
└───────┴─────────────────────┴────────────────────┘

rolling_min( window_size: int, weights: list[float] | None = None, *, min_periods: int | None = None, center: bool = False, ) → Expr[source]

对此数组中的值应用滚动最小值（移动最小值）。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

一个长度为 window_size 的窗口将遍历数组。填充此窗口的值将（可选地）与由 weights 向量给出的权重相乘。结果值将聚合为其最小值。

给定行的窗口将包括该行本身及其前面的window_size - 1个元素。

Parameters:

window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

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

指定权重以与窗口中的值相乘：

>>> df.with_columns(
...     rolling_min=pl.col("A").rolling_min(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_min │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.25        │
│ 3.0 ┆ 0.5         │
│ 4.0 ┆ 0.75        │
│ 5.0 ┆ 1.0         │
│ 6.0 ┆ 1.25        │
└─────┴─────────────┘

将窗口中的值居中

>>> df.with_columns(
...     rolling_min=pl.col("A").rolling_min(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_min │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.0         │
│ 3.0 ┆ 2.0         │
│ 4.0 ┆ 3.0         │
│ 5.0 ┆ 4.0         │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_min_by( by: IntoExpr, window_size: timedelta | str, *, min_periods: int = 1, closed: ClosedInterval = 'right', ) → Expr[source]

基于另一列应用滚动最小值。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定一个by列 t_1, ..., t_n>，那么closed="right"（默认值）意味着窗口将是：

(t_0 - 窗口大小, t_0]

(t_1 - window_size, t_1]

…

(t_n - 窗口大小, t_n]

Parameters:

by

应该是 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型（注意，整数类型需要使用 'i' 在 window size 中）。

window_size

窗口的长度。可以是一个由timedelta表示的动态时间大小，也可以是以下字符串语言：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

min_periods

在计算结果之前，窗口中应该为非空值的数量。

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

定义时间间隔的哪些边是闭合的（包含的），默认为 'right'。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

创建一个带有日期时间列和行号列的DataFrame

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

计算时间窗口右侧关闭的滚动最小值（默认）

>>> df_temporal.with_columns(
...     rolling_row_min=pl.col("index").rolling_min_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_min │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23              │
└───────┴─────────────────────┴─────────────────┘

rolling_quantile( quantile: float, interpolation: RollingInterpolationMethod = 'nearest', window_size: int = 2, weights: list[float] | None = None, *, min_periods: int | None = None, center: bool = False, ) → Expr[source]

计算滚动分位数。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

一个长度为 window_size 的窗口将遍历数组。填充此窗口的值将（可选地）与由 weights 向量给出的权重相乘。结果值将聚合到它们的分位数。

给定行的窗口将包括该行本身及其前面的window_size - 1个元素。

Parameters:

quantile: 分位数在0.0到1.0之间。
interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’}: 插值方法。
window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_quantile=pl.col("A").rolling_quantile(
...         quantile=0.25, window_size=4
...     ),
... )
shape: (6, 2)
┌─────┬──────────────────┐
│ A   ┆ rolling_quantile │
│ --- ┆ ---              │
│ f64 ┆ f64              │
╞═════╪══════════════════╡
│ 1.0 ┆ null             │
│ 2.0 ┆ null             │
│ 3.0 ┆ null             │
│ 4.0 ┆ 2.0              │
│ 5.0 ┆ 3.0              │
│ 6.0 ┆ 4.0              │
└─────┴──────────────────┘

为每个窗口中的值指定权重：

>>> df.with_columns(
...     rolling_quantile=pl.col("A").rolling_quantile(
...         quantile=0.25, window_size=4, weights=[0.2, 0.4, 0.4, 0.2]
...     ),
... )
shape: (6, 2)
┌─────┬──────────────────┐
│ A   ┆ rolling_quantile │
│ --- ┆ ---              │
│ f64 ┆ f64              │
╞═════╪══════════════════╡
│ 1.0 ┆ null             │
│ 2.0 ┆ null             │
│ 3.0 ┆ null             │
│ 4.0 ┆ 2.0              │
│ 5.0 ┆ 3.0              │
│ 6.0 ┆ 4.0              │
└─────┴──────────────────┘

指定权重和插值方法

>>> df.with_columns(
...     rolling_quantile=pl.col("A").rolling_quantile(
...         quantile=0.25,
...         window_size=4,
...         weights=[0.2, 0.4, 0.4, 0.2],
...         interpolation="linear",
...     ),
... )
shape: (6, 2)
┌─────┬──────────────────┐
│ A   ┆ rolling_quantile │
│ --- ┆ ---              │
│ f64 ┆ f64              │
╞═════╪══════════════════╡
│ 1.0 ┆ null             │
│ 2.0 ┆ null             │
│ 3.0 ┆ null             │
│ 4.0 ┆ 1.625            │
│ 5.0 ┆ 2.625            │
│ 6.0 ┆ 3.625            │
└─────┴──────────────────┘

将窗口中的值居中

>>> df.with_columns(
...     rolling_quantile=pl.col("A").rolling_quantile(
...         quantile=0.2, window_size=5, center=True
...     ),
... )
shape: (6, 2)
┌─────┬──────────────────┐
│ A   ┆ rolling_quantile │
│ --- ┆ ---              │
│ f64 ┆ f64              │
╞═════╪══════════════════╡
│ 1.0 ┆ null             │
│ 2.0 ┆ null             │
│ 3.0 ┆ 2.0              │
│ 4.0 ┆ 3.0              │
│ 5.0 ┆ null             │
│ 6.0 ┆ null             │
└─────┴──────────────────┘

rolling_quantile_by( by: IntoExpr, window_size: timedelta | str, *, quantile: float, interpolation: RollingInterpolationMethod = 'nearest', min_periods: int = 1, closed: ClosedInterval = 'right', ) → Expr[source]

基于另一列计算滚动分位数。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定一个by列 t_1, ..., t_n>，那么closed="right"（默认值）意味着窗口将是：

(t_0 - 窗口大小, t_0]

(t_1 - window_size, t_1]

…

(t_n - 窗口大小, t_n]

Parameters:

by

应该是 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型（注意，整数类型需要在 window size 中使用 'i'）。

quantile

分位数在0.0到1.0之间。

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

插值方法。

window_size

窗口的长度。可以是一个由timedelta表示的动态时间大小，也可以是以下字符串语言：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

min_periods

在计算结果之前，窗口中应该为非空值的数量。

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

定义时间间隔的哪些边是闭合的（包含的），默认为 'right'。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

创建一个带有日期时间列和行号列的DataFrame

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

计算右侧关闭时间窗口的滚动分位数：

>>> df_temporal.with_columns(
...     rolling_row_quantile=pl.col("index").rolling_quantile_by(
...         "date", window_size="2h", quantile=0.3
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬──────────────────────┐
│ index ┆ date                ┆ rolling_row_quantile │
│ ---   ┆ ---                 ┆ ---                  │
│ u32   ┆ datetime[μs]        ┆ f64                  │
╞═══════╪═════════════════════╪══════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0.0                  │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.0                  │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.0                  │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2.0                  │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3.0                  │
│ …     ┆ …                   ┆ …                    │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19.0                 │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20.0                 │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21.0                 │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22.0                 │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23.0                 │
└───────┴─────────────────────┴──────────────────────┘

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

计算滚动偏度。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定行的窗口将包括该行本身及其前面的window_size - 1个元素。

Parameters:

window_size: 滚动窗口的整数大小。
bias: 如果为False，则计算会针对统计偏差进行校正。

示例

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

注意这些值如何匹配以下内容：

>>> pl.Series([1, 4, 2]).skew(), pl.Series([4, 2, 9]).skew()
(0.38180177416060584, 0.47033046033698594)

rolling_std( window_size: int, weights: list[float] | None = None, *, min_periods: int | None = None, center: bool = False, ddof: int = 1, ) → Expr[source]

计算滚动标准差。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

一个长度为 window_size 的窗口将遍历数组。填充此窗口的值将（可选地）与由 weights 向量给出的权重相乘。结果值将被聚合为其标准差。

给定行的窗口将包括该行本身，以及其前面的window_size - 1个元素。

Parameters:

window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。
ddof: “自由度差值”：长度为N的窗口的除数是N - ddof

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_std=pl.col("A").rolling_std(window_size=2),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_std │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.707107    │
│ 3.0 ┆ 0.707107    │
│ 4.0 ┆ 0.707107    │
│ 5.0 ┆ 0.707107    │
│ 6.0 ┆ 0.707107    │
└─────┴─────────────┘

指定权重以与窗口中的值相乘：

>>> df.with_columns(
...     rolling_std=pl.col("A").rolling_std(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_std │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.433013    │
│ 3.0 ┆ 0.433013    │
│ 4.0 ┆ 0.433013    │
│ 5.0 ┆ 0.433013    │
│ 6.0 ┆ 0.433013    │
└─────┴─────────────┘

将窗口中的值居中

>>> df.with_columns(
...     rolling_std=pl.col("A").rolling_std(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_std │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.0         │
│ 3.0 ┆ 1.0         │
│ 4.0 ┆ 1.0         │
│ 5.0 ┆ 1.0         │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_std_by( by: IntoExpr, window_size: timedelta | str, *, min_periods: int = 1, closed: ClosedInterval = 'right', ddof: int = 1, ) → Expr[source]

基于另一列计算滚动标准差。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定一个by列 t_1, ..., t_n>，那么closed="right"（默认值）意味着窗口将是：

(t_0 - 窗口大小, t_0]

(t_1 - window_size, t_1]

…

(t_n - 窗口大小, t_n]

Parameters:

by

应该是 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型（注意，整数类型需要在 window size 中使用 'i'）。

window_size

窗口的长度。可以是一个由timedelta表示的动态时间大小，也可以是以下字符串语言：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

min_periods

在计算结果之前，窗口中应该为非空值的数量。

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

定义时间间隔的哪些边是闭合的（包含的），默认为 'right'。

ddof

“自由度差值”：长度为N的窗口的除数是N - ddof

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

创建一个带有日期时间列和行号列的DataFrame

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

计算滚动标准差，时间窗口在右侧关闭（默认）

>>> df_temporal.with_columns(
...     rolling_row_std=pl.col("index").rolling_std_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_std │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ f64             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ null            │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.707107        │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 0.707107        │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 0.707107        │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 0.707107        │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 0.707107        │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 0.707107        │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 0.707107        │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 0.707107        │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 0.707107        │
└───────┴─────────────────────┴─────────────────┘

计算两侧窗口闭合的滚动标准差

>>> df_temporal.with_columns(
...     rolling_row_std=pl.col("index").rolling_std_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_std │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ f64             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ null            │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.707107        │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.0             │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 1.0             │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 1.0             │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 1.0             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 1.0             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 1.0             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 1.0             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 1.0             │
└───────┴─────────────────────┴─────────────────┘

rolling_sum( window_size: int, weights: list[float] | None = None, *, min_periods: int | None = None, center: bool = False, ) → Expr[source]

对此数组中的值应用滚动求和（移动求和）。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

一个长度为 window_size 的窗口将遍历数组。填充此窗口的值将（可选地）与由 weights 向量给出的权重相乘。结果值将被聚合为它们的总和。

给定行的窗口将包括该行本身及其前面的window_size - 1个元素。

Parameters:

window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

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

指定权重以与窗口中的值相乘：

>>> df.with_columns(
...     rolling_sum=pl.col("A").rolling_sum(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_sum │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.75        │
│ 3.0 ┆ 2.75        │
│ 4.0 ┆ 3.75        │
│ 5.0 ┆ 4.75        │
│ 6.0 ┆ 5.75        │
└─────┴─────────────┘

将窗口中的值居中

>>> df.with_columns(
...     rolling_sum=pl.col("A").rolling_sum(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_sum │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 6.0         │
│ 3.0 ┆ 9.0         │
│ 4.0 ┆ 12.0        │
│ 5.0 ┆ 15.0        │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_sum_by( by: IntoExpr, window_size: timedelta | str, *, min_periods: int = 1, closed: ClosedInterval = 'right', ) → Expr[source]

基于另一列应用滚动求和。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定一个by列 t_1, ..., t_n>，那么closed="right"（默认值）意味着窗口将是：

(t_0 - 窗口大小, t_0]

(t_1 - window_size, t_1]

…

(t_n - 窗口大小, t_n]

Parameters:

window_size

窗口的长度。可以是一个由timedelta表示的动态时间大小，也可以是以下字符串语言：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

min_periods

在计算结果之前，窗口中应该为非空值的数量。

by

应该是 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型（注意，整数类型需要使用 'i' 在 window size 中）。

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

定义时间间隔的哪些边是闭合的（包含的），默认为 'right'。

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

创建一个带有日期时间列和行号列的DataFrame

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

计算时间窗口右侧关闭的滚动总和（默认）

>>> df_temporal.with_columns(
...     rolling_row_sum=pl.col("index").rolling_sum_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_sum │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 1               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 3               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 5               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 7               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 39              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 41              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 43              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 45              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 47              │
└───────┴─────────────────────┴─────────────────┘

计算两侧窗口闭合的滚动总和

>>> df_temporal.with_columns(
...     rolling_row_sum=pl.col("index").rolling_sum_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_sum │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 1               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 3               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 6               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 9               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 57              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 60              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 63              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 66              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 69              │
└───────┴─────────────────────┴─────────────────┘

rolling_var( window_size: int, weights: list[float] | None = None, *, min_periods: int | None = None, center: bool = False, ddof: int = 1, ) → Expr[source]

计算滚动方差。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

一个长度为 window_size 的窗口将遍历数组。填充此窗口的值将（可选地）与由 weights 向量给出的权重相乘。结果值将聚合到它们的方差。

给定行的窗口将包括该行本身及其前面的window_size - 1个元素。

Parameters:

window_size: 窗口的长度以元素数量表示。
weights: 一个与窗口长度相同的可选切片，它将与窗口中的值进行元素级乘法。
min_periods: 在计算结果之前，窗口中应该为非空值的数量。如果设置为None（默认值），它将被设置为等于window_size。
center: 将标签设置在窗口的中心。
ddof: “自由度差值”：长度为N的窗口的除数是N - ddof

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_var=pl.col("A").rolling_var(window_size=2),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_var │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.5         │
│ 3.0 ┆ 0.5         │
│ 4.0 ┆ 0.5         │
│ 5.0 ┆ 0.5         │
│ 6.0 ┆ 0.5         │
└─────┴─────────────┘

指定权重以与窗口中的值相乘：

>>> df.with_columns(
...     rolling_var=pl.col("A").rolling_var(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_var │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.1875      │
│ 3.0 ┆ 0.1875      │
│ 4.0 ┆ 0.1875      │
│ 5.0 ┆ 0.1875      │
│ 6.0 ┆ 0.1875      │
└─────┴─────────────┘

将窗口中的值居中

>>> df.with_columns(
...     rolling_var=pl.col("A").rolling_var(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_var │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.0         │
│ 3.0 ┆ 1.0         │
│ 4.0 ┆ 1.0         │
│ 5.0 ┆ 1.0         │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_var_by( by: IntoExpr, window_size: timedelta | str, *, min_periods: int = 1, closed: ClosedInterval = 'right', ddof: int = 1, ) → Expr[source]

基于另一列计算滚动方差。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

给定一个by列 t_1, ..., t_n>，那么closed="right"（默认值）意味着窗口将是：

(t_0 - 窗口大小, t_0]

(t_1 - window_size, t_1]

…

(t_n - 窗口大小, t_n]

Parameters:

by

应该是 DateTime, Date, UInt64, UInt32, Int64, 或 Int32 数据类型（注意，整数类型需要使用 'i' 在 window size 中）。

window_size

窗口的长度。可以是一个由timedelta表示的动态时间大小，也可以是以下字符串语言：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

min_periods

在计算结果之前，窗口中应该为非空值的数量。

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

定义时间间隔的哪些边是闭合的（包含的），默认为 'right'。

ddof

“自由度差值”：长度为N的窗口的除数是N - ddof

注释

如果你想在同一个动态窗口上计算多个聚合统计量，考虑使用rolling - 这个方法可以缓存窗口大小的计算。

示例

创建一个带有日期时间列和行号列的DataFrame

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

计算滚动方差，时间窗口在右侧关闭（默认）

>>> df_temporal.with_columns(
...     rolling_row_var=pl.col("index").rolling_var_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_var │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ f64             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ null            │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5             │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 0.5             │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 0.5             │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 0.5             │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 0.5             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 0.5             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 0.5             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 0.5             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 0.5             │
└───────┴─────────────────────┴─────────────────┘

计算两侧窗口闭合的滚动方差

>>> df_temporal.with_columns(
...     rolling_row_var=pl.col("index").rolling_var_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_var │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ f64             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ null            │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5             │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.0             │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 1.0             │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 1.0             │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 1.0             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 1.0             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 1.0             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 1.0             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 1.0             │
└───────┴─────────────────────┴─────────────────┘

round(decimals: int = 0) → Expr[source]

将底层浮点数据四舍五入到 decimals 位小数。

Parameters:

decimals: 四舍五入的小数位数。

示例

>>> 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 │
└─────┘

round_sig_figs(digits: int) → Expr[source]

四舍五入到指定的有效数字位数。

Parameters:

digits: 要四舍五入的有效数字位数。

示例

>>> df = pl.DataFrame({"a": [0.01234, 3.333, 1234.0]})
>>> df.with_columns(pl.col("a").round_sig_figs(2).alias("round_sig_figs"))
shape: (3, 2)
┌─────────┬────────────────┐
│ a       ┆ round_sig_figs │
│ ---     ┆ ---            │
│ f64     ┆ f64            │
╞═════════╪════════════════╡
│ 0.01234 ┆ 0.012          │
│ 3.333   ┆ 3.3            │
│ 1234.0  ┆ 1200.0         │
└─────────┴────────────────┘

从这个表达式中取样。

Parameters:

n: 返回的项目数量。不能与fraction一起使用。如果fraction为None，则默认为1。
fraction: 返回项目的比例。不能与 n 一起使用。
with_replacement: 允许值被多次采样。
shuffle: 打乱采样数据点的顺序。
seed: 随机数生成器的种子。如果设置为None（默认值），则为每次采样操作生成一个随机种子。

示例

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

search_sorted( element: IntoExpr | np.ndarray[Any, Any], side: SearchSortedSide = 'any', ) → Expr[source]

找到应插入元素以保持顺序的索引。

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

Parameters:

element: 表达式或标量值。
side{‘any’, ‘left’, ‘right’}: 如果选择‘any’，则返回找到的第一个合适位置的索引。如果选择‘left’，则返回找到的最左边合适位置的索引。如果选择‘right’，则返回找到的最右边合适位置的索引。

示例

>>> 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) → Expr[source]

将表达式标记为‘已排序’。

使下游代码能够使用排序数组的快速路径。

Parameters:

descending: 是否Series的顺序是降序的。

警告

如果数据未排序，这可能导致错误的结果！！请谨慎使用！

示例

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

shift(n: int | IntoExprColumn = 1, *, fill_value: IntoExpr | None = None) → Expr[source]

将值按给定的索引数进行移动。

Parameters:

n: 向前移动的索引数量。如果传递了负值，则值将向相反方向移动。
fill_value: 用此值填充生成的空值。

另请参阅

backward_fill
forward_fill

注释

此方法类似于SQL中的LAG操作，当n的值为正时。当n的值为负时，它类似于LEAD。

示例

默认情况下，值会向前移动一个索引。

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

传递一个负值以向相反方向移动。

>>> df.with_columns(shift=pl.col("a").shift(-2))
shape: (4, 2)
┌─────┬───────┐
│ a   ┆ shift │
│ --- ┆ ---   │
│ i64 ┆ i64   │
╞═════╪═══════╡
│ 1   ┆ 3     │
│ 2   ┆ 4     │
│ 3   ┆ null  │
│ 4   ┆ null  │
└─────┴───────┘

指定fill_value以填充结果中的空值。

>>> df.with_columns(shift=pl.col("a").shift(-2, fill_value=100))
shape: (4, 2)
┌─────┬───────┐
│ a   ┆ shift │
│ --- ┆ ---   │
│ i64 ┆ i64   │
╞═════╪═══════╡
│ 1   ┆ 3     │
│ 2   ┆ 4     │
│ 3   ┆ 100   │
│ 4   ┆ 100   │
└─────┴───────┘

shrink_dtype() → Expr[source]

将数值列缩小到所需的最小数据类型。

缩小到适合此[Series]极值所需的dtype。这可以用于减少内存压力。

示例

>>> 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) → Expr[source]

打乱此表达式的内容。

请注意，这是独立于任何其他列或表达式进行洗牌的。如果您希望每行保持不变，请使用 df.sample(shuffle=True)

Parameters:

seed: 随机数生成器的种子。如果设置为None（默认），每次调用shuffle时都会生成一个随机种子。

示例

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

sign() → Expr[source]

计算数值类型的逐元素符号函数。

返回值计算如下：

如果 x 小于 0，则为 -1。
1 如果 x > 0。
x 否则（通常为 0，但如果输入为 NaN 则可能为 NaN）。

空值将按原样保留，并且输入的dtype也将保留。

示例

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

sin() → Expr[source]

计算元素的正弦值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

sinh() → Expr[source]

计算双曲正弦的逐元素值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

skew(*, bias: bool = True) → Expr[source]

计算数据集的样本偏度。

对于正态分布的数据，偏度应该接近于零。对于单峰连续分布，偏度值大于零意味着分布的右侧尾部有更多的权重。函数skewtest可以用来确定偏度值是否在统计上足够接近于零。

有关更多信息，请参阅 scipy.stats。

Parameters:

biasbool, optional: 如果为False，则计算会针对统计偏差进行校正。

注释

样本偏度计算为Fisher-Pearson偏度系数，即

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

其中

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

是偏置样本的第$i\texttt{th}$中心矩，而 $\bar{x}$是样本均值。如果bias为False，则计算会进行偏置校正，计算出的值是调整后的 Fisher-Pearson标准化矩系数，即

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

示例

>>> 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, ) → Expr[source]

获取此表达式的一个切片。

Parameters:

offset: 起始索引。支持负索引。
length: 切片的长度。如果设置为None，将从偏移量开始选择所有行。

示例

>>> 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, ) → Expr[source]

对此列进行排序。

在投影/选择上下文中使用时，整个列会被排序。在分组上下文中使用时，组会被排序。

Parameters:

descending: 按降序排序。
nulls_last: 将空值放在最后。

示例

>>> 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 │
└──────┘

在按上下文分组时，组会被排序。

>>> df = pl.DataFrame(
...     {
...         "group": ["one", "one", "one", "two", "two", "two"],
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.group_by("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, nulls_last: bool | Sequence[bool] = False, multithreaded: bool = True, maintain_order: bool = False, ) → Expr[source]

按其他列的排序对此列进行排序。

在投影/选择上下文中使用时，整个列会被排序。在分组上下文中使用时，组会被排序。

Parameters:

by: 要排序的列。接受表达式输入。字符串被解析为列名。
*more_by: 要排序的附加列，指定为位置参数。
descending: 按降序排序。当按多列排序时，可以通过传递布尔值序列来为每列指定。
nulls_last: 将空值放在最后；可以指定一个适用于所有列的布尔值，或者为每列控制指定一个布尔值序列。
multithreaded: 使用多线程进行排序。
maintain_order: 如果元素相等，是否应保持顺序。

示例

传递单个列名以按该列排序。

>>> 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     │
└───────┘

支持通过表达式进行排序。

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

通过传递列列表按多列排序。

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

或者使用位置参数以相同的方式按多列排序。

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

在按上下文分组时，组会被排序。

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

从每个组中取出一行，其中某一列在该组中达到其最小值。

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

sqrt() → Expr[source]

计算元素的平方根。

示例

>>> 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) → Expr[source]

获取标准差。

Parameters:

ddof: “自由度差值”：计算中使用的除数是 N - ddof，其中 N 表示元素的数量。默认情况下，ddof 为 1。

示例

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

sub(other: Any) → Expr[source]

方法等同于减法运算符 expr - other。

Parameters:

other: 数值字面量或表达式值。

示例

>>> df = pl.DataFrame({"x": [0, 1, 2, 3, 4]})
>>> df.with_columns(
...     pl.col("x").sub(2).alias("x-2"),
...     pl.col("x").sub(pl.col("x").cum_sum()).alias("x-expr"),
... )
shape: (5, 3)
┌─────┬─────┬────────┐
│ x   ┆ x-2 ┆ x-expr │
│ --- ┆ --- ┆ ---    │
│ i64 ┆ i64 ┆ i64    │
╞═════╪═════╪════════╡
│ 0   ┆ -2  ┆ 0      │
│ 1   ┆ -1  ┆ 0      │
│ 2   ┆ 0   ┆ -1     │
│ 3   ┆ 1   ┆ -3     │
│ 4   ┆ 2   ┆ -6     │
└─────┴─────┴────────┘

sum() → Expr[source]

获取总和值。

注释

{Int8, UInt8, Int16, UInt16} 中的数据类型在求和之前会被转换为 Int64，以防止溢出问题。

示例

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

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

获取最后 n 行。

Parameters:

n: 返回的行数。

示例

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

tan() → Expr[source]

计算元素的正切值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

tanh() → Expr[source]

计算双曲正切的逐元素值。

Returns:

Expr: 数据类型 Float64 的表达。

示例

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

to_physical() → Expr[source]

将逻辑数据类型转换为物理表示。

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()
List(inner) -> List(physical of inner)
Array(inner) -> Struct(physical of inner)
Struct(fields) -> Array(physical of fields)

其他数据类型将保持不变。

警告

物理表示是一个实现细节，并不保证是稳定的。

示例

复制pandas的 pd.factorize 函数。

>>> 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 | IntoExprColumn = 5) → Expr[source]

返回k个最大的元素。

非空元素总是优先于空元素。输出不保证按任何特定顺序排列，如果您希望输出排序，请在此函数后调用sort()。

这具有时间复杂度：

\[O(n)\]

Parameters:

k: 返回的元素数量。

另请参阅

top_k_by
bottom_k
bottom_k_by

示例

获取系列中的5个最大值。

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

top_k_by( by: IntoExpr | Iterable[IntoExpr], k: int | IntoExprColumn = 5, *, reverse: bool | Sequence[bool] = False, ) → Expr[source]

返回与by列中k个最大元素对应的元素。

非空元素总是优先于空元素，无论reverse的值如何。输出不保证按任何特定顺序排列，如果您希望输出排序，请在此函数后调用sort()。

这具有时间复杂度：

\[O(n \log{n})\]

Parameters:

by: 用于确定最大元素的列。接受表达式输入。字符串被解析为列名。
k: 返回的元素数量。
reverse: 考虑by列中的k个最小元素（而不是k个最大元素）。可以通过传递一个布尔值序列来为每列指定这一点。

另请参阅

top_k
bottom_k
bottom_k_by

示例

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [6, 5, 4, 3, 2, 1],
...         "c": ["Apple", "Orange", "Apple", "Apple", "Banana", "Banana"],
...     }
... )
>>> df
shape: (6, 3)
┌─────┬─────┬────────┐
│ a   ┆ b   ┆ c      │
│ --- ┆ --- ┆ ---    │
│ i64 ┆ i64 ┆ str    │
╞═════╪═════╪════════╡
│ 1   ┆ 6   ┆ Apple  │
│ 2   ┆ 5   ┆ Orange │
│ 3   ┆ 4   ┆ Apple  │
│ 4   ┆ 3   ┆ Apple  │
│ 5   ┆ 2   ┆ Banana │
│ 6   ┆ 1   ┆ Banana │
└─────┴─────┴────────┘

获取按列 a 或 b 排序的前2行。

>>> df.select(
...     pl.all().top_k_by("a", 2).name.suffix("_top_by_a"),
...     pl.all().top_k_by("b", 2).name.suffix("_top_by_b"),
... )
shape: (2, 6)
┌────────────┬────────────┬────────────┬────────────┬────────────┬────────────┐
│ a_top_by_a ┆ b_top_by_a ┆ c_top_by_a ┆ a_top_by_b ┆ b_top_by_b ┆ c_top_by_b │
│ ---        ┆ ---        ┆ ---        ┆ ---        ┆ ---        ┆ ---        │
│ i64        ┆ i64        ┆ str        ┆ i64        ┆ i64        ┆ str        │
╞════════════╪════════════╪════════════╪════════════╪════════════╪════════════╡
│ 6          ┆ 1          ┆ Banana     ┆ 1          ┆ 6          ┆ Apple      │
│ 5          ┆ 2          ┆ Banana     ┆ 2          ┆ 5          ┆ Orange     │
└────────────┴────────────┴────────────┴────────────┴────────────┴────────────┘

按给定顺序通过多列获取前2行。

>>> df.select(
...     pl.all()
...     .top_k_by(["c", "a"], 2, reverse=[False, True])
...     .name.suffix("_by_ca"),
...     pl.all()
...     .top_k_by(["c", "b"], 2, reverse=[False, True])
...     .name.suffix("_by_cb"),
... )
shape: (2, 6)
┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐
│ a_by_ca ┆ b_by_ca ┆ c_by_ca ┆ a_by_cb ┆ b_by_cb ┆ c_by_cb │
│ ---     ┆ ---     ┆ ---     ┆ ---     ┆ ---     ┆ ---     │
│ i64     ┆ i64     ┆ str     ┆ i64     ┆ i64     ┆ str     │
╞═════════╪═════════╪═════════╪═════════╪═════════╪═════════╡
│ 2       ┆ 5       ┆ Orange  ┆ 2       ┆ 5       ┆ Orange  │
│ 5       ┆ 2       ┆ Banana  ┆ 6       ┆ 1       ┆ Banana  │
└─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘

获取每组中按列 a 排序的前2行。

>>> (
...     df.group_by("c", maintain_order=True)
...     .agg(pl.all().top_k_by("a", 2))
...     .explode(pl.all().exclude("c"))
... )
shape: (5, 3)
┌────────┬─────┬─────┐
│ c      ┆ a   ┆ b   │
│ ---    ┆ --- ┆ --- │
│ str    ┆ i64 ┆ i64 │
╞════════╪═════╪═════╡
│ Apple  ┆ 4   ┆ 3   │
│ Apple  ┆ 3   ┆ 4   │
│ Orange ┆ 2   ┆ 5   │
│ Banana ┆ 6   ┆ 1   │
│ Banana ┆ 5   ┆ 2   │
└────────┴─────┴─────┘

truediv(other: Any) → Expr[source]

方法等同于浮点除法运算符 expr / other。

Parameters:

other: 数值字面量或表达式值。

另请参阅

floordiv

注释

零除行为遵循IEEE-754标准：

0/0: 无效操作 - 数学上未定义，返回NaN。 n/0: 在有限操作数上给出精确的无限结果，例如：±无穷大。

示例

>>> df = pl.DataFrame(
...     data={"x": [-2, -1, 0, 1, 2], "y": [0.5, 0.0, 0.0, -4.0, -0.5]}
... )
>>> df.with_columns(
...     pl.col("x").truediv(2).alias("x/2"),
...     pl.col("x").truediv(pl.col("y")).alias("x/y"),
... )
shape: (5, 4)
┌─────┬──────┬──────┬───────┐
│ x   ┆ y    ┆ x/2  ┆ x/y   │
│ --- ┆ ---  ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ f64  ┆ f64   │
╞═════╪══════╪══════╪═══════╡
│ -2  ┆ 0.5  ┆ -1.0 ┆ -4.0  │
│ -1  ┆ 0.0  ┆ -0.5 ┆ -inf  │
│ 0   ┆ 0.0  ┆ 0.0  ┆ NaN   │
│ 1   ┆ -4.0 ┆ 0.5  ┆ -0.25 │
│ 2   ┆ -0.5 ┆ 1.0  ┆ -4.0  │
└─────┴──────┴──────┴───────┘

unique(*, maintain_order: bool = False) → Expr[source]

获取此表达式的唯一值。

Parameters:

maintain_order: 保持数据顺序。这需要更多的工作。

示例

>>> 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() → Expr[source]

返回按出现顺序排列的唯一值的计数。

此方法与value_counts不同之处在于它不返回值，只返回计数，并且可能更快

示例

>>> 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() → Expr[source]

计算上限。

返回一个单位Series，其值为该表达式dtype可能的最大值。

示例

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

value_counts( *, sort: bool = False, parallel: bool = False, name: str | None = None, normalize: bool = False, ) → Expr[source]

计算唯一值的出现次数。

Parameters:

sort: 按计数降序排序输出。如果设置为False（默认值），输出的顺序是随机的。
parallel: 并行执行计算。

注意

在分组上下文中，此选项可能不应启用，因为计算已经按组并行化。
name: 给结果计数列一个特定的名称；如果normalize为True，则默认为“proportion”，否则默认为“count”。
normalize: 如果为真，则给出唯一值的相对频率

Returns:

Expr: 数据类型 Struct 的表达，其中包含唯一值到其计数的映射。

示例

>>> df = pl.DataFrame(
...     {"color": ["red", "blue", "red", "green", "blue", "blue"]}
... )
>>> df.select(pl.col("color").value_counts())  
shape: (3, 1)
┌─────────────┐
│ color       │
│ ---         │
│ struct[2]   │
╞═════════════╡
│ {"red",2}   │
│ {"green",1} │
│ {"blue",3}  │
└─────────────┘

按（降序）计数排序输出并自定义计数字段名称。

>>> df = df.select(pl.col("color").value_counts(sort=True, name="n"))
>>> df
shape: (3, 1)
┌─────────────┐
│ color       │
│ ---         │
│ struct[2]   │
╞═════════════╡
│ {"blue",3}  │
│ {"red",2}   │
│ {"green",1} │
└─────────────┘

>>> df.unnest("color")
shape: (3, 2)
┌───────┬─────┐
│ color ┆ n   │
│ ---   ┆ --- │
│ str   ┆ u32 │
╞═══════╪═════╡
│ blue  ┆ 3   │
│ red   ┆ 2   │
│ green ┆ 1   │
└───────┴─────┘

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

获取方差。

Parameters:

ddof: “自由度差值”：计算中使用的除数是 N - ddof，其中 N 表示元素的数量。默认情况下，ddof 为 1。

示例

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

where(predicate: Expr) → Expr[source]

过滤单个列。

自版本0.20.4起已弃用：请改用filter()。

filter() 的别名。

Parameters:

predicate: 布尔表达式。

示例

>>> df = pl.DataFrame(
...     {
...         "group_col": ["g1", "g1", "g2"],
...         "b": [1, 2, 3],
...     }
... )
>>> df.group_by("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        ┆ 0   ┆ 3   │
└───────────┴─────┴─────┘

xor(other: Any) → Expr[source]

方法等效于按位异或运算符 expr ^ other。

Parameters:

other: 整数或布尔值；接受表达式输入。

示例

>>> df = pl.DataFrame(
...     {"x": [True, False, True, False], "y": [True, True, False, False]}
... )
>>> df.with_columns(pl.col("x").xor(pl.col("y")).alias("x ^ y"))
shape: (4, 3)
┌───────┬───────┬───────┐
│ x     ┆ y     ┆ x ^ y │
│ ---   ┆ ---   ┆ ---   │
│ bool  ┆ bool  ┆ bool  │
╞═══════╪═══════╪═══════╡
│ true  ┆ true  ┆ false │
│ false ┆ true  ┆ true  │
│ true  ┆ false ┆ true  │
│ false ┆ false ┆ false │
└───────┴───────┴───────┘

>>> def binary_string(n: int) -> str:
...     return bin(n)[2:].zfill(8)
>>>
>>> df = pl.DataFrame(
...     data={"x": [10, 8, 250, 66], "y": [1, 2, 3, 4]},
...     schema={"x": pl.UInt8, "y": pl.UInt8},
... )
>>> df.with_columns(
...     pl.col("x")
...     .map_elements(binary_string, return_dtype=pl.String)
...     .alias("bin_x"),
...     pl.col("y")
...     .map_elements(binary_string, return_dtype=pl.String)
...     .alias("bin_y"),
...     pl.col("x").xor(pl.col("y")).alias("xor_xy"),
...     pl.col("x")
...     .xor(pl.col("y"))
...     .map_elements(binary_string, return_dtype=pl.String)
...     .alias("bin_xor_xy"),
... )
shape: (4, 6)
┌─────┬─────┬──────────┬──────────┬────────┬────────────┐
│ x   ┆ y   ┆ bin_x    ┆ bin_y    ┆ xor_xy ┆ bin_xor_xy │
│ --- ┆ --- ┆ ---      ┆ ---      ┆ ---    ┆ ---        │
│ u8  ┆ u8  ┆ str      ┆ str      ┆ u8     ┆ str        │
╞═════╪═════╪══════════╪══════════╪════════╪════════════╡
│ 10  ┆ 1   ┆ 00001010 ┆ 00000001 ┆ 11     ┆ 00001011   │
│ 8   ┆ 2   ┆ 00001000 ┆ 00000010 ┆ 10     ┆ 00001010   │
│ 250 ┆ 3   ┆ 11111010 ┆ 00000011 ┆ 249    ┆ 11111001   │
│ 66  ┆ 4   ┆ 01000010 ┆ 00000100 ┆ 70     ┆ 01000110   │
└─────┴─────┴──────────┴──────────┴────────┴────────────┘