Communitygithub.com

CartoDB/agent-skills

指导用户构建复合评分工作流,适用于处理复合得分、指数、多变量评分、区域排名、站点评分、市场潜力、韧性指数、风险指数、加权得分、主成分分析(PCA)以及有监督/无监督评分等场景。

agent-skills 是什么?

该技能专门用于指导用户在 CARTO 工作流中创建复合评分、指数或多变量排名。它首先通过一个决策树帮助用户确定评分方法:有目标变量时使用有监督方法(`native.spatialcompositesupervised`),无目标但有专家权重知识时选择无监督的自定义权重或加权求和,无目标且无权重时则使用熵或第一主成分的无监督方法。随后,技能分步骤详细说明了有监督和无监督两种管线的构建过程,包括数据加载、特征选择、参数配置等关键环节。技能还特别强调了一些常见陷阱,例如:在 Snowflake 上注意列名大写、确保所有输入变量为数值型且方向一致、有监督评分本质是残差而非原始值、以及权重参数的实际格式为三元组 JSON 字符串。该技能支持通过 MCP 服务器的工作流工具或 `carto workflows` CLI 两种访问路径。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CartoDB/agent-skills/tree/HEAD/skills/carto-composite-scoring

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

当用户希望创建复合评分、指数或多变量排名时,请使用此技能。

前置条件:加载 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 + 使用 native.selectexpression 将加权和在 SQL 中直接写出(a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3)。输入和权重可在工作流内联检查;每个归一化列被物化;无需 Analytics Toolbox 依赖。当利益相关者需要查看/审计公式时,或你未运行 AT 时使用。
    • 2b. 希望 AT 为你处理管道(缩放、聚合、分桶) → 使用 scoring_method: CUSTOM_WEIGHTS 的 native.spatialcompositeunsupervised。一个节点,但公式隐藏在组件内部。
  3. “无目标,无权重?”
    • → 使用 ENTROPY 或 FIRST_PC 的无监督方法,使用 native.spatialcompositeunsupervised

成功:在设计管道之前,你已经确定了要使用的组件和评分方法。

步骤 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 则必填。传输格式是一个 JSON 编码的三元组字符串 [[<column>, <weight>, <reverse>], ...]——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 等。参见 carto-create-workflow/references/providers/<provider>.md 了解大小写规则和 SQL 方言等价形式。
  • 所有输入变量必须是数值型,且方向一致。 首先通过 CASE WHEN 对有序字符串(“low”/“medium”/“high”)进行编码,对于“越高越差”的变量乘以 -1(或设置 reverse 标志),否则会反转得分含义。
  • 有监督 R 平方阈值(默认 0.4)较为宽松。如果模型拟合不佳,基于残差的得分主要是噪声。检查模型诊断信息。
  • 自定义权重在内部进行归一化,总和为 1。绝对值无关紧要,只有比率重要。
  • 有监督得分是残差,而不是原始值。该得分识别的是偏离模型的区域,而不是原始值最高的区域。
  • 从特征选择中删除空间索引列和几何列——只向评分组件传递实际的特征变量。
  • weights 的类型标签报告有误。 组件模式(通过 read_workflow_components MCP 或 carto workflows components get native.spatialcompositeunsupervised --json)将 weights 列为 type: "ColumnNumber",但实际的传输形状是一个三元组的 JSON 编码字符串 [[<column>, <weight>, <reverse>], ...](见上文步骤 2)。请相信此技能和参考模板,而不是报告的类型标签。
  • indexcol.allowedColumns 是一个 UI 提示,并非验证器。 模式为 native.spatialcompositeunsupervised.indexcol 列出了 ["geoid", "h3", "quadbin"],但它是工作流的下拉提示——运行时任何唯一标识列都可以(例如 store_id、cell_id)。

参考模板

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

模板组件文件
有监督——识别韧性社区native.spatialcompositesupervisedcomposite-score-supervised.json
无监督——市场潜力评分native.spatialcompositeunsupervisedcomposite-score-unsupervised.json

常见变体

变体方法
风险指数(洪水、犯罪等)使用 CUSTOM_WEIGHTS 的无监督方法;反转那些“越高越安全”的变量
市场潜力 / 站点评分使用 CUSTOM_WEIGHTS 或 ENTROPY 的无监督方法;对需求侧变量赋予更高权重
韧性指数使用结果变量(例如收入变化)的有监督方法;残差揭示表现过度/不足的区域
数据驱动指数(无领域专业知识)使用 FIRST_PC 或 ENTROPY 的无监督方法,让方差驱动权重
人类发展 / 综合指标使用 CUSTOM_WEIGHTS 和 RANKING 缩放的无监督方法,实现有序安全的聚合

Individual skills in this repo

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

相关技能