modules.dataClean 模块帮助

本章节包含 modules.dataClean 包中常用「数据清洗 / 质量检查」模块的使用说明和示例，例如：

按列策略检查表或 ResultModel 中的空值，并在发现问题时报错或告警

NullValueChecker

模块简介与适用场景

NullValueChecker 按列策略检查指定字段是否存在空值，并按策略报错、告警或忽略。
不修改数据：输入对象原样从 OutputTable 传出，适合作为读写、统计、绘图前的质量门禁。
支持 TableData、TableCollection 和 ResultModel；列名 / 表名均可写内部名或显示标题。
典型适用场景：
- 从 GDIM 读入业务表后，确认主键、坐标、关键计算结果不为空；
- 写入 GDIM 或生成报告前，对关键字段做空值门禁；
- 对计算结果 ResultModel 中的标量字段或列表字段做空值检查。
关键提醒：整列为空时只走 all_null_action，部分为空才走 any_null_action；未设置 table_requirement 时，遇到第一个 error 会立即停止。TableCollection 可用 table_requirement 表达备选表组合（如 A 或 (B 且 C)），详见「表条件说明」。列策略形状与空值判定见后文说明。上游把整个输入写成 None 时走 none_input_action``（默认 ``ignore），模块初始化时尚未写入的 None 不会触发，详见「输入整体为 None」。

端口说明

输入端口 - InputTable：待检查的 TableData、TableCollection 或 ResultModel。端口被写入 None 后按 none_input_action 处理，OutputTable 仍为 None``（``error 会先抛出）。尚未写入的 ``None``（含初始化时的自动执行）不检查。
输出端口 - OutputTable：与输入为**同一对象**（不拷贝、不改写）。输入为 None 时为 None。

快速上手示例：检查单表指定列

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.dataClean import NullCheckPolicy, NullValueChecker

table = TableData(
    {"bore_id": ["ZK1", None, "ZK3"], "depth": [12.0, 15.0, 18.0]},
    name="bore_table",
    title="钻孔表",
)

checker = NullValueChecker(mname="CheckNulls")
checker.InputTable = table
checker.column_policies = {
    "bore_id": NullCheckPolicy(any_null_action="error"),
    "depth": {},  # 空 dict 使用默认策略：整列空则报错，部分空则发出 GDI 数据质量告警
}
checker.execute()
out_table = checker.OutputTable.data  # 与输入 table 是同一对象

快速上手示例：检查表集合中的指定表

TableCollection 必须按表嵌套配置；未列入的表不会被检查。

from gdisdk.modules.dataClean import NullCheckPolicy, NullValueChecker

checker = NullValueChecker(mname="CheckCollectionNulls")
checker.InputTable = tables  # TableCollection
checker.column_policies = {
    "钻孔表": {
        "钻孔编号": NullCheckPolicy(any_null_action="error"),
        "孔口高程": {"any_null_action": "gdi_warning"},
    },
    "地层表": {
        "层号": {"all_null_action": "error", "any_null_action": "warning"},
    },
}
checker.execute()
out_tables = checker.OutputTable.data

快速上手示例：备选表组合 A 或 (B 且 C)

from gdisdk.modules.dataClean import NullCheckPolicy, NullValueChecker

checker = NullValueChecker(mname="CheckAltTables")
checker.InputTable = tables  # TableCollection
checker.column_policies = {
    "汇总表": {"编号": NullCheckPolicy(any_null_action="error")},
    "明细表A": {"编号": {"any_null_action": "error"}},
    "明细表B": {"编号": {"any_null_action": "error"}},
}
checker.table_requirement = [["汇总表"], ["明细表A", "明细表B"]]
checker.execute()
out_tables = checker.OutputTable.data

快速上手示例：检查 ResultModel 字段

from gdisdk.dataclass.results import ResultModel, UnitField
from gdisdk.modules.dataClean import NullCheckPolicy, NullValueChecker

result = ResultModel.from_dict(
    {"bearing_capacity": 150.0, "note": "", "layers": ["粘土", None]},
    model_name="BearingResult",
    model_title="承载力计算",
    fields_meta={
        "bearing_capacity": UnitField(title="承载力特征值"),
        "note": UnitField(title="备注"),
        "layers": UnitField(title="土层"),
    },
)

checker = NullValueChecker(mname="CheckResultNulls")
checker.InputTable = result
checker.column_policies = {
    "承载力特征值": NullCheckPolicy(all_null_action="error"),
    "备注": {"all_null_action": "gdi_warning"},
    "土层": {"any_null_action": "gdi_warning"},
}
checker.execute()
out_result = checker.OutputTable.data

参数说明

