精准数据测试的开源框架¶

为科学家、工程师和寻求正确性的分析师提供的数据验证。

Project Status: Active – The project has reached a stable, usable state and is being actively developed.

pandera 是一个 Union.ai 开源项目，提供了一种灵活且富有表现力的 API，用于对类似于数据框的对象进行数据验证，以使数据处理管道更加易读和健壮。

数据框包含信息，pandera 在运行时显式验证这些信息。这在对生产至关重要的数据管道或可重复的研究环境中非常有用。使用 pandera，您可以：

定义一个模式一次，并使用它来验证不同的数据框类型，包括 pandas、polars、dask、modin 和 pyspark.pandas。
检查列中的类型和属性在一个 pd.DataFrame 或者值在一个 pd.Series 中。
执行更复杂的统计验证，如假设检验。
解析数据以标准化产生有效数据所需的预处理步骤。
无缝集成现有的数据分析/处理管道通过函数装饰器。
使用基于类的API定义数据框模型，采用pydantic风格的语法，并使用类型语法验证数据框。
从架构对象合成数据用于基于属性的测试与 pandas 数据结构。
惰性验证数据框，以便在引发错误之前执行所有验证规则。
集成与丰富的python工具生态系统，如pydantic、fastapi和mypy。

安装¶

使用 pip 安装：

pip install pandera

或者 conda:

conda install -c conda-forge pandera

额外¶

安装附加功能：

pip

pip install 'pandera[hypotheses]'  # hypothesis checks
pip install 'pandera[io]'          # yaml/script schema io utilities
pip install 'pandera[strategies]'  # data synthesis strategies
pip install 'pandera[mypy]'        # enable static type-linting of pandas
pip install 'pandera[fastapi]'     # fastapi integration
pip install 'pandera[dask]'        # validate dask dataframes
pip install 'pandera[pyspark]'     # validate pyspark dataframes
pip install 'pandera[modin]'       # validate modin dataframes
pip install 'pandera[modin-ray]'   # validate modin dataframes with ray
pip install 'pandera[modin-dask]'  # validate modin dataframes with dask
pip install 'pandera[geopandas]'   # validate geopandas geodataframes
pip install 'pandera[polars]'      # validate polars dataframes

conda

conda install -c conda-forge pandera-hypotheses  # hypothesis checks
conda install -c conda-forge pandera-io          # yaml/script schema io utilities
conda install -c conda-forge pandera-strategies  # data synthesis strategies
conda install -c conda-forge pandera-mypy        # enable static type-linting of pandas
conda install -c conda-forge pandera-fastapi     # fastapi integration
conda install -c conda-forge pandera-dask        # validate dask dataframes
conda install -c conda-forge pandera-pyspark     # validate pyspark dataframes
conda install -c conda-forge pandera-modin       # validate modin dataframes
conda install -c conda-forge pandera-modin-ray   # validate modin dataframes with ray
conda install -c conda-forge pandera-modin-dask  # validate modin dataframes with dask
conda install -c conda-forge pandera-geopandas   # validate geopandas geodataframes
conda install -c conda-forge pandera-polars      # validate polars dataframes

快速开始¶

import pandas as pd
import pandera as pa

# data to validate
df = pd.DataFrame({
    "column1": [1, 4, 0, 10, 9],
    "column2": [-1.3, -1.4, -2.9, -10.1, -20.4],
    "column3": ["value_1", "value_2", "value_3", "value_2", "value_1"],
})

# define schema
schema = pa.DataFrameSchema({
    "column1": pa.Column(int, checks=pa.Check.le(10)),
    "column2": pa.Column(float, checks=pa.Check.lt(-1.2)),
    "column3": pa.Column(str, checks=[
        pa.Check.str_startswith("value_"),
        # define custom checks as functions that take a series as input and
        # outputs a boolean or boolean Series
        pa.Check(lambda s: s.str.split("_", expand=True).shape[1] == 2)
    ]),
})

