modules.statistics 模块帮助

本章节包含 modules.statistics 包中常用「统计功能」模块的使用说明和示例，例如：

对 TableData 做与 pandas describe 等价的汇总统计，并可选抽取部分指标到 ResultModel；
对指定列（或列组合）做 value_counts，输出频次或占比表；
对方向向量或高维特征做**球面 K 均值（Spherical K-Means）**聚类，按余弦相似度划分簇；倾向、倾角需开启 geo_dips，先转为三维单位极点再聚类；
对勘察 统计指标表 按地层/岩土分组做**数理统计**（个数、极值、平均值、标准值、变异系数等），并生成蒙版表与合并 Excel（MathematicalStatistics）。

TableDescribe

模块简介与适用场景

TableDescribe 对输入 TableData 调用 describe，生成一张「统计量 × 列」的汇总表（OutputStatTable），行为与 pandas 一致：数值列给出 count、mean、std、分位数等；文本/object 列给出 count、unique、top、freq 等。
可通过 selected_pairs 从描述结果中抽取「列 + 统计量」到 OutputResultModel，便于写入报表字段或下游结构化输出；键支持**字段内部名**，也支持**字段标题**（会通过 title_to_name 解析）。
典型适用场景：
- 勘察/试验数据入库后，快速得到各数值列的量级、缺失与分布概况；
- 对分类字段做 unique、top、freq 统计（需将 include 设为 "all" 或 ["object"] 等）；
- 只关心少数指标（如某几列的 mean、std）时，用 selected_pairs 输出 ResultModel，避免手写解析 describe 结果表。

端口说明

输入端口 - InputTable：待描述的表格（TableData）；未连接或数据为 None 时，两个输出均为 None。
输出端口 - OutputStatTable：描述结果表（TableData）；索引/行名为统计量名称，列为被描述的字段；若没有任何列可描述（结果为空），则为 None。 - OutputResultModel：由 selected_pairs 抽取的指标集合（ResultModel）；若未配置 selected_pairs 或没有成功抽取到任何值，则为 None。

快速上手示例：默认只描述数值列

from gdisdk.modules import TableDescribe

desc = TableDescribe(mname="Describe")
desc.InputTable = my_table
desc.execute()
stat_table = desc.OutputStatTable.data
# 如需 pandas DataFrame：stat_table.dataframe

快速上手示例：包含文本列，并抽取部分指标到 ResultModel

from gdisdk.modules import TableDescribe

desc = TableDescribe(mname="Describe")
desc.include = "all"
desc.selected_pairs = {
    "厚度": ["mean", "std"],       # 可用字段标题
    "layer_no": ["min", "max"],   # 也可用内部列名
}
desc.InputTable = my_table
desc.execute()
result = desc.OutputResultModel.data
# ResultModel 中字段名为「内部列名_统计量」，如 layer_no_min

快速上手示例：只对部分列做完整 describe

from gdisdk.modules import TableDescribe

desc = TableDescribe(mname="Describe")
desc.describe_columns = ["depth", "qc"]
desc.include = None  # 仍仅对其中数值列做描述
desc.InputTable = my_table
desc.execute()
stat_table = desc.OutputStatTable.data

参数说明

TableDescribe 参数一览
参数名	类型	默认值	说明
`include`	`Literal["all"] \| list[str] \| None`	`None`	`None`：仅数值列；`"all"`：所有类型；`list`：按 pandas 规则筛选 dtype（如 `"object"`、`"number"`、`"float64"` 等）。
`describe_columns`	`list[str] \| None`	`None`	仅对这些列做 `describe` 并写入 `OutputStatTable`；`None` 表示使用全部列（仍受 `include` 约束）。
`selected_pairs`	`dict[str, list[str]] \| None`	`None`	列名或列标题 → 需要的统计量名称列表；结果写入 `OutputResultModel`。统计量名须出现在 `describe` 结果的行索引中（如 `mean`、`25%`、`freq` 等）。

行为说明

当 describe 结果为空（例如筛选后无可描述列）时，OutputStatTable 与 OutputResultModel 均为 None。
selected_pairs 中整型类统计量（如 count、unique、freq）会转为 int，其余非缺失值一般转为 float；缺失统计量为 None。
OutputResultModel 中各字段的 UnitField 会尽量继承原列计量单位，标题形如「原列标题-统计量名」。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules import TableDescribe

pipe = PipeLine(app_name="DescribeDemo", app_title="表格描述示例")

