alterlab-vaex

Vaex

概要

Vaex は、遅延評価とメモリ外処理に対応した DataFrame 用 Python ライブラリです。HDF5／Arrow ファイルをメモリマップし、式を遅延評価して、1 台のマシン上で数十億行を対象とする N 次元グリッドの統計量を、対話的な作業に十分な速度で計算します。

メンテナンス状況（最初にお読みください）

Vaex は実質的に最小限のメンテナンスモードです。プロジェクトの「Is Vaex active?」ディスカッション（vaexio/vaex #2363、2024 年 6 月）で、コア開発者の 1 人はもう関与していないと述べ、もう 1 人は「少なくとも vaex のリリースを出せるよう最善を尽くす」とだけ約束しました。リリース頻度はおよそ年 1 回まで落ちており（vaex-core 4.18 は 2024 年 10 月、4.19 は 2025 年 9 月）、4.19 でも Python 3.9～3.12 と pandas<3 のみをサポートしています。また、2 次元の matplotlib プロットは matplotlib ≥ 3.9 で動作しません。実用上の影響は次のとおりです。

• 既存の Vaex コード：以下のように固定した Python 3.12 環境で動作させ、移行を計画してください。
• 新規プロジェクト：デフォルトでは Polars（alterlab-polars）を使用してください。pl.scan_parquet(...) と collect(engine="streaming") の組み合わせで、ほとんどの RAM を超えるデータの集計に対応できます。クラスターには Dask（alterlab-dask）を使用してください。Vaex の特有の強み（メモリマップされた HDF5、巨大なテーブルの高速なビン集計／可視化）が重要で、ユーザーが環境上の制約を受け入れる場合に限り、新規作業で Vaex を推奨してください。

このスキルを使用する場面

ユーザーが次のことを希望している場合に、このスキルを使用してください。

• 既存の Vaex パイプライン（vaex.open、仮想列、選択、vaex.ml）を実行、デバッグ、または拡張する。
• RAM を超えるメモリマップされた HDF5／Arrow ファイルを開き、高速な集計またはビン集計を行う。
• delay=True／df.execute() を使用して、複数の集計を 1 回のパスでまとめて実行する。
• 大容量の CSV を HDF5／Arrow／Parquet に変換する、または Vaex のワークフローを Polars に移植する。

対象外

シナリオ	代わりに使用
既存の Vaex コードがなく、RAM を超えるデータを扱う新規分析プロジェクト、または Python 3.13 以降／pandas 3 の環境	alterlab-polars
データがメモリに収まり、最速のインメモリ groupby／結合が目的の場合	alterlab-polars
マルチノードクラスターでの実行、タスクグラフ、または分散スケジューラーのダッシュボード	alterlab-dask
ディスクまたはクラウドオブジェクトストア上の、テーブルではないチャンク化された N 次元科学配列	alterlab-zarr

インストール

# Dedicated environment — vaex 4.19 has no wheels for Python 3.13+ and requires pandas < 3
uv venv --python 3.12 .venv-vaex
uv pip install --python .venv-vaex "vaex==4.19.*"
uv pip install --python .venv-vaex "matplotlib<3.9"   # only if you need df.viz.heatmap

主な機能

Vaex には 6 つの機能分野があり、それぞれ references/ にドキュメントがあります。

1. DataFrame とデータの読み込み

HDF5／Arrow／Parquet／CSV ファイルを開き、pandas／NumPy／Arrow から変換し、構造を確認します — references/core_dataframes.md。

2. データの処理と操作

フィルタリング、名前付き選択、仮想列と式、groupby／集計、文字列、日時、欠損データ — references/data_processing.md。

3. パフォーマンスと最適化

遅延評価、delay=True によるバッチ処理、実体化、キャッシュ、非同期実行 — references/performance.md。

4. データの可視化

df.viz アクセサー、選択、ウィジェットを使用して、巨大なテーブルのビンヒストグラムとヒートマップを作成します — references/visualization.md。

5. 機械学習との統合

vaex.ml のスケーラー、エンコーダー、PCA、k-means、scikit-learn／XGBoost／LightGBM／CatBoost のラッパー — references/machine_learning.md。ブースターと scikit-learn のラッパーは学習特徴量をメモリ上に実体化します。遅延状態を維持するのは変換器と予測列のみです。

