Communitygithub.com

CartoDB/agent-skills

複合スコア、インデックス、多変量ランキングに関するユーザーの質問に応じて、CARTO Workflowでの複合スコアワークフロー構築をガイドします。

agent-skills とは?

このスキルは、CARTOプラットフォーム上で複合スコア、インデックス、多変量ランキングを作成するためのワークフロー開発を支援します。ユーザーが「複合スコア」「インデックス」「多変量スコア」「ランキング」「加重スコア」「PCA」「教師あり/教師なしスコアリング」などのキーワードを含む質問をした際にアクティブになります。主にCARTOのWorkflow機能を活用し、MCPサーバー経由のツール(create_workflow, validate_workflow, run_workflow)またはcarto workflows CLIの2つのアクセスパスをサポートします。スキルはまず決定木に従ってスコアリング手法(教師あり/教師なし/重み付き)を特定し、その後パイプラインの設計・構築手順を詳細に説明します。教師あり手法(native.spatialcompositesupervised)は目的変数ありの場合に使われ、回帰残差に基づくスコアを出力します。教師なし手法(native.spatialcompositeunsupervised)は目的変数がない場合に使われ、エントロピー、第1主成分、またはカスタム重みによるスコアリングが可能です。このスキルは、変数の方向性の一致、NULL値の処理、重みのワイヤフォーマット(JSONエンコードされたトリプル文字列)といった重要な注意点もカバーしており、実際のワークフローテンプレートも提供します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CartoDB/agent-skills/tree/HEAD/skills/carto-composite-scoring

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ユーザーがCARTO Workflowで複合スコア、インデックス、または多変量ランキングを作成したい場合に、このスキルを使用してください。

前提条件: 開発プロセスには carto-create-workflow をロードしてください。これにより、MCPサーバーのワークフローツール(create_workflow、validate_workflow、run_workflow)が接続されている場合と、そうでない場合の carto workflows CLI の両方のアクセスパスをカバーします。ルーティングシグナル: carto-basics/references/access-paths.md

手順

ステップ 1: スコアリングアプローチの決定

以下の決定木に従ってユーザーに質問してください。

  1. 「目標/結果変数はありますか?」 (例: 収益、売上、犯罪率)
    • はい → native.spatialcompositesupervised を使用する教師あり手法
  2. 「目標はないが、変数の重要度に関する専門知識はありますか?」 (つまりカスタム重み)
    • 2a. 透明性がノード数より重要 → native.normalize を変数ごとに適用し、native.selectexpression で重み付き合計をSQLで直接記述(a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3)。入力と重みはWorkflows内でインラインで検査可能。各正規化列はマテリアライズされます。Analytics Toolboxの依存関係はありません。利害関係者が計算式を確認/監査する必要がある場合、またはAT上で実行していない場合に使用します。
    • 2b. ATパイプライン(スケーリング、集計、バケット化)を自動で処理したい → scoring_method: CUSTOM_WEIGHTS を指定した native.spatialcompositeunsupervised。1ノードで済みますが、計算式はコンポーネント内部に隠蔽されます。
  3. 「目標も重みもない」
    • → ENTROPY または FIRST_PC を使用した教師なし手法(native.spatialcompositeunsupervised)

成功条件: パイプラインを設計する前に、使用するコンポーネントとスコアリング手法を特定できました。

ステップ 2: パイプラインの構築

教師ありパイプライン(native.spatialcompositesupervised)

  1. 空間フィーチャデータセットをロードする(H3またはQuadbinで事前インデックス済み)
  2. 目標/結果データセットをロードする
  3. 両方のデータセットを空間インデックス列で結合する
  4. 関連するフィーチャ列のみを選択する(フィーチャ選択から空間インデックス列とジオメトリを削除 — 実際のフィーチャ変数のみを渡す)
  5. 以下のパラメータで native.spatialcompositesupervised を実行する:
    • model_type: LINEAR_REG
    • bucketize: EQUAL_INTERVALS_ZERO_CENTERED
    • n_buckets: 5
    • outlier_removal: true
    • r_squared_threshold: 0.4
  6. 出力: 回帰残差に基づく複合スコア(モデルに対して過小/過大パフォーマンスの領域を特定)

成功条件: ワークフローがフィーチャと目標変数を結合し、数値フィーチャ列のみを選択し、空間セルごとに残差ベースのスコアを生成します。