describe = TableDescribe(mname="Describe")
# links = reader.OutputTable >> describe.InputTable
# pipe.add_links(links)
# pipe.run()
# stat_table = describe.OutputStatTable.data
# result = describe.OutputResultModel.data

更多信息

ValuesCount

模块简介与适用场景

ValuesCount 对 TableData 做 value_counts：统计指定列（或全部列）上**取值或取值组合**出现的次数，输出一张窄表（OutputCountTable）。
支持 normalize=True 输出占比；支持排序、升序/降序；dropna=False 时可包含含缺失行的组合。
subset 可使用**字段内部名**或**字段标题**（经 _to_field_names 解析）。
典型适用场景：
- 统计地层名称、土类编码等分类字段的频数；
- 多列联合计数（例如「标段 + 岩性」组合出现了多少次）；
- 需要占比而非原始计数时，设 normalize=True``（结果中频次列名为 ``proportion）。

端口说明

输入端口 - InputTable：输入表（TableData）；为空则输出 None。
输出端口 - OutputCountTable：计数结果表（TableData）。除被统计的列外，最后一列为 count 或 proportion``（由 ``normalize 决定）；表名/标题由模块自动生成。

快速上手示例：单列频数

from gdisdk.modules import ValuesCount

vc = ValuesCount(mname="ValuesCount")
vc.subset = "岩土名称"  # 或内部列名
vc.normalize = False
vc.sort = True
vc.ascending = False
vc.InputTable = my_table
vc.execute()
out = vc.OutputCountTable.data

快速上手示例：多列组合计数与占比

from gdisdk.modules import ValuesCount

vc = ValuesCount(mname="ValuesCount")
vc.subset = ["section_id", "soil_type"]
vc.normalize = True
vc.dropna = True
vc.InputTable = my_table
vc.execute()
out = vc.OutputCountTable.data

快速上手示例：统计所有列的组合（慎用大宽表）

from gdisdk.modules import ValuesCount

vc = ValuesCount(mname="ValuesCount")
vc.subset = None
vc.InputTable = my_table
vc.execute()
out = vc.OutputCountTable.data

参数说明

ValuesCount 参数一览
参数名	类型	默认值	说明
`subset`	`str \| list[str] \| None`	`None`	参与计数的列；单列传字符串，多列传列表；`None` 表示使用全部列的组合（列数多时结果可能很大）。
`normalize`	`bool`	`False`	`True` 时输出占比为 `proportion` 列，否则为 `count`。
`sort`	`bool`	`True`	是否按频次/占比排序。
`ascending`	`bool`	`False`	在 `sort=True` 时是否升序；默认 `False` 为降序（最常见在前）。
`dropna`	`bool`	`True`	`True` 时排除含 NA 的行；`False` 时保留。

行为说明

多列计数时，结果通过 reset_index 展开为多列 + 计数列；模块会尽量把原列的 FieldMetadata 拷到结果列上。
计数列的元数据来自 TableSeries 的 field_meta；列名一般为 count 或 proportion。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules import ValuesCount

pipe = PipeLine(app_name="ValueCountsDemo", app_title="频次统计示例")

vc = ValuesCount(mname="ValuesCount")
vc.subset = "地层名称"
# links = reader.OutputTable >> vc.InputTable
# pipe.add_links(links)
# pipe.run()
# counts = vc.OutputCountTable.data

更多信息

SphericalKMeans

模块简介与适用场景

SphericalKMeans 在 TableData 的数值列上拟合**球面 K 均值**：以**余弦相似度**（而非欧氏距离）优化簇中心，适合已经是方向向量的数据，以及文本嵌入等落在单位超球面（或需按方向比较）的数据。
默认在拟合前对每一行特征做 **L2 归一化**（normalize=True）；若数据已是单位向量，可设 normalize=False 避免重复计算。
倾向、倾角不能按二维向量做 L2 归一化。 这两列是角度。设置 geo_dips=True 后，模块把每一行换成东、北、上方向的单位极点再聚类。feature_columns 依次为倾向、倾角，可用字段名或字段标题；为 None 时使用保留字段 dip_direction、dip_angle。此时忽略 normalize。
feature_columns 支持**字段内部名**与**字段标题**（经 convert_to_field_names 解析）。geo_dips=False 且为 None 时自动选用表中**全部数值列**。
参与拟合的行：在选定特征列上**任一为 NaN** 的行会被**排除**；OutputLabelsTable 仍保留原表所有行，这些行上的 cluster_label 为缺失。
centers_in_original_scale 控制**中心表**的含义。向量模式下，True``（默认）为簇内样本在原始特征尺度上的算术平均，``False 为单位球上的归一化质心。geo_dips=True 时，True 为极点的球面平均换回的倾向和倾角（度），False 为东、北、上单位极点 n_east、n_north、n_up。
典型适用场景：
- 结构面、节理的倾向和倾角分群（geo_dips=True）；
- 已经是方向余弦或单位向量的无监督分群；
- 高维嵌入向量按方向聚类；
- 需要在表格中得到 cluster_label 列及可解释的簇中心表供下游筛选或制图。

