Python Polars チートシート(O'Reillyの書籍に基づく)
Python Polars Cheatsheet (based on our O'Reilly book) (opensource.posit.co)
要約
このチートシートは、Pythonのデータ処理ライブラリであるPolarsのクイックリファレンスガイドです。Polarsは、高速で表現力豊かなDataFrame APIを提供し、データの変換、分析、可視化に使用されます。記事では、Polarsのインストール方法、データ構造(Series、DataFrame、LazyFrame)、Eager APIとLazy APIの違い、データ型、データの読み書き、列の選択、新しい列の作成、行のフィルタリングなどの基本的な操作について解説しています。
全文翻訳
Python Polars: 決定版チートシート
Polars は、高速で表現力豊かな DataFrame API を用いてデータを変換、分析、可視化するためのライブラリです。2020年に Ritchie Vink によって初めてリリースされました。
ターミナルから、Polars をすべてのオプション依存関係とともにインストールします。
uv pip install "polars[all]"
Python で Polars をインポートし、インストールされている Polars とその依存関係のバージョンを確認します。
import polars as pl
pl.show_versions()
Polars のクエリは通常、データを読み込み、変換し、結果を書き出します。完全なクエリは、メソッド呼び出しの単一チェーンであることがよくあります。
fruit = pl.read_csv("fruit.csv")
fruit.filter(
(pl.col("weight") > 1000) & pl.col("is_round")
).write_parquet("fruit.parquet")
このチートシート全体を通して、df は DataFrame、lf は LazyFrame、o は df と結合する2番目の DataFrame、e は任意の式を表します。したがって、e.abs() は式に対して .abs() を呼び出すことを意味します。例えば pl.col("x").abs() のような場合です。
データ構造#
Polars はすべてのデータを Series または DataFrame のいずれかに格納します。
| 構造 | 説明 |
|---|---|
Series | 一次元。同じデータ型の値のシーケンスを保持します。 |
DataFrame | 二次元。行と列を持ちます。1つ以上の Series で構成され、すべて同じ長さです。 |
LazyFrame | DataFrame に似ていますが、データは保持しません。DataFrame を生成するための設計図です。 |
pandas とは異なり、Polars DataFrame には行インデックスがなく、API はインプレース(その場での)変更よりも不変性とメソッドチェーンを重視します。
-
名前と値のシーケンスを渡して Series を作成します。
series = pl.Series("sales", [150.00, 300.00, 250.00]) -
各値が Series または通常の Python シーケンスである列の辞書から DataFrame を作成します。
pl.read_*()関数を使用してファイルから作成することもできます。df = pl.DataFrame({ "sales": series, "id": [41, 42, 43] }) -
行インデックスがないため、必要に応じて明示的に列として追加します。
df.with_row_index("id") -
DataFrame を LazyFrame に変換します。あるいは、
pl.scan_*()関数から直接 LazyFrame として開始します。lf = df.lazy()
Eager と Lazy API#
Eager API は即座に実行されますが、Lazy API は最適化されたクエリプランを最初に構築します。オプティマイザは、述語プッシュダウン(可能な限り早期にフィルタリング)と射影プッシュダウン(使用されない列の削除)を自動的に適用します。
.lazy() と .collect() を使用して、2つの表現間を移動します。.lazy() は DataFrame を LazyFrame に変換し、.collect() は LazyFrame を実行して DataFrame を返します。
-
DataFrame を LazyFrame に変換し、LazyFrame を実行して DataFrame を取得します。
lf = df.lazy() df = lf.collect() -
ストリーミングエンジンを使用して、メモリ外のデータを処理するため、メモリよりも大きいデータセットも処理できます。
lf.collect(engine="streaming") -
最適化されたクエリプランをテキストとして表示するか、グラフとして視覚化して、オプティマイザが何を行ったかを確認します。
lf.explain() lf.show_graph() -
クエリを実行し、ノードごとのタイミングを返します。これにより、実際の処理時間がどこにかかっているかがわかります。
lf.profile()
データ型#
Polars は、フラットおよび階層データの効率的な列指向フォーマットである Apache Arrow メモリ仕様のほとんどを実装しています。
| グループ | 型 | メモ |
|---|---|---|
| 数値 | Decimal | 128 ビット、精度、スケール |
Float32 | 範囲 ±3.4×10³⁸ | |
Float64 | 範囲 ±1.8×10³⁰⁸ | |
Int8 | 範囲 ±128 | |
Int16 | 範囲 ±32,768 | |
Int32 | 範囲 ±2.1×10⁹ | |
Int64 | 範囲 ±9.2×10¹⁸ | |
Int128 | 範囲 ±3.4×10³⁸ | |
UInt8 | 範囲 0–255 | |
UInt16 | 範囲 0–65,535 | |
UInt32 | 範囲 0–4.3×10⁹ | |
UInt64 | 範囲 0–1.8×10¹⁹ | |
| 時系列 | Date | Unix エポックからの日数 |
Datetime | Unix エポックからのマイクロ秒 | |
Duration | 時間間隔 / デルタ | |
Time | 1日のうちの時間 | |
| ネスト | Array | 固定長シーケンス |
List | 可変長シーケンス | |
Struct | 名前付きの複数のフィールド | |
| 文字列 | String | UTF-8 テキスト、可変長 |
Categorical | 文字列の辞書 | |
Enum | 文字列の固定辞書 | |
| その他 | Boolean | True / False |
Binary | 生バイト | |
Null | Null / None を表す |
型の検査#
-
列名とデータ型の辞書、またはデータ型のみのリストを取得します。
df.schema df.dtypes -
列ごとに1行で、データ型を含めて表示します。これは、DataFrame 自体の表示が読みにくい幅広の DataFrame に便利です。
df.glimpse() -
null の数を含む、列ごとの要約統計量を計算します。
df.describe() -
DataFrame のメモリ内サイズを指定した単位で報告します。
df.estimated_size("mb")
キャスティング#
-
列を別のデータ型にキャストします。デフォルトでは、キャストは厳密であるため、適合しない値はエラーを発生させます。
df.select(pl.col("id").cast(pl.UInt64)) -
strict=Falseを渡して、エラーを発生させずにキャストします。ターゲット型に収まらない値は、代わりに null になります。df.select(pl.col("id").cast(pl.Int8, strict=False))
データの読み書き#
Polars には4つの入力および出力関数のファミリーがあり、どちらが必要かは Eager で作業しているか Lazy で作業しているかによって異なります。
read_*()はデータを DataFrame に読み込みます。scan_*()は LazyFrame を作成し、実際の読み込みを collect まで遅延させます。write_*()は DataFrame をディスクまたはクラウドストレージに書き込みます。sink_*()はすべてのデータをメモリに保持せずに、ディスクまたはクラウドストレージにストリーミングします。
すべてのフォーマットが4つの操作すべてをサポートしているわけではありません。
| フォーマット | read | scan | write | sink |
|---|---|---|---|---|
| Avro | ✓ | ✓ | ||
| Clipboard | ✓ | ✓ | ||
| CSV | ✓ | ✓ | ✓ | ✓ |
| Database | ✓ | ✓ | ||
| Delta Lake | ✓ | ✓ | ✓ | ✓ |
| Excel / ODS | ✓ | ✓ | ||
| Iceberg | ✓ | ✓ | ✓ | |
| IPC / Feather | ✓ | ✓ | ✓ | ✓ |
| JSON | ✓ | ✓ | ||
| NDJSON | ✓ | ✓ | ✓ | ✓ |
| Parquet | ✓ | ✓ | ✓ | ✓ |
| PyArrow Dataset | ✓ |
これらの多くの関数が受け入れるキーワード引数には、schema_overrides、n_rows、row_index_name、storage_options、compression があります。
-
URI に glob パターンを渡してクラウドストレージのファイルをスキャンし、
storage_optionsを使用して認証情報とリージョン設定を提供します。pl.scan_parquet( "s3://bucket/*.parquet", storage_options={"aws_region": "us-east-2"} ) -
クエリをパーティション化された Parquet データセットに直接ストリーミングし、キー列の各一意の値ごとに1つのディレクトリを書き込みます。
lf.sink_parquet(pl.PartitionBy("out/", key="x"))
データ変換#
列の選択#
名前、データ型、または位置に基づいて列を保持します。
-
名前で列を選択します。
df.select("a", "b") -
式の結果を選択し、出力時に列を変換できるようにします。
df.select(pl.col("x") * 2) -
キーワード引数を使用して、式の結果に名前を付けます。これにより、新しい列が生成されます。
df.select(doubled=pl.col("x") * 2) -
正規表現に一致する列名を選択します。パターンは
^で始まり$で終わる必要があります。df.select(pl.col("^.*_color$")) -
すべての列を選択します。
df.select(pl.all())
より柔軟にするには、列セレクターを使用します。これらは、セット演算子 |、&、-、^、~ を使用して組み合わせることができます。
-
セレクターモジュールをインポートし、データ型または名前パターンで列を選択します。
cs.string()、cs.contains()、cs.first()も参照してください。import polars.selectors as cs df.select(cs.numeric()) df.select(cs.starts_with("val")) -
列を保持する代わりに削除します。存在しない名前がエラーを発生させる代わりに無視されるように、
strict=Falseを渡します。df.drop("a", "y", strict=False)
列の作成#
新しい列は既存の列の右側に追加されます。
-
式から計算された新しい列を追加し、キーワード引数で名前を付けます。
df.with_columns(new=pl.col("a") + 1) -
同じ名前の式を生成して既存の列を置き換えます。ここでは、列
aの null がゼロに置き換えられます。df.with_columns(pl.col("a").fill_null(0)) -
すべての行に同じリテラル値を持つ列を追加します。
df.with_columns(ones=pl.lit(1)) -
行インデックスの列を追加します。ゼロ以外のオフセットからカウントを開始するには、
offsetを使用します。df.with_row_index(name="id", offset=1)
行のフィルタリング#
1つ以上の列または式の値に従って行を保持します。
-
既存のブール列の名前を渡してフィルタリングします。
df.filter("valid") -
単一の式でフィルタリングします。
df.filter(pl.col("x") > 5) -
複数の式を渡して、論理 AND で結合します。
&で明示的に AND を記述することもできます。この場合、各比較には独自の括弧が必要です。df.filter(pl.col("valid"), pl.col("x") > 5) df.filter(pl.col("valid") & (pl.col("x") > 5)) -
論理 OR には
|を使用します。df.filter(pl.col("valid") | (pl.col("x") > 5)) -
キーワード引数制約でフィルタリングします。これは、等価性をテストし、結果を AND で結合するショートカットです。
df.filter(valid=True, x=5) -
欠損値のない行のみを保持するか、特定の列にチェックを制限します。
df.drop_nulls() df.drop_nulls("x") -
重複行を削除します。重複を定義する列を決定するために
subsetを使用し、重複のうちどれを残すかを選択するためにkeepを使用します。df.unique(subset=["x"], keep="first")
行のスライスとサンプリング#
位置に基づいて行を保持します。
-
最初の数行、または最後の数行を保持します。どちらもデフォルトは5です。
df.head() df.tail(10) -
オフセットと長さを指定して、連続したスライスを保持します。これは、3行目から7行目を保持します。
df.slice(2, 5) -
N番目の行をすべて保持します。
df.gather_every(2) -
行のランダムなサンプルを取得します。同じ行が複数回描画されることを許可するには
with_replacement=Trueを使用するか、固定数ではなく割合をサンプリングするにはfractionを使用します。df.sample(10) df.sample(10, with_replacement=True) df.sample(fraction=0.2)
行のソート#
1つ以上の列または式の値に従って行を並べ替えます。
-
単一の列で昇順(デフォルト)にソートするか、複数の列で順番にソートします。
df.sort("x") df.sort("x", "y") -
null を先頭ではなく末尾に移動します。
df.sort("x", nulls_last=True) -
順序を反転します。複数の列でソートする場合、ブール値のリストを渡して列ごとの方向を設定します。
df.sort("x", descending=True) df.sort("x", "y", descending=[False, True]) -
列ではなく、計算された比率やリストの長さなどの式の結果でソートします。
df.sort(pl.col("x") / pl.col("y")) df.sort(pl.col("l").list.len()) -
すべてをソートしてからスライスするよりも安価な、列に従って k 個の最大または最小の行のみを保持します。
df.top_k(5, by="score") df.bottom_k(5, by="score")
リシェイピング#
ワイドからロングへ、またはその逆へ移行します。
-
1つ以上の列の値を新しい行に変換することで DataFrame を長くします。
index列を識別子として保持します。df.unpivot(on=["c"], index="id") -
列の値を新しい列に変換することで DataFrame を広くします。
onとindexの組み合わせが一意でない場合は、aggregate_functionを指定して衝突をどのように結合するかを決定します。df.pivot(on="c", index="id", values="x") df.pivot(on="c", index="id", values="x", aggregate_function="sum") -
リスト列を展開して、各要素が独自の行になるようにし、他の列を繰り返します。
df.explode("l") -
構造体(struct)列を展開して、各フィールドが独自の列になるようにします。
df.unnest("s") -
行と列を入れ替えます。元の列名を列として保持するには
include_header=Trueを使用します。df.transpose(include_header=True) -
DataFrame を小さな DataFrame のリストに分割します。指定された列の一意の値ごとに1つの DataFrame が生成されます。
df.partition_by("group")
要約と集計#
分割。適用。結合。
-
1つ以上の列で DataFrame をグループに分割します。これにより
GroupByオブジェクトが得られ、その後集計します。dfg = df.group_by("x") dfg = df.group_by("x", "y") -
各グループに既製の要約を適用します。グループごとの行数をカウントし、各グループの最初の行を取得するか、グループごとの各列の平均を計算します。
dfg.len() dfg.head(2) dfg.mean() -
標準の集計が適合しない場合に、独自の関数を各グループに適用します。
dfg.map_groups(...) -
集計を完全に制御するには
agg()を使用します。集計メソッドのない式を渡すと値がリストに収集され、キーワード引数で結果に名前を付けると、新しい列に適切な名前が付けられます。dfg.agg(...) dfg.agg(pl.col("y")) dfg.agg(avg=pl.col("y").mean()) -
ウィンドウ式を
over()と一緒に使用して、行を折りたたむことなく、元の DataFrame に新しい列として集計を追加します。df.with_columns(avg=pl.col("y").mean().over("x")) -
カテゴリではなく、時間値またはインデックスでグループ化します。
group_by_dynamic()は固定期間のウィンドウを作成し、group_byはその上に通常のグループ化を追加します。df.group_by_dynamic("timestamp", every="1h", group_by="store") -
固定ステップではなく、各行で移動するウィンドウには
rolling()を使用します。これは、店舗ごとの7日間の移動合計売上を計算します。df.rolling(index_column="date", period="7d", group_by="store").agg( pl.col("sales").sum() ) -
正規の時系列から欠落している行を作成し、すべての間隔が表されるようにします。
df.upsample( time_column="date", every="1d", group_by="store", maintain_order=True ) -
列を下方向に集計するのではなく、列を横断して集計します。水平関数は、各行内で複数の列を結合します。
df.select(pl.sum_horizontal(cs.numeric())) df.select(pl.any_horizontal(cs.boolean()))
結合と連結#
複数の DataFrame を1つに結合します。
-
共有キーで2つの DataFrame を結合します。デフォルトは内部結合(inner join)で、両側で一致する行のみを保持します。
df.join(o, on="key") -
howを使用して異なる結合戦略を選択します。左結合(left join)はdfのすべての行を保持します。df.join(o, on="key", how="left") -
キーが各 DataFrame で異なる名前の場合、両側を明示的に名前付けします。
df.join(o, left_on="a", right_on="b") -
完全外部結合(full outer join)は両側のすべての行を保持します。
coalesce=Trueを追加して、2つのキー列を1つにマージします。df.join(o, on="key", how="full", coalesce=True) -
フィルタリング結合は
dfの列のみを返し、oをフィルターとしてのみ使用します。セミ結合(semi join)は一致するdfの行を保持し、アンチ結合(anti join)は一致しない行を保持します。df.join(o, on="key", how="semi") df.join(o, on="key", how="anti") -
クロス結合(cross join)は両方の DataFrame のデカルト積を生成するため、キーは不要です。
df.join(o, how="cross") -
最近接一致で結合します。正確な一致ではなく、通常は2つの時系列を一致させる方法です。
byを使用して、まず一部の列で正確に一致させます。df.join_asof(o, on="ts", by="i") -
不等号やその他の非等価結合のために、任意の述語で結合します。
df.join_where(o, pl.col("a") >= pl.col("b"))
df.join() の一般的なキーワード引数には、left_on、right_on、coalesce、join_nulls、suffix、validate があります。validate は `