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 :
- « Avez-vous une variable cible/résultat ? » (ex. revenu, ventes, taux de criminalité)
- Oui → Méthode supervisée utilisant
native.spatialcompositesupervised
- Oui → Méthode supervisée utilisant
- « 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.normalizepar variable +native.selectexpressionavec 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.spatialcompositeunsupervisedavecscoring_method: CUSTOM_WEIGHTS. Un seul nœud, mais la formule est cachée à l'intérieur du composant.
- 2a. La transparence importe plus que le nombre de nœuds →
- « Pas de cible, pas de poids ? »
- → Méthode non supervisée avec
ENTROPYouFIRST_PCen utilisantnative.spatialcompositeunsupervised
- → Méthode non supervisée avec
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)
- Chargez le jeu de données de caractéristiques spatiales (pré-indexé en H3 ou Quadbin)
- Chargez le jeu de données cible/résultat
- Joignez les deux jeux de données sur la colonne d'index spatial
- 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)
- Exécutez
native.spatialcompositesupervisedavec les paramètres :model_type:LINEAR_REGbucketize:EQUAL_INTERVALS_ZERO_CENTEREDn_buckets:5outlier_removal:truer_squared_threshold:0.4
- 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)
- Chargez le jeu de données de caractéristiques spatiales
- Sélectionnez uniquement les colonnes de caractéristiques pertinentes
- Encodez les variables catégorielles/ordinales en numériques à l'aide de
native.casewhen(ex. "Low_density_urban" → 4, "High_density_urban" → 2) - Optionnellement, inversez les variables où plus élevé = pire en multipliant par -1 dans la requête SELECT transmise au composant
- Exécutez
native.spatialcompositeunsupervisedavec les paramètres :scoring_method:CUSTOM_WEIGHTS/ENTROPY/FIRST_PCweights: requis siCUSTOM_WEIGHTS. Le format filaire est une chaîne JSON encodée de triplets[[<colonne>, <poids>, <inverser>], ...]—columnest le nom de la colonne de caractéristiques,weightest un poids numérique (normalisé en interne pour totaliser 1),reverseest un booléen (trueinverse 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:RANKINGaggregation:LINEARoutput:RETURN_RANGEavec la plage[0, 1]
- 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. Voircarto-create-workflow/references/providers/<provider>.mdpour 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
weightsest mal rapporté. Le schéma du composant (viaread_workflow_componentsMCP oucarto workflows components get native.spatialcompositeunsupervised --json) listeweightscommetype: "ColumnNumber", mais la forme filaire réelle est une chaîne encodée JSON deColumnAndNumberde 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.allowedColumnsest une indication d'interface utilisateur, pas un validateur. Le schéma liste["geoid", "h3", "quadbin"]pournative.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èle | Composant | Fichier |
|---|---|---|
| Supervisé — Identification de quartiers résilients | native.spatialcompositesupervised | composite-score-supervised.json |
| Non supervisé — Notation du potentiel de marché | native.spatialcompositeunsupervised | composite-score-unsupervised.json |
Variations courantes
| Variation | Approche |
|---|---|
| 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 site | Non supervisé avec CUSTOM_WEIGHTS ou ENTROPY ; pondérer davantage les variables côté demande |
| Indice de résilience | Supervisé 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 composite | Non supervisé avec CUSTOM_WEIGHTS et mise à l'échelle RANKING pour une agrégation ordinale sûre |