pandera.api.checks.Check¶

class pandera.api.checks.Check(check_fn, groups=None, groupby=None, ignore_na=True, element_wise=False, name=None, error=None, raise_warning=False, n_failure_cases=None, title=None, description=None, statistics=None, strategy=None, **check_kwargs)[source]¶

检查数据对象是否具有某些属性。

对数据对象应用验证函数。

Parameters:

check_fn (Callable) –
一个用于检查数据对象的函数。对于列或系列模式检查，如果 element_wise 为 True，则此函数应具有签名： Callable[[pd.Series], Union[pd.Series, bool]]，输出系列是一个布尔向量。

如果 element_wise 为 False，则此函数应具有以下签名： Callable[[Any], bool]，其中 Any 是列中的一个元素。

对于 DataFrame 模式检查，如果 element_wise=True，fn 应具有签名： Callable[[pd.DataFrame], Union[pd.DataFrame, pd.Series, bool]]，输出的数据框或系列包含布尔值。

如果 element_wise 为 True，fn 将应用于数据框的每一行，具有以下签名 Callable[[pd.Series], bool] 其中系列输入是一行数据框。
groups (Union[str, List[str], None]) – 传递给fn 可调用的字典输入将受限于groups指定的组。
groupby (Union[str, List[str], Callable, None]) –
如果提供了字符串或字符串列表，这些列将用于分组列系列。如果传递了一个可调用对象，预期的签名是: Callable[ [pd.DataFrame], pd.core.groupby.DataFrameGroupBy]

在Column检查的情况下，此函数可以访问整个数据框，但Column.name是从此DataFrameGroupby对象中选择的，以便将SeriesGroupBy对象传递给check_fn。

指定groupby参数会改变check_fn的签名为:

Callable[[Dict[Union[str, Tuple[str]], pd.Series]], Union[bool, pd.Series]] # noqa

其中输入是一个将键映射到列/数据框子集的字典。
ignore_na (bool) – 如果为 True，在判断检查是否通过或失败时将忽略空值。对于数据框，忽略任何包含空值的行。新版本 0.4.0 中新增
element_wise (bool) – 是否以逐元素的方式应用验证器。如果是bool，则假设所有检查应逐列应用。如果是列表，则元素的数量应与检查的数量相同。
name (可选[str, None]) – 检查的可选名称。
错误 (Optional[str, None]) – 如果系列未通过验证检查，则自定义错误消息。
raise_warning (bool) – 如果为 True，抛出一个 SchemaWarning 而不是抛出一个 SchemaError，用于特定检查。这一选项应谨慎使用，在检查失败是信息性的情况下，并且不应停止程序的执行时。
n_failure_cases (可选[int, 无]) – 报告前n个独特的失败案例。如果无，报告所有失败案例。
标题 (可选[字符串, 无]) – 检查的可读性标签。
描述 (可选[str, None]) – 一个任意的检查文本描述。
统计 (可选[字典[字符串, 任意], 无]) – 传递给检查函数的关键字参数。这些值被序列化并表示检查的约束。
策略 (可选[任何, 无]) – 一种假设策略，用于实现此检查的数据合成策略。有关更多详细信息，请参阅用户指南。
check_kwargs – 传递给 check_fn 的关键字参数

Example:

下面的示例使用了 pandas，但适用于任何支持的 dataframe libraries。

>>> import pandas as pd
>>> import pandera as pa
>>>
>>>
>>> # column checks are vectorized by default
>>> check_positive = pa.Check(lambda s: s > 0)
>>>
>>> # define an element-wise check
>>> check_even = pa.Check(lambda x: x % 2 == 0, element_wise=True)
>>>
>>> # checks can be given human-readable metadata
>>> check_with_metadata = pa.Check(
...     lambda x: True,
...     title="Always passes",
...     description="This check always passes."
... )
>>>
>>> # specify assertions across categorical variables using `groupby`,
>>> # for example, make sure the mean measure for group "A" is always
>>> # larger than the mean measure for group "B"
>>> check_by_group = pa.Check(
...     lambda measures: measures["A"].mean() > measures["B"].mean(),
...     groupby=["group"],
... )
>>>
>>> # define a wide DataFrame-level check
>>> check_dataframe = pa.Check(
...     lambda df: df["measure_1"] > df["measure_2"])
>>>
>>> measure_checks = [check_positive, check_even, check_by_group]
>>>
>>> schema = pa.DataFrameSchema(
...     columns={
...         "measure_1": pa.Column(int, checks=measure_checks),
...         "measure_2": pa.Column(int, checks=measure_checks),
...         "group": pa.Column(str),
...     },
...     checks=check_dataframe
... )
>>>
>>> df = pd.DataFrame({
...     "measure_1": [10, 12, 14, 16],
...     "measure_2": [2, 4, 6, 8],
...     "group": ["B", "B", "A", "A"]
... })
>>>
>>> schema.validate(df)[["measure_1", "measure_2", "group"]]
    measure_1  measure_2 group
