FinceptTerminal functime Wrapper 使用指南：基于 Polars 的 40 函数机器学习时序预测与特征工程

FinceptTerminal functime Wrapper 使用指南：基于 Polars 的 40 函数机器学习时序预测与特征工程

【免费下载链接】FinceptTerminalFinceptTerminal is a modern finance application offering advanced market analytics, investment research, and economic data tools, designed for interactive exploration and>项目地址: https://gitcode.com/GitHub_Trending/fi/FinceptTerminal

本篇指南系统讲解 FinceptTerminal 中functime_wrapper的完整用法。该 wrapper 以 Polars 为数据底座，将 functime 库的 6 大类能力（机器学习预测、特征提取、预处理、交叉验证、误差指标、频率偏移）封装为 40 个统一风格、返回结构化字典的 Python 函数，可直接用于金融面板数据的多实体时序建模。读完本文，你将掌握从面板数据构造、线性/树模型预测、自动超参调优，到日历/节假日特征、滚动窗口特征、滑窗交叉验证与 9 种精度指标计算的完整实战链路，并能结合源码理解其底层实现与在 FinceptTerminal 中的两种落地形态。

概览：40 个函数、6 大模块

functime_wrapper是 functime 机器学习时序库的全面封装，以 Polars DataFrame 为数据格式，追求"开箱即用"的极速性能。其能力按 README（fincept-qt/scripts/Analytics/functime_wrapper/README.md）划分如下：

六个模块在仓库中的文件布局为（目录 fincept-qt/scripts/Analytics/functime_wrapper）：

functime_wrapper/ ├── __init__.py # 主导出（含 PEP 562 懒加载） ├── forecasting.py # ML 预测模型（18 个函数） ├── feature_extraction.py # 日历/节假日特征（4 个函数） ├── preprocessing.py # 数据变换（11 个函数） ├── cross_validation.py # CV 切分（3 个函数） ├── metrics.py # 精度指标（9 个函数） ├── offsets.py # 频率工具（1 个函数） └── README.md # 说明文档

值得留意的是，目录中还包含advanced_cv.py、advanced_models.py、anomaly_detection.py、backtesting.py、confidence_intervals.py、ensemble.py、feature_importance.py、seasonality.py以及functime_service.py等扩展文件，其中functime_service.py是面向 FinceptTerminal 界面"Functime"子标签的独立服务形态（详见后文"源码纵深的两种落地形态"）。

安装与运行环境

wrapper 依赖 functime 库与 Polars，README 指定的安装命令为：

pip install functime==0.1.10

需要说明的版本事实（源自 README 的 Version 小节与各模块源码 import 语句）：

• functime：0.1.10
• Wrapper 版本：1.0.0
• 函数总数：40
• Coverage：Complete（README 声明）
• 主要运行时依赖：polars、numpy、scipy；预测模块另依赖functime.forecasting，预处理模块在实现上以本地scipy.stats/ Polars 表达式完成（不依赖 functime 云端能力）。

快速自检

每个子模块都内置了if __name__ == "__main__":的冒烟测试入口，可直接以脚本方式运行验证环境：

python forecasting.py python preprocessing.py python feature_extraction.py python cross_validation.py python metrics.py python offsets.py

上述命令应在functime_wrapper目录下执行；各脚本会构造样例面板数据并打印各函数的关键输出（如预测 shape、滞后列名、指标均值），全部通过时输出Test: PASSED。

快速上手：面板数据构造与线性模型预测

所有预测类函数都遵循同一数据契约：面板数据 DataFrame 必须包含三列——entity_id（实体标识，如股票代码）、time（时间戳）、value（观测值），这一定义在 README Notes 中明确声明。

构造示例面板数据

import polars as pl df = pl.DataFrame({ 'entity_id': ['A'] * 10, 'time': pl.datetime_range( start=pl.datetime(2020, 1, 1), end=pl.datetime(2020, 1, 10), interval='1d', eager=True ).to_list(), 'value': [10.0, 12.0, 15.0, 14.0, 18.0, 20.0, 22.0, 21.0, 25.0, 28.0] })

三种线性模型对比

from functime_wrapper import forecast_linear_model, forecast_lasso, forecast_ridge # Linear Model（无正则化） linear_forecast = forecast_linear_model(df, fh=3, freq='1d') print(f"Linear forecast: {linear_forecast['forecast']}") # Lasso（L1 正则化，默认 alpha=1.0） lasso_forecast = forecast_lasso(df, fh=3, freq='1d', alpha=0.1) print(f"Lasso forecast: {lasso_forecast['forecast']}") # Ridge（L2 正则化，默认 alpha=1.0） ridge_forecast = forecast_ridge(df, fh=3, freq='1d', alpha=0.1) print(f"Ridge forecast: {ridge_forecast['forecast']}")

