Polarsのpolars.Expr.clipとは何なのか調べてみた

はじめに

今年の7月にPolarsのv1.0.0がリリースされ、現在はv1.12.0が最新です。
私はリリース直後にpolars-jaユーザーグループが開催した「リリースノートを読む会」に参加し、その中で触れられたclip関数に興味を持ちました。
かなり時間が経ってしまいましたが、この関数について調べてみることにしました。
以下の点が特に気になったポイントです。

調査のポイント

clip関数がどのような処理を行うのか
どのような場面で役に立つのか

結論

ざっくり結論を記載します。

• どのような関数か
  → clip関数は、指定した最小値や最大値を境界として、値がその範囲を超える場合に境界値に変換することができる関数です。

• どのような場面で使用されるのか
  → データの前処理や異常値の処理に使用されるようです。

この後に関数の概要、サンプルコードを記載します。

clip関数の概要と使い方

公式ドキュメントを確認したところ、clip関数は、データフレームやシリーズ内の数値や時間などの値を指定した範囲に収めるために使用されるようでした。例えば、データに異常値があった場合に除去せずに使用したいというような処理や、値を一定範囲内に保つ必要がある場合に使用されるものだと思われます。

以下はPolarsでの使用例です。

Polarsでのclip関数の使用例①

import polars as pl

# DataFrameの作成
df = pl.DataFrame({
    'A': [1, 2, 3, 4, 5],
    'B': [10, 20, 30, 40, 50]
})

# 値を特定の範囲内に制限する
clipped_df = df.with_columns([
    pl.col('A').clip(2, 4),
    pl.col('B').clip(20, 40)
])

出力結果:

shape: (5, 2)
┌─────┬─────┐
│ A   │ B   │
│ --- │ --- │
│ i64 │ i64 │
╞═════╪═════╡
│ 2   │ 20  │
│ 2   │ 20  │
│ 3   │ 30  │
│ 4   │ 40  │
│ 4   │ 40  │
└─────┴─────┘

Polarsでのclip関数の使用例②

import polars as pl

# DataFrame作成
df = pl.DataFrame({"a": [0, 1, 2, 3, 4, 5, 6], "min": [1, None, 1, 3, 4, 6, None]})
df.select(pl.col("a").clip("min"))

出力結果:

shape: (7, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 1   │
│ 2   │
│ 3   │
│ 4   │
│ 6   │
│ 6   │
└─────┘

解説

使用例②については、サンプルコードを見て動かしただけだと私は理解できなかったので、ChatGPTを使用して解説してもらいました。

1. まず、a と min の2つの列を持つPolarsのDataFrameを作成します。
2. a 列には0から6の整数が含まれています。
3. min 列には、クリッピング時の最小値として使う値が設定されています。一部には None（欠損値）も含まれており、クリッピングに影響を与えます。
4. pl.col("a").clip("min") は、列 a の値を、min 列の値でクリッピングする操作です。
5. clip 関数は a 列の各値を確認し、対応する min 列の値が設定されていれば、その値以下にはならないように制限します。たとえば、 a 列の最初の値 0 は min 列の 1 でクリップされるため、結果は 1 になります。
6. min 列の値が None の場合、その行のクリッピングには影響しないため、元の値がそのまま出力されます。

上記の流れから、0 から始まる a 列の値が、指定された min 列の最小値によって制限されるため、上記の出力結果となることがわかりました。

Pandas の clip 関数

Pandasにおいても同様にclip関数が存在しています。
Pandasでは、DataFrame または Series に対して clip 関数を使用することができます。

import pandas as pd

# DataFrameの作成
df = pd.DataFrame({'A': [1, 2, 3, 4, 5], 'B': [10, 20, 30, 40, 50]})
clipped_df = df.clip(lower=2, upper=4)
print(clipped_df)

出力結果:

   A  B
0  2  10
1  2  20
2  3  30
3  4  40
4  4  50

まとめ

clip関数は、指定した最小値や最大値を境界として、値がその範囲を超える場合に境界値に変換することができる関数であり、データの前処理や異常値の処理を行う際に使用されることがあるようです。
また、Polarsだけでなく、Pandasにおいてもclip関数が提供されています。

参考