Data Profiler | 你的数据里有什么？

DataProfiler 是一个 Python 库，旨在简化数据分析、监控和敏感数据检测。

通过单个命令加载数据，该库会自动格式化并将文件加载到 DataFrame (数据框) 中。Profiling (数据剖析) 数据，库可以识别架构、统计信息、实体（PII / NPI (个人身份信息 / 非个人身份信息)）等。随后，数据剖析结果可用于下游应用程序或报告中。

开始使用只需几行代码（示例 CSV）：

import json
from dataprofiler import Data, Profiler

data = Data("your_file.csv") # Auto-Detect & Load: CSV, AVRO, Parquet, JSON, Text, URL

print(data.data.head(5)) # Access data directly via a compatible Pandas DataFrame

profile = Profiler(data) # Calculate Statistics, Entity Recognition, etc

readable_report = profile.report(report_options={"output_format": "compact"})

print(json.dumps(readable_report, indent=4))

注意：Data Profiler 附带一个预训练的深度学习模型，用于高效识别敏感数据（PII / NPI）。如果需要，可以轻松地将新实体添加到现有的预训练模型中，或者插入一个新的实体识别管道。

如需 API 文档，请访问 文档页面。

如果您有建议或发现错误，请提交问题。

如果您想贡献代码，请访问 贡献指南。

---

安装

要从 pypi 安装完整包：pip install DataProfiler[full]

如果您想安装 ML 依赖项而不生成报告，请使用 DataProfiler[ml]

如果 ML 需求过于严格（例如，您不想安装 tensorflow），您可以使用 DataProfiler[reports] 安装更精简的包。该精简包会禁用默认的敏感数据检测/实体识别（labler）

从 pypi 安装：pip install DataProfiler

什么是数据档案？

在本库中，数据档案 (Data Profile) 是一个包含关于底层数据集的统计信息和预测的字典。其中包含 “全局统计信息” (global_stats)，存储数据集级别的数据；以及 “列/行级别统计信息” (data_stats)（每一列都是一个新的键值对条目）。

结构化档案的格式如下：

"global_stats": {
    "samples_used": int,
    "column_count": int,
    "row_count": int,
    "row_has_null_ratio": float,
    "row_is_null_ratio": float,
    "unique_row_ratio": float,
    "duplicate_row_count": int,
    "file_type": string,
    "encoding": string,
    "correlation_matrix": list[list[int]], (*)
    "chi2_matrix": list[list[float]],
    "profile_schema": {
        string: list[int]
    },
    "times": dict[string, float],
},
"data_stats": [
    {
        "column_name": string,
        "data_type": string,
        "data_label": string,
        "categorical": bool,
        "order": string,
        "samples": list[str],
        "statistics": {
            "sample_size": int,
            "null_count": int,
            "null_types": list[string],
            "null_types_index": {
                string: list[int]
            },
            "data_type_representation": dict[string, float],
            "min": [null, float, str],
            "max": [null, float, str],
            "mode": float,
            "median": float,
            "median_absolute_deviation": float,
            "sum": float,
            "mean": float,
            "variance": float,
            "stddev": float,
            "skewness": float,
            "kurtosis": float,
            "num_zeros": int,
            "num_negatives": int,
            "histogram": {
                "bin_counts": list[int],
                "bin_edges": list[float],
            },
            "quantiles": {
                int: float
            },
            "vocab": list[char],
            "avg_predictions": dict[string, float],
            "data_label_representation": dict[string, float],
            "categories": list[str],
            "unique_count": int,
            "unique_ratio": float,
            "categorical_count": dict[string, int],
            "gini_impurity": float,
            "unalikeability": float,
            "precision": {
                'min': int,
                'max': int,
                'mean': float,
                'var': float,
                'std': float,
                'sample_size': int,
                'margin_of_error': float,
                'confidence_level': float
            },
            "times": dict[string, float],
            "format": string
        },
        "null_replication_metrics": {
            "class_prior": list[int],
            "class_sum": list[list[int]],
            "class_mean": list[list[int]]
        }
    }
]

(*) 目前相关系数矩阵 (correlation_matrix) 的更新功能已禁用。它将在后续更新中恢复。用户仍可通过将 is_enable 选项设置为 True 按需使用它。