结合 forecasting.py 源码可以看到统一的设计模式：

• fit_*系列：实例化 functime 模型（如LinearModel(freq=freq)、Lasso(freq=freq, alpha=alpha)），调用model.fit(y=y_train, X=X_train)，返回含model_type、freq、alpha、fitted: True的状态字典；
• forecast_*系列：在 fit 基础上调用model.predict(fh=fh, X=X_future)，返回字典含forecast（由forecast.to_dicts()转换的列表）、shape、horizon；
• 参数签名统一为(y_train, fh, X_train=None, X_future=None, freq='1d', **model_params)，其中X_train/X_future是可选外生变量（Exogenous Variables），README 的 Key Features 明确将其列为 wrapper 能力之一。

freq支持 '1d'（日）、'1w'（周）、'1mo'（月）、'1q'（季）、'1y'（年）等频率字符串，README Notes 中亦有同样声明。

Auto 系列：FLAML 驱动的自动超参调优

当不想手工调参时，可选用 Auto 版本。6 个 Auto 模型（auto_linear_model、auto_lasso、auto_ridge、auto_elasticnet、auto_knn、auto_lightgbm）底层基于 functime 的AutoLasso、AutoRidge等类，README 明确标注其调参后端为FLAML。

from functime_wrapper import auto_lasso, auto_ridge, auto_elasticnet # Auto-tune Lasso auto_result = auto_lasso(df, fh=3, freq='1d') print(f"Best params: {auto_result['best_params']}") print(f"Forecast: {auto_result['forecast']}") # Auto-tune Ridge ridge_result = auto_ridge(df, fh=3, freq='1d') print(f"Forecast: {ridge_result['forecast']}") # Auto-tune ElasticNet elastic_result = auto_elasticnet(df, fh=3, freq='1d') print(f"Forecast: {elastic_result['forecast']}")

从 forecasting.py 第 240-352 行可见 Auto 模型的实现差异：它们不再手动fit+predict，而是直接调用model.fit_predict(y=y_train, fh=fh, X=X_train, X_future=X_future)一步完成训练与预测，并在返回字典中尝试读取model.best_params（通过hasattr(model, 'best_params')防御性取值）暴露 FLAML 搜索到的最优超参。所有 Auto 函数还接受**tuning_params透传给底层 Auto 类，可用于约束搜索空间。

预处理：Box-Cox、缩放、差分、滞后与滚动特征

预处理模块（preprocessing.py）值得特别说明：模块 docstring 明确指出其采用sklearn 风格的本地实现（本地 scipy/Polars 计算），刻意绕开 functime 的云端依赖，因此不依赖 functime 的云计算能力，更适合本地金融数据流水线。

from functime_wrapper import ( apply_boxcox, scale_data, difference_data, create_lags, create_rolling_features ) # Box-Cox 变换（lmbda=None 时自动用 MLE 求解最优 lambda） boxcox_result = apply_boxcox(df, lmbda=0.5) print(f"Transformed: {boxcox_result['transformed']}") # 缩放（standard / minmax / robust 三种方法，按 entity_id 分组计算） scaled = scale_data(df, method='standard') print(f"Scaled: {scaled['scaled']}") # 差分（order 阶差分，对齐时丢弃前 order 个时间点） diff_result = difference_data(df, order=1) print(f"Differenced: {diff_result['differenced']}") # 滞后特征（整数自动展开为 1..n 的列表，生成 lag_1/lag_2/lag_3 列并 drop 空行） lags_result = create_lags(df, lags=[1, 2, 3]) print(f"Lagged features: {lags_result['columns']}") # 滚动特征（window_sizes × stats 的组合生成 rolling_<stat>_<window> 列） rolling_result = create_rolling_features(df, window_sizes=[3, 7], stats=['mean', 'std']) print(f"Rolling features: {rolling_result['columns']}")

各函数的关键实现细节（源自源码）：

特征提取：日历效应与节假日效应

特征提取模块（feature_extraction.py）直接包装 functime 的add_calendar_effects、add_holiday_effects、make_future_calendar_effects、make_future_holiday_effects四个底层函数，用于生成星期、月份、节假日指示等外生特征。

from functime_wrapper import ( create_calendar_effects, create_holiday_effects, create_future_calendar_effects ) # 日历效应（星期、月份等；country_codes 可选） calendar = create_calendar_effects(df, freq='1d') print(f"Calendar features: {calendar['columns']}") # 节假日效应（country_codes 必填，如 'US'；freq 默认 'D'） holidays = create_holiday_effects(df, country_codes=['US'], freq='D') print(f"Holiday features: {holidays['columns']}") # 未来日期的日历特征（用于构造预测期的外生变量 X_future） future_calendar = create_future_calendar_effects(fh=7, freq='1d') print(f"Future calendar: {future_calendar['data']}")