端口说明

输入端口 - InputTable：输入表（TableData）；未连接或为空时，两个输出均为 None。
输出端口 - OutputLabelsTable：在**原表所有列**基础上追加整型列 cluster_label``（0 起始簇编号）；未参与拟合的行该列为缺失。 - ``OutputCentersTable：每簇一行；首列为 cluster_id``（0 起始）。其余列在向量模式下与特征列同名；``geo_dips=True 且 centers_in_original_scale=True 时为倾向列和倾角列；该模式下 centers_in_original_scale=False 时为 n_east、n_north、n_up。

快速上手示例：指定特征列

from gdisdk.modules import SphericalKMeans

skm = SphericalKMeans(mname="SphericalKMeans")
skm.feature_columns = ["fx", "fy", "fz"]
skm.n_clusters = 3
skm.random_state = 0
skm.InputTable = my_table
skm.execute()
labeled = skm.OutputLabelsTable.data
centers = skm.OutputCentersTable.data

快速上手示例：自动使用全部数值列

from gdisdk.modules import SphericalKMeans

skm = SphericalKMeans(mname="SphericalKMeans")
skm.n_clusters = 5
skm.InputTable = my_table
skm.execute()
labeled = skm.OutputLabelsTable.data

快速上手示例：倾向与倾角

from gdisdk.modules import SphericalKMeans

skm = SphericalKMeans(mname="SphericalKMeans")
skm.geo_dips = True
skm.feature_columns = ["dip_direction", "dip_angle"]  # 省略则使用这两个保留字段；也可写标题，如「倾向」「倾角」
skm.n_clusters = 3
skm.random_state = 0
skm.InputTable = joints_table
skm.execute()
labeled = skm.OutputLabelsTable.data
centers = skm.OutputCentersTable.data

参数说明

SphericalKMeans 参数一览
参数名	类型	默认值	说明
`feature_columns`	`list[str] \| None`	`None`	用作特征的列名或标题列表。`geo_dips=False` 且为 `None` 时使用全部数值列。`geo_dips=True` 时必须恰好两列，顺序为倾向、倾角；`None` 时使用 `dip_direction`、`dip_angle`。
`n_clusters`	`int`	`5`	簇个数。
`init`	`"k-means++" \| "random"`	`"k-means++"`	初始中心策略；`"k-means++"` 一般更稳健。
`n_init`	`int`	`10`	不同随机种子重复运行次数，取惯性最小的一次结果。
`max_iter`	`int`	`300`	单次运行的最大迭代次数。
`tol`	`float`	`1e-4`	中心位移 Frobenius 范数的收敛容差。
`random_state`	`int \| None`	`None`	随机种子；传入整数可复现结果。
`normalize`	`bool`	`True`	是否在拟合前对每行特征 L2 归一化到单位范数。`geo_dips=True` 时忽略该参数。
`centers_in_original_scale`	`bool`	`True`	向量模式：`True` 为簇内算术平均，`False` 为单位质心。`geo_dips=True`：`True` 为球面平均换回的倾向和倾角（度），`False` 为东、北、上单位极点。
`geo_dips`	`bool`	`False`	`True` 时按 `feature_columns` 中的倾向、倾角聚类：先转为东-北-上单位极点，再做球面 K 均值。倾向按 360 取模，倾角须在 0 到 90 之间。

行为说明

标签表中的 cluster_label 与中心表中的 cluster_id 使用**同一套** 0 起始簇编号：凡 cluster_label == k 的样本，其簇中心为 cluster_id == k 的那一行（中心表按 cluster_id 为 0 … n_clusters-1 排列）。
聚类仅在 dropna 后的有效子集上拟合；标签列对无效行留空，不改变原表行数。
空簇时，centers_in_original_scale=True 下中心行为 NaN。geo_dips=True 时，空簇以及极点平均为零向量的簇，在两种中心输出下都是 NaN。
geo_dips=True 时，倾向在拟合前按 360 取模，标签表仍保留输入原值。倾角超出 0 到 90、两列解析到同一字段、或字段不存在时，执行抛出 ValueError。
产状中心是极点的球面平均换回的角度。簇跨过正北时，这与倾向的算术平均不同。
execute 的返回值为 OutputLabelsTable 对应的 ``TableData``（与端口数据一致）。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules import SphericalKMeans

