modules.contaDataProcess 模块帮助

本章节包含 modules.contaDataProcess 包中与**污染物浓度类表格数据**处理相关的模块说明，例如将 GDIM / 业务表中的浓度字符串批量转为数值型，供统计、绘图或写入下游模块使用。

ContaDataToNumeric

模块简介与适用场景

ContaDataToNumeric 将 TableData 或 TableCollection 中指定列的**污染物浓度类字符串**转换为数值型（float），并输出同类型的表或表集合。
支持监测数据中常见的浓度写法（如 nd、<0.01、missing 等）；具体转换规则见后文「转换规则说明」。
无法识别的单元格值可通过 invalid_value_action、invalid_warning_type 配置处理方式，详见「参数说明」与「无效值处理说明」。
输入形态：单张 TableData，或 ``TableCollection``（可仅处理部分表，并保留主表 / 子表关系）。
典型适用场景：
- 从 GDIM 读入的浓度字段仍为字符串，需在统计或绘图前统一为数值；
- 仅需处理部分表或部分字段时，通过 process_type、process_tables、concentration_fields 精确控制范围。

端口说明

输入端口 - InputTable：待处理的 TableData 或 TableCollection。
输出端口 - OutputTable：与输入同类型的表或表集合；当 InputTable 为空时为 None。

快速上手示例：单表自动识别污染物浓度字段

process_type="auto" 时，模块会自动处理字段元数据中 data_format 为 pollutantConcentration 的列。

from gdisdk.modules.contaDataProcess import ContaDataToNumeric

module = ContaDataToNumeric(mname="ContaToNumeric")
module.process_type = "auto"
module.InputTable = your_table_data
module.execute()
numeric_table = module.OutputTable.data

快速上手示例：仅处理指定字段

from gdisdk.modules.contaDataProcess import ContaDataToNumeric

module = ContaDataToNumeric(mname="ContaToNumericInclude")
module.process_type = "include"
module.concentration_fields = ["benzene", "甲苯"]  # 字段内部名或字段标题
module.InputTable = your_table_data
module.execute()
numeric_table = module.OutputTable.data

快速上手示例：表集合中按表分别配置

from gdisdk.modules.contaDataProcess import ContaDataToNumeric

module = ContaDataToNumeric(mname="ContaToNumericCollection")
module.process_type = "include"
module.process_tables = ["sample", "其他表"]  # 表内部名或表标题
module.concentration_fields = {
    "sample": ["benzene"],
    "其他表": ["value"],
}
module.InputTable = your_table_collection  # TableCollection
module.execute()
numeric_collection = module.OutputTable.data

快速上手示例：自定义无效值处理

from gdisdk.modules.contaDataProcess import ContaDataToNumeric

module = ContaDataToNumeric(mname="ContaToNumericInvalid")
module.process_type = "auto"
module.invalid_value_action = "to_nan"       # 无效值转为 NaN
module.invalid_warning_type = "gdi_warning"  # 在 GDIM 中显示告警
module.InputTable = your_table_data
module.execute()
numeric_table = module.OutputTable.data

参数说明