validated_df = schema(df)
print(validated_df)

   column1  column2  column3
      1     -1.3  value_1
      4     -1.4  value_2
      0     -2.9  value_3
     10    -10.1  value_2
      9    -20.4  value_1

您可以传递pandas支持的内置python类型，或表示合法的pandas数据类型的字符串，或者pandera的 DataType:

schema = pa.DataFrameSchema({
    # built-in python types
    "int_column": pa.Column(int),
    "float_column": pa.Column(float),
    "str_column": pa.Column(str),

    # pandas dtype string aliases
    "int_column2": pa.Column("int64"),
    "float_column2": pa.Column("float64"),
    # pandas > 1.0.0 support native "string" type
    "str_column2": pa.Column("str"),

    # pandera DataType
    "int_column3": pa.Column(pa.Int),
    "float_column3": pa.Column(pa.Float),
    "str_column3": pa.Column(pa.String),
})

有关数据类型的更多详细信息，请参见 DataType

数据框模型¶

pandera 还提供了一种表达模式的替代 API，灵感来自 dataclasses 和 pydantic。上述 DataFrameModel 的等效 DataFrameSchema 将是：

from pandera.typing import Series

class Schema(pa.DataFrameModel):

    column1: int = pa.Field(le=10)
    column2: float = pa.Field(lt=-1.2)
    column3: str = pa.Field(str_startswith="value_")

    @pa.check("column3")
    def column_3_check(cls, series: Series[str]) -> Series[bool]:
        """Check that column3 values have two elements after being split with '_'"""
        return series.str.split("_", expand=True).shape[1] == 2

Schema.validate(df)

	列1	列2	列3
0	1	-1.3	value_1
1	4	-1.4	value_2
2	0	-2.9	value_3
3	10	-10.1	value_2
4	9	-20.4	值_1

信息性错误¶

如果数据框未通过验证检查， pandera 提供有用的错误信息。还可以为 Check 提供 error 参数以获取自定义错误信息。

在验证Check被违反的情况下：

simple_schema = pa.DataFrameSchema({
    "column1": pa.Column(
        int, pa.Check(lambda x: 0 <= x <= 10, element_wise=True,
                    error="range checker [0, 10]"))
})

# validation rule violated
fail_check_df = pd.DataFrame({
    "column1": [-20, 5, 10, 30],
})

try:
    simple_schema(fail_check_df)
except pa.errors.SchemaError as exc:
    print(exc)

Column 'column1' failed element-wise validator number 0: <Check <lambda>: range checker [0, 10]> failure cases: -20, 30

如果列名指定错误的情况：

# column name mis-specified
wrong_column_df = pd.DataFrame({
    "foo": ["bar"] * 10,
    "baz": [1] * 10
})


try:
    simple_schema(wrong_column_df)
except pa.errors.SchemaError as exc:
    print(exc)

column 'column1' not in dataframe. Columns in dataframe: ['foo', 'baz']

错误报告¶

如果数据框使用 lazy=True 进行惰性验证，错误将会被汇总到一个错误报告中。错误报告将 DATA 和 SCHEMA 错误进行分组，以便提供数据框内错误来源的概览。以下是架构和数据框：

schema = pa.DataFrameSchema({"id": pa.Column(int, pa.Check.lt(10))}, name="MySchema", strict=True)
df = pd.DataFrame({"id": [1, None, 30], "extra_column": [1, 2, 3]})

try:
    schema.validate(df, lazy=True)
except pa.errors.SchemaErrors as exc:
    print(exc)

