mcpField
C
carto-composite-scoring

carto-composite-scoring

github.com/cartodbデータ・データベース656 回インストール1 週間前に更新
リポジトリ

carto-composite-scoring について

CARTO Workflows で複合スコア、インデックス、ランキングを選定・作成するスキルです。目的変数や専門家の重みに基づく手法選択と、教師あり・教師なしの空間スコアリングを扱います。

主な機能

  1. 01教師あり・教師なしの手法選択
  2. 02回帰残差スコアの作成
  3. 03カスタムウェイトによる変数の統合
  4. 04エントロピーまたは第一主成分によるスコアリング
  5. 05入力変数の数値化と方向の調整

活用シーン

  1. 01リスクまたは市場ポテンシャル指数の作成
  2. 02専門家が定めた重みによる地点の順位付け
  3. 03モデル予測を上回る・下回る地域の特定

MCP 対応

このスキルは carto-create-workflow に依存します。MCP セッション接続時は MCP ツールで CARTO ワークフローを操作し、それ以外では CLI を使います。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cartodb/agent-skills --skill carto-composite-scoring

インストール後、Claude Code で/carto-composite-scoringを入力して読み込まれたか確認します。

同梱ファイルcomposite-score-supervised.jsoncomposite-score-unsupervised.json

詳細

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 を使用し、SQL に重み付き合計をそのまま記述した native.selectexpression を使用します（a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3）。入力と重みをワークフロー内で確認でき、正規化された各列が実体化されます。Analytics Toolbox への依存もありません。関係者が計算式を確認・監査する必要がある場合や、AT 上で実行しない場合に使用してください。
    • AT パイプライン（スケーリング、集計、ビン分け）の処理を任せたい → scoring_method: CUSTOM_WEIGHTS を指定して native.spatialcompositeunsupervised を使用します。ノードは 1 つですが、計算式はコンポーネント内に隠れます。
  3. 「ターゲットも重みもありませんか？」
    • → native.spatialcompositeunsupervised を使用する、ENTROPY または FIRST_PC による教師なし手法

成功条件：パイプラインを設計する前に、使用するコンポーネントとスコアリング方法が特定されていること。

ステップ 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 を使用して、カテゴリ変数／順序変数を数値に変換します（例：「低密度の都市部」→ 4、「高密度の都市部」→ 2）
  4. 必要に応じて、値が大きいほど悪い変数は、コンポーネントに渡す SELECT クエリ内で -1 を掛けて反転します
  5. 次のパラメーターを指定して native.spatialcompositeunsupervised を実行します。
    • scoring_method: CUSTOM_WEIGHTS / ENTROPY / FIRST_PC
    • weights: CUSTOM_WEIGHTS の場合は必須です。ワイヤ形式は、トリプル [[<column>, <weight>, <reverse>], ...] を JSON エンコードした文字列です。column はフィーチャー列名、weight は数値の重み（内部で合計が 1 になるように正規化されます）、reverse はブール値です（true にすると変数が反転され、CASE WHEN を使わずに、値が大きいほど悪い変数を値が大きいほど良い変数にできます）。例：'[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'。オブジェクトのマップではありません。
    • scaling: RANKING
    • aggregation: LINEAR
    • output: 範囲 [0, 1] を指定した RETURN_RANGE`
  6. 出力：位置ごとの複合インデックススコア

成功条件：すべての入力変数が数値で、変数の方向性が揃っており（スコアに対して値が大きいほど良い）、空間セルごとに正規化されたスコアが出力されていること。

注意点

  • プロバイダーの大文字・小文字と SQL 方言。 このスキルでは、小文字の列名を使用します（BigQuery／Databricks／Postgres／Redshift の規則）。Snowflake では、引用符で囲まれていない識別子は大文字で表示されるため、重み、式、後続の SQL では POPULATION_DENSITY、ACCIDENT_RATE などを参照してください。大文字・小文字の規則と SQL 方言の相当表現については、carto-create-workflow/references/providers/<provider>.md を参照してください。
  • すべての入力変数は数値で、方向をそろえる必要があります。 順序を表す文字列（「低」「中」「高」）は、まず CASE WHEN でエンコードします。また、「値が高いほど悪い」場合は、スコアリング前に -1 を掛ける（または reverse フラグを設定する）必要があります。これを忘れると、スコアの意味が逆転します。
  • 教師あり R-squared のしきい値（デフォルトは 0.4）は緩やかです。モデルの適合度が低い場合、残差に基づくスコアの大部分はノイズになります。モデルの診断結果を確認してください。
  • カスタム重みは内部で正規化され、合計が 1 になります。絶対値は関係なく、比率のみが重要です。
  • 教師ありスコアは生の値ではなく残差です。 スコアが示すのは、モデルから逸脱している地域であり、生の値が最も高い地域ではありません。
  • 特徴量の選択から空間インデックス列とジオメトリを除外してください。 スコアリングコンポーネントには、実際の特徴量変数のみを渡してください。
  • weights の型ラベルは誤って報告されています。 コンポーネントスキーマ（MCP の read_workflow_components または carto workflows components get native.spatialcompositeunsupervised --json 経由）では、weights は type: "ColumnNumber" と記載されています。しかし、実際のワイヤー形式は、3 要素の配列 [[<column>, <weight>, <reverse>], ...] を JSON エンコードした ColumnAndNumber 文字列です（上記のステップ 2 を参照）。報告された型ラベルではなく、このスキルと参照テンプレートを信頼してください。
  • indexcol.allowedColumns は UI のヒントであり、バリデーターではありません。 スキーマでは native.spatialcompositeunsupervised.indexcol に ["geoid", "h3", "quadbin"] が列挙されていますが、これは Workflows のドロップダウンのヒントです。実行時には、任意の一意識別子列（例：store_id、cell_id）を使用できます。

参照テンプレート

どちらの例も、Quadbin 解像度 18 の Milan 空間特徴量データを使用します。

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

一般的なバリエーション

バリエーションアプローチ
リスク指数（洪水、犯罪など）CUSTOM_WEIGHTS を使った教師なし方式。値が高いほど安全な変数は反転します
市場ポテンシャル／立地スコアリングCUSTOM_WEIGHTS または ENTROPY を使った教師なし方式。需要側の変数に高い重みを付けます
レジリエンス指数結果変数（例：収益の変化）を使った教師あり方式。残差から、平均を上回る／下回る対象が明らかになります
データ駆動型指数（ドメインの専門知識なし）FIRST_PC または ENTROPY を使った教師なし方式。分散に基づいて重みを決定します
人間開発／複合指標CUSTOM_WEIGHTS と RANKING スケーリングを使った教師なし方式。順序尺度を安全に集約できます

コメント

Markdown 対応