非结构化档案的格式如下：

"global_stats": {
    "samples_used": int,
    "empty_line_count": int,
    "file_type": string,
    "encoding": string,
    "memory_size": float, # in MB
    "times": dict[string, float],
},
"data_stats": {
    "data_label": {
        "entity_counts": {
            "word_level": dict[string, int],
            "true_char_level": dict[string, int],
            "postprocess_char_level": dict[string, int]
        },
        "entity_percentages": {
            "word_level": dict[string, float],
            "true_char_level": dict[string, float],
            "postprocess_char_level": dict[string, float]
        },
        "times": dict[string, float]
    },
    "statistics": {
        "vocab": list[char],
        "vocab_count": dict[string, int],
        "words": list[string],
        "word_count": dict[string, int],
        "times": dict[string, float]
    }
}

图结构档案的格式如下：

"num_nodes": int,
"num_edges": int,
"categorical_attributes": list[string],
"continuous_attributes": list[string],
"avg_node_degree": float,
"global_max_component_size": int,
"continuous_distribution": {
    "<attribute_1>": {
        "name": string,
        "scale": float,
        "properties": list[float, np.array]
    },
    "<attribute_2>": None,
    ...
},
"categorical_distribution": {
    "<attribute_1>": None,
    "<attribute_2>": {
        "bin_counts": list[int],
        "bin_edges": list[float]
    },
    ...
},
"times": dict[string, float]

档案统计描述

结构化配置文件

全局统计信息：

• samples_used - 用于生成此配置文件的输入数据样本数量
• column_count - 输入数据集中包含的列数
• row_count - 输入数据集中包含的行数
• row_has_null_ratio - 包含至少一个空值的行数占总行数的比例
• row_is_null_ratio - 完全由空值组成的行（空行）占总行数的比例
• unique_row_ratio - 输入数据集中不同行的数量占总行数的比例
• duplicate_row_count - 在输入数据集中出现次数大于一次的行数
• file_type - 包含输入数据集的文件格式（例如：.csv）
• encoding - 包含输入数据集的文件的编码（例如：UTF-8）
• correlation_matrix - 形状为 column_count x column_count 的矩阵，包含数据集中每列之间的相关系数
• chi2_matrix - 形状为 column_count x column_count 的矩阵，包含数据集中每列之间的卡方统计量
• profile_schema - 描述输入数据集格式的说明，标记每一列及其在数据集中的索引
  • string - 问题列的标签及其在配置文件 schema 中的索引
• times - 生成此数据集全局统计信息所花费的时间（毫秒）

数据统计信息：

• column_name - 该列在输入数据集中的标签/标题
• data_type - 该列中包含的原生 Python 数据类型
• data_label - 由 Labeler 组件确定的该列数据的标签/实体
• categorical - 如果该列包含分类数据则为 'true'
• order - 该列中数据的排序方式（如果有），否则为“random”
• samples - 来自该列的一小部分数据条目
• statistics - 关于该列的统计信息
  • sample_size - 用于生成此配置文件的输入数据样本数量
  • null_count - 样本中空条目的数量
  • null_types - 该样本中存在的不同空值类型的列表
  • null_types_index - 包含每个空值类型及其在该样本中出现位置索引列表的字典
  • data_type_representation - 识别为每种数据类型的样本百分比
  • min - 样本中的最小值
  • max - 样本中的最大值
  • mode - 样本条目的众数
  • median - 样本条目的中位数
  • median_absolute_deviation - 样本条目的中位绝对偏差
  • sum - 该列所有采样值的总和
  • mean - 样本中所有条目的平均值
  • variance - 样本中所有条目的方差
  • stddev - 样本中所有条目的标准差
  • skewness - 样本中所有条目的统计偏度
  • kurtosis - 样本中所有条目的统计峰度
  • num_zeros - 该样本中值为 0 的条目数量
  • num_negatives - 该样本中值小于 0 的条目数量
  • histogram - 包含直方图相关信息
    • bin_counts - 每个 bin 内的条目数量
    • bin_edges - 每个 bin 的阈值
  • quantiles - 按样本中条目顺序列出的每个百分位数的值
  • vocab - 该样本条目中使用的字符列表
  • avg_predictions - 所有采样数据点的数据标签预测置信度的平均值
  • categories - 如果 categorial = 'true'，则列出样本中的每个不同类别
  • unique_count - 样本中不同条目的数量
  • unique_ratio - 样本中不同条目数量与样本总条目数量的比例
  • categorical_count - 如果 categorical = 'true'，则列出每个类别采样的条目数量
  • gini_impurity - 衡量从集合中随机选择一个元素时，如果根据子集中的标签分布进行随机标记，被错误标记的频率
  • unalikeability - 表示样本内条目彼此不同的频率的值
  • precision - 关于每个样本数字位数的统计信息字典
  • times - 生成此样本统计信息所花费的时间（毫秒）
  • format - 可能的日期时间格式列表