create_future_calendar_effects与create_future_holiday_effects的典型用法是生成预测窗口内的外生变量，配合预测函数中的X_future参数使用——这是带节假日/周期外生回归的 ML 预测的标准闭环。所有特征函数统一返回{'data', 'shape', 'columns'}结构，便于下游直接检查新增列名。

交叉验证：三种切分策略

交叉验证模块（cross_validation.py）包装 functime 的train_test_split、expanding_window_split、sliding_window_split，返回的 splits 列表包含每个折的训练/测试 DataFrame 及 shape。

from functime_wrapper import ( split_train_test, create_expanding_window_splits, create_sliding_window_splits ) # 简单训练/测试划分（默认 test_size=1） split = split_train_test(df, test_size=2) print(f"Train: {split['train_shape']}, Test: {split['test_shape']}") # 扩展窗口 CV（训练集逐渐增大，默认 step=1） expanding = create_expanding_window_splits(df, test_size=1, n_splits=3) print(f"Number of splits: {expanding['n_splits']}") # 滑窗 CV（固定 train_size 的训练窗口） sliding = create_sliding_window_splits(df, train_size=5, test_size=1, n_splits=3) print(f"Number of splits: {sliding['n_splits']}")

参数语义（源码确认）：test_size为每折测试长度、n_splits为折数、step为窗口每次滑动的步长（默认 1）；create_sliding_window_splits额外要求train_size。返回结构为{'n_splits', 'splits': [{'train_shape', 'test_shape', 'train', 'test'}]}，其中 train/test 为to_dicts()后的列表，可直接传给预测函数进行滚动回测式评估。

指标评估：9 种预测精度度量

指标模块（metrics.py）包装 functime 的mae、mape、mase、mse、rmse、rmsse、smape、overforecast、underforecast，要求y_true与y_pred为同构面板 DataFrame；返回值同时给出逐实体明细（如'mae': [...]）与全面板均值（如'mean_mae'）。

from functime_wrapper import ( calculate_mae, calculate_rmse, calculate_smape, calculate_mase, calculate_overforecast ) y_true = df # 实际值 y_pred = df # 预测值（需与 y_true 同构） # MAE mae = calculate_mae(y_true, y_pred) print(f"MAE: {mae['mean_mae']}") # RMSE rmse = calculate_rmse(y_true, y_pred) print(f"RMSE: {rmse['mean_rmse']}") # SMAPE smape = calculate_smape(y_true, y_pred) print(f"SMAPE: {smape['mean_smape']}") # MASE（需要训练数据 y_train 与季节周期 sp，默认 sp=1） y_train = df mase = calculate_mase(y_true, y_pred, y_train, sp=1) print(f"MASE: {mase['mean_mase']}") # 高估比例（预测持续高于实际的程度） over = calculate_overforecast(y_true, y_pred) print(f"Overforecast: {over['mean_overforecast']}")

实现细节（源码确认）：所有指标函数通过result.select(pl.col('<metric>').mean()).item()计算面板均值；其中calculate_underforecast对可能出现的空均值做了防御处理（mean_val if mean_val is not None else 0.0），避免无低估样本时返回None。calculate_mase与calculate_rmsse需要额外的y_train与sp（seasonal period）参数，因为缩放误差以训练期的朴素一步预测误差为分母。

频率工具：频率字符串转季节周期

偏移模块（offsets.py）包装 functime 的freq_to_sp，将频率字符串转换为整数季节周期（seasonal period），可用于 MASE/RMSSE 的sp参数或 Holt-Winters 的季节长度：

from functime_wrapper import frequency_to_seasonal_period for freq in ['1d', '1w', '1mo', '1q', '1y', '1h', '30m']: result = frequency_to_seasonal_period(freq) print(f"{freq} -> seasonal period: {result['seasonal_period']}")

返回结构为{'seasonal_period': int, 'frequency': freq}，其测试入口遍历日/周/月/季/年/小时/30 分钟共 7 种频率，验证转换覆盖度。

函数参考总表

以下函数总表直接继承自 README 的 Function Reference 章节，供快速检索。

Forecasting（forecasting.py，18 个函数）

其中 Lasso/Ridge 的alpha默认值为 1.0，ElasticNet 额外有l1_ratio默认 0.5（源码确认）。

Feature Extraction（feature_extraction.py，4 个函数）

