modules.statistics 模块帮助

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

对 TableData 做与 pandas describe 等价的汇总统计，并可选抽取部分指标到 ResultModel；
对指定列（或列组合）做 value_counts，输出频次或占比表；
对方向向量或高维特征做**球面 K 均值（Spherical K-Means）**聚类，按余弦相似度划分簇。

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()
desc.InputTable = my_table
desc.execute()
stat_table = desc.OutputStatTable.data
# 如需 pandas DataFrame：stat_table.dataframe

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

from gdisdk.modules import TableDescribe

desc = TableDescribe(
    include="all",
    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(
    describe_columns=["depth", "qc"],
    include=None,  # 仍仅对其中数值列做描述
)
desc.InputTable = my_table
desc.execute()

参数说明

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()
# 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(
    subset="岩土名称",  # 或内部列名
    normalize=False,
    sort=True,
    ascending=False,
)
vc.InputTable = my_table
vc.execute()
out = vc.OutputCountTable.data

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

from gdisdk.modules import ValuesCount

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

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

from gdisdk.modules import ValuesCount

vc = ValuesCount(subset=None)
vc.InputTable = my_table
vc.execute()

参数说明

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()
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 避免重复计算。
feature_columns 支持**字段内部名**与**字段标题**（经 convert_to_field_names 解析）；为 None 时自动选用表中**全部数值列**。
参与拟合的行：在选定特征列上**任一为 NaN** 的行会被**排除**；OutputLabelsTable 仍保留原表所有行，这些行上的 cluster_label 为缺失。
centers_in_original_scale 控制**中心表**的含义：True``（默认）时每簇中心为簇内样本在**原始特征尺度**上的算术平均；``False 时输出算法在单位球上的归一化质心向量。
典型适用场景：
- 结构面、节理等用方向余弦或单位向量表示时的无监督分群；
- 高维嵌入向量按方向聚类；
- 需要在表格中得到 cluster_label 列及可解释的簇中心表供下游筛选或制图。

端口说明

输入端口 - InputTable：输入表（TableData）；未连接或为空时，两个输出均为 None。
输出端口 - OutputLabelsTable：在**原表所有列**基础上追加整型列 cluster_label``（0 起始簇编号）；未参与拟合的行该列为缺失。 - ``OutputCentersTable：每簇一行；首列为 cluster_id``（0 起始），其余列为与各特征列同名的中心坐标，含义由 ``centers_in_original_scale 决定。

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

from gdisdk.modules import SphericalKMeans

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

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

from gdisdk.modules import SphericalKMeans

skm = SphericalKMeans(n_clusters=5)
skm.InputTable = my_table
skm.execute()

参数说明

SphericalKMeans 参数一览
参数名	类型	默认值	说明
`feature_columns`	`list[str] \| None`	`None`	用作特征的列名或标题列表；`None` 表示使用全部数值列。若无任何数值列，执行时会 `ValueError`。
`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 归一化到单位范数。
`centers_in_original_scale`	`bool`	`True`	`True`：`OutputCentersTable` 中各特征列为簇内样本的算术平均（与输入同量纲）；`False`：列为单位球上的归一化质心。

行为说明

标签表中的 cluster_label 与中心表中的 cluster_id 使用**同一套** 0 起始簇编号：凡 cluster_label == k 的样本，其簇中心为 cluster_id == k 的那一行（中心表按 cluster_id 为 0 … n_clusters-1 排列）。
聚类仅在 dropna 后的有效子集上拟合；标签列对无效行留空，不改变原表行数。
空簇时，在 centers_in_original_scale=True 下对应中心行的各特征列为 NaN。
execute 的返回值为 OutputLabelsTable 对应的 ``TableData``（与端口数据一致）。

在 pipeline 中的使用方式

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

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

skm = SphericalKMeans()
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

更多信息