教師なしパイプライン(native.spatialcompositeunsupervised)

  1. 空間フィーチャデータセットをロードする
  2. 関連するフィーチャ列のみを選択する
  3. カテゴリカル/順序変数を native.casewhen を使用して数値にエンコードする(例: "Low_density_urban" → 4、"High_density_urban" → 2)
  4. 必要に応じて、コンポーネントに渡すSELECTクエリ内で -1 を乗算して、値が大きいほど悪い変数を反転させる
  5. 以下のパラメータで native.spatialcompositeunsupervised を実行する:
    • scoring_method: CUSTOM_WEIGHTS / ENTROPY / FIRST_PC
    • weights: CUSTOM_WEIGHTS の場合は必須。ワイヤフォーマットはトリプルのJSONエンコード文字列 [[<column>, <weight>, <reverse>], ...] — column はフィーチャ列名、weight は数値の重み(内部で合計が1になるように正規化)、reverse はブール値(true にすると、CASE WHEN を使わずに「高いほど悪い」を「高いほど良い」に反転)。例: '[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'。オブジェクトマップではありません。
    • scaling: RANKING
    • aggregation: LINEAR
    • output: RETURN_RANGE(範囲 [0, 1])
  6. 出力: 位置ごとの複合インデックススコア

成功条件: すべての入力変数が数値で、変数の方向が揃っており(スコアに対して高いほど良い)、出力は空間セルごとに正規化されたスコアです。

注意点

  • プロバイダーの大文字小文字とSQL方言。 このスキルは小文字の列名を使用します(BigQuery / Databricks / Postgres / Redshift の慣例)。Snowflakeでは、引用符なしの識別子は大文字で表示されます — 重み、式、および後続のSQLでは POPULATION_DENSITY、ACCIDENT_RATE などを参照してください。大文字小文字のルールとSQL方言の同等物については、carto-create-workflow/references/providers/<provider>.md を参照してください。
  • すべての入力変数は数値で、方向が揃っている必要があります。 順序文字列("low"/"medium"/"high")は最初にCASE WHENでエンコードし、「高いほど悪い」場合は -1 を乗算(または reverse フラグを設定)してからスコアリングしてください — これを忘れるとスコアの意味が逆転します。
  • 教師ありR二乗閾値(デフォルト0.4)は許容範囲です。モデルの適合が悪い場合、残差ベースのスコアはほとんどノイズになります。モデルの診断結果を確認してください。
  • カスタム重みは内部で正規化され、合計が1になります。絶対値は重要ではなく、比率のみが重要です。
  • 教師ありスコアは残差であり、生の値ではありません。このスコアは、モデルから逸脱する領域を特定し、生の値が最も高い領域ではありません。
  • 空間インデックス列とジオメトリはフィーチャ選択から削除 — 実際のフィーチャ変数のみをスコアリングコンポーネントに渡します。
  • weights の型ラベルは誤って報告されています。 コンポーネントスキーマ(read_workflow_components MCP または carto workflows components get native.spatialcompositeunsupervised --json 経由)では weights の型が "ColumnNumber" としてリストされていますが、実際のワイヤ形状はトリプルの ColumnAndNumber JSONエンコード文字列 [[<column>, <weight>, <reverse>], ...] です(上記ステップ2参照)。報告された型ラベルよりも、このスキルとリファレンステンプレートを信頼してください。
  • indexcol.allowedColumns はUIヒントであり、バリデーターではありません。 スキーマでは native.spatialcompositeunsupervised.indexcol に対して ["geoid", "h3", "quadbin"] がリストされていますが、これはWorkflowsのドロップダウンヒントです。実行時には、任意の一意の識別子列(例: store_id、cell_id)が機能します。

リファレンステンプレート

どちらの例も、Quadbin解像度18のミラノ空間フィーチャデータを使用しています。

テンプレートコンポーネントファイル
教師あり — レジリエントな近隣地域の特定native.spatialcompositesupervisedcomposite-score-supervised.json
教師なし — 市場ポテンシャルスコアリングnative.spatialcompositeunsupervisedcomposite-score-unsupervised.json

一般的なバリエーション

バリエーションアプローチ
リスク指標(洪水、犯罪など)CUSTOM_WEIGHTS を使用した教師なし手法。「高いほど安全」な変数は反転させる。
市場ポテンシャル/サイトスコアリングCUSTOM_WEIGHTS または ENTROPY を使用した教師なし手法。需要側の変数の重みを高く設定する。
レジリエンス指標結果変数(例: 収益変化)を用いた教師あり手法。残差により過小/過大パフォーマンス領域が明らかになる。
データ駆動型指標(ドメイン知識なし)FIRST_PC または ENTROPY を使用した教師なし手法。分散が重みを決定する。
人間開発/複合指標CUSTOM_WEIGHTS と RANKING スケーリングを使用した教師なし手法。順序データに安全な集計を実現。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル