---

functime 是一个功能强大的 Python 库，用于在 大型面板数据集 上进行生产就绪的 全局预测 和 时间序列特征提取。

functime 还配备了时间序列 预处理（Box-Cox 变换、差分等）、交叉验证 拆分器（扩展窗口和滑动窗口）以及预测 指标（MASE、SMAPE 等）。所有这些都优化为 懒加载 Polars 转换。

欢迎加入我们的 Discord！

亮点

• 快速： 在您的笔记本电脑上，几秒钟内即可对 10 万个时间序列进行预测和特征提取（例如 tsfresh、Catch22）
• 高效： 使用 Polars 对时间序列进行并行特征工程
• 久经考验： 提供实际业务价值并屡获竞赛冠军的机器学习算法
• 外生特征： 每个预测器均支持外生特征
• 回测： 支持扩展窗口和滑动窗口拆分器
• 自动滞后和超参数调优： 使用 FLAML

其他亮点

functime 配备了一个专门的 LLM 代理，用于分析、描述和比较您的预测结果。请参阅这里的操作指南 这里。

开始使用

通过 pip 包管理器安装 functime。

pip install functime

functime 还提供额外的选项。例如，要安装带有大语言模型 (LLM) 和 lightgbm 特征的 functime：

pip install "functime[llm,lgb]"

• cat: 使用 catboost 预测器
• xgb: 使用 xgboost 预测器
• lgb: 使用 lightgbm 预测器
• llm: 使用由 LLM 驱动的预测分析师

预测

import polars as pl
from functime.cross_validation import train_test_split
from functime.seasonality import add_fourier_terms
from functime.forecasting import linear_model
from functime.preprocessing import scale
from functime.metrics import mase

# 加载大宗商品价格数据
y = pl.read_parquet("https://github.com/functime-org/functime/raw/main/data/commodities.parquet")
entity_col, time_col = y.columns[:2]

# 时间序列拆分
y_train, y_test = y.pipe(train_test_split(test_size=3))

# 拟合-预测
forecaster = linear_model(freq="1mo", lags=24)
forecaster.fit(y=y_train)
y_pred = forecaster.predict(fh=3)

# functime ❤️ 函数式设计
# 拟合-预测一步完成
y_pred = linear_model(freq="1mo", lags=24)(y=y_train, fh=3)

# 并行评估预测结果
scores = mase(y_true=y_test, y_pred=y_pred, y_train=y_train)

# 使用目标变换和特征变换进行预测
forecaster = linear_model(
    freq="1mo",
    lags=24,
    target_transform=scale(),
    feature_transform=add_fourier_terms(sp=12, K=6)
)

# 使用外生回归量进行预测！
# 只需将它们传递给 X 即可
X = (
    y.select([entity_col, time_col])
    .pipe(add_fourier_terms(sp=12, K=6)).collect()
)
X_train, X_future = y.pipe(train_test_split(test_size=3))
forecaster = linear_model(freq="1mo", lags=24)
forecaster.fit(y=y_train, X=X_train)
y_pred = forecaster.predict(fh=3, X=X_future)

完整的预测操作指南请参见 这里。

特征提取

functime 提供超过 100 种 时间序列特征提取器。每个特征都可以通过 functime 的自定义 ts（时间序列）命名空间轻松访问，该命名空间适用于任何 Polars Series 或表达式。要在模块中注册自定义的 ts Polars 命名空间，您必须先导入 functime。

要注册自定义的 ts Polars 命名空间，您必须先导入 functime！

import polars as pl
import numpy as np
from functime.feature_extractors import FeatureExtractor, binned_entropy

# 加载大宗商品价格数据
y = pl.read_parquet("https://github.com/functime-org/functime/raw/main/data/commodities.parquet")

# 获取列名（“商品类型”、“时间”、“价格”）
entity_col, time_col, value_col = y.columns

# 从单个时间序列中提取单个特征
binned_entropy = binned_entropy(
    pl.Series(np.random.normal(0, 1, size=10)),
    bin_count=10
)

# 🔥 同样适用于具有查询优化的 LazyFrames
features = (
    pl.LazyFrame({
        "index": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
        "value": np.random.normal(0, 1, size=10)
    })
    .select(
        binned_entropy=pl.col("value").ts.binned_entropy(bin_count=10),
        lempel_ziv_complexity=pl.col("value").ts.lempel_ziv_complexity(threshold=3),
        longest_streak_above_mean=pl.col("value").ts.longest_streak_above_mean(),
    )
    .collect()
)

# 🚄 在多个堆叠的时间序列上以极快的速度提取特征
# 使用 `group_by`
features = (
    y.group_by(entity_col)
    .agg(
        binned_entropy=pl.col(value_col).ts.binned_entropy(bin_count=10),
        lempel_ziv_complexity=pl.col(value_col).ts.lempel_ziv_complexity(threshold=3),
        longest_streak_above_mean=pl.col(value_col).ts.longest_streak_above_mean(),
    )
)

# 🚄 在多个时间序列的窗口上以极快的速度提取特征
# 使用 `group_by_dynamic`
features = (
    # 按年度间隔计算滚动特征
    y.group_by_dynamic(
        time_col,
        every="12mo",
        by=entity_col,
    )
    .agg(
        binned_entropy=pl.col(value_col).ts.binned_entropy(bin_count=10),
        lempel_ziv_complexity=pl.col(value_col).ts.lempel_ziv_complexity(threshold=3),
        longest_streak_above_mean=pl.col(value_col).ts.longest_streak_above_mean(),
    )
)

