carto-hotspot-analysis

Getis-Ord Gi* によるホットスポット分析

Getis-Ord Gi* 統計量を使用して、統計的に有意な空間クラスター（ホットスポットとコールドスポット）を特定する CARTO Workflows を構築します。

前提条件：開発プロセス、JSON 構造、検証コマンドについては、carto-create-workflow を読み込んでください。この資料では、両方のアクセス方法（接続時は create_workflow、validate_workflow、run_workflow などの MCP サーバーのワークフローツール、その他の場合は 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 を使用して、分析前にデータセットを絞り込みます（例：カテゴリ、日付範囲、NULL 以外の値によるフィルタリング）。

成功条件：出力に分析対象のサブセットのみが含まれます。

ステップ 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	辺の長さ約 500 m	街路レベル

成功条件：調査対象地域をカバーする連続したグリッドができ、すべてのセルに空間インデックス列（例：h3）が割り当てられます。

ステップ 4：セルごとに集計する

native.groupby を使用して、セルごとに 1 行となる数値を生成します。

• グループ化：空間インデックス列（h3）
• 集計：h3,count（または value_col,sum ／ value_col,avg）

ポリフィルを使用する場合、データのないセルの値は 0 にしてください（結合後に native.selectexpression を使用して COALESCE(count, 0) を指定します）。

成功条件：出力には一意のセルごとにちょうど 1 行があり、カウント／合計列が含まれます。隙間はありません。

ステップ 5：Getis-Ord Gi* を実行する

次の項目を指定して native.getisord を使用します。

入力	説明	デフォルト
indexcol	H3／Quadbin インデックスを含む列	h3
valuecol	分析する数値列	h3_count
kernel	近傍の重み付け関数	uniform
size	K-ring サイズ（ホップ数で示す近傍半径）	3

カーネルの選択肢：uniform、triangular、quadratic、quartic、gaussian。距離に応じて重みを減衰させる理由がない限り、デフォルトの uniform（すべての近傍に同じ重みを付与）を使用します。

K-ring サイズ：大きいほどパターンが滑らかになり、より広範囲を示します。小さいほどクラスターが局所的になります。

成功条件：出力には、すべてのセルについて index、gi（z スコア）、p_value 列が含まれます。（これらの列が UPPERCASE で表示される Snowflake については、「注意事項」の Provider の大文字／小文字表記に関する注記を参照してください。）

ステップ 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> で確認してください。
• 出力列の名前は h3 や quadbin ではなく index です。元データと結合する必要がある場合は、名前を変更してください（例：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 時空間分析の出力の後に追加します。
• 各セルの時間的傾向を分類します：新規ホットスポット、連続的、激化、減衰、散発的、振動、過去のホットスポット。
• 有意水準（デフォルトは 0.05）を用いた Modified Mann-Kendall 傾向検定を使用します。
• パイプライン：... -> Getis-Ord 時空間分析 -> 時空間ホットスポット分類。

時系列クラスタリング（native.timeseriesclustering）：

• 時間的な Gi* パターンの類似性に基づいて、場所をグループ化します。
• 接続順序：Getis-Ord 時空間分析 -> 有意なセルをフィルタリング -> 時系列をクラスタリング。
• 手法：profile（形状ベース）または value（大きさベース）。
• テンプレートのフィルタリングの目安：時間ステップの 60% 以上で p_value < 0.05 となるセルを保持します。

---

参照テンプレート

これらのファイルは動作する例です（このスキルのフォルダー内にあるスキル固有のファイルです）。

ファイル	説明
poi_hotspot.json	ストックホルムのアメニティ POI — H3 解像度 9、uniform カーネル、k=3
space_time_hotspot.json	バルセロナの事故 — 時空間 Gi*、H3 解像度 9、週単位のビン
spacetime_hotspot_classification.json	ロンドンの衝突事故 — 時空間 Gi* + 分類、gaussian カーネル

---

よくあるバリエーション

バリエーション	方法
ポイントの代わりにポリゴンを入力	native.h3frompoint の代わりに native.h3polyfill を使用します
既存のグリッドを拡張	native.h3enrich を使用してポイントをグリッドにカウントし、手動での group-by + join を避けます
他のデータと組み合わせる	保存する前に、Getis-Ord の出力をエンリッチメントまたは属性テーブルと結合します
時空間／傾向の分類	上記の「時空間のバリエーション」セクションを参照してください