fg-data-profiling 示例库全解析:12 类真实数据集的 Profiling 报告实战指南
fg-data-profiling 示例库全解析:12 类真实数据集的 Profiling 报告实战指南
本指南以仓库 docs/getting-started/examples.md 中收录的示例报告为线索,逐一带你还原 Census、Meteorites、Titanic、时间序列空气质量、数据集对比等场景下的完整生成代码与关键配置。读完本文,你将掌握如何针对不同数据类型(文本、URL、图像 Logo、时间序列、分类高基数)组合 ProfileReport 的参数,并能直接基于 examples 目录中的脚本复现每一份报告。
一、示例库整体一览
examples.md 是一份"开箱即用"的示例索引,它用真实的报告链接展示了 data_profiling(该仓库的 Python 包名)在不同行业、不同数据类型、不同定制程度下的表现力:
| 示例 | 数据主题 | 核心看点 |
|---|---|---|
| Census Income | 美国成人普查数据 | 列定义注入、数据集元信息、缺失值预处理 |
| NASA Meteorites | 陨石着陆记录 | 构造各类"问题列"(常量、布尔、混合、相关、重复) |
| Titanic | 泰坦尼克号乘客数据 | 最经典的入门数据集 |
| NZA | 荷兰医保局开放数据 | 大文件读取、日期解析、自定义 Logo |
| Stata Auto | 1978 年汽车数据 | Stata 格式文件直读 |
| Colors | 颜色名称数据 | 多列类型混合的简单示例 |
| Vektis | 荷兰医疗数据 | 分号分隔 CSV、按需关闭部分相关系数 |
| UCI Bank | 银行营销数据 | 压缩包数据缓存、营销建模场景 |
| Russian Vocabulary | 俄语词频数据 | Unicode 文本分析(词/字符) |
| Website Inaccessibility | 网站可达性数据 | URL 数据类型的在线检测 |
| Orange / Coal Prices | 价格演化序列 | HTML 主题(Flatly / United)定制 |
| USA Air Quality | 空气质量时间序列 | tsmode 时间序列剖析 + 热力图 |
| HCC | 肝癌临床数据 | 预处理前后双报告对比 |
这些示例脚本全部集中在仓库根目录的 examples 目录下,每个子目录(或 features/ 下的独立文件)都对应一个可以直接运行生成报告的最小脚本,且统一依赖 ProfileReport 与 data_profiling.utils.cache 提供的数据缓存工具。
二、经典公开数据集示例
2.1 Census Income:列定义与数据集元信息注入
examples/census/census.py 是配置最丰富的示例之一。它先用 cache_file 从 UCI 仓库缓存 adult.data,再手动指定列名(UCI 该数据本身无表头):
from data_profiling import ProfileReport
from data_profiling.config import Dataset
from data_profiling.utils.cache import cache_file
file_name = cache_file(
"census_train.csv",
"https://archive.ics.uci.edu/ml/machine-learning-databases/adult/adult.data",
)
df = pd.read_csv(
file_name, header=None, index_col=False,
names=["age", "workclass", "fnlwgt", "education", "education-num",
"marital-status", "occupation", "relationship", "race", "sex",
"capital-gain", "capital-loss", "hours-per-week", "native-country"],
)
# 将原始数据中的 "?" 统一替换为缺失值
df = df.replace("\\?", np.nan, regex=True)
值得注意的三个定制点:
- 数据集元信息:通过
profile.config.dataset = Dataset(...)注入description、copyright_year、author、creator、url等字段,报告概览(Overview)页会展示这些来源信息。Dataset定义于 src/data_profiling/config.py。 - 列描述:
profile.config.variables.descriptions = definitions从 examples/census/census_column_definition.json 读取每列的业务含义描述。 - 概览精简:
profile.config.show_variable_description = False让概览页只显示描述信息,避免冗余。
最后以 explorative=True 模式生成 census_report.html。从这里可以看到 ProfileReport 的配置体系是对象属性可写的——你完全可以在创建报告后再修改 profile.config 的各个字段。
2.2 NASA Meteorites:主动构造"问题数据"验证检测能力
examples/meteorites/meteorites.py 的核心价值在于:它人为制造了一组数据分析中常见的"麻烦",用来演示报告能检测到什么:
np.random.seed(7331)
df = pd.read_csv(file_name)
df["year"] = pd.to_datetime(df["year"], errors="coerce") # 日期解析(1880 年之前的记录会失效)
df["source"] = "NASA" # 1. 常量列
df["boolean"] = np.random.choice([True, False], df.shape[0]) # 2. 布尔列
df["mixed"] = np.random.choice([1, "A"], df.shape[0]) # 3. 混合类型列
df["unhashable"] = [[1]] * df.shape[0] # 4. 不可哈希列
df["reclat_city"] = df["reclat"] + np.random.normal(scale=5, size=(len(df))) # 5. 高度相关列
df = pd.concat([df, pd.DataFrame(df.iloc[0:10].copy())], ignore_index=True) # 6. 重复行
这段代码精准覆盖了报告中"Alerts(告警)"机制的典型触发源:常量告警、混合类型告警、高相关性告警、重复数据告警等。报告中还会给出与第 3 节 docs/getting-started/concepts.md 所述告警体系一一对应的可视化条目。
此外它还演示了两类配置用法:
html={"style": {"logo": logo_string}}:用 Base64 内联图片替换报告默认 Logo(logo_string是一段很长的data:image/png;base64,...)。correlations={"cramers": {"calculate": False}}:关闭 Cramér's V 相关系数计算,因为该数据集类别变量过多、计算开销大。
2.3 Titanic:最小可用模板
examples/titanic/titanic.py 是整个仓库中最精简的示例,堪称"三行出报告"的标准模板:
df = pd.read_csv(cache_file("titanic.csv", "https://.../titanic.csv"))
profile = ProfileReport(df, title="Titanic Dataset", explorative=True)
profile.to_file("titanic_report.html")
它证明了在多数常规数据集上,ProfileReport(df) 的默认行为已经足够完整:类型推断、缺失值统计、分布可视化、相关性矩阵、样本表都会自动生成。
三、行业开放数据与多格式数据示例
3.1 NZA 与 Vektis:荷兰医疗/医保数据
荷兰的开放数据在两个示例中各有侧重:
- examples/nza/nza.py 读取荷兰医保局的 DBC 数据,使用
pd.read_csv(file_name, low_memory=False)处理大文件,并将"JAAR"列按%Y格式解析为日期;同样注入了自定义 Base64 Logo。 - examples/vektis/vektis.py 读取 Vektis 邮编数据时指定
sep=";"(欧洲 CSV 常见分隔符),并通过correlations配置一次性关闭三个计算代价较高的相关系数:
report = ProfileReport(
df,
title="Vektis Postal Code 2017",
correlations={
"kendall": {"calculate": False},
"phi_k": {"calculate": False},
"cramers": {"calculate": False},
},
)
这类"按需关闭相关系数"的做法在列数多、类别基数大的数据上能显著缩短报告生成时间。
3.2 UCI Bank 与 Stata Auto:压缩包与 Stata 格式
- examples/bank_marketing_data/banking_data.py 使用
cache_zipped_file下载并解压bank.zip,再以sep=";"读取 UCI 银行营销数据集——该数据正是 GCP 金融倾向性建模方案中使用的数据。 - examples/stata_auto/stata_auto.py 直接用
pd.read_stata读取.dta格式文件(1978 年汽车数据),展示了data_profiling与 pandas 全生态数据读取能力的无缝衔接。
3.3 Colors:最小多类型数据集
examples/colors/colors.py 为颜色名 CSV 指定了列名 ["Code", "Name", "Hex", "R", "G", "B"],其中 Hex 是字符串、R/G/B 是数值,一份报告即可同时覆盖字符串与数值列的剖析,适合作为快速体验的 playground。
四、特性展示型示例:文本、URL 与主题定制
features/ 目录集中了"为了验证某项特性而存在"的示例,对应的正是 examples.md 中功能展示最密集的一组。
4.1 俄语词汇:Unicode 文本深度分析
examples/features/russian_vocabulary.py 读取 1000 个高频俄语词(含英文翻译与词性),核心配置是:
profile = ProfileReport(
df,
title="Russian 1000 most occurring words | Profile Report",
vars={"cat": {"words": True, "characters": True}},
)
vars.cat.words 与 vars.cat.characters 两个开关会为类别列额外生成词频分析与字符级频率分析。由于俄语采用西里尔字母,这份报告能直观验证包对 Unicode 文本的切分与统计能力。
4.2 网站可达性:URL 数据类型在线检测
examples/features/urls.py 把 Berkman Center 的 URL 清单读入 DataFrame,并开启 URL 类型的专用分析:
df = pd.read_csv(file_name, parse_dates=["date_added"])
profile = ProfileReport(
df,
title="Website Inaccessibility Test Lists",
vars={"url": {"active": True}},
)
vars.url.active=True 会触发对每个 URL 的在线可达性探测(如返回状态、跳转等),这是 data_profiling 针对 URL 数据类型的独有扩展能力,见 docs/features/profile_values.md 中关于特殊类型的说明。
4.3 价格序列:Flatly 与 United 双主题演示
主题定制分别由两个脚本演示:
- examples/features/theme_flatly_demo.py:读取 IMF 煤炭价格数据(
parse_dates=["DATE"]),输出flatly_report.html; - examples/features/theme_united_demo.py:读取 IMF 橙子价格数据,且额外传入
orange_mode=True(橙色主题模式),输出united_report.html。
两者都把自定义 Logo 放在 html={"style": {"logo": ...}} 中。结合 docs/advanced_settings/available_settings.md 可以看到,html.style 下可配置的主题项远不止 Logo,还包括导航栏配色、侧边栏样式等。
五、高级场景示例:时间序列与数据集对比
这两类示例代表 examples.md 中"最能体现包深度"的两个方向。
5.1 USA Air Quality:逐站点时间序列剖析
examples/usaairquality/usaairquality.py 演示了完整的时间序列 Profiling 工作流:
from data_profiling.visualisation.plot import timeseries_heatmap
df = df[df["State"] == "Arizona"]
df["Date Local"] = pd.to_datetime(df["Date Local"])
# 1. 先画整体时间热力图(按实体分组、按时间排序)
timeseries_heatmap(dataframe=df, entity_column="Site Num", sortby="Date Local")
# 2. 再按站点逐个生成时间序列报告
for group in df.groupby("Site Num"):
profile = ProfileReport(group[1], tsmode=True, sortby="Date Local")
profile.to_file(f"Ts_Profile_{group[0]}.html")
这里 tsmode=True 会启用时间序列模式,报告将包含自相关、平稳性、季节性等时间序列专属指标;sortby 指定按哪一列排序以恢复时间顺序。热力图函数 timeseries_heatmap 位于 src/data_profiling/visualisation/plot.py。更完整的时间序列能力说明可参考 docs/features/time_series_datasets.md。
5.2 HCC:预处理前后对比报告
examples/hcc/eda-with-feature-comparison.py 是"数据清洗前后对比"的教科书式示例:
original_report = ProfileReport(df, title="Original Data")
original_report.to_file("original_report.html")
# 清洗:去重、删列、均值填充缺失
df_transformed = df.copy().drop_duplicates().drop(columns="O2")
df_transformed["Ferritin"] = mean_imputer.fit_transform(...)
transformed_report = ProfileReport(df_transformed, title="Transformed Data")
comparison_report = original_report.compare(transformed_report)
comparison_report.to_file("original_vs_transformed.html")
核心是 ProfileReport.compare() 方法:它接受两份报告对象,输出逐变量的并排对比视图(分布、缺失率、类型变化等)。HCC(肝细胞癌)数据集来自医疗领域,预处理前后的差异(去重、删除高度相关列、缺失值插补)可以在对比报告中一目了然。该用例对应仓库中的 Notebook 版本 examples/hcc/eda-with-feature-comparison.ipynb,并可在 docs/features/comparing_datasets.md 找到更系统的说明。
六、统一的数据获取机制:cache_file 与 cache_zipped_file
细心的读者会发现几乎所有示例都调用了 from data_profiling.utils.cache import cache_file(或 cache_zipped_file)。这是示例层的统一基础设施,实现在 src/data_profiling/utils/cache.py:
cache_file(filename, url):将远程文件下载到本地缓存目录,若本地已存在同名文件则直接复用,避免重复下载;cache_zipped_file:适用于bank.zip这类压缩包,会自动解压。
因此你可以放心地反复运行示例脚本,第二次起基本是秒级生成报告,这也是"示例可复现"的前提。
七、如何运行这些示例
所有示例的入口都是 if __name__ == "__main__":,在已安装 data_profiling 的 Python 环境中直接运行即可,例如:
python examples/titanic/titanic.py
python examples/census/census.py
python examples/usaairquality/usaairquality.py
运行完成后会在对应目录(或当前目录)生成 HTML 报告文件,如 titanic_report.html、census_report.html、Ts_Profile_<站点ID>.html。安装与命令行用法可参考 docs/getting-started/installation.md 与 docs/getting-started/quickstart.md。
小结
从 examples.md 这份索引出发,我们还原了仓库中 12 类真实示例的完整代码与配置逻辑,可以总结出四条可迁移的实战经验:
- 按数据特征开配置:文本列开
vars.cat.words/characters,URL 列开vars.url.active,时间序列开tsmode; - 按规模取舍计算:类别基数大时用
correlations={...: {"calculate": False}}关闭昂贵的相关系数; - 善用元信息注入:
profile.config.dataset与variables.descriptions让报告自带数据字典与来源说明; - 对比驱动数据治理:
ProfileReport.compare()是评估清洗效果、向团队汇报数据质量改进的最佳载体。
需要更深度定制时,可继续查阅 docs/advanced_settings/available_settings.md 与 docs/getting-started/concepts.md,把示例中的配置组合成适合你自己数据集的报告流水线。