carto-composite-scoring

当用户想在 CARTO Workflow 中创建综合得分、指数或多变量排名时，使用此技能。

前置条件：加载 carto-create-workflow 以了解开发流程。它涵盖两种访问方式——连接 MCP 服务时使用 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 管道处理缩放、聚合和分桶 → 使用 native.spatialcompositeunsupervised，并设置 scoring_method: CUSTOM_WEIGHTS。只需一个节点，但公式隐藏在组件内部。
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 将分类／有序变量编码为数值（例如，“Low_density_urban” → 4，“High_density_urban” → 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：RETURN_RANGE，范围为 [0, 1]
6. 输出：每个位置的综合指数得分

成功标准：所有输入变量均为数值型，变量方向一致（得分越高越好），并为每个空间单元生成归一化得分。

注意事项

• 提供商的大小写规则和 SQL 方言。 此技能使用小写列名（BigQuery / Databricks / Postgres / Redshift 惯例）。在 Snowflake 上，未加引号的标识符会显示为大写——在权重、表达式和下游 SQL 中引用 POPULATION_DENSITY、ACCIDENT_RATE 等。有关大小写规则和 SQL 方言对应项，请参阅 carto-create-workflow/references/providers/<provider>.md。
• 所有输入变量都必须是数值，且方向一致。 先用 CASE WHEN 将有序字符串（“low”/“medium”/“high”）编码；对于“越高越差”的变量，在评分前乘以 -1（或设置 reverse 标志）——忘记这一步会颠倒分数的含义。
• 监督式 R-squared 阈值（默认值为 0.4）较为宽松。如果模型拟合效果较差，基于残差的分数大多只是噪声。请检查模型诊断信息。
• 自定义权重会在内部归一化，使其总和为 1。绝对值并不重要，只有比例重要。
• 监督式分数是残差，不是原始值。分数标识的是偏离模型的区域，而不是原始值最高的区域。
• 从特征选择中排除空间索引列和几何数据——只向评分组件传入实际特征变量。
• weights 类型标签报告有误。 组件架构（通过 read_workflow_components MCP 或 carto workflows components get native.spatialcompositeunsupervised --json 获取）将 weights 列为 type: "ColumnNumber"，但实际传输格式是 JSON 编码的 ColumnAndNumber 字符串，包含三元组 [[<column>, <weight>, <reverse>], ...]（见上文步骤 2）。请以此技能和参考模板为准，不要依赖报告的类型标签。
• indexcol.allowedColumns 是 UI 提示，而非验证器。 架构为 native.spatialcompositeunsupervised.indexcol 列出了 ["geoid", "h3", "quadbin"]，但这只是 Workflows 下拉菜单的提示——运行时可使用任何唯一标识列（例如 store_id、cell_id）。

参考模板

两个示例都使用 Quadbin 分辨率为 18 的米兰空间特征数据。

模板	组件	文件
监督式 — 识别具有韧性的社区	native.spatialcompositesupervised	composite-score-supervised.json
非监督式 — 市场潜力评分	native.spatialcompositeunsupervised	composite-score-unsupervised.json

常见变体

变体	方法
风险指数（洪水、犯罪等）	使用 CUSTOM_WEIGHTS 的非监督式方法；对于数值越高越安全的变量进行反向处理
市场潜力 / 选址评分	使用 CUSTOM_WEIGHTS 或 ENTROPY 的非监督式方法；提高需求侧变量的权重
韧性指数	使用结果变量（例如收入变化）的监督式方法；残差可揭示表现超出或低于预期的对象
数据驱动指数（无领域专业知识）	使用 FIRST_PC 或 ENTROPY 的非监督式方法，让方差决定权重
人类发展 / 综合指标	使用 CUSTOM_WEIGHTS 和 RANKING 缩放的非监督式方法，以便安全地聚合有序变量