pipe = PipeLine(app_name="SkmDemo", app_title="球面K均值示例")

skm = SphericalKMeans(mname="SphericalKMeans")
skm.geo_dips = True
skm.feature_columns = ["倾向", "倾角"]  # 字段名或字段标题，顺序为倾向、倾角
skm.n_clusters = 4
# links = reader.OutputTable >> skm.InputTable
# pipe.add_links(links)
# pipe.run()
# labeled = skm.OutputLabelsTable.data
# centers = skm.OutputCentersTable.data

更多信息

MathematicalStatistics

模块简介与适用场景

MathematicalStatistics``（勘察数理统计）从 ``TableCollection 中读取指定的 统计指标表，按 地层编号**（优先）或 **岩土名称 分组，对选定指标列计算勘察成果常用的统计量，并输出原始明细、统计结果、参与/剔除蒙版及按地层块合并的 Excel。
集合中应包含 地层表 layer_table：当指标表某行缺少地层编号或岩土名称时，模块会结合钻孔编号与试验深度（标贯/静探/动探/土工/岩石试验等表有内置深度字段规则）在地层表中反查层位与岩土名称。
默认在每组、每指标列上按 eliminate_params 做离群剔除后再汇总；GDIM 上用户调整蒙版后，可通过 modified_mask_table_json 传入修订后的蒙版表 JSON 重新统计。
典型场景：从 GDIM 读入标贯/静探/土工试验等指标表与地层表，按层统计 N、qc、天然密度等；导出带删除线标记的合并统计 Excel；为 RecentlyDepositedLoess 等模块准备按层汇总的统计表。

端口说明

输入端口
- InputTables：勘察表集合（TableCollection），须能通过 get_table 取到 statistics_table 指定的指标表及 layer_table；未连接或集合为空时，四个输出均为 None。
输出端口
- OutputOriginalDataTable：筛选并补全层位信息后的 **原始数据表**（固定列 layer_number / material_name / bore_number + 统计指标列）。
- OutputStatisticsResultTable： 统计结果表；在固定列基础上增加 ``statistics_item``（统计项目），每个「地层/岩土分组 × 统计项目」一行。
- OutputOriginalDataMaskTable：与原始数据表同形的布尔蒙版；True 表示该单元格参与统计，False 表示被剔除（合并 Excel 中对相应数值加删除线）。
- OutputMergeTableExcel：上传至 GDIM 的合并统计表 Excel（GdimMinIOFile）。生成文件依赖 pipeline 的 GDIM token 与项目 ID；本地无鉴权时会 ValueError。

execute() 的返回值与 OutputOriginalDataTable 一致。

输入表要求

统计指标表**（参数 ``statistics_table``）：表 **name 或 title 与配置一致。需包含 statistics_columns 中的列（支持列 内部名 或 字段标题）。
**钻孔编号**（可选筛选 statistics_bores）：指标表须存在 bore_num / bore_number / 钻孔编号 / 孔号 之一。
**地层编号筛选**（statistics_layers）：若配置非空，指标表须存在 layer_num / layer_number / 地层编号 / 层号 之一。
地层表 layer_table：用于按深度反查层位；须含钻孔列与 ``layer_bottom_depth``（或标题「地层底深度」）等字段，规则与实现一致即可。

快速上手示例：指定指标表与统计列

from gdisdk.modules import MathematicalStatistics

stats = MathematicalStatistics(mname="MathStats")
stats.InputTables = my_table_collection  # 含指标表与 layer_table
stats.statistics_table = "spt_table"
stats.statistics_columns = ["标贯击数", "杆长"]
stats.statistics_bores = []  # 空列表表示不按孔号过滤
stats.statistics_layers = []

stats.execute()
original = stats.OutputOriginalDataTable.data
result = stats.OutputStatisticsResultTable.data
mask = stats.OutputOriginalDataMaskTable.data
excel_file = stats.OutputMergeTableExcel.data

参数说明

