featuretools API 参考全指南：从演示数据集到深度特征合成与特征工程的完整接口地图

特征工程机器学习数据科学【免费下载链接】featuretoolsAn open source python library for automated feature engineering项目地址https://gitcode.com/gh_mirrors/fe/featuretools点击查看免费下载本篇指南以 featuretools 官方 API Referencedocs/source/api_reference.rst为骨架系统梳理这个开源自动化特征工程库的全部公开接口从demo数据集加载、dfs深度特征合成、Timedelta时间窗口到 100 个特征原语Primitive、EntitySet 构建与序列化、特征筛选与可视化。读完本文你将掌握 featuretools 每个核心模块的入口函数、参数语义、返回结构与底层实现位置可直接对照源码查阅与实战调用。目录导航API Reference 按功能域将全部公开接口划分为十余个大类本文依此组织Demo 数据集加载featuretools.demo深度特征合成 DFSfeaturetools.dfs/get_valid_primitives时间工具Timedelta/make_temporal_cutoffs特征原语体系Transform / Aggregation 及 10 子类特征方法、计算、描述、可视化、编码特征筛选与特征矩阵工具特征的保存与加载EntitySet / Relationship 全量 API数据类型与原语工具方法Demo 数据集一键加载多表数据API Reference 的第一个模块是featuretools.demo它提供四个可直接复用的演示数据集加载函数用于快速验证 DFS 与特征工程流程。模块入口在 featuretools/demo/api.py四个函数分别对应四个独立模块。load_retail经典多表零售数据load_retailfeaturetools/demo/retail.py加载经过改写的 UCI Online Retail 数据集并组装成含四张表的标准 EntitySetimport featuretools as ft es ft.demo.load_retail() # Entityset: demo_retail_data # DataFrames: # orders (shape [22190, 3]) # products (shape [3684, 3]) # customers (shape [4372, 2]) # order_products (shape [401704, 7]) # 只加载 1000 行子集 es ft.demo.load_retail(nrows1000)关键参数idEntitySet 的 id默认demo_retail_datanrows从底层 CSV 读取的行数None表示全量加载return_single_table为True时直接返回单个 DataFrame不做实体化拆分适合快速探索原始数据。从源码看该函数内部先pd.read_csv读取数据再通过es.add_dataframe(...)加入order_products表并连续调用两次es.normalize_dataframe(...)从订单明细中切分出products与orders两张父表——这正是多表实体集的标准构建模式与本文后文 EntitySet API 一节相互印证。数据改动包括列名重命名、customer_id转唯一化customer_name、去重、新增total与cancelled列以及币种换算。load_mock_customer可定制规模的模拟客户数据load_mock_customerfeaturetools/demo/mock_customer.py用固定随机种子生成客户、产品、会话、交易四类模拟数据可精确控制规模# 返回 dict[str - DataFrame] dataframes ft.demo.load_mock_customer( n_customers5, n_products5, n_sessions35, n_transactions500, random_seed0, ) # dataframes.keys(): customers / sessions / transactions / products # 或直接返回已建好关系与 last_time_index 的 EntitySet es ft.demo.load_mock_customer(return_entitysetTrue) # 或返回合并后的单表 df ft.demo.load_mock_customer(return_single_tableTrue)该数据集的实体关系为products.product_id - transactions.product_id、sessions.session_id - transactions.session_id、customers.customer_id - sessions.customer_id并已调用add_last_time_indexes()是演示dfs多表聚合最常用的数据源。zip_code列被标记为PostalCode、product_id标记为Categorical可触发邮编/分类原语。load_flight带筛选条件的航班数据load_flightfeaturetools/demo/flight.py加载 2017 年航班延误数据并组装成 airports / flights / trip_logs / airlines 四表实体集支持按月份与城市筛选es ft.demo.load_flight( verboseTrue, month_filter[1], categorical_filter{origin_city: [Boston, MA]}, ) # Entityset: Flight Data # DataFrames: # airports [Rows: 55, Columns: 3] # flights [Rows: 613, Columns: 9] # trip_logs [Rows: 9456, Columns: 22] # airlines [Rows: 10, Columns: 1] # Relationships: # trip_logs.flight_id - flights.flight_id # flights.carrier - airlines.carrier # flights.dest - airports.dest参数说明month_filter限定使用月份如[1, 2]categorical_filter按分类列取值过滤示例返回波士顿进出港航班nrows传给pd.read_csvdemoTrue时只用两个月数据以加快加载verbose显示tqdm进度条。下面这张图展示了航班实体集的 cutoff time 结构——每个航班如编号 14、92带time_index预测时刻由竖虚线标出load_weather单表时序天气数据load_weatherfeaturetools/demo/weather.py加载澳大利亚每日最低气温数据构建仅含temperatures单表的实体集es ft.demo.load_weather() # Entityset: Weather Data df ft.demo.load_weather(return_single_tableTrue) # 原始 DataFrame其 EntitySet 只含一张temperatures表indexidmake_indexTruetime_indexDate适合演示单表时间序列特征的生成。深度特征合成DFS核心 APIDFS 是 featuretools 的引擎公开入口为dfs与get_valid_primitives均在 featuretools/synthesis/api.py 中导出。dfs一步完成特征生成与矩阵计算dfsfeaturetools/synthesis/dfs.py是最高层封装输入多表数据与关系输出特征列表与特征矩阵。其完整签名包含 30 个参数是理解 featuretools 能力边界的关键。最简调用只传数据、关系和目标表from featuretools.primitives import Mean dataframes { sessions: (session_df, id), transactions: (transactions_df, id, transaction_time), } relationships [(sessions, id, transactions, session_id)] feature_matrix, features dfs( dataframesdataframes, relationshipsrelationships, target_dataframe_nametransactions, cutoff_timecutoff_times, )参数分组详解均出自 dfs.py分组参数语义与默认值数据输入dataframesdict格式{表名 - (df, index列, time_index列, logical_types, semantic_tags, make_index)}仅 df 必填传入 Woodwork DataFrame 时其余参数被忽略relationships关系列表元素为(父表, 父列, 子表, 子列)四元组entityset已构建好的 EntitySet与dataframes/relationships二选一目标设置target_dataframe_name在其上做预测的目标表名时间控制cutoff_time每个实例的特征计算截止时刻可传单值、可解析字符串或 DataFrame实例 id 列须与目标表 index 同名或为instance_id时间列须与 time_index 同名或为time多余列会并入结果矩阵instance_ids仅当cutoff_time为单个时间点时使用指定要计算特征的实例training_window截止时刻之前可用的数据窗口Timedelta或字符串None表示使用截止前全部数据。注意用 Pandas Timedelta 时月/年单位非相对时间应改用 Featuretools Timedelta 或字符串approximate分桶粒度如 24 小时——同日截止的实例对昂贵特征共用一次计算显著加速cutoff_time_in_indexTrue时返回 MultiIndex实例 id 截止时间并按(time, instance_id)排序include_cutoff_time是否把截止时刻当刻的数据计入特征计算默认True原语配置agg_primitives聚合原语列表默认[sum, std, max, skew, min, mean, count, percent_true, num_unique, mode]trans_primitives变换原语列表默认[day, year, month, weekday, haversine, num_words, num_characters]groupby_trans_primitives生成 GroupByTransform 特征的变换原语where_primitives带 where 子句应用的原语默认[count]特征裁剪max_depth特征最大深度默认 2max_features特征数量上限默认-1表示不限ignore_dataframes/ignore_columns黑名单表 / 列dict[str - list[str]]drop_contains/drop_exact按特征名包含 / 精确匹配字符串删除特征allowed_paths允许建特征的表路径白名单primitive_options每个原语或原语组的细粒度选项include_dataframes、ignore_dataframes、include_columns、ignore_columns及对应的include/ignore_groupby_dataframes/columns限定 groupby 候选seed_features手动定义的种子特征列表计算资源n_jobs并行进程数默认 1dask_kwargsdask 客户端/调度器参数即使不设n_jobs传入该参数也会启用多进程。可接收cluster、diagnostics port及LocalCluster的合法关键字chunk_size分块计算行数正整数表示每块行数(0,1)浮点表示占全部实例的比例字符串cutoff time表示按截止时间切块save_progress中间计算结果保存路径progress_callback进度回调形参(update, progress_percent, time_elapsed)返回控制features_onlyTrue时只返回特征列表、不计算矩阵return_types限制返回列类型list[woodwork.ColumnSchema]或all默认返回全部数值/分类/布尔类型verbose输出详细日志底层调用链从源码可见dfs依次执行EntitySet(dfs, dataframes, relationships)构建实体集 →DeepFeatureSynthesis(...)构造 DFS 对象 →dfs_object.build_features(...)生成特征featuretools/synthesis/deep_feature_synthesis.py→_categorize_features对特征分类 →get_unused_primitives检测未用原语并发出UnusedPrimitiveWarning→ 最后调用calculate_feature_matrix计算矩阵featuretools/computational_backends/calculate_feature_matrix.py。注意当features_onlyFalse且生成的特征为空时dfs会直接断言报错提示原语与数据类型不兼容。get_valid_primitives查询可用原语用于查询给定实体集/表上可用的原语集合配合自定义原语注册后检查生效范围定义见 featuretools/synthesis/get_valid_primitives.py。时间工具Timedelta 与 cutoff 生成Timedeltafeaturetools.Timedelta实现于 featuretools/entityset/timedelta.py是支持相对时间单位的专用时间增量类用于training_window、approximate等场景解决 Pandas Timedelta 中月/年非相对单位的局限from featuretools import Timedelta # 支持相对单位 window Timedelta(2, months) window Timedelta(3 days)make_temporal_cutoffsmake_temporal_cutoffsfeaturetools/utils/time_utils.py为每个实例生成一组等间距的截止时间序列用于时间序列交叉验证from featuretools.utils import make_temporal_cutoffs # 每个实例 id 生成 num_windows 个、间隔 window_size 的截止时间 cutoffs make_temporal_cutoffs( instance_ids[1, 2, 3], cutoffs[2014-01-01, 2014-02-01, 2014-03-01], window_size1 month, num_windows3, )三种组合方式window_size num_windows生成等窗window_size start每实例的起始时间列表生成可变数量窗口num_windows start生成数量固定、大小可变的窗口。源码中三者同时传入会抛出ValueErrorOnly supply 2 of the 3 optional args。下面这张图展示了零售示例数据集中 cutoff time 的结构——左侧虚线04:00 01/01/2014与右侧虚线00:00 01/02/2014之间的数据用于特征计算虚线之后标签才可知特征原语Primitives体系原语是 DFS 的特征构建单元API Reference 将其分为两大基类与十余个子类。基类定义于 featuretools/primitives/base/TransformPrimitivetransform_primitive_base.py逐行或逐分组作用于单个表内的列输出与输入行数相同的新列AggregationPrimitiveaggregation_primitive_base.py沿实体关系把子表多条记录聚合成父表/目标表上的一个标量值。聚合原语Aggregation PrimitivesAPI Reference 共列出 68 个聚合原语覆盖统计、时序、集合、分布四类能力源码实现位于 featuretools/primitives/standard/aggregation/基础统计Count、Sum、Mean、Median、Max、Min、Std、Variance、Skew、Kurtosis、Mode、Entropy、Trend条件计数CountAboveMean、CountBelowMean、CountGreaterThan、CountLessThan、CountInsideRange、CountOutsideRange、CountInsideNthSTD、CountOutsideNthSTD、MaxCount、MinCount、MedianCount占比与唯一性PercentTrue、PercentUnique、NumUnique、NMostCommon、NMostCommonFrequency、AverageCountPerUnique、HasNoDuplicates、IsUnique、IsMonotonicallyIncreasing、IsMonotonicallyDecreasing时序相关DateFirstEvent、First、Last、FirstLastTimeDelta、AvgTimeBetween、TimeSinceFirst、TimeSinceLast、TimeSinceLastTrue、TimeSinceLastFalse、TimeSinceLastMax、TimeSinceLastMin、MaxMinDelta连续段统计MaxConsecutiveTrue、MaxConsecutiveFalse、MaxConsecutivePositives、MaxConsecutiveNegatives、MaxConsecutiveZeros、NumConsecutiveGreaterMean、NumConsecutiveLessMean、NumTrue、NumFalseSinceLastTrue、NumTrueSinceLastFalse、NumPeaks、NumZeroCrossings时间粒度NUniqueDays、NUniqueDaysOfCalendarYear、NUniqueMonths、NUniqueWeeks这些原语的批量行为由 featuretools/tests/primitive_tests/aggregation_primitive_tests/ 下的测试覆盖其中 test_agg_primitives.py 是核心参数化测试集。变换原语Transform Primitives变换原语按功能划分为以下子类源码位于 featuretools/primitives/standard/transform/二元运算Binarybinary/AddNumeric、AddNumericScalar、SubtractNumeric、SubtractNumericScalar、ScalarSubtractNumericFeature、MultiplyNumeric、MultiplyNumericScalar、MultiplyBoolean、MultiplyNumericBoolean、DivideNumeric、DivideNumericScalar、DivideByFeature、ModuloNumeric、ModuloNumericScalar、ModuloByFeature以及布尔比较Equal、EqualScalar、NotEqual、NotEqualScalar、GreaterThan、GreaterThanScalar、GreaterThanEqualTo、GreaterThanEqualToScalar、LessThan、LessThanScalar、LessThanEqualTo、LessThanEqualToScalar特征组合Combine featuresIsIn、And、Or、Not布尔逻辑与成员判断累积变换Cumulativecumulative/CumCount、CumSum、CumMean、CumMin、CumMax、CumulativeTimeSinceLastTrue、CumulativeTimeSinceLastFalse、Diff、DiffDatetime、TimeSincePrevious日期时间Datetimedatetime/Age、Year、Month、Day、Week、Weekday、Hour、Minute、Second、Quarter、DayOfYear、DaysInMonth、IsWeekend、IsMonthStart、IsMonthEnd、IsQuarterStart、IsQuarterEnd、IsYearStart、IsYearEnd、IsLeapYear、IsFirstWeekOfMonth、NthWeekOfMonth、PartOfDay、Season、IsLunchTime、IsWorkingHours、TimeSince、TimeSincePrevious、DateToHoliday、DistanceToHoliday、IsFederalHoliday、DateToTimeZoneEmail / URL / 文件EmailAddressToDomain、IsFreeEmailDomain、URLToDomain、URLToProtocol、URLToTLD、FileExtension免费邮箱域名数据见 featuretools/primitives/data/free_email_provider_domains.txt指数平滑Exponentialexponential/ExponentialWeightedAverage、ExponentialWeightedSTD、ExponentialWeightedVariance通用变换GeneralAbsolute、AbsoluteDiff、IsNull、NaturalLogarithm、SquareRoot、Negate、Sine、Cosine、Tangent、Percentile、PercentChange、RateOfChange、SameAsPrevious、SavgolFilter、Variance地理Locationlatlong/Haversine、CityblockDistance、GeoMidpoint、IsInGeoBox、Latitude、Longitude姓名NameFullNameToFirstName、FullNameToLastName、FullNameToTitle自然语言NaturalLanguagenatural_language/NumWords、NumCharacters、MeanCharactersPerWord、MedianWordLength、TotalWordLength、CountString、NumUniqueSeparators、NumberOfCommonWords、NumberOfHashtags、NumberOfMentions、NumberOfUniqueWords、NumberOfWordsInQuotes、PunctuationCount、TitleWordCount、UpperCaseCount、UpperCaseWordCount、WhitespaceCount邮编Postal Codepostal/OneDigitPostalCode、TwoDigitPostalCode时间序列Time Seriestime_series/滚动窗口RollingCount、RollingMean、RollingSum对应rolling_*.py系列、RollingMax、RollingMin、RollingSTD、RollingTrend、RollingOutlierCount扩张窗口ExpandingCount、ExpandingMean、ExpandingMax、ExpandingMin、ExpandingSTD、ExpandingTrendexpanding/以及Lag、NumericLag后两者存在于__init__.py的导出中对应 time_series/lag.py 与 numeric_lag.py特征对象方法FeatureBasefeaturetools/feature_base/feature_base.py是所有特征的基类API Reference 收录两个高频方法FeatureBase.rename重命名特征影响特征矩阵列名FeatureBase.get_depth返回特征深度是控制 DFSmax_depth的底层依据此外FeatureBase.get_name、get_feature_names、dataframe_name等属性在 feature_base.py 中一并定义供手动组装seed_features时使用。特征计算与后处理 APIcalculate_feature_matrixcalculate_feature_matrixfeaturetools/computational_backends/calculate_feature_matrix.py是dfs底层实际执行的特征矩阵计算器接受features、entityset、cutoff_time、training_window、approximate、chunk_size、n_jobs、dask_kwargs、save_progress、verbose等参数。它还提供approximate_features内部函数用于approximate分桶优化见 featuretools/computational_backends/api.py。特征描述、可视化与编码describe_featurefeaturetools/feature_base/feature_descriptions.py为特征生成自然语言描述辅助特征解释与报告输出graph_featurefeaturetools/feature_base/feature_visualizer.py以图形式可视化特征计算结构支持to_file输出文件、description开关encode_featuresfeaturetools/synthesis/encode_features.py对特征矩阵中的类别特征做 one-hot / 实体集编码是 DFS 输出进入机器学习模型前的标准预处理步骤。特征筛选Feature Selectionfeaturetools.selection提供四个一键式特征筛选函数featuretools/selection/selection.py均返回(pd.DataFrame, list[FeatureBase])与dfs输出格式匹配若未传入features则只返回矩阵remove_low_information_featuresselection.py移除低信息量特征remove_highly_null_features(feature_matrix, featuresNone, pct_null_threshold0.95)空值占比超过阈值默认 95%的列被移除。源码中对pct_null_threshold做[0,1]范围校验超出抛ValueError注意阈值为0.0与大于0.0时的比较边界不同前者用后者用remove_single_value_features(feature_matrix, featuresNone, count_nan_as_valueFalse)移除所有取值相同的列。count_nan_as_valueTrue时把 NaN 视为独立取值否则一个唯一值 其余全空的特征也会被删remove_highly_correlated_features(feature_matrix, featuresNone, pct_corr_threshold0.95, features_to_checkNone, features_to_keepNone)移除与另一列相关性超过阈值默认 0.95的列可用features_to_check限定待检查列、features_to_keep保护必留列。特征矩阵工具replace_inf_valuesfeaturetools/computational_backends/utils.py把特征矩阵中的inf/-inf替换为指定值from featuretools.computational_backends import replace_inf_values fm replace_inf_values(fm, replacement_valuenp.nan, columnsNone)参数replacement_value默认np.nancolumns可限定处理列该函数在同一文件中也作为 dask 分块计算的内部工具被复用。特征的保存与加载save_features/load_features支持把特征定义序列化到本地或 S3 并恢复featuretools/feature_base/features_serializer.py、features_deserializer.pyfrom featuretools import save_features, load_features save_features(features, locationmy_features.json, profile_nameNone) loaded load_features(my_features.json, profile_nameNone)profile_name用于 S3 存储场景的凭证配置。EntitySet 与 Relationship多表数据建模 APIEntitySet 是 DFS 的数据模型核心featuretools.EntitySet与featuretools.Relationship的构造器及方法在 featuretools/entityset/ 中实现。构造与数据准备方法说明实现文件EntitySet(id)构造实体集entityset.pyEntitySet.add_dataframe添加表支持 Woodwork 类型推断同左EntitySet.add_relationship/add_relationships添加单个 / 批量关系同左EntitySet.normalize_dataframe从现有表切分出父表如load_retail的做法同左EntitySet.replace_dataframe替换表数据同左EntitySet.add_interesting_values标记类别列中有趣取值触发 where 类特征生成同左EntitySet.add_last_time_indexes自动计算每张表的 last_time_index同左EntitySet.set_secondary_time_index设置次要时间索引列同左EntitySet.concat横向拼接两个 EntitySet同左序列化read_entityset(path, profile_nameNone, **kwargs)featuretools/entityset/deserialize.py从磁盘恢复实体集EntitySet.to_csv/to_pickle/to_parquet导出实体集对应 serialize.py 的底层实现。查询方法与可视化EntitySet.__getitem__按表名取表es[transactions]find_backward_paths/find_forward_paths按方向遍历实体关系路径是 DFS 自动特征扩展时的路径搜索基础get_forward_dataframes/get_backward_dataframes获取沿关系方向关联的相邻表集合query_by_values按取值过滤查询表中数据EntitySet.plot可视化实体关系图绘图逻辑见 featuretools/utils/plot_utils.py。Relationship 属性Relationshipfeaturetools/entityset/relationship.py暴露四个只读属性parent_column/child_column父表 / 子表上的连接列名parent_dataframe/child_dataframe对应的父表 / 子表 DataFrame 对象。数据与原语工具方法数据类型工具list_logical_types列出 Woodwork 支持的全部逻辑类型如Numeric、Categorical、NaturalLanguage、PostalCode、Boolean、Ordinal、Datetime等供add_dataframe(logical_types...)时选用list_semantic_tags列出可附加在列上的语义标签如numeric、category、time_index、index等用于驱动原语匹配与特征合成。原语工具list_primitivesfeaturetools/primitives/utils.py返回 DataFrame列出全部内置原语的name、typetransform/aggregation、description、valid_inputs、return_type五列是当前库有哪些原语可用的一站式查询入口summarize_primitives同文件 L117返回原语的指标汇总表便于概览原语集合的统计分布get_recommended_primitivesfeaturetools/utils/recommend_primitives.py针对给定的数据类型与任务推荐原语组合帮助从 100 原语中快速选型。结合使用的推荐工作流综合以上 API一个典型的多表自动化特征工程流水线为import featuretools as ft from featuretools.selection import remove_low_information_features, remove_highly_correlated_features # 1. 加载演示数据或自建 EntitySet es ft.demo.load_mock_customer(return_entitysetTrue) # 2. 深度特征合成只生成定义先不计算 features ft.dfs(entitysetes, target_dataframe_namesessions, features_onlyTrue, max_depth2) # 3. 计算特征矩阵带时间窗口 fm, features ft.dfs(entitysetes, target_dataframe_namesessions, featuresfeatures, cutoff_time2014-01-01) # 4. 后处理编码 筛选 清洗 fm_encoded, features_encoded ft.encode_features(fm, features) fm_clean, _ remove_low_information_features(fm_encoded, features_encoded) fm_clean, _ remove_highly_correlated_features(fm_clean, pct_corr_threshold0.9) fm_clean ft.computational_backends.replace_inf_values(fm_clean) # 5. 持久化特征定义 ft.save_features(features_encoded, features.json)结语featuretools 的 API 面并不庞大但层次分明demo提供即时可用的多表数据集dfs是唯一入口原语库是能力来源EntitySet 是数据模型selection/encode_features/describe_feature/graph_feature构成后处理闭环。对照本指南的模块划分你可以按需深入 featuretools/ 下的对应源码文件进一步理解每个接口的边界行为与性能特征。赞分享特征工程机器学习数据科学【免费下载链接】featuretoolsAn open source python library for automated feature engineering项目地址https://gitcode.com/gh_mirrors/fe/featuretools点击查看免费下载相关推荐Featuretools 版本演进全解析从 1.0 重构到 1.31.0 的深度特征合成变更史Featuretools 版本演进全解析从 1.0 重构到 1.31.0 的深度特征合成变更史 Featuretools 是面向自动特征工程的 Python特征工程机器学习数据科学D2L.ai特征工程数值特征、类别特征与文本特征处理完整指南D2L.ai特征工程数值特征、类别特征与文本特征处理完整指南 想要在深度学习项目中获得出色的模型性能吗特征工程是关键 D2L.ai 提供了完整的特征工文档教程人工智能深度学习NLP计算机视觉强化学习时间序列特征工程完整指南从原始数据到预测特征时间序列特征工程完整指南从原始数据到预测特征 时间序列特征工程是将原始时间序列数据转化为有效预测特征的关键步骤直接影响模型预测性能。本文将以Darts库为基机器学习深度学习数据分析数据科学上一篇Zotero Aria拖拽引用文献的终极技巧分享下一篇Unity文本排版终极指南5个简单技巧实现完美换行与对齐创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考