Preprocessing（preprocessing.py，11 个函数）

Cross Validation（cross_validation.py，3 个函数）

Metrics（metrics.py，9 个函数）

Offsets（offsets.py，1 个函数）

源码纵深的两种落地形态

1. PEP 562 懒加载的主导出设计

init.py 除了声明 40 个公开 API 的__all__外，采用PEP 562 懒加载机制：所有函数通过_LAZY_ATTRS映射到(子模块, 原名)，由模块级__getattr__在首次访问时importlib.import_module动态导入并缓存到globals()。源码注释说明了原因：各子模块含if __name__ == "__main__":测试块，若在包导入阶段急于全部 import，当用户以python -m方式执行子模块时，会因模块已提前进入sys.modules而触发RuntimeWarning。这一设计既保住了"from functime_wrapper import forecast_lasso即可用"的整洁公共 API，又避免了与脚本直跑方式的冲突。

2. 面向界面的 functime_service 服务层

在 wrapper 之外，目录中的 functime_service.py 是面向 FinceptTerminal 桌面端"Functime"子标签的自包含服务：它基于 pandas + sklearn + statsmodels 实现（源码 docstring 明确说明不要求 polars 版 functime 库，原 polars 版保留为functime_service_polars_legacy.py）。其通过dispatch(operation, data)暴露 7 个操作：check_status、forecast、anomaly_detection、seasonality、metrics、confidence_intervals、stationarity，并统一返回{success, operation, data|error, error_kind}响应契约。例如forecast操作支持linear/ridge/lasso/elasticnet/knn/naive/drift/holt_winters/arima多模型、递归多步外推、样本内 R²/MAE/RMSE 与残差统计；stationarity操作整合 ADF 与 KPSS 检验并给出建议差分阶数。这一层可以看作 40 函数 API 之外的第二种集成形态：无需 Polars 面板结构，仅凭一维数值列表即可通过 CLI（python functime_service.py <operation> '<json>'）驱动整套时序分析。

关键特性与使用注意

README 的 Key Features 汇总如下，均已在源码中得到印证：

• Polars 驱动：全部 40 个函数以 Polars DataFrame 为输入输出，利用表达式引擎获得高性能；
• 面板数据：原生支持多实体时序（entity_id分组贯穿缩放、差分、插补、滞后、滚动、重采样等所有预处理）；
• ML 预测：6 种模型（Linear、Lasso、Ridge、ElasticNet、KNN、LightGBM）；
• 自动调优：6 个 Auto 版本基于 FLAML 自动搜索超参并回传best_params；
• 特征工程：日历、节假日、滞后、滚动特征；
• 变换能力：Box-Cox、缩放、差分、插补、零填充、重采样、类型强制；
• 交叉验证：扩展窗口与滑窗两种滚动切分；
• 指标完备：9 种预测精度度量，含方向性偏差类指标（over/underforecast）；
• 外生变量：X_train/X_future支持外部回归量，配合create_future_calendar_effects可构造预测期特征。

README Notes 中的关键约束需在实际使用中遵守：

1. 所有函数面向Polars DataFrame（非 Pandas）；
2. 面板数据必须包含entity_id、time、value三列；
3. 频率取值：'1d'（日）、'1w'（周）、'1mo'（月）、'1q'（季）、'1y'（年）；
4. Auto 模型使用 FLAML 进行超参调优。

版本信息与许可证

• functime：0.1.10（README 指定安装版本）
• Wrapper 版本：1.0.0
• 函数总数：40
• Coverage：Complete（README 声明）
• Last Updated：2026-01-23
• License：MIT License，与 FinceptTerminal 项目主体一致（见仓库根目录 LICENSE）

结语

functime_wrapper以"统一数据契约 + 统一返回结构 + fit/forecast 与 auto 双模式"的设计，把 functime 的 Polars 原生机器学习时序能力完整接入 FinceptTerminal 的量化分析体系。无论是手工挑选正则化模型、借助 FLAML 自动调参，还是通过本地 scipy/Polars 实现完成 Box-Cox、缩放、差分、滚动特征等预处理，40 个函数都遵循可预测的签名与字典返回，便于在脚本、回测引擎或functime_service服务层中组合复用。若需在 FinceptTerminal 中落地单变量快速预测与诊断（含异常检测、季节分解、平稳性检验与置信区间），functime_service.py提供的 7 个服务操作是更贴近界面集成的另一条路径。

【免费下载链接】FinceptTerminalFinceptTerminal is a modern finance application offering advanced market analytics, investment research, and economic data tools, designed for interactive exploration and>项目地址: https://gitcode.com/GitHub_Trending/fi/FinceptTerminal