사용자가 CARTO 워크플로우에서 합성 점수(composite score), 지수(index), 또는 다중 변수 순위(multi-variable ranking)를 만들고자 할 때 이 스킬을 사용하세요.
사전 조건: 개발 과정에서 carto-create-workflow를 로드하세요. 이는 MCP 서버의 워크플로우 도구(create_workflow, validate_workflow, run_workflow)가 연결되어 있을 때와 그렇지 않을 때 carto workflows CLI의 두 가지 접근 경로를 모두 다룹니다. 라우팅 신호: carto-basics/references/access-paths.md.
지침
1단계: 점수 매기기 접근 방식 결정
사용자에게 다음과 같은 결정 트리를 질문하세요:
- "목표/결과 변수(target/outcome variable)가 있습니까?" (예: 수익, 매출, 범죄율)
- 예 → 지도(Supervised) 방법:
native.spatialcompositesupervised사용
- 예 → 지도(Supervised) 방법:
- "목표 변수는 없지만, 변수의 중요도에 대한 전문가 지식이 있습니까?" (즉, 사용자 정의 가중치)
- 2a. 투명성(Transparency)이 노드 수보다 중요함 → 변수별로
native.normalize를 수행하고, 가중 합을 SQL에 직접 작성한native.selectexpression사용 (예:a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3). 입력과 가중치는 Workflows에서 인라인으로 검사 가능하며, 각 정규화된 컬럼은 구체화(materialize)됩니다. Analytics Toolbox에 의존하지 않습니다. 이해관계자가 공식을 보고 감사(audit)해야 할 때, 또는 AT를 사용하지 않을 때 사용하세요. - 2b. AT 파이프라인(스케일링, 집계, 버킷팅)을 자동으로 처리하기를 원함 →
scoring_method: CUSTOM_WEIGHTS와 함께native.spatialcompositeunsupervised사용. 하나의 노드이지만 공식은 구성 요소 내부에 숨겨져 있습니다.
- 2a. 투명성(Transparency)이 노드 수보다 중요함 → 변수별로
- "목표 변수도, 가중치도 없습니까?"
- →
ENTROPY또는FIRST_PC와 함께 비지도(Unsupervised) 방법 사용:native.spatialcompositeunsupervised
- →
성공: 파이프라인을 설계하기 전에 어떤 구성 요소와 점수 매기기 방법을 사용할지 식별했습니다.
2단계: 파이프라인 구축
지도 파이프라인 (native.spatialcompositesupervised)
- 공간 특성 데이터셋 로드 (H3 또는 Quadbin에서 사전 색인화됨)
- 목표/결과 데이터셋 로드
- 공간 인덱스 컬럼을 기준으로 두 데이터셋 조인
- 관련 특성 컬럼만 선택 (공간 인덱스 컬럼과 지오메트리는 특성 선택에서 제외 — 실제 특성 변수만 전달)
- 매개변수와 함께
native.spatialcompositesupervised실행:model_type:LINEAR_REGbucketize:EQUAL_INTERVALS_ZERO_CENTEREDn_buckets:5outlier_removal:truer_squared_threshold:0.4
- 출력: 회귀 잔차 기반 합성 점수 (모델 대비 과대/과소 성능 지역 식별)
성공: 워크플로우가 특성과 목표 변수를 조인하고, 숫자 특성 컬럼만 선택하며, 공간 셀당 잔차 기반 점수를 생성합니다.
비지도 파이프라인 (native.spatialcompositeunsupervised)
- 공간 특성 데이터셋 로드
- 관련 특성 컬럼만 선택
native.casewhen을 사용하여 범주형/순서형 변수를 숫자로 인코딩 (예: "Low_density_urban" → 4, "High_density_urban" → 2)- 선택적으로 값이 클수록 나쁜 변수는 구성 요소에 전달되는 SELECT 쿼리에서 -1을 곱하여 방향을 반전시킴
- 매개변수와 함께
native.spatialcompositeunsupervised실행:scoring_method:CUSTOM_WEIGHTS/ENTROPY/FIRST_PCweights:CUSTOM_WEIGHTS인 경우 필수. 전선 형식은 삼중항(triples)의 JSON 인코딩 문자열[[<column>, <weight>, <reverse>], ...]—column은 특성 컬럼 이름,weight는 숫자 가중치(내부적으로 합이 1이 되도록 정규화됨),reverse는 부울 값(true는 CASE WHEN 없이 값이 클수록 나쁨을 값이 클수록 좋음으로 반전시킴). 예:'[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'. 객체 맵(object map)이 아닙니다.scaling:RANKINGaggregation:LINEARoutput:RETURN_RANGE, 범위[0, 1]
- 출력: 위치별 합성 지수 점수
성공: 모든 입력 변수가 숫자이고, 변수 방향이 정렬되었으며(값이 클수록 점수에 좋음), 출력은 공간 셀당 정규화된 점수입니다.
주의 사항 (Gotchas)
- 공급자(Provider) 대소문자 규칙 및 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-제곱 임계값(기본값 0.4)은 관대합니다. 모델 적합도가 낮으면 잔차 기반 점수는 대부분 잡음입니다. 모델 진단을 검사하세요.
- 사용자 정의 가중치는 내부적으로 합이 1이 되도록 정규화됩니다. 절대값은 중요하지 않으며, 비율만 중요합니다.
- 지도 학습 점수는 잔차(residuals)입니다. 원시 값이 아닙니다. 점수는 모델에서 벗어난(DEVIATE) 영역을 식별하며, 원시 값이 가장 높은 영역을 식별하지 않습니다.
- 특성 선택에서 공간 인덱스 컬럼과 지오메트리를 제거하세요 — 점수 매기기 구성 요소에 실제 특성 변수만 전달하세요.
weights유형 레이블이 잘못 보고됩니다. 구성 요소 스키마(read_workflow_componentsMCP 또는carto workflows components get native.spatialcompositeunsupervised --json통해)는weights를type: "ColumnNumber"로 나열하지만, 실제 전선 형태는 삼중항의ColumnAndNumberJSON 인코딩 문자열[[<column>, <weight>, <reverse>], ...]입니다(위 2단계 참조). 보고된 유형 레이블보다 이 스킬과 참조 템플릿을 신뢰하세요.indexcol.allowedColumns는 UI 힌트일 뿐, 유효성 검사기가 아닙니다. 스키마는native.spatialcompositeunsupervised.indexcol에 대해["geoid", "h3", "quadbin"]을 나열하지만, 이는 Workflows 드롭다운 힌트입니다 — 런타임에는 고유 식별자 컬럼(예:store_id,cell_id)이 작동합니다.
참조 템플릿 (Reference Templates)
두 예제 모두 Quadbin 해상도 18의 밀라노(Milan) 공간 특성 데이터를 사용합니다.
| 템플릿 | 구성 요소 | 파일 |
|---|---|---|
| 지도 학습 — 회복력 있는 지역 식별 | native.spatialcompositesupervised | composite-score-supervised.json |
| 비지도 학습 — 시장 잠재력 점수 매기기 | native.spatialcompositeunsupervised | composite-score-unsupervised.json |
일반적인 변형 (Common Variations)
| 변형 | 접근 방식 |
|---|---|
| 위험 지수 (홍수, 범죄 등) | CUSTOM_WEIGHTS와 함께 비지도 학습; 값이 클수록 안전한 변수는 방향 반전 |
| 시장 잠재력 / 부지 점수 매기기 | CUSTOM_WEIGHTS 또는 ENTROPY와 함께 비지도 학습; 수요 측 변수에 더 높은 가중치 부여 |
| 회복력 지수 | 결과 변수(예: 수익 변화)와 함께 지도 학습; 잔차가 과대/과소 성과 지역을 드러냄 |
| 데이터 기반 지수 (도메인 전문 지식 없음) | FIRST_PC 또는 ENTROPY와 함께 비지도 학습; 분산이 가중치를 결정하도록 함 |
| 인간 개발 / 합성 지표 | CUSTOM_WEIGHTS 및 RANKING 스케일링과 함께 비지도 학습; 순서형 안전 집계를 위해 사용 |