fg-data-profiling 示例库全解析:12 类真实数据集的 Profiling 报告实战指南

原创2026-09-21 12:33:481,635 阅读
文章标签:数据分析数据可视化数据科学

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)

值得注意的三个定制点:

  1. 数据集元信息:通过 profile.config.dataset = Dataset(...) 注入 description、copyright_year、author、creator、url 等字段,报告概览(Overview)页会展示这些来源信息。Dataset 定义于 src/data_profiling/config.py。
  2. 列描述:profile.config.variables.descriptions = definitions 从 examples/census/census_column_definition.json 读取每列的业务含义描述。
  3. 概览精简: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 双主题演示

主题定制分别由两个脚本演示:

两者都把自定义 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 类真实示例的完整代码与配置逻辑,可以总结出四条可迁移的实战经验:

  1. 按数据特征开配置:文本列开 vars.cat.words/characters,URL 列开 vars.url.active,时间序列开 tsmode;
  2. 按规模取舍计算:类别基数大时用 correlations={...: {"calculate": False}} 关闭昂贵的相关系数;
  3. 善用元信息注入:profile.config.dataset 与 variables.descriptions 让报告自带数据字典与来源说明;
  4. 对比驱动数据治理:ProfileReport.compare() 是评估清洗效果、向团队汇报数据质量改进的最佳载体。

需要更深度定制时,可继续查阅 docs/advanced_settings/available_settings.md 与 docs/getting-started/concepts.md,把示例中的配置组合成适合你自己数据集的报告流水线。

登录后查看全文
fg-data-profiling