tsfresh API文档详解：核心函数参数与返回值解析-优快云博客

tsfresh API文档详解：核心函数参数与返回值解析

【免费下载链接】tsfresh Automatic extraction of relevant features from time series: 项目地址: https://gitcode.com/gh_mirrors/ts/tsfresh

你是否在时间序列特征工程中遇到过这些问题：特征提取参数复杂难以配置？不知如何筛选有价值的特征？本文将系统解析tsfresh核心API的参数配置与返回值格式，帮助你高效完成时间序列特征工程。读完本文你将掌握：extract_features与select_features函数的完整参数说明、特征提取流程中的关键配置项、特征选择的统计检验原理，以及如何通过参数调优提升特征质量。

核心功能模块概览

tsfresh的API组织结构清晰，主要功能分布在以下核心模块中：

特征提取：tsfresh.feature_extraction
特征选择：tsfresh.feature_selection
数据转换：tsfresh.transformers
工具函数：tsfresh.utilities

官方API文档结构可参考docs/api/modules.rst，其中详细定义了各模块的层级关系与调用路径。

特征提取API详解：extract_features

作为tsfresh最核心的函数，extract_features负责从时间序列数据中自动生成特征矩阵。其函数签名如下：

def extract_features(
    timeseries_container,
    default_fc_parameters=None,
    kind_to_fc_parameters=None,
    column_id=None,
    column_sort=None,
    column_kind=None,
    column_value=None,
    chunksize=defaults.CHUNKSIZE,
    n_jobs=defaults.N_PROCESSES,
    show_warnings=defaults.SHOW_WARNINGS,
    disable_progressbar=defaults.DISABLE_PROGRESSBAR,
    impute_function=defaults.IMPUTE_FUNCTION,
    profile=defaults.PROFILING,
    profiling_filename=defaults.PROFILING_FILENAME,
    profiling_sorting=defaults.PROFILING_SORTING,
    distributor=None,
    pivot=True,
):

关键参数解析

1. 数据格式参数

timeseries_container：输入时间序列数据容器，支持两种格式：
- pandas.DataFrame：需配合column_*参数指定各字段角色
- 字典类型：键为kind名称，值为对应时间序列DataFrame
column_id：样本ID列名，用于标识不同时间序列样本
column_sort：时间排序列名，确保时间序列的顺序正确性
column_kind：数据类型列名，用于区分同一样本的不同测量维度
column_value：数值列名，存储时间序列观测值

数据格式详细说明参见官方文档docs/text/data_formats.rst

2. 特征计算配置

default_fc_parameters：默认特征计算参数配置，默认使用ComprehensiveFCParameters，包含所有支持的特征计算器。典型配置示例：

{
    "mean": None,           # 无参数特征
    "std": None,            # 无参数特征
    "fft_coefficient": [    # 带参数特征
        {"coeff": 0, "attr": "real"},
        {"coeff": 1, "attr": "imag"}
    ]
}

kind_to_fc_parameters：按kind指定特征计算参数，优先级高于default_fc_parameters，实现不同类型数据的差异化特征提取

3. 执行控制参数

n_jobs：并行计算进程数，默认使用全部CPU核心
chunksize：并行任务分块大小，影响内存占用与计算效率
distributor：分布式计算引擎选择，支持MultiprocessingDistributor与MapDistributor

4. 结果处理参数

impute_function：缺失值填充函数，默认使用tsfresh.utilities.dataframe_functions.impute
pivot：是否将结果转换为宽表格式，默认为True，返回(index, feature)二维矩阵

返回值格式

函数返回pandas.DataFrame对象，格式如下：

index	kind1__feature1__param1	kind1__feature2	kind2__feature1	...
1	0.123	45.6	True	...
2	0.456	78.9	False	...

特征名称采用三级命名规范：{kind}__{feature}__{parameters}，其中参数部分通过特定编码格式生成，如fft_coefficient__coeff_0__attr_real表示FFT系数的第0个实部值。

特征选择API详解：select_features

特征选择是提升模型性能的关键步骤，select_features函数通过统计检验筛选具有预测价值的特征，其函数定义为：

def select_features(
    X,
    y,
    test_for_binary_target_binary_feature=defaults.TEST_FOR_BINARY_TARGET_BINARY_FEATURE,
    test_for_binary_target_real_feature=defaults.TEST_FOR_BINARY_TARGET_REAL_FEATURE,
    test_for_real_target_binary_feature=defaults.TEST_FOR_REAL_TARGET_BINARY_FEATURE,
    test_for_real_target_real_feature=defaults.TEST_FOR_REAL_TARGET_REAL_FEATURE,
    fdr_level=defaults.FDR_LEVEL,
    hypotheses_independent=defaults.HYPOTHESES_INDEPENDENT,
    n_jobs=defaults.N_PROCESSES,
    show_warnings=defaults.SHOW_WARNINGS,
    chunksize=defaults.CHUNKSIZE,
    ml_task="auto",
    multiclass=False,
    n_significant=1,
):