• null_replication_metrics - 基于列值是否为空（字典键引用的列表索引 1）或不为空（索引 0）对数据进行分区后的统计信息
  • class_prior - 包含列值为空和不为空的概率的列表
  • class_sum - 基于列值是否为空而包含其他所有行之和的列表
  • class_mean - 基于列值是否为空而包含其他所有行之平均值的列表

非结构化数据档案

global_stats：

• samples_used - 用于生成此档案的输入数据样本数量
• empty_line_count - 输入数据中的空行数量
• file_type - 输入数据的文件类型（例如：.txt）
• encoding - 输入数据文件的编码（例如：UTF-8）
• memory_size - 输入数据的大小（MB）
• times - 生成此档案所需的时间（毫秒）

data_stats：

• data_label - 输入数据标签的标签和统计信息
  • entity_counts - 特定标签或实体在输入数据中出现的次数
    • word_level - 每个标签或实体内计数的单词数量
    • true_char_level - 由模型确定的每个标签或实体内计数的字符数量
    • postprocess_char_level - 由后处理器确定的每个标签或实体内计数的字符数量
  • entity_percentages - 输入数据中每个标签或实体的百分比
    • word_level - 输入数据中包含在每个标签或实体内的单词百分比
    • true_char_level - 由模型确定的输入数据中包含在每个标签或实体内的字符百分比
    • postprocess_char_level - 由后处理器确定的输入数据中包含在每个标签或实体内的字符百分比
  • times - 数据标签器预测数据所需的时间
• statistics - 输入数据的统计信息
  • vocab - 输入数据中每个字符的列表
  • vocab_count - 输入数据中每个不同字符的出现次数
  • words - 输入数据中每个单词的列表
  • word_count - 输入数据中每个不同单词的出现次数
  • times - 生成词汇表和单词统计信息所需的时间（毫秒）

图数据档案

• num_nodes - 图中的节点数量
• num_edges - 图中的边数量
• categorical_attributes - 分类边属性列表
• continuous_attributes - 连续边属性列表
• avg_node_degree - 图中节点的平均度数
• global_max_component_size: 全局最大连通分量的大小

continuous_distribution：

• <attribute_N>: 属性列表中第 N 个边属性的名称
  • name - 属性分布的名称
  • scale - 用于缩放和比较分布的负对数似然值
  • properties - 描述分布的统计属性列表
    • [形状（可选）, 位置，缩放，均值，方差，偏度，峰度]

categorical_distribution：

• <attribute_N>: 属性列表中第 N 个边属性的名称

  • bin_counts: 分布直方图中每个区间的计数
  • bin_edges: 分布直方图中每个区间的边界

• times - 生成此档案所需的时间（毫秒）

支持

支持的数据格式

• 任何分隔符文件 (CSV, TSV 等)
• JSON 对象
• Avro 文件
• Parquet 文件
• 文本文件
• Pandas DataFrame (数据框)
• 指向上述受支持文件类型的 URL

数据类型

数据类型 针对结构化数据在列级别确定

• Int
• Float
• String
• DateTime

数据标签

数据标签 针对结构化数据在单元格级别确定（使用 Profiler 时为列/行），或针对非结构化数据在字符级别确定。

• UNKNOWN
• ADDRESS
• BAN (银行账号，10-18 位数字)
• CREDIT_CARD
• EMAIL_ADDRESS
• UUID
• HASH_OR_KEY (md5, sha1, sha256, 随机哈希等)
• IPV4
• IPV6
• MAC_ADDRESS
• PERSON
• PHONE_NUMBER
• SSN
• URL
• US_STATE
• DRIVERS_LICENSE
• DATE
• TIME
• DATETIME
• INTEGER
• FLOAT
• QUANTITY
• ORDINAL