0         10          2     B
1         12          4     B
2         14          6     A
3         16          8     A

请查看这里获取更多使用详情。

属性

`one_sample_ttest`
`two_sample_ttest`
`BACKEND_REGISTRY`
`CHECK_FUNCTION_REGISTRY`
`REGISTERED_CUSTOM_CHECKS`

方法

__init__(check_fn, groups=None, groupby=None, ignore_na=True, element_wise=False, name=None, error=None, raise_warning=False, n_failure_cases=None, title=None, description=None, statistics=None, strategy=None, **check_kwargs)[source]¶

对数据对象应用验证函数。

Parameters:

check_fn (Callable) –
一个用于检查数据对象的函数。对于列或系列模式检查，如果 element_wise 为 True，则此函数应具有签名： Callable[[pd.Series], Union[pd.Series, bool]]，输出系列是一个布尔向量。

如果 element_wise 为 False，则此函数应具有以下签名： Callable[[Any], bool]，其中 Any 是列中的一个元素。

对于 DataFrame 模式检查，如果 element_wise=True，fn 应具有签名： Callable[[pd.DataFrame], Union[pd.DataFrame, pd.Series, bool]]，输出的数据框或系列包含布尔值。

如果 element_wise 为 True，fn 将应用于数据框的每一行，具有以下签名 Callable[[pd.Series], bool] 其中系列输入是一行数据框。
groups (Union[str, List[str], None]) – 传递给fn 可调用的字典输入将受限于groups指定的组。
groupby (Union[str, List[str], Callable, None]) –
如果提供了字符串或字符串列表，这些列将用于分组列系列。如果传递了一个可调用对象，预期的签名是: Callable[ [pd.DataFrame], pd.core.groupby.DataFrameGroupBy]

在Column检查的情况下，此函数可以访问整个数据框，但Column.name是从此DataFrameGroupby对象中选择的，以便将SeriesGroupBy对象传递给check_fn。

指定groupby参数会改变check_fn的签名为:

Callable[[Dict[Union[str, Tuple[str]], pd.Series]], Union[bool, pd.Series]] # noqa

其中输入是一个将键映射到列/数据框子集的字典。
ignore_na (bool) – 如果为 True，则在判断检查是否通过或失败时将忽略空值。对于数据框，忽略任何包含空值的行。 新版本 0.4.0 中新增
element_wise (bool) – 是否以逐元素的方式应用验证器。如果是bool，则假设所有检查应逐列应用。如果是列表，则元素的数量应与检查的数量相同。
name (可选[str, None]) – 检查的可选名称。
错误 (可选[字符串, 无]) – 如果系列未通过验证检查，则为自定义错误消息。
raise_warning (bool) – 如果为 True，抛出一个 SchemaWarning 而不是抛出一个 SchemaError，用于特定检查。这一选项应谨慎使用，在检查失败是信息性的情况下，并且不应停止程序的执行时。
n_failure_cases (可选[int, 无]) – 报告前n个独特的失败案例。如果无，报告所有失败案例。
标题 (可选[字符串, 无]) – 检查的可读性标签。
描述 (可选[str, None]) – 一个任意的检查文本描述。
统计 (可选[字典[字符串, 任意], 无]) – 传递给检查函数的关键字参数。这些值被序列化并表示检查的约束。
策略 (可选[任何, 无]) – 一种假设策略，用于实施此检查的数据综合策略。详情请参见用户指南。
check_kwargs – 传递给 check_fn 的关键字参数

