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

素晴らしいテーブル plotnine | Python Python Polars: 決定版チートシート Python Polars を使用したデータの変換、分析、可視化のためのクイックリファレンスガイド 詳細はこちら... Jeroen Janssens, Thijs Nieuwdorp PDFをダウンロード 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は結合するための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_*() 関数を使用してファイルからDataFrameを作成することもできます： df = pl.DataFrame({ "sales": series, "id": [41, 42, 43] }) 行インデックスがないため、必要な場合は明示的に列として追加します： df.with_row_index("id") DataFrameをLazyFrameに変換します。または、pl.scan_*() 関数から直接LazyFrameを開始します： lf = df.lazy() Eager APIと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 String UTF-8テキスト、可変長 Categorical 文字列の辞書 Enum 固定長の辞書 Other 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つの操作すべてをサポートしているわけではありません： フォーマット 読み込み スキャン 書き込み シンク Avro ✓ ✓ クリップボード ✓ ✓ CSV ✓ ✓ ✓ ✓ データベース ✓ ✓ Delta Lake ✓ ✓ ✓ ✓ Excel / ODS ✓ ✓ Iceberg ✓ ✓ ✓ IPC / Feather ✓ ✓ ✓ ✓ JSON ✓ ✓ NDJSON ✓ ✓ ✓ ✓ Parquet ✓ ✓ ✓ ✓ PyArrow Dataset ✓ これらの関数の多くが受け入れるキーワード引数には、schema_overrides、n_rows、row_index_name、storage_options、compressionなどがあります。 globパターンを含むURIを渡してクラウドストレージのファイルをスキャンし、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で結合します。明示的に&で記述することもできます。その場合、各比較には独自の括弧が必要です： df.filter(pl.col("valid"), pl.col("x")