{
    "SCHEMA": {
        "COLUMN_NOT_IN_SCHEMA": [
            {
                "schema": "MySchema",
                "column": "MySchema",
                "check": "column_in_schema",
                "error": "column 'extra_column' not in DataFrameSchema {'id': <Schema Column(name=id, type=DataType(int64))>}"
            }
        ],
        "SERIES_CONTAINS_NULLS": [
            {
                "schema": "MySchema",
                "column": "id",
                "check": "not_nullable",
                "error": "non-nullable series 'id' contains null values:1   NaNName: id, dtype: float64"
            }
        ],
        "WRONG_DATATYPE": [
            {
                "schema": "MySchema",
                "column": "id",
                "check": "dtype('int64')",
                "error": "expected series 'id' to have type int64, got float64"
            }
        ]
    },
    "DATA": {
        "DATAFRAME_CHECK": [
            {
                "schema": "MySchema",
                "column": "id",
                "check": "less_than(10)",
                "error": "Column 'id' failed element-wise validator number 0: less_than(10) failure cases: 30.0"
            }
        ]
    }
}

验证上述数据框会导致数据层级错误，即 id 列具有未通过检查的值，以及模式层级错误，例如额外的列和 None 值。

此错误报告对于调试很有用，各列表中的每个项目对应于一个 SchemaError

数据框后端支持的特性¶

当前，pandera 提供三种验证后端: pandas, pyspark, 和 polars。下表显示了 pandera 的哪些特性可用于支持的 dataframe 库:

特征	pandas	pyspark	polars
DataFrameSchema 验证	✅	✅	✅
数据框模型验证	✅	✅	✅
系列模式验证	✅	🚫	❌
索引/多重索引验证	✅	🚫	🚫
内置和自定义检查	✅	✅	✅
分组检查	✅	❌	❌
自定义检查注册	✅	✅	❌
假设检验	✅	❌	❌
内置和自定义 `DataType`s	✅	✅	✅
使用解析器进行预处理	✅	❌	❌
数据合成策略	✅	❌	❌
验证装饰器	✅	✅	✅
惰性验证	✅	✅	✅
删除无效行	✅	❌	✅
Pandera 配置	✅	✅	✅
模式推断	✅	❌	❌
模式持久性	✅	❌	❌
数据格式转换	✅	❌	❌
Pydantic 类型支持	✅	❌	❌
FastAPI支持	✅	❌	❌

图例

✅: 支持
❌: 不支持
🚫: 不适用

注意

在 pandera 中，dask、modin、geopandas 和 pyspark.pandas 支持均利用了 pandas 验证后端。

贡献¶

欢迎所有的贡献、错误报告、错误修复、文档改进、增强和创意。

有关如何贡献的详细概述可以在贡献指南的GitHub上找到。

问题¶

提交问题、功能请求或修复建议到 github。

需要帮助？¶

有很多方式可以获得有关您问题的帮助。您可以在Github Discussions页面上提出问题，或者通过Discord与维护者和pandera社区联系。

如何引用¶

如果您在学术或行业研究中使用 pandera，请考虑引用该论文和/或软件包。

论文 ¶

@InProceedings{ niels_bantilan-proc-scipy-2020,
  author    = { {N}iels {B}antilan },
  title     = { pandera: {S}tatistical {D}ata {V}alidation of {P}andas {D}ataframes },
  booktitle = { {P}roceedings of the 19th {P}ython in {S}cience {C}onference },
  pages     = { 116 - 124 },
  year      = { 2020 },
  editor    = { {M}eghann {A}garwal and {C}hris {C}alloway and {D}illon {N}iederhut and {D}avid {S}hupe },
  doi       = { 10.25080/Majora-342d178e-010 }
}

软件包¶

许可和鸣谢¶

pandera 在 MIT 许可证下授权。并由 Niels Bantilan (niels@union.ai) 编写和维护

索引和表¶

索引

精准数据测试的开源框架¶

安装¶

额外¶

快速开始¶

数据框模型¶

信息性错误¶

错误报告¶

数据框后端支持的特性¶

贡献¶

问题¶

需要帮助？¶

如何引用¶

论文¶

软件包¶

许可和鸣谢¶

索引和表¶

论文 ¶