入门指南

加载文件

Data Profiler (数据分析器) 可以分析以下数据/文件类型：

• CSV 文件（或任何分隔符文件）
• JSON 对象
• Avro 文件
• Parquet 文件
• 文本文件
• Pandas DataFrame (数据框)
• 指向上述受支持文件类型的 URL

分析器应自动识别文件类型并将数据加载到 Data Class (数据类) 中。

与其他属性一起，Data Class (数据类) 允许通过有效的 Pandas DataFrame 访问数据。

# Load a csv file, return a CSVData object
csv_data = Data('your_file.csv')

# Print the first 10 rows of the csv file
print(csv_data.data.head(10))

# Load a parquet file, return a ParquetData object
parquet_data = Data('your_file.parquet')

# Sort the data by the name column
parquet_data.data.sort_values(by='name', inplace=True)

# Print the sorted first 10 rows of the parquet data
print(parquet_data.data.head(10))

# Load a json file from a URL, return a JSONData object
json_data = Data('https://github.com/capitalone/DataProfiler/blob/main/dataprofiler/tests/data/json/iris-utf-8.json')

如果文件类型未被自动识别（罕见情况），您可以具体指定它们，参见章节 指定文件类型或分隔符。

分析文件

示例使用 CSV 文件，但 CSV、JSON、Avro、Parquet 或文本文件同样适用。

import json
from dataprofiler import Data, Profiler

# Load file (CSV should be automatically identified)
data = Data("your_file.csv")

# Profile the dataset
profile = Profiler(data)

# Generate a report and use json to prettify.
report  = profile.report(report_options={"output_format": "pretty"})

# Print the report
print(json.dumps(report, indent=4))

更新档案

目前，数据分析器具备批量更新其档案的功能。

import json
from dataprofiler import Data, Profiler

# Load and profile a CSV file
data = Data("your_file.csv")
profile = Profiler(data)

# Update the profile with new data:
new_data = Data("new_data.csv")
profile.update_profile(new_data)

# Print the report using json to prettify.
report  = profile.report(report_options={"output_format": "pretty"})
print(json.dumps(report, indent=4))

请注意，如果您用来更新档案的数据包含与原始档案数据索引重叠的整数索引，当计算空值行时，索引将“移位”到未使用的值，以确保空值计数和比率仍然准确。

合并档案

如果您有两个具有相同 Schema (模式) 的文件（但数据不同），可以通过加法运算符将两个档案合并在一起。

这也使得档案能够以分布式方式确定。

import json
from dataprofiler import Data, Profiler

# Load a CSV file with a schema
data1 = Data("file_a.csv")
profile1 = Profiler(data1)

# Load another CSV file with the same schema
data2 = Data("file_b.csv")
profile2 = Profiler(data2)

profile3 = profile1 + profile2

# Print the report using json to prettify.
report  = profile3.report(report_options={"output_format": "pretty"})
print(json.dumps(report, indent=4))

注意，如果合并后的分析结果 (profile) 具有重叠的整数索引，在计算空行时，索引将被“移位”到未使用的值，以确保空值计数和比率仍然准确。

分析器差异

为了查找具有相同架构 (schema) 的分析结果之间的变化，我们可以利用 profile 的 diff 函数。diff 将提供整体文件和采样差异，以及数据统计的详细差异。例如，数值列同时包含用于评估相似性的 t-test (t 检验) 和用于量化列分布偏移的 PSI (Population Stability Index)。更多信息详见 Github Pages 中的 Profiler 章节。

创建差异报告如下：

import json
import dataprofiler as dp

# Load a CSV file
data1 = dp.Data("file_a.csv")
profile1 = dp.Profiler(data1)

# Load another CSV file
data2 = dp.Data("file_b.csv")
profile2 = dp.Profiler(data2)

diff_report = profile1.diff(profile2)
print(json.dumps(diff_report, indent=4))

分析 Pandas DataFrame

import pandas as pd
import dataprofiler as dp
import json