NullValueChecker 参数一览
参数名	类型	默认值	说明
`table`	`TableData \| TableCollection \| ResultModel \| None`	`None`	构造时可直接赋给 `InputTable`；文档示例推荐用 `InputTable` 端口赋值。
`column_policies`	`dict \| None`	`{}`	按列 / 字段配置检查策略。值为 `NullCheckPolicy` 或等价 `dict`。`TableData` / `ResultModel` 为 `{列: 策略}`；`TableCollection` 必须为 `{表: {列: 策略}}`。详见「列策略说明」。
`display_table_titles`	`dict[str, str] \| None`	`None`	仅 `TableCollection`。键与 `column_policies` / `table_requirement` 的表查找键相同，值是缺表时显示的标题。表存在时仍用该表自己的标题。未给出标题时，缺表消息使用查找键。
`table_requirement`	`list[list[str]] \| None`	`None`	仅 `TableCollection`。二维列表表示「或 / 且」备选表条件，例如 `[["A"], ["B", "C"]]` 表示 `A 或 (B 且 C)`。键可为表名或表标题。详见「表条件说明」。
`empty_table_action`	`Literal["error", "warning", "gdi_warning", "ignore"]`	`"error"`	被检查的表行数为 0 时的处理方式。触发后跳过该表的列空值检查（`error` 会立即停止）。详见「空表处理说明」。
`empty_table_message`	`str \| None`	`None`	空表时的自定义消息。占位符：`{table}`。为 `None` 时使用默认中文消息。
`none_input_action`	`Literal["ignore", "warning", "gdi_warning", "error"]`	`"ignore"`	`InputTable` 被写入且值为 `None` 时的处理方式。初始化时尚未写入的 `None` 不触发。`ignore` / `warning` / `gdi_warning` 仍把 `None` 原样传出；`error` 抛出 `ValueError`。详见「输入整体为 None」。
`none_input_message`	`str \| None`	`None`	输入整体为 `None` 时的自定义消息，按原文发出。为 `None` 时使用默认中文消息。
`treat_empty_string_as_null`	`bool`	`True`	是否将空字符串 `""` 视为空值。仅空格的字符串（如 `" "`）不视为空值。
`treat_empty_list_as_null`	`bool`	`True`	是否将空列表 `[]` 和空元组 `()` 视为空值。`ResultModel` 字段值为 `[]` 或 `()` 时按「全部为空」处理。

列策略说明

column_policies 的形状随输入类型变化；键均可写内部名（name）或显示标题（title）。

`column_policies` 与输入类型
输入类型	配置形态	行为摘要
`TableData`	`{列: 策略}`	只检查列出的列；未列出的列不检查。列不存在时抛出 `KeyError`，消息中的列名见「提示标题」。
`ResultModel`	`{字段: 策略}`	只检查列出的字段；字段不存在时抛出 `KeyError`，消息中的字段名见「提示标题」。
`TableCollection`	`{表: {列: 策略}}`	只检查列出的表；未列出的表跳过。未设置 `table_requirement` 时，表不存在抛出 `KeyError`。若误写成单层 `{列: 策略}`，会抛出 `ValueError`。缺表时的表名见「提示标题」。

策略可用 NullCheckPolicy(...) 或 dict。空 dict``（``{}）等价于全部使用默认值：

NullCheckPolicy 字段
字段	类型	默认值	说明
`all_null_action`	`Literal["error", "warning", "gdi_warning", "ignore"]`	`"error"`	该列 / 字段全部为空时的处理方式。
`any_null_action`	`Literal["error", "warning", "gdi_warning", "ignore"]`	`"gdi_warning"`	该列 / 字段部分为空（有空值但并非全部为空）时的处理方式。
`all_null_message`	`str \| None`	`None`	全部为空时的自定义消息。占位符：`{table}`、`{column}`、`{null_count}`、`{total_count}`。
`any_null_message`	`str \| None`	`None`	部分为空时的自定义消息。占位符同上。
`display_column_title`	`str \| None`	`None`	列或字段找不到时，报错里显示的标题。找到后仍用该列自己的标题。空白或未设置时，使用策略键（字段名或字段标题）。

提示标题

报错和告警里的表名、列名按这个顺序取值：

表或列能对上时，用它自己的标题。
对不上时，用用户指定的标题：列和字段用 NullCheckPolicy.display_column_title，TableCollection 中缺失的表用 display_table_titles。
用户也没有指定时，用策略里的查找键。

这些标题只用于显示，不参与查找。查找键仍是 column_policies / table_requirement 的键，可以是内部名或标题。

空值判定与动作说明

