carto-hotspot-analysis

使用 Getis-Ord Gi* 进行热点分析

构建 CARTO 工作流，使用 Getis-Ord Gi* 统计量识别具有统计显著性的空间聚类（热点和冷点）。

前提条件：加载 carto-create-workflow，了解开发流程、JSON 结构和验证命令 — 它涵盖两种访问路径（已连接 MCP 服务时使用其工作流工具，例如 create_workflow、validate_workflow 和 run_workflow；否则使用 carto workflows CLI；路由信号见 carto-basics/references/access-paths.md）。

---

说明

热点工作流始终遵循以下流程：

Source Data → (Filter) → Spatial Indexing → Aggregation → Getis-Ord Gi* → (Filter Significant) → Save

步骤 1：加载源数据

使用 native.gettablebyname。输入表通常包含点几何。

成功标志：节点输出包含几何列（例如 geom）的表。

步骤 2：筛选（如有需要）

使用 native.wheresimplified 或 native.where，在分析前缩小数据集范围（例如按类别、日期范围或非空值筛选）。

成功标志：输出仅包含与分析相关的子集。

步骤 3：构建完整网格

首选方法：先使用 native.h3polyfill 对研究区域边界（例如区级多边形）进行多边形填充，创建完整且无间隙的网格。然后将待分析数据关联到此网格（例如通过 native.h3enrich 统计每个单元格中的点数，或手动连接后分组）。这样可确保研究区域内的每个单元格都有值（即使是 0），这是 Getis-Ord 所需的 — 网格中的间隙会扭曲邻域计算，并可能产生误导性结果。

更简单的替代方法（没有研究区域边界时）：直接使用 native.h3frompoint 或 native.quadbinfromgeopoint 将点几何转换为网格单元格。请注意，此方法只会生成存在数据的单元格，留下的间隙可能会影响统计量。

分辨率指南 — 分辨率越高 = 单元格越小 = 局部模式越明显：

分辨率	单元格大小	适用场景
H3 res 7	边长约 5 km	区/城市级模式
H3 res 8	边长约 2 km	邻里级模式
H3 res 9	边长约 500m	街道级模式

成功标志：一个覆盖研究区域的连续网格，且每个单元格都分配有空间索引列（例如 h3）。

步骤 4：按单元格聚合

使用 native.groupby，为每个单元格生成一行，并包含一个数值：

• 分组依据：空间索引列（h3）
• 聚合方式：h3,count（或 value_col,sum / value_col,avg）

如果采用多边形填充方法，没有数据的单元格应赋值为 0（连接后使用 native.selectexpression 执行 COALESCE(count, 0)）。

成功标志：输出中每个唯一单元格恰好有一行，并包含计数/总和列 — 没有间隙。

步骤 5：运行 Getis-Ord Gi*

使用 native.getisord，参数如下：

输入	说明	默认值
indexcol	包含 H3/Quadbin 索引的列	h3
valuecol	待分析的数值列	h3_count
kernel	邻居的加权函数	uniform
size	K 环大小（以跳数表示的邻域半径）	3

核函数选项：uniform、triangular、quadratic、quartic、gaussian。除非用户有理由按距离递减权重，否则默认使用 uniform（所有邻居权重相同）。

K 环大小：越大 = 模式越平滑、范围越广。越小 = 聚类越局部。

成功标志：输出中每个单元格都包含 index、gi（z 分数）和 p_value 列。（参见“注意事项”中的提供方大小写说明 — Snowflake 会将这些列显示为大写。）

步骤 6：筛选显著结果（可选）

使用 native.where，仅保留具有统计显著性的单元格：

• p_value < 0.05 — 置信度 95%
• p_value < 0.05 AND gi > 0 — 仅热点
• p_value < 0.05 AND gi < 0 — 仅冷点

成功标志：仅保留具有统计意义的聚类单元格。

步骤 7：保存

使用 native.saveastable 持久化结果。H3/Quadbin 列无需转换几何即可直接在 CARTO Builder 中可视化。

成功：已验证的工作流，可通过 create_workflow（MCP）或 carto workflows create（CLI）上传。

---

输出列

列	含义
index	空间索引网格 ID（H3 或 Quadbin）
gi	Gi* z 分数——正值 = 热点，负值 = 冷点
p_value	统计显著性——值越低，置信度越高

---

注意事项