6. I/O 操作

フォーマットの推奨事項、エクスポート戦略、Arrow 相互運用、チャンク化された CSV の変換、リモートデータ — references/io_operations.md。

クイックスタートのパターン

import vaex

# 1. Open or create a DataFrame
df = vaex.open('large_file.hdf5')  # or .arrow, .parquet; CSV is read (and optionally converted)
# OR
df = vaex.from_pandas(pandas_df)

# 2. Explore
print(df)          # first/last rows and column info
df.describe()      # statistical summary

# 3. Virtual columns (no memory overhead)
df['new_column'] = df.x ** 2 + df.y

# 4. Filter
df_filtered = df[df.age > 25]

# 5. Statistics (lazy, computed in passes over the data)
mean_val = df.x.mean()
stats = df.groupby('category').agg({'value': 'sum'})

# 6. Visualize (df.plot1d / df.plot are deprecated aliases of these)
df.viz.histogram(df.x, limits=[0, 100])
df.viz.heatmap(df.x, df.y, limits='99.7%')   # needs matplotlib < 3.9

# 7. Export
df.export_hdf5('output.hdf5')

ベストプラクティス

1. 大規模なデータセットにメモリマップドアクセスするには、HDF5 または Apache Arrow を使用します。Polars への移行が見込まれる場合は、最も移植性の高い Parquet を選びます。
2. データを実体化するより、仮想列を優先します。
3. 複数の統計量を計算する場合は、delay=True を指定して処理をまとめて実行します。
4. CSV を繰り返し読み込むのではなく、一度だけ HDF5／Arrow／Parquet に変換します。
5. 最適化の前に df.byte_size() でメモリ使用量を確認し、df.describe() でデータを調べます。
6. 環境（Python 3.12、vaex==4.19.*）を固定し、分析の再現性を保てるよう、結果とともに記録します。

よくあるパターン

パターン：大規模な CSV を HDF5 に変換する

import vaex

# convert=True streams the CSV in chunks to an HDF5 file next to it
df = vaex.from_csv('large_file.csv', convert=True, chunk_size=5_000_000)

# Future loads are memory-mapped and near-instant
df = vaex.open('large_file.csv.hdf5')

パターン：効率的な集計

# delay=True batches several aggregations into ONE pass over the data.
# Each delayed call returns a promise; df.execute() runs them together.
mean_x = df.mean(df.x, delay=True)
std_y = df.std(df.y, delay=True)
sum_z = df.sum(df.z, delay=True)

df.execute()
print(mean_x.get(), std_y.get(), sum_z.get())

パターン：特徴量エンジニアリングでの仮想列の使用

# No memory overhead — computed on the fly
df['age_squared'] = df.age ** 2
df['full_name'] = df.first_name + ' ' + df.last_name
df['is_adult'] = df.age >= 18

パターン：Vaex のクエリを Polars に移行する

# Vaex: df = vaex.open('big.parquet'); df['z'] = df.x ** 2 + df.y
#       df[df.x > 0.5].groupby('category').agg({'z': 'mean'})
import polars as pl

result = (
    pl.scan_parquet('big.parquet')                      # lazy, like vaex.open
    .with_columns((pl.col('x') ** 2 + pl.col('y')).alias('z'))   # virtual column
    .filter(pl.col('x') > 0.5)                          # filter
    .group_by('category').agg(pl.col('z').mean())       # groupby/agg
    .collect(engine='streaming')                        # out-of-core execution
)

Polars では Vaex の HDF5 レイアウトを直接読み込めません。df.export_parquet(...) または df.export_arrow(...) で一度エクスポートしてください。複数の delay=True による統計処理は、1 つの遅延クエリ内の select(...) にまとめられます。Polars API のその他の情報については、alterlab-polars を参照してください。

リソース

• references/core_dataframes.md — DataFrame の作成、読み込み、基本構造
• references/data_processing.md — フィルタリング、式、集計、変換
• references/performance.md — 最適化戦略と遅延評価
• references/visualization.md — プロットとインタラクティブな可視化
• references/machine_learning.md — ML パイプラインとモデルの統合
• references/io_operations.md — ファイル形式とデータのインポート／エクスポート

AlterLab Academic Skills スイートの一部です。