MathematicalStatistics 参数一览
参数名	类型	默认值	说明
`statistics_table`	`str \| None`	`None`	必填。统计指标表在集合中的 name 或 title。
`statistics_bores`	`list[str] \| None`	`[]`	仅保留这些钻孔编号的行；空列表表示不过滤。
`statistics_layers`	`list[str] \| None`	`[]`	仅保留这些地层编号的行；空列表表示不过滤（需指标表有地层列）。
`statistics_columns`	`list[str] \| None`	`None`	必填。参与统计的指标列（内部名或标题）。
`statistics_items`	`list[str] \| None`	见下文默认项	必填（默认已给出常用六项）。可选统计项目见「统计项目说明」。
`eliminate_params`	`dict \| None`	见下文	离群剔除配置；`eliminate_method` 为 `None` 时不剔除。
`modified_mask_table_json`	`str \| dict \| None`	`None`	用户修订后的蒙版表（`TableData` 序列化 JSON 或 dict）；行数、列名与顺序须与原始数据表一致。

默认 statistics_items：统计个数、最小值、最大值、平均值、标准值、变异系数。

默认 eliminate_params：

eliminate_method：None``（不剔除）；可选 ``戈罗伯斯、m倍标准差法、肖维勒。
confidence_in_testing_critical_value：``0.05``（戈罗伯斯检验用）。
testing_critical_value：None``（``m倍标准差法时必填）。
test_type：单边检验 或 双边检验。

统计项目说明

模块支持的 statistics_items 取值（须与下表中文名完全一致）：

统计项目
统计项目	含义概要
`统计个数`	蒙版为 `True` 且可转为数值的样本个数（整数）。
`最小值` / `最大值` / `平均值`	组内有效样本的极值与算术平均。
`标准差`	样本标准差（`ddof=1`）；仅 1 个样本时为 `None`。
`变异系数`	标准差 / \|平均值\|；平均值为 0 时为 `None`。
`修正系数` / `标准值`	按 GB 50021 统计修正系数 (gamma_s) 与变异系数计算；标准值 = 平均值 × (gamma_s)。样本数小于 6 时：标准值改用平均值并 `GDIWarning`；修正系数不计算，结果为 `NaN` 并 `GDIWarning`。样本数为 1 时标准差/变异系数为 `None`。
`推荐值`	与平均值相同（便于与平台习惯字段对齐）。

数值型统计结果一般 **保留三位小数**（统计个数 为整数）。

数据剔除说明

剔除在 每个分组 × 每个指标列 上独立进行；仅影响该列蒙版，不改变原始数据表中的数值。
戈罗伯斯：迭代剔除最离群点，直至统计量不超过临界值；样本数少于 3 时不剔除。
肖维勒：按 Chauvenet 准则反复剔除超出阈值的点。
m倍标准差法：剔除与均值之差超过 m × 标准差 的点（m 为 testing_critical_value）；单边/双边由 test_type 控制。
筛选后指标表 无数据行 时，模块发出 GDIWarning，仍返回 空表结构 并尝试生成/上传合并 Excel（与有数据时端口类型一致）。

蒙版表与 Excel 输出

未传入 modified_mask_table_json 时，蒙版初始全为 True，再按 eliminate_params 将剔除位置置为 False。
传入修订蒙版后跳过自动剔除，直接按蒙版汇总。
合并 Excel 按 地层编号 分块：先输出该层全部原始数据行，再输出该层全部统计结果行；地层编号、岩土名称列会对连续相同值做单元格合并；被剔除的数值在 Excel 中以 红色删除线 显示。
OutputMergeTableExcel 使用工作区文件 merge_statistics_table.xlsx 并调用 GDIM 上传接口（app_auto_report）；请在 pipeline 中配置有效 InputToken / 项目上下文。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules import GdimTableReader, MathematicalStatistics

pipe = PipeLine(app_name="MathStatsDemo", app_title="勘察数理统计示例")

reader = GdimTableReader(mname="ReadTables")
stats = MathematicalStatistics(mname="MathStats")
stats.statistics_table = "spt_table"
stats.statistics_columns = ["标贯击数"]

# reader.InputToken = (token, proj_id, host)
# reader.table_fields = ["标贯试验数据表", "地层数据表"]
# links = reader.OutputTables >> stats.InputTables
# pipe.add_links(links)
# pipe.run()
# result = stats.OutputStatisticsResultTable.data

更多信息

API 参考 - modules 包
完整类定义与参数说明（statistics）
新近堆积黄土判别等下游模块对 统计结果表 的形态要求，见 modules.geoSurvey 模块帮助中 RecentlyDepositedLoess 一节。