my_dataframe = pd.DataFrame([[1, 2.0],[1, 2.2],[-1, 3]])
profile = dp.Profiler(my_dataframe)

# print the report using json to prettify.
report = profile.report(report_options={"output_format": "pretty"})
print(json.dumps(report, indent=4))

# read a specified column, in this case it is labeled 0:
print(json.dumps(report["data_stats"][0], indent=4))

非结构化分析器

除结构化分析器外，DataProfiler 还为 TextData 对象或字符串提供非结构化分析 (unstructured) 功能。当指定 profiler_type 选项为 unstructured 时，非结构化分析器也支持 list[string]、pd.Series(string) 或 pd.DataFrame(string)。以下是使用文本文件的非结构化分析器示例。

import dataprofiler as dp
import json

my_text = dp.Data('text_file.txt')
profile = dp.Profiler(my_text)

# print the report using json to prettify.
report = profile.report(report_options={"output_format": "pretty"})
print(json.dumps(report, indent=4))

下面是另一个使用 pd.Series 字符串的非结构化分析器示例，其中 profiler 选项为 profiler_type='unstructured'

import dataprofiler as dp
import pandas as pd
import json

text_data = pd.Series(['first string', 'second string'])
profile = dp.Profiler(text_data, profiler_type='unstructured')

# print the report using json to prettify.
report = profile.report(report_options={"output_format": "pretty"})
print(json.dumps(report, indent=4))

图分析器

DataProfiler 还支持从 csv 文件对图数据进行分析。以下是使用图数据 csv 文件的图分析器示例：

import dataprofiler as dp
import pprint

my_graph = dp.Data('graph_file.csv')
profile = dp.Profiler(my_graph)

# print the report using pretty print (json dump does not work on numpy array values inside dict)
report = profile.report()
printer = pprint.PrettyPrinter(sort_dicts=False, compact=True)
printer.pprint(report)

访问 文档页面 以获取更多示例和 API 详情

参考文献

Sensitive Data Detection with High-Throughput Neural Network Models for Financial Institutions
作者：Anh Truong, Austin Walters, Jeremy Goodsitt
2020 https://arxiv.org/abs/2012.09597
The AAAI-21 Workshop on Knowledge Discovery from Unstructured Data in Financial Services

DataProfiler 快速上手指南

DataProfiler 是一款 Python 库，旨在简化数据分析、监控及敏感数据（如 PII/NPI）的检测。它支持自动加载多种格式文件并生成详细的数据画像报告。

环境准备

• 操作系统：Windows, macOS, Linux
• Python 版本：需安装 Python 3.x 环境
• 依赖管理：确保已安装 pip 包管理器

安装步骤

推荐使用国内镜像源以加快下载速度（可选）。

1. 基础安装

仅安装核心功能：

pip install DataProfiler

2. 完整功能安装

包含机器学习依赖及报告生成功能（推荐）：

pip install DataProfiler[full]

3. 按需安装

• 仅安装 ML 依赖（不生成报告）：

  pip install DataProfiler[ml]
  

• 轻量级安装（禁用敏感数据检测/实体识别）：

  pip install DataProfiler[reports]
  

提示：若遇到下载速度慢的问题，可使用清华源或阿里源，例如： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple DataProfiler[full]

基本使用

以下示例展示了如何加载数据、生成分析配置并输出 JSON 格式的统计报告。

import json
from dataprofiler import Data, Profiler

data = Data("your_file.csv") # Auto-Detect & Load: CSV, AVRO, Parquet, JSON, Text, URL

print(data.data.head(5)) # Access data directly via a compatible Pandas DataFrame

profile = Profiler(data) # Calculate Statistics, Entity Recognition, etc

readable_report = profile.report(report_options={"output_format": "compact"})

print(json.dumps(readable_report, indent=4))

说明

1. 数据加载：Data 类支持自动检测并加载 CSV、AVRO、Parquet、JSON、文本及 URL 格式。
2. 数据访问：生成的 data.data 对象兼容 Pandas DataFrame，可直接进行后续操作。
3. 分析生成：Profiler 会自动计算统计数据、识别实体（包括预训练的敏感数据模型）。
4. 报告输出：通过 report() 方法获取结构化报告，支持 JSON 等格式导出。