/spatial-analysis

name: spatial-analysis
description: 'Guideline-driven spatial analysis skill. Given a research question and data context, provides decision frameworks for selecting appropriate spatial methods, diagnostics, and interpretation strategies. Adapts to available data, spatial units, and analytical objectives — Claude Code determines the optimal workflow. Use when user says "spatial analysis", "analyze spatial data", "run spatial regression", "check for clustering", "map this", or needs to go from a research question to a complete spatial analysis.'
argument-hint: [research-question-or-analysis-goal]
allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, Agent

Spatial Analysis: Guideline-Driven Decision Framework

Analyze: **$ARGUMENTS**

Purpose

This skill provides **guidelines, decision tables, and guardrails** for spatial analysis — not a fixed procedure. The sequence and combination of methods should be determined by Claude Code based on:

1. The research question and its analytical objective 2. The available data (type, size, quality, spatial unit) 3. The study context (domain, audience, publication target)

Read `skills/knowledge/spatial-methods.md` for reference implementations. This skill decides *when*, *why*, and *under what conditions* to use them.

Constants

• **OUTPUT_DIR = `output/spatial-analysis`** — Default destination for all analysis artifacts.
• **MAX_FEATURES = 15** — Soft cap on predictors before recommending dimensionality reduction.
• **MGWR_MAX_N = 3000** — Subsample threshold for MGWR.
• **GWR_MAX_N = 5000** — Subsample threshold for GWR.
• **SIGNIFICANCE_LEVEL = 0.05** — Default alpha unless user specifies otherwise.
• **SPATIAL_CV_FOLDS = 5** — Default spatial cross-validation folds.

> Override via argument, e.g., `/spatial-analysis "question" — significance: 0.01, max features: 8`.

---

1. Research Question Classification

Before selecting any method, classify the research question. This classification drives every downstream decision.

1.1 Analytical Objective Mapping

| Objective | Signal phrases | Typical method families | |---|---|---| | **Description** | "what is the spatial pattern of...", "how is X distributed" | Choropleth, KDE, summary statistics, ESDA | | **Explanation** | "what factors explain...", "why does X vary across..." | Regression ladder (OLS → spatial → local) | | **Comparison** | "does X differ between regions..." | Stratified analysis, interaction terms, regional subsetting | | **Prediction** | "can we predict...", "where will X occur..." | ML + spatial CV, feature engineering | | **Clustering / hot spots** | "are events clustered...", "where are hot spots..." | Moran's I, LISA, Getis-Ord Gi*, DBSCAN | | **Association** | "is X related to Y spatially..." | Bivariate Moran's I, spatial regression | | **Accessibility** | "who has access to...", "what areas are underserved..." | Network analysis, 2SFCA, isochrones | | **Temporal-spatial change** | "how has X changed over time across space..." | Panel methods, spatiotemporal aggregation | | **Causal inference** | "does X cause Y..." | Spatial DiD, IV, RDD — flag limitations explicitly | | **Interpolation** | "what is the value at unsampled locations..." | Kriging, IDW, cross-validation |

**If the question maps to multiple objectives**, identify the primary one and treat others as supporting. If the question is too vague, ask the user to clarify the outcome, spatial unit, and study area.

1.2 Should Spatial Methods Be Used at All?

Not every geographic dataset requires spatial statistics. Evaluate:

| Question | If "no" | If "yes" | |---|---|---| | Is spatial dependence theoretically plausible? | Standard methods may suffice | Spatial structure likely matters | | Is the spatial structure itself the research question? | Spatial methods are optional | Spatial methods are mandatory | | Would ignoring spatial structure bias results? | OLS may be adequate | Spatial adjustment needed |

**Guideline:** If all three are "no", recommend non-spatial analysis and explain why. Do not force spatial methods where they add no value.

1.3 Write Question Classification

Save classification to `output/spatial-analysis/question_classification.md`:

# Research Question Classification

**Question**: [user's question]
**Date**: [today]

## Analytical Objective
- Primary: [objective type]
- Supporting: [if any]

## Key Components
- Outcome variable: [or N/A]
- Explanatory variables: [list or TBD]
- Spatial unit: [point / polygon / raster / network]
- Temporal structure: [cross-sectional / panel / time series]
- Study extent: [description]
- Estimated N: [if known]

## Spatial Methods Needed?
- [Yes / No / Conditional on diagnostics]
- Reasoning: [why]

## Method Candidates
1. [method — why it fits this question]
2. [method — why it fits this question]
3. [method — conditional on X]

---

2. Data Readiness Guidelines

These guidelines apply regardless of analytical objective. Evaluate data readiness before proceeding to any analysis. The depth of preparation depends on the situation.

2.1 CRS Decision Framework

**This is non-negotiable.** Wrong CRS invalidates distance, area, and density calculations.

| If the analysis involves... | CRS requirement | Recommendation | |---|---|---| | Distance or density calculations | Projected (meters) | Local UTM or national grid | | Area calculations | Equal-area projection | Albers, Mollweide, or national equal-area | | Only display / web mapping | Any (geographic OK) | WGS84 (EPSG:4326) | | Spatial joins / overlays | Both layers must match | Reproject to analysis CRS first | | Mixed (distance + display) | Analyze in projected, display in geographic | Two CRS in workflow |

**Guardrail:** If data is in EPSG:4326 and the analysis involves distances, areas, or density — project first. Never compute Euclidean distance on lat/lon.

**UTM zone estimation** (when no local CRS is obvious):

centroid = gdf.geometry.unary_un