ContaDataToNumeric 参数一览
参数名	类型	默认值	说明
`table`	`TableData \| TableCollection \| None`	`None`	构造时可直接赋给 `InputTable`；若为 `None` 则须在后续连接端口或属性赋值传入。
`process_type`	`Literal["auto", "include", "exclude"]`	`"auto"`	字段选择模式。`auto`：自动选择 `data_format` 为 `pollutantConcentration` 的字段；`include`：仅处理 `concentration_fields` 中的字段；`exclude`：处理除 `concentration_fields` 外所有列。
`process_tables`	`list[str] \| None`	`None`	仅 ``TableCollection`` 输入时有效：指定待处理的表名或表标题列表。未指定时处理集合中的全部表；未出现在列表中的表保持原样输出。
`concentration_fields`	`list[str] \| dict[str, list[str]] \| None`	`None`	参与 `include/exclude` 模式的字段名或字段标题。单表可用 `list[str]`；表集合推荐 `dict[表名或表标题, 字段列表]`。表集合 + `list[str]` 时，对 `process_tables` 中各表使用同一字段列表。
`detect_limit`	`float`	`0.0`	`nd`、`小于检出限` 等第二类特殊字符串对应的数值。
`less_than_multiplier`	`float`	`0.5`	`<数字` 形式字符串的换算系数，最终值为该系数乘以 `<` 后的数字。
`missing_error_type`	`Literal["error", "warning", "gdi_warning"]`	`"error"`	当 `process_tables` 或 `concentration_fields` 中配置的表或字段在输入中不存在时的处理方式。`error` 抛出 `KeyError`；`warning` 输出 `UserWarning`；`gdi_warning` 输出 `GDIWarning` 并在 GDIM 中显示警告。
`invalid_value_action`	`Literal["error", "drop_column", "drop_row", "to_nan", "to_detect_limit"]`	`"error"`	待处理列中出现无法识别的单元格值时的处理方式。`error` 抛出 `ValueError`；`drop_column` 删除整列；`drop_row` 删除整行；`to_nan` 转为 `NaN`；`to_detect_limit` 转为 `detect_limit`。空字符串与 `None` 会转为 `NaN`，不视为无效值。
`invalid_warning_type`	`Literal["warning", "gdi_warning"]`	`"gdi_warning"`	当 `invalid_value_action` 不为 `"error"` 时，无效值处理告警的类型。`warning` 输出 `UserWarning`；`gdi_warning` 输出 `GDIWarning` 并在 GDIM 中显示。

转换规则说明

已是数值类型的单元格会转为 float 保留。
可解析为普通数字的字符串会转为对应浮点数。
下列字符串（不区分大小写，除中文项外）转为 NaN：missing、unmeasured、not-measured、nm、unknown、unk、na。
空字符串 "" 与 None 转为 NaN，不视为无效值。
下列字符串转为 detect_limit：nd、nondetect、non-detect、小于检出限。
匹配 <数字 的字符串（如 "<0.01"、"< 0.01"）转为 less_than_multiplier × 数字。
非字符串且非数值类型、以及无法归入以上规则的取值：视为**无效值**，按 invalid_value_action 处理；需要平台可见告警时将 invalid_warning_type 设为 "gdi_warning"。

无效值处理说明

invalid_value_action 选项
取值	行为	是否告警
`"error"`	抛出 `ValueError`，Pipeline 中断	否
`"drop_column"`	删除含无效值的整列	是（按 `invalid_warning_type`）
`"drop_row"`	删除含无效值的整行（同一行任一待处理列无效即删整行）	是（按 `invalid_warning_type`）
`"to_nan"`	将无效单元格转为 `NaN`	是（按 `invalid_warning_type`）
`"to_detect_limit"`	将无效单元格转为 `detect_limit`	是（按 `invalid_warning_type`）

行为与错误说明

process_type="auto" 依赖字段元数据 data_format == "pollutantConcentration"；若上游表未设置该格式，请改用 include 或 exclude 并配置 concentration_fields：待转换列较少时用 include 显式列出；待转换列较多、仅需排除少数非浓度列时，用 exclude 往往更省事。
concentration_fields 为 dict 且 process_type != "auto" 时，键必须与输入表名/表标题匹配；不匹配的表配置会被忽略，并按 missing_error_type 报错或告警。
TableCollection 输入时，输出集合会保留原集合的主表、子表及 primary_key 关系；仅 process_tables 命中的表会做数值转换。
当没有任何列需要处理时，模块返回输入表的**拷贝**，数据内容不变。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.contaDataProcess import ContaDataToNumeric

pipe = PipeLine(app_name="ContaNumericDemo", app_title="污染物浓度转数值示例")

to_numeric = ContaDataToNumeric(mname="ContaToNumeric")
to_numeric.process_type = "auto"
to_numeric.detect_limit = 0.0
to_numeric.less_than_multiplier = 0.5
# reader.OutputTable >> to_numeric.InputTable
pipe.add_module(to_numeric)
pipe.run()

result = to_numeric.OutputTable.data

更多信息

API 参考 - modules 包