视为空值的取值：None、NaN、NaT、pd.NA；当 treat_empty_string_as_null=True``（默认）时，空字符串 ``"" 也视为空值；当 treat_empty_list_as_null=True``（默认）时，空列表 ``[] 和空元组 () 也视为空值。
仅空格的字符串 **不**视为空值。
整列 / 整个列表为空时，只触发 all_null_action，不会再触发 any_null_action。
ResultModel 的标量字段若为空，按「全部为空」处理（null_count = total_count = 1）。
ResultModel 的 list / tuple 字段：若整个值是空列表 / 空元组且 treat_empty_list_as_null=True，按「全部为空」处理；否则按元素逐项计数。
动作含义：
- "error"：抛出 ValueError。未设置 table_requirement 时立即停止后续列 / 表 / 字段检查；设置后见「表条件说明」。
- "warning"：发出 UserWarning，继续检查；
- "gdi_warning"：发出 ``GDIDataQualityWarning``（可在 GDIM 界面展示），继续检查；
- "ignore"：不提示、不中断。
默认中文消息示例：'钻孔表' 的 '钻孔编号' 列存在空值（1/3）。{table} 取表标题（或 ResultModel 的模型标题），{column} 取列 / 字段自己的标题。对象不存在时的名称见「提示标题」。

空表处理说明

仅对 TableData，以及 TableCollection 中**已列入** column_policies 的表生效；ResultModel 没有「空表」这一动作。
模块会先解析策略中的列名。列不存在时，即使表为空也会先抛出 KeyError。
列均能解析且行数为 0 时，按 empty_table_action 处理，然后**跳过**该表的列空值检查。因此空表不会再按「整列为空」触发 all_null_action。
即使 column_policies 为空，空的 TableData 仍会触发 empty_table_action。
默认消息：'{table}' 为空表，没有数据。

输入整体为 None

与空表不同：空表是已有对象且行数为 0，走 empty_table_action；这里是 InputTable 的值本身为 None。
只在该端口**被写入之后**触发。PipeModule 初始化结束时的自动 execute() 看到的是尚未写入的默认 None，不会告警或报错。流水线运行时，上游输出（包括显式 None）会写入子模块输入，这时才按 none_input_action 处理。
动作与列检查相同：ignore 不提示；warning 发出 UserWarning；gdi_warning 发出 GDIDataQualityWarning；error 抛出 ValueError 并停止运行。除 error 外，OutputTable 仍为 None，下游可以继续。
已连接到上游时，默认消息形如 模块 'Doc2_1' 的输出 'OutputResultModel' 为 None。没有上游链接时，形如 模块 'Check' 的输入 'InputTable' 为 None。none_input_message 按原文发出，不做占位符替换。
放在起始模块输出的旁路上即可，不必插进原有数据连接。一个输出可以同时连到合并模块和检查模块。

表条件说明

table_requirement 仅用于 TableCollection，用二维列表表达「或 / 且」备选表组合。[["A"], ["B", "C"]] 表示 A 或 (B 且 C)。每个键可为表名或表标题。必须写成二维列表；["A", "B"] 或 ["A", ["B", "C"]] 会抛出 ValueError。用于 TableData / ResultModel 时抛出 ValueError。

从左到右检查每个条件组。一组**通过**当且仅当组内每张表都存在，且检查未触发 error / warning / gdi_warning``（``ignore 不算失败）。
第一组通过后，不再检查后续组，也不发出已失败组的告警 / 报错。
全部组都失败时，才发出「组内表都存在」的那些组的全部告警和报错（多个 error 合并为一条 ValueError）。
仅当每一组都因缺表而失败时，才抛出 KeyError``（消息形如 ``不满足表条件 A 或 (B 且 C)：指定的表 'A' 不存在；…）。条件式和「指定的表」里的名称按「提示标题」取值：表存在时用它自己的标题，否则用 display_table_titles，再否则用查找键。
column_policies 中有、但不在 table_requirement 里的表始终必查：缺表立即 KeyError，空值问题立即按策略发出。若要「缺这张表就报错」，把它从 table_requirement 挪到只写在 column_policies 中即可。
组内表存在但策略列不存在时，仍立即抛出 ``KeyError``（配置错误，不作为备选回退）。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.dataClean import NullCheckPolicy, NullValueChecker

pipeline = PipeLine(app_name="NullCheckDemo", app_title="空值检查示例")
pipeline.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["钻孔表"]
read_tables.output_table_name = "钻孔表"

checker = NullValueChecker("CheckNulls")
checker.column_policies = {
    "钻孔编号": NullCheckPolicy(any_null_action="error"),
    "孔口高程": {"any_null_action": "gdi_warning"},
}

pipeline.add_links(read_tables.OutputTable >> checker.InputTable)
pipeline.add_module(read_tables)
pipeline.add_module(checker)
pipeline.run()

table = checker.OutputTable.data

更多信息