• 提供程序的大小写与 SQL 方言。 此技能文档中的列名均为小写（BigQuery / Databricks / Postgres / Redshift 的惯例）。在 Snowflake 上，未加引号的标识符会显示为大写——在表达式中请引用 H3、INDEX、GI、P_VALUE、H3_COUNT。对于特定方言的 SQL 片段（例如下文的 DATETIME_TRUNC），请参阅 carto-create-workflow/references/providers/<provider>.md 中的对应表。
• Getis-Ord 组件需要 Analytics Toolbox。离线验证（通过 MCP 使用 validate_workflow，或使用 carto workflows validate）无法解析 AT 位置——运行前请使用仅限 CLI 的 carto workflows verify-remote --connection <conn> 确认。
• 输出列名为 index，而不是 h3 或 quadbin。如果需要与原始数据联接，请重命名该列（例如使用 native.renamecolumn）。
• 如果调用 native.h3boundary 来生成用于可视化的网格几何，新列名为 <h3col>_geo（例如 index_geo），而不是 geom。请在下游节点中使用相应列名。
• valuecol 必须是数值型。如果要对要素计数，分组步骤必须生成一个计数列——不要将原始索引列作为值传入。
• 分辨率过高且区域过大 = 网格数量极多，可能运行缓慢或超出内存限制。请从适中的分辨率开始，再逐步细化。
• 过滤步骤（步骤 6）结果为空，通常意味着 k 环大小太小，或数据过于稀疏，不足以形成显著聚类。请尝试增大 size 或降低分辨率。
• 时空 Getis-Ord 要求日期列为 DATETIME 类型。如果数据类型为 DATE 或 TIMESTAMP，请进行 CAST。
• 时间带宽的选择会显著影响结果。bandwidth=1 可检测快速变化；bandwidth=3+ 会平滑较长时间段内的趋势。
• 对于时间序列聚类，请预先筛选出显著网格（60% 启发式规则），以避免聚类噪声。
• 时空分类组件会在内部基于 Gi* 输出运行——分类前不要按 p_value 过滤，否则趋势检验将缺少部分数据。

---

时空变体

Getis-Ord 时空分析（native.getisordspacetime）：

• 将基本 Gi* 扩展为同时检测空间和时间上的聚类。
• 额外输入：kerneltime（uniform/gaussian）、bandwidth（时间步数）、timeinterval（week/month/day）。
• 数据必须预先汇总到时间分箱中（例如，每个 H3 单元格的每周计数）。
• 流程：点 -> H3 -> 创建时间列（BigQuery：DATETIME_TRUNC(CAST(datetime AS TIMESTAMP), WEEK)；Snowflake / Databricks / Postgres：DATE_TRUNC('WEEK', datetime)）-> GROUP BY (h3, time_bin) -> Getis-Ord 时空分析 -> 筛选 p_value < 0.05 AND gi > 0。

时空热点分类（native.spacetimehotspotsclassification）：

• 在 Getis-Ord 时空分析的输出之后串联。
• 对每个单元格的时间趋势进行分类：新热点、连续热点、增强热点、减弱热点、零星热点、波动热点、历史热点。
• 使用修正的 Mann-Kendall 趋势检验，并采用显著性阈值（默认值为 0.05）。
• 流程：... -> Getis-Ord 时空分析 -> 时空热点分类。

时间序列聚类（native.timeseriesclustering）：

• 按时间 Gi* 模式的相似性对位置分组。
• 链路：Getis-Ord 时空分析 -> 筛选显著单元格 -> 时间序列聚类。
• 方法：profile（基于形状）或 value（基于幅度）。
• 模板中的筛选启发式：保留时间步中 p_value < 0.05 的比例 >=60% 的单元格。

---

参考模板

这些文件是可运行的示例（位于此技能文件夹中，供本技能使用）：

文件	描述
poi_hotspot.json	斯德哥尔摩便利设施 POI — H3 分辨率 9、均匀核、k=3
space_time_hotspot.json	巴塞罗那事故 — 时空 Gi*、H3 分辨率 9、每周分箱
spacetime_hotspot_classification.json	伦敦碰撞事故 — 时空 Gi* + 分类、高斯核

---

常见变体

变体	方法
使用多边形输入而非点	使用 native.h3polyfill 代替 native.h3frompoint
丰富现有网格	使用 native.h3enrich 将点计数汇总到网格中（无需手动分组和联接）
与其他数据结合	保存之前，将 Getis-Ord 输出与丰富数据或属性表联接
时空 / 趋势分类	参见上方“时空变体”部分