Communitygithub.com

CartoDB/agent-skills

Guide l'utilisateur dans la création de workflows de scores composites lorsqu'il pose des questions sur les scores composites, les indices, les scores multivariables, le classement de zones, la notation de sites, le potentiel de marché, les indices de résilience, les indices de risque, les scores pondérés, l'ACP ou la notation supervisée/non supervisée.

Qu'est-ce que agent-skills ?

Cette compétence est spécialisée dans la création de scores composites, d'indices ou de classements multivariables dans CARTO Workflows. Elle est utile pour tout développeur ou analyste souhaitant transformer des données spatiales multivariées en une métrique unique et interprétable, que ce soit pour évaluer le potentiel de marché, la résilience, le risque ou tout autre indicateur composite. La compétence prend en charge à la fois les approches supervisées (via `native.spatialcompositesupervised`) lorsqu'une variable cible est disponible, et non supervisées (via `native.spatialcompositeunsupervised`), avec ou sans pondérations personnalisées. Elle fonctionne sur toutes les plateformes supportées par CARTO (BigQuery, Snowflake, Databricks, Postgres, Redshift) et fournit des instructions détaillées, des pièges à éviter (comme la casse des colonnes sur Snowflake ou la nécessité d'encodage des variables ordinales) ainsi que des modèles de référence téléchargeables. En suivant un arbre de décision clair, elle guide l'utilisateur vers le composant et la méthode de notation les plus adaptés à son cas.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Utilisez cette compétence chaque fois que l'utilisateur souhaite créer un score composite, un indice ou un classement multivariable dans un Workflow CARTO.

Prérequis : Chargez carto-create-workflow pour le processus de développement. Il couvre les deux chemins d'accès — les outils de workflow du serveur MCP (create_workflow, validate_workflow, run_workflow) lorsqu'il est attaché, la CLI carto workflows sinon. Signaux de routage : carto-basics/references/access-paths.md.

Instructions

Étape 1 : Déterminer l'approche de notation

Posez à l'utilisateur l'arbre de décision suivant :

  1. « Avez-vous une variable cible/résultat ? » (ex. revenu, ventes, taux de criminalité)
    • Oui → Méthode supervisée utilisant native.spatialcompositesupervised
  2. « Pas de cible, mais avez-vous une connaissance experte de l'importance des variables ? » (c'est-à-dire des poids personnalisés)
    • 2a. La transparence importe plus que le nombre de nœuds → native.normalize par variable + native.selectexpression avec la somme pondérée écrite littéralement en SQL (a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3). Les entrées et les poids sont inspectables en ligne dans les Workflows ; chaque colonne normalisée est matérialisée ; pas de dépendance à Analytics Toolbox. À utiliser lorsque les parties prenantes ont besoin de voir/vérifier la formule, ou lorsque vous n'utilisez pas AT.
    • 2b. Vous voulez que le pipeline AT (mise à l'échelle, agrégation, regroupement) soit géré pour vous → native.spatialcompositeunsupervised avec scoring_method: CUSTOM_WEIGHTS. Un seul nœud, mais la formule est cachée à l'intérieur du composant.
  3. « Pas de cible, pas de poids ? »
    • → Méthode non supervisée avec ENTROPY ou FIRST_PC en utilisant native.spatialcompositeunsupervised

Succès : Vous avez identifié le composant et la méthode de notation à utiliser avant de concevoir le pipeline.

Étape 2 : Construire le pipeline

Pipeline supervisé (native.spatialcompositesupervised)

  1. Chargez le jeu de données de caractéristiques spatiales (pré-indexé en H3 ou Quadbin)
  2. Chargez le jeu de données cible/résultat
  3. Joignez les deux jeux de données sur la colonne d'index spatial
  4. Sélectionnez uniquement les colonnes de caractéristiques pertinentes (supprimez la colonne d'index spatial et la géométrie de la sélection des caractéristiques — ne transmettez que les variables de caractéristiques réelles)
  5. Exécutez native.spatialcompositesupervised avec les paramètres :
    • model_type : LINEAR_REG
    • bucketize : EQUAL_INTERVALS_ZERO_CENTERED
    • n_buckets : 5
    • outlier_removal : true
    • r_squared_threshold : 0.4
  6. Résultat : score composite basé sur les résidus de régression (identifie les zones qui sur-performent ou sous-performent par rapport au modèle)

Succès : Le workflow joint les caractéristiques à la variable cible, sélectionne uniquement les colonnes de caractéristiques numériques et produit un score basé sur les résidus par cellule spatiale.

Pipeline non supervisé (native.spatialcompositeunsupervised)

  1. Chargez le jeu de données de caractéristiques spatiales
  2. Sélectionnez uniquement les colonnes de caractéristiques pertinentes
  3. Encodez les variables catégorielles/ordinales en numériques à l'aide de native.casewhen (ex. "Low_density_urban" → 4, "High_density_urban" → 2)
  4. Optionnellement, inversez les variables où plus élevé = pire en multipliant par -1 dans la requête SELECT transmise au composant
  5. Exécutez native.spatialcompositeunsupervised avec les paramètres :
    • scoring_method : CUSTOM_WEIGHTS / ENTROPY / FIRST_PC
    • weights : requis si CUSTOM_WEIGHTS. Le format filaire est une chaîne JSON encodée de triplets [[<colonne>, <poids>, <inverser>], ...] — column est le nom de la colonne de caractéristiques, weight est un poids numérique (normalisé en interne pour totaliser 1), reverse est un booléen (true inverse la variable pour que plus élevé = pire devienne plus élevé = meilleur sans avoir besoin de CASE WHEN). Exemple : '[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'. Pas un objet.
    • scaling : RANKING
    • aggregation : LINEAR
    • output : RETURN_RANGE avec la plage [0, 1]
  6. Résultat : score d'indice composite par emplacement

Succès : Toutes les variables d'entrée sont numériques, les directions des variables sont alignées (plus élevé = meilleur pour le score), et le résultat est un score normalisé par cellule spatiale.

Pièges

  • Casse du fournisseur et dialecte SQL. Cette compétence utilise des noms de colonnes en minuscules (convention BigQuery / Databricks / Postgres / Redshift). Sur Snowflake, les identifiants non guillemetés apparaissent en MAJUSCULES — référencez POPULATION_DENSITY, ACCIDENT_RATE, etc. dans les poids, les expressions et le SQL en aval. Voir carto-create-workflow/references/providers/<provider>.md pour les règles de casse et les équivalents de dialecte SQL.
  • Toutes les variables d'entrée doivent être numériques, avec une direction alignée. Encodez les chaînes ordinales ("faible"/"moyen"/"élevé") via CASE WHEN d'abord, et là où "plus élevé est pire" multipliez par -1 (ou définissez le drapeau reverse) avant la notation — oublier cela inverse la signification du score.
  • Seuil R-carré supervisé (par défaut 0,4) est permissif. Si l'ajustement du modèle est médiocre, le score basé sur les résidus est principalement du bruit. Inspectez les diagnostics du modèle.
  • Les poids personnalisés sont normalisés en interne pour totaliser 1. Les valeurs absolues n'ont pas d'importance, seuls les ratios comptent.
  • Les scores supervisés sont des résidus, pas des valeurs brutes. Le score identifie les zones qui S'ÉCARTENT du modèle, pas les zones avec les valeurs brutes les plus élevées.
  • Supprimez la colonne d'index spatial et la géométrie de la sélection des caractéristiques — ne transmettez que les variables de caractéristiques réelles au composant de notation.
  • Le label de type weights est mal rapporté. Le schéma du composant (via read_workflow_components MCP ou carto workflows components get native.spatialcompositeunsupervised --json) liste weights comme type: "ColumnNumber", mais la forme filaire réelle est une chaîne encodée JSON de ColumnAndNumber de triplets [[<colonne>, <poids>, <inverser>], ...] (voir Étape 2 ci-dessus). Faites confiance à cette compétence et aux modèles de référence plutôt qu'au label de type rapporté.
  • indexcol.allowedColumns est une indication d'interface utilisateur, pas un validateur. Le schéma liste ["geoid", "h3", "quadbin"] pour native.spatialcompositeunsupervised.indexcol, mais c'est une indication de liste déroulante des Workflows — toute colonne d'identifiant unique fonctionne à l'exécution (ex. store_id, cell_id).

Modèles de référence

Les deux exemples utilisent des données de caractéristiques spatiales de Milan à la résolution Quadbin 18.

ModèleComposantFichier
Supervisé — Identification de quartiers résilientsnative.spatialcompositesupervisedcomposite-score-supervised.json
Non supervisé — Notation du potentiel de marchénative.spatialcompositeunsupervisedcomposite-score-unsupervised.json

Variations courantes

VariationApproche
Indice de risque (inondation, criminalité, etc.)Non supervisé avec CUSTOM_WEIGHTS ; inverser les variables où plus élevé = plus sûr
Potentiel de marché / notation de siteNon supervisé avec CUSTOM_WEIGHTS ou ENTROPY ; pondérer davantage les variables côté demande
Indice de résilienceSupervisé avec variable de résultat (ex. variation des revenus) ; les résidus révèlent les sur/sous-performeurs
Indice piloté par les données (sans expertise du domaine)Non supervisé avec FIRST_PC ou ENTROPY pour laisser la variance déterminer les poids
Développement humain / indicateur compositeNon supervisé avec CUSTOM_WEIGHTS et mise à l'échelle RANKING pour une agrégation ordinale sûre

Individual skills in this repo

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

Skills associés