vaex

Vaex

概要

Vaex は、RAM に収まらない大規模な表形式データセットを処理・可視化するために設計された、遅延評価とアウトオブコア処理に対応する高性能な Python ライブラリです。Vaex は毎秒 10 億行以上を処理でき、数十億行のデータセットをインタラクティブに探索・分析できます。

インストール

完全版のメタパッケージをインストールします（推奨）：

uv pip install vaex

最小限のインストール（必要なものだけを選択）：

uv pip install vaex-core vaex-viz vaex-hdf5 vaex-ml

vaex パッケージはメタパッケージであり、vaex-core、vaex-viz、vaex-hdf5、vaex-ml などのサブパッケージをインストールします。Arrow のサポートは vaex-core に組み込まれています（個別の vaex-arrow パッケージは非推奨です）。vaex-distributed は非推奨となり、vaex-enterprise が推奨されています。

バージョンに関する注意（vaex 4.19.0+）： Python 3.12 および NumPy v2 では、vaex >= 4.19.0 が必要です。Windows では、annoy 依存関係のビルドに Python の開発用ヘッダーが必要になる場合があります。

このスキルを使う場面

次のような場合に Vaex を使います：

• 使用可能な RAM を超える表形式データセット（ギガバイトからテラバイト）の処理
• 大規模なデータセットに対する高速な統計集計の実行
• 大規模データセットの可視化やヒートマップの作成
• ビッグデータを対象とする機械学習パイプラインの構築
• データ形式（CSV、HDF5、Arrow、Parquet）間の変換
• メモリーのオーバーヘッドを避けるための遅延評価や仮想列の利用
• 天文データ、金融時系列データ、その他の大規模な科学データセットの処理

Vaex と代替ツールの比較： データが RAM に収まり、インメモリーで最高速度が必要な場合は polars を使います。クラスター上で pandas/NumPy を分散処理する必要がある場合は dask を使います。メモリーマップされた HDF5/Arrow ファイルを使って、RAM を超える表形式データを単一マシンでアウトオブコア分析する場合は vaex を使います。

主な機能

Vaex には主に 6 つの機能領域があり、それぞれの詳細は references ディレクトリに記載されています。

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

ファイル（HDF5、CSV、Arrow、Parquet）、pandas DataFrame、NumPy 配列、辞書など、さまざまなソースから Vaex DataFrame を読み込み、作成します。次の項目については references/core_dataframes.md を参照してください：

• 大容量ファイルを効率よく開く
• pandas/NumPy/Arrow からの変換
• サンプルデータセットの使用
• DataFrame の構造の理解

2. データ処理と操作

すべてのデータをメモリーに読み込まずに、フィルタリング、仮想列の作成、式の使用、データの集計を行います。次の項目については references/data_processing.md を参照してください：

• フィルタリングと選択
• 仮想列と式
• Groupby 操作と集計
• 文字列操作と日時の処理
• 欠損データの処理

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

Vaex の遅延評価、キャッシュ戦略、メモリー効率の高い操作を活用します。次の項目については references/performance.md を参照してください：

• 遅延評価の理解
• delay=True を使った操作のバッチ処理
• 必要に応じた列の実体化
• キャッシュ戦略
• 非同期操作

4. データの可視化

ヒートマップ、ヒストグラム、散布図など、大規模データセットのインタラクティブな可視化を作成します。次の項目については references/visualization.md を参照してください：

• 1D および 2D プロットの作成
• ヒートマップによる可視化
• 選択の操作
• プロットとサブプロットのカスタマイズ

5. 機械学習との連携

トランスフォーマーやエンコーダーを使い、scikit-learn、XGBoost、その他のフレームワークと連携する ML パイプラインを構築します。次の項目については references/machine_learning.md を参照してください：

• 特徴量のスケーリングとエンコード
• PCA と次元削減
• K-means クラスタリング
• scikit-learn/XGBoost/CatBoost との連携
• モデルのシリアライズとデプロイ

6. I/O 操作

さまざまな形式のデータを最適なパフォーマンスで効率よく読み書きします。次の項目については references/io_operations.md を参照してください：

• ファイル形式の推奨事項
• エクスポート戦略
• Apache Arrow の使用
• 大容量ファイルの CSV 処理
• サーバーとリモートデータへのアクセス

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

ほとんどの Vaex タスクでは、次のパターンに従います：

import vaex

# 1. Open or create DataFrame
df = vaex.open('large_file.hdf5')  # or .csv, .arrow, .parquet
# OR
df = vaex.from_pandas(pandas_df)

# 2. Explore the data
print(df)  # Shows first/last rows and column info
df.describe()  # Statistical summary

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

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

# 5. Compute statistics (fast, lazy evaluation)
mean_val = df.x.mean()
stats = df.groupby('category').agg({'value': 'sum'})

# 6. Visualize (df.viz is the recommended accessor since vaex 4.0)
df.viz.heatmap(df.x, df.y, limits='99.7%', show=True)
# Legacy: df.plot1d() and df.plot() still work on the DataFrame

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

リファレンスの活用

リファレンスファイルには、各機能領域に関する詳細情報が記載されています。具体的なタスクに応じて、リファレンスをコンテキストに読み込んでください。

• 基本操作：まず references/core_dataframes.md と references/data_processing.md を確認してください
• パフォーマンスの問題：references/performance.md を確認してください
• 可視化タスク：references/visualization.md を使用してください
• ML パイプライン：references/machine_learning.md を参照してください
• ファイル I/O：references/io_operations.md を確認してください

ベストプラクティス

1. 大規模データセットで最適なパフォーマンスを得るには、HDF5 または Apache Arrow 形式を使用してください
2. メモリを節約するため、データを実体化する代わりに仮想列を活用してください
3. 複数の計算を行う場合は、delay=True を使用して処理をまとめてください
4. データを CSV のまま保持するのではなく、効率的な形式にエクスポートしてください
5. 中間データを保存せずに複雑な計算を行うには、式を使用してください
6. df.describe() と df.nbytes でプロファイリングし、データの形状とメモリ使用量を把握してください

よくあるパターン

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

import vaex

# Open large CSV lazily (vaex 4.14+), or use from_csv to convert to HDF5
df = vaex.open('large_file.csv')
# df = vaex.from_csv('large_file.csv', convert='large_file.hdf5')

# Export to HDF5 for faster future access
df.export_hdf5('large_file.hdf5')

# Future loads are instant
df = vaex.open('large_file.hdf5')

パターン：効率的な集計

# Use delay=True to batch multiple operations
mean_x = df.x.mean(delay=True)
std_y = df.y.std(delay=True)
sum_z = df.z.sum(delay=True)

# Execute all at once
results = vaex.execute([mean_x, std_y, sum_z])

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

# 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

リソース

このスキルには、references/ ディレクトリにリファレンスドキュメントが含まれています。

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

エージェントの作業手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを確定します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 サンプルまたは単一のフォールドで実行し、実行時間とメモリを確認します。
4. 上記の指示とリファレンスを使用して、タスク全体を実行します。
5. 結果を検証します。 ホールドアウトデータ、固定した乱数シード、適切な指標を使用し、データリークを確認して、不確実性（CI、シード間の標準偏差）を報告します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の点を明記します。

これが発生した場合	対応
メモリ不足または実行が非常に遅い	サブサンプリング、チャンク処理または遅延計算の使用、モデルサイズの縮小を行い、変更内容をユーザーに伝えます。
インストール済みのバージョンに、この指示にある関数、フラグ、エンドポイントがない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えてください。
• このセッションで計算していない指標を報告してはいけません。すべての数値について、その算出に使用したコード経路を示してください。
• ここにあるバージョン固有の詳細は古くなっている可能性があります。インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する、共有 GPU またはクラウドのクォータを消費する、個人データまたは患者データを扱う、あるいは取り消せない操作を行う場合は、事前に確認してください。

関連スキル

• polars：Python 向けの高性能 DataFrame ライブラリ。ETL、分析、pandas からの移行に使用します。
• polars-bio：Arrow と DataFusion を基盤とし、Polars DataFrame 上でのゲノム区間操作とバイオインフォマティクスのファイル I/O に対応する Python ライブラリ polars-bio。
• dask：メモリに収まらない規模の pandas／NumPy ワークフロー向け分散コンピューティング。