HN 日本語サマリー

← 一覧へ戻る
プログラミング

Python Polars チートシート(O'Reillyの書籍に基づく)

Python Polars Cheatsheet (based on our O'Reilly book) (opensource.posit.co)

158 pointsby jeroenjanssens33 コメント

要約

このチートシートは、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 で構成され、すべて同じ長さです。
LazyFrameDataFrame に似ていますが、データは保持しません。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 メモリ仕様のほとんどを実装しています。

グループ型メモ
数値Decimal128 ビット、精度、スケール
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¹⁹
時系列DateUnix エポックからの日数
DatetimeUnix エポックからのマイクロ秒
Duration時間間隔 / デルタ
Time1日のうちの時間
ネストArray固定長シーケンス
List可変長シーケンス
Struct名前付きの複数のフィールド
文字列StringUTF-8 テキスト、可変長
Categorical文字列の辞書
Enum文字列の固定辞書
その他BooleanTrue / False
Binary生バイト
NullNull / 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つの操作すべてをサポートしているわけではありません。

フォーマットreadscanwritesink
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 は `