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 为数据格式追求开箱即用的极速性能。其能力按 READMEfincept-qt/scripts/Analytics/functime_wrapper/README.md划分如下模块函数数量能力Forecasting18线性回归、Lasso、Ridge、ElasticNet、KNN、LightGBM 及对应 Auto 自动调参版本Feature Extraction4日历效应与节假日效应特征Preprocessing11数据变换Box-Cox、差分、缩放、插补、滞后、滚动窗口等Cross Validation3训练/测试划分、扩展窗口、滑窗切分Metrics9预测精度指标MAE、MAPE、MASE、MSE、RMSE、RMSSE、SMAPE 及高估/低估比例Offsets1频率字符串到季节周期转换六个模块在仓库中的文件布局为目录 fincept-qt/scripts/Analytics/functime_wrapperfunctime_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 库与 PolarsREADME 指定的安装命令为pip install functime0.1.10需要说明的版本事实源自 README 的 Version 小节与各模块源码 import 语句functime0.1.10Wrapper 版本1.0.0函数总数40CoverageCompleteREADME 声明主要运行时依赖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( startpl.datetime(2020, 1, 1), endpl.datetime(2020, 1, 10), interval1d, eagerTrue ).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, fh3, freq1d) print(fLinear forecast: {linear_forecast[forecast]}) # LassoL1 正则化默认 alpha1.0 lasso_forecast forecast_lasso(df, fh3, freq1d, alpha0.1) print(fLasso forecast: {lasso_forecast[forecast]}) # RidgeL2 正则化默认 alpha1.0 ridge_forecast forecast_ridge(df, fh3, freq1d, alpha0.1) print(fRidge forecast: {ridge_forecast[forecast]})结合 forecasting.py 源码可以看到统一的设计模式fit_*系列实例化 functime 模型如LinearModel(freqfreq)、Lasso(freqfreq, alphaalpha)调用model.fit(yy_train, XX_train)返回含model_type、freq、alpha、fitted: True的状态字典forecast_*系列在 fit 基础上调用model.predict(fhfh, XX_future)返回字典含forecast由forecast.to_dicts()转换的列表、shape、horizon参数签名统一为(y_train, fh, X_trainNone, X_futureNone, freq1d, **model_params)其中X_train/X_future是可选外生变量Exogenous VariablesREADME 的 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, fh3, freq1d) print(fBest params: {auto_result[best_params]}) print(fForecast: {auto_result[forecast]}) # Auto-tune Ridge ridge_result auto_ridge(df, fh3, freq1d) print(fForecast: {ridge_result[forecast]}) # Auto-tune ElasticNet elastic_result auto_elasticnet(df, fh3, freq1d) print(fForecast: {elastic_result[forecast]})从 forecasting.py 第 240-352 行可见 Auto 模型的实现差异它们不再手动fitpredict而是直接调用model.fit_predict(yy_train, fhfh, XX_train, X_futureX_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 变换lmbdaNone 时自动用 MLE 求解最优 lambda boxcox_result apply_boxcox(df, lmbda0.5) print(fTransformed: {boxcox_result[transformed]}) # 缩放standard / minmax / robust 三种方法按 entity_id 分组计算 scaled scale_data(df, methodstandard) print(fScaled: {scaled[scaled]}) # 差分order 阶差分对齐时丢弃前 order 个时间点 diff_result difference_data(df, order1) print(fDifferenced: {diff_result[differenced]}) # 滞后特征整数自动展开为 1..n 的列表生成 lag_1/lag_2/lag_3 列并 drop 空行 lags_result create_lags(df, lags[1, 2, 3]) print(fLagged features: {lags_result[columns]}) # 滚动特征window_sizes × stats 的组合生成 rolling_stat_window 列 rolling_result create_rolling_features(df, window_sizes[3, 7], stats[mean, std]) print(fRolling features: {rolling_result[columns]})各函数的关键实现细节源自源码函数行为要点apply_boxcoxBox-Cox 要求正值当最小值 ≤ 0 时自动平移shift |min| 1lmbdaNone时用scipy.stats.boxcox求最优 lambdalmbda0时退化为对数变换(x^λ−1)/λ公式find_boxcox_normmax仅返回 MLE 求解的最优 lambdamethod参数预留coerce_data_types统一类型entity_id转 Utf8、time转 Datetime、value转 Float64并返回各列 dtype 映射impute_missing支持forward/backward/mean/zero/linear五种策略均通过 Polars 表达式按entity_id分组填充.over(entity_id)reindex_panel_data频率映射表{1d,1h,1w,1mo,1m}对每个实体生成完整日期范围后 left join产生缺测空值resample_data基于group_by_dynamic重采样agg_method支持 sum/mean/first/last/min/maxscale_datastandard用 z-score、minmax用最大最小归一化、robust用中位数与 IQR全部按实体分组zero_pad_data在序列开头按首个时间间隔前插指定数量的 0 值行用于对齐不同实体起始日期特征提取日历效应与节假日效应特征提取模块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, freq1d) print(fCalendar features: {calendar[columns]}) # 节假日效应country_codes 必填如 USfreq 默认 D holidays create_holiday_effects(df, country_codes[US], freqD) print(fHoliday features: {holidays[columns]}) # 未来日期的日历特征用于构造预测期的外生变量 X_future future_calendar create_future_calendar_effects(fh7, freq1d) print(fFuture 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_size1 split split_train_test(df, test_size2) print(fTrain: {split[train_shape]}, Test: {split[test_shape]}) # 扩展窗口 CV训练集逐渐增大默认 step1 expanding create_expanding_window_splits(df, test_size1, n_splits3) print(fNumber of splits: {expanding[n_splits]}) # 滑窗 CV固定 train_size 的训练窗口 sliding create_sliding_window_splits(df, train_size5, test_size1, n_splits3) print(fNumber of splits: {sliding[n_splits]})参数语义源码确认test_size为每折测试长度、n_splits为折数、step为窗口每次滑动的步长默认 1create_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(fMAE: {mae[mean_mae]}) # RMSE rmse calculate_rmse(y_true, y_pred) print(fRMSE: {rmse[mean_rmse]}) # SMAPE smape calculate_smape(y_true, y_pred) print(fSMAPE: {smape[mean_smape]}) # MASE需要训练数据 y_train 与季节周期 sp默认 sp1 y_train df mase calculate_mase(y_true, y_pred, y_train, sp1) print(fMASE: {mase[mean_mase]}) # 高估比例预测持续高于实际的程度 over calculate_overforecast(y_true, y_pred) print(fOverforecast: {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与spseasonal 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 章节供快速检索。Forecastingforecasting.py18 个函数函数说明fit_linear_model拟合 Linear Regression 预测器forecast_linear_model拟合并预测Linear Regressionfit_lasso拟合 LassoL1预测器forecast_lasso拟合并预测Lassofit_ridge拟合 RidgeL2预测器forecast_ridge拟合并预测Ridgefit_elasticnet拟合 ElasticNet 预测器forecast_elasticnet拟合并预测ElasticNetfit_knn拟合 K 近邻预测器forecast_knn拟合并预测KNN默认n_neighbors5fit_lightgbm拟合 LightGBM 预测器**params透传forecast_lightgbm拟合并预测LightGBMauto_linear_model自动调参 Linear Modelauto_lasso自动调参 Lassoauto_ridge自动调参 Ridgeauto_elasticnet自动调参 ElasticNetauto_knn自动调参 KNNauto_lightgbm自动调参 LightGBM其中 Lasso/Ridge 的alpha默认值为 1.0ElasticNet 额外有l1_ratio默认 0.5源码确认。Feature Extractionfeature_extraction.py4 个函数函数说明create_calendar_effects添加日历特征日、月、年等create_holiday_effects添加节假日指示特征create_future_calendar_effects为未来日期生成日历特征create_future_holiday_effects为未来日期生成节假日特征Preprocessingpreprocessing.py11 个函数函数说明apply_boxcox应用 Box-Cox 变换find_boxcox_normmax求解最优 Box-Cox lambdacoerce_data_types转换为 functime 兼容 dtypedifference_data面板数据差分impute_missing缺失值插补create_lags创建滞后特征reindex_panel_data按指定频率重索引resample_data重采样到不同频率create_rolling_features创建滚动窗口特征scale_data缩放面板数据zero_pad_data零值填充面板数据Cross Validationcross_validation.py3 个函数函数说明split_train_test划分为训练集与测试集create_expanding_window_splits扩展窗口 CVcreate_sliding_window_splits滑窗 CVMetricsmetrics.py9 个函数函数说明calculate_mae平均绝对误差calculate_mape平均绝对百分比误差calculate_mase平均绝对缩放误差需 y_train、spcalculate_mse均方误差calculate_rmse均方根误差calculate_rmsse均方根缩放误差需 y_train、spcalculate_smape对称 MAPEcalculate_overforecast高估比例calculate_underforecast低估比例Offsetsoffsets.py1 个函数函数说明frequency_to_seasonal_period频率转季节周期源码纵深的两种落地形态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 面板结构仅凭一维数值列表即可通过 CLIpython 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 中的关键约束需在实际使用中遵守所有函数面向Polars DataFrame非 Pandas面板数据必须包含entity_id、time、value三列频率取值1d日、1w周、1mo月、1q季、1y年Auto 模型使用 FLAML 进行超参调优。版本信息与许可证functime0.1.10README 指定安装版本Wrapper 版本1.0.0函数总数40CoverageCompleteREADME 声明Last Updated2026-01-23LicenseMIT 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考