modules.dataClean 模块帮助

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

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

NullValueChecker

模块简介与适用场景

• NullValueChecker 按列策略检查指定字段是否存在空值，并按策略报错、告警或忽略。

• 不修改数据：输入对象原样从 OutputTable 传出，适合作为读写、统计、绘图前的质量门禁。

• 支持 TableData、TableCollection 和 ResultModel；列名 / 表名均可写内部名或显示标题。

• 典型适用场景：

  • 从 GDIM 读入业务表后，确认主键、坐标、关键计算结果不为空；

  • 写入 GDIM 或生成报告前，对关键字段做空值门禁；

  • 对计算结果 ResultModel 中的标量字段或列表字段做空值检查。

• 关键提醒：整列为空时只走 all_null_action，部分为空才走 any_null_action；遇到第一个 error 会立即停止。列策略形状与空值判定见后文说明。

端口说明

• 输入端口 - InputTable：待检查的 TableData、TableCollection 或 ResultModel。为 None 时不检查，OutputTable 亦为 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

快速上手示例：检查 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 必须为 {表: {列: 策略}}。详见「列策略说明」。
empty_table_action	Literal["error", "warning", "gdi_warning", "ignore"]	"error"	被检查的表行数为 0 时的处理方式。触发后跳过该表的列空值检查（error 会立即停止）。详见「空表处理说明」。
empty_table_message	str | None	None	空表时的自定义消息。占位符：{table}。为 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	{表: {列: 策略}}	只检查列出的表；未列出的表跳过。表不存在时抛出 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	部分为空时的自定义消息。占位符同上。

空值判定与动作说明

• 视为空值的取值：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，立即停止后续列 / 表 / 字段检查；

  • "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}' 为空表，没有数据。

在 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

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（dataClean）