Example:

下面的示例使用了 pandas，但适用于任何支持的 dataframe libraries。

>>> import pandas as pd
>>> import pandera as pa
>>>
>>>
>>> # column checks are vectorized by default
>>> check_positive = pa.Check(lambda s: s > 0)
>>>
>>> # define an element-wise check
>>> check_even = pa.Check(lambda x: x % 2 == 0, element_wise=True)
>>>
>>> # checks can be given human-readable metadata
>>> check_with_metadata = pa.Check(
...     lambda x: True,
...     title="Always passes",
...     description="This check always passes."
... )
>>>
>>> # specify assertions across categorical variables using `groupby`,
>>> # for example, make sure the mean measure for group "A" is always
>>> # larger than the mean measure for group "B"
>>> check_by_group = pa.Check(
...     lambda measures: measures["A"].mean() > measures["B"].mean(),
...     groupby=["group"],
... )
>>>
>>> # define a wide DataFrame-level check
>>> check_dataframe = pa.Check(
...     lambda df: df["measure_1"] > df["measure_2"])
>>>
>>> measure_checks = [check_positive, check_even, check_by_group]
>>>
>>> schema = pa.DataFrameSchema(
...     columns={
...         "measure_1": pa.Column(int, checks=measure_checks),
...         "measure_2": pa.Column(int, checks=measure_checks),
...         "group": pa.Column(str),
...     },
...     checks=check_dataframe
... )
>>>
>>> df = pd.DataFrame({
...     "measure_1": [10, 12, 14, 16],
...     "measure_2": [2, 4, 6, 8],
...     "group": ["B", "B", "A", "A"]
... })
>>>
>>> schema.validate(df)[["measure_1", "measure_2", "group"]]
    measure_1  measure_2 group
0         10          2     B
1         12          4     B
2         14          6     A
3         16          8     A

请查看这里获取更多使用详情。

classmethod between(min_value, max_value, include_min=True, include_max=True, **kwargs)[source]¶

函数 in_range() 的别名

Return type:: 检查

classmethod eq(value, **kwargs)[source]¶

等于的别名 equal_to()

Return type:: 检查

classmethod equal_to(value, **kwargs)[source]¶

确保数据容器的所有元素都等于某个值。

Parameters:: 值 (Any) – 这个数据对象中的值必须等于这个值。
Return type:: 检查

classmethod ge(min_value, **kwargs)[source]¶

等于或大于的别名 greater_than_or_equal_to()

Return type:: 检查

classmethod greater_than(min_value, **kwargs)[source]¶

确保数据容器的值严格大于最小值。

Parameters:: min_value (Any) – 必须超出的下界。必须是可与待验证数据对象的数据类型（例如，float或int的数值类型以及datetime的日期时间）进行比较的类型。
Return type:: 检查

classmethod greater_than_or_equal_to(min_value, **kwargs)[source]¶

确保所有值都大于或等于某个值。

Parameters:: min_value (Any) – 数据值的允许最小值。必须是可与要验证的数据对象的dtype进行比较的类型。
Return type:: 检查

classmethod gt(min_value, **kwargs)[source]¶

函数 greater_than() 的别名

Return type:: 检查

classmethod in_range(min_value, max_value, include_min=True, include_max=True, **kwargs)[source]¶

确保序列中的所有值都在一个区间内。

两个端点必须与要验证的数据对象的dtype相当。

Parameters:

min_value (~T) – 区间的左端点/下端点。
max_value (~T) – 区间的右侧/上侧端点。必须大于或等于 min_value。
include_min (bool) – 定义是否 min_value 也是一个允许的值（默认）或者所有值必须严格大于 min_value。
include_max (bool) – 定义 min_value 是否也是一个允许的值（默认值），或者所有值是否必须严格小于 max_value。

Return type:

检查

classmethod isin(allowed_values, **kwargs)[source]¶

确保系列中仅出现允许的值。

这检查数据对象的所有元素是否属于允许值的元素集合。如果允许值是一个字符串，则元素集合由字符串的所有不同字符组成。因此，只有在允许值中至少出现一次的单个字符才能满足此条件。如果您想检查子字符串，请使用 Check.str_contains()。

Parameters:

allowed_values (可迭代的) – 允许的值的集合。可以是任何可迭代对象。
kwargs – 传递给Check 初始化器的关键字参数。

Return type:

检查

classmethod le(max_value, **kwargs)[source]¶

的别名 less_than_or_equal_to()

Return type:: 检查

classmethod less_than(max_value, **kwargs)[source]¶

确保一系列的值严格低于最大值。

Parameters:: max_value (Any) – 一个序列的所有元素必须严格小于此。必须是可以与要验证的数据对象的dtype进行比较的类型。
Return type:: 检查

classmethod less_than_or_equal_to(max_value, **kwargs)[source]¶

确保一系列的值严格低于最大值。

Parameters:: max_value (Any) – 不可超过的上界。必须是与要验证的数据对象的dtype可比较的类型。
Return type:: 检查

classmethod lt(max_value, **kwargs)[source]¶

的别名为 less_than()

Return type:: 检查

classmethod ne(value, **kwargs)[source]¶

的别名 not_equal_to()

Return type:: 检查

classmethod not_equal_to(value, **kwargs)[source]¶

确保数据容器的元素不等于某个特定值。

Parameters:: value (Any) – 此值不得出现在数据对象中。
Return type:: 检查

classmethod notin(forbidden_values, **kwargs)[source]¶

确保一些定义的值在一系列中不会出现。

像 Check.isin() 这样的检查如果应用于字符串，则操作于单个字符。如果 forbidden_values 是一个字符串，它被理解为禁止字符的集合。任何长度大于 1 的字符串在设计上不能包含在其中。

Parameters:

forbidden_values (Iterable) – 不应出现的值集合。可以是任何可迭代对象。
raise_warning – 如果为真，则在验证时抛出 SchemaWarning 而不是 SchemaError。

Return type:

检查

classmethod str_contains(pattern, **kwargs)[source]¶

确保每一行内都可以找到一个模式。

Parameters:

模式 (Union[str, Pattern]) – 用于搜索的正则表达式模式
kwargs – 传递给Check 初始化器的关键字参数。

Return type:

检查

classmethod str_endswith(string, **kwargs)[source]¶

确保所有值以某个字符串结尾。

Parameters:

string (str) – 字符串所有值应以此结尾
kwargs – 传递给Check 初始化器的关键字参数。

Return type:

检查

classmethod str_length(min_value=None, max_value=None, **kwargs)[source]¶

确保字符串的长度在指定范围内。

Parameters:

min_value (可选[整数, 无]) – 字符串的最小长度（默认：无最小值）
max_value (可选[整数, 无]) – 字符串的最大长度（默认：没有最大值）

Return type:

检查

classmethod str_matches(pattern, **kwargs)[source]¶

确保字符串以正则表达式匹配开始。

Parameters:

模式 (Union[str, Pattern]) – 用于匹配的正则表达式模式
kwargs – 传递给Check 初始化器的关键字参数。

Return type:

检查

classmethod str_startswith(string, **kwargs)[source]¶

确保所有值都以某个字符串开头。

Parameters:

string (str) – 所有值应该以字符串开头
kwargs – 传递给Check 初始化器的关键字参数。

Return type:

检查

classmethod unique_values_eq(values, **kwargs)[source]¶

确保数据对象中的唯一值包含所有值。

注意

与 isin() 相比，此检查确保 values 可迭代中的所有项都包含在系列中。

Parameters:: values (str) – 必须存在的一组值。可以是任何可迭代的对象。
Return type:: 检查

__call__(check_obj, column=None)[source]¶

验证 DataFrame 或 Series。

Parameters:

check_obj (Any) – 要验证的 Series 的 DataFrame。
列 (可选[字符串, 无]) – 对于数据框检查，将检查函数应用于此列。

Return type:

CheckResult

Returns:

检查结果元组包含：

check_output: 布尔标量，Series 或 DataFrame指示哪些元素通过了检查。

check_passed: 布尔标量，指示检查是否总体通过。

checked_object: 被检查的对象本身。根据提供给Check的选项，这将是一系列、数据框，或者如果groupby选项被验证后端支持并指定，则为Dict[str, Series]或Dict[str, DataFrame]，其中键是不同的组。

failure_cases: 失败的检查对象的子集。