相关项目

如果您对 Polars 的通用数据科学插件感兴趣，那么一定要查看 polars-ds。polars-ds 是由 functime 的核心维护者之一创建的项目，它是将常用的数据科学操作以 Rust 极速实现并扩展到您的 Polars 流水线的最简单方式！

许可证

functime 采用 Apache-2.0 许可证发布。

functime 快速上手指南

functime 是一个强大的 Python 库，专为大规模面板数据设计，提供生产级的全局预测和时间序列特征提取功能。它基于 Polars 构建，利用惰性计算实现极速处理，能在笔记本电脑上秒级处理十万级时间序列。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.9 - 3.12
• 核心依赖：
  • polars (底层计算引擎)
  • numpy
  • scikit-learn (部分模型依赖)
  • FLAML (自动超参数调优)

注意：functime 强依赖 Polars 的惰性执行机制，建议确保安装最新版本的 Polars 以获得最佳性能。

安装步骤

使用 pip 进行基础安装：

pip install functime

如需使用特定功能（如大语言模型分析或特定 boosting 算法），可安装额外依赖：

# 安装 LLM 分析功能和 LightGBM 支持
pip install "functime[llm,lgb]"

# 其他可选组件
# pip install "functime[cat]"   # CatBoost 支持
# pip install "functime[xgb]"   # XGBoost 支持

国内加速建议：如果下载速度较慢，推荐使用国内镜像源：

pip install functime -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 快速预测 (Forecasting)

以下示例展示如何加载数据、划分训练集/测试集，并使用线性模型进行预测。

import polars as pl
from functime.cross_validation import train_test_split
from functime.forecasting import linear_model
from functime.metrics import mase

# 加载示例数据 (商品价格指数)
y = pl.read_parquet("https://github.com/functime-org/functime/raw/main/data/commodities.parquet")
entity_col, time_col = y.columns[:2]

# 划分时间序列训练集和测试集 (最后 3 期作为测试)
y_train, y_test = y.pipe(train_test_split(test_size=3))

# 初始化并训练模型 (频率为月度，滞后 24 期)
forecaster = linear_model(freq="1mo", lags=24)
forecaster.fit(y=y_train)

# 预测未来 3 期
y_pred = forecaster.predict(fh=3)

# 函数式风格：一行代码完成拟合与预测
y_pred = linear_model(freq="1mo", lags=24)(y=y_train, fh=3)

# 并行计算评估指标 (MASE)
scores = mase(y_true=y_test, y_pred=y_pred, y_train=y_train)
print(scores)

带外生变量预测： 只需将外生特征 DataFrame 传入 X 参数即可。

from functime.seasonality import add_fourier_terms

# 构造外生特征 (傅里叶项)
X = (
    y.select([entity_col, time_col])
    .pipe(add_fourier_terms(sp=12, K=6)).collect()
)

# 划分外生变量的训练集和未来集
X_train, X_future = X.pipe(train_test_split(test_size=3))

# 训练与预测
forecaster = linear_model(freq="1mo", lags=24)
forecaster.fit(y=y_train, X=X_train)
y_pred = forecaster.predict(fh=3, X=X_future)

2. 特征提取 (Feature Extraction)

functime 提供了 100+ 种时间序列特征提取器，通过自定义的 .ts 命名空间直接集成到 Polars 中。

重要：使用前必须先 import functime 以注册命名空间。

import polars as pl
import numpy as np
import functime  # 必须导入以注册 .ts 命名空间
from functime.feature_extractors import binned_entropy

# 加载数据
y = pl.read_parquet("https://github.com/functime-org/functime/raw/main/data/commodities.parquet")
entity_col, time_col, value_col = y.columns

# 场景 A: 对单个序列提取特征
single_series = pl.Series(np.random.normal(0, 1, size=10))
entropy_val = binned_entropy(single_series, bin_count=10)

# 场景 B: 在 LazyFrame 上高效提取多个特征 (利用查询优化)
features = (
    pl.LazyFrame({
        "index": range(10),
        "value": np.random.normal(0, 1, size=10)
    })
    .select(
        binned_entropy=pl.col("value").ts.binned_entropy(bin_count=10),
        lempel_ziv_complexity=pl.col("value").ts.lempel_ziv_complexity(threshold=3),
        longest_streak_above_mean=pl.col("value").ts.longest_streak_above_mean(),
    )
    .collect()
)

# 场景 C: 对大规模分组数据并行提取特征 (最常用)
features = (
    y.group_by(entity_col)
    .agg(
        binned_entropy=pl.col(value_col).ts.binned_entropy(bin_count=10),
        lempel_ziv_complexity=pl.col(value_col).ts.lempel_ziv_complexity(threshold=3),
        longest_streak_above_mean=pl.col(value_col).ts.longest_streak_above_mean(),
    )
)
print(features.head())

通过以上步骤，您可以快速开始使用 functime 进行高性能的时间序列分析与建模。更多高级用法（如自动调参、LLM 分析报告）请参考官方文档。