Use esta skill sempre que o usuário quiser criar um score composto, índice ou classificação multivariável em um Workflow do CARTO.
Pré-requisitos: Carregue carto-create-workflow para o processo de desenvolvimento. Ela cobre ambos os caminhos de acesso — as ferramentas de workflow do servidor MCP (create_workflow, validate_workflow, run_workflow) quando anexado, ou a CLI carto workflows caso contrário. Sinais de roteamento: carto-basics/references/access-paths.md.
Instruções
Etapa 1: Determinar a abordagem de pontuação
Pergunte ao usuário a seguinte árvore de decisão:
- "Você tem uma variável alvo/resultado?" (ex.: receita, vendas, taxa de criminalidade)
- Sim → Método Supervisionado usando
native.spatialcompositesupervised
- Sim → Método Supervisionado usando
- "Sem alvo, mas você tem conhecimento especializado sobre a importância das variáveis?" (ou seja, pesos personalizados)
- 2a. Transparência é mais importante que a contagem de nós →
native.normalizepor variável +native.selectexpressioncom a soma ponderada literalmente em SQL (a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3). As entradas e os pesos são inspecionáveis inline nos Workflows; cada coluna normalizada é materializada; sem dependência do Analytics Toolbox. Use quando as partes interessadas precisam ver/auditar a fórmula, ou quando você não está executando no AT. - 2b. Quer o pipeline do AT (escalonamento, agregação, agrupamento) tratado para você →
native.spatialcompositeunsupervisedcomscoring_method: CUSTOM_WEIGHTS. Um nó, mas a fórmula fica oculta dentro do componente.
- 2a. Transparência é mais importante que a contagem de nós →
- "Sem alvo, sem pesos?"
- → Método Não supervisionado com
ENTROPYouFIRST_PCusandonative.spatialcompositeunsupervised
- → Método Não supervisionado com
Sucesso: Você identificou qual componente e método de pontuação usar antes de projetar o pipeline.
Etapa 2: Construir o pipeline
Pipeline supervisionado (native.spatialcompositesupervised)
- Carregue o conjunto de dados de features espaciais (pré-indexado em H3 ou Quadbin)
- Carregue o conjunto de dados alvo/resultado
- Junte ambos os conjuntos na coluna do índice espacial
- Selecione apenas as colunas de features relevantes (descarte a coluna do índice espacial e a geometria da seleção de features — passe apenas as variáveis de features reais)
- Execute
native.spatialcompositesupervisedcom parâmetros:model_type:LINEAR_REGbucketize:EQUAL_INTERVALS_ZERO_CENTEREDn_buckets:5outlier_removal:truer_squared_threshold:0.4
- Saída: score composto baseado nos resíduos da regressão (identifica áreas que têm desempenho superior/inferior em relação ao modelo)
Sucesso: O workflow junta as features com a variável alvo, seleciona apenas colunas de features numéricas e produz um score baseado em resíduos por célula espacial.
Pipeline não supervisionado (native.spatialcompositeunsupervised)
- Carregue o conjunto de dados de features espaciais
- Selecione apenas as colunas de features relevantes
- Codifique quaisquer variáveis categóricas/ordinais para numérico usando
native.casewhen(ex.: "Low_density_urban" → 4, "High_density_urban" → 2) - Opcionalmente, inverta variáveis onde maior = pior multiplicando por -1 na consulta SELECT passada ao componente
- Execute
native.spatialcompositeunsupervisedcom parâmetros:scoring_method:CUSTOM_WEIGHTS/ENTROPY/FIRST_PCweights: obrigatório seCUSTOM_WEIGHTS. O formato é uma string JSON de triplas[[<coluna>, <peso>, <inverter>], ...]—colunaé o nome da coluna de feature,pesoé um peso numérico (normalizado internamente para somar 1),inverteré um booleano (trueinverte a variável para que maior = pior se torne maior = melhor sem necessidade de CASE WHEN). Exemplo:'[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'. Não é um mapa de objetos.scaling:RANKINGaggregation:LINEARoutput:RETURN_RANGEcom intervalo[0, 1]
- Saída: índice composto por localização
Sucesso: Todas as variáveis de entrada são numéricas, as direções das variáveis estão alinhadas (maior = melhor para o score) e a saída é um score normalizado por célula espacial.
Armadilhas
- Maiúsculas/minúsculas do provedor e dialeto SQL. Esta skill usa nomes de colunas em minúsculas (convenção do BigQuery / Databricks / Postgres / Redshift). No Snowflake, identificadores não citados aparecem em MAIÚSCULAS — consulte
POPULATION_DENSITY,ACCIDENT_RATE, etc. em pesos, expressões e SQL downstream. Vejacarto-create-workflow/references/providers/<provider>.mdpara regras de maiúsculas/minúsculas e equivalentes de dialeto SQL. - Todas as variáveis de entrada devem ser numéricas, com direção alinhada. Codifique strings ordinais ("baixo"/"médio"/"alto") via CASE WHEN primeiro, e onde "maior é pior" multiplique por -1 (ou defina a flag
reverse) antes da pontuação — esquecer isso inverte o significado do score. - Limiar de R-quadrado supervisionado (padrão 0,4) é permissivo. Se o ajuste do modelo for ruim, o score baseado em resíduos será principalmente ruído. Inspecione os diagnósticos do modelo.
- Pesos personalizados são normalizados internamente para somar 1. Os valores absolutos não importam, apenas as proporções.
- Scores supervisionados são resíduos, não valores brutos. O score identifica áreas que SE DESVIAM do modelo, não áreas com os valores brutos mais altos.
- Descarte a coluna do índice espacial e a geometria da seleção de features — passe apenas variáveis de features reais para o componente de pontuação.
- O rótulo de tipo de
weightsé relatado incorretamente. O esquema do componente (viaread_workflow_componentsMCP oucarto workflows components get native.spatialcompositeunsupervised --json) listaweightscomotype: "ColumnNumber", mas a forma real é uma string JSON codificada de triplas[[<coluna>, <peso>, <inverter>], ...](veja Etapa 2 acima). Confie nesta skill e nos templates de referência em vez do rótulo de tipo relatado. indexcol.allowedColumnsé uma dica de UI, não um validador. O esquema lista["geoid", "h3", "quadbin"]paranative.spatialcompositeunsupervised.indexcol, mas é uma dica de dropdown do Workflows — qualquer coluna de identificador único funciona em tempo de execução (ex.:store_id,cell_id).
Templates de Referência
Ambos os exemplos usam dados de features espaciais de Milão na resolução Quadbin 18.
| Template | Componente | Arquivo |
|---|---|---|
| Supervisionado — Identificando bairros resilientes | native.spatialcompositesupervised | composite-score-supervised.json |
| Não supervisionado — Scoring de potencial de mercado | native.spatialcompositeunsupervised | composite-score-unsupervised.json |
Variações Comuns
| Variação | Abordagem |
|---|---|
| Índice de risco (inundação, crime, etc.) | Não supervisionado com CUSTOM_WEIGHTS; inverta variáveis onde maior = mais seguro |
| Potencial de mercado / scoring de locais | Não supervisionado com CUSTOM_WEIGHTS ou ENTROPY; pondere variáveis do lado da demanda mais alto |
| Índice de resiliência | Supervisionado com variável de resultado (ex.: mudança na receita); resíduos revelam desempenho superior/inferior |
| Índice orientado por dados (sem conhecimento de domínio) | Não supervisionado com FIRST_PC ou ENTROPY para deixar a variância guiar os pesos |
| Desenvolvimento humano / indicador composto | Não supervisionado com CUSTOM_WEIGHTS e escalonamento RANKING para agregação segura para ordinais |