Run a spatial analysis on a layer
run_analysisCompute a spatial analysis server-side and append the finished, honestly-legended result as a new layer + camera; the result REPLACES its input layer(s) (undoable). hotspot = Getis-Ord Gi*: hot/cold significance classes (99/95/90%, Benjamini-Hochberg FDR-corrected) on a numeric field, or on hex-binned point density when valueField is omitted. zonal = aggregate points into polygon zones (an existing zone layer OR a generated h3 fishnet): count/sum/mean/min/max per zone as a quantile choropleth where zero and no-data are distinct classes. enrich = join a US Census ACS indicator (median income, home value, rent, …) onto each feature by tract/county/state containment — unmatched features stay null, never zero-filled. join = spatial join (attribute transfer): each point in layerId takes properties from the joinLayerId polygon containing it (collisions prefixed, unmatched points carry NO joined fields, zero overlap is a typed rejection). merge = append two same-geometry-class layers into one dataset with a per-row source column (schemas never null-filled; class mismatch is a typed failure). near = nearest-neighbor distance columns (great-circle meters, stated — never presented as road distance). dissolve = true polygon union per attribute group (missing values form their own group; partial sums reported). Returns a grounded memo + stats payload — every number is computed, never generated; findings keep the map. Costs 1 credit when the result lands; typed failures (unknown layer, too few features, >10,000-feature cap) are refunded.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | hotspot only: nearest neighbors per feature (default 8). | |
| stats | No | zonal only: which statistics to attach per zone (default: count, plus sum/mean/min/max when valueField is set). | |
| story | No | Opt-in: persist the shared map with a 2-step story rail (grounded overview + analysis memo isolating the result layer) — the /m/ link opens with it. | |
| zones | No | zonal only: generate an h3 hex fishnet over the source extent instead of using a zone layer (resolution 3-10, default auto). Provide EXACTLY ONE of zoneLayerId or zones. | |
| fields | No | join only: which join-layer properties to transfer (default: auto-select up to 12 non-internal properties, overflow reported). | |
| map_id | Yes | ||
| prefix | No | join only: prefix for a joined field whose name collides with an existing target property (default "join_"). | |
| layerId | Yes | The workspace layer to analyze (geojson-backed; the point source for zonal; the point TARGET for join; the styling donor for merge). | |
| analysis | Yes | Which analysis to run. 'hotspot' = Getis-Ord Gi* with FDR-corrected significance classes. 'zonal' = aggregate a point layer into polygon zones (count/sum/mean/min/max choropleth). 'enrich' = join a US Census indicator onto each feature by containment (tract/county/state). 'join' = spatial join (attribute transfer): each POINT in layerId takes the listed properties from the polygon in joinLayerId that contains it — the aggregate direction (points INTO polygons) is 'zonal'. 'merge' = append layerId + mergeLayerId (same geometry class) into ONE dataset, each row stamped with its source layer. 'near' = each POINT in layerId gains the great-circle distance to (and identity of) its nearest feature in nearLayerId. 'dissolve' = union POLYGONS sharing a dissolveField value into single features (omit the field to dissolve all into one). | |
| annotate | No | Opt-in: place ONE callout annotation at the headline feature (hottest cluster / top zone / highest value). Label text comes only from computed values. | |
| geoLevel | No | enrich only: containment geography (default tract). Tract/county fetch only the states the data touches, capped at 3 — filter first or use state for wider layers. | |
| hexMeters | No | hotspot density mode only: hex cell spacing in meters (default auto from the data extent). | |
| indicator | No | enrich only (required there): a US Census ACS preset id (e.g. 'median_household_income', 'median_home_value', 'median_rent') or a raw ACS variable code (e.g. 'B19013_001E'). | |
| nearField | No | near only: property of the nearest feature to copy as its identity (default: first name-like property). | |
| rationale | Yes | Short audit-log label (≤300 chars) stating the user-facing goal this call serves, e.g. "add wildfire layer for the user's California query". Required on every call. Stored in the operations log so map edits stay traceable — we never see your chat history. | |
| sumFields | No | dissolve only: numeric properties to SUM per group — skipped values reported, a group with none present carries NO sum. | |
| valueField | No | Numeric property to analyze. hotspot: omit on point layers for incident-DENSITY mode (hex-binned counts). zonal: omit for count-only aggregation. | |
| joinLayerId | No | join only (required there): the POLYGON layer providing the attributes. | |
| nearLayerId | No | near only (required there): the POINT layer to search for each target point's nearest neighbor. | |
| sourceField | No | merge only: name of the per-row provenance column naming each row's source layer (default "merge_source"; renamed on collision, reported). | |
| zoneLayerId | No | zonal only: an existing polygon layer to aggregate into. Provide EXACTLY ONE of zoneLayerId or zones. | |
| maxDistanceM | No | near only: search radius in meters — a point whose nearest neighbor is farther carries NO near fields (reported). | |
| mergeLayerId | No | merge only (required there): the second layer — same geometry class (point/line/polygon) as layerId. | |
| dissolveField | No | dissolve only: group-by property (omit = dissolve ALL into one footprint); missing values form their own "(no value)" group. |