关键参数解析

1. 输入数据参数

X：extract_features生成的特征矩阵
y：目标变量，支持分类(离散)与回归(连续)任务

2. 统计检验参数

test_for_binary_target_real_feature：二分类问题中连续特征的检验方法，默认使用"mann"（Mann-Whitney U检验）
fdr_level：错误发现率控制水平，默认0.05，控制特征选择的假阳性率
hypotheses_independent：是否假设特征间相互独立，默认False（更保守的FDR校正）

3. 任务配置参数

ml_task：机器学习任务类型，支持"auto"（自动推断）、"classification"和"regression"
multiclass：是否为多分类任务，启用时需设置n_significant
n_significant：多分类任务中特征需显著预测的类别数

返回值格式

返回筛选后的特征矩阵，仅保留统计显著的特征列。特征选择的统计原理可参考docs/text/feature_filtering.rst。

特征提取流程与参数交互

特征提取与选择的典型工作流如下：

from tsfresh import extract_features, select_features
from tsfresh.examples import load_robot_execution_failures

# 加载示例数据
df, y = load_robot_execution_failures()

# 提取特征
X = extract_features(
    df, 
    column_id="id", 
    column_sort="time",
    default_fc_parameters={
        "abs_energy": None,
        "mean_abs_change": None,
        "fft_coefficient": [{"coeff": 0, "attr": "real"}]
    }
)

# 筛选特征
X_selected = select_features(X, y, fdr_level=0.01)

特征提取过程中的参数交互关系如图所示：

高级配置：特征计算器参数调优

tsfresh支持超过70种特征计算器，每种计算器都有特定的参数配置。完整特征列表参见docs/text/list_of_features.rst。以下是常用特征及其参数配置示例：

1. 时间域特征

{
    "time_reversal_asymmetry_statistic": [{"lag": 1}, {"lag": 2}],
    "c3": [{"lag": 1}, {"lag": 2}],
    "change_quantiles": [{"f_agg": "mean", "isabs": True, "quantiles": [0.2, 0.8]}]
}

2. 频率域特征

{
    "fft_coefficient": [
        {"coeff": 0, "attr": "real"},
        {"coeff": 1, "attr": "imag"},
        {"coeff": 2, "attr": "abs"}
    ],
    "spectral_centroid": None
}

自定义特征计算器开发可参考docs/text/how_to_add_custom_feature.rst。

性能优化参数配置

处理大规模时间序列数据时，合理的参数配置可显著提升效率：

内存优化：
- 降低chunksize减少单次内存占用
- 使用dask.distributed作为distributor实现分布式计算
计算加速：
- n_jobs设置为CPU核心数的1.5倍（超线程优化）
- 对高频采样数据先降采样再提取特征
特征降维：
- 通过kind_to_fc_parameters排除无关数据类型
- 调整fc_parameters只计算有物理意义的特征

大规模数据处理的详细策略参见docs/text/large_data.rst。

常见问题与参数调优建议

Q1: 特征矩阵包含大量NaN值如何处理？

A1: 调整impute_function参数，使用自定义填充策略：

from tsfresh.utilities.dataframe_functions import impute

extract_features(..., impute_function=lambda x: impute(x, value=-999))

Q2: 如何加速特征提取过程？

A2: 结合以下参数组合：

extract_features(
    ...,
    n_jobs=4,
    chunksize=100,
    default_fc_parameters=MinimalFCParameters()  # 使用精简特征集
)

Q3: 特征选择后保留特征太少怎么办？

A3: 提高fdr_level至0.1或使用更宽松的统计检验：

select_features(..., fdr_level=0.1, test_for_binary_target_real_feature="ttest")

更多常见问题参见docs/text/faq.rst。

总结与最佳实践

tsfresh的API设计兼顾了灵活性与易用性，通过合理配置参数可满足不同场景的特征工程需求。推荐的最佳实践工作流：

数据准备：严格遵循数据格式规范，确保column_id、column_sort等关键字段正确设置
特征提取：先使用MinimalFCParameters快速验证流程，再逐步扩展特征集
参数调优：通过profiling=True分析计算瓶颈，针对性优化耗时特征计算器
特征选择：根据任务类型合理设置ml_task与统计检验方法
结果验证：结合领域知识评估特征重要性，避免过度依赖统计显著性

通过本文介绍的API参数配置方法，你可以充分发挥tsfresh的自动特征工程能力，快速构建高质量的时间序列特征矩阵。完整API文档参见docs/api/tsfresh.rst。

提示：使用notebooks/01 Feature Extraction and Selection.ipynb交互式学习API使用方法。

【免费下载链接】tsfresh Automatic extraction of relevant features from time series: 项目地址: https://gitcode.com/gh_mirrors/ts/tsfresh

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考