alterlab-vaex

Vaex

概述

Vaex 是一个用于惰性、外存 DataFrame 的 Python 库：它通过内存映射读取 HDF5/Arrow 文件，惰性计算表达式，并在 N 维网格上快速计算统计数据，足以在单机上交互式处理数十亿行数据。

维护状态（请先阅读）

Vaex 实际上已进入最低限度维护模式。在项目的“Vaex 是否活跃？”讨论（vaexio/vaex #2363，2024 年 6 月）中，一位核心开发者表示自己已不再参与，另一位则只承诺“尽力至少发布 vaex 版本”。发布速度已放缓至大约每年一次（vaex-core 4.18 于 2024 年 10 月发布，4.19 于 2025 年 9 月发布）；4.19 仍仅支持 Python 3.9–3.12，并要求 pandas<3；二维 matplotlib 绘图在 matplotlib ≥ 3.9 时会出错。实际影响如下：

• 现有 Vaex 代码：在固定版本的 Python 3.12 环境中（如下）继续运行，并规划迁移。
• 新项目：默认使用 Polars（alterlab-polars）——pl.scan_parquet(...) 加上 collect(engine="streaming") 可以满足大多数超出内存容量的聚合任务；对于集群则使用 Dask（alterlab-dask）。只有当 Vaex 的特定优势（内存映射 HDF5、对超大表进行快速分箱统计/可视化）很重要，且用户接受环境限制时，才建议在新项目中使用 Vaex。

何时使用此技能

当用户希望执行以下操作时，使用此技能：

• 运行、调试或扩展现有 Vaex 工作流（vaex.open、虚拟列、选择、vaex.ml）。
• 打开超出内存容量的内存映射 HDF5/Arrow 文件，并快速计算聚合或分箱统计。
• 使用 delay=True / df.execute() 在一次遍历中批量执行多个聚合。
• 将大型 CSV 转换为 HDF5/Arrow/Parquet，或将 Vaex 工作流迁移到 Polars。

不适用场景

场景	改用
没有现有 Vaex 代码的新超内存容量分析项目，或 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 提供六大功能领域，分别记录在 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。Booster 和 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 统计操作可合并为单个延迟查询中的一个 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 套件。