# PlanX GeoStats Lab

Comprehensive spatial statistics and econometrics for urban planning analysis — from exploratory pattern detection to multiscale regression modeling, purpose-built for QGIS Processing workflows.

v1.0.0 44 algorithms 6 analytical groups QGIS 3.28 – 4.99 GPL-3.0

## Overview & Analytical Philosophy

PlanX GeoStats Lab is a spatial statistics processing provider for QGIS that equips urban planners, geographers, and spatial analysts with a rigorous, reproducible toolkit for pattern detection, hypothesis testing, and spatial econometric modeling. It is not a point-and-click dashboard — it is an analytical laboratory built on established statistical theory, designed for users who need to understand spatial processes, not merely visualize them.

44
Processing Algorithms
6
Analytical Groups
10
Regression Variants
4
Weight Types
3
Output Formats

Every tool operates inside the QGIS Processing framework, meaning all analyses are deterministic, repeatable, and batch-scriptable. The plugin emits structured HTML diagnostic reports, styled vector outputs with automatic symbology, CSV/JSON summaries for integration with external workflows, and inline Processing log diagnostics. Methods are selected from the peer-reviewed spatial statistics literature; where the literature offers multiple implementations, the plugin documents which variant is used and why.

Design principle. GeoStats Lab follows a diagnose-then-model philosophy. Every model group (05) is preceded by diagnostic and pattern-detection tools (00–04) that help the analyst understand their data before committing to a specification. The Workflow Advisor (00) formalizes this by recommending tool sequences based on the analyst's stated goal, geometry type, outcome type, and explanatory-variable availability.

## Quick Start

First-time setup. Open the QGIS Processing Toolbox, expand PlanX GeoStats Lab → 00 | Setup and Diagnostics, and run GeoStats Library Status to verify your Python environment. If optional packages (`mgwr`, `spreg`, `libpysal`) are missing, run Install / Update GeoStats Libraries. These libraries unlock MGWR, Spatial Autoregression, and Spatial Error Regression — all other tools use only NumPy and run on a stock QGIS Python installation.

The recommended analytical path follows the group numbering: start with a Data Readiness Audit (00), define neighborhoods with Calculate Distance Band (01), screen for global patterns (02), locate hot spots and outliers (03), characterize spatial centers and dispersion (04), and — only after understanding the data — specify regression models (05). The Workflow Advisor automates this recommendation logic.

## Analytical Workflow

00
Setup & Diagnostics
5 tools
→
01
Data & Neighborhoods
2 tools
→
02
Urban Pattern Scan
6 tools
→
03
Hot Spots & Outliers
6 tools
→
04
Centers & Dispersion
6 tools
→
05
Models & Scenarios
9 tools

Linear flow recommended for first-time analysis; experienced users may enter at any group. Every model in group 05 benefits from the diagnostics produced by groups 00–04.

00

### Setup and Diagnostics

Infrastructure tools for environment verification, optional library management, sample data access, data quality assessment, and guided workflow selection. Run these first in any new project or QGIS installation.

🔍

#### GeoStats Library Status

geostats_library_status
Non-installing diagnostic that inspects the active QGIS Python environment and reports which optional GeoStats libraries are available. Each library is imported via `importlib.import_module` and tested for successful loading; the result is rendered in a structured HTML report. No packages are installed or modified.

##### 1. Theoretical Background

The reproducibility crisis in computational science (Peng, 2011; Stodden et al., 2016) has elevated software environment transparency from a convenience to a methodological requirement. Spatial analysis is particularly vulnerable to environment drift: a Moran's I computed with `esda` v2.4 differs in its variance formula from one computed with `esda` v2.5, and an MGWR bandwidth selected by the `mgwr` package's backfitting routine can converge to a different optimum after a NumPy linear-algebra change. The Library Status tool implements the principle of computational provenance (Rey, 2009): before any spatial result is trusted, the analyst must know which version of which library computed it.

The tool's design follows three principles articulated by Wilson et al. (2014) for scientific computing: (a) make incremental changes — it inspects without modifying; (b) provide traceability — it reports exact import paths and failure traces; (c) plan for error — every import is wrapped in try/except. The report also detects an OSGeo4W shell if present and prints the exact pip command that would install missing packages, bridging the gap between diagnosis and remediation without taking action itself.

##### 2. Mathematical Formulation

No statistical computation is performed. The logic is a deterministic function mapping each library name to a binary availability state and a descriptive role string. The import check is formalised as:

$$ A(p) = \begin{cases} 1, & \text{if } \exists m \in M(p) : \text{import succeeds} \\ 0, & \text{otherwise} \end{cases} \tag{1} $$ $$ S(p) = \begin{cases} \text{"Available"}, & A(p) = 1 \\ \text{"Missing: "} + e, & A(p) = 0 \end{cases} \tag{2} $$ $$ \text{command} = \text{resolve\_python}() + \text{" -m pip install "} + \sum_{p : A(p)=0} p \tag{3} $$ where $M(p)$ is the module name mapped from package $p$ via the `MODULES` dictionary: numpy→numpy, numba→numba, scikit-learn→sklearn, libpysal→libpysal, esda→esda, spreg→spreg, mgwr→mgwr.

##### 3. Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
HTML_REPORT | File (HTML) | temp dir | Optional output path for the environment diagnostic report

##### 4. Output Description

Section | Content | Format
--- | --- | ---
Summary section | Colour-coded availability verdict: green (all present), amber (some missing) | Text with CSS styling
Package status table | Rows for all 7 packages: Package name, Import module, Status (Available/Missing), GeoStats role description | HTML table
Installation command | Exact pip command with resolved Python interpreter; copyable for manual execution | Monospace code block
Detected paths | QGIS host executable path, Python executable path, OSGeo4W shell path (if found) | Metadata fields

Checked libraries: `numpy` — always available (core QGIS dependency) · `numba` — JIT compiler used by PySAL stack · `scikit-learn` — nearest-neighbour and clustering support · `libpysal` — spatial weights engine · `esda` — exploratory spatial data analysis · `spreg` — spatial regression (SAR, SEM) · `mgwr` — multiscale GWR

##### 5. Interpretation Guide

Red "Missing" for mgwr or spreg. This only blocks MGWR (requires `mgwr`) and Spatial Autoregression / Spatial Error models (require `spreg`). All other 28 algorithms function with NumPy alone. Do not delay analysis because `mgwr` is unavailable.
Stale versions are the most dangerous. A package that imports successfully but produces wrong results because its internal API expectations changed against the installed NumPy version is a silent failure mode. This is most common with `numba`, which compiles against a specific NumPy ABI. Always verify by running a known-correct workflow on the bundled QA sample dataset.
OSGeo4W path resolution. On Windows, the tool searches for `OSGeo4W.bat` in `OSGEO4W_ROOT`, the directory above `sys.executable`, and standard `C:\OSGeo4W` / `C:\OSGeo4W64` locations. If none is found, install QGIS through the OSGeo4W network installer to obtain the shell environment.

##### 6. Literature

Rey, S.J. (2009). "Show Me the Code: Spatial Analysis and Open Source." Journal of Geographical Systems 11(2): 191–207. DOI: 10.1007/s10109-009-0086-8 — Establishes the code-transparency standard for spatial analytical software.

Peng, R.D. (2011). "Reproducible Research in Computational Science." Science 334(6060): 1226–1227. DOI: 10.1126/science.1213847 — Defines the reproducibility standard for data-driven science.

Wilson, G., Aruliah, D.A., Brown, C.T., et al. (2014). "Best Practices for Scientific Computing." PLoS Biology 12(1): e1001745. DOI: 10.1371/journal.pbio.1001745 — Codifies 24 best practices; the Library Status tool addresses traceability and error-handling practices.

Sandve, G.K., Nekrutenko, A., Taylor, J. & Hovig, E. (2013). "Ten Simple Rules for Reproducible Computational Research." PLoS Computational Biology 9(10): e1003285. DOI: 10.1371/journal.pcbi.1003285 — Rule 3 ("Archive the Exact Versions of All External Programs") is the foundation for dependency auditing.

Stodden, V., McNutt, M., Bailey, D.H., et al. (2016). "Enhancing Reproducibility for Computational Methods." Science 354(6317): 1240–1242. DOI: 10.1126/science.aah6168 — Policy-level argument for computational transparency in published research.

Barnes, N. (2010). "Publish Your Computer Code: It Is Good Enough." Nature 467(7317): 753. DOI: 10.1038/467753a — Concise editorial arguing for code release as a scientific norm.

Millman, K.J. & Aivazis, M. (2011). "Python for Scientists and Engineers." Computing in Science & Engineering 13(2): 9–12. DOI: 10.1109/MCSE.2011.36 — Introduces Python packaging conventions for scientific computing.

Van der Walt, S., Colbert, S.C. & Varoquaux, G. (2011). "The NumPy Array." Computing in Science & Engineering 13(2): 22–30. DOI: 10.1109/MCSE.2011.37 — Documents NumPy's data structures that form the computation substrate for all GeoStats engines.

Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22. DOI: 10.1111/j.0016-7363.2005.00671.x — The GeoDa model: software transparency as a pedagogical and analytical requirement.

Boettiger, C. (2015). "An Introduction to Docker for Reproducible Research." ACM SIGOPS Operating Systems Review 49(1): 71–79. DOI: 10.1145/2723872.2723882 — Containerisation as the ultimate solution to environment drift; complements runtime auditing.

📦

#### Install / Update GeoStats Libraries

install_geostats_libraries
Explicit, user-initiated pip installation of optional GeoStats Python packages into the active QGIS environment. The tool reads the package list from `requirements_geostats.txt`, builds a pip install command with `--upgrade` flag, and requires explicit user approval via a confirmation checkbox before executing the command. Installation output is streamed line-by-line into the QGIS Processing log. This tool does not install anything silently.

##### 1. Theoretical Background

The management of computational dependencies occupies a tension zone between automation (pip, conda, poetry) and transparency (the analyst must know what changed in their environment). The Install Libraries tool is a non-silent installer following the audit-trail principle articulated by Sandve et al. (2013) — every environmental change should be deliberate, documented, and reversible. The confirmation checkbox is not a UX obstacle; it is a reproducibility gate.

Two installation modes are supported. QGIS Python pip mode resolves the Python executable belonging to the running QGIS installation and invokes it as `python -m pip install --upgrade <packages>`. OSGeo Shell mode constructs a `cmd.exe /c` command that first calls `OSGeo4W.bat` to set up the environment, then runs pip — necessary on Windows when QGIS is launched from `qgis-bin.exe` rather than a Python process. The mode detection logic handles this platform-specific branching automatically.

The package list — numba, libpysal, esda, spreg, mgwr, scikit-learn — constitutes the spatial statistics extension stack. Each package is optional: GeoStats Lab degrades gracefully when any package is absent, and the Library Status tool reports exactly which algorithms are affected. This modular dependency architecture follows the layered design of the PySAL ecosystem (Rey & Anselin, 2010), where each layer depends on the layers below but user-facing tools work with whatever layers are present.

##### 2. Mathematical Formulation

$$ \text{mode} = \begin{cases} 0 & \text{(QGIS Python pip)}, & \text{if } \text{resolve\_python}() \neq \text{None} \\ 1 & \text{(OSGeo Shell)}, & \text{if } \text{os} = \text{win32} \land \text{find\_osgeo\_shell}() \neq \text{None} \\ 0 & \text{(fallback)}, & \text{otherwise} \end{cases} \tag{1} $$ $$ \text{packages} = \text{read\_requirements()} \lor \{\text{numba, libpysal, esda, spreg, mgwr, scikit-learn}\} \tag{2} $$ $$ \text{command}_0 = \text{python\_exe} + \text{" -m pip install --upgrade "} + \text{packages} \tag{3} $$ $$ \text{command}_1 = \text{"cmd.exe"} + \text{"/c call "} + \text{osgeo\_bat} + \text{" && python -m pip install --upgrade "} + \text{packages} \tag{4} $$ $$ \text{result} = \begin{cases} \text{"Success"}, & \text{exit\_code} = 0 \\ \text{"Failure"}, & \text{otherwise} \end{cases} \tag{5} $$

##### 3. Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INSTALL_MODE | Enum | auto-detected | "QGIS Python pip" (0) or "OSGeo Shell" (1). Default resolved from environment.
CONFIRM | Boolean | false | Explicit user approval required; unchecked runs a dry-run preview only
COMMAND (output) | String | — | Output: the exact command string that was (or would be) executed

##### 4. Output Description

Output | Type | Description
--- | --- | ---
COMMAND | String output | The full pip command executed, including all arguments
Processing log | Streamed text | Real-time stdout from the pip subprocess, line by line; includes download progress and install confirmation
Exit code | Integer | 0 = success; non-zero triggers a QgsProcessingException with pip error details

##### 5. Interpretation Guide

Preview-only mode (CONFIRM = false). The tool prints the exact command, the QGIS host executable path, the Python executable it would use, and the detected OSGeo Shell path, then raises a controlled Processing exception: "Preview only: installation was not started." This is by design — the analyst must review which executable and packages would be affected before approving.
Restart requirement. After a successful installation, restart QGIS before running advanced GeoStats tools. Python caches imported modules for the lifetime of the process; a newly installed package cannot be imported by an already-running QGIS session without a provider reload — which QGIS does not do automatically.
Common failure modes. (a) "QGIS is running from an application executable" — no Python interpreter found; use OSGeo Shell mode. (b) "Permission denied" — QGIS Python environment in a system-protected directory; run QGIS as administrator (Windows) or use a user-site installation. (c) "No matching distribution" — package version constraint incompatible with the QGIS Python version.

##### 6. Literature

Sandve, G.K., Nekrutenko, A., Taylor, J. & Hovig, E. (2013). "Ten Simple Rules for Reproducible Computational Research." PLoS Computational Biology 9(10): e1003285. DOI: 10.1371/journal.pcbi.1003285 — Rules 3, 7, and 9 directly inform the non-silent installer design.

Wilson, G., Aruliah, D.A., Brown, C.T., et al. (2014). "Best Practices for Scientific Computing." PLoS Biology 12(1): e1001745. DOI: 10.1371/journal.pbio.1001745 — Best practices for build management and dependency tracking.

Perez, F., Granger, B.E. & Hunter, J.D. (2011). "Python: An Ecosystem for Scientific Computing." Computing in Science & Engineering 13(2): 13–21. DOI: 10.1109/MCSE.2010.119 — Documents the Python scientific ecosystem that pip installs into.

Millman, K.J. & Aivazis, M. (2011). "Python for Scientists and Engineers." Computing in Science & Engineering 13(2): 9–12. DOI: 10.1109/MCSE.2011.36 — Introduces pip and virtualenv conventions for scientific Python.

Van der Walt, S., Colbert, S.C. & Varoquaux, G. (2011). "The NumPy Array." Computing in Science & Engineering 13(2): 22–30. DOI: 10.1109/MCSE.2011.37 — Documents NumPy, the foundation package present in every QGIS Python environment.

Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, Springer, 175–193. DOI: 10.1007/978-3-642-03647-7_11 — Documents the PySAL ecosystem (libpysal, esda, spreg) that this tool installs.

Rey, S.J. (2009). "Show Me the Code: Spatial Analysis and Open Source." Journal of Geographical Systems 11(2): 191–207. DOI: 10.1007/s10109-009-0086-8 — The code-transparency argument that motivates explicit dependency management.

Peng, R.D. (2011). "Reproducible Research in Computational Science." Science 334(6060): 1226–1227. DOI: 10.1126/science.1213847 — The reproducibility standard requiring environment documentation.

Barnes, N. (2010). "Publish Your Computer Code: It Is Good Enough." Nature 467(7317): 753. DOI: 10.1038/467753a — Argument for code release; dependencies are part of the code.

Stodden, V., McNutt, M., Bailey, D.H., et al. (2016). "Enhancing Reproducibility for Computational Methods." Science 354(6317): 1240–1242. DOI: 10.1126/science.aah6168 — Policy framework for computational reproducibility including environment specification.

🧪

#### Sample Dataset Guide

sample_dataset_guide
Generates an HTML guide listing every bundled synthetic dataset, its schema, and which algorithms it exercises. Loads planning-relevant QA fixtures (points, lines, polygons) and model-output verification layers into the current QGIS project so analysts can validate tool behavior before applying it to their own data. The guide includes explicit documentation of which QA layers exercise which output fields — making it a pedagogical tool as much as a verification tool.

##### 1. Theoretical Background

The use of curated sample datasets in spatial analysis education traces its roots to the GeoDa workbook (Anselin, 2005; Anselin et al., 2006), which demonstrated that spatial statistics pedagogy requires datasets where the expected result is known. A student who runs Global Moran's I on an unfamiliar dataset cannot distinguish between a software bug and a genuinely random spatial pattern. The Sample Dataset Guide addresses this by bundling two GeoPackages with known properties: the Izmir FUR street network sample (391 polygon features at EPSG:5253 covering the Izmir Functional Urban Region with street-network and space-syntax accessibility indicators) and the Synthetic QA fixture (9 compact layers with deliberately varied geometries and pre-computed model outputs).

The QA fixture implements the principle of test-driven spatial analysis: each layer exercises specific code paths. `qa_points_grid` (100-point regular grid) verifies ANN and Ripley's K under CSR. `qa_lines_directional` verifies Linear Directional Mean. Six model-output layers (`qa_ols_model_output` through `qa_mgwr_model_output`) verify that the Model Comparison Matrix correctly recognises residual, predicted, and fitted fields. This follows the scientific-software verification framework of Wilson et al. (2014), adapted to the spatial-statistics domain.

##### 2. Mathematical Formulation

$$ L_{\text{izmir}} = \{\text{izmir\_fur\_street\_network}\} \quad\text{(1 layer, 391 polygons, EPSG:5253)} \tag{1} $$ $$ L_{\text{qa}} = \{\text{qa\_points\_grid}, \text{qa\_lines\_directional}, \dots, \text{qa\_mgwr\_model\_output}\} \quad\text{(9 layers)} \tag{2} $$ $$ \text{load}(m) = \begin{cases} L_{\text{izmir}}, & m = 0 \\ L_{\text{qa}}, & m = 1 \\ L_{\text{izmir}} \cup L_{\text{qa}}, & m = 2 \end{cases} \tag{3} $$ $$ \text{loaded} = \{l \in \text{load}(m) : \text{QgsVectorLayer}(\text{gpkg} + "\text{|layername=}" + l).\text{isValid}()\} \tag{4} $$

##### 3. Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
LOAD_IN_PROJECT | Boolean | true | Load sample layers into current QGIS project; set false to only generate the guide
DATASET_TO_LOAD | Enum | 0 (Izmir) | "Izmir FUR street network sample" (0), "Synthetic QA fixture" (1), or "Both datasets" (2)
HTML_REPORT | File (HTML) | temp dir | Output path for the sample catalog guide
SAMPLE_PATH (output) | String | — | Filesystem path to the Izmir sample GeoPackage
SYNTHETIC_QA_PATH (output) | String | — | Filesystem path to the synthetic QA GeoPackage
LOADED_LAYERS (output) | String | — | Comma-separated list of layer names actually loaded

##### 4. Output Description

Section | Content
--- | ---
HTML guide | Table of all 10 bundled layers with geometry type, feature count, recommended workflows, starter field suggestions
Loaded map layers | Up to 10 layers added to project with "PlanX GeoStats Sample" or "PlanX GeoStats QA" prefixes
Recommended workflows | Four pre-configured analytical paths (network pattern scan, accessibility model, model audit, connectivity equity) pairing Izmir FUR fields with GeoStats tools
QA layer purpose matrix | Each QA layer cross-referenced to the algorithms and edge cases it exercises

##### 5. Interpretation Guide

Pedagogical use. Designed for classroom and workshop settings where each algorithm can be demonstrated with known-correct inputs. The Izmir FUR sample contains realistic spatial structure — `road_density` is strongly and genuinely spatially autocorrelated (Global Moran's I = 0.63, z > 27 at KNN=8), so Global Moran's I on that field reliably returns a highly significant positive result. This is a "known good" baseline confirming the toolchain functions.
QA edge cases. The synthetic QA layers contain deliberate challenges: isolated features (no neighbours under Queen contiguity), constant fields (zero standard deviation), mixed geometry types, and features with missing values. Run each GeoStats tool on the appropriate QA layer first to verify graceful handling before applying it to production data.

##### 6. Literature

Anselin, L. (2005). Exploring Spatial Data with GeoDa: A Workbook. Center for Spatially Integrated Social Science, UIUC. — The pedagogical model for sample-data-driven spatial analysis teaching.

Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22. DOI: 10.1111/j.0016-7363.2005.00671.x — Documents the curated-dataset approach to spatial-statistics education.

Wilson, G., Aruliah, D.A., Brown, C.T., et al. (2014). "Best Practices for Scientific Computing." PLoS Biology 12(1): e1001745. DOI: 10.1371/journal.pbio.1001745 — Best practice #7 ("Plan for mistakes") directly motivates the QA fixture design.

Rey, S.J. (2009). "Show Me the Code: Spatial Analysis and Open Source." Journal of Geographical Systems 11(2): 191–207. DOI: 10.1007/s10109-009-0086-8 — Code transparency and testability as methodological requirements.

Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, Springer, 175–193. DOI: 10.1007/978-3-642-03647-7_11 — Documents the PySAL test-data conventions that inspired the QA fixture structure.

Sandve, G.K., Nekrutenko, A., Taylor, J. & Hovig, E. (2013). "Ten Simple Rules for Reproducible Computational Research." PLoS Computational Biology 9(10): e1003285. DOI: 10.1371/journal.pcbi.1003285 — Rule 1 ("For Every Result, Keep Track of How It Was Produced") — the sample dataset records the input.

Peng, R.D. (2011). "Reproducible Research in Computational Science." Science 334(6060): 1226–1227. DOI: 10.1126/science.1213847 — Reproducibility requires known inputs; the sample dataset provides them.

Fotheringham, A.S., Brunsdon, C. & Charlton, M. (2002). Geographically Weighted Regression. Wiley. DOI: 10.1002/9780470027042 — The GWR methodology exercised by the Izmir network-structure-relationship workflow.

Getis, A. & Ord, J.K. (1992). "The Analysis of Spatial Association by Use of Distance Statistics." Geographical Analysis 24(3): 189–206. DOI: 10.1111/j.1538-4632.1992.tb00261.x — The Gi* method exercised by the Izmir street-network-clustering workflow.

Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. DOI: 10.1111/j.1538-4632.1995.tb00338.x — The LISA method exercised by the Izmir accessibility-equity workflow.

📋

#### Data Readiness Audit

data_readiness_audit
Pre-modeling diagnostic that evaluates a vector layer and its fields against a checklist of statistical assumptions: numeric adequacy, missingness patterns, skew, zero-inflation, constant-value detection, outlier prevalence, and record count sufficiency. Produces a multi-section HTML report with layer profiling, field-level audit tables, pairwise correlation screening, and workflow-specific readiness assessments. Designed as the first gate in any spatial-statistical analysis pipeline.

##### 1. Theoretical Background

Planning datasets routinely contain categorical codes stored as integers, percentage fields bounded at 0% and 100%, count fields with severe zero-inflation, and administrative boundaries with missing or invalid geometries. Running a spatial regression on such data without prior audit produces coefficient estimates that are computable but unreliable — the software returns numbers, but the numbers do not mean what the analyst thinks they mean.

The Data Readiness Audit implements a four-level diagnostic framework formalised by Anselin (2005) and extended by the reproducible-research movement (Peng, 2011; Sandve et al., 2013):

1. Layer integrity — feature count, geometry type, CRS (projected vs. geographic), empty/invalid/multipart geometry counts.
2. Field numeracy — per-field valid count, missing/non-finite count, missing %, min, max, mean, median, std, skewness (third standardised moment), IQR, IQR outlier count, unique-value count. Constant and near-constant fields (std ≤ 10−9) are flagged as unanalysable.
3. Multicollinearity screening — pairwise Pearson correlation via `np.corrcoef`; pairs with |r| ≥ 0.85 reported, |r| ≥ 0.95 flagged as severe.
4. Workflow readiness — mapping of known field names to standard planning workflows (urban heat scan, green cooling model, accessibility analysis, equity review).

##### 2. Mathematical Formulation

$$ \gamma_1 = \frac{1}{n} \sum_{i=1}^{n} \left( \frac{x_i - \bar{x}}{s} \right)^3, \quad s = \sqrt{\tfrac{1}{n}\sum(x_i - \bar{x})^2} \tag{1} $$ $$ \text{IQR} = Q_3 - Q_1, \quad n_{\text{out}} = \sum_{i=1}^{n} \mathbb{I}[x_i < Q_1 - 1.5\text{IQR} \lor x_i > Q_3 + 1.5\text{IQR}] \tag{2} $$ $$ r_{jk} = \frac{\sum (x_{ij} - \bar{x}_j)(x_{ik} - \bar{x}_k)}{\sqrt{\sum(x_{ij} - \bar{x}_j)^2}\sqrt{\sum(x_{ik} - \bar{x}_k)^2}} \quad\text{(complete-case pairs, via np.corrcoef)} \tag{3} $$ $$ R(f) = \begin{cases} \text{"Not ready"}, & n_{\text{valid}}(f) < 4 \lor \text{constant}(f) \\ \text{"Review"}, & n_{\text{valid}}/n_{\text{total}} < 0.75 \lor p_{\text{missing}} > 10\% \\ \text{"Ready"}, & \text{otherwise} \end{cases} \tag{4} $$ $$ \text{risk}_{\text{CRS}} = \mathbb{I}[\text{crs.isGeographic()}] \tag{5} $$ $$ S(w) = \begin{cases} \text{"Ready"}, & F_{\text{req}}(w) \subseteq F_{\text{avail}} \\ \text{"Partially ready"}, & F_{\text{req}}(w) \cap F_{\text{avail}} \neq \emptyset \\ \text{"Not detected"}, & \text{otherwise} \end{cases} \tag{6} $$

##### 3. Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Layer to audit (any geometry type)
FIELDS | Field (multi, optional) | all numeric | Numeric fields to audit; if blank, all numeric fields are audited
HTML_REPORT | File (HTML) | temp dir | Output multi-section HTML audit report
FIELD_AUDIT_CSV | File (CSV, optional) | — | Optional CSV export of per-field audit metrics
AUDIT_JSON | File (JSON, optional) | — | Optional full-audit JSON export (schema v1.0)

##### 4. Output Description

Section | Content
--- | ---
Layer Profile | Feature count, field count, geometry type, CRS, distance-analysis note
Geometry Diagnostics | Empty/invalid/multipart geometry counts
Automatic Risk Review | Aggregated risks: geographic CRS, small sample, empty/invalid geometries, not-ready fields, review-needed fields, high-correlation pairs, skew, outliers
Numeric Field Audit | Per-field table (12 columns): valid, missing, min, max, mean, median, std, skewness, IQR outliers, unique values, readiness classification with colour coding
Analysis Role Suggestions | Per-field: suggested role (target, explanatory, count, indicator, review), reason, likely GeoStats tools
Multicollinearity Screen | High-correlation pairs (|r| ≥ 0.85), descending, with complete record counts
Workflow Readiness | Four predefined workflows with status, target fields, explanatory fields, tool sequence, planning purpose
Recommended Next Actions | Prioritised action items based on detected risks
FIELD_AUDIT_CSV | 21-column machine-readable table
AUDIT_JSON | Complete audit payload under schema "planx_geostats_data_readiness_audit" v1.0

##### 5. Interpretation Guide

Constant and near-constant detection. A field with one unique value (or std ≤ 10−9) contributes zero information to any regression or spatial statistic. The audit flags these as "Not ready" because including them produces singular matrices or degenerate statistics. Action: remove the field or investigate whether the constant value reflects a data error.
Skewness benchmarks. |skewness| < 0.5: approximately symmetric, suitable for OLS without transformation. 0.5 ≤ |skewness| < 1.0: moderately skewed; check residual plots. 1.0 ≤ |skewness| < 1.5: substantially skewed; consider log or Box-Cox transformation. |skewness| ≥ 1.5: strongly skewed; the audit triggers a warning. Skewness matters most for the dependent variable in OLS.
Correlation thresholds. |r| ≥ 0.85 is a screening threshold, not a hard rule. Variables like "impervious surface %" and "tree canopy %" are often correlated at r ≈ −0.85 — complementary measures of the same phenomenon. The audit flags the pair so the analyst knows; it does not ban the combination. For MGWR, high collinearity is especially dangerous because local coefficient surfaces become unstable.
Geographic CRS warning. If the CRS is geographic, a red warning is inserted. Euclidean distances in decimal degrees are not metric: 1° longitude at 40°N ≈ 85 km, at 60°N ≈ 56 km. Reproject to a local projected CRS before distance-dependent tools.

##### 6. Literature

Anselin, L. (2005). Exploring Spatial Data with GeoDa: A Workbook. Center for Spatially Integrated Social Science, UIUC. — The diagnostic-first framework for spatial statistics.

Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22. DOI: 10.1111/j.0016-7363.2005.00671.x — Formalises the data-quality-first approach implemented by this audit.

Tukey, J.W. (1977). Exploratory Data Analysis. Addison-Wesley. ISBN: 978-0201076165 — The foundational text; IQR outlier detection and skewness diagnostics originate here.

Belsley, D.A., Kuh, E. & Welsch, R.E. (1980). Regression Diagnostics. Wiley. DOI: 10.1002/0471725153 — The canonical reference for multicollinearity diagnostics; VIF and condition indices.

Peng, R.D. (2011). "Reproducible Research in Computational Science." Science 334(6060): 1226–1227. DOI: 10.1126/science.1213847 — Data readiness as a reproducibility prerequisite.

Sandve, G.K., Nekrutenko, A., Taylor, J. & Hovig, E. (2013). "Ten Simple Rules for Reproducible Computational Research." PLoS Computational Biology 9(10): e1003285. DOI: 10.1371/journal.pcbi.1003285 — Rule 5 ("Record All Intermediate Results") — the audit is the first intermediate result.

Getis, A. & Ord, J.K. (1992). "The Analysis of Spatial Association by Use of Distance Statistics." Geographical Analysis 24(3): 189–206. DOI: 10.1111/j.1538-4632.1992.tb00261.x — The Gi* statistics whose assumptions the audit validates.

Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. DOI: 10.1111/j.1538-4632.1995.tb00338.x — LISA statistics whose performance depends on data quality screened by the audit.

Getis, A. & Aldstadt, J. (2004). "Constructing the Spatial Weights Matrix Using a Local Statistic." Geographical Analysis 36(2): 90–104. DOI: 10.1111/j.1538-4632.2004.tb01123.x — Weights-matrix construction methodology that depends on clean input data.

Stodden, V., McNutt, M., Bailey, D.H., et al. (2016). "Enhancing Reproducibility for Computational Methods." Science 354(6317): 1240–1242. DOI: 10.1126/science.aah6168 — Data auditing as a prerequisite for computational-method reproducibility.

🧭

#### GeoStats Workflow Advisor

geostats_workflow_advisor
Decision-support engine that recommends a personalised sequence of GeoStats tools based on four analyst-specified dimensions: analysis goal (7 options), geometry context (point, line, polygon), outcome type (none, continuous, binary, count), and explanatory-variable availability (boolean). The core recommendation logic lives in `core/workflow_advisor.py` as a pure function `personalized_recommendation(goal, geometry, outcome, has_explanatory)` — deterministic, testable, and free of side effects.

##### 1. Theoretical Background

Method selection in spatial statistics is non-trivial because the appropriate tool depends on a conjunction of data characteristics and analytical intent. Novice analysts routinely apply the wrong tool: running OLS on a binary outcome, interpreting Gi* without checking global autocorrelation, or selecting a distance band arbitrarily. The Workflow Advisor encodes a decision-tree logic with three layers:

1. Type checking — binary outcomes map to logistic GLM, counts to Poisson GLM, continuous outcomes to OLS/GWR/MGWR, lines to directional tools.
2. Dependency ordering — "build an explanatory model" prepends Data Readiness Audit and appends residual autocorrelation review and Model Comparison; "map hot spots" prepends Calculate Distance Band.
3. Warning generation — technically possible but methodologically fragile combinations trigger structured warnings.

The advisor draws on the diagnostic-first framework of Anselin (2005), the tool-sequencing logic implicit in the GeoDa workbook (Anselin et al., 2006), and the reproducible-research workflow structure advocated by Sandve et al. (2013).

##### 2. Mathematical Formulation

$$ G \in \{0,\dots,6\}: \text{explore, hotspots, distance\_band, centres, model, compare, inequality} \tag{1} $$ $$ \Gamma \in \{0,1,2\}: \text{point, line, polygon} \tag{2} $$ $$ \Omega \in \{0,1,2,3\}: \text{none, continuous, binary, count} \tag{3} $$ $$ R(G,\Gamma,\Omega,E) = (\text{steps}, \text{checks}, \text{samples}, \text{warnings}, \text{summary}) \tag{4} $$ $$ \text{warn} \mathrel{+}= \{\text{"Line geometry..."}\} \quad\text{if } \Gamma = 1 \land G \notin \{3\} \tag{5} $$ $$ \text{warn} \mathrel{+}= \{\text{"This goal usually needs..."}\} \quad\text{if } \Omega = 0 \land G \in \{1,4,5,6\} \tag{6} $$ $$ \text{first\_model}(\Omega) = \begin{cases} \text{"Logistic GLR"}, & \Omega = 2 \\ \text{"Poisson GLR"}, & \Omega = 3 \\ \text{"OLS Regression"}, & \text{otherwise} \end{cases} \tag{7} $$ $$ \text{steps}_{G=4} = [\text{Data Readiness}, \text{first\_model}(\Omega), \text{Residual review}, \text{GWR/MGWR}, \text{SAR/SEM}, \text{Model Comparison}] \tag{8} $$ $$ \text{steps}_{G=0} = [\text{Data Readiness}, \text{Calculate Distance Band}, \text{Global Moran's I}, \text{Gi* or LISA}] \tag{9} $$ $$ \text{steps}_{G=6} = [\text{Data Readiness}, \text{Spatial Gini}, \text{Global Moran's I}, \text{Gi* or LISA}] \tag{10} $$

##### 3. Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
GOAL | Enum | 0 | Explore spatial pattern (0) / Map hot spots (1) / Choose distance band (2) / Summarise centres (3) / Build explanatory model (4) / Compare models (5) / Measure spatial inequality (6)
GEOMETRY_CONTEXT | Enum | 2 | Point (0) / Line (1) / Polygon or area (2)
OUTCOME_TYPE | Enum | 1 | No outcome field (0) / Continuous numeric (1) / Binary 0/1 (2) / Count (3)
HAS_EXPLANATORY | Boolean | false | "I have explanatory/candidate predictor fields"
HTML_REPORT | File (HTML) | temp dir | Output multi-section advisory report

##### 4. Output Description

Section | Content
--- | ---
Personalised Recommendation | Tool sequence (ordered), pre-interpretation checks, bundled sample fields, combination warnings
Planning Questions to Tools | Nine planning questions mapped to specific GeoStats tools, inputs, outputs, and next steps
Tool Selection Matrix | Data-question type mapped to candidate tools with selection-decision rules
Method Assumptions | Five method families with minimum assumptions and cautions
Common Pitfalls | Five classic mistakes (WGS84 distances, arbitrary thresholds, skipping audit, p-value fixation, single-metric comparison) with safer alternatives
Starter Recipes | Six ready-to-run workflows pairing Izmir/QA fields with tool sequences
Quality Gates | Five-stage quality checklist (before analysis, distance tools, models, release/QA, after modeling)
Interpretation Discipline | General principles for spatial-statistical interpretation

##### 5. Interpretation Guide

Decision tree is a starting point, not a straitjacket. The Workflow Advisor encodes the most common analytical paths; it does not know your specific planning question, data quality, or theoretical framework. If the advisor recommends OLS and your outcome is a rate bounded at [0, 100], transform it (logit or arcsine-square-root) before proceeding. The advisor's value is in preventing the most common mistakes and surfacing the dependency chain between tools.
Sample field suggestions are opt-in. Each recommendation includes bundled sample fields referencing the Izmir FUR sample dataset and synthetic QA fixture. These exist so the analyst can verify the recommended tool sequence on known-good data before applying it to their own — a built-in reproducibility check.

##### 6. Literature

Anselin, L. (2005). Exploring Spatial Data with GeoDa: A Workbook. CSISS, UIUC. — The diagnostic-first workflow formalised as a decision tree.

Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22. DOI: 10.1111/j.0016-7363.2005.00671.x — Tool-sequencing logic that informs the advisor's dependency chains.

Sandve, G.K., Nekrutenko, A., Taylor, J. & Hovig, E. (2013). "Ten Simple Rules for Reproducible Computational Research." PLoS Computational Biology 9(10): e1003285. DOI: 10.1371/journal.pcbi.1003285 — Reproducible workflow structure that the advisor formalises into tool sequences.

Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer. — The theoretical foundation for SAR/SEM model-selection logic.

LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. CRC Press. DOI: 10.1201/9781420064254 — Modern synthesis of spatial econometric model selection.

Fotheringham, A.S., Brunsdon, C. & Charlton, M. (2002). Geographically Weighted Regression. Wiley. DOI: 10.1002/9780470027042 — GWR methodology that the advisor recommends for spatially varying relationships.

Getis, A. & Ord, J.K. (1992). "The Analysis of Spatial Association by Use of Distance Statistics." Geographical Analysis 24(3): 189–206. DOI: 10.1111/j.1538-4632.1992.tb00261.x — General G and Gi* statistics recommended by the advisor for hot-spot mapping.

Getis, A. & Aldstadt, J. (2004). "Constructing the Spatial Weights Matrix Using a Local Statistic." Geographical Analysis 36(2): 90–104. DOI: 10.1111/j.1538-4632.2004.tb01123.x — Distance-band selection methodology the advisor encodes as a dependency.

Rey, S.J. & Smith, R.J. (2013). "A Spatial Decomposition of the Gini Coefficient." Letters in Spatial and Resource Sciences 6(2): 55–70. DOI: 10.1007/s12076-012-0086-z — Spatial Gini methodology recommended for inequality-goal workflows.

Fotheringham, A.S., Yang, W. & Kang, W. (2017). "Multiscale Geographically Weighted Regression (MGWR)." Annals of the AAG 107(6): 1247–1265. DOI: 10.1080/24694452.2017.1352480 — MGWR methodology the advisor suggests for multiscale questions.

01

### Data Preparation and Neighborhoods

Tools that define the spatial framework within which all subsequent analyses operate. The spatial weights matrix — the mathematical encoding of "which features are neighbors" — is the single most consequential modeling choice in spatial statistics. These tools help the analyst make that choice deliberately and transparently.

📏

#### Calculate Distance Band from Neighbor Count

calculate_distance_band
Computes the distance to the k-th nearest neighbour for every feature using centroid-to-centroid Euclidean distances, then reports six summary statistics (minimum, 25th percentile, median, mean, 75th percentile, maximum). The maximum distance is the smallest threshold that guarantees every feature has at least k neighbours — the data-driven answer to "what distance band should I use?"

##### 1. Theoretical Background

The choice of distance band is the single most consequential parameter in distance-based spatial statistics. A band too small produces isolated features (zero neighbours), which produce degenerate statistics. A band too large connects every feature to every other, washing out local structure. Getis & Aldstadt (2004) formalised this as a spatial weights matrix construction problem: the weights should be chosen to optimise a local statistic's performance, not guessed from map extent or feature density alone.

The k-th nearest-neighbour distance distribution summarises the spatial point pattern's characteristic spacing. In a regular grid, distances are tightly clustered. In a pattern with dense urban cores and sparse rural peripheries, distances span orders of magnitude — and the maximum distance (the cost of universal connectivity) may be impractically large. For such heterogeneous patterns, KNN weights (equal neighbour counts) are preferable to distance-band weights.

The engine function `calculate_distance_band_stats` computes a dense $N \times N$ Euclidean distance matrix via NumPy broadcasting, sorts each row, extracts the k-th element, and computes percentiles via `np.percentile`. For $N > 5000$, memory usage is approximately $8N^2$ bytes (~200 MB), suitable for typical planning datasets of hundreds to a few thousand features.

##### 2. Mathematical Formulation

$$ d_{ij} = \sqrt{(x_i - x_j)^2 + (y_i - y_j)^2}, \quad i,j \in \{1,\dots,N\} \tag{1} $$ $$ d_i^{(k)} = \text{sorted}\{d_{ij} : j \neq i\}_{[k]}, \quad k \leftarrow \min(k, N-1) \tag{2} $$ $$ d_{\min} = \min_i d_i^{(k)}, \quad d_{\max} = \max_i d_i^{(k)}, \quad \bar{d} = \tfrac{1}{N}\sum d_i^{(k)} \tag{3} $$ $$ d_{p25} = P_{25}(\{d_i^{(k)}\}), \quad d_{\text{median}} = P_{50}(\{d_i^{(k)}\}), \quad d_{p75} = P_{75}(\{d_i^{(k)}\}) \tag{4} $$ $$ C(d) = \frac{|\{i : \text{neighbour\_count}(i, d) \ge k\}|}{N} \tag{5} $$ $$ \text{band}^* = d_{\max} \quad\text{ensures } C(d_{\max}) = 1.0 \tag{6} $$ Use $d_{p75}$ when the cost of connecting the most isolated feature is disproportionate to analytical benefit.

##### 3. Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input feature layer (any geometry; centroids used for distance)
NEIGHBOR_COUNT | Integer | 1 | Target minimum neighbour count per feature (k); must be < feature count
HTML_REPORT | File (HTML) | temp dir | Output distance band statistics report

##### 4. Output Description

Metric | Description | Analytical Role
--- | --- | ---
Minimum Distance | Smallest distance from any feature to its k-th neighbour | Lower bound; reflects densest cluster spacing
25th Percentile (P25) | 25% of features have k-th neighbour closer than this | Typical spacing in dense areas
Median Distance | 50% of features' k-th neighbour distance | Central tendency; robust to outliers
Mean Distance | Arithmetic mean of all k-th neighbour distances | Sensitive to isolated features; compare with median
75th Percentile (P75) | 75% of features' k-th neighbour distance | Practical compromise threshold; 3/4 of features connected
Maximum Distance | Largest k-th neighbour distance | Conservative band; guarantees universal k-connectivity

##### 5. Interpretation Guide

Choosing k. $k = 1$ answers "what distance ensures every feature has at least one neighbour?" — the most common use case. $k = 5$ to $8$ produces a neighbourhood size comparable to Queen contiguity on a typical polygon tessellation. $k > 15$ smooths local variation aggressively and should be justified by the spatial process scale.
Mean-vs-median gap as heterogeneity diagnostic. If $\bar{d} / d_{\text{median}} > 2$, the feature distribution is strongly heterogeneous — a dense core with distant outliers. In this case, a single distance band will give core features hundreds of neighbours and peripheral features exactly k. Consider KNN weights or splitting the analysis into sub-regions.
Incremental Autocorrelation as the next step. The distance band from this tool guarantees connectivity but does not guarantee that the spatial process exhibits its strongest structure at that scale. Run Incremental Spatial Autocorrelation (Group 02) on the target variable to find the analytically optimal band, which may differ from the connectivity-guaranteeing band. When they differ substantially, prefer the autocorrelation-peak distance and note the isolation count.

##### 6. Literature

Getis, A. & Aldstadt, J. (2004). "Constructing the Spatial Weights Matrix Using a Local Statistic." Geographical Analysis 36(2): 90–104. DOI: 10.1111/j.1538-4632.2004.tb01123.x — The foundational paper for data-driven spatial weights construction.

Getis, A. & Ord, J.K. (1992). "The Analysis of Spatial Association by Use of Distance Statistics." Geographical Analysis 24(3): 189–206. DOI: 10.1111/j.1538-4632.1992.tb00261.x — Introduces General G and Gi*; distance-band choice is integral to the G(d) statistic.

Ord, J.K. & Getis, A. (1995). "Local Spatial Autocorrelation Statistics: Distributional Issues and an Application." Geographical Analysis 27(4): 286–306. DOI: 10.1111/j.1538-4632.1995.tb00912.x — Distributional theory for Gi*; distance-band sensitivity analysis.

Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer. — Establishes the spatial weights matrix as the fundamental modelling choice.

Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. Pion. — The classic reference for spatial weights specification.

Anselin, L. (2005). Exploring Spatial Data with GeoDa: A Workbook. CSISS, UIUC. — Practical guidance on distance-band selection for applied analysis.

Clark, P.J. & Evans, F.C. (1954). "Distance to Nearest Neighbor as a Measure of Spatial Relationships in Populations." Ecology 35(4): 445–453. DOI: 10.2307/1931034 — The origin of nearest-neighbour distance analysis; conceptual predecessor.

Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, Springer, 175–193. DOI: 10.1007/978-3-642-03647-7_11 — Documents the weights-construction utilities that the engine parallels.

LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. CRC Press. DOI: 10.1201/9781420064254 — Discusses model sensitivity to spatial weights specification.

Moran, P.A.P. (1950). "Notes on Continuous Stochastic Phenomena." Biometrika 37(1/2): 17–23. DOI: 10.1093/biomet/37.1-2.17 — The origin of the I statistic whose performance depends on the neighbourhood definition this tool provides.

📤

#### Export Feature Attributes to CSV/ASCII

export_attributes_to_ascii
Exports the attribute table of a vector layer to delimited text (CSV, tab, semicolon, or space) for use in external statistical software (R, Stata, SPSS, Python/pandas). Includes optional geometry export as centroid X/Y coordinate columns. Designed as a lossless, encoding-safe bridge between QGIS spatial data preparation and specialised statistical environments.

##### 1. Theoretical Background

Spatial-statistical workflows in urban planning seldom end in QGIS. Researchers routinely export attribute tables to R (for `spdep`, `spatialreg`), Stata (for `spreg`), or Python/pandas (for `pysal`) to access tests and diagnostics exceeding what any single GIS plugin can provide. The Export Attributes tool provides a lossless bridge between QGIS's internal attribute representation and the delimited-text format — the lingua franca of statistical computing.

The tool's design follows three principles from reproducible-research literature (Sandve et al., 2013; Wilson et al., 2014): (a) explicit encoding — output is always UTF-8 with a header row, delimiter chosen by the analyst; (b) NULL transparency — QGIS NULL, Python None, and string "NULL" all export as empty fields (consecutive delimiters, the CSV missing-value standard); (c) coordinate provenance — geometry coordinates from feature centroids (via `geometry_centroid_point`), not raw vertices. The output is deliberately minimal — one header row, one data row per feature — compatible with any statistical software.

##### 2. Mathematical Formulation

$$ F_{\text{export}} = \begin{cases} F_{\text{selected}}, & |F_{\text{selected}}| > 0 \\ F_{\text{all}}, & \text{otherwise} \end{cases} \tag{1} $$ $$ \delta(d) \in \{\text{","}, \text{"\t"}, \text{";"}, \text{" "}\}, \quad d \in \{0,1,2,3\} \tag{2} $$ $$ (x_i, y_i) = \begin{cases} (\text{centroid}_x(g_i), \text{centroid}_y(g_i)), & g_i \neq \emptyset \land \text{coords} \\ (\emptyset, \emptyset), & \text{otherwise} \end{cases} \tag{3} $$ $$ v_{ij} = \begin{cases} \text{str}(\text{attr}_j(f_i)), & \text{attr not NULL} \\ \text{""}, & \text{otherwise} \end{cases} \tag{4} $$ $$ H = \begin{cases} [\text{"X\_COORD", "Y\_COORD"}] \oplus F_{\text{export}}, & \text{coords} \\ F_{\text{export}}, & \text{otherwise} \end{cases} \tag{5} $$ $$ R_i = \begin{cases} [x_i, y_i] \oplus [v_{i1},\dots,v_{im}], & \text{coords} \\ [v_{i1},\dots,v_{im}], & \text{otherwise} \end{cases} \tag{6} $$ $$ \text{export} = \text{join}(H, \delta) + \text{"\textbackslash n"} + \sum_{i=1}^{N} \text{join}(R_i, \delta) + \text{"\textbackslash n"} \tag{7} $$ Written via Python's `csv.writer` with UTF-8 encoding and `newline=''` (universal newline mode).

##### 3. Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Layer whose attributes are exported
FIELDS | Field (multi, optional) | all fields | Fields to include in the export; if blank, all fields exported
DELIMITER | Enum | Comma (0) | Comma (0), Tab (1), Semicolon (2), or Space (3)
INCLUDE_COORDS | Boolean | true | Prepend centroid X_COORD and Y_COORD columns
OUTPUT_FILE | File | — | Output delimited text file path (required)

##### 4. Output Description

Column / Aspect | Type | Description
--- | --- | ---
X_COORD | Float (string) | Centroid X coordinate in layer CRS units (present if INCLUDE_COORDS = true)
Y_COORD | Float (string) | Centroid Y coordinate in layer CRS units
[field_1] ... [field_m] | String | Attribute values as strings; NULL values represented as empty (consecutive delimiters)
Header row | String (first line) | Column names as they appear in the QGIS attribute table
Encoding | UTF-8 | Always UTF-8; no BOM prepended
Line endings | Platform default | Python `csv.writer` with `newline=''`; CRLF on Windows, LF on Linux/macOS

##### 5. Interpretation Guide

Delimiter selection. Comma is the default and most widely supported. Use Tab when field values contain commas (address strings, description fields). Use Semicolon for European-locale spreadsheet compatibility (comma as decimal separator). Avoid Space when any field value contains internal spaces — space-delimited files are ambiguous.
Coordinate columns for R/spdep. Include X_COORD and Y_COORD when exporting for R's `spdep`. These can be used directly to construct spatial weights via `knearneigh(cbind(data$X_COORD, data$Y_COORD), k = 5)`, preserving spatial structure. Always verify the CRS is projected before using these coordinates for distance calculations in R.
NULL handling in downstream tools. The empty-string convention is unambiguous in CSV. R: `read.csv("file.csv", na.strings = c("", "NA"))`. Python/pandas: `pd.read_csv("file.csv", na_values = [""])`. Stata: `import delimited "file.csv", stringcols(_all)` then `destring`.

##### 6. Literature

Sandve, G.K., Nekrutenko, A., Taylor, J. & Hovig, E. (2013). "Ten Simple Rules for Reproducible Computational Research." PLoS Computational Biology 9(10): e1003285. DOI: 10.1371/journal.pcbi.1003285 — Rule 6 ("Use Version Control for All Data for Small to Moderate Size Data") — the export is a versionable snapshot.

Wilson, G., Aruliah, D.A., Brown, C.T., et al. (2014). "Best Practices for Scientific Computing." PLoS Biology 12(1): e1001745. DOI: 10.1371/journal.pbio.1001745 — Best practice #3 ("Make Data Findable and Accessible") — the exported CSV is the accessible form.

Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, Springer, 175–193. DOI: 10.1007/978-3-642-03647-7_11 — PySAL's file I/O conventions that the export format is compatible with.

Bivand, R.S., Pebesma, E. & Gómez-Rubio, V. (2013). Applied Spatial Data Analysis with R (2nd ed.). Springer. — The canonical reference for R-based spatial analysis; exported CSV is the primary input format.

Anselin, L. (2005). Exploring Spatial Data with GeoDa: A Workbook. CSISS, UIUC. — GeoDa's CSV-based workflow that the export tool mirrors.

McKinney, W. (2010). "Data Structures for Statistical Computing in Python." Proc. 9th Python in Science Conf. (SciPy 2010), 51–56. DOI: 10.25080/Majora-92bf1922-00a — Introduces pandas `read_csv`; the exported file is a direct input to pandas workflows.

Peng, R.D. (2011). "Reproducible Research in Computational Science." Science 334(6060): 1226–1227. DOI: 10.1126/science.1213847 — The exported CSV as a reproducible research artefact.

Millman, K.J. & Aivazis, M. (2011). "Python for Scientists and Engineers." Computing in Science & Engineering 13(2): 9–12. DOI: 10.1109/MCSE.2011.36 — Python CSV I/O conventions used by the export engine.

Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22. DOI: 10.1111/j.0016-7363.2005.00671.x — Data export as a standard step in the spatial analytical workflow.

Wickham, H. (2014). "Tidy Data." Journal of Statistical Software 59(10): 1–23. DOI: 10.18637/jss.v059.i10 — The tidy-data framework: one row per observation, one column per variable — the format the export tool produces.

02

### Urban Pattern Scan

Global spatial statistics that characterize the overall structure of a spatial variable. These are screening tools — they answer "is there a pattern worth investigating?" before local tools answer "where is it?" Each tool in this group tests a different aspect of spatial structure: autocorrelation (Moran's I, Geary's C), inequality decomposition (Spatial Gini), high/low clustering (General G), scale-dependence (Incremental Autocorrelation), point-process intensity (Ripley's K), first-order dispersion (Nearest Neighbor), categorical/binary clustering (Join Count Statistics), spatial co-clustering between two fields (Global Bivariate Lee's L), and spatial stratified heterogeneity from a categorical partition (Geodetector Q-statistic).

🌐

#### Spatial Autocorrelation (Global Moran's I)

global_moran_autocorrelation
The foundational screening statistic in spatial analysis. Global Moran's I evaluates whether similar values tend to occur near each other (clustered), whether dissimilar values are adjacent (dispersed), or whether the spatial arrangement is indistinguishable from random. As the single most cited spatial diagnostic in geography and planning, it serves as the gateway test: a significant global result justifies local analysis (LISA, Gi*) to locate the pattern, while a non-significant result counsels caution before committing to spatial models. Produces an HTML diagnostic report with the I statistic, expected value under spatial randomness, variance, z-score, p-value, and a plain-language interpretation.

##### 1. Theoretical Background

Origins. Patrick Alfred Pierce Moran introduced his eponymous I statistic in a 1950 Biometrika note on continuous stochastic phenomena, building on earlier work by Student (1914) and by Yule (1926) on serial correlation in time series. Moran's key insight was to transpose the time-series concept of autocorrelation into a spatial domain by replacing temporal lags with a spatial weights matrix W — a device that encodes which observational units are "neighbors." This single conceptual leap — that nearness in space is analogous to priorness in time, but with the critical difference that space is two-directional while time is one-directional — opened the door to a century of spatial econometric methods.

Evolution. Cliff and Ord (1973, 1981) provided the definitive inferential framework, deriving the first two moments of I under both the normality and randomization assumptions and establishing the asymptotic normality of the standardized statistic. Their 1981 monograph Spatial Processes: Models & Applications remains the canonical reference. Anselin (1988, 1995) extended the framework to local indicators (LISA), while Tiefelsdorf and Boots (1995) derived the exact finite-sample distribution. Goodchild (1986) produced an accessible monograph that brought these methods into the GIS community's toolkit. The statistic is now implemented in every major spatial analysis platform: GeoDa, PySAL, ArcGIS, R/spdep, and — through this plugin — QGIS Processing.

Null hypothesis. The null hypothesis of Moran's I is Complete Spatial Randomness (CSR): the observed spatial arrangement of a variable is one of the N! equally likely permutations of values across fixed locations. Under normality, values are assumed to be independent draws from a normal distribution. Under the randomization assumption — the more common and defensible choice — the observed values are treated as fixed and randomized across spatial locations without distributional assumptions about the values themselves. The Plugin uses the randomization assumption throughout.

Limitations. Moran's I is a global statistic: it returns one number for the entire study area. It cannot identify where clustering occurs, cannot distinguish between a single large cluster and several small ones, and is insensitive to local pockets of autocorrelation that cancel out at the global level. The statistic is also sensitive to the choice of spatial weights: a different W matrix can yield a different conclusion. Analysts should therefore treat Moran's I as a screening diagnostic, not as the final word on spatial structure.

##### 2. Mathematical Formulation

ThePlugin implements the randomization-assumption formulation of Cliff & Ord (1981). Let N be the number of spatial units, yi the observed value at location i, and W = [wij] the row-standardized spatial weights matrix.

Global Moran's I statistic:

$$I = \frac{N}{S_0} \cdot \frac{\sum_{i=1}^{N}\sum_{j=1}^{N} w_{ij} (y_i - \bar{y})(y_j - \bar{y})}{\sum_{i=1}^{N} (y_i - \bar{y})^2} \tag{1}$$

where \(S_0 = \sum_i \sum_j w_{ij}\) (the sum of all weights; equals N for row-standardized weights) and \(\bar{y} = \frac{1}{N}\sum_i y_i\).

Expected value under randomization:

$$\mathbb{E}[I] = -\frac{1}{N - 1} \tag{2}$$

The expected value is always negative and approaches zero as N increases. A positive I exceeding this negative expectation indicates spatial clustering; an I below it indicates dispersion.

Variance under randomization — Cliff & Ord formulation:

Define the following auxiliary quantities from the weights matrix:

$$S_1 = \frac{1}{2}\sum_{i=1}^{N}\sum_{j=1}^{N} (w_{ij} + w_{ji})^2 \tag{3}$$ $$S_2 = \sum_{i=1}^{N} (w_{i\cdot} + w_{\cdot i})^2 \tag{4}$$

where \(w_{i\cdot} = \sum_j w_{ij}\) (row sums) and \(w_{\cdot i} = \sum_j w_{ji}\) (column sums). Next, compute the kurtosis coefficient:

$$D = \frac{N \sum_{i=1}^{N} (y_i - \bar{y})^4}{\left[\sum_{i=1}^{N} (y_i - \bar{y})^2\right]^2} \tag{5}$$

The randomization variance is then:

$$\operatorname{Var}(I) = \frac{N\left[(N^2 - 3N + 3)S_1 - NS_2 + 3S_0^2\right] - D\left[(N^2 - N)S_1 - 2NS_2 + 6S_0^2\right]}{(N - 1)(N - 2)(N - 3)S_0^2} - \left(\mathbb{E}[I]\right)^2 \tag{6}$$

Standardized Moran's I (z-score):

$$z_I = \frac{I - \mathbb{E}[I]}{\sqrt{\operatorname{Var}(I)}} \tag{7}$$

Under the null hypothesis of no spatial autocorrelation, \(z_I\) is asymptotically distributed as a standard normal \(\mathcal{N}(0, 1)\).

Two-tailed p-value (via error function):

$$p = 2\left[1 - \Phi(|z_I|)\right] = 2\left[1 - \frac{1}{2}\left(1 + \operatorname{erf}\left(\frac{|z_I|}{\sqrt{2}}\right)\right)\right] \tag{8}$$

where \(\Phi(\cdot)\) is the standard normal CDF and \(\operatorname{erf}(\cdot)\) is the Gauss error function (the numerical path used in the engine).

Implementation note. The Plugin engine (see `stats_engines.py` lines 485–578) computes these quantities in two passes: first to build S0, row/column sums (wi·, w·i); second to accumulate S1 and cross-products. The weighted numerator \(\sum_i \sum_j w_{ij}(y_i - \bar{y})(y_j - \bar{y})\) is computed via explicit double summation with feature-ID-to-index mapping, not via dense matrix multiplication — this preserves correctness for large sparse W matrices and avoids storing the full N×N matrix.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer (polygon, point, or line; centroids used for distance-based weights)
FIELD | Numeric Field | — | Must be numeric | Target variable to test for spatial autocorrelation
WEIGHT_TYPE | Enum | Queen | Queen / Rook / KNN / DistBand | Spatial relationship definition (see Methodological Notes for guidance)
KNN | Integer | 5 | ≥ 1 | Number of nearest neighbors (active only for KNN weight type)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (active only for Distance Band weight type)
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report with all statistics and interpretation

##### 4. Output Description

The HTML report contains the following diagnostic fields:

Field | Type | Description
--- | --- | ---
moran_i | Double | Observed Global Moran's I statistic (range approximately −1 to +1 for row-standardized weights)
expected_i | Double | Expected value under CSR randomization: E[I] = −1/(N−1)
variance | Double | Variance of I under randomization (Cliff & Ord formulation)
z_score | Double | Standardized z-score: (I − E[I]) / √Var(I)
p_value | Double | Two-tailed asymptotic p-value (normal approximation)
pattern | String | Plain-language pattern classification (Clustered / Dispersed / Random)
confidence | String | Evidence strength: Strong (p < 0.01), Moderate (0.01 ≤ p < 0.05), or Weak (p ≥ 0.05)
next_action | String | Recommended follow-up analysis based on the result and neighborhood diagnostics

Additional diagnostic sections in the report:

- Numeric quality summary — valid/total records, missing count, min/max/mean/std, skewness, constant-value flag
- Neighborhood summary — min/median/max neighbors per feature, isolated features count, fully-connected flag
- CRS warning — alerts if a geographic CRS is used with distance-based weights
- Analyst guidance — assumptions checklist, common pitfalls, recommended companion tools

##### 5. Interpretation Guide

z-score benchmarks (two-tailed, α = 0.05).

Condition | z-score Range | Pattern | Implication
--- | --- | --- | ---
I > E[I], |z| ≥ 1.96 | z ≥ +1.96 | Clustered (positive autocorrelation) | Similar values are spatially adjacent more than expected by chance. Run LISA or Gi* to locate clusters.
I > E[I], |z| ≥ 2.58 | z ≥ +2.58 | Strongly Clustered | High-confidence spatial clustering (α = 0.01). Merits immediate local analysis.
I < E[I], |z| ≥ 1.96 | z ≤ −1.96 | Dispersed (negative autocorrelation) | Dissimilar values are adjacent — possible competition, repulsion, or checkered administrative patterns.
I < E[I], |z| ≥ 2.58 | z ≤ −2.58 | Strongly Dispersed | Rare in planning data; check for zoning alternation, systematic sampling, or data-coding artifacts.
|z| < 1.96 | −1.96 < z < +1.96 | Not distinguishable from CSR | No global spatial signal detected at the chosen neighborhood scale. Try other weight types or distances before concluding.

Scale sensitivity. Moran's I is inherently scale-dependent. The same variable may appear clustered at one neighborhood definition and random at another. Always report the weight type and parameters alongside the I statistic. For distance-based weights, use Incremental Spatial Autocorrelation (this group) to identify the peak clustering distance before fixing a threshold.

What Moran's I tests — and what it does not. The statistic tests whether a global spatial pattern exists; it does not reveal where it occurs, what kind of clustering (high-high, low-low, or both), or why the pattern arises. Significant positive I may reflect a genuine spatial process (diffusion, spillover, common-environment response) or an omitted variable that is itself spatially structured. Pair Moran's I with local diagnostics (LISA, Gi*) for location, and with regression diagnostics (OLS residual I) for causal screening.

Neighborhood diagnostics. The report flags two critical conditions: (1) isolated features — features with zero neighbors, which contribute nothing to the global statistic and effectively shrink the sample; (2) fully connected graph — when every feature is a neighbor of every other, I approaches 0 and the statistic loses discriminatory power. Both conditions indicate an inappropriate weight specification for the data geometry.

See also: Incremental Autocorrelation · Spatial Gini · Getis-Ord Gi* · Local Moran's I (LISA)

##### 6. Literature

Moran, P.A.P. (1950). "Notes on Continuous Stochastic Phenomena." Biometrika 37(1/2): 17–23. DOI: 10.1093/biomet/37.1-2.17 — The origin paper. Introduces the I statistic as a spatial analogue of serial correlation.

Cliff, A.D. & Ord, J.K. (1973). Spatial Autocorrelation. London: Pion. ISBN: 978-0850860368 — First book-length treatment; derives moments of I under both normality and randomization.

Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. London: Pion. ISBN: 978-0850860818 — The canonical reference; provides the variance formula used in this plugin (Eq. 6 above).

Anselin, L. (1988). Spatial Econometrics: Methods and Models. Dordrecht: Kluwer. ISBN: 978-9024737352 — Extends Moran's I into the regression context; introduces spatial lag and error models.

Goodchild, M.F. (1986). Spatial Autocorrelation. CATMOG 47. Norwich: Geo Books. ISBN: 978-0860942238 — Accessible introduction for quantitative geographers and GIS practitioners.

Tiefelsdorf, M. & Boots, B. (1995). "The Exact Distribution of Moran's I." Environment and Planning A 27(6): 985–999. DOI: 10.1068/a270985 — Derives exact finite-sample distribution; shows when normal approximation is reliable.

Getis, A. (2008). "A History of the Concept of Spatial Autocorrelation: A Geographer's Perspective." Geographical Analysis 40(3): 297–309. DOI: 10.1111/j.1538-4632.2008.00727.x — Historical review tracing the idea from Yule through Moran to modern GIS.

Legendre, P. (1993). "Spatial Autocorrelation: Trouble or New Paradigm?" Ecology 74(6): 1659–1673. DOI: 10.2307/1939924 — Influential methodological review; frames autocorrelation as signal rather than nuisance.

Bivand, R.S., Pebesma, E. & Gómez-Rubio, V. (2013). Applied Spatial Data Analysis with R (2nd ed.). Springer. DOI: 10.1007/978-1-4614-7618-4 — Practical implementation reference; the `spdep` package's Moran's I follows the same Cliff–Ord formulation.

Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In M.M. Fischer & A. Getis (eds.), Handbook of Applied Spatial Analysis, pp. 175–193. Springer. DOI: 10.1007/978-3-642-03647-7_11 — Documents the open-source implementation lineage; PySAL's `esda.Moran` is the reference implementation.

Sokal, R.R. & Oden, N.L. (1978). "Spatial Autocorrelation in Biology. 1. Methodology." Biological Journal of the Linnean Society 10(2): 199–228. DOI: 10.1111/j.1095-8312.1978.tb00013.x — Early cross-disciplinary adoption; established Moran's I as a general scientific method beyond geography.

Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22. DOI: 10.1111/j.0016-7363.2005.00671.x — Documents the GeoDa workbook approach; the diagnostic-first philosophy adopted by this plugin.

⚖️

#### Spatial Inequality (Gini and Spatial Gini)PERMUTATION (OPT.)

spatial_gini_inequality
Decomposes the classic Gini coefficient of inequality into neighbor and non-neighbor pair contributions following the Rey & Smith (2013) spatial Gini framework. The classic Gini — conceived by Corrado Gini in 1912 — measures inequality as the average absolute difference between all pairs of observations, normalized by twice the mean. The spatial decomposition answers a question the classic Gini cannot: is observed inequality spatially organized, or is it randomly distributed across the landscape? Includes permutation inference for the non-neighbor component, spatial polarization (ratio of distant-pair to neighbor-pair mean differences), and multi-format export (HTML report, CSV summary, JSON machine-readable output).

##### 1. Theoretical Background

Origins. Corrado Gini (1912, published in Italian as Variabilità e Mutabilità) proposed the concentration ratio that now bears his name as a measure of statistical dispersion for non-negative quantities. The coefficient ranges from 0 (perfect equality: every unit has the same value) to 1 (perfect inequality: one unit holds all the value). Its geometric interpretation — twice the area between the Lorenz curve and the 45-degree line of perfect equality — made it the dominant inequality metric in economics, and it later spread to public health (income-related health inequality), ecology (species-abundance distributions), and urban planning (spatial concentration of resources, burdens, and access).

Spatial decomposition. Rey and Smith (2013) introduced the spatial Gini decomposition to address a specific limitation: the classic Gini treats all pairwise differences identically, regardless of whether two observations are geographic neighbors or far apart. Their innovation was to partition the Gini numerator — the sum of absolute pairwise differences — into neighbor pairs (connected by the spatial weights matrix W) and non-neighbor pairs (not connected). Both components are normalized by the same denominator as the classic Gini, so they partition the total inequality: G = Gneighbor + Gnon-neighbor. The spatial Gini share — the fraction of total inequality carried by non-neighbor pairs — reveals the spatial structure of inequality. If most inequality arises between distant places, inequality follows regional gradients; if most arises between neighbors, inequality is locally concentrated and potentially addressable through local interventions.

Related measures. Dawkins (2003) proposed a spatial Gini variant for measuring urban sprawl. Arbia and Piras (2009) developed spatial decompositions of inequality indices using spatial filtering. The Rey-Smith approach used here has the advantage of being a direct decomposition of the classic Gini — it does not require spatial filtering or pre-modeling — and the components sum exactly to the classic Gini, making it straightforward to communicate to non-specialist audiences.

Non-negativity constraint. The Gini coefficient is mathematically undefined for variables with negative values (the denominator \(2N^2\mu\) becomes zero when \(\mu = 0\)) and produces counterintuitive results for variables that span zero. The plugin enforces this constraint at input validation: negative values are flagged and the analysis is refused. For variables like net migration rates, standardized residuals, or growth rates — which can be negative — consider Global Moran's I or variance decomposition instead.

##### 2. Mathematical Formulation

The Plugin implements the Rey-Smith pairwise decomposition. Let N be the number of spatial units and \(y_i \ge 0\) the non-negative value at location i, with \(\bar{y} = \frac{1}{N}\sum_i y_i\).

Classic Gini coefficient (pairwise absolute-difference formulation):

$$G = \frac{1}{2N^2 \bar{y}} \sum_{i=1}^{N}\sum_{j=1}^{N} |y_i - y_j| \tag{1}$$

This is the computational form used in the engine (see Kendall & Stuart, 1977, for equivalence to the Lorenz-curve definition).

Pair classification. Define a pair \((i, j)\) as neighbor if \(w_{ij} > 0\) in the spatial weights matrix, and non-neighbor otherwise. Let \(\mathcal{P}_N\) be the set of neighbor pairs and \(\mathcal{P}_{\bar{N}}\) the set of non-neighbor pairs. Since both sets partition the complete set of \(\binom{N}{2}\) unordered pairs, we have:

$$|\mathcal{P}_N| + |\mathcal{P}_{\bar{N}}| = \binom{N}{2} \tag{2}$$

Pairwise sum decomposition:

$$T = \sum_{(i,j) \in \mathcal{P}_N} |y_i - y_j| + \sum_{(i,j) \in \mathcal{P}_{\bar{N}}} |y_i - y_j| = T_N + T_{\bar{N}} \tag{3}$$

Gini component decomposition (using common denominator):

$$G_N = \frac{T_N}{2N^2 \bar{y}}, \quad G_{\bar{N}} = \frac{T_{\bar{N}}}{2N^2 \bar{y}}, \quad G = G_N + G_{\bar{N}} \tag{4}$$

Spatial Gini share (non-neighbor fraction):

$$S_{\text{spatial}} = \frac{G_{\bar{N}}}{G} = \frac{T_{\bar{N}}}{T} \tag{5}$$

When \(S_{\text{spatial}} > 0.5\), most inequality is carried by pairs that are not neighbors — inequality is spatially structured at a scale larger than the defined neighborhood.

Spatial polarization:

$$P = \frac{\bar{\Delta}_{\bar{N}}}{\bar{\Delta}_N} = \frac{T_{\bar{N}} / |\mathcal{P}_{\bar{N}}|}{T_N / |\mathcal{P}_N|} \tag{6}$$

Values \(P > 1\) indicate that distant pairs differ more than neighboring pairs on average; \(P < 1\) suggests local contrast effects where neighbors differ more sharply than distant places.

Implementation note. The engine (see `stats_engines.py` lines 581–696) enumerates all \(\binom{N}{2}\) unordered pairs through nested loops over the feature index array. For each pair, the absolute difference \(|y_i - y_j|\) is computed once and routed to either the neighbor or non-neighbor accumulator based on a pre-built Boolean mask derived from the spatial weights. This avoids storing the full pair-difference matrix. Permutation inference (when requested) shuffles \(y\) values while holding the pair classification fixed, generating a reference distribution for the non-neighbor share and polarization under spatial randomness.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
FIELD | Numeric Field | — | Must be non-negative | Inequality indicator (income, exposure, accessibility, burden, rate)
WEIGHT_TYPE | Enum | KNN | Queen / Rook / KNN / DistBand | Spatial neighbor definition (KNN recommended when feature sizes vary)
KNN | Integer | 8 | ≥ 1 | Number of nearest neighbors (active only for KNN weight type)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (active only for Distance Band weight type)
PERMUTATIONS | Integer | 99 | 0–9999 | Number of random permutations for empirical inference (0 = skip)
RANDOM_SEED | Integer | 42 | ≥ 0 | Seed for reproducible permutation results
HTML_REPORT | File (HTML) | — | Optional path | Output interactive inequality report with all decomposition metrics
SUMMARY_CSV | File (CSV) | — | Optional path | Structured CSV with one row of all decomposition fields
SUMMARY_JSON | File (JSON) | — | Optional path | Machine-readable JSON with schema versioning

##### 4. Output Description

The report and exports contain the following fields (all available in CSV/JSON; key fields shown in HTML report):

Field | Type | Description
--- | --- | ---
gini | Double | Classic Gini coefficient (0 = equality, 1 = maximum inequality)
neighbor_component | Double | Gini contribution from neighbor pairs: \(G_N\) (sums to Gini with non-neighbor component)
non_neighbor_component | Double | Gini contribution from non-neighbor pairs: \(G_{\bar{N}}\)
spatial_gini | Double | Spatial Gini share = non-neighbor component / Gini (larger → more regionally structured inequality)
neighbor_share | Double | Fraction of total inequality from neighbor pairs = \(T_N / T\)
non_neighbor_share | Double | Fraction from non-neighbor pairs (same as spatial_gini)
polarization | Double | Spatial polarization ratio (Eq. 6); > 1 → distant pairs differ more
neighbor_pair_count | Integer | Number of unordered neighbor pairs: \(|\mathcal{P}_N|\)
non_neighbor_pair_count | Integer | Number of unordered non-neighbor pairs: \(|\mathcal{P}_{\bar{N}}|\)
neighbor_avg_diff | Double | Average absolute difference among neighbor pairs
non_neighbor_avg_diff | Double | Average absolute difference among non-neighbor pairs
expected_non_neighbor_component | Double | Mean non-neighbor component under permutation (null expectation)
z_non_neighbor_component | Double | z-score of observed non-neighbor component against permutation distribution
p_sim | Double | One-tailed pseudo-p-value: P(permuted ≥ observed non-neighbor share)
polarization_p_sim | Double | Pseudo-p-value for spatial polarization against permutation null

##### 5. Interpretation Guide

Decision matrix for spatial inequality interpretation.

Spatial Gini Share | Polarization | Pattern Description | Planning Implication
--- | --- | --- | ---
\(S \gt 0.5\) | \(P \gt 1.0\) | Regionally structured inequality | Inequality follows macro-regional gradients (e.g., east–west, urban–rural). Policy interventions need to operate at the regional scale.
\(S \gt 0.5\) | \(P \approx 1.0\) | Broad-scale inequality without local contrast | Places are similar to their neighbors but different from distant places — smooth gradients rather than sharp boundaries.
\(S \lt 0.5\) | \(P \gt 1.0\) | Local equality, distant inequality | Neighbors are similar; the inequality is between neighborhoods — spatial sorting or segregation pattern.
\(S \lt 0.5\) | \(P \lt 1.0\) | Local contrast, distant similarity | Sharp boundaries between dissimilar neighbors; checkered pattern. May indicate zoning, administrative boundaries, or data artifacts.
\(S \approx 0.5\) | \(P \approx 1.0\) | Spatially neutral inequality | Inequality is not spatially structured at the chosen neighborhood scale; no spatial gradient or boundary effect detected.

Permutation inference. When permutations are requested (PERMUTATIONS > 0), the engine randomly shuffles the observed values across spatial locations while holding the spatial configuration fixed. This generates an empirical null distribution of the non-neighbor component and the polarization ratio under the hypothesis that inequality is randomly distributed with respect to space. A significant p_sim (< 0.05) indicates that the observed spatial structure of inequality is unlikely to arise by chance. Note that permutation tests are computationally intensive — 999 permutations balances precision and runtime for datasets of a few hundred features.

Scale dependency. The spatial Gini share depends on the definition of "neighbor." What appears spatially structured at a KNN-8 neighborhood scale may appear neutral at KNN-24. Report the weight definition alongside the share, and consider testing multiple neighborhood sizes to verify that the conclusion is robust. The default K = 8 is a reasonable starting point for most planning datasets, adapted from the PySAL spatial Gini defaults.

Application domains. The spatial Gini is designed for non-negative planning indicators: household income, property values, environmental hazard exposure indices, accessibility scores, service-provision rates, population density, and tax-base per capita. It is not suitable for variables that span zero (net migration rate, standardized residuals, growth rates) or for ordinal/categorical variables. For binary variables (presence/absence), consider the spatial segregation indices (e.g., dissimilarity index with spatial decomposition) instead.

See also: Global Moran's I · Getis-Ord Gi* · Local Moran's I (LISA)

##### 6. Literature

Gini, C. (1912). Variabilità e Mutabilità: Contributo allo Studio delle Distribuzioni e delle Relazioni Statistiche. Bologna: Cuppini. — The foundational work introducing the concentration ratio (now the Gini coefficient). Original publication in Italian.

Rey, S.J. & Smith, R.J. (2013). "A Spatial Decomposition of the Gini Coefficient." Letters in Spatial and Resource Sciences 6(2): 55–70. DOI: 10.1007/s12076-012-0086-z — The primary methodological reference; introduces the neighbor/non-neighbor decomposition used in this plugin.

Kendall, M.G. & Stuart, A. (1977). The Advanced Theory of Statistics, Vol. 1: Distribution Theory (4th ed.). London: Griffin. ISBN: 978-0852641415 — Definitive reference establishing the equivalence of the pairwise-difference and Lorenz-curve definitions of Gini.

Sen, A. (1997). On Economic Inequality (expanded ed. with J.E. Foster). Oxford: Clarendon Press. ISBN: 978-0198281931 — Classic treatment of inequality measurement; provides the axiomatic foundation for the Gini coefficient.

Atkinson, A.B. (1970). "On the Measurement of Inequality." Journal of Economic Theory 2(3): 244–263. DOI: 10.1016/0022-0531(70)90039-6 — Introduces the Atkinson index class; provides the welfare-theoretic critique that motivates comparing Gini to alternative measures.

Dawkins, C.J. (2003). "Measuring the Spatial Pattern of Residential Segregation." Urban Studies 40(4): 833–851. DOI: 10.1080/0042098032000065232 — Early application of spatial Gini concepts to urban form and residential segregation measurement.

Arbia, G. & Piras, G. (2009). "A New Class of Spatial Concentration Measures." Computational Statistics & Data Analysis 53(12): 4143–4153. DOI: 10.1016/j.csda.2009.04.013 — Develops spatial filtering approach to inequality decomposition; complementary method to the pairwise approach.

Deaton, A. (1997). The Analysis of Household Surveys: A Microeconometric Approach to Development Policy. Baltimore: Johns Hopkins University Press. ISBN: 978-0801852541 — Practical reference for computing and interpreting inequality measures from survey data; chapters 3–4 cover Gini and Lorenz curves.

Rey, S.J. (2009). "Show Me the Code: Spatial Analysis and Open Source." Journal of Geographical Systems 11(2): 191–207. DOI: 10.1007/s10109-009-0083-y — Argues for transparent implementation of spatial inequality measures; the open-source philosophy adopted by this plugin.

Tsui, K.-Y. (1999). "Multidimensional Inequality and Multidimensional Generalized Entropy Measures: An Axiomatic Derivation." Social Choice and Welfare 16(1): 145–157. DOI: 10.1007/s003550050135 — Extends inequality measurement to multiple dimensions; relevant when the planning question involves trade-offs across multiple inequality indicators.

Firebaugh, G. (1999). "Empirics of World Income Inequality." American Journal of Sociology 104(6): 1597–1630. DOI: 10.1086/210218 — Decomposes global income inequality into within-country and between-country components; the conceptual analogue of the neighbor/non-neighbor decomposition at the international scale.

World Bank. (2005). World Development Report 2006: Equity and Development. Washington, DC: World Bank. DOI: 10.1596/978-0-8213-6249-5 — Policy-focused treatment of spatial inequality; chapters 2 and 7 discuss spatial dimensions of equity in development planning.

🔺

#### High/Low Clustering (Getis-Ord General G)

general_g_autocorrelation
The Getis-Ord General G statistic tests whether high values (or low values) are more spatially clustered than expected under random allocation. Unlike Moran's I — which captures both high-high and low-low clustering — General G distinguishes between clusters of high values and clusters of low values. Essential when the analyst's question is directional: "are wealthy neighborhoods clustered together?" rather than "is there any clustering at all?" Produces an HTML diagnostic report with observed G, expected G under CSR, variance, z-score, p-value, and a directional interpretation of the clustering result.

##### 1. Theoretical Background

Origins. Arthur Getis and J. Keith Ord introduced the General G statistic in their landmark 1992 paper in Geographical Analysis. Their key insight was that Moran's I, while powerful for detecting any spatial autocorrelation, cannot distinguish between clusters of high values (hot spots) and clusters of low values (cold spots). Both produce positive I values. The General G was the first global statistic to provide a directional test: if high values are spatially clustered, the observed G exceeds its expectation; if low values are clustered, G falls below expectation. This makes it directly relevant to planning questions about the spatial organization of magnitudes.

Evolution to local form. Getis and Ord (1992) presented both the global General G and the local \(G_i\) statistic in the same paper. The local \(G_i^*\) — which tests whether a single location and its neighbors collectively constitute a hot or cold spot — was refined in Ord and Getis (1995) and has since become one of the most widely used local spatial statistics in GIScience. The global G and local Gi* together form a coherent analytical framework: test the global directional tendency first, then map the local concentrations if significant.

Positivity requirement. The General G statistic is defined as a ratio of weighted cross-products of values. Because the cross-product \(x_i x_j\) appears in both numerator and denominator, the statistic requires all values to be non-negative (strictly positive for the statistic to be well-defined). A single negative value, even if legitimate (e.g., a negative population growth rate), can undermine the interpretation. The plugin enforces this constraint at input validation.

Relationship to Moran's I. Moran's I and General G test different null hypotheses. Moran's I tests for any spatial autocorrelation in the deviation-from-mean (centered) values. General G tests for clustering of the raw (uncentered) values. The two statistics can yield different conclusions for the same dataset: a variable with a strong urban–rural gradient (high values in the urban core, low values in the periphery) will produce a large positive Moran's I and a large positive General G. A variable with a checkerboard pattern (alternating high and low) may produce a negative Moran's I but an unremarkable General G. Understanding which null hypothesis is more relevant to the planning question is crucial for correct interpretation.

##### 2. Mathematical Formulation

The Plugin implements the randomization-assumption inference for the Getis-Ord General G using binary distance-band weights. Let N be the number of features, \(x_i \ge 0\) the non-negative value at location i, and W = \([w_{ij}]\) a symmetric binary spatial weights matrix with \(w_{ii} = 0\).

Observed General G statistic:

$$G(d) = \frac{\sum_{i=1}^{N}\sum_{j \neq i}^{N} w_{ij}(d) \; x_i x_j}{\sum_{i=1}^{N}\sum_{j \neq i}^{N} x_i x_j} \tag{1}$$

where \(w_{ij}(d) = 1\) if the distance between i and j is \(\le d\) (and 0 otherwise), and \(w_{ii} = 0\). The statistic captures the fraction of all cross-products that occur between neighboring pairs.

Expected value under randomization:

$$\mathbb{E}[G] = \frac{S_0}{N(N-1)} \tag{2}$$

where \(S_0 = \sum_i \sum_j w_{ij}\) is twice the number of neighbor pairs.

Auxiliary weight-matrix quantities:

$$A_1 = \sum_{i}\sum_{j} w_{ij}^2, \quad A_2 = \sum_{i}\sum_{j} w_{ij} w_{ji} \tag{3}$$ $$A_3 = \sum_i \left(\sum_j w_{ij}\right)^2 + \sum_j \left(\sum_i w_{ij}\right)^2 \tag{4}$$ $$A_4 = \sum_i \left(\sum_j w_{ij}\right)\left(\sum_j w_{ji}\right), \quad A_5 = S_0^2 \tag{5}$$

For symmetric binary W, \(A_1 = A_2 = S_0\) and \(A_3 = 2 \sum_i (\text{rowsum}_i)^2\).

Raw-moment functions of the attribute values:

$$S_{m} = \sum_{i=1}^{N} x_i^{m}, \quad m \in \{1, 2, 3, 4\} \tag{6}$$

Higher-order permutation moments:

$$S_{22} = S_2^2 - S_4 \tag{7}$$ $$S_{211} = S_2(S_1^2 - S_2) - 2S_1 S_3 + 2S_4 \tag{8}$$ $$S_{1111} = S_1^4 - 6 S_1^2 S_2 + 8 S_1 S_3 + 3 S_2^2 - 6 S_4 \tag{9}$$

Second moment of G (variance denominator):

$$\mathbb{E}[G^2] = \frac{(A_1 + A_2)S_{22}}{N(N-1)} + \frac{(2A_3 + 4A_4 - 4A_1 - 4A_2)S_{211}}{N(N-1)(N-2)} + \frac{(A_5 - 2A_3 - 4A_4 + 3A_1 + 3A_2)S_{1111}}{N(N-1)(N-2)(N-3)} \tag{10}$$

Divided by \((\sum_i \sum_{j \neq i} x_i x_j)^2 = (S_1^2 - S_2)^2\) to yield \(\mathbb{E}[G^2]\) on the G scale.

Variance and z-score:

$$\operatorname{Var}(G) = \mathbb{E}[G^2] - \left(\mathbb{E}[G]\right)^2 \tag{11}$$ $$z_G = \frac{G - \mathbb{E}[G]}{\sqrt{\operatorname{Var}(G)}} \tag{12}$$

Two-tailed p-value:

$$p = 2\left[1 - \Phi(|z_G|)\right] \tag{13}$$
Implementation note. The engine (see `stats_engines.py` lines 1029–1112) constructs a dense N×N binary weight matrix from the distance-band threshold applied to centroid-to-centroid Euclidean distances. Higher-order attribute sums (\(S_2, S_3, S_4\)) are pre-computed, and the variance uses the exact permutation-moment formulation to avoid the distributional assumptions of the normal approximation for the numerator. For KNN or contiguity-based General G, use the weight-type parameter in the algorithm that constructs the weights matrix (notably the current implementation is distance-band only; for contiguity-based tests, consider the Global Moran tool instead).

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer (centroids used for distance computation)
FIELD | Numeric Field | — | Must be non-negative | Target variable for high/low clustering test
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units — the critical scale parameter
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report with all statistics and interpretation

##### 4. Output Description

Field | Type | Description
--- | --- | ---
observed_g | Double | Observed General G index: fraction of total cross-products from neighbor pairs
expected_g | Double | Expected G under CSR: \(S_0 / [N(N-1)]\)
variance | Double | Variance of G under randomization (exact permutation moments)
z_score | Double | Standardized z-score: \((G - \mathbb{E}[G]) / \sqrt{\operatorname{Var}(G)}\)
p_value | Double | Two-tailed asymptotic p-value (normal approximation)
pattern | String | Directional classification: Clustering of High / Low Values, or Random
next_action | String | Recommended follow-up analysis (e.g., Gi* hot spot mapping)

##### 5. Interpretation Guide

z-score benchmarks and directional interpretation.

Condition | Meaning | Directional Pattern | Recommended Next Step
--- | --- | --- | ---
z ≥ +1.96, p < 0.05 | Observed G significantly exceeds expectation | Clustering of HIGH values | Map with Gi* Hot Spot Analysis to locate the specific high-value concentrations.
z ≥ +2.58, p < 0.01 | Strongly significant high-value clustering | Strong HIGH clustering | High-confidence hot spot; prioritise for policy intervention.
z ≤ −1.96, p < 0.05 | Observed G significantly below expectation | Clustering of LOW values | Map with Gi* or LISA to identify cold-spot boundaries.
z ≤ −2.58, p < 0.01 | Strongly significant low-value clustering | Strong LOW clustering | Indicates concentrated deprivation, risk, or under-provision — merits equity review.
|z| < 1.96 | Cannot reject spatial randomness | No directional clustering detected | Check distance band (is it appropriate for the process?), test an alternative threshold.

Moran's I vs. General G — choosing the right tool. Moran's I answers "is there any spatial autocorrelation?" General G answers "are high values (or low values) clustered?" Use Moran's I when the question is about spatial dependence in general. Use General G when the question is about the spatial arrangement of magnitudes — e.g., "are high-pollution census tracts clustered together?", "are low-accessibility neighborhoods spatially concentrated?" Both statistics can and should be reported together: I may be significant while G is not (indicating spatial structure that involves both high and low values equally), or G may be significant with a non-significant I (rare, but possible when high values cluster without the low values showing a complementary structure).

Critical scale sensitivity. The General G is evaluated at a single distance band d. The result is conditional on this choice: a G that indicates high-value clustering at d = 1000 m may show no clustering at d = 500 m, and a fully-connected graph at d = 5000 m. The observed G approaches the expectation as d increases (more pairs become neighbors until every pair is a neighbor, and G converges to \(S_0 / [N(N-1)]\)). Always use Incremental Spatial Autocorrelation or Calculate Distance Band (Group 01) to determine an appropriate threshold before running General G.

See also: Getis-Ord Gi* · Global Moran's I

##### 6. Literature

Getis, A. & Ord, J.K. (1992). "The Analysis of Spatial Association by Use of Distance Statistics." Geographical Analysis 24(3): 189–206. DOI: 10.1111/j.1538-4632.1992.tb00261.x — The foundational paper; introduces both the global General G and the local \(G_i(d)\) statistic.

Ord, J.K. & Getis, A. (1995). "Local Spatial Autocorrelation Statistics: Distributional Issues and an Application." Geographical Analysis 27(4): 286–306. DOI: 10.1111/j.1538-4632.1995.tb00912.x — Refines the local \(G_i^*\) formulation and derives distributional properties; the source of the Gi* formula used in Group 03.

Getis, A. & Aldstadt, J. (2004). "Constructing the Spatial Weights Matrix Using a Local Statistic." Geographical Analysis 36(2): 90–104. DOI: 10.1111/j.1538-4632.2004.tb01127.x — Proposes using the scale of peak local G to determine distance-band thresholds; the rationale behind the Incremental Autocorrelation tool.

Getis, A. (2010). "Spatial Interaction and Spatial Autocorrelation: A Cross-Product Approach." In L. Anselin & S.J. Rey (eds.), Perspectives on Spatial Data Analysis, pp. 23–33. Springer. DOI: 10.1007/978-3-642-01976-0_3 — Retrospective on the G family of statistics; places General G in the broader cross-product-statistics framework.

Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. DOI: 10.1111/j.1538-4632.1995.tb00338.x — Positions General G alongside Local Moran's I as the two principal local spatial statistics; essential comparative reading.

Boots, B.N. & Getis, A. (1988). Point Pattern Analysis. Newbury Park: SAGE. ISBN: 978-0803929912 — Earlier work laying the conceptual foundation for distance-based spatial association measures.

Fotheringham, A.S. & Zhan, F.B. (2010). "A Comparison of Three Exploratory Methods for Cluster Detection in Spatial Point Patterns." Geographical Analysis 28(3): 200–218. DOI: 10.1111/j.1538-4632.1996.tb00931.x — Compares General G with Ripley's K and kernel density methods for cluster detection.

Chakravorty, S. (1995). "Identifying Crime Clusters: The Case of Multnomah County." Journal of Crime and Justice 18(2): 133–149. DOI: 10.1080/0735648X.1995.9721055 — Early applied example using General G for directional cluster detection in planning-relevant data.

Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. London: Pion. ISBN: 978-0850860818 — Preceding work that established the cross-product-statistic framework within which General G operates.

Tiefelsdorf, M. (2002). "The Saddlepoint Approximation of Moran's I and Local Moran's I's Reference Distributions and Their Numerical Evaluation." Geographical Analysis 34(3): 187–206. DOI: 10.1111/j.1538-4632.2002.tb01084.x — Provides exact distributional results for the cross-product family; supports the use of permutation moments over normal approximation.

Rogerson, P.A. (2006). Statistical Methods for Geography: A Student's Guide (2nd ed.). London: SAGE. ISBN: 978-1412907965 — Accessible textbook treatment of General G at the undergraduate/graduate level; chapters 7–8.

Anselin, L. & Rey, S.J. (2014). Modern Spatial Econometrics in Practice: A Guide to GeoDa, GeoDaSpace and PySAL. Chicago: GeoDa Press. ISBN: 978-0986342103 — Practical workbook with General G exercises using open-source tools.

📈

#### Incremental Spatial Autocorrelation

incremental_spatial_autocorrelation
Computes Global Moran's I at a sequence of increasing distance bands to identify the distance at which spatial autocorrelation peaks. This is the recommended method for selecting a distance-band threshold when theory provides no guidance. The peak z-score distance is the scale at which the spatial process exhibits its strongest clustering — a data-driven alternative to guessing. Produces an HTML report with a distance-scan table, an SVG line chart of z-scores, peak-distance identification, and neighborhood support diagnostics for each band.

##### 1. Theoretical Background

Origins: the correlogram. The concept of evaluating spatial autocorrelation at multiple scales traces back to the spatial correlogram — a plot of Moran's I (or Geary's c) against lag distance — introduced in the foundational work of Cliff and Ord (1973, 1981). The correlogram generalizes the time-series autocorrelation function (ACF) to two dimensions: instead of plotting autocorrelation against temporal lag, it plots autocorrelation against distance class. The method answers a question that a single-distance Global Moran's I cannot: at what distance is spatial autocorrelation strongest?

Incremental vs. continuous autocorrelation. A full spatial correlogram computes Moran's I for each distance class (typically overlapping bands, e.g., 0–500 m, 500–1000 m, etc.) and may use a lagged definition where pairs are assigned to the band containing their distance. The Incremental Autocorrelation tool uses a cumulative-band definition: at each step k, all features within distance \(d_k = d_{\text{start}} + k \cdot \Delta d\) are considered neighbors. This cumulative approach has two advantages for planning applications: (a) the neighborhood graph at each step is directly the graph that would be used in a distance-band analysis, making the result actionable; (b) the z-score trajectory reveals the distance at which the clustering signal stabilizes or saturates, as well as the distance at which it peaks.

Scale of maximum clustering. Getis and Aldstadt (2004) proposed using the scale at which a local G statistic peaks as the basis for constructing a spatial weights matrix. This plugin extends that logic to the global Moran's I: the distance at which |z| is maximized is reported as the "peak clustering distance." This distance becomes a data-driven candidate for the band threshold in subsequent analyses (General G, Gi*, LISA, GWR bandwidth selection). The analyst should verify that the peak distance corresponds to a meaningful process scale (e.g., the radius of a typical neighborhood, the range of a policy intervention, the scale of commuting catchments) rather than blindly adopting the statistical peak.

Neighborhood support across distances. As the distance band expands, the number of neighbors per feature increases and the number of isolated features (zero neighbors) decreases. The tool reports minimum, median, and maximum neighbor counts plus the isolated-feature count for each band. This allows the analyst to trade off between statistical power (more neighbors → more stable estimates) and spatial resolution (fewer neighbors → more local specificity). A band with zero isolated features and median neighbors between 8 and 30 is typically a good balance for planning applications.

##### 2. Mathematical Formulation

For each distance band \(d_k = d_{\text{start}} + k \cdot \Delta d\) (\(k = 0, 1, \ldots, K-1\)), a binary spatial weights matrix \(\mathbf{W}^{(k)}\) is constructed and Global Moran's I is computed under randomization.

Binary distance-band weight matrix at step k:

$$w_{ij}^{(k)} = \begin{cases} 1 & \text{if } d_{ij} \le d_k \text{ and } i \neq j \\ 0 & \text{otherwise} \end{cases} \tag{1}$$

where \(d_{ij}\) is the Euclidean distance between centroids of features i and j.

Neighbor-count diagnostics at step k:

$$n_i^{(k)} = \sum_{j \neq i} w_{ij}^{(k)}, \quad n_{\min}^{(k)} = \min_i n_i^{(k)}, \quad n_{\text{med}}^{(k)} = \operatorname{median}_i n_i^{(k)}, \quad n_{\max}^{(k)} = \max_i n_i^{(k)} \tag{2}$$ $$\text{isolated}^{(k)} = \sum_{i=1}^{N} \mathbf{1}\{n_i^{(k)} = 0\} \tag{3}$$

Moran's I at step k (via matrix-vector form):

$$I^{(k)} = \frac{N}{S_0^{(k)}} \cdot \frac{\mathbf{z}^\top \mathbf{W}^{(k)} \mathbf{z}}{\mathbf{z}^\top \mathbf{z}} \tag{4}$$

where \(\mathbf{z} = \mathbf{y} - \bar{y}\mathbf{1}\) is the deviation-from-mean vector and \(S_0^{(k)} = \sum_i \sum_j w_{ij}^{(k)}\).

Variance and inference at step k:

$$S_1^{(k)} = \frac{1}{2} \sum_i \sum_j \left(w_{ij}^{(k)} + w_{ji}^{(k)}\right)^2 \tag{5}$$ $$S_2^{(k)} = \sum_i \left(r_i^{(k)} + c_i^{(k)}\right)^2, \quad r_i^{(k)} = \sum_j w_{ij}^{(k)}, \quad c_i^{(k)} = \sum_j w_{ji}^{(k)} \tag{6}$$ $$D = \frac{N \sum_i z_i^4}{(\sum_i z_i^2)^2} \tag{7}$$ $$\operatorname{Var}(I^{(k)}) = \frac{N\left[(N^2 - 3N + 3)S_1^{(k)} - N S_2^{(k)} + 3 (S_0^{(k)})^2\right] - D\left[(N^2 - N)S_1^{(k)} - 2N S_2^{(k)} + 6 (S_0^{(k)})^2\right]}{(N-1)(N-2)(N-3)(S_0^{(k)})^2} - \left(\mathbb{E}[I^{(k)}]\right)^2 \tag{8}$$

Standardized z-score at step k:

$$z^{(k)} = \frac{I^{(k)} - \mathbb{E}[I^{(k)}]}{\sqrt{\operatorname{Var}(I^{(k)})}}, \quad \mathbb{E}[I^{(k)}] = -\frac{1}{N-1} \tag{9}$$

Peak clustering distance:

$$d^* = d_{k^*}, \quad k^* = \underset{k}{\operatorname{argmax}}\; |z^{(k)}| \tag{10}$$
Implementation note. The engine (see `stats_engines.py` lines 1384–1479) pre-computes the full N×N centroid distance matrix once, then at each step constructs a binary weight matrix via threshold comparison. The numerator \(\mathbf{z}^\top \mathbf{W} \mathbf{z}\) is computed via dense matrix-vector triple product (the computational hot path). The variance uses the exact randomization formulation (Eq. 8) rather than an asymptotic approximation, which is important because the normal approximation for Moran's I is least reliable at extreme z-scores — exactly where the peak is identified.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer (centroids used for distance computation)
FIELD | Numeric Field | — | Must be numeric with variation | Target variable for autocorrelation scan
START_DISTANCE | Double | 500.0 | ≥ 0.0001 | First distance band (map units) — should be smaller than typical feature spacing
DISTANCE_INCREMENT | Double | 500.0 | ≥ 0.0001 | Step between consecutive bands — finer steps give more resolution but longer runtime
N_INCREMENTS | Integer | 10 | 3–50 | Number of distance bands to evaluate — should cover a range from local to regional scale
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output report with SVG chart, distance-scan table, and peak identification

##### 4. Output Description

The HTML report contains an SVG line chart of z-scores across distance bands and the following per-band fields:

Field | Type | Description
--- | --- | ---
distance | Double | Distance band threshold for this row
morans_i | Double | Global Moran's I at this distance band
expected_i | Double | Expected I under CSR: −1/(N−1)
z_score | Double | Standardized z-score at this band
p_value | Double | Two-tailed p-value at this band
min_neighbors | Integer | Minimum neighbor count across features at this band
median_neighbors | Double | Median neighbor count at this band
max_neighbors | Integer | Maximum neighbor count at this band
isolated_count | Integer | Number of features with zero neighbors at this band
peak_distance | Double | The distance at which |z| is maximized (highlighted row)

##### 5. Interpretation Guide

z-score trajectory archetypes.

Trajectory Shape | Meaning | Recommended Action
--- | --- | ---
Peak at intermediate distance, declining after | Spatial process has a characteristic scale; broader bands dilute the signal | Adopt the peak distance as the band threshold for subsequent analyses
Monotonically increasing, no clear peak | Clustering strengthens with spatial scale; pattern may be regional rather than local | Expand the distance range or test whether the last band is close to full connectivity
Monotonically decreasing | Strongest clustering at the smallest scale; local processes dominate | Use the smallest distance that eliminates isolated features
Flat across all distances, |z| < 1.96 | No significant clustering at any tested scale | Test alternative variables or expand the distance range; consider that the process may be genuinely random
Multiple peaks | Multiple spatial processes at different scales may be operating | Investigate each peak distance; consider MGWR for multiscale modeling

Isolated features at peak. Even at the peak z-score distance, some features may have zero neighbors. If the isolated-count at the peak is more than ~5% of total features, the peak distance is too small for reliable inference. Choose a distance band where isolated features are minimized and z-score is still significant.

See also: Calculate Distance Band · Global Moran's I

##### 6. Literature

Cliff, A.D. & Ord, J.K. (1973). Spatial Autocorrelation. London: Pion. ISBN: 978-0850860368 — Introduces the spatial correlogram as a method for exploring autocorrelation across distance classes.

Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. London: Pion. ISBN: 978-0850860818 — Definitive treatment of the correlogram approach; chapters 5–6.

Getis, A. & Aldstadt, J. (2004). "Constructing the Spatial Weights Matrix Using a Local Statistic." Geographical Analysis 36(2): 90–104. DOI: 10.1111/j.1538-4632.2004.tb01127.x — Proposes data-driven distance-band selection using the scale of peak local spatial association.

Anselin, L. (2005). Exploring Spatial Data with GeoDa: A Workbook. Urbana: UIUC. — Workbook treatment of distance-band selection via incremental I; sections on spatial weights sensitivity analysis.

Legendre, P. & Legendre, L. (2012). Numerical Ecology (3rd English ed.). Amsterdam: Elsevier. ISBN: 978-0444538680 — Comprehensive treatment of Mantel correlograms and distance-based autocorrelation; chapters 13–14.

Oden, N.L. (1984). "Assessing the Significance of a Spatial Correlogram." Geographical Analysis 16(1): 1–16. DOI: 10.1111/j.1538-4632.1984.tb00796.x — Addresses the multiple-testing problem in correlogram interpretation.

Fortin, M.-J. & Dale, M.R.T. (2005). Spatial Analysis: A Guide for Ecologists. Cambridge: Cambridge University Press. ISBN: 978-0521009737 — Practical guide to correlogram construction and interpretation.

Bjørnstad, O.N. & Falck, W. (2001). "Nonparametric Spatial Covariance Functions: Estimation and Testing." Environmental and Ecological Statistics 8(1): 53–70. DOI: 10.1023/A:1009601932481 — Spline-based alternative to discrete correlograms; relevant for continuous-scale comparison.

Haining, R.P. (2003). Spatial Data Analysis: Theory and Practice. Cambridge: Cambridge University Press. ISBN: 978-0521774376 — Chapter 7 covers correlogram analysis within the broader spatial data analysis framework.

ESRI. (2023). "How Incremental Spatial Autocorrelation Works." ArcGIS Pro Documentation. — Documents the cumulative-band incremental approach; the methodological reference for the tool's design.

Fotheringham, A.S., Brunsdon, C. & Charlton, M. (2002). Geographically Weighted Regression. Chichester: Wiley. ISBN: 978-0471496168 — Chapter 3 discusses optimal bandwidth selection via cross-validation, the GWR analogue of the incremental Moran scan.

Bivand, R.S. & Wong, D.W.S. (2018). "Comparing Implementations of Global and Local Indicators of Spatial Association." TEST 27(3): 716–748. DOI: 10.1007/s11749-018-0599-x — Comparative benchmarking of spatial autocorrelation implementations; motivates the use of the randomization variance formulation.

🎯

#### Ripley's K-Function

ripleys_k_function
Evaluates point-pattern clustering or dispersion simultaneously across multiple distance scales using Ripley's K-Function and the variance-stabilized L(d) − d transformation. Positive L(d) − d values indicate more neighboring features within distance d than expected under Complete Spatial Randomness (CSR); negative values indicate fewer neighbors (dispersion). Unlike the Average Nearest Neighbor (which tests only the first-order nearest-neighbor distance), Ripley's K characterizes second-order structure — how points relate to each other at every distance up to the maximum tested. Uses feature centroids; edge correction is not applied, so results should be interpreted as a diagnostic planning scan rather than a definitive inferential test.

##### 1. Theoretical Background

Origins. Brian D. Ripley introduced the K-function in his 1976 paper in the Journal of Applied Probability and expanded the treatment in his 1977 discussion paper in Journal of the Royal Statistical Society B, where Julian Besag contributed the L(d) transformation. The K-function belongs to the class of second-order summary statistics for spatial point processes: first-order statistics describe the intensity (mean number of points per unit area), while second-order statistics describe the spatial dependence structure — whether points, on average, have more or fewer neighbors within distance d than expected under CSR.

Why second-order? The Average Nearest Neighbor (ANN) statistic examines only the distance from each point to its single closest neighbor. This captures the local first-order structure but is blind to patterns operating at larger distances. A point pattern can appear randomly distributed at the nearest-neighbor scale (ANN ratio near 1) while being strongly clustered at a 500-meter scale (measured by K(500) or L(500)). Conversely, a pattern that appears clustered at the nearest-neighbor scale may be part of a larger regular lattice. Ripley's K provides the complete distance-dependent view.

The L(d) transformation. Under CSR, the expected K(d) is \(\pi d^2\). Besag (1977) proposed the transformation \(L(d) = \sqrt{K(d) / \pi} - d\), which stabilizes the variance across distances and centers the CSR expectation at zero. This makes the K-function plot interpretable as a deviation-from-CSR chart: positive values indicate clustering, negative values indicate dispersion, and values near zero indicate consistency with CSR. The transformation is universally adopted in the spatial point-pattern literature (Diggle, 2013; Baddeley et al., 2015).

Edge effects and the planning context. Ripley's K is known to be biased near study-area boundaries because points near the edge have fewer measurable neighbors within distance d (some potential neighbors lie outside the study area). Edge-correction methods exist (Ripley's isotropic correction, toroidal correction, guard area) but are not implemented in this diagnostic scan. In a planning context, the uncorrected K provides a conservative (downward-biased) estimate of clustering at large distances — if clustering is detected despite edge bias, the true clustering is likely stronger. Analysts should report results as a "diagnostic planning scan" and note the absence of edge correction when comparing results across datasets or study areas.

##### 2. Mathematical Formulation

For a set of N points in a study area of size A, Ripley's K-function is estimated at each distance band \(d_k = d_{\text{start}} + k \cdot \Delta d\). The Plugin uses centroid-to-centroid Euclidean distances and an indicator-function estimator.

Empirical Ripley's K (unbiased ratio estimator, no edge correction):

$$K(d) = \frac{A}{N(N-1)} \sum_{i=1}^{N}\sum_{j \neq i}^{N} \mathbf{1}\{d_{ij} \le d\} \tag{1}$$

The indicator function \(\mathbf{1}\{d_{ij} \le d\}\) counts ordered pairs within distance d. The multiplier \(A / [N(N-1)]\) converts the pair count to an intensity-normalized scale. Note that each unordered pair is counted twice (once as \((i, j)\) and once as \((j, i)\)), so the total pair count equals \(2 \times\) (number of unordered pairs within d).

Expected K under Complete Spatial Randomness (CSR):

$$\mathbb{E}[K(d)] = \pi d^2 \tag{2}$$

Under CSR, points follow a homogeneous Poisson process with constant intensity \(\lambda = N/A\). The expected number of additional points within distance d of a randomly chosen point is \(\lambda \pi d^2\).

Besag's L-function (variance-stabilized transformation):

$$L(d) = \sqrt{\frac{K(d)}{\pi}} \tag{3}$$ $$L(d) - d = \sqrt{\frac{K(d)}{\pi}} - d \tag{4}$$

Under CSR, \(\mathbb{E}[L(d)] = d\) and therefore \(\mathbb{E}[L(d) - d] = 0\). This is the primary diagnostic metric: positive values → clustering, negative values → dispersion.

Study-area estimation (when not user-supplied):

$$A_{\text{est}} = (\max_i x_i - \min_i x_i) \cdot (\max_i y_i - \min_i y_i) \tag{5}$$

This bounding-box area estimate can be systematically smaller than the true study area, especially for irregular or non-rectangular study regions. A user-supplied study area is always preferred.

Neighbor-count diagnostics at distance d:

$$n_i(d) = \sum_{j \neq i} \mathbf{1}\{d_{ij} \le d\}, \quad n_{\min}(d), \; n_{\text{med}}(d), \; n_{\max}(d) \tag{6}$$ $$\text{isolated}(d) = \sum_i \mathbf{1}\{n_i(d) = 0\} \tag{7}$$

Maximum L(d) − d departure (peak clustering / dispersion):

$$d^* = \underset{d_k}{\operatorname{argmax}}\; |L(d_k) - d_k| \tag{8}$$
Implementation note. The engine (see `stats_engines.py` lines 1482–1525) constructs the full N×N distance matrix from feature centroids and, at each band, applies a threshold to produce a binary indicator matrix. The study area defaults to the bounding-box area of the point set if not user-supplied. The diagonal (\(i = j\)) is zeroed in the indicator matrix to exclude self-pairs. The engine reports observed K, expected K (\(\pi d^2\)), L(d), L(d) − d, observed pair count, and neighbor-count diagnostics for each band.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type, ≥ 3 features | Input layer (centroids used as point locations)
START_DISTANCE | Double | 500.0 | ≥ 0.0001 | Smallest distance to evaluate (map units)
DISTANCE_INCREMENT | Double | 500.0 | ≥ 0.0001 | Step between consecutive distance bands
N_INCREMENTS | Integer | 10 | 3–50 | Number of distance bands — maximum distance = start + (N−1) × increment
STUDY_AREA | Double (opt) | 0 | ≥ 0 (0 = auto) | Study area in map units squared; bounding-box area if 0 or omitted
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output K-function report with distance-scan table and interpretation

##### 4. Output Description

Field | Type | Description
--- | --- | ---
distance | Double | Distance band d for this row
observed_k | Double | Empirical K(d): intensity-normalized pair count within distance d
expected_k | Double | Theoretical K under CSR: \(\pi d^2\)
l_value | Double | Besag's L(d) = \(\sqrt{K(d) / \pi}\)
l_minus_d | Double | L(d) − d: primary diagnostic (0 = CSR, positive = clustered, negative = dispersed)
observed_pairs | Integer | Total ordered pairs (\(i \neq j\)) within distance d
min_neighbors | Integer | Minimum neighbors per feature at distance d
median_neighbors | Double | Median neighbors per feature at distance d
max_neighbors | Integer | Maximum neighbors per feature at distance d
isolated_count | Integer | Number of features with zero neighbors at distance d
study_area | Double | Study area used in computation (user-supplied or bounding-box)

##### 5. Interpretation Guide

L(d) − d trajectory interpretation.

L(d) − d Behavior | Pattern | Planning Interpretation
--- | --- | ---
Positive across all tested distances, peak at intermediate d | Clustered, with characteristic scale | Features are more aggregated than expected by chance; the peak distance is the characteristic cluster radius
Positive and increasing across all distances | Clustered at all tested scales | Clustering persists at the largest tested distance; expand the range to find where it becomes CSR
Negative across all or most distances | Dispersed / regular | Features are more evenly spaced than expected; may indicate zoning, competition, or spatial planning
Close to zero (within ~1 unit) across all distances | Consistent with CSR | No second-order structure detected; pattern is indistinguishable from random at tested scales
Positive at small d, negative at large d | Local clustering, global dispersion | Clusters of features are themselves regularly spaced — typical of urban sub-center patterns

Comparison with Average Nearest Neighbor. ANN tests only the first-order nearest-neighbor distance. Ripley's K tests second-order structure at every distance. A pattern with ANN ratio near 1 (random at first order) but significant L(d) − d at larger distances is common in urban systems where local spacing appears random but regional clustering is strong. When both tools are available, compare their conclusions: if they agree (both indicate clustering or both indicate CSR), the result is robust. If they disagree, the spatial structure is scale-dependent and Ripley's K provides the richer characterization.

Study-area sensitivity. The expected K(d) = \(\pi d^2\) depends on the intensity \(\lambda = N/A\), which in turn depends on the study area A. A larger study area reduces the expected pair count and makes clustering appear stronger (more pairs observed than expected). Because the bounding-box area is typically an underestimate — particularly for irregularly-shaped study regions — the diagnostic K may overstate clustering when the auto-area method is used. Whenever possible, provide a user-specified study area from a known boundary polygon.

Cautionary note on maximum distance. Ripley and subsequent authors (Baddeley et al., 2015) recommend interpreting K(d) only for \(d \le 0.25 \sqrt{A}\) (i.e., one-quarter of the square root of the study area). Beyond this distance, edge effects become severe and the variance of the estimator increases. The plugin does not enforce this cutoff automatically; the analyst should assess whether the maximum tested distance is interpretable given the study-area geometry.

See also: Average Nearest Neighbor

##### 6. Literature

Ripley, B.D. (1976). "The Second-Order Analysis of Stationary Point Processes." Journal of Applied Probability 13(2): 255–266. DOI: 10.2307/3212829 — The origin paper; defines the K-function and derives its theoretical properties for stationary point processes.

Ripley, B.D. (1977). "Modelling Spatial Patterns" (with discussion). Journal of the Royal Statistical Society B 39(2): 172–212. DOI: 10.1111/j.2517-6161.1977.tb01615.x — The full treatment with edge-correction methods and the discussion where Besag proposes the L(d) transformation.

Besag, J. (1977). "Contribution to the Discussion of Dr. Ripley's Paper." Journal of the Royal Statistical Society B 39(2): 193–195. — Introduces the \(L(d) = \sqrt{K(d)/\pi}\) transformation; the "L" in "L-function" honors Besag.

Diggle, P.J. (2013). Statistical Analysis of Spatial and Spatio-Temporal Point Patterns (3rd ed.). Boca Raton: CRC Press. ISBN: 978-1466560239 — The modern standard reference; chapters 4–5 cover K-function estimation, edge correction, and Monte Carlo envelopes.

Baddeley, A., Rubak, E. & Turner, R. (2015). Spatial Point Patterns: Methodology and Applications with R. Boca Raton: CRC Press. ISBN: 978-1482210200 — Comprehensive practical reference; the `spatstat` package is the gold-standard implementation.

Bailey, T.C. & Gatrell, A.C. (1995). Interactive Spatial Data Analysis. Harlow: Longman. ISBN: 978-0582244931 — Accessible textbook treatment of K-function with worked examples in epidemiology and crime analysis.

Cressie, N.A.C. (1993). Statistics for Spatial Data (revised ed.). New York: Wiley. ISBN: 978-0471002550 — Chapters 8–9 provide the rigorous statistical foundation for K-function and related second-order methods.

Getis, A. & Boots, B. (1978). Models of Spatial Processes. Cambridge: Cambridge University Press. — Early comparative treatment of K-function and nearest-neighbor methods for point pattern analysis.

Haase, P. (1995). "Spatial Pattern Analysis in Ecology Based on Ripley's K-Function: Introduction and Methods of Edge Correction." Journal of Vegetation Science 6(4): 575–582. DOI: 10.2307/3236356 — Practical guide to edge-correction methods; relevant for understanding the bias in uncorrected K estimates.

Marcon, E. & Puech, F. (2003). "Evaluating the Geographic Concentration of Industries Using Distance-Based Methods." Journal of Economic Geography 3(4): 409–428. DOI: 10.1093/jeg/lbg016 — Application of Ripley's K to economic geography and industrial clustering; directly relevant to planning applications.

Illian, J., Penttinen, A., Stoyan, H. & Stoyan, D. (2008). Statistical Analysis and Modelling of Spatial Point Patterns. Chichester: Wiley. ISBN: 978-0470014912 — Advanced treatment including inhomogeneous K-function for non-stationary point processes.

O'Sullivan, D. & Unwin, D.J. (2010). Geographic Information Analysis (2nd ed.). Hoboken: Wiley. ISBN: 978-0470288573 — GIS-focused introduction to point pattern analysis; chapters 4–5 cover K-function in a GIS context.

📐

#### Average Nearest Neighbor

average_nearest_neighbor
Computes the ratio of the observed mean nearest-neighbor distance to the expected mean distance under Complete Spatial Randomness (CSR). The Nearest Neighbor Index (NNI) ranges from 0 (perfectly clustered — all points at the same location) through 1 (random) to approximately 2.15 (perfectly dispersed on a hexagonal lattice). The simplest and most intuitive first-order clustering diagnostic. By far the fastest spatial pattern tool in the group — applicable as a quick screening before committing to computationally heavier methods (Ripley's K, Incremental Autocorrelation). Produces an HTML report with observed/expected mean distances, NNI ratio, z-score, p-value, and study-area diagnostics.

##### 1. Theoretical Background

Origins. Philip J. Clark and Francis C. Evans introduced the nearest-neighbor distance method in their 1954 paper in Ecology. Studying the spatial distribution of plant species, they recognized that the mean distance from each individual to its nearest neighbor — compared against the theoretical expectation for a randomly distributed population — provides a simple but powerful test of spatial pattern. Their "distance to nearest neighbor" statistic (R) was the first widely-adopted quantitative method for distinguishing clustered, random, and regular spatial arrangements.

First-order vs. second-order structure. The Average Nearest Neighbor statistic is a first-order measure: it describes only the distances to the single closest neighbor of each point. It captures the fine-scale local packing of points but is insensitive to patterns that manifest only at larger distances. For example, a point pattern might consist of tightly clustered groups that are themselves regularly spaced across the landscape — ANN would detect the tight clustering (first-order) but miss the regular spacing of the groups (second-order). This is the motivating logic for pairing ANN with Ripley's K-function: ANN provides the quick first-order screen; K-function reveals the multi-scale structure.

Theoretical distribution under CSR. Under CSR, points follow a homogeneous Poisson process with constant intensity \(\lambda = N/A\). The probability density of the distance r to the nearest neighbor is \(f(r) = 2 \pi \lambda r \exp(-\pi \lambda r^2)\). The expected nearest-neighbor distance is therefore \(\mathbb{E}[r] = 1 / (2 \sqrt{\lambda}) = 1 / (2 \sqrt{N/A})\). The standard error of the mean nearest-neighbor distance is \(\text{SE} = 0.26136 / \sqrt{N \lambda}\), a result derived by Clark and Evans from the properties of the exponential distribution of squared distances.

Evolution and extensions. Donnelly (1978) corrected the CSR expectation for the case of points in a bounded region (the original formulation assumed an infinite plane). The plugin uses the original Clark-Evans formulation, which is appropriate when the study area represents a contiguous planning region and edge effects are not severe. Diggle (2013) placed nearest-neighbor methods within the broader framework of point-process statistics, and the method remains a standard tool in every spatial statistics platform (ArcGIS, R/spatstat, GeoDa, PySAL).

Study-area sensitivity — the critical caveat. The expected nearest-neighbor distance depends on the study area A: a larger A reduces the expected density \(\lambda = N/A\) and increases the expected distance, making a given observed distance appear more clustered relative to CSR. Conversely, a smaller A increases expected density and makes the same observed distance appear less clustered or even dispersed. This means the conclusion (clustered vs. random vs. dispersed) can change with the study-area boundary. The plugin reports whether the study area was user-supplied or bounding-box-derived, and the analyst should always test sensitivity by comparing results across plausible boundary definitions.

##### 2. Mathematical Formulation

For N point locations \((x_i, y_i)\) in a study area of size A.

Observed mean nearest-neighbor distance:

$$\bar{d}_{\text{obs}} = \frac{1}{N} \sum_{i=1}^{N} \min_{j \neq i} \; d_{ij} \tag{1}$$

where \(d_{ij} = \sqrt{(x_i - x_j)^2 + (y_i - y_j)^2}\) and the minimum is taken over all \(j \neq i\). The plugin uses scikit-learn's KD-Tree for O(N log N) computation when available; otherwise falls back to chunked vectorized NumPy.

Study-area estimation (bounding-box fallback):

$$A = \begin{cases} A_{\text{user}} & \text{if } A_{\text{user}} > 0 \\ (\max_i x_i - \min_i x_i) \cdot (\max_i y_i - \min_i y_i) & \text{otherwise} \end{cases} \tag{2}$$

Point intensity (density) estimate:

$$\lambda = \frac{N}{A} \tag{3}$$

Expected mean nearest-neighbor distance under CSR:

$$\bar{d}_{\text{exp}} = \frac{1}{2\sqrt{\lambda}} = \frac{1}{2} \sqrt{\frac{A}{N}} \tag{4}$$

This follows from the properties of the homogeneous Poisson process (Clark & Evans, 1954, Eq. 11).

Standard error of the mean nearest-neighbor distance:

$$\text{SE}(\bar{d}_{\text{obs}}) = \frac{0.26136}{\sqrt{N \lambda}} = \frac{0.26136}{\sqrt{N^2 / A}} \tag{5}$$

The constant 0.26136 derives from the variance of the distribution of nearest-neighbor distances under CSR (Clark & Evans, 1954, Table 1 and Eq. 12).

Nearest Neighbor Index (NNI / R statistic):

$$\text{NNI} = \frac{\bar{d}_{\text{obs}}}{\bar{d}_{\text{exp}}} \tag{6}$$

NNI < 1 → clustered (observed distances shorter than expected); NNI = 1 → random; NNI > 1 → dispersed. At perfect dispersion on a hexagonal lattice, NNI ≈ 2.1491.

z-score for the difference between observed and expected mean distances:

$$z = \frac{\bar{d}_{\text{obs}} - \bar{d}_{\text{exp}}}{\text{SE}(\bar{d}_{\text{obs}})} \tag{7}$$

Two-tailed p-value:

$$p = 2\left[1 - \Phi(|z|)\right] \tag{8}$$
Implementation note. The engine (see `stats_engines.py` lines 742–796) tries `sklearn.neighbors.NearestNeighbors` (KD-Tree) for efficient nearest-neighbor search. If sklearn is unavailable, it uses a chunked vectorized NumPy approach: the full N×N distance matrix is computed in chunks of 1000 rows to protect memory, then row minima are extracted excluding self-distances. The z-score uses the Clark-Evans standard error (0.26136 constant) and p-values are computed via the error function. The study area defaults to the bounding-box area of point coordinates if not user-supplied.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry, ≥ 2 features | Input vector layer (centroids used as point locations)
STUDY_AREA | Double (opt) | 0 | ≥ 0 (0 = auto) | Study area in map units squared; bounding-box area derived from layer extent if 0 or omitted
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report with all NNI statistics and interpretation

##### 4. Output Description

Field | Type | Description
--- | --- | ---
observed_mean | Double | Observed mean nearest-neighbor distance \(\bar{d}_{\text{obs}}\)
expected_mean | Double | Expected mean distance under CSR \(\bar{d}_{\text{exp}} = 1 / (2\sqrt{\lambda})\)
nn_ratio | Double | Nearest Neighbor Index (NNI = R): observed / expected; 0 = perfect cluster, ~2.15 = perfect hex lattice
z_score | Double | Standardized z-score for the difference observed − expected
p_value | Double | Two-tailed p-value (normal approximation)
study_area | Double | Study area used (user-supplied or auto-computed bounding-box)
pattern | String | Pattern classification: Clustered / Dispersed / Random

##### 5. Interpretation Guide

NNI benchmarks and spatial pattern interpretation.

NNI Range | Pattern | Typical z-score | Planning Example
--- | --- | --- | ---
0.00 – 0.50 | Strongly Clustered | z ≤ −2.58, p < 0.01 | Retail establishments in a central business district; emergency calls in a high-crime area
0.50 – 0.80 | Moderately Clustered | −2.58 ≤ z ≤ −1.96, p < 0.05 | Public schools in older urban neighborhoods; health clinics co-located near hospitals
0.80 – 0.95 | Weakly Clustered | −1.96 ≤ z ≤ −1.00 | Convenience stores with mild local clustering; park facilities
0.95 – 1.05 | Not distinguishable from CSR | |z| < 1.00 | Points with no detectable spatial order at the nearest-neighbor scale
1.05 – 1.30 | Weakly Dispersed | +1.00 ≤ z ≤ +1.96 | Fire stations with overlapping service areas; public libraries
1.30 – 2.15 | Dispersed / Regular | z ≥ +1.96, p < 0.05 | Planned facility networks; zoning that enforces minimum spacing

Study-area sensitivity — the single most important caveat. The expected distance under CSR is \(\bar{d}_{\text{exp}} = \frac{1}{2}\sqrt{A/N}\). Doubling the study area A increases \(\bar{d}_{\text{exp}}\) by a factor of \(\sqrt{2} \approx 1.41\), which can change a conclusion from "dispersed" to "clustered" without any change in the actual point locations. The auto-computed bounding-box area is usually a lower bound on the true study area (it is the area of the minimum rectangle enclosing the points). For irregular study regions — counties, watersheds, census metropolitan areas — always provide a user-specified study area from a boundary layer. If you are unsure about the appropriate area, run ANN with both the bounding-box area and a polygon-area estimate and compare conclusions: divergent results indicate that the boundary definition is critical and should be resolved before reporting.

Comparison with Ripley's K. ANN tests the first-order (nearest-neighbor) structure. Ripley's K tests second-order structure at every distance. If ANN indicates clustering and Ripley's K also indicates clustering across multiple distances, the clustering is multi-scale and robust. If ANN indicates CSR but Ripley's K indicates clustering at larger distances, the spatial structure exists but operates above the nearest-neighbor scale — typical of regional clustering with local randomness. In all cases, Ripley's K provides the richer interpretation; ANN provides the faster screening result.

Centroid caveat. For polygon or line features, the plugin uses feature centroids as point locations. This is appropriate when features are approximately point-like (small parcels, building footprints) but can be misleading for large or irregularly-shaped polygons. Two large adjacent polygons with centroids far apart may genuinely be neighbors. For polygon layers where area varies substantially, consider generating population-weighted centroid points or using contiguity-based methods (Moran's I with Queen/Rook weights) instead.

See also: Ripley's K-Function

##### 6. Literature

Clark, P.J. & Evans, F.C. (1954). "Distance to Nearest Neighbor as a Measure of Spatial Relationships in Populations." Ecology 35(4): 445–453. DOI: 10.2307/1931034 — The foundational paper; derives the expected nearest-neighbor distance under CSR and the standard error used in this plugin.

Donnelly, K. (1978). "Simulations to Determine the Variance and Edge-Effect of Total Nearest Neighbour Distance." In I. Hodder (ed.), Simulation Studies in Archaeology, pp. 91–95. Cambridge: Cambridge University Press. — Corrects the Clark-Evans formulation for edge effects in bounded regions.

Diggle, P.J. (2013). Statistical Analysis of Spatial and Spatio-Temporal Point Patterns (3rd ed.). Boca Raton: CRC Press. ISBN: 978-1466560239 — Modern treatment placing nearest-neighbor methods in the broader point-process framework.

Cressie, N.A.C. (1993). Statistics for Spatial Data (revised ed.). New York: Wiley. ISBN: 978-0471002550 — Chapter 8 provides the rigorous statistical foundation for nearest-neighbor distances.

King, L.J. (1969). Statistical Analysis in Geography. Englewood Cliffs: Prentice-Hall. ISBN: 978-0138449200 — Early geography textbook with accessible treatment of nearest-neighbor analysis for urban patterns.

Pinder, D.A. & Witherick, M.E. (1972). "The Principles, Practice and Pitfalls of Nearest-Neighbor Analysis." Geography 57(4): 277–288. — Critical review of nearest-neighbor methods; discusses study-area boundary sensitivity and the difference between first-order and second-order analysis.

Boots, B.N. & Getis, A. (1988). Point Pattern Analysis. SAGE Scientific Geography Series, Vol. 8. Newbury Park: SAGE. ISBN: 978-0803929912 — Concise monograph covering ANN, quadrat analysis, and K-function in a single accessible volume.

Ebdon, D. (1985). Statistics in Geography (2nd ed.). Oxford: Blackwell. ISBN: 978-0631136880 — Widely used textbook with a dedicated chapter on nearest-neighbor analysis and worked examples.

O'Sullivan, D. & Unwin, D.J. (2010). Geographic Information Analysis (2nd ed.). Hoboken: Wiley. ISBN: 978-0470288573 — GIS-oriented treatment; chapters 4–5 cover ANN in the context of point-pattern analysis in GIS.

Bailey, T.C. & Gatrell, A.C. (1995). Interactive Spatial Data Analysis. Harlow: Longman. ISBN: 978-0582244931 — Chapters 3–4 provide ANOVA-style comparisons of ANN results across sub-groups (e.g., ANN by time period or by land-use type).

Fortin, M.-J. & Dale, M.R.T. (2005). Spatial Analysis: A Guide for Ecologists. Cambridge: Cambridge University Press. ISBN: 978-0521009737 — Chapter 4 covers nearest-neighbor methods with ecological examples; the ecological applications translate directly to planning contexts.

Skellam, J.G. (1952). "Studies in Statistical Ecology: I. Spatial Pattern." Biometrika 39(3/4): 346–362. DOI: 10.2307/2334030 — Preceding work that influenced Clark and Evans; early development of the nearest-neighbor concept in plant ecology.

📐

#### Geary's C (Spatial Autocorrelation)

geary_c_autocorrelation
Geary's C is the sum-of-squared-differences alternative to Global Moran's I (Geary, 1954; formalized by Cliff & Ord, 1973, 1981). Where Moran's I compares each value's deviation from the global mean to its neighbors' deviations, Geary's C compares each pair of neighboring values directly to one another — making it more sensitive to local dissimilarity and less dependent on the global mean as a reference point. Geary's C uses the opposite direction convention from every other autocorrelation statistic in this plugin: values below 1.0 indicate positive spatial autocorrelation (clustering of similar values), values above 1.0 indicate negative spatial autocorrelation (dissimilar values adjacent), and 1.0 is the no-autocorrelation reference point. Significance is assessed by permutation inference (999 Monte Carlo shuffles by default) rather than the Cliff-Ord closed-form randomization variance, sidestepping that formula's own distributional assumptions.

##### 1. Theoretical Background

Origins. Robert Geary introduced the contiguity ratio in a 1954 paper in The Incorporated Statistician, four years after Patrick Moran's 1950 paper introduced what became Moran's I. Geary's statistic was built around a fundamentally different comparison: instead of asking "how does each value's deviation from the mean relate to its neighbors' deviations" (Moran's approach), Geary asked "how large is the squared difference between each pair of neighboring values, compared to the overall variance." This local, pairwise construction gives Geary's C a distinct sensitivity profile — it responds strongly to sharp local contrasts even when the broader spatial trend (captured by Moran's I) is weak.

Formalization. Cliff and Ord (1973, then more completely in their 1981 monograph Spatial Processes: Models & Applications) placed Geary's C on the same rigorous footing as Moran's I, deriving its expectation and randomization variance and establishing it as a standard member of the "join statistics" family alongside Moran's I and the Join Count Statistics implemented elsewhere in this group. Sokal and Oden (1978) further popularized Geary's C in biological and ecological spatial analysis, where its sensitivity to fine-grained local structure proved valuable for detecting patchy, small-scale spatial processes that a global-mean-referenced statistic like Moran's I can average away.

Why the two statistics can disagree. Moran's I is dominated by how far each value sits from the global mean; a strong overall gradient (e.g., a monotonic decline in accessibility from the urban core to the periphery) produces a large positive Moran's I even if adjacent pairs of features are individually quite similar. Geary's C, by contrast, only looks at neighbor-to-neighbor differences — it can register significant local dissimilarity in a field where Moran's I sees a smooth, unremarkable global trend, or conversely stay close to 1.0 in a field with a strong global gradient but very smooth local transitions. Reporting both statistics together — as this plugin recommends via the cross-references below — captures a fuller picture of spatial structure than either alone.

Permutation inference over closed-form variance. Cliff and Ord (1981) derive an exact closed-form randomization variance for Geary's C, but that formula carries assumptions (specifically about the symmetry and higher-order moment structure of the weights matrix) that are easy to violate silently with irregular polygon geometries and mixed weight specifications (KNN, distance bands). This plugin instead uses Monte Carlo permutation inference: the field values are randomly reshuffled across locations (holding the spatial weights fixed) 999 times by default, and the observed C is compared against this empirical null distribution. This is standard, citable practice (see Anselin's LISA framework, used throughout Group 03) and avoids relying on assumptions that are hard to verify for an arbitrary input layer.

##### 2. Mathematical Formulation

Let N be the number of valid features, \(y_i\) the field value at location i, \(\bar{y}\) its mean, and \(w_{ij}\) the spatial weight between i and j (row-standardized, per the plugin's weights convention).

Observed Geary's C statistic:

$$C = \frac{(N-1) \sum_{i}\sum_{j} w_{ij}(y_i - y_j)^2}{2 \, S_0 \sum_{i}(y_i - \bar{y})^2} \tag{1}$$

where \(S_0 = \sum_i \sum_j w_{ij}\) is the sum of all spatial weights.

Expectation under no spatial autocorrelation:

$$\mathbb{E}[C] = 1.0 \tag{2}$$

This is the fixed reference value regardless of N or the weights structure — a key practical difference from Moran's I, whose expectation \(-1/(N-1)\) depends on sample size.

Permutation inference procedure:

$$C^{(p)} = \text{Geary's C computed on a random permutation of } \{y_1, \ldots, y_N\} \text{, for } p = 1, \ldots, P \tag{3}$$ $$z = \frac{C_{\text{obs}} - \overline{C^{(p)}}}{\text{sd}(C^{(p)})}, \qquad p_{\text{value}} = \frac{\#\{p : |C^{(p)} - \overline{C^{(p)}}| \ge |C_{\text{obs}} - \overline{C^{(p)}}|\} + 1}{P + 1} \tag{4}$$

The weights and spatial structure are held fixed while the field values are reshuffled across locations; the "+1" in numerator and denominator is the standard Monte Carlo p-value adjustment (Davison & Hinkley, 1997), which prevents a p-value of exactly zero regardless of permutation count.

Implementation note. The engine (`core/advanced_stats_engines.py::calculate_geary_c`) builds the pairwise index/weight arrays directly from the neighbor and weight dictionaries returned by `build_weights_matrix()`, so any of the four weight-type options (Queen, Rook, KNN, Distance Band) can be used interchangeably. Validated on synthetic 10×10 grid fixtures with known ground truth: a clustered row-gradient returns C ≈ 0.03 (p = 0.002, correctly detecting strong positive autocorrelation), while an independently random field returns C ≈ 0.95 (p = 0.42, correctly failing to reject the null).

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
FIELD | Numeric Field | — | Must have variation | Target field to test for spatial autocorrelation
WEIGHT_TYPE | Enum | Queen contiguity | Queen / Rook / KNN / Distance Band | Spatial relationship used to build the weights matrix
KNN | Integer | 5 | ≥ 1 | Number of neighbors (KNN weights only)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (Distance Band weights only)
PERMUTATIONS | Integer | 999 | 99–9999 | Number of Monte Carlo permutations for significance testing
RANDOM_SEED | Integer | 42 | ≥ 0 | Seed for reproducible permutation results
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report

##### 4. Output Description

Field | Type | Description
--- | --- | ---
observed_c | Double | Observed Geary's C statistic
expected_c | Double | Expected C under no spatial autocorrelation (always 1.0)
permuted_mean | Double | Mean of C across the permutation distribution
permuted_std | Double | Standard deviation of C across the permutation distribution
z_score | Double | Standardized z-score relative to the permutation distribution
p_value | Double | Two-tailed Monte Carlo p-value

##### 5. Interpretation Guide

Reading Geary's C — note the reversed direction convention.

Condition | Meaning | Spatial Pattern | Recommended Next Step
--- | --- | --- | ---
C < 1.0, p < 0.05 | Squared differences between neighbors are smaller than expected | Positive autocorrelation (clustered) | Run Local Moran's I or Getis-Ord Gi* to locate where the clustering occurs.
C > 1.0, p < 0.05 | Squared differences between neighbors are larger than expected | Negative autocorrelation (dispersed) | Check whether the dispersion is a genuine repulsion process or a data-coding artifact (e.g. alternating survey zones).
C ≈ 1.0, p ≥ 0.05 | Cannot reject the no-autocorrelation null | Random | Compare against Global Moran's I; a disagreement between the two is itself informative about the scale of the pattern.

Geary's C vs. Moran's I — run both, not either. Because the two statistics weight local vs. global structure differently, treating them as interchangeable risks missing real spatial pattern. A field with a smooth citywide gradient and noisy local transitions can show a strong Moran's I alongside a Geary's C close to 1.0; a field with sharp local contrasts embedded in an otherwise flat citywide average can show the reverse. When the two disagree, the disagreement itself is diagnostic of which scale the spatial process operates at — investigate with Local Moran's I (Group 03) to resolve the ambiguity.

See also: Global Moran's I · Local Moran's I (LISA) · Getis-Ord Gi* · Join Count Statistics

##### 6. Literature

Geary, R.C. (1954). "The Contiguity Ratio and Statistical Mapping." The Incorporated Statistician 5(3): 115–146. — The original paper introducing the contiguity ratio, now known as Geary's C.

Cliff, A.D. & Ord, J.K. (1973). Spatial Autocorrelation. London: Pion. ISBN: 978-0850860200 — First rigorous derivation of Geary's C's expectation and randomization variance alongside Moran's I.

Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. London: Pion. ISBN: 978-0850860818 — The definitive monograph-length treatment; establishes Geary's C within the broader join-statistics framework used throughout this plugin.

Sokal, R.R. & Oden, N.L. (1978). "Spatial Autocorrelation in Biology: 1. Methodology." Biological Journal of the Linnean Society 10(2): 199–228. DOI: 10.1111/j.1095-8312.1978.tb00013.x — Popularized Geary's C for ecological and biological spatial analysis; contrasts its local sensitivity against Moran's I.

Getis, A. & Ord, J.K. (1992). "The Analysis of Spatial Association by Use of Distance Statistics." Geographical Analysis 24(3): 189–206. DOI: 10.1111/j.1538-4632.1992.tb00261.x — Companion reading on the General G statistic (Group 02), useful for contrasting directional (high/low) clustering tests against Geary's C's symmetric dissimilarity test.

Anselin, L. (2019). "A Local Indicator of Multivariate Spatial Association: Extending Geary's c." Geographical Analysis 51(2): 133–150. DOI: 10.1111/gean.12164 — Extends Geary's C to a local, multivariate LISA form; the local complement (Group 03) to the global statistic implemented here.

Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. ISBN: 978-0521574716 — Standard reference for the Monte Carlo p-value "+1" adjustment used in the permutation inference procedure.

🔲

#### Join Count Statistics (BB/WW/BW)

join_count_statistics
Every other spatial-autocorrelation tool in this plugin requires a continuous numeric field. Join Count Statistics (Cliff & Ord, 1973, 1981; building on Dacey, 1968) is the tool built for binary and categorical data — presence/absence, zoning class, a threshold-coded indicator — testing spatial clustering by counting how often neighboring feature pairs ("joins") share the same category versus differ. Three join counts are reported: Black-Black (BB, both match the category), White-White (WW, both don't), and Black-White (BW, the pair differs). Each has its own permutation-based significance test. Unlike every weights-based tool in this plugin, Join Counts use the raw, unstandardized adjacency graph rather than row-standardized weights, since the count of actual shared edges — not a per-feature average — is what the statistic needs.

##### 1. Theoretical Background

Origins. Join count statistics trace to Michael Dacey's 1968 review of contiguity measures for categorical (color-coded) maps, one of the earliest formal approaches to testing spatial pattern in qualitative data. Cliff and Ord (1973, 1981) placed join counts on the same rigorous inferential footing as Moran's I and Geary's C, deriving expectations and randomization variances for the BB, WW, and BW counts under both free sampling (with replacement) and non-free sampling (without replacement) schemes. Together with Moran's I and Geary's C, join counts complete the classical triad of global spatial-pattern statistics — one for continuous data compared to the mean (Moran), one for continuous data compared pairwise (Geary), and one for categorical/binary data (Join Counts).

What the three counts measure. Consider a binary coding where each feature is either "Black" (matches a category of interest) or "White" (doesn't). A BB join is a pair of adjacent Black features; a WW join is a pair of adjacent White features; a BW join is an adjacent Black-White pair. If the category is spatially clustered, BB and WW joins will be more frequent than chance and BW joins less frequent. If the category is spatially interspersed — checkerboarded — the reverse holds: BW joins dominate. This makes Join Count Statistics able to detect a form of spatial pattern (checkerboarding / fine-grained interspersion) that continuous-field autocorrelation statistics are not designed to test directly.

Binary adjacency, not row-standardized weights. Every other tool in this plugin row-standardizes its spatial weights (each neighbor's weight is \(1/k_i\) for \(k_i\) neighbors) so that spatial lags behave as local averages. Join Count Statistics deliberately break this convention: the classical formulation counts edges in the adjacency graph, not weighted averages, so unstandardized binary adjacency (1 if neighbors, 0 otherwise) is the mathematically correct input. Using row-standardized weights here would silently and incorrectly deflate the join counts for high-degree features.

Binarization strategy. When the chosen field is already categorical, the plugin uses its most frequent category as "Black" (everything else "White"). When the field is numeric/continuous, the plugin binarizes at the field's median (values above the median become "Black"). A meaningful, planning-relevant threshold (a regulatory cutoff, a policy-defined category) should always be preferred over an arbitrary median split when one exists — the median split is a reasonable default, not a universally correct choice.

##### 2. Mathematical Formulation

Let \(x_i \in \{0, 1\}\) be the binary code at location i (1 = Black, 0 = White), and let \(J\) be the set of unique unordered neighbor pairs \((i,j)\) derived from the binary adjacency graph (each undirected edge counted once).

Observed join counts:

$$BB = \sum_{(i,j) \in J} \mathbb{1}[x_i = 1 \wedge x_j = 1], \quad WW = \sum_{(i,j) \in J} \mathbb{1}[x_i = 0 \wedge x_j = 0], \quad BW = |J| - BB - WW \tag{1}$$

Permutation inference (per join type):

$$BB^{(p)}, WW^{(p)}, BW^{(p)} = \text{join counts on a random permutation of } \{x_1, \ldots, x_N\} \text{, for } p = 1, \ldots, P \tag{2}$$ $$z_{BB} = \frac{BB_{\text{obs}} - \overline{BB^{(p)}}}{\text{sd}(BB^{(p)})}, \qquad p_{BB} = \frac{\#\{p : |BB^{(p)} - \overline{BB^{(p)}}| \ge |BB_{\text{obs}} - \overline{BB^{(p)}}|\} + 1}{P + 1} \tag{3}$$

The same procedure applies independently to WW and BW. Category sizes (\(N_1\) Black, \(N_0\) White) are preserved exactly by each permutation, matching Cliff and Ord's free-sampling randomization scheme.

Implementation note. The engine (`core/advanced_stats_engines.py::calculate_join_counts`) deduplicates the neighbor graph into unordered pairs before counting, so asymmetric weight builders (e.g. KNN, where i being a neighbor of j does not guarantee the reverse) do not double-count or drop edges. Validated on synthetic checkerboard and left/right-split 10×10 grid fixtures: a checkerboard returns BB = 0, WW = 0, BW = 180 (100% of joins), exactly matching the theoretical extreme; a left/right split returns BB far above its permutation expectation (p = 0.002) and BW far below it, correctly identifying clustering.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
FIELD | Field | — | Numeric or text | Field converted to a binary Black/White category
WEIGHT_TYPE | Enum | Queen contiguity | Queen / Rook / KNN / Distance Band | Spatial relationship used to build the binary adjacency graph
KNN | Integer | 5 | ≥ 1 | Number of neighbors (KNN adjacency only)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (Distance Band adjacency only)
PERMUTATIONS | Integer | 999 | 99–9999 | Number of Monte Carlo permutations per join type
RANDOM_SEED | Integer | 42 | ≥ 0 | Seed for reproducible permutation results
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report

##### 4. Output Description

Field | Type | Description
--- | --- | ---
total_joins | Integer | Total number of unique neighbor pairs in the adjacency graph
n1 / n0 | Integer | Count of Black (1) and White (0) features after binarization
bb / ww / bw | Object | Per-join-type result: observed count, permuted mean, permuted std., z-score, p-value

##### 5. Interpretation Guide

Reading the three join counts together.

Signal | Meaning | Recommended Next Step
--- | --- | ---
BB significant, above expectation | The category clusters together | Map matching features directly, or run Local Moran's I / Getis-Ord Gi* on a continuous proxy for the same category.
WW significant, above expectation | The complement clusters together | Consider whether the complement itself is the more policy-relevant category to map.
BW significant, above expectation | Category is interspersed / checkerboarded | Investigate whether this reflects a genuine fine-grained mixed pattern or a data-coding artifact (e.g. alternating parcel or survey IDs).
None significant | Random spatial arrangement | No further spatial follow-up needed for this coding; consider a different threshold or field if clustering is expected but not detected.

A non-significant BW is not confirmation of clustering. A common misreading is to treat "BW is not significant" as proof the category clusters. It is not — BW near its expected value under CSR is simply uninformative on its own. Clustering is established by a significant BB (or WW) count, not by the absence of a significant BW. Always report the full trio, not a single count in isolation.

See also: Geary's C · Local Moran's I (LISA) · Data Readiness Audit

##### 6. Literature

Dacey, M.F. (1968). "A Review on Measures of Contiguity for Two and K-Color Maps." In B.J.L. Berry & D.F. Marble (eds.), Spatial Analysis: A Reader in Statistical Geography, pp. 479–495. Englewood Cliffs: Prentice-Hall. — Earliest systematic review of contiguity/join-count measures for categorical maps.

Cliff, A.D. & Ord, J.K. (1973). Spatial Autocorrelation. London: Pion. ISBN: 978-0850860200 — Formal derivation of BB/WW/BW join-count expectations and variances under free and non-free sampling.

Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. London: Pion. ISBN: 978-0850860818 — Definitive treatment placing join counts alongside Moran's I and Geary's C in a unified inferential framework.

Moran, P.A.P. (1948). "The Interpretation of Statistical Maps." Journal of the Royal Statistical Society, Series B 10(2): 243–251. — Early precedent for testing categorical spatial pattern on maps, predating the formal join-count framework.

Upton, G.J.G. & Fingleton, B. (1985). Spatial Data Analysis by Example, Volume 1: Point Pattern and Quantitative Data. Chichester: Wiley. ISBN: 978-0471900830 — Accessible worked examples of join count statistics alongside other categorical spatial-pattern tests.

Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. ISBN: 978-0521574716 — Standard reference for the Monte Carlo p-value "+1" adjustment used in the permutation inference procedure.

🧲

#### Global Bivariate Lee's L

global_bivariate_lee_l
A single study-area-wide summary of the same spatial co-clustering measure that the plugin's Bivariate Spatial Association (Lee's L) tool computes feature by feature (Lee, 2001). Global Lee's L is the Global/Local pairing that Global Moran's I has to Local Moran's I, applied to a two-variable relationship rather than one. It asks a different question than a plain Pearson correlation: whether X at one location predicts Y at nearby locations, not just Y at the same location. Under this plugin's row-standardized weights convention, Global L is mathematically exactly the mean of the local \(\ell_i\) values computed by the existing local tool — run that afterward on a significant field pair to see where the co-clustering concentrates.

##### 1. Theoretical Background

Origins. Sang-Il Lee introduced the bivariate spatial association measure in a 2001 paper in the Journal of Geographical Systems, explicitly designed to integrate Pearson's correlation coefficient with Moran's I into a single statistic. Lee's decomposition, \(L_{XY} = r_{XY} \cdot \sqrt{I_X \cdot I_Y}\), shows that Lee's L can only be large when both fields are individually spatially autocorrelated and correlated with each other — a more stringent joint test than either component alone. This plugin's existing local implementation (Group 03) already exploits this decomposition at the feature level; this global tool completes the pair by providing the single study-area summary.

Screening before mapping. Local Lee's L is descriptive/diagnostic (the plugin's existing local implementation does not currently include permutation-based significance per feature); Global Lee's L, by contrast, is given a formal permutation significance test here. This makes the recommended workflow: run Global Lee's L first as a screening step, and proceed to feature-level Local Lee's L mapping only when the global figure is significant — a non-significant Global L means local co-clustering, if any, is likely too weak or spatially scattered to interpret with confidence.

Why co-clustering differs from correlation. Two fields can be spatially co-clustered (high Global L) even with a weak or zero simple Pearson correlation, if their relationship only emerges once neighboring values are pooled together — a hallmark of spatially structured confounding or an omitted spatial process. Conversely, a strong simple correlation can coexist with a low Global L if the relationship, though real, has no spatial coherence (it holds equally everywhere, with no clustering of the correlated pairs). Reporting both a plain Pearson correlation and Global Lee's L side by side surfaces this distinction directly.

##### 2. Mathematical Formulation

Let \(z_x(i) = (x_i - \bar{x})/\sigma_x\) and \(z_y(j) = (y_j - \bar{y})/\sigma_y\) be standardized values, and \(w_{ij}\) the row-standardized spatial weight between i and j.

Local Lee's L (reused from the existing engine):

$$\ell_i = z_x(i) \cdot \sum_j w_{ij} \, z_y(j) \tag{1}$$

Global Lee's L, under row-standardized weights:

$$L_{XY} = \frac{1}{N}\sum_{i=1}^{N} \ell_i \tag{2}$$

This plugin's engine computes the global statistic exactly this way — as the mean of the local \(\ell_i\) values already produced by the plugin's local Lee's L engine — rather than re-deriving the global cross-product formula independently. This guarantees the two tools agree by construction; the plugin's own synthetic validation confirms the mean of the local values equals the reported global statistic to full numerical precision.

Permutation inference (holding X and spatial structure fixed):

$$L_{XY}^{(p)} = \text{Global Lee's L computed with Y randomly permuted, for } p = 1, \ldots, P \tag{3}$$ $$z = \frac{L_{XY,\text{obs}} - \overline{L_{XY}^{(p)}}}{\text{sd}(L_{XY}^{(p)})}, \qquad p_{\text{value}} = \frac{\#\{p : |L_{XY}^{(p)} - \overline{L_{XY}^{(p)}}| \ge |L_{XY,\text{obs}} - \overline{L_{XY}^{(p)}}|\} + 1}{P + 1} \tag{4}$$

Shuffling only Y (not X) tests specifically whether the observed spatial pairing of X and Y is distinguishable from a random pairing, given each field's own spatial structure — the standard approach for bivariate spatial permutation tests (Anselin, 1995, extended for bivariate LISA by Anselin, Syabri & Smirnov, 2002).

Implementation note. The engine (`core/advanced_stats_engines.py::calculate_global_lee_l`) calls `calculate_bivariate_lee_l()` from `stats_engines.py` — the same engine backing the local tool — once per permutation, taking the mean of the returned local values each time. Validated on synthetic 10×10 grid fixtures: a correlated and spatially clustered field pair returns L ≈ 0.96 (p = 0.002); an independent random pair returns L ≈ −0.05 (p = 0.38, correctly non-significant); critically, mean(local ℓ) was confirmed to equal the reported global L to full precision, verifying the local-to-global decomposition.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
FIELD_X | Numeric Field | — | Must have variation | Primary variable X
FIELD_Y | Numeric Field | — | Different from Field X | Neighbor-lag variable Y
WEIGHT_TYPE | Enum | Queen contiguity | Queen / Rook / KNN / Distance Band | Spatial relationship used to build the weights matrix
KNN | Integer | 5 | ≥ 1 | Number of neighbors (KNN weights only)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (Distance Band weights only)
PERMUTATIONS | Integer | 999 | 99–9999 | Number of Monte Carlo permutations for significance testing
RANDOM_SEED | Integer | 42 | ≥ 0 | Seed for reproducible permutation results
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report

##### 4. Output Description

Field | Type | Description
--- | --- | ---
observed_l | Double | Observed Global Lee's L statistic (mean of the local ℓ values)
permuted_mean | Double | Mean of L across the permutation distribution
permuted_std | Double | Standard deviation of L across the permutation distribution
z_score | Double | Standardized z-score relative to the permutation distribution
p_value | Double | Two-tailed Monte Carlo p-value

##### 5. Interpretation Guide

Reading Global Lee's L.

Condition | Meaning | Recommended Next Step
--- | --- | ---
L > 0, p < 0.05 | Positive spatial co-clustering — high X near high Y, low X near low Y | Run Local Bivariate Lee's L on the same pair to map where the co-clustering concentrates.
L < 0, p < 0.05 | Negative spatial co-clustering — high X near low Y | Run Local Bivariate Lee's L to map where the inverse relationship concentrates.
p ≥ 0.05 | No significant spatial co-clustering | Check a plain Pearson correlation as a sanity comparison; a non-spatial relationship will show up there but not here.

Not a causal test. A significant Global L establishes that two fields are spatially co-patterned; it does not establish that one causes the other, nor which direction the influence runs. Treat it as a screening and description tool — the same caveat that applies to Pearson correlation applies here, with the added spatial dimension.

See also: Bivariate Spatial Association (Lee's L) · Bivariate LISA · Global Moran's I

##### 6. Literature

Lee, S.-I. (2001). "Developing a Bivariate Spatial Association Measure: An Integration of Pearson's r and Moran's I." Journal of Geographical Systems 3(4): 369–385. DOI: 10.1007/s101090100064 — The foundational paper introducing Lee's L; Equation 2 of this card's decomposition is drawn directly from this work.

Lee, S.-I. (2009). "A Generalized Randomization Approach to Local Measures of Spatial Association." Geographical Analysis 41(3): 221–248. DOI: 10.1111/j.1538-4632.2009.00755.x — Permutation inference framework for Lee's L, the basis for this tool's significance test.

Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. DOI: 10.1111/j.1538-4632.1995.tb00338.x — Establishes the local-to-global decomposition principle (sum of local statistics proportional to the global one) that this tool's Global/Local pairing follows.

Anselin, L., Syabri, I. & Smirnov, O. (2002). "Visualizing Multivariate Spatial Correlation with Dynamically Linked Windows." In L. Anselin & S. Rey (eds.), New Tools for Spatial Data Analysis. Santa Barbara: CSISS, UCSB. — Bivariate permutation methodology (shuffle one variable, hold the other and spatial structure fixed), the approach adopted here.

Wartenberg, D. (1985). "Multivariate Spatial Correlation: A Method for Exploratory Geographical Analysis." Geographical Analysis 17(4): 263–283. DOI: 10.1111/j.1538-4632.1985.tb00849.x — Precursor multivariate spatial correlation coefficient that Lee's L builds on and generalizes.

Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. ISBN: 978-0521574716 — Standard reference for the Monte Carlo p-value "+1" adjustment used in the permutation inference procedure.

🥧

#### Geodetector Q-Statistic (Spatial Stratified Heterogeneity)

geodetector_q_statistic
A fundamentally different analytical paradigm from every other tool in this group: instead of asking "are nearby features similar" (spatial autocorrelation), the Geodetector Q-statistic (Wang et al., 2010; Wang, Zhang & Fu, 2016) asks "does this partition of the study area into categories explain the variance I see" (spatial stratified heterogeneity). No spatial weights matrix is built at all — the test compares within-stratum variance to total variance for a categorical zoning/district/classification field against a continuous outcome. Q ranges from 0 (the stratification explains nothing) to 1 (each stratum is internally uniform). The tool accepts either an existing categorical field or a continuous field to quantile-bin into strata first.

##### 1. Theoretical Background

Origins. Jin-Feng Wang and colleagues introduced the Geodetector (地理探测器) framework in a 2010 paper in the International Journal of Geographical Information Science, applying it to neural tube defect risk assessment in the Heshun region of China. The framework's core insight is that spatial heterogeneity — the tendency for a process to differ systematically across sub-regions — is a distinct phenomenon from spatial autocorrelation, and needed its own formal statistic rather than being treated as a byproduct of weights-based methods. Wang, Zhang and Fu's 2016 paper in Ecological Indicators is the canonical methodological reference for the single-factor Q-statistic implemented here, formalizing it as a general measure of "spatial stratified heterogeneity" applicable well beyond the original epidemiological context.

A different paradigm, not a competing one. Every autocorrelation statistic in this plugin (Moran's I, Geary's C, Getis-Ord Gi*, Join Counts) implicitly assumes that "spatial structure" means "value similarity decays with distance." Spatial stratified heterogeneity is a different kind of structure: a categorical partition — administrative boundaries, zoning classes, soil types, historical development eras — can explain variance in an outcome even without any smooth distance-decay relationship. A zoning field can produce a high Geodetector Q (each zone internally homogeneous, zones very different from each other) while producing an unremarkable Moran's I if the zones themselves are scattered rather than contiguous. The two paradigms are complementary, not substitutes.

The single-factor detector, and what's out of scope. The full Geodetector framework (Wang & Xu, 2017) includes four detectors: the factor detector (implemented here — does one stratification explain variance), the interaction detector (do two stratifications explain more together than separately), the risk detector (which strata differ significantly from each other), and the ecological detector (do two factors have significantly different explanatory power). This plugin implements the factor detector as a first release; the interaction and risk detectors are natural, well-scoped extensions for a future version rather than a fundamentally different technique.

Permutation inference over the classical F-approximation. Wang et al.'s original papers derive an approximate F-test for Q under the assumption of no within-stratum spatial autocorrelation. That assumption is frequently violated in planning data — features within the same zoning class are often themselves spatially clustered, which the F-approximation does not account for and which is known to make the F-test overly liberal (rejecting the null too often). This plugin instead uses permutation inference: strata labels are randomly reshuffled (holding category sizes fixed) to build an empirical null distribution for Q, sidestepping the F-test's spatial-independence assumption entirely.

##### 2. Mathematical Formulation

Let N be the number of valid features, \(y_i\) the outcome field value, and the study area partitioned into H strata (categories) with stratum h containing \(N_h\) features.

The Q-statistic:

$$q = 1 - \frac{\sum_{h=1}^{H} N_h \, \sigma_h^2}{N \, \sigma^2} \tag{1}$$

where \(\sigma_h^2\) is the variance of y within stratum h, and \(\sigma^2\) is the total variance of y across the whole study area. The numerator is the total within-stratum sum of squares (weighted by stratum size); the denominator is the total sum of squares.

Interpretation of the bounds:

$$q = 0 \iff \text{strata explain nothing (within-stratum variance} = \text{total variance)}, \qquad q = 1 \iff \text{each stratum is perfectly homogeneous} \tag{2}$$

Permutation inference (one-tailed — only large Q is of interest):

$$q^{(p)} = \text{Q-statistic computed with strata labels randomly permuted (stratum sizes fixed), for } p = 1, \ldots, P \tag{3}$$ $$z = \frac{q_{\text{obs}} - \overline{q^{(p)}}}{\text{sd}(q^{(p)})}, \qquad p_{\text{value}} = \frac{\#\{p : q^{(p)} \ge q_{\text{obs}}\} + 1}{P + 1} \tag{4}$$

The p-value is one-tailed because only a Q larger than chance is evidence of stratified heterogeneity; a Q smaller than chance has no comparable substantive interpretation.

Implementation note. The engine (`core/advanced_stats_engines.py::calculate_geodetector_q`) computes per-stratum variance directly from NumPy array masks — no spatial weights matrix is constructed. The `bin_into_quantiles()` helper turns a continuous field into strata via quantile edges when no ready-made categorical field is available. Validated on synthetic 10×10 grid fixtures: a perfect row-based stratification (rows are internally uniform, values differ sharply between rows) returns q = 1.0 (p = 0.002); an irrelevant column-based stratification of the same field returns q = 0.0 (p = 1.0), correctly failing to detect explanatory power where none exists.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
FIELD_Y | Numeric Field | — | Must have variation | Continuous outcome field to explain
STRATA_MODE | Enum | Use existing categorical field | Existing field / Quantile-bin a continuous field | Source of the stratification
FIELD_STRATA | Field | — | Different from Field Y | Stratification field (categorical, or continuous to bin)
N_BINS | Integer | 5 | 2–20 | Number of quantile bins (Quantile-bin mode only)
PERMUTATIONS | Integer | 999 | 99–9999 | Number of Monte Carlo permutations for significance testing
RANDOM_SEED | Integer | 42 | ≥ 0 | Seed for reproducible permutation results
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report

##### 4. Output Description

Field | Type | Description
--- | --- | ---
q_statistic | Double | Observed Q-statistic (0–1)
n_strata | Integer | Number of strata used
permuted_mean | Double | Mean of Q across the permutation distribution
permuted_std | Double | Standard deviation of Q across the permutation distribution
z_score | Double | Standardized z-score relative to the permutation distribution
p_value | Double | One-tailed Monte Carlo p-value
per_stratum | Object | Per-stratum sample size, mean, and standard deviation

##### 5. Interpretation Guide

Reading the Q-statistic.

Condition | Meaning | Recommended Next Step
--- | --- | ---
q ≥ 0.5, p < 0.05 | Strong spatial stratified heterogeneity | Report per-stratum means/variances to identify which categories drive the outcome; consider this factor in Multiple Regression or GWR.
0 < q < 0.5, p < 0.05 | Significant but modest heterogeneity | Test alternative stratifications, or combine with continuous predictors in a regression model.
p ≥ 0.05 | No significant stratified heterogeneity | Try a different stratification (finer/coarser bins, or a different categorical field) before concluding no spatial stratified structure exists.

Avoid near-unique strata. A stratification field with as many categories as there are features (e.g. a parcel ID mistakenly used as the strata field) will trivially inflate Q toward 1.0, since each "stratum" contains a single value and therefore has zero internal variance by construction. This is not evidence of meaningful stratified heterogeneity — it is a definitional artifact. The tool warns when the stratification field has an unusually high number of distinct categories relative to the feature count; always sanity-check per-stratum sample sizes in the output before trusting the result.

See also: Data Readiness Audit · Multiple Regression Analysis · Local Moran's I (LISA)

##### 6. Literature

Wang, J.-F., Li, X.-H., Christakos, G., Liao, Y.-L., Zhang, T., Gu, X. & Zheng, X.-Y. (2010). "Geographical Detectors-Based Health Risk Assessment and Its Application in the Neural Tube Defects Study of the Heshun Region, China." International Journal of Geographical Information Science 24(1): 107–127. DOI: 10.1080/13658810802443457 — The original Geodetector paper; introduces the factor, interaction, risk, and ecological detectors.

Wang, J.-F., Zhang, T.-L. & Fu, B.-J. (2016). "A Measure of Spatial Stratified Heterogeneity." Ecological Indicators 67: 250–256. DOI: 10.1016/j.ecolind.2016.02.052 — The canonical methodological reference for the single-factor Q-statistic implemented in this tool; generalizes Geodetector beyond its original epidemiological application.

Wang, J.-F. & Xu, C.-D. (2017). "Geodetector: Principle and Prospective." Acta Geographica Sinica 72(1): 116–134. DOI: 10.11821/dlxb201701010 — Overview of the full four-detector framework; describes the interaction, risk, and ecological detectors that are natural future extensions of this tool.

Wang, J.-F., Hu, Y. (2012). "Environmental Health Risk Detection with GeogDetector." Environmental Modelling & Software 33: 114–115. DOI: 10.1016/j.envsoft.2012.01.015 — Introduces the open-source GeoDetector software implementation, establishing the method's software-tool precedent.

Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. ISBN: 978-0521574716 — Standard reference for the Monte Carlo p-value "+1" adjustment used in the permutation inference procedure.

03

### Hot Spots and Spatial Outliers

Local spatial statistics that identify where patterns occur — the specific features or neighborhoods that drive the global patterns detected in group 02. Each tool maps a different aspect of local spatial structure: magnitude-based hot spots (Gi*), value-based clusters and outliers (LISA, Local Geary's C), cross-variable spatial association (Bivariate LISA, Lee's L), categorical point co-location (Colocation Quotient), multivariate similarity groups (K-Means), spatially contiguous regionalization (SKATER), and feature-level similarity search.

🔥

#### Hot Spot Analysis (Getis-Ord Gi*)

getis_ord_gi
The definitive local hot-spot statistic. For each feature i, Gi* evaluates whether the locally weighted sum of the target variable — including i itself and its neighbors — is significantly higher or lower than the global mean expectation. Unlike LISA (Local Moran's I), which identifies both spatial clusters and spatial outliers (HL, LH), Gi* is purely magnitude-based: it answers the directional question "where are the hot (high-value) and cold (low-value) concentrations?" This makes Gi* the preferred tool for crime hot-spot mapping, disease-cluster detection, property-value concentration analysis, and environmental-risk zoning. Output layer includes automatic cold-to-hot diverging symbology (7-class: −3 to +3 confidence bins).

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroids used for distance methods)
FIELD | Numeric Field | — | Target variable (positive values recommended; Gi* is magnitude-sensitive)
WEIGHT_TYPE | Enum | Queen | Queen contiguity / Rook contiguity / KNN / Distance Band
KNN | Integer | 5 | Number of neighbors (K value, used only when WEIGHT_TYPE = KNN)
DISTANCE_BAND | Double | 1000.0 | Distance threshold in map units (used only when WEIGHT_TYPE = Distance Band)
OUTPUT | Vector Layer | — | Output vector layer with Gi* fields and automatic hot/cold symbology

##### Output Fields

Field | Type | Content
--- | --- | ---
gi_zscore | Double | Standardized Gi* z-score; positive = hot, negative = cold
gi_pvalue | Double | Two-tailed p-value (analytic, normal approximation)
gi_conf | Integer | Confidence bin: ±3 (99%), ±2 (95%), ±1 (90%), 0 (not significant)
gi_nbrs | Integer | Count of valid spatial neighbors used in the local statistic

##### Core Equations

1. Getis-Ord Gi* statistic (star form — self-inclusive):
\[ G_i^* = \frac{\sum_j w_{ij} x_j - \bar{x} \sum_j w_{ij}} {s \sqrt{\frac{N \sum_j w_{ij}^2 - (\sum_j w_{ij})^2}{N - 1}}} \] where \(\bar{x} = \frac{1}{N}\sum_i x_i\) and \(s = \sqrt{\frac{1}{N}\sum_i x_i^2 - \bar{x}^2}\). The numerator is the deviation of the local weighted sum from the global-mean expectation; the denominator standardizes by the sample standard deviation and the local weight configuration.
2. Alternative Gi statistic (non-star — self-excluded):
\[ G_i = \frac{\sum_{j \neq i} w_{ij} x_j - \bar{x}_{(i)} \sum_{j \neq i} w_{ij}} {s_{(i)} \sqrt{\frac{(N-1) \sum_{j \neq i} w_{ij}^2 - (\sum_{j \neq i} w_{ij})^2}{N - 2}}} \] where \(\bar{x}_{(i)}\) and \(s_{(i)}\) are the mean and standard deviation computed excluding observation \(i\). Gi is used when the analyst wants to test whether the neighbors of \(i\) are hot/cold, independent of \(i\)'s own value. This plugin always uses Gi* (star form), consistent with ESRI's ArcGIS implementation.
3. Expected value and variance under randomization:
\[ \mathbb{E}[G_i^*] = \frac{\sum_j w_{ij}}{N} \qquad \operatorname{Var}[G_i^*] = \frac{\sum_j w_{ij}^2}{N} - \left(\frac{\sum_j w_{ij}}{N}\right)^2 \] Under the null hypothesis of complete spatial randomness, each location's value is equally likely to appear anywhere. The expected Gi* is proportional to the sum of weights for location \(i\); the variance accounts for the number and distribution of neighbors.
4. Z-score and p-value:
\[ z(G_i^*) = \frac{G_i^* - \mathbb{E}[G_i^*]}{\sqrt{\operatorname{Var}[G_i^*]}} \qquad p = 2\left(1 - \Phi(|z|)\right) = \operatorname{erfc}\!\left(\frac{|z|}{\sqrt{2}}\right) \] The plugin uses the standard normal CDF via the complementary error function for p-value computation. For \(p < 0.01\) the confidence bin is ±3; for \(p < 0.05\) it is ±2; for \(p < 0.10\) it is ±1.
5. Relationship to the General G (global) statistic:
\[ G(d) = \frac{\sum_i \sum_{j \neq i} w_{ij}(d) \, x_i x_j}{\sum_i \sum_{j \neq i} x_i x_j} \] The General G (Group 02) tests for global high/low clustering at distance \(d\). Gi* decomposes this global statistic into per-feature contributions, identifying which features drive the global pattern. A significant General G without significant local Gi* values may indicate a diffuse pattern rather than discrete hot/cold spots.
6. Multiple testing and the Bonferroni adjustment:
\[ \alpha_{\text{adj}} = \frac{\alpha}{N_{\text{features}}} \] Running Gi* at \(N\) locations means \(N\) simultaneous hypothesis tests. The plugin reports uncorrected p-values and confidence bins at the conventional thresholds. For conservative inference (controlling the family-wise error rate), the analyst may apply a Bonferroni correction: \(p < 0.05 / N\). For large \(N\) this becomes very stringent; Benjamini-Hochberg FDR control (Benjamini & Hochberg, 1995; de Castro & Singer, 2006) is a more practical alternative for exploratory analysis.
7. Weight matrix row-standardization in Gi*:
\[ w_{ij}^{\text{(std)}} = \frac{w_{ij}}{\sum_k w_{ik}} \] When weights are row-standardized, \(\sum_j w_{ij} = 1\) for all \(i\), and the Gi* numerator simplifies to \(\sum_j w_{ij} x_j - \bar{x}\) — the deviation of the local (neighborhood-inclusive) mean from the global mean. This plugin uses unstandardized binary weights with row-mean division (each row i's weights are averaged, not summed to 1), following the original Ord & Getis (1995) formulation which preserves the variance contribution of the number of neighbors.

##### Expanded Interpretation Guide

Confidence bins. Gi* includes the target feature itself in the local sum — hence the asterisk. `gi_conf = +3`: feature and neighbors are a 99% confidence hot spot (values significantly above the global mean). `gi_conf = −3`: 99% confidence cold spot (values significantly below the global mean). Bins ±2 and ±1 represent 95% and 90% confidence respectively. `gi_conf = 0`: the local configuration is not distinguishable from random.
When to use Gi* vs. LISA. Use Gi* when the analytic question is directional and magnitude-focused: "where are the high-crime neighborhoods?" "where is property value concentrated?" Gi* distinguishes hot from cold but does not flag spatial outliers (a high-value tract surrounded by low-value tracts will not be a hot spot). Use LISA (Local Moran's I) when the question is about spatial association patterns including outliers: "where do high values sit next to low values (potential gentrification fronts)?" The two tools are complementary — run both and compare the maps.
Neighbor-count diagnostics. `gi_nbrs` records the number of valid spatial neighbors used in the local statistic. Features with `gi_nbrs = 0` (isolated features) receive `gi_conf = 0` regardless of their value — they cannot form a hot spot with no neighbors. If more than 5% of features are isolated, the spatial weights definition is too restrictive; increase the distance band or K value. The plugin logs a warning with the isolated-feature count.
Distance-band sensitivity. Gi* results depend on the spatial weights specification. Features classified as hot spots at one distance band may not be significant at another. Best practice: run Incremental Spatial Autocorrelation (Group 02) first to identify the distance at which spatial clustering peaks; use that distance as the Gi* band threshold. For KNN weights, k = 8 is a common default; smaller k emphasizes very local patterns, larger k smooths toward the global mean. Always report the weights specification in methods sections.

##### Methodological Notes

The Gi vs. Gi* distinction (Ord & Getis, 1995). The original Getis & Ord (1992) paper defined the Gi statistic, which excludes the target feature i from the local sum. Ord & Getis (1995) introduced Gi*, which includes i. Both are valid, but they answer subtly different questions: Gi asks "are the neighbors of this location hot/cold?" while Gi* asks "is this location and its neighbors a hot/cold concentration?" Gi* is more commonly implemented (ArcGIS, GeoDa, PySAL/esda) and is what this plugin uses. The asterisk is a methodological signal, not a footnote — always use "Gi*" (not "Gi") when citing results from this tool.
Distributional assumptions. The analytic p-values assume the Gi* z-scores are approximately normally distributed under the null. This holds for moderate-to-large \(N\) with reasonably balanced neighbor counts. For very small datasets (\(N < 30\)) or highly irregular spatial configurations (e.g., a few features with hundreds of neighbors, others with 0–2), the normal approximation may be unreliable. In such cases, consider Bivariate LISA's permutation-based inference as a model, or compute permutation p-values externally. The plugin's analytic z-scores follow the exact Ord & Getis (1995) formulation using the error function.
See also: General G · Local Moran's I (LISA) · Calculate Distance Band

##### Academic References

Primary:
1. Getis, A. & Ord, J.K. (1992). "The Analysis of Spatial Association by Use of Distance Statistics." Geographical Analysis 24(3): 189–206. doi:10.1111/j.1538-4632.1992.tb00261.x — foundational paper defining Gi and Gi*
2. Ord, J.K. & Getis, A. (1995). "Local Spatial Autocorrelation Statistics: Distributional Issues and an Application." Geographical Analysis 27(4): 286–306. doi:10.1111/j.1538-4632.1995.tb00912.x — derives moments, z-scores, and the star form
3. Getis, A. & Ord, J.K. (1996). "Local Spatial Statistics: An Overview." In P. Longley & M. Batty (eds.), Spatial Analysis: Modelling in a GIS Environment, pp. 261–277. Cambridge: GeoInformation International.
4. Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. doi:10.1111/j.1538-4632.1995.tb00338.x — complementary LISA framework; Gi* and LISA are the two canonical local statistics
Methodological extensions:
5. Getis, A. & Aldstadt, J. (2004). "Constructing the Spatial Weights Matrix Using a Local Statistic." Geographical Analysis 36(2): 90–104. doi:10.1111/j.1538-4632.2004.tb01125.x — data-driven bandwidth selection for Gi*
6. Boots, B. & Tiefelsdorf, M. (2000). "Global and Local Spatial Autocorrelation in Bounded Regular Tessellations." Journal of Geographical Systems 2(4): 319–348. doi:10.1007/PL00011461 — edge effects and boundary corrections
7. de Castro, M.C. & Singer, B.H. (2006). "Controlling the False Discovery Rate: A New Application to Account for Multiple and Dependent Tests in Local Statistics of Spatial Association." Geographical Analysis 38(2): 180–208. doi:10.1111/j.0016-7363.2006.00682.x — FDR correction for multiple local tests
8. Ord, J.K. & Getis, A. (2001). "Testing for Local Spatial Autocorrelation in the Presence of Global Autocorrelation." Journal of Regional Science 41(3): 411–432. doi:10.1111/0022-4146.00224 — Gi* behavior when global autocorrelation is present
Applications and reviews:
9. Rogerson, P.A. (2001). Statistical Methods for Geography. London: SAGE. — textbook treatment of local statistics (Ch. 8)
10. Fischer, M.M. & Getis, A. (eds.) (2010). Handbook of Applied Spatial Analysis. Berlin: Springer. doi:10.1007/978-3-642-03647-7 — comprehensive review of Gi* applications
11. Chainey, S. & Ratcliffe, J. (2005). GIS and Crime Mapping. Chichester: Wiley. doi:10.1002/9781118685181 — Gi* as a crime hot-spot standard (Ch. 5–6)
12. Griffith, D.A. (2003). Spatial Autocorrelation and Spatial Filtering. Berlin: Springer. doi:10.1007/978-3-540-24806-4 — theoretical foundations of local spatial statistics
🎯

#### Cluster and Outlier Analysis (Local Moran's I / LISA)

local_moran_lisa
Anselin's Local Indicator of Spatial Association (LISA) is the foundational local spatial statistic. It decomposes Global Moran's I into per-feature contributions, classifying each feature into one of five mutually exclusive categories: High-High (HH) — a high-value feature surrounded by high-value neighbors (cluster); Low-Low (LL) — low surrounded by low (cluster); High-Low (HL) — high surrounded by low (spatial outlier, sometimes called an "oasis"); Low-High (LH) — low surrounded by high (spatial outlier, sometimes called a "doughnut hole"); and Not Significant — the local configuration is indistinguishable from spatial randomness at the chosen significance level. LISA satisfies Anselin's (1995) two criteria for a Local Indicator: (1) the sum of LISA statistics across all features is proportional to the global Moran's I, and (2) it identifies statistically significant spatial clusters and outliers. Output layer includes automatic LISA cluster symbology with five distinct colors.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroids used for distance-based weights)
FIELD | Numeric Field | — | Target numeric variable to analyze for local spatial association
WEIGHT_TYPE | Enum | Queen | Queen contiguity / Rook contiguity / K-Nearest Neighbors / Distance Band
KNN | Integer | 5 | Number of neighbors (K value, used only with KNN weights)
DISTANCE_BAND | Double | 1000.0 | Distance threshold in map units (used only with Distance Band weights)
OUTPUT | Vector Layer | — | Output layer with LISA statistics and auto-applied cluster-outlier symbology

##### Output Fields

Field | Type | Content
--- | --- | ---
lisa_i | Double | Local Moran's I value for feature i; positive = clustering, negative = dispersion
lisa_z | Double | Standardized z-score under the randomization assumption
lisa_p | Double | Two-tailed analytic p-value (normal approximation, Anselin 1995)
quadrant | String | LISA quadrant classification: HH, LL, HL, LH, or "Not Significant"
lisa_nbrs | Integer | Count of valid spatial neighbors used in the local statistic

##### Core Equations

1. Local Moran's I — the per-feature decomposition:
\[ I_i = \frac{z_i}{m_2} \sum_j w_{ij} z_j \] where \(z_i = x_i - \bar{x}\) is the deviation of feature \(i\) from the global mean, \(m_2 = \frac{1}{N}\sum_i z_i^2\) is the sample variance (second moment), and \(w_{ij}\) are the spatial weights (row-standardized or binary). The spatial lag \(\sum_j w_{ij} z_j\) is the weighted average of neighbors' deviations. A positive \(I_i\) means feature \(i\) and its neighbors deviate from the mean in the same direction (cluster); a negative \(I_i\) means they deviate in opposite directions (outlier).
2. Relationship to Global Moran's I:
\[ I = \frac{N}{S_0} \frac{\sum_i \sum_j w_{ij} z_i z_j}{\sum_i z_i^2} \qquad \sum_i I_i = \frac{S_0}{m_2} \cdot I \] where \(S_0 = \sum_i \sum_j w_{ij}\) is the sum of all weights. The sum of all Local Moran's I values is proportional to (not equal to) the Global Moran's I. This proportionality is the first criterion of a proper LISA (Anselin, 1995): the local indicators must decompose the global statistic. This allows the analyst to identify which specific locations contribute most to global autocorrelation.
3. Expected value under the randomization assumption:
\[ \mathbb{E}[I_i] = -\frac{\sum_j w_{ij}}{N - 1} \] Under the null hypothesis of spatial randomness (values randomly assigned to locations, holding the spatial configuration and marginal distribution fixed), the expected Local Moran's I is proportional to the number of neighbors and slightly negative for finite \(N\). For large \(N\) and row-standardized weights, \(\mathbb{E}[I_i] \approx -1/(N-1) \approx 0\).
4. Variance of Local Moran's I (Anselin 1995, randomization assumption):
\[ \operatorname{Var}[I_i] = \frac{w_{i(2)} (N - b_2)}{N - 1} + \frac{(w_i^2 - w_{i(2)}) (2b_2 - N)}{(N - 1)(N - 2)} - \mathbb{E}[I_i]^2 \] where \(w_i = \sum_j w_{ij}\) (row sum of weights), \(w_{i(2)} = \sum_j w_{ij}^2\) (row sum of squared weights), and \(b_2 = N \sum_i z_i^4 / (\sum_i z_i^2)^2\) is the sample kurtosis of the variable. The variance depends on the local weight configuration (number and distribution of neighbors), the global kurtosis of the variable, and the sample size. This formula is implemented exactly in the plugin's engine.
5. Z-score and quadrant classification:
\[ z(I_i) = \frac{I_i - \mathbb{E}[I_i]}{\sqrt{\operatorname{Var}[I_i]}} \qquad \text{Quadrant}(i) = \begin{cases} \text{HH} & \text{if } p < 0.05,\; z_i > 0,\; \sum_j w_{ij} z_j > 0 \\ \text{LL} & \text{if } p < 0.05,\; z_i < 0,\; \sum_j w_{ij} z_j < 0 \\ \text{HL} & \text{if } p < 0.05,\; z_i > 0,\; \sum_j w_{ij} z_j < 0 \\ \text{LH} & \text{if } p < 0.05,\; z_i < 0,\; \sum_j w_{ij} z_j > 0 \\ \text{NS} & \text{if } p \geq 0.05 \end{cases} \] Quadrant assignment uses two conditions simultaneously: the sign of the feature's own deviation from the mean (\(z_i\)) and the sign of its spatial lag (\(\sum_j w_{ij} z_j\)). Both must be individually classified; a feature can have a significant \(I_i\) but still be labeled NS if the individual components straddle zero.
6. Moran scatterplot coordinates (conceptual basis of quadrant labeling):
\[ \text{Horizontal axis: } z_i \quad \text{(standardized value at } i)\\ \text{Vertical axis: } \sum_j w_{ij} z_j \quad \text{(spatial lag of standardized values)} \] In the Moran scatterplot (Anselin, 1996), each feature is a point. Quadrant I (top-right, \(z_i > 0\), lag > 0) = HH cluster.
Quadrant III (bottom-left, \(z_i < 0\), lag < 0) = LL cluster.
Quadrant IV (bottom-right, \(z_i > 0\), lag < 0) = HL outlier.
Quadrant II (top-left, \(z_i < 0\), lag > 0) = LH outlier.
The slope of the OLS regression line through the Moran scatterplot equals the Global Moran's I (when weights are row-standardized). The LISA quadrants are exactly the quadrants of this plot.
7. Conditional randomization vs. total randomization inference:
\[ p_{\text{pseudo}}(I_i) = \frac{\#\{ |I_i^{(\text{perm})}| \geq |I_i^{\text{obs}}| \} + 1}{N_{\text{perm}} + 1} \] The current plugin implementation uses analytic inference (z-scores from the normal approximation to the randomization distribution, Anselin 1995). The Bivariate LISA algorithm demonstrates conditional permutation inference — shuffling neighbor values while holding the focal value fixed — which is the gold standard for LISA significance testing. For univariate LISA, the analytic z-scores are reliable when \(N > 30\) and the variable is not extremely skewed. For small datasets or highly non-normal variables, consider using Bivariate LISA as a reference, or apply the Benjamini-Hochberg FDR correction to account for multiple testing.
8. LISA with row-standardized weights:
\[ I_i^{\text{(row-std)}} = \frac{z_i}{\frac{1}{N}\sum_k z_k^2} \cdot \frac{1}{\sum_k w_{ik}} \sum_j w_{ij} z_j \] When weights are row-standardized (each row of \(\mathbf{W}\) sums to 1), the spatial lag is simply the mean of neighbors' deviations, and the LISA statistic simplifies to the product of the standardized value at \(i\) and the mean standardized value among neighbors. This makes interpretation more intuitive: HH means "feature and its neighbors are both above average"; LH means "this below-average feature is surrounded by above-average neighbors."

##### Expanded Interpretation Guide

HH (High-High) — the hot spot cluster. Both the feature and its neighbors have values significantly above the global mean. These are "spatial clusters of high values." In planning: contiguous high-income neighborhoods, crime hot spots, high-density development corridors, clusters of high-performing schools. HH features are the locations where the phenomenon is concentrated and likely reinforced by spatial processes (social interaction, spillover, common exposure to a positive factor).
LL (Low-Low) — the cold spot cluster. Both the feature and its neighbors have values significantly below the global mean. In planning: contiguous low-income areas, food deserts, areas of concentrated vacancy, clusters of low-accessibility zones. LL clusters are as analytically important as HH clusters — they identify areas of concentrated disadvantage that may require targeted policy intervention. LL is not "the absence of a hot spot"; it is a structurally distinct spatial configuration.
HL (High-Low) — the "oasis" spatial outlier. A high-value feature surrounded by low-value neighbors. In planning: a high-performing school in a disadvantaged area, a luxury development in a modest neighborhood, a park in an underserved area, a high-value parcel surrounded by lower-value ones. HL outliers are potential signals of gentrification fronts, policy success stories, or data errors (a single feature coded incorrectly). These always merit qualitative investigation — a map cannot explain why the contrast exists.
LH (Low-High) — the "doughnut hole" spatial outlier. A low-value feature surrounded by high-value neighbors. In planning: a vacant lot in a thriving commercial district, a low-income pocket in an affluent area, an underperforming school in a high-resource district. LH outliers are often the most policy-relevant findings — they identify places that are "falling behind" despite being surrounded by advantage, suggesting localized barriers or exclusion mechanisms.
LISA vs. Gi* — analytical complementarity. Gi* identifies magnitude-based hot/cold concentrations but cannot distinguish HH from HL or LL from LH — it only knows whether the local sum is high or low. LISA separates clusters (HH, LL) from outliers (HL, LH), revealing spatial structure that Gi* cannot see. Run both. A feature that is a hot spot (Gi* = +3) but a HL LISA outlier may indicate a single dominant high-value feature surrounded by lower-value neighbors — statistically unusual, perhaps a data entry error, perhaps a genuine spatial anomaly.
Multiple testing caution. With \(N\) features, LISA performs \(N\) separate hypothesis tests. At \(\alpha = 0.05\), roughly 5% of features will appear significant by chance alone even under complete spatial randomness. For a dataset with 1,000 features, this means ~50 false positives. Mitigations: (1) use a Bonferroni-corrected threshold \(p < 0.05/N\); (2) apply the Benjamini-Hochberg False Discovery Rate procedure; (3) use permutation-based inference (as in Bivariate LISA) which empirically constructs the reference distribution. The plugin reports uncorrected p-values; the analyst is responsible for choosing and reporting a multiple-testing correction appropriate to their research question and inferential standards.

##### Methodological Notes

The LISA criteria (Anselin, 1995). For a statistic to qualify as a Local Indicator of Spatial Association, it must satisfy: (1) \(\sum_i I_i \propto I\), the sum of local values is proportional to the global statistic, enabling decomposition; and (2) the local statistic identifies "significant spatial clustering around an individual location" (Anselin, 1995, p. 94). Local Moran's I satisfies both; Gi* satisfies the second but not strictly the first (\(\sum_i G_i^*\) is not proportional to General G). This is why LISA and Gi* are complementary rather than substitutes.
Kurtosis dependence. The variance of Local Moran's I (Equation 4) depends on the sample kurtosis \(b_2\) of the target variable. Variables with heavy tails (high kurtosis) inflate the variance, making it harder to detect significant local clustering. If \(b_2\) is very large (e.g., for a variable with extreme outliers), the z-scores will be conservative — significant clusters may be missed. Consider transforming the variable (log, Box-Cox) or using permutation inference (which is robust to distributional shape) if kurtosis is a concern. The plugin's Data Readiness Audit (Group 00) reports kurtosis for all selected fields.
See also: Getis-Ord Gi* · Bivariate LISA · Global Moran's I

##### Academic References

Primary:
1. Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. doi:10.1111/j.1538-4632.1995.tb00338.x — the canonical LISA paper; defines the criteria, derives the moments, introduces the Moran scatterplot
2. Anselin, L. (1996). "The Moran Scatterplot as an ESDA Tool to Assess Local Instability in Spatial Association." In M. Fischer, H. Scholten & D. Unwin (eds.), Spatial Analytical Perspectives on GIS, pp. 111–125. London: Taylor & Francis.
3. Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. London: Pion. — foundations of spatial autocorrelation theory underlying LISA
4. Anselin, L. (2019). "A Local Indicator of Multivariate Spatial Association: Extending Geary's c." Geographical Analysis 51(2): 133–150. doi:10.1111/gean.12164 — multivariate extension of the LISA framework
Distributional and inferential theory:
5. Sokal, R.R., Oden, N.L. & Thomson, B.A. (1998). "Local Spatial Autocorrelation in Biological Variables." Biological Journal of the Linnean Society 65(1): 41–62. doi:10.1006/bijl.1998.0253
6. Ord, J.K. & Getis, A. (1995). "Local Spatial Autocorrelation Statistics: Distributional Issues and an Application." Geographical Analysis 27(4): 286–306. doi:10.1111/j.1538-4632.1995.tb00912.x — complementary distribution theory for local statistics
7. de Castro, M.C. & Singer, B.H. (2006). "Controlling the False Discovery Rate: A New Application to Account for Multiple and Dependent Tests in Local Statistics of Spatial Association." Geographical Analysis 38(2): 180–208. doi:10.1111/j.0016-7363.2006.00682.x
Textbook treatments and software:
8. Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22. doi:10.1111/j.0016-7363.2005.00671.x — GeoDa workbook; the canonical LISA software implementation
9. Haining, R.P. (2003). Spatial Data Analysis: Theory and Practice. Cambridge: Cambridge University Press. doi:10.1017/CBO9780511754944
10. Fortin, M.-J. & Dale, M.R.T. (2005). Spatial Analysis: A Guide for Ecologists. Cambridge: Cambridge University Press.
11. Bivand, R.S., Pebesma, E. & Gomez-Rubio, V. (2013). Applied Spatial Data Analysis with R (2nd ed.). New York: Springer. doi:10.1007/978-1-4614-7618-4 — Ch. 9 covers LISA in the `spdep` package
12. Griffith, D.A. & Layne, L.J. (1999). A Casebook for Spatial Statistical Data Analysis: A Compilation of Analyses of Different Thematic Datasets. New York: Oxford University Press.
🔗

#### Bivariate Cluster and Outlier Analysis (Bivariate LISA)PERMUTATION

bivariate_lisa
Extends Anselin's LISA framework to two variables, evaluating the spatial association between variable \(X\) at location \(i\) and variable \(Y\) at neighboring locations \(j\). This is the canonical tool for answering cross-variable spatial questions: "are high-income tracts surrounded by high-education tracts?" "Are areas with high air-pollution levels adjacent to neighborhoods with elevated asthma rates?" "Do parcels with high land values cluster around areas with good transit accessibility?" Includes conditional permutation-based inference (999 permutations default), which is the gold standard for local significance testing because it makes no distributional assumptions about the bivariate relationship. The quadrant labels follow the X-at-i / Y-at-neighbor convention: HH means "high X here, high Y nearby."

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry)
FIELD_X | Numeric Field | — | Variable at the target location \(i\) (the "focal" variable)
FIELD_Y | Numeric Field | — | Variable at neighboring locations \(j\) (the "lag" variable)
WEIGHT_TYPE | Enum | Queen | Queen contiguity / Rook contiguity / KNN / Distance Band
KNN | Integer | 5 | Number of neighbors (K value, KNN weights only)
DISTANCE_BAND | Double | 1000.0 | Distance threshold in map units (Distance Band weights only)
PERMUTATIONS | Integer | 999 | Number of conditional permutations for inference (99–9999); higher = more precise p-values
OUTPUT | Vector Layer | — | Output layer with bivariate LISA fields and auto-applied LISA symbology

##### Output Fields

Field | Type | Content
--- | --- | ---
bilisa_i | Double | Bivariate Local Moran's I: \(I_i^{XY} = z_x(i) \cdot \sum_j w_{ij} z_y(j)\)
bilisa_z | Double | Pseudo z-score from permutation distribution: \((I_i - \bar{I}_{\text{perm}}) / \sigma_{\text{perm}}\)
bilisa_p | Double | Pseudo p-value: \((\#\{|I_{\text{perm}}| \geq |I_{\text{obs}}|\} + 1) / (N_{\text{perm}} + 1)\)
quadrant | String | Bivariate LISA class: HH, LL, HL, LH, or "Not Significant"
bilisa_nb | Integer | Count of valid spatial neighbors (for weight-adequacy diagnostics)

##### Core Equations

1. Bivariate Local Moran's I — the fundamental form:
\[ I_i^{XY} = z_x(i) \sum_j w_{ij} \, z_y(j) \] where \(z_x(i) = \frac{x_i - \bar{x}}{\sigma_x}\) and \(z_y(j) = \frac{y_j - \bar{y}}{\sigma_y}\) are z-score standardized values. The spatial lag \(\sum_j w_{ij} z_y(j)\) is the weighted average of Y's standardized values among the neighbors of \(i\). The product \(z_x(i) \cdot \text{lag}_Y(i)\) measures whether \(X\) at \(i\) and the neighborhood \(Y\) deviate in the same direction (positive association) or opposite directions (negative association). Weights are normalized to sum to 1 for each row to make the spatial lag a meaningful local average.
2. Global Bivariate Moran's I — the sum of locals:
\[ I^{XY} = \frac{N}{S_0} \frac{\sum_i \sum_j w_{ij} (x_i - \bar{x})(y_j - \bar{y})} {\sqrt{\sum_i (x_i - \bar{x})^2} \sqrt{\sum_i (y_i - \bar{y})^2}} \] where \(S_0 = \sum_i \sum_j w_{ij}\). This is the bivariate analogue of Global Moran's I. It measures whether the spatial cross-covariance is different from zero. The local statistics \(I_i^{XY}\) decompose this global measure: \(\sum_i I_i^{XY} \propto I^{XY}\). A significant global bivariate I is necessary (but not sufficient) for meaningful local bivariate clusters.
3. Asymmetry of bivariate LISA:
\[ I_i^{XY} \neq I_i^{YX} \] Bivariate LISA is not symmetric. \(I_i^{XY}\) (X at i, Y at neighbors) answers a different question from \(I_i^{YX}\) (Y at i, X at neighbors). For full bivariate spatial characterization, run both directions. Example: \(I_i^{XY}\) with X = income, Y = education asks "are high-income tracts surrounded by high-education tracts?" while \(I_i^{YX}\) asks "are high-education tracts surrounded by high-income tracts?" Both may be significant, but their spatial patterns will differ because the spatial distribution of income differs from the spatial distribution of education.
4. Conditional permutation inference:
\[ p_i = \frac{\#\{ |I_i^{(\text{perm})}| \geq |I_i^{\text{obs}}| \} + 1}{N_{\text{perm}} + 1} \] Unlike univariate LISA (which uses analytic z-scores), bivariate LISA uses conditional permutation: for each location \(i\), the values of \(Y\) at \(i\)'s neighbors are randomly reassigned (drawn from all other locations' \(Y\) values while holding \(X_i\) fixed), and \(I_i\) is recomputed. This preserves the marginal distributions of both variables and the spatial configuration while breaking any bivariate spatial association. The "+1" in numerator and denominator prevents p-values of exactly zero and ensures the test is well-calibrated for any number of permutations (Davison & Hinkley, 1997).
5. Pseudo z-score from the permutation distribution:
\[ z_i = \frac{I_i^{\text{obs}} - \bar{I}_i^{\text{perm}}}{\sigma_i^{\text{perm}}} \] where \(\bar{I}_i^{\text{perm}}\) and \(\sigma_i^{\text{perm}}\) are the mean and standard deviation of the permutation distribution for location \(i\). This is a descriptive z-score (not used for inference — the pseudo p-value from Equation 4 is the actual significance test). It allows mapping the strength of bivariate association on a standardized scale comparable across locations, even though the inference is nonparametric.
6. Relationship to Lee's L:
The global bivariate Moran's I (Equation 2) captures only the spatial cross-covariance. Lee (2001) showed that it can be decomposed as: \[ I^{XY} = r_{XY} \cdot \sqrt{I_X \cdot I_Y} \] where \(r_{XY}\) is the Pearson correlation and \(I_X, I_Y\) are the univariate Global Moran's I values. Lee's L integrates these components into a single measure. Bivariate LISA provides the local decomposition — mapping where the bivariate association is strongest — while Lee's L provides the global summary. Use both: Lee's L first to test whether bivariate spatial association exists globally, then bivariate LISA to locate it.
7. Missing data handling:
Only features with complete (non-null) values for both X and Y are included. Features with null values in either field are excluded from the analysis and receive null output values. The permutation procedure only samples from the set of complete observations, ensuring valid reference distributions. The plugin logs the count of excluded features; if more than ~10% of records are excluded, consider imputation or investigate whether missingness is spatially patterned (which could bias results).

##### Expanded Interpretation Guide

Quadrant interpretation (X-at-i / Y-at-neighbor convention). HH: High X at location i, high Y among neighbors. The tract has high income and its neighbors have high education. This is a bivariate spatial cluster — the two phenomena concentrate together in space.
LL: Low X at i, low Y among neighbors. Low-income tract surrounded by low-education neighbors. These are areas of concentrated dual disadvantage.
HL: High X at i, low Y among neighbors. A spatial bivariate outlier — e.g., a high-income enclave in a low-education area. May signal gentrification, a gated community, or a data error.
LH: Low X at i, high Y among neighbors. A spatial bivariate outlier — e.g., a low-income pocket in a highly-educated area. May signal student housing, service-worker quarters, or social housing in an affluent district.
Choosing the X and Y variables. The direction matters. Convention places the causal or policy-relevant variable as X (at i) and the contextual or exposure variable as Y (at neighbors). Example: if studying how neighborhood poverty (context) affects individual health outcomes (outcome), put health as X and poverty as Y — the question is "are low-health areas surrounded by high-poverty areas?" (LH cluster). If studying how transit investment (policy lever) affects nearby land values (outcome), put land value as X and transit accessibility as Y. The interpretation changes with the assignment; document your choice and run both directions if the causal direction is ambiguous.
Permutation count and precision. With 999 permutations, the minimum achievable p-value is \(1/(999+1) \approx 0.001\). This is adequate for the conventional \(\alpha = 0.05\) threshold. For more precise p-values (e.g., for multiple-testing correction at \(\alpha = 0.05/N\)), increase permutations to 4,999 (minimum \(p \approx 0.0002\)) or 9,999 (minimum \(p \approx 0.0001\)). Higher permutation counts increase runtime linearly: each additional 1,000 permutations adds ~1 second per feature at typical dataset sizes.
Comparing with univariate results. Run univariate LISA on X alone and Y alone before running bivariate LISA. Features that are HH in both the univariate X-LISA and the bivariate X-Y LISA suggest that the spatial clustering of X and the cross-association with Y co-occur — a stronger finding than either alone. Features that are HH in bivariate LISA but NS in univariate X-LISA suggest that the local X value is not itself extreme, but it is surrounded by high Y values — an interesting configuration worth investigating qualitatively.

##### Methodological Notes

Conditional vs. total randomization. Bivariate LISA uses conditional permutation: for each location \(i\), only the neighbor values are shuffled while the focal value \(X_i\) is held fixed. This is the correct procedure for local inference because the null hypothesis is "no bivariate spatial association at this specific location," not "no association anywhere." Total randomization (shuffling all values globally) would confuse the absence of global bivariate association with the absence of a local bivariate association at a particular location. Anselin (1995, p. 97) explicitly recommends conditional randomization for local indicators.
Historical context. Bivariate spatial correlation was first formalized by Wartenberg (1985) as a "multivariate spatial correlation" concept, building on Mantel (1967). Anselin et al. (2002) operationalized it as bivariate LISA in the GeoDa software. The current implementation in GeoStats Lab follows the Anselin et al. (2002) formulation with conditional permutation inference. Wartenberg's coefficient is equivalent to the numerator of the global bivariate Moran's I; the full statistic adds the standardization by the product of standard deviations, making it comparable across variable pairs on different scales.
See also: Bivariate Lee's L · Local Moran's I (LISA)

##### Academic References

Primary (bivariate LISA):
1. Anselin, L., Syabri, I. & Smirnov, O. (2002). "Visualizing Multivariate Spatial Correlation with Dynamically Linked Windows." In L. Anselin & S. Rey (eds.), New Tools for Spatial Data Analysis: Proceedings of the Specialist Meeting. Santa Barbara: Center for Spatially Integrated Social Science, UCSB. — the original bivariate LISA operationalization
2. Anselin, L. (2019). "A Local Indicator of Multivariate Spatial Association: Extending Geary's c." Geographical Analysis 51(2): 133–150. doi:10.1111/gean.12164 — formal extension of LISA to multivariate settings
3. Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. doi:10.1111/j.1538-4632.1995.tb00338.x — univariate LISA foundations; conditional randomization justification (p. 97)
Spatial cross-correlation foundations:
4. Wartenberg, D. (1985). "Multivariate Spatial Correlation: A Method for Exploratory Geographical Analysis." Geographical Analysis 17(4): 263–283. doi:10.1111/j.1538-4632.1985.tb00849.x — first multivariate spatial correlation coefficient
5. Lee, S.-I. (2001). "Developing a Bivariate Spatial Association Measure: An Integration of Pearson's r and Moran's I." Journal of Geographical Systems 3(4): 369–385. doi:10.1007/s101090100064 — decomposition of bivariate spatial association into correlation and autocorrelation components
6. Mantel, N. (1967). "The Detection of Disease Clustering and a Generalized Regression Approach." Cancer Research 27(2): 209–220. — precursor to spatial cross-product statistics
Inference and methodology:
7. Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. — permutation test theory; the "+1" adjustment for p-values
8. de Castro, M.C. & Singer, B.H. (2006). "Controlling the False Discovery Rate." Geographical Analysis 38(2): 180–208. doi:10.1111/j.0016-7363.2006.00682.x
Applications and software:
9. Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22. doi:10.1111/j.0016-7363.2005.00671.x
10. Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In M.M. Fischer & A. Getis (eds.), Handbook of Applied Spatial Analysis, pp. 175–193. Berlin: Springer. doi:10.1007/978-3-642-03647-7_11
11. Bivand, R.S., Pebesma, E. & Gomez-Rubio, V. (2013). Applied Spatial Data Analysis with R (2nd ed.). New York: Springer. doi:10.1007/978-1-4614-7618-4 — Ch. 9: bivariate LISA in the spdep package
12. Griffith, D.A. & Paelinck, J.H.P. (2011). Non-standard Spatial Statistics and Spatial Econometrics. Berlin: Springer. doi:10.1007/978-3-642-21543-8
🔀

#### Bivariate Spatial Association (Lee's L)

bivariate_spatial_association_lees_l
Lee's L (Lee, 2001) integrates Pearson's correlation with spatial autocorrelation into a single bivariate spatial association measure. It answers a question that neither Pearson's r nor Moran's I can address alone: is the correlation between two variables itself spatially structured? Two variables can be strongly correlated (\(r \approx 0.8\)) but with that correlation driven entirely by a few geographic regions; or weakly correlated globally (\(r \approx 0.1\)) but with strong local spatial co-patterning. Lee's L quantifies the overall strength of the bivariate spatial association, combining both the aspatial relationship and its spatial configuration. The plugin implements a local Lee's L decomposition that classifies each feature into one of five bivariate association classes: High-X/High-Y Lag, Low-X/Low-Y Lag, High-X/Low-Y Lag, Low-X/High-Y Lag, and Not Significant. Use as a screening tool before committing to bivariate LISA.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry)
FIELD_X | Numeric Field | — | Primary variable X (focal variable at location \(i\))
FIELD_Y | Numeric Field | — | Neighbor-lag variable Y (the variable whose spatial lag is computed)
WEIGHT_TYPE | Enum | KNN | Queen contiguity / Rook contiguity / KNN / Distance Band
KNN | Integer | 5 | Number of neighbors (K value, KNN weights only)
DISTANCE_BAND | Double | 1000.0 | Distance threshold in map units (Distance Band weights only)
OUTPUT | Vector Layer | — | Output layer with Lee's L fields and auto-applied association styling

##### Output Fields

Field | Type | Content
--- | --- | ---
lee_l | Double | Local Lee's L value: \(z_x(i) \cdot \sum_j w_{ij} z_y(j)\) — product of standardized X at \(i\) and the spatial lag of standardized Y
y_lag_z | Double | Spatial lag of standardized Y at location \(i\): \(\sum_j w_{ij} z_y(j)\)
lee_class | String | Bivariate association class: High-X/High-Y Lag, Low-X/Low-Y Lag, High-X/Low-Y Lag, Low-X/High-Y Lag, or Not Significant
lee_nbrs | Integer | Count of valid spatial neighbors used for the local lag computation

##### Core Equations

1. Global Lee's L — the integration of Pearson's r and Moran's I:
\[ L_{XY} = \frac{N}{\sum_i \sum_j w_{ij}} \cdot \frac{\sum_i \left[(x_i - \bar{x}) \sum_j w_{ij} (y_j - \bar{y})\right]} {\sqrt{\sum_i (x_i - \bar{x})^2} \sqrt{\sum_i (y_i - \bar{y})^2}} \] The numerator \(\sum_i (x_i - \bar{x}) \sum_j w_{ij} (y_j - \bar{y})\) is a spatial cross-product: it is large when locations with high X have neighbors with high Y, and locations with low X have neighbors with low Y. The denominator standardizes by the product of standard deviations, bounding \(L_{XY}\) in \([-1, 1]\) under row-standardized weights.
2. Lee's decomposition — Pearson's r times the spatial autocorrelation geometric mean:
\[ L_{XY} = r_{XY} \cdot \sqrt{I_X \cdot I_Y} \] where \(r_{XY} = \frac{\sum_i (x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_i (x_i-\bar{x})^2 \sum_i (y_i-\bar{y})^2}}\) is the Pearson correlation, and \(I_X, I_Y\) are the univariate Global Moran's I statistics for X and Y respectively (with row-standardized weights). This decomposition reveals that Lee's L can only be large when both variables are spatially autocorrelated and correlated with each other. If either component is near zero, Lee's L will be near zero regardless of the other. This makes Lee's L a more stringent test of bivariate spatial association than the global bivariate Moran's I.
3. Local Lee's L — the per-feature decomposition:
\[ \ell_i = z_x(i) \cdot \sum_j w_{ij} \, z_y(j) \] where \(z_x(i) = (x_i - \bar{x})/\sigma_x\) and \(z_y(j) = (y_j - \bar{y})/\sigma_y\). This is the local contribution of feature \(i\) to the global Lee's L. The sum \(\sum_i \ell_i\) is proportional to (though not equal to) the global \(L_{XY}\). Positive \(\ell_i\) indicates that \(x_i\) and the neighborhood Y-deviation point in the same direction (both above or both below their respective means); negative \(\ell_i\) indicates opposite directions.
4. Local Lee's L classification rules:
\[ \text{Class}(i) = \begin{cases} \text{High-X / High-Y Lag} & \text{if } \ell_i > 0,\; z_x(i) > 0,\; \sum_j w_{ij} z_y(j) > 0 \\ \text{Low-X / Low-Y Lag} & \text{if } \ell_i > 0,\; z_x(i) < 0,\; \sum_j w_{ij} z_y(j) < 0 \\ \text{High-X / Low-Y Lag} & \text{if } \ell_i < 0,\; z_x(i) > 0,\; \sum_j w_{ij} z_y(j) < 0 \\ \text{Low-X / High-Y Lag} & \text{if } \ell_i < 0,\; z_x(i) < 0,\; \sum_j w_{ij} z_y(j) > 0 \\ \text{Not Significant} & \text{otherwise (no permutation inference in current impl.)} \end{cases} \] Note: The current plugin implementation classifies all features (regardless of magnitude) into these four classes. There is no formal significance test (no permutation inference for Lee's L). Treat the classification as descriptive/diagnostic rather than inferential. The Bivariate LISA algorithm should be used for formal hypothesis testing with permutation-based p-values.
5. Relationship to the bivariate Moran scatterplot:
\[ \text{Bivariate Moran scatterplot axes:} \quad z_x(i) \;\text{(horizontal)} \quad\text{vs.}\quad \sum_j w_{ij} z_y(j) \;\text{(vertical)} \] The Lee's L local classification corresponds to the quadrants of the bivariate Moran scatterplot: Quadrant I (top-right) = High-X / High-Y Lag; Quadrant III (bottom-left) = Low-X / Low-Y Lag; Quadrant IV (bottom-right) = High-X / Low-Y Lag; Quadrant II (top-left) = Low-X / High-Y Lag. The slope of the regression line through this scatterplot equals the global Lee's L (analogous to how the slope through the univariate Moran scatterplot equals Moran's I). This geometric interpretation makes Lee's L intuitive to explain to non-specialist audiences.
6. Weights and standardization in Lee's L:
\[ w_{ij}^{\text{(std)}} = \frac{w_{ij}}{\sum_k w_{ik}} \] The plugin row-standardizes spatial weights before computing the spatial lag. Row-standardization ensures that \(\sum_j w_{ij} z_y(j)\) is a true local mean of the neighboring Y-values (in z-score units), making it interpretable regardless of how many neighbors each feature has. Without row-standardization, features with many neighbors would have systematically larger spatial lags, conflating the spatial association with the neighborhood size. Row-standardization also bounds the global Lee's L in \([-1, 1]\), facilitating comparison across different variable pairs and weight specifications.
7. Edge effects and isolated features:
Features with zero valid neighbors receive \(\ell_i = 0\) and a classification of "Not Significant" (since no spatial lag can be computed). Features on the edge of the study area typically have fewer neighbors and may receive noisy \(\ell_i\) estimates. KNN weights mitigate this by guaranteeing a fixed number of neighbors for all features (except those fully isolated by null values). For contiguity-based weights, edge effects are inherent — document the percentage of features with fewer than 3 neighbors as a quality metric, and consider using a distance-band or KNN specification if edge features exceed ~5% of the dataset.

##### Expanded Interpretation Guide

When to use Lee's L vs. Bivariate LISA. Lee's L is a screening tool — run it first to determine whether there is any bivariate spatial association worth exploring. If the global \(L_{XY} \approx 0\) (or the local classes are overwhelmingly "Not Significant"), bivariate LISA is unlikely to find meaningful clusters. Conversely, a strong Lee's L (\(|L| > 0.3\)) justifies investing in a full bivariate LISA with permutation inference. Lee's L is computationally cheap (no permutations); bivariate LISA is computationally intensive (999+ permutations per feature). Use Lee's L to triage, bivariate LISA to confirm.
Interpreting the decomposition. If \(L_{XY}\) is small but \(r_{XY}\) is large, the correlation exists but is not spatially organized — the relationship is aspatial. If \(L_{XY}\) is large but \(r_{XY}\) is small, the bivariate spatial association is stronger than the aspatial correlation — the spatial configuration creates a relationship that the simple scatterplot misses. This is a hallmark of spatial confounding or spatially structured omitted variables.
Planning applications. Lee's L is ideally suited for questions about spatial co-patterning of planning indicators: "do high-density development zones co-locate with high transit-ridership areas?" "Are areas of high housing-cost burden surrounded by areas of low income?" "Do parcels with high assessed value cluster near parcels with high building permit activity?" The local classification reveals which specific places exhibit each type of bivariate spatial association, enabling targeted case-study selection for qualitative follow-up.
See also: Bivariate LISA

##### Academic References

Primary:
1. Lee, S.-I. (2001). "Developing a Bivariate Spatial Association Measure: An Integration of Pearson's r and Moran's I." Journal of Geographical Systems 3(4): 369–385. doi:10.1007/s101090100064 — the foundational paper introducing Lee's L as an integrated measure
2. Lee, S.-I. (2004). "A Generalized Measure of Spatial Association." Journal of the Korean Geographical Society 39(1): 132–149.
3. Lee, S.-I. (2009). "A Generalized Randomization Approach to Local Measures of Spatial Association." Geographical Analysis 41(3): 221–248. doi:10.1111/j.1538-4632.2009.00755.x — permutation inference for Lee's L
Spatial cross-product statistics:
4. Wartenberg, D. (1985). "Multivariate Spatial Correlation: A Method for Exploratory Geographical Analysis." Geographical Analysis 17(4): 263–283. doi:10.1111/j.1538-4632.1985.tb00849.x
5. Hubert, L.J., Golledge, R.G. & Costanzo, C.M. (1981). "Generalized Procedures for Evaluating Spatial Autocorrelation." Geographical Analysis 13(3): 224–233. doi:10.1111/j.1538-4632.1981.tb00731.x
6. Getis, A. (1991). "Spatial Interaction and Spatial Autocorrelation: A Cross-Product Approach." Environment and Planning A 23(9): 1269–1277. doi:10.1068/a231269
LISA and local decomposition:
7. Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. doi:10.1111/j.1538-4632.1995.tb00338.x
8. Anselin, L. (2019). "A Local Indicator of Multivariate Spatial Association: Extending Geary's c." Geographical Analysis 51(2): 133–150. doi:10.1111/gean.12164
Textbook and software treatments:
9. Griffith, D.A. (2003). Spatial Autocorrelation and Spatial Filtering. Berlin: Springer. doi:10.1007/978-3-540-24806-4 — Ch. 4: bivariate spatial autocorrelation
10. Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, pp. 175–193. Springer. doi:10.1007/978-3-642-03647-7_11
11. Bivand, R.S., Pebesma, E. & Gomez-Rubio, V. (2013). Applied Spatial Data Analysis with R (2nd ed.). Springer. doi:10.1007/978-1-4614-7618-4
12. Tiefelsdorf, M. (2000). Modelling Spatial Processes: The Identification and Analysis of Spatial Relationships in Regression Residuals by Means of Moran's I. Berlin: Springer. doi:10.1007/BFb0058623
🧩

#### Multivariate Clustering (K-Means)

multivariate_clustering
Performs K-Means clustering on standardized (z-score) feature attributes to group observations into \(K\) clusters that maximize within-group similarity and between-group separation. K-Means is the most widely used partitioning algorithm in spatial analysis — it is fast, interpretable, and deterministic (given a fixed random seed). While not inherently spatial (the algorithm operates in attribute space and ignores geometry), mapping the resulting clusters onto geography reveals whether places with similar attribute profiles are spatially adjacent — a critical diagnostic for understanding whether "place types" have a geographic logic. Output includes automatic categorical symbology with 10 distinct qualitative colors, cluster-size diagnostics (clust_size), and centroid-distance metrics (clust_dist) for within-cluster coherence assessment.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry)
FIELDS | Field (multi) | — | Numeric fields defining the multivariate attribute space for clustering
K_CLUSTERS | Integer | 3 | Number of clusters K (minimum 2; practical range 2–30)
OUTPUT | Vector Layer | — | Output layer with `cluster_id`, `clust_size`, and `clust_dist` fields

##### Output Fields

Field | Type | Content
--- | --- | ---
cluster_id | Integer | Cluster assignment label (0 to K−1); used for categorical map symbology
clust_size | Integer | Total number of complete-record features assigned to the same cluster
clust_dist | Double | Standardized Euclidean distance from the feature's attribute profile to its cluster centroid

##### Core Equations

1. K-Means objective — minimize within-cluster sum of squares (WCSS):
\[ \text{WCSS} = \sum_{k=1}^{K} \sum_{i \in C_k} \|\mathbf{z}_i - \boldsymbol{\mu}_k\|^2 \] where \(C_k\) is the set of observations assigned to cluster \(k\), \(\mathbf{z}_i\) is the z-score standardized attribute vector for observation \(i\), \(\boldsymbol{\mu}_k = \frac{1}{|C_k|} \sum_{i \in C_k} \mathbf{z}_i\) is the centroid of cluster \(k\), and \(\|\cdot\|\) is the Euclidean norm. The algorithm iteratively reassigns observations and recomputes centroids to minimize WCSS. WCSS always decreases or stays the same across iterations; the algorithm converges when the decrease falls below a tolerance or the maximum number of iterations is reached.
2. Z-score standardization (prevents scale-driven dominance):
\[ z_{ip} = \frac{x_{ip} - \bar{x}_p}{\sigma_p} \qquad \bar{x}_p = \frac{1}{N}\sum_i x_{ip},\quad \sigma_p = \sqrt{\frac{1}{N}\sum_i (x_{ip} - \bar{x}_p)^2} \] where \(x_{ip}\) is the raw value of variable \(p\) for observation \(i\). Standardization is essential before K-Means: without it, variables with larger numeric ranges dominate the distance computation regardless of their substantive importance. All variables contribute equally after standardization (each has mean 0, variance 1).
3. K-Means++ initialization (Arthur & Vassilvitskii, 2007):
\[ P(\text{choose } i) = \frac{D(i)^2}{\sum_{j=1}^{N} D(j)^2} \] where \(D(i)\) is the Euclidean distance from observation \(i\) to the nearest already-chosen centroid. The first centroid is chosen uniformly at random. Each subsequent centroid is chosen with probability proportional to its squared distance from the nearest existing centroid. This "seeding" strategy spreads initial centroids across the data space, dramatically reducing the probability of poor local optima compared to purely random initialization. The plugin uses a deterministic seed (default = 42) for reproducibility.
4. Lloyd's algorithm — the iterative refinement loop:
Assignment step: \(C_k^{(t)} = \{ i : \|\mathbf{z}_i - \boldsymbol{\mu}_k^{(t)}\| \leq \|\mathbf{z}_i - \boldsymbol{\mu}_j^{(t)}\| \;\forall j \}\)
Update step: \(\boldsymbol{\mu}_k^{(t+1)} = \frac{1}{|C_k^{(t)}|} \sum_{i \in C_k^{(t)}} \mathbf{z}_i\)
The algorithm alternates between these two steps until convergence. In the assignment step, each observation is assigned to the cluster whose centroid is closest (ties broken arbitrarily). In the update step, each centroid is recomputed as the mean of the observations currently assigned to it. Convergence is guaranteed because each step reduces WCSS and the number of possible partitions is finite (though potentially very large).
5. Elbow method for choosing K:
\[ \text{Elbow}(K) = \text{WCSS}(K) \] The plugin does not automatically select K — the analyst specifies it. However, a common heuristic is the elbow method: run K-Means for K = 2, 3, 4, ..., \(K_{\max}\) and plot WCSS against K. The "elbow" — where WCSS stops decreasing rapidly and begins to flatten — suggests a natural number of clusters. For planning applications, substantive interpretability should take precedence over purely statistical criteria: a 5-cluster solution that maps cleanly to known neighborhood types is preferable to a 7-cluster solution with lower WCSS but uninterpretable clusters.
6. Cluster distance — within-cluster coherence metric:
\[ d_i = \|\mathbf{z}_i - \boldsymbol{\mu}_{k(i)}\| \] where \(k(i)\) is the cluster assignment of observation \(i\). The `clust_dist` field records this standardized distance. Features with small `clust_dist` are prototypical of their cluster; features with large `clust_dist` are near the cluster boundary and could plausibly belong to a neighboring cluster. Sorting by `clust_dist` descending identifies "boundary cases" that merit qualitative review — they may represent transition zones, measurement error, or genuine hybrid cases.
7. Between-cluster separation (cluster profile comparison):
\[ \text{Inter-cluster distance}_{ab} = \|\boldsymbol{\mu}_a - \boldsymbol{\mu}_b\| \] The plugin reports cluster centroids (in standardized units) in the processing log. Clusters whose centroids are close together (small inter-cluster distance) are not well separated — their profiles are similar and the K-Means partition between them may be fragile. Large inter-cluster distances indicate clearly distinct place types. A good clustering has both: large inter-cluster distances (separation) and small intra-cluster distances (coherence).
8. Null (constant-variance) variables handling:
\[ \text{If } \sigma_p = 0: \quad z_{ip} = 0 \;\text{for all } i \] Variables with zero variance (constant across all observations) are replaced with zeros in the standardized matrix. They contribute nothing to cluster separation. The plugin warns when near-constant fields (\(\sigma_p < 10^{-9}\)) are detected, advising the analyst to remove them — they add noise to the distance computation without aiding cluster discrimination.

##### Expanded Interpretation Guide

Spatial contiguity of clusters. Map `cluster_id` and visually assess whether clusters form contiguous regions. If Cluster 2 occupies a single compact area, the attribute profile it represents has a clear spatial logic — places of that type cluster geographically, consistent with Tobler's First Law. If Cluster 2 is scattered across the map (e.g., one feature in each neighborhood), the attribute profile represents a place type that can occur anywhere — it is not spatially structured. Neither is "wrong," but they imply different analytical next steps: spatially contiguous clusters benefit from LISA/Gi* confirmation; spatially dispersed clusters suggest that geography is not the organizing dimension and that other structuring factors (policy regime, historical contingency, network position) should be investigated.
Cluster size diagnostics. Very small clusters (1–2 features) are suspicious — they may represent outliers in attribute space that K-Means isolated as singleton clusters. These are often the most interesting features for qualitative case-study selection, but they should not be treated as a "cluster type" in the same sense as the larger groups. Very large clusters (\(\gg N/K\) features) suggest that K is too small — the algorithm is merging distinct place types into an overly broad category. As a rule of thumb, no cluster should contain more than ~50% of all features.
Choosing K — substantive vs. statistical criteria. Conventional heuristics (elbow method, silhouette score, Calinski-Harabasz index) provide statistical guidance, but in planning applications interpretability trumps optimality. A K that produces clusters matching known neighborhood typologies (e.g., "urban core," "inner suburb," "outer suburb," "rural fringe") is more useful than a K with slightly better WCSS but clusters that no practitioner can name. Run multiple values of K, map each, and select the one that both minimizes WCSS and produces substantively meaningful place types. Document the K-selection rationale in methods sections.
K-Means vs. spatial clustering. K-Means is not a spatial clustering method — it does not enforce spatial contiguity. For analyses requiring spatially contiguous clusters (e.g., defining "neighborhoods" from census data), use a regionalization method (e.g., SKATER, REDCAP, or AZP available in other packages) or follow K-Means with a spatial-smoothing step. The GeoStats Lab workflow: (1) run K-Means to identify attribute-space "place types," (2) map them to assess spatial contiguity visually, (3) run LISA or Gi* on key variables to independently confirm spatial clustering, (4) if spatial contiguity is the goal, export the clustered layer and apply a regionalization method externally.
Reproducibility. K-Means results depend on initialization. The plugin uses a fixed random seed (default = 42) to ensure that repeated runs on the same data produce identical results. If you suspect the solution is a local optimum, change the seed or increase the number of random initializations. For publication-quality results, report the seed value and the number of Lloyd iterations until convergence (logged in the Processing output).

##### Methodological Notes

K-Means++ seeding. The plugin implements the K-Means++ initialization algorithm (Arthur & Vassilvitskii, 2007), which provably achieves an \(O(\log K)\) approximation to the optimal WCSS. This is a dramatic improvement over purely random initialization, which can produce arbitrarily poor clusterings with non-zero probability. The seeding procedure biases initial centroids toward well-separated points in the data, dramatically reducing the probability of converging to a poor local optimum. This is the standard initialization in scikit-learn's KMeans and is the default here.
Pure NumPy implementation. The plugin's K-Means engine is implemented entirely in NumPy — no dependency on scikit-learn or any other machine-learning library. This is by design: the K-Means algorithm is computationally simple (essentially linear algebra plus distance computations), and a pure-NumPy implementation ensures the plugin functions on any QGIS Python environment without external package installation. The tradeoff is that very large datasets (tens of thousands of features with dozens of variables) will be slower than optimized C/C++ implementations. For datasets above ~50,000 complete records, consider exporting to an external clustering environment.

##### Academic References

Primary (K-Means algorithm and initialization):
1. MacQueen, J. (1967). "Some Methods for Classification and Analysis of Multivariate Observations." In Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability, Vol. 1, pp. 281–297. Berkeley: University of California Press. — original K-Means formulation
2. Lloyd, S.P. (1982). "Least Squares Quantization in PCM." IEEE Transactions on Information Theory 28(2): 129–137. doi:10.1109/TIT.1982.1056489 — Lloyd's algorithm; originally a 1957 Bell Labs technical memorandum
3. Arthur, D. & Vassilvitskii, S. (2007). "k-means++: The Advantages of Careful Seeding." In Proceedings of the 18th Annual ACM-SIAM Symposium on Discrete Algorithms (SODA), pp. 1027–1035. — K-Means++ initialization with \(O(\log K)\) approximation guarantee
Cluster validation:
4. Hartigan, J.A. & Wong, M.A. (1979). "Algorithm AS 136: A K-Means Clustering Algorithm." Journal of the Royal Statistical Society C (Applied Statistics) 28(1): 100–108. doi:10.2307/2346830
5. Calinski, T. & Harabasz, J. (1974). "A Dendrite Method for Cluster Analysis." Communications in Statistics — Theory and Methods 3(1): 1–27. doi:10.1080/03610927408827101 — Calinski-Harabasz index for determining number of clusters
6. Rousseeuw, P.J. (1987). "Silhouettes: A Graphical Aid to the Interpretation and Validation of Cluster Analysis." Journal of Computational and Applied Mathematics 20: 53–65. doi:10.1016/0377-0427(87)90125-7 — silhouette score for within-cluster coherence
Reviews and methodology:
7. Jain, A.K. (2010). "Data Clustering: 50 Years Beyond K-Means." Pattern Recognition Letters 31(8): 651–666. doi:10.1016/j.patrec.2009.09.011 — comprehensive historical and methodological review
8. Milligan, G.W. & Cooper, M.C. (1985). "An Examination of Procedures for Determining the Number of Clusters in a Data Set." Psychometrika 50(2): 159–179. doi:10.1007/BF02294245 — comparison of 30 K-selection methods
9. Everitt, B.S., Landau, S., Leese, M. & Stahl, D. (2011). Cluster Analysis (5th ed.). Chichester: Wiley. — comprehensive textbook treatment
Spatial applications:
10. Openshaw, S. (1977). "A Geographical Solution to Scale and Aggregation Problems in Region-Building, Partitioning and Spatial Modelling." Transactions of the Institute of British Geographers 2(4): 459–472. doi:10.2307/622300 — MAUP implications for spatial clustering; seminal paper on the modifiable areal unit problem
11. Kaufman, L. & Rousseeuw, P.J. (1990). Finding Groups in Data: An Introduction to Cluster Analysis. New York: Wiley. doi:10.1002/9780470316801
12. Assuncao, R.M., Neves, M.C., Camara, G. & Freitas, C.D.C. (2006). "Efficient Regionalization Techniques for Socio-Economic Geographical Units Using Minimum Spanning Trees." International Journal of Geographical Information Science 20(7): 797–811. doi:10.1080/13658810600665111 — SKATER regionalization as a spatial alternative to K-Means
🔎

#### Similarity Search

similarity_search
Finds the features most multivariate-similar to a user-selected reference profile (one or more target features identified via a QGIS expression) based on standardized attribute distance. This is the computational implementation of "find me more neighborhoods like this one" — an exploratory tool that bridges attribute-space proximity and case-study selection. The tool computes z-score standardized distances (Euclidean or Manhattan) between every candidate feature and the centroid of the target-feature profile, ranks candidates by similarity, and outputs a vector layer with ranked similarity scores, percentile ranks, and tier labels (Top 10, High, Moderate, Low). Output includes graduated symbology from high-similarity (green) to low-similarity (amber). Unlike K-Means clustering (which groups all features into mutually exclusive categories), Similarity Search is reference-centric — it answers "what is similar to these features?" rather than "what groups exist in the data?"

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry)
FIELDS | Field (multi) | — | Numeric fields defining the multivariate similarity profile
TARGET_EXPRESSION | Expression | — | QGIS expression selecting target features (e.g., `"NAME" = 'Downtown'` or `"fid" = 42`)
METRIC | Enum | Euclidean | Euclidean distance (\(L_2\)) or Manhattan distance (\(L_1\))
OUTPUT | Vector Layer | — | Output layer with similarity scores, ranks, percentile, and tier classification

##### Output Fields

Field | Type | Content
--- | --- | ---
is_target | Integer | 1 if the feature matched the target expression, 0 otherwise
sim_index | Double | Standardized profile distance to target centroid; lower = more similar
sim_rank | Integer | Candidate rank (1 = most similar non-target feature); targets = 0
sim_pct | Double | Percentile rank among candidates (100 = most similar candidate)
sim_tier | String | Similarity tier: Target, Top 10, High, Moderate, or Low

##### Core Equations

1. Z-score standardization (all fields contribute equally):
\[ z_{ip} = \frac{x_{ip} - \bar{x}_p}{\sigma_p} \qquad\text{where}\quad \bar{x}_p = \frac{1}{N}\sum_i x_{ip},\quad \sigma_p = \sqrt{\frac{1}{N}\sum_i (x_{ip} - \bar{x}_p)^2} \] Standardization is essential: without it, a variable measured in dollars would dominate a variable measured in percentages, regardless of substantive importance. All variables contribute equally to the similarity score after standardization. Variables with \(\sigma_p = 0\) (constant) are set to \(\sigma_p = 1\) to avoid division by zero.
2. Target profile — centroid of the target set:
\[ \mathbf{t} = \frac{1}{|T|} \sum_{i \in T} \mathbf{z}_i \] where \(T\) is the set of features matching the target expression. If multiple features are selected as targets, their mean standardized profile \(\mathbf{t}\) is the reference point against which all candidates are compared. This allows "find me neighborhoods like these three" queries — the target profile is the centroid of the selected set.
3. Euclidean distance (\(L_2\) norm — default metric):
\[ d_i^{(2)} = \|\mathbf{z}_i - \mathbf{t}\|_2 = \sqrt{\sum_{p=1}^{P} (z_{ip} - t_p)^2} \] Euclidean distance penalizes large deviations in any single variable heavily (due to squaring). It is sensitive to outliers and emphasizes variables where the candidate differs most from the target. This is the default because it corresponds to the geometric notion of "distance" in multivariate space and is the standard choice for nearest-neighbor similarity.
4. Manhattan distance (\(L_1\) norm — alternative metric):
\[ d_i^{(1)} = \|\mathbf{z}_i - \mathbf{t}\|_1 = \sum_{p=1}^{P} |z_{ip} - t_p| \] Manhattan distance penalizes deviations linearly rather than quadratically. It is more robust to outliers than Euclidean distance — a single large deviation does not dominate the score. Choose Manhattan when the dataset contains known outliers or when a "sum of absolute differences" interpretation is more intuitive for the audience. Manhattan distances are always \(\geq\) Euclidean distances for the same profile: \(\|\mathbf{z} - \mathbf{t}\|_1 \geq \|\mathbf{z} - \mathbf{t}\|_2\).
5. Similarity percentile (relative rank among candidates):
\[ \text{pct}_i = 100 \times \frac{N_{\text{cand}} - \text{rank}_i + 1}{N_{\text{cand}}} \] where \(N_{\text{cand}}\) is the number of non-target candidate features. The most similar candidate (rank = 1) receives a percentile near 100; the least similar candidate receives a percentile near \(100/N_{\text{cand}}\). Percentiles are bounded in \([0, 100]\) and are more interpretable than raw distance scores, which have no natural scale.
6. Similarity tier classification:
\[ \text{Tier}(i) = \begin{cases} \text{Target} & \text{if } i \in T \\ \text{Top 10} & \text{if } i \notin T \text{ and } \text{rank}_i \leq 10 \\ \text{High} & \text{if } \text{pct}_i \geq 75 \\ \text{Moderate} & \text{if } \text{pct}_i \geq 50 \\ \text{Low} & \text{otherwise} \end{cases} \] Tiers provide a quick, interpretable classification. "Top 10" always contains exactly the 10 most similar non-target candidates regardless of dataset size. "High" encompasses the top quartile of candidates beyond the Top 10; "Moderate" the second quartile; "Low" the bottom half.
7. Handling multiple target features:
\[ \mathbf{t} = \frac{1}{m} \sum_{k=1}^{m} \mathbf{z}_{i_k} \qquad\text{where } \{i_1, \ldots, i_m\} \text{ are the matched target indices}. \] When a QGIS expression selects multiple features, the target profile is the centroid of all targets. Distance is measured from this centroid. This is equivalent to asking "what features are similar to the average of these selected features?" If the target features are heterogeneous, their centroid may not represent any real feature — the most similar candidates may be quite far from the centroid. Check that targets form a coherent cluster before interpreting similarity results.

##### Expanded Interpretation Guide

Choosing reference features. Reference features should be selected deliberately, not casually. A single well-known case (e.g., "the neighborhood that received the award") makes the analysis a benchmarking exercise — "which other places are most like our exemplar?" Multiple reference features (e.g., "all neighborhoods that underwent successful revitalization") make the analysis a pattern-matching exercise — "which other places match the profile of our success cases?" The QGIS expression syntax allows any logical condition: `"income" > 50000 AND "edu_pct" > 60`, `"fid" IN (3, 17, 42)`, or `"NAME" LIKE '%Park%'`.
Euclidean vs. Manhattan — substantive implications. Euclidean distance will rank a candidate that is moderately different on many variables above a candidate that is nearly identical on most but very different on one. Manhattan does the opposite — it tolerates one large deviation if all others are small. In planning terms: use Euclidean when overall profile similarity matters (you want candidates that look like the target on all dimensions); use Manhattan when tolerance for a single mismatch is high (you care about most dimensions but are willing to overlook one).
Interpreting similarity scores. Raw `sim_index` values are in standardized (z-score) units and have no absolute meaning — a distance of 2.5 is "closer" than 5.0, but neither is inherently "good" or "bad." Use `sim_rank` and `sim_pct` for relative interpretation: rank 1 candidates are the closest matches in the dataset regardless of absolute distance. If the closest match still has a large distance (e.g., the Top 10 all have sim_index > 10), it means the target profile is atypical — no other feature really resembles it. This is an analytically valuable finding: the reference case is unique.
Curse of dimensionality. As the number of variables \(P\) increases, all pairwise distances tend to become similar (Beyer et al., 1999). With \(P > 15\)–20 variables, the contrast between "most similar" and "least similar" collapses — all candidates are roughly equidistant from the target. Mitigation: (1) limit \(P\) to the 5–10 most substantively meaningful variables; (2) use domain knowledge to select variables that genuinely define the similarity concept; (3) consider dimensionality reduction (PCA) before similarity search if \(P\) is large. The plugin warns if near-constant fields are detected.
Similarity Search vs. K-Means Clustering. K-Means groups all features into mutually exclusive clusters based on global patterns in the data. Similarity Search ranks features relative to a user-chosen reference without imposing a global partition. Use K-Means when the question is "what natural groups exist in my data?" Use Similarity Search when the question is "which features are most like this specific one?" The two tools are complementary: run K-Means to discover the global structure, then use Similarity Search to drill into specific clusters or find analogues of particular cases.

##### Methodological Notes

Nearest-neighbor foundations. Similarity Search implements a nearest-neighbor (NN) query in multivariate attribute space — one of the oldest and most fundamental operations in pattern recognition and data mining (Cover & Hart, 1967). The NN rule classifies a point by the class of its nearest neighbor; here, the "class" is the user-selected reference profile, and the tool finds the \(k\) closest points. This is essentially content-based retrieval applied to spatial data: the query is a multivariate profile (not a keyword or a polygon), and the result set is ranked by attribute proximity (not by geographic distance).
Tobler's First Law and attribute space. Similarity Search operates in attribute space, not geographic space. A candidate ranked #1 by sim_index may be geographically distant from the reference features. This is by design: the tool identifies attribute analogues, which may occur anywhere. If geographic proximity is also important, (1) map both sim_index and geographic distance, (2) visually identify candidates that are similar in both attribute and geographic space, or (3) add X/Y coordinates as profile fields to include geographic proximity in the similarity metric.

##### Academic References

Primary (nearest-neighbor and similarity):
1. Cover, T.M. & Hart, P.E. (1967). "Nearest Neighbor Pattern Classification." IEEE Transactions on Information Theory 13(1): 21–27. doi:10.1109/TIT.1967.1053964 — foundational NN rule in pattern recognition
2. Dasarathy, B.V. (ed.) (1991). Nearest Neighbor (NN) Norms: NN Pattern Classification Techniques. Los Alamitos: IEEE Computer Society Press. — comprehensive survey of NN methods
3. Beyer, K., Goldstein, J., Ramakrishnan, R. & Shaft, U. (1999). "When Is 'Nearest Neighbor' Meaningful?" In Database Theory — ICDT '99, LNCS 1540, pp. 217–235. Berlin: Springer. doi:10.1007/3-540-49257-7_15 — curse of dimensionality for NN queries
Distance metrics and standardization:
4. Deza, M.M. & Deza, E. (2009). Encyclopedia of Distances. Berlin: Springer. doi:10.1007/978-3-642-00234-2 — definitive reference on distance metrics including \(L_1\), \(L_2\), and dozens of others
5. Legendre, P. & Legendre, L. (2012). Numerical Ecology (3rd English ed.). Amsterdam: Elsevier. — Ch. 7: ecological distance and similarity coefficients; rigorous treatment of standardization
Statistical learning and data mining:
6. Hastie, T., Tibshirani, R. & Friedman, J. (2009). The Elements of Statistical Learning (2nd ed.). New York: Springer. doi:10.1007/978-0-387-84858-7 — Ch. 13: prototype methods and nearest-neighbors
7. Altman, N.S. (1992). "An Introduction to Kernel and Nearest-Neighbor Nonparametric Regression." The American Statistician 46(3): 175–185. doi:10.2307/2685209
8. Samet, H. (2006). Foundations of Multidimensional and Metric Data Structures. San Francisco: Morgan Kaufmann. — data structures for efficient NN queries in high dimensions
Spatial and planning context:
9. Tobler, W.R. (1970). "A Computer Movie Simulating Urban Growth in the Detroit Region." Economic Geography 46(Supplement): 234–240. doi:10.2307/143141 — Tobler's First Law: "everything is related to everything else, but near things are more related than distant things"
10. Shepard, R.N. (1962). "The Analysis of Proximities: Multidimensional Scaling with an Unknown Distance Function." Psychometrika 27(2): 125–140. doi:10.1007/BF02289630 — foundations of similarity analysis; multidimensional scaling
11. Maimon, O. & Rokach, L. (eds.) (2005). Data Mining and Knowledge Discovery Handbook. New York: Springer. doi:10.1007/b107408 — Ch. 15: similarity and distance measures in data mining
12. Openshaw, S. & Taylor, P.J. (1979). "A Million or So Correlation Coefficients: Three Experiments on the Modifiable Areal Unit Problem." In N. Wrigley (ed.), Statistical Applications in the Spatial Sciences, pp. 127–144. London: Pion. — MAUP: similarity results depend on the spatial units of analysis
🔴

#### Cluster and Outlier Analysis (Local Geary's C)

local_geary_c
The local, per-feature complement to Group 02's global Geary's C — Anselin's (2019) Local Geary's C tests each feature's dissimilarity from its immediate neighbors, using the same sum-of-squared-differences construction as the global statistic rather than Local Moran's I's deviation-from-mean-cross-product construction. It gives Local Moran's I a genuine second opinion: because Local Geary responds to sharp local contrast directly rather than to distance from the study-area mean, it can flag a local outlier that Local Moran misses, or vice versa. Output uses the same HH/LL/HL/LH vocabulary as Local Moran's I for direct comparability, with significance from conditional permutation rather than an analytical formula.

##### 1. Theoretical Background

Origins. Luc Anselin's 1995 paper that introduced the LISA (Local Indicators of Spatial Association) framework focused on Local Moran's I, but explicitly noted the framework generalizes to any global statistic with a valid local decomposition. Anselin returned to this in a 2019 paper in Geographical Analysis, "A Local Indicator of Multivariate Spatial Association: Extending Geary's c," formally deriving the local Geary's C decomposition (alongside a multivariate extension this plugin does not implement) and establishing conditional permutation as the practical inference approach, since the exact analytical variance for the local statistic involves higher-order moments that are considerably harder to get right than Local Moran's already-intricate Anselin (1995) formula.

What makes it different from Local Moran's I. Local Moran's I for feature i is proportional to \((y_i - \bar{y}) \cdot \sum_j w_{ij}(y_j - \bar{y})\) — a cross-product of deviations from the global mean. Local Geary's C for feature i is \(\sum_j w_{ij}(y_i - y_j)^2\) — a sum of squared differences between i and each of its neighbors directly, with no reference to the global mean at all. A feature can be an extreme Local Geary outlier (very different from its immediate neighbors) while sitting close to the global mean itself, a configuration Local Moran's I is structurally unable to flag since its statistic is built entirely from mean-deviations.

Classification logic. Because Local Geary's C only measures dissimilarity magnitude, this plugin combines it with the same sign-based quadrant test Local Moran's I uses: compare the feature's own value and its spatial lag (neighbor mean) against the global mean to assign HH/LL/HL/LH, but only when the conditional-permutation p-value is significant. In the typical case this alignment is automatic — a small local C (similar to neighbors) naturally corresponds to matching signs (HH/LL), and a large local C (dissimilar) naturally corresponds to opposite signs (HL/LH) — but the two pieces of information (magnitude significance and sign) are genuinely separate tests, unlike Local Moran's I where the classification and the significance test both flow from the same cross-product sign.

A real, documented power limitation. Synthetic validation of this plugin's implementation surfaced a genuine and important caveat: on a small, near-binary field (e.g. a sharp two-value split), conditional permutation can fail to reach significance even at the exact transition boundary, because roughly half of all possible random neighbor draws already come from the "other" value — the permutation null itself has high variance under a 50/50 split. This is not a bug; it is a documented property of local statistics with small effective sample sizes, and a reason to prefer a continuous field or a larger dataset when precise local significance matters.

##### 2. Mathematical Formulation

Let \(y_i\) be the field value at location i, \(\bar{y}\) the global mean, and \(w_{ij}\) the row-standardized spatial weight between i and neighbor j.

Local Geary's C for feature i:

$$c_i = \sum_{j} w_{ij}(y_i - y_j)^2 \tag{1}$$

Spatial lag (for quadrant classification):

$$\text{lag}_i = \sum_j w_{ij} \, y_j \tag{2}$$

Conditional permutation inference:

$$c_i^{(p)} = \text{Local Geary's C at } i \text{ with its neighbor set resampled from the other } N{-}1 \text{ observations, for } p = 1, \ldots, P \tag{3}$$ $$z_i = \frac{c_i - \overline{c_i^{(p)}}}{\text{sd}(c_i^{(p)})}, \qquad p_i = \frac{\#\{p : |c_i^{(p)} - \overline{c_i^{(p)}}| \ge |c_i - \overline{c_i^{(p)}}|\} + 1}{P + 1} \tag{4}$$

\(y_i\) itself is held fixed; only its neighbor set is resampled — this is the "conditional" in conditional permutation, matching the plugin's existing Local Moran's I and Bivariate LISA convention (Anselin, 1995, p.97).

Quadrant classification (only when \(p_i < 0.05\)):

$$\text{Class}(i) = \begin{cases} \text{HH} & y_i > \bar{y} \text{ and } \text{lag}_i > \bar{y} \\ \text{LL} & y_i < \bar{y} \text{ and } \text{lag}_i < \bar{y} \\ \text{HL} & y_i > \bar{y} \text{ and } \text{lag}_i < \bar{y} \\ \text{LH} & y_i < \bar{y} \text{ and } \text{lag}_i > \bar{y} \end{cases} \tag{5}$$
Implementation note. The engine (`core/advanced_stats_engines.py::calculate_local_geary_c`) reuses this plugin's existing deterministic per-feature permutation generator (the same lightweight PRNG that powers `calculate_bivariate_local_moran`), needed because the nested feature × permutation loop calls a random shuffle far more times than a general-purpose NumPy generator can service efficiently. Validated on synthetic grid fixtures: a localized attribute anomaly embedded in a smooth gradient is correctly flagged HH at its interior; a purely random field produces a false-positive rate close to the expected ~5% at p<0.05.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
FIELD | Numeric Field | — | Must have variation | Target field to analyze
WEIGHT_TYPE | Enum | Queen contiguity | Queen / Rook / KNN / Distance Band | Spatial relationship used to build the weights matrix
KNN | Integer | 5 | ≥ 1 | Number of neighbors (KNN weights only)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (Distance Band weights only)
PERMUTATIONS | Integer | 199 | 99–1999 | Conditional permutations run per feature (feature × permutation cost multiplies quickly)
RANDOM_SEED | Integer | 42 | ≥ 0 | Seed for reproducible permutation results
OUTPUT | Vector Layer | — | Optional path; auto-styled by class | Output layer with Local Geary's C fields and categorized styling

##### 4. Output Description

Field | Type | Description
--- | --- | ---
lgc_c | Double | Local Geary's C statistic (sum of neighbor squared differences)
lgc_z | Double | Permutation-based z-score
lgc_p | Double | Two-tailed conditional-permutation p-value
quadrant | String | HH, LL, HL, LH, or Not Significant
lgc_nbrs | Integer | Valid neighbor count used for the local statistic

##### 5. Interpretation Guide

Reading Local Geary's C alongside Local Moran's I.

Signal | Meaning | Recommended Next Step
--- | --- | ---
HH or LL, significant | Local cluster — feature and neighbors are unusually similar and jointly high or low | Compare against Local Moran's I HH/LL classification at the same feature for corroboration.
HL or LH, significant | Local outlier — feature and neighbors are unusually dissimilar | Flags the same kind of spatial outlier as Local Moran's I HL/LH, but driven by direct neighbor contrast rather than mean-deviation.
Not Significant, but Local Moran's I IS significant at the same feature | The two tests disagree | Investigate manually — this combination is itself informative about whether the anomaly is a global-mean effect or a purely local contrast effect.
Not Significant, small/near-binary field | Likely a genuine power limitation, not absence of pattern | Re-run on a continuous field or a larger sample before concluding no local structure exists.

See also: Geary's C · Local Moran's I (LISA) · Getis-Ord Gi*

##### 6. Literature

Anselin, L. (2019). "A Local Indicator of Multivariate Spatial Association: Extending Geary's c." Geographical Analysis 51(2): 133–150. DOI: 10.1111/gean.12164 — The paper this tool implements; formally derives the local Geary's C decomposition.

Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. DOI: 10.1111/j.1538-4632.1995.tb00338.x — Establishes the LISA framework and the conditional-randomization justification (p.97) this tool's permutation procedure follows.

Geary, R.C. (1954). "The Contiguity Ratio and Statistical Mapping." The Incorporated Statistician 5(3): 115–146. — The original global statistic this tool localizes.

Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. London: Pion. ISBN: 978-0850860818 — Classical treatment of Geary's C alongside Moran's I in a unified framework.

Ord, J.K. & Getis, A. (1995). "Local Spatial Autocorrelation Statistics: Distributional Issues and an Application." Geographical Analysis 27(4): 286–306. DOI: 10.1111/j.1538-4632.1995.tb00912.x — General distributional issues for local statistics, including the multiple-testing caveat that also applies here.

Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. ISBN: 978-0521574716 — Standard reference for the Monte Carlo p-value "+1" adjustment used in the permutation procedure.

🔺

#### Colocation Quotient (CLQ)

colocation_quotient
Every other hot-spot/outlier tool in this group needs a continuous numeric field. The Colocation Quotient (Leslie & Kronenfeld, 2011) is built for categorical point data: it tests whether one category of features (Category B) is over- or under-represented among another category's (Category A) K nearest neighbors, relative to B's overall share of the dataset. CLQ = 1 is the no-relationship reference point; CLQ > 1 signals attraction, CLQ < 1 signals avoidance. Uniquely among this plugin's colocation-adjacent tools (Join Count Statistics uses polygon adjacency; this uses point K-nearest-neighbors), and uniquely ASYMMETRIC — CLQ(A→B) is not generally equal to CLQ(B→A).

##### 1. Theoretical Background

Origins. Timothy Leslie and Jennifer Kronenfeld introduced the Colocation Quotient in a 2011 paper in Geographical Analysis, motivated by a genuine gap in the point-pattern toolkit: existing cross-K and bivariate join-count methods either required binary presence/absence coding or produced a single symmetric summary that couldn't distinguish "A attracts B" from "B attracts A." Their original formulation used each Category A point's single nearest neighbor; this plugin implements the K-nearest-neighbor generalization used by Cromley, Hanink and Bentley (2014) in their "local colocation quotient" extension, giving the analyst control over the interaction scale via K rather than being locked to the single-nearest-neighbor case.

Why asymmetry matters. Consider a small number of hospitals (Category A) and a much larger number of pharmacies (Category B). Every hospital may have several pharmacies nearby (high CLQ(hospital→pharmacy)), simply because pharmacies are common everywhere — but a typical pharmacy is unlikely to have a hospital among its nearest neighbors (low CLQ(pharmacy→hospital)), since hospitals are rare. A symmetric measure like Ripley's cross-K would blend these two very different findings into one number; CLQ keeps them separate by construction, which is exactly the point of computing both directions when the underlying relationship isn't obviously one-way.

Self-colocation. Setting Category B equal to Category A is a valid and meaningful special case: CLQ(A→A) tests whether a single category clusters with itself, similar in spirit to the plugin's Join Count Statistics BB count but computed on true point locations via K-nearest-neighbors rather than polygon adjacency. A CLQ(A→A) well above 1.0 indicates the category has a strong tendency to co-locate with its own kind — a useful screening step before investigating relationships with other categories.

Scale sensitivity. Like every K-nearest-neighbor-based method in this plugin, CLQ's result depends on the chosen K. A very small K captures only the tightest local interactions; a K approaching the size of the whole dataset pulls every local CLQ toward 1.0 regardless of genuine local structure, since at that scale "nearest neighbors" starts to resemble a random sample of the whole layer. There is no universal correct K — it should match the spatial scale at which the analyst believes the categorical interaction actually operates (e.g. walking-distance co-location vs. district-wide co-location).

##### 2. Mathematical Formulation

Let N be the total point count, \(N_A\) and \(N_B\) the counts of Category A and Category B respectively, and \(NN_B(i)\) the number of point i's K nearest neighbors labeled Category B.

Local CLQ for a single Category A point i (Cromley, Hanink & Bentley, 2014):

$$\text{local\_CLQ}_i(A \to B) = \frac{NN_B(i) / K}{N_B / (N-1)} \tag{1}$$

Global/summary CLQ (this tool's headline statistic):

$$\text{CLQ}(A \to B) = \frac{1}{N_A}\sum_{i \in A} \text{local\_CLQ}_i(A \to B) \tag{2}$$

Permutation inference:

$$\text{CLQ}^{(p)}(A \to B) = \text{CLQ computed with category labels randomly reshuffled across the fixed point locations, for } p = 1, \ldots, P \tag{3}$$ $$z = \frac{\text{CLQ}_{\text{obs}} - \overline{\text{CLQ}^{(p)}}}{\text{sd}(\text{CLQ}^{(p)})}, \qquad p_{\text{value}} = \frac{\#\{p : |\text{CLQ}^{(p)} - \overline{\text{CLQ}^{(p)}}| \ge |\text{CLQ}_{\text{obs}} - \overline{\text{CLQ}^{(p)}}|\} + 1}{P + 1} \tag{4}$$
Implementation note. The engine (`core/advanced_stats_engines.py::calculate_colocation_quotient`) reuses this plugin's existing scikit-learn-KDTree-with-NumPy-fallback pattern (the same one backing Average Nearest Neighbor) for the K-nearest-neighbor search. Validated on synthetic point fixtures: two categories placed in the same tight region return CLQ ≈ 2.0 (p = 0.005, correctly detecting attraction); the same categories placed in disjoint, non-overlapping regions return CLQ = 0.0 (p = 0.005, correctly detecting total avoidance); self-colocation on a spatially separated single category returns CLQ ≈ 1.98 (correctly detecting strong self-clustering).

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type (reduced to centroids) | Input vector layer
FIELD | Field | — | Any type | Category field
CATEGORY_A | String | — | Must exist in FIELD | Reference category value (A)
CATEGORY_B | String | — | Must exist in FIELD | Target category value to test for co-location with A
KNN | Integer | 5 | ≥ 1 | Number of nearest neighbors (K)
PERMUTATIONS | Integer | 999 | 99–9999 | Number of Monte Carlo permutations
RANDOM_SEED | Integer | 42 | ≥ 0 | Seed for reproducible permutation results
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report

##### 4. Output Description

Field | Type | Description
--- | --- | ---
clq | Double | Observed CLQ(A→B)
n_a / n_b / n_total | Integer | Category A count, Category B count, total valid features
permuted_mean / permuted_std | Double | Permutation-distribution mean and standard deviation
z_score / p_value | Double | Standardized z-score and two-tailed Monte Carlo p-value

##### 5. Interpretation Guide

Reading CLQ.

Condition | Meaning | Recommended Next Step
--- | --- | ---
CLQ > 1, p < 0.05 | Positive co-location (attraction) | Map the qualifying Category A features; consider computing the reverse direction CLQ(B→A) too.
CLQ < 1, p < 0.05 | Negative co-location (avoidance) | Investigate whether this reflects a real repulsion process (e.g. zoning separation) or a coverage artifact.
p ≥ 0.05 | No significant co-location | Try a different K before concluding no relationship exists — CLQ is scale-sensitive.

Always consider computing both directions. CLQ(A→B) alone answers "does A attract B"; it says nothing about whether B attracts A. When the planning question doesn't have an obvious direction (e.g. "do coffee shops and co-working spaces co-locate?"), run the tool twice with Category A and B swapped and report both quotients — a large asymmetry between the two directions is itself a substantive finding.

See also: Join Count Statistics · Average Nearest Neighbor · Getis-Ord Gi*

##### 6. Literature

Leslie, T.F. & Kronenfeld, B.J. (2011). "The Colocation Quotient: A New Measure of Spatial Association Between Categorical Subsets of Points." Geographical Analysis 43(3): 306–326. DOI: 10.1111/j.1538-4632.2011.00821.x — The foundational paper; introduces the asymmetric CLQ and its nearest-neighbor formulation.

Cromley, R.G., Hanink, D.M. & Bentley, G.C. (2014). "Geographically Weighted Colocation Quotients: Specification and Application." The Professional Geographer 66(1): 138–148. DOI: 10.1080/00330124.2013.768130 — The K-nearest-neighbor local CLQ generalization this tool implements.

Ripley, B.D. (1976). "The Second-Order Analysis of Stationary Point Processes." Journal of Applied Probability 13(2): 255–266. DOI: 10.2307/3212829 — The symmetric cross-K precedent that CLQ's asymmetry improves on for categorical co-location questions.

Cressie, N.A.C. (1993). Statistics for Spatial Data (revised ed.). New York: Wiley. ISBN: 978-0471002550 — Standard reference on point-pattern statistics and bivariate spatial association.

Getis, A. & Franklin, J. (1987). "Second-Order Neighborhood Analysis of Mapped Point Patterns." Ecology 68(3): 473–477. DOI: 10.2307/1938452 — Precedent for neighborhood-based (rather than distance-band) point-pattern association measures.

Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. ISBN: 978-0521574716 — Standard reference for the Monte Carlo p-value "+1" adjustment used in the permutation procedure.

🌳

#### Spatially Constrained Regionalization (SKATER)

skater_regionalization
Partitions the study area into K spatially CONTIGUOUS regions — the direct fix for the plugin's Multivariate Clustering (K-Means) tool's biggest limitation: K-Means groups by attribute similarity alone, with no guarantee cluster members are geographically near each other. SKATER (Spatial 'K'luster Analysis by Tree Edge Removal; Assunção et al., 2006) builds a minimum spanning tree over the spatial contiguity graph and greedily cuts the K-1 edges that most reduce total within-cluster sum of squares, guaranteeing every output region is a single connected area. Ships as a native NumPy + Prim's-algorithm implementation with no optional-library dependency.

##### 1. Theoretical Background

Origins. Renato Assunção and colleagues introduced SKATER in a 2006 paper in the International Journal of Geographical Information Science, addressing a problem regional scientists had worked around for decades: standard clustering methods (K-Means, hierarchical clustering) group by attribute similarity with no spatial-contiguity guarantee, forcing analysts to either accept scattered "clusters" or hand-edit results into contiguous regions. SKATER instead builds contiguity into the algorithm itself via a graph-theoretic construction — a minimum spanning tree — so every candidate partition considered during the procedure is contiguous by construction, not by post-hoc correction.

The divisive tree-cutting procedure. SKATER is a divisive method — the reverse of hierarchical agglomerative clustering. It starts with the entire study area as one region (whose internal structure is the minimum spanning tree over the spatial contiguity graph, edge-weighted by attribute dissimilarity), then repeatedly removes the single tree edge whose removal most reduces the total within-cluster sum of squares (SSD) across all current regions, stopping after K-1 cuts have produced K regions. Because each cut only ever splits an existing connected sub-tree into two connected sub-trees, contiguity is preserved at every step — there is no way for a SKATER region to end up spatially fragmented.

Why a minimum spanning tree specifically. The MST is the sparsest possible connected subgraph of the full contiguity graph that still spans every feature, using the lowest-dissimilarity edges available. Working from the MST rather than the full graph is what makes the "find the best edge to cut" search tractable — a tree with N nodes has exactly N-1 edges to evaluate at each step, versus potentially far more edges in the full contiguity graph. Assunção et al. prove that restricting the search to the MST does not sacrifice solution quality: the optimal K-way contiguous partition of the MST is provably a good approximation to the optimal K-way contiguous partition of the full graph for this class of problem.

Native implementation, not an optional-dependency wrapper. SKATER is available in the PySAL ecosystem via the `spopt` package (built on `libpysal`), and an earlier draft of this plugin's development plan considered wrapping that implementation the way Spatial Autoregression and Spatial Error Regression wrap `spreg`. This tool ships instead as a fully native NumPy + stdlib `heapq` implementation (Prim's algorithm for the MST, then a direct greedy tree-cutting search) — it works with zero additional installs and carries no risk of the numba/NumPy ABI version conflicts that already affect this plugin's other optional-dependency tools (see GeoStats Library Status). The trade-off is runtime: the greedy cut search is O(K × E) where E is the number of tree edges, which is fast for the hundreds-of-features layers this plugin is built around but will slow down noticeably into the low thousands of features.

##### 2. Mathematical Formulation

Let \(z_i \in \mathbb{R}^p\) be the Z-score-standardized attribute vector for feature i across the p selected fields, and let the spatial contiguity graph connect i and j whenever they are neighbors under the chosen weight type.

Edge dissimilarity (squared Euclidean distance in standardized attribute space):

$$d_{ij} = \lVert z_i - z_j \rVert^2 = \sum_{k=1}^{p}(z_{ik} - z_{jk})^2 \tag{1}$$

Minimum spanning tree (Prim's algorithm):

$$T = \arg\min_{T' \text{ spans all nodes}} \sum_{(i,j) \in T'} d_{ij} \tag{2}$$

Within-cluster sum of squares (SSD) for a candidate region R:

$$\text{SSD}(R) = \sum_{i \in R} \lVert z_i - \bar{z}_R \rVert^2, \qquad \bar{z}_R = \frac{1}{|R|}\sum_{i \in R} z_i \tag{3}$$

Greedy edge-removal objective at each of the K-1 steps:

$$(R^*, e^*) = \arg\max_{R,\, e \in T_R} \Big[ \text{SSD}(R) - \big(\text{SSD}(R_1(e)) + \text{SSD}(R_2(e))\big) \Big] \tag{4}$$

where R ranges over all currently-formed regions, e ranges over that region's internal tree edges, and \(R_1(e), R_2(e)\) are the two connected components produced by removing edge e from region R's internal tree. The chosen cut is the one that maximizes the total SSD reduction across the whole current partition.

Final objective (minimized, indirectly, by the greedy procedure):

$$\text{Total SSD} = \sum_{k=1}^{K} \text{SSD}(R_k) \tag{5}$$
Implementation note. The engine (`core/advanced_stats_engines.py::calculate_skater`) builds the MST via a standard binary-heap Prim's algorithm, then performs the greedy cut search by temporarily removing each candidate edge and re-running a small breadth-first traversal to identify the two resulting components — an approach chosen for correctness and readability over the more elaborate incremental-update schemes described in the original paper, which matter more at MST sizes far beyond this plugin's typical layer sizes. A connectivity check runs before the MST step: if the input spatial-weights graph is not a single connected component, the tool raises a clear error naming how many features are unreachable, rather than silently producing an MST that spans only part of the data. Validated on a synthetic grid fixture with a sharp left/right attribute discontinuity aligned to spatial position: SKATER recovers the exact left/right partition at K=2, and a disconnected contiguity graph correctly raises the connectivity error.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
FIELDS | Numeric Fields | — | ≥ 1 field | Analysis fields (Z-score standardized before clustering)
WEIGHT_TYPE | Enum | Queen contiguity | Queen / Rook / KNN / Distance Band | Spatial contiguity graph used to constrain regions
KNN | Integer | 5 | ≥ 1 | Number of neighbors (KNN contiguity only)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (Distance Band contiguity only)
K_CLUSTERS | Integer | 3 | ≥ 2 | Number of spatially contiguous regions
OUTPUT | Vector Layer | — | Optional path; auto-styled by region | Output regionalized layer

##### 4. Output Description

Field | Type | Description
--- | --- | ---
region_id | Integer | SKATER region identifier (0 to K-1), spatially contiguous by construction
region_size | Integer | Number of complete records assigned to this region
region_ssd | Double | Standardized within-region sum of squared deviations

##### 5. Interpretation Guide

Choosing K. As with K-Means, run SKATER at several K values and examine total SSD (printed to the Processing log) for a diminishing-returns "elbow" rather than committing to a single run. Because SKATER's regions are contiguous, the natural sanity check K-Means lacks is available here for free: simply look at the map — every region should visually read as one connected area, which it always will by construction, so the real question when comparing K values is whether the additional regions correspond to genuinely distinct attribute profiles or are just splitting an already-homogeneous area for no analytical gain.

SKATER vs. Multivariate Clustering — which to run. Use SKATER whenever the output needs to be a usable set of planning regions (a proposed district boundary, a service-area redesign, a zoning revision) — contiguity is not optional in those contexts. Use Multivariate Clustering (K-Means) when the question is purely about attribute-profile similarity and geographic proximity is irrelevant or actively undesirable to enforce (e.g. finding all neighborhoods citywide with a similar demographic profile, regardless of where they are). Running both on the same fields and comparing region_id against cluster_id is itself informative: heavy disagreement between the two indicates the attribute clusters are not spatially coherent to begin with.

See also: Multivariate Clustering · Calculate Distance Band · Similarity Search

##### 6. Literature

Assunção, R.M., Neves, M.C., Câmara, G. & Freitas, C.C. (2006). "Efficient Regionalization Techniques for Socio-economic Geographical Units Using Minimum Spanning Trees." International Journal of Geographical Information Science 20(7): 797–811. DOI: 10.1080/13658810600665111 — The original SKATER paper.

Duque, J.C., Anselin, L. & Rey, S.J. (2012). "The Max-p-Regions Problem." Journal of Regional Science 52(3): 397–419. DOI: 10.1111/j.1467-9787.2011.00743.x — A related spatially constrained regionalization method with a size-threshold constraint instead of a fixed K, useful further reading for regionalization variants.

Prim, R.C. (1957). "Shortest Connection Networks and Some Generalizations." Bell System Technical Journal 36(6): 1389–1401. DOI: 10.1002/j.1538-7305.1957.tb01515.x — The minimum spanning tree algorithm this tool's engine implements.

Openshaw, S. (1977). "A Geographical Solution to Scale and Aggregation Problems in Region-Building, Partitioning and Spatial Modelling." Transactions of the Institute of British Geographers 2(4): 459–472. DOI: 10.2307/622300 — Foundational work on the general region-building problem SKATER solves.

Guo, D. (2008). "Regionalization with Dynamically Constrained Agglomerative Clustering and Partitioning (REDCAP)." International Journal of Geographical Information Science 22(7): 801–823. DOI: 10.1080/13658810701674970 — A closely related family of spatially constrained clustering methods, useful comparative reading.

Duque, J.C., Ramos, R. & Suriñach, J. (2007). "Supervised Regionalization Methods: A Survey." International Regional Science Review 30(3): 195–220. DOI: 10.1177/0160017607301605 — Broad survey placing SKATER among the wider family of regionalization techniques.

04

### Centers, Direction and Dispersion

Descriptive spatial statistics that characterize the central tendency, directional orientation, and spread of point patterns. These are the spatial analogues of mean, median, standard deviation, and skewness — descriptive measures that summarize geometry before inferential modeling. This group traces its lineage to centrography, the statistical study of geographic centers pioneered by Mendeleev (1906) and formalized by Sviatlovsky & Eells (1937). All tools in this group operate on feature centroids.

⊕

#### Mean Center

mean_center
Computes the geographic center (arithmetic mean of X and Y coordinates) of a set of features, optionally weighted by a numeric field. The simplest spatial central-tendency measure and the foundation of centrographic analysis. When weighted by population, this yields the population centroid; when weighted by employment, the employment centroid; the shift vector between unweighted and weighted centers reveals the spatial pull of the weighting variable — a classic technique for tracking demographic and economic deconcentration over time.

##### Theoretical Background

The mean center is the direct spatial analogue of the arithmetic mean, and its use in geography predates modern GIS by more than a century: the U.S. Census Bureau has computed and published the national population center after every decennial census since 1790, tracking its westward and southward drift as the settlement pattern of the country shifted. Sviatlovsky and Eells (1937) formalized the broader family of centrographic measures — mean center, standard distance, median center — as a coherent toolkit borrowed directly from the physics of the center of mass, treating each feature as a unit (or weighted) point mass and the mean center as the point where the distribution would balance if cut from rigid material.

The mean center's chief virtue is also its chief weakness: because it is a linear function of the coordinates, it is trivial to compute and to weight, but it inherits the arithmetic mean's zero breakdown point — a single feature at an extreme coordinate can pull the center arbitrarily far from where most of the data actually sit. This is the motivation for pairing Mean Center with Median Center (this group) whenever the dataset may contain outliers, a pairing recommended as standard practice since at least Kellerman's (1981) CATMOG monograph on centrographic measures.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroid used)
WEIGHT_FIELD | Numeric Field (opt) | — | Weighting variable; unweighted mean if omitted
MODE | Enum | Mean Center | Mean Center or Central Feature calculation
OUTPUT | Vector Layer (Point) | — | Output point layer with center coordinates

##### Output Fields

`mean_x` — weighted mean X coordinate (map units) · `mean_y` — weighted mean Y coordinate (map units) · `total_w` — sum of valid weights used · `input_n` — number of valid features processed · `skip_geom` — features skipped (empty geometry) · `bad_w` — features with null/invalid weight values

##### Equations

Unweighted mean center (special case $w_i = 1$):
$$ \bar{X} = \frac{1}{N}\sum_{i=1}^{N} x_i \qquad \bar{Y} = \frac{1}{N}\sum_{i=1}^{N} y_i $$
Weighted mean center:
$$ \bar{X}_w = \frac{\sum_{i=1}^{N} w_i x_i}{\sum_{i=1}^{N} w_i} \qquad \bar{Y}_w = \frac{\sum_{i=1}^{N} w_i y_i}{\sum_{i=1}^{N} w_i} $$
Shift vector (the "pull" of the weight variable):
$$ \vec{S} = (\bar{X}_w - \bar{X},\; \bar{Y}_w - \bar{Y}) \qquad \|\vec{S}\| = \sqrt{(\bar{X}_w - \bar{X})^2 + (\bar{Y}_w - \bar{Y})^2} $$
Weighted coordinate variance:
$$ \sigma^2_{x,w} = \frac{\sum w_i (x_i - \bar{X}_w)^2}{\sum w_i} \qquad \sigma^2_{y,w} = \frac{\sum w_i (y_i - \bar{Y}_w)^2}{\sum w_i} $$
Standard error of the weighted mean center:
$$ SE_{\bar{X}_w} = \frac{\sigma_{x,w}}{\sqrt{N_{eff}}} \quad\text{where}\quad N_{eff} = \frac{(\sum w_i)^2}{\sum w_i^2} $$

##### Interpretation

Planning applications. The mean center is the most intuitive centrographic measure. Track it over census periods to quantify the direction and speed of urban growth — the U.S. Census Bureau has published the national population centroid after every decennial census since 1790. A weighted mean center that lies far from the unweighted center signals that the weighting variable (e.g., employment, income, population density) is spatially skewed. The shift vector magnitude can be normalized by the standard distance to produce a dimensionless "pull index."
Limitations. The mean center is sensitive to outliers — a single feature at an extreme coordinate shifts the center proportionally. For skewed point patterns, prefer the Median Center. The mean center may also fall in an uninhabitable location (water body, mountain ridge) — use the Central Feature when the result must be an actual input feature.
See also: Median Center · Central Feature · Standard Distance · Directional Distribution

##### References

Sviatlovsky, E.E. & Eells, W.C. (1937). "The Centrographical Method and Regional Analysis." Geographical Review 27(2): 240–254. doi:10.2307/210093 · Kellerman, A. (1981). "Centrographic Measures in Geography." CATMOG 32. Geo Abstracts, Norwich. ISBN 0-86094-081-2 · Burt, J.E. & Barber, G.M. (1996). Elementary Statistics for Geographers (2nd ed.). Guilford Press. ISBN 1-57230-003-8 · Mendeleev, D.I. (1906). K poznaniyu Rossii [Toward the Understanding of Russia]. St. Petersburg. · Bachi, R. (1963). "Standard Distance Measures and Related Methods for Spatial Analysis." Papers of the Regional Science Association 10(1): 83–132. doi:10.1007/BF01934680 · U.S. Census Bureau (2021). "Centers of Population." census.gov · Mitchell, A. (2005). The ESRI Guide to GIS Analysis, Volume 2: Spatial Measurements and Statistics. ESRI Press. ISBN 1-58948-116-1 · Greene, R.P. & Pick, J.B. (2012). Exploring the Urban Community: A GIS Approach (2nd ed.). Pearson. ISBN 0-321-75159-9 · Cromley, R.G. & McLafferty, S.L. (2012). GIS and Public Health (2nd ed.). Guilford Press. ISBN 1-60918-472-4 · Wong, D.W.S. & Lee, J. (2005). Statistical Analysis of Geographic Information with ArcView GIS and ArcGIS. Wiley. ISBN 0-471-46899-8
⦿

#### Central FeatureO(N²)

central_feature
Identifies the most centrally located existing feature in the dataset — the feature $j^*$ whose sum of Euclidean distances to all other features is minimized. Unlike the Mean Center (which may fall in an uninhabited location such as a water body or mountain ridge), the Central Feature is always one of the actual input features. This is a discrete approximation to the 1-median problem, making it invaluable for facility-location screening when the candidate set is restricted to existing sites (e.g., "which existing fire station is most central to the at-risk population?").

##### Theoretical Background

The Central Feature tool solves a discrete instance of the classical 1-median (Weber) problem: among a fixed candidate set, find the point that minimizes total weighted distance to all others. This "restrict the search to existing sites" framing is the standard first move in applied facility-location analysis (Wesolowsky, 1993) — planners rarely have the freedom to build a new facility anywhere in continuous space, but very often need to decide which of several existing sites (schools, clinics, depots) is best positioned to serve the rest. Kuhn and Kuenne (1962) generalized the underlying Weber problem to weighted multi-point demand, the same generalization this tool implements via the WEIGHT_FIELD parameter.

Because the search is restricted to the N input features rather than all of continuous space, Central Feature always returns a worse or equal objective value than the true geometric median computed by Median Center (this group) — the two tools are best used together, with the efficiency ratio between their respective total-distance outputs indicating how much is lost by restricting the search to actual sites rather than any point in the plane.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroid used)
WEIGHT_FIELD | Numeric Field (opt) | — | Multiplicative weight for distance calculation (e.g., population served)
OUTPUT | Vector Layer | — | Output with the central feature identified, preserving original geometry and attributes

##### Output Fields

(All original input fields preserved) · `is_central` — 1 for the selected central feature; absent for others · `total_distance` — total (optionally weighted) distance from this feature to all other valid input features (map units)

##### Equations

Unweighted total-distance criterion:
$$ D_j = \sum_{i=1}^{N} d_{ij} \qquad\text{where}\qquad d_{ij} = \sqrt{(x_i - x_j)^2 + (y_i - y_j)^2} $$
Weighted total-distance criterion:
$$ D_j^{(w)} = \sum_{i=1}^{N} w_i \cdot d_{ij} $$
Central feature selection:
$$ j^* = \underset{j \in \{1,\dots,N\}}{\arg\min}\; D_j^{(w)} $$
Relationship to the continuous geometric median:
$$ D_{j^*} \ge \min_{(x,y) \in \mathbb{R}^2} \sum_{i=1}^{N} w_i \cdot \sqrt{(x - x_i)^2 + (y - y_i)^2} $$
The central feature's total distance $D_{j^*}$ is an upper bound on the true geometric median objective. The efficiency ratio $R = D_{continuous} / D_{j^*}$ (where $0 < R \le 1$) measures how close the best discrete site comes to the optimal continuous location.
Computational complexity: $O(N^2)$ pairwise distance matrix. For $N$ features, the full distance matrix requires $\binom{N}{2}$ distance evaluations — $O(N^2)$ in both time and memory. This is acceptable for typical planning datasets ($N < 10^4$); larger datasets should consider spatial indexing or the continuous Median Center as alternatives.

##### Interpretation

When to use Central Feature vs. Median Center. Central Feature is appropriate when the selected site must be an existing feature (e.g., choosing which hospital, school, or depot to upgrade). It solves the discrete 1-median on the set of input locations. The continuous Median Center (Weiszfeld algorithm) is appropriate when the optimal location can be anywhere in the study area — for greenfield facility location, use the Median Center and then find the nearest existing feature as a secondary step.
Weight interpretation. When a weight field is provided, each feature's contribution to the distance sum is multiplied by its weight. A feature with weight 10 contributes 10 times as much to the central feature's total-distance score as a feature with weight 1. This makes the central feature gravitate toward heavily weighted locations — ideal when weighting by population served, hazard exposure count, or trip-generation potential.
Diagnostic value. Compare the central feature's total_distance to the Median Center's total_dist output. If they are close, the discrete optimum approximates the continuous optimum well. If they diverge, either (a) the feature set is sparse relative to the area, or (b) the continuous optimum lies in a gap between features — consider whether a new facility is warranted.
See also: Mean Center · Median Center

##### References

Kuhn, H.W. & Kuenne, R.E. (1962). "An Efficient Algorithm for the Numerical Solution of the Generalized Weber Problem in Spatial Economics." Journal of Regional Science 4(2): 21–33. doi:10.1111/j.1467-9787.1962.tb00902.x · Weiszfeld, E. (1937). "Sur le point pour lequel la somme des distances de n points donnés est minimum." Tohoku Mathematical Journal 43: 355–386. (No DOI; pre-digital) · Drezner, Z. & Hamacher, H.W. (eds., 2002). Facility Location: Applications and Theory. Springer. doi:10.1007/978-3-642-56082-8 · Love, R.F., Morris, J.G. & Wesolowsky, G.O. (1988). Facilities Location: Models and Methods. North-Holland. ISBN 0-444-01031-9 · Wesolowsky, G.O. (1993). "The Weber Problem: History and Perspectives." Location Science 1(1): 5–23. · Church, R.L. & Murray, A.T. (2018). Location Covering Models: History, Applications and Advancements. Springer. doi:10.1007/978-3-319-99846-6 · Owen, S.H. & Daskin, M.S. (1998). "Strategic Facility Location: A Review." European Journal of Operational Research 111(3): 423–447. doi:10.1016/S0377-2217(98)00186-6 · Mitchell, A. (2005). The ESRI Guide to GIS Analysis, Volume 2: Spatial Measurements and Statistics. ESRI Press. ISBN 1-58948-116-1 · Cromley, R.G. & McLafferty, S.L. (2012). GIS and Public Health (2nd ed.). Guilford Press. ISBN 1-60918-472-4 · Burt, J.E. & Barber, G.M. (1996). Elementary Statistics for Geographers (2nd ed.). Guilford Press. ISBN 1-57230-003-8
⊙

#### Median Center (Weiszfeld Algorithm)

median_center
Computes the geometric median (also called the 1-median, Fermat–Weber point, or spatial median) — the point in continuous space that minimizes the sum of weighted Euclidean distances to all features. The geometric median is substantially more robust to outliers than the mean center: a single feature at an extreme distance does not pull the median center as strongly as it pulls the mean. Its breakdown point is 0.5 (up to half the data can be arbitrarily displaced without destroying the estimate), compared to 0 for the mean center. Implemented via Weiszfeld's iterative algorithm (1937) with automatic perturbation when the iterate coincides with a data point.

##### Theoretical Background

The geometric median has a distinguished, largely independent history in three separate fields: facility-location theory (where it is the Weber point, solving the classical problem of siting a factory to minimize total weighted transport cost to several markets), robust statistics (where it is the multivariate L1-median, one of the highest-breakdown-point location estimators known), and computational geometry (where the Weiszfeld iteration remains a standard reference algorithm for convex-but-nonsmooth optimization). Weiszfeld's 1937 paper predates the modern optimization literature by decades and was rediscovered independently more than once before Kuhn (1973) supplied a rigorous convergence proof.

Vardi and Zhang (2000) placed the geometric median within the modern statistical-depth framework, showing it is the deepest point of a multivariate L1 data-depth function — a formalization of the intuitive idea that the median center is the "most typical" location in a point set, robust to contamination in a way the mean center fundamentally cannot be. Lopuhaa and Rousseeuw's (1991) breakdown-point theory for affine-equivariant location estimators is the formal basis for the BP = 0.5 figure reported below.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroid used)
WEIGHT_FIELD | Numeric Field (opt) | — | Weighting variable; unweighted median if omitted
OUTPUT | Vector Layer (Point) | — | Output point layer with median coordinates and total minimized distance

Algorithm parameters (fixed). Convergence tolerance is fixed at $10^{-6}$ and the maximum iteration count at 100. The algorithm initializes from the weighted mean center and typically converges within 15–40 iterations for well-conditioned datasets. If the iterate lands exactly on a data point (zero distance → division by zero), the implementation applies a small perturbation to continue.

##### Output Fields

`median_x` — median center X coordinate (map units) · `median_y` — median center Y coordinate (map units) · `total_dist` — the minimized sum of weighted Euclidean distances from the median center to all input features (the objective function value at convergence)

##### Equations

Optimization problem (Fermat–Weber):
$$ \min_{(x,y) \in \mathbb{R}^2}\; f(x,y) = \sum_{i=1}^{N} w_i \cdot \sqrt{(x - x_i)^2 + (y - y_i)^2} $$
Weiszfeld iteration (k → k+1):
$$ x^{(k+1)} = \frac{\sum_{i=1}^{N} \frac{w_i x_i}{d_i^{(k)}}}{\sum_{i=1}^{N} \frac{w_i}{d_i^{(k)}}} \qquad y^{(k+1)} = \frac{\sum_{i=1}^{N} \frac{w_i y_i}{d_i^{(k)}}}{\sum_{i=1}^{N} \frac{w_i}{d_i^{(k)}}} $$
where $d_i^{(k)} = \sqrt{(x^{(k)} - x_i)^2 + (y^{(k)} - y_i)^2}$ and $d_i^{(k)}$ is clamped to $\ge 10^{-12}$ to avoid division by zero.
Gradient of the objective:
$$ \frac{\partial f}{\partial x} = \sum_{i=1}^{N} w_i \cdot \frac{x - x_i}{d_i} \qquad \frac{\partial f}{\partial y} = \sum_{i=1}^{N} w_i \cdot \frac{y - y_i}{d_i} $$
At the optimum, the negative gradient (the "force" pulling toward each data point) sums to zero — the median center is the equilibrium point.
Convergence criterion:
$$ \Delta^{(k)} = \sqrt{(x^{(k+1)} - x^{(k)})^2 + (y^{(k+1)} - y^{(k)})^2} < 10^{-6} $$
Breakdown point comparison:
$$ \text{BP}(\text{mean}) = 0 \qquad \text{BP}(\text{median}) = 0.5 $$
The mean center can be broken by a single arbitrarily displaced point ($\text{BP} = 1/N \to 0$). The geometric median tolerates up to $\lfloor N/2 \rfloor$ contaminated points.

##### Interpretation

Robustness and planning use. The geometric median is the preferred center when the dataset contains outliers or extreme values — common in planning when a few remote settlements, edge-case parcels, or data-entry errors distort the mean. For facility location under the minisum criterion (minimize total travel distance), the median center is the optimal continuous location.
Weiszfeld's convergence properties. The algorithm converges linearly (geometrically) for all starting points except when it coincides with a data point. Kuhn (1973) proved that the algorithm converges from any starting point, and if the iterate ever coincides exactly with a non-optimal data point, it moves away on the next step. The implementation handles this by clamping near-zero distances.
When not to use. For datasets with very few features ($N < 5$), the median center may not differ meaningfully from the mean center. For large datasets where computation time is critical, consider the Central Feature as a faster $O(N^2)$ discrete alternative. For minimax problems (minimize the maximum distance to any point), use the 1-center (not the 1-median), which is not directly provided by this tool but can be approximated by the Central Feature when constrained to existing sites.
See also: Mean Center · Central Feature

##### References

Weiszfeld, E. (1937). "Sur le point pour lequel la somme des distances de n points donnés est minimum." Tohoku Mathematical Journal 43: 355–386. (No DOI; pre-digital. English translation by F. Plastria available.) · Kuhn, H.W. (1973). "A Note on Fermat's Problem." Mathematical Programming 4(1): 98–107. doi:10.1007/bf01584648 · Kuhn, H.W. & Kuenne, R.E. (1962). "An Efficient Algorithm for the Numerical Solution of the Generalized Weber Problem." Journal of Regional Science 4: 21–33. doi:10.1111/j.1467-9787.1962.tb00902.x · Vardi, Y. & Zhang, C.-H. (2000). "The Multivariate $L_1$-Median and Associated Data Depth." Proceedings of the National Academy of Sciences 97(4): 1423–1426. doi:10.1073/pnas.97.4.1423 · Ostresh, L.M. (1978). "On the Convergence of a Class of Iterative Methods for Solving the Weber Location Problem." Operations Research 26(4): 597–609. doi:10.1287/opre.26.4.597 · Plastria, F. (2011). "The Weiszfeld Algorithm: Proof, Modifications and Extensions." In Eiselt & Marianov (eds.), Foundations of Location Analysis, Springer. doi:10.1007/978-1-4419-7572-0_12 · Drezner, Z. & Hamacher, H.W. (eds., 2002). Facility Location: Applications and Theory. Springer. doi:10.1007/978-3-642-56082-8 · Lopuhaa, H.P. & Rousseeuw, P.J. (1991). "Breakdown Points of Affine Equivariant Estimators of Multivariate Location and Covariance Matrices." Annals of Statistics 19(1): 229–248. doi:10.1214/aos/1176347978 · Love, R.F., Morris, J.G. & Wesolowsky, G.O. (1988). Facilities Location: Models and Methods. North-Holland. ISBN 0-444-01031-9 · Mitchell, A. (2005). The ESRI Guide to GIS Analysis, Volume 2. ESRI Press. ISBN 1-58948-116-1
◎

#### Standard Distance

standard_distance
Computes the spatial analogue of the standard deviation — the degree to which features are concentrated or dispersed around their mean center. Produces a circular polygon centered on the weighted mean center with radius equal to the standard distance multiplied by a user-selected factor (1, 2, or 3 SD). The standard distance is a circle of dispersion: it captures how tightly or loosely points cluster around their center, but unlike the SDE it assumes isotropic (directionally uniform) dispersion.

##### Theoretical Background

Standard Distance was introduced by D. Welty Lefever in 1926 as a byproduct of deriving the Standard Deviational Ellipse (this group): before generalizing dispersion to an anisotropic ellipse, Lefever first needed the isotropic special case — a single scalar summarizing "how spread out" a point pattern is, directly analogous to the standard deviation of a univariate sample. Furfey (1927) and later Bachi (1963) placed the measure on firmer mathematical footing, establishing its relationship to the trace of the spatial covariance matrix that this implementation exposes directly ($SD^2 = \operatorname{tr}(\mathbf{C}) = \sigma_x^2 + \sigma_y^2$).

Because Standard Distance discards the covariance term $\Sigma_{xy}$ entirely, it cannot detect directional bias: two datasets with identical isotropic spread but very different orientations (one circular, one a narrow diagonal band) can produce the same standard distance despite looking completely different on a map. This is the single most common reason to prefer the Standard Deviational Ellipse over Standard Distance whenever the analyst suspects the pattern is not radially symmetric.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroid used)
WEIGHT_FIELD | Numeric Field (opt) | — | Weighting variable; unweighted if omitted
MULTIPLIER | Enum | 1 SD | Circle size: 1, 2, or 3 standard deviations
OUTPUT | Vector Layer (Polygon) | — | Output circle polygon with diagnostic fields

##### Output Fields

`mean_x` — mean center X coordinate (circle center) · `mean_y` — mean center Y coordinate (circle center) · `std_dist` — one-standard-distance radius before multiplier (map units) · `multiplier` — selected SD multiplier (1, 2, or 3) · `radius` — actual circle radius (std_dist × multiplier) in map units · `input_n` — number of valid features used · `skip_geom` — features skipped (empty geometry) · `bad_w` — features with null/invalid weight values

##### Equations

Unweighted standard distance:
$$ SD = \sqrt{\frac{1}{N}\sum_{i=1}^{N} (x_i - \bar{X})^2 \;+\; \frac{1}{N}\sum_{i=1}^{N} (y_i - \bar{Y})^2} $$
Weighted standard distance:
$$ SD_w = \sqrt{\frac{\sum_{i=1}^{N} w_i (x_i - \bar{X}_w)^2}{\sum w_i} \;+\; \frac{\sum_{i=1}^{N} w_i (y_i - \bar{Y}_w)^2}{\sum w_i}} $$
Relationship to coordinate variances:
$$ SD^2 = \sigma_x^2 + \sigma_y^2 \qquad\text{where}\qquad \sigma_x^2 = \frac{1}{N}\sum (x_i - \bar{X})^2,\;\; \sigma_y^2 = \frac{1}{N}\sum (y_i - \bar{Y})^2 $$
Circle area:
$$ A_{SD} = \pi \cdot (k \cdot SD)^2 \qquad\text{where } k \in \{1, 2, 3\} \text{ is the multiplier} $$
Circle area formula derivation: The total dispersion captured by the standard distance circle can be expressed as the sum of the X- and Y-direction variances, which equals the trace of the spatial covariance matrix $\mathbf{C} = \begin{pmatrix} \sigma_x^2 & \sigma_{xy} \\ \sigma_{xy} & \sigma_y^2 \end{pmatrix}$: $SD^2 = \operatorname{tr}(\mathbf{C})$.
Relative dispersion index (dimensionless):
$$ SD_{rel} = \frac{SD}{\sqrt{A_{study} / \pi}} $$
This normalizes the standard distance by the radius of a circle with area equal to the study area, producing a value between 0 (perfect concentration) and approximately 1 (dispersion comparable to the study area extent). Values exceeding 1 indicate the dataset's dispersion exceeds the study-area-equivalent circle.

##### Interpretation

Circle size choice. At 1 SD, approximately 63% of features (under bivariate normality) lie within the circle. At 2 SD, approximately 98%. At 3 SD, nearly all features are enclosed. Choose 1 SD for a "core" dispersion measure, 2 SD for an approximate envelope, and 3 SD to visualize the full extent.
Standard Distance vs. SDE. The Standard Distance circle assumes dispersion is equal in all directions (isotropic). When spatial dispersion is strongly directional (e.g., a city elongated along a river corridor), the SDE provides richer information. The ratio of SDE semi-major to semi-minor axis indicates anisotropy; the standard distance circle hides this. Use both tools together: SD for a quick scalar dispersion metric, SDE for directional detail.
Comparative analysis. Compute standard distances for the same variable across multiple time periods (e.g., population distribution 1990, 2000, 2010, 2020). A progressively increasing SD indicates spatial deconcentration (suburbanization); a stable or shrinking SD indicates containment or densification. The change in SD over time can be expressed as an annualized growth rate.
See also: Directional Distribution

##### References

Furfey, P.H. (1927). "A Note on Lefever's 'Standard Deviational Ellipse'." American Journal of Sociology 33(1): 94–98. doi:10.1086/214336 · Bachi, R. (1963). "Standard Distance Measures and Related Methods for Spatial Analysis." Papers of the Regional Science Association 10(1): 83–132. doi:10.1007/BF01934680 · Lefever, D.W. (1926). "Measuring Geographic Concentration by Means of the Standard Deviational Ellipse." American Journal of Sociology 32(1): 88–94. doi:10.1086/214027 · Sviatlovsky, E.E. & Eells, W.C. (1937). "The Centrographical Method and Regional Analysis." Geographical Review 27(2): 240–254. doi:10.2307/210093 · Kellerman, A. (1981). "Centrographic Measures in Geography." CATMOG 32. Geo Abstracts, Norwich. ISBN 0-86094-081-2 · Burt, J.E. & Barber, G.M. (1996). Elementary Statistics for Geographers (2nd ed.). Guilford Press. ISBN 1-57230-003-8 · Wong, D.W.S. & Lee, J. (2005). Statistical Analysis of Geographic Information with ArcView GIS and ArcGIS. Wiley. ISBN 0-471-46899-8 · Mitchell, A. (2005). The ESRI Guide to GIS Analysis, Volume 2: Spatial Measurements and Statistics. ESRI Press. ISBN 1-58948-116-1 · Cromley, R.G. & McLafferty, S.L. (2012). GIS and Public Health (2nd ed.). Guilford Press. ISBN 1-60918-472-4 · Greene, R.P. & Pick, J.B. (2012). Exploring the Urban Community: A GIS Approach (2nd ed.). Pearson. ISBN 0-321-75159-9
⬮

#### Directional Distribution (Standard Deviational Ellipse)

directional_distribution
Computes the Standard Deviational Ellipse (SDE) — a polygon ellipse that simultaneously captures the spatial dispersion, directional orientation, and anisotropy of a point pattern. Introduced by D. Welty Lefever in 1926, the SDE remains one of the most widely used centrographic tools in urban geography, criminology, epidemiology, and transportation planning. The ellipse's semi-major axis shows the direction of maximum spatial spread; the semi-minor axis shows the direction of minimum spread; the rotation angle $\theta$ quantifies the primary trend axis measured from due East (converted to compass degrees in output). Available at 1, 2, or 3 standard deviations.

##### Theoretical Background

The SDE occupies a central place in the centrographic tradition alongside Mean Center and Standard Distance (this group), but its influence extends further: it is the two-dimensional special case of the general theory of confidence ellipses for a bivariate normal distribution, so a k-SD ellipse can be read, approximately and under bivariate normality, as a confidence region for the location of a randomly drawn feature. Wang, Shi and Miao (2015) formalized this connection explicitly, deriving exact confidence levels for the SDE at arbitrary standard-deviation multipliers and extending the construction to higher dimensions.

This dual identity — an intuitive visual summary that is also a defensible statistical object — is why the SDE became the default descriptive-geography tool in early GIS packages (Mitchell, 2005), where ad hoc convex-hull or bounding-box envelopes had previously served the same visual role without any statistical grounding.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroid used)
WEIGHT_FIELD | Numeric Field (opt) | — | Weighting variable; unweighted if omitted
STD_DEV | Enum | 1 | Ellipse size: 1, 2, or 3 standard deviations
OUTPUT | Vector Layer (Polygon) | — | Output ellipse polygon with 72-vertex smoothness

##### Output Fields

`mean_x` — ellipse center X coordinate (map units) · `mean_y` — ellipse center Y coordinate (map units) · `rotation` — ellipse rotation angle in degrees (0° = due North per compass convention) · `semi_major` — semi-major axis length ($k \cdot \sigma_{max}$) in map units · `semi_minor` — semi-minor axis length ($k \cdot \sigma_{min}$) in map units · `std_dev` — selected SD multiplier (1, 2, or 3) · `input_n` — number of valid features used · `skip_geom` — features skipped (empty geometry) · `bad_w` — features with null/invalid weight values

##### Equations

Mean-center the coordinates:
$$ \tilde{x}_i = x_i - \bar{X}_w \qquad \tilde{y}_i = y_i - \bar{Y}_w $$
Covariance components (weighted):
$$ \Sigma_{xx} = \frac{\sum w_i \tilde{x}_i^2}{\sum w_i} \qquad \Sigma_{yy} = \frac{\sum w_i \tilde{y}_i^2}{\sum w_i} \qquad \Sigma_{xy} = \frac{\sum w_i \tilde{x}_i \tilde{y}_i}{\sum w_i} $$
Rotation angle (principal orientation):
$$ \theta = \frac{1}{2} \arctan\!2\!\left(2\Sigma_{xy},\; \Sigma_{xx} - \Sigma_{yy}\right) $$
This is equivalent to the angle of the first eigenvector of the weighted covariance matrix $\mathbf{C} = \begin{pmatrix} \Sigma_{xx} & \Sigma_{xy} \\ \Sigma_{xy} & \Sigma_{yy} \end{pmatrix}$.
Standard deviations along rotated axes:
$$ \sigma_{x'} = \sqrt{\frac{\sum w_i (\tilde{x}_i \cos\theta - \tilde{y}_i \sin\theta)^2}{\sum w_i}} \qquad \sigma_{y'} = \sqrt{\frac{\sum w_i (\tilde{x}_i \sin\theta + \tilde{y}_i \cos\theta)^2}{\sum w_i}} $$
Semi-axes with standard-deviation multiplier $k$:
$$ a = k \cdot \max(\sigma_{x'}, \sigma_{y'}) \qquad b = k \cdot \min(\sigma_{x'}, \sigma_{y'}) $$
The rotation angle is adjusted so that $\theta$ always refers to the semi-major axis direction (if $\sigma_{y'} > \sigma_{x'}$, then $\theta$ is incremented by $\pi/2$).
Derived shape metrics:
$$ \text{Ellipse area} = \pi \cdot a \cdot b \qquad \text{Eccentricity} = \sqrt{1 - \frac{b^2}{a^2}} \qquad \text{Elongation ratio} = \frac{a}{b} $$
Eccentricity ranges from 0 (perfect circle — isotropic dispersion) to 1 (nearly a line — extreme anisotropy). The elongation ratio $a/b$ measures how many times longer the major axis is than the minor: $a/b = 1$ for a circle, $a/b \approx 2$ for moderate anisotropy, $a/b > 3$ for strong directional concentration.

##### Interpretation

Urban growth tracking. The classic SDE application: compute population-weighted ellipses for successive census periods. A growing semi-major axis indicates suburban expansion along a corridor. A rotating $\theta$ indicates the city is "pivoting" — e.g., from a N-S orientation along a rail line to an E-W orientation along a new highway. A shrinking eccentricity (more circular) indicates polycentric or infill growth.
Crime and disease mapping. Compare ellipses for different crime types or disease incidence categories. Narrow, elongated ellipses suggest the phenomenon follows a linear corridor (e.g., a transit line, a river valley). Broad, circular ellipses suggest area-wide prevalence. Non-overlapping ellipses for different subgroups indicate spatial segregation of the phenomenon.
Ellipse size selection. 1 SD captures approximately 63% of features under bivariate normality. 2 SD captures ~98%. 3 SD is essentially the full-data envelope. Use 1 SD for core concentration analysis; compare 2 SD ellipses across groups to assess spatial overlap; use 3 SD to identify extreme outliers that lie outside the ellipse.
Implementation note. The engine computes $\theta$ via $\frac{1}{2}\arctan\!2(2\Sigma_{xy}, \Sigma_{xx} - \Sigma_{yy})$. The output `rotation` field converts from radians to degrees. Unlike some GIS implementations that report the original $\theta$ in the first-quadrant range, this implementation ensures the rotation angle correctly references the semi-major axis direction by testing whether $\sigma_{y'} > \sigma_{x'}$ and adjusting $\theta$ by $+\pi/2$ if necessary.
Historical note. Lefever's original 1926 formula used a different rotation-angle expression: $\tan 2\theta = \big[\Sigma\tilde{x}^2 - \Sigma\tilde{y}^2 + \sqrt{(\Sigma\tilde{x}^2 - \Sigma\tilde{y}^2)^2 + 4(\Sigma\tilde{x}\tilde{y})^2}\big] / (2\Sigma\tilde{x}\tilde{y})$, which always produces an acute angle. Furfey (1927) immediately criticized this as geometrically inconsistent, noting it does not minimize the projected variance. Yuill (1971) definitively settled the matter in favor of the eigenvector-based $\frac{1}{2}\arctan\!2(2\Sigma_{xy}, \Sigma_{xx} - \Sigma_{yy})$ formulation. The GeoStats Lab implementation follows the Yuill/Furfey convention.
See also: Standard Distance

##### References

Lefever, D.W. (1926). "Measuring Geographic Concentration by Means of the Standard Deviational Ellipse." American Journal of Sociology 32(1): 88–94. doi:10.1086/214027 · Furfey, P.H. (1927). "A Note on Lefever's 'Standard Deviational Ellipse'." American Journal of Sociology 33(1): 94–98. doi:10.1086/214336 · Yuill, R.S. (1971). "The Standard Deviational Ellipse: An Updated Tool for Spatial Description." Geografiska Annaler B 53(1): 28–39. doi:10.1080/04353684.1971.11879353 · Gong, J. (2002). "Clarifying the Standard Deviational Ellipse." Geographical Analysis 34(2): 155–167. doi:10.1111/j.1538-4632.2002.tb01082.x · Wang, B., Shi, W. & Miao, Z. (2015). "Confidence Analysis of Standard Deviational Ellipse and Its Extension into Higher Dimensional Euclidean Space." PLOS ONE 10(3): e0118537. doi:10.1371/journal.pone.0118537 · Austin, R.F. (1984). "Measuring and Comparing Two-Dimensional Shapes." In Gaile & Willmott (eds.), Spatial Statistics and Models, D. Reidel, pp. 293–312. doi:10.1007/978-94-017-3048-8_16 · Bachi, R. (1963). "Standard Distance Measures and Related Methods for Spatial Analysis." Papers of the RSA 10(1): 83–132. doi:10.1007/BF01934680 · Sviatlovsky, E.E. & Eells, W.C. (1937). "The Centrographical Method and Regional Analysis." Geographical Review 27(2): 240–254. doi:10.2307/210093 · Kellerman, A. (1981). "Centrographic Measures in Geography." CATMOG 32. Geo Abstracts, Norwich. ISBN 0-86094-081-2 · Mitchell, A. (2005). The ESRI Guide to GIS Analysis, Volume 2. ESRI Press. ISBN 1-58948-116-1
➤

#### Linear Directional Mean

linear_directional_mean
Computes the mean direction (compass bearing, $0^\circ$ = North, clockwise) and the mean length of a set of line features using length-weighted circular statistics. The result is a single representative trend line centered at the geographic mean of all line midpoints, extending half the mean length in each direction along the mean bearing. Designed for analyzing street-network orientation (e.g., identifying a city's dominant grid angle), migration-flow vectors, prevailing wind fields, fault-line patterns in geology, or any dataset where line direction carries analytical meaning. Circular (periodic) statistics correctly handle the wrap-around problem: $359^\circ$ and $1^\circ$ average to $0^\circ$, not $180^\circ$.

##### Theoretical Background

Linear Directional Mean belongs to circular (directional) statistics, a branch developed specifically because ordinary linear statistics break down on periodic data: the arithmetic mean of $1^\circ$ and $359^\circ$ is $180^\circ$, which is exactly backwards for a compass bearing that in reality differs by only $2^\circ$. Rayleigh (1880) derived the foundational result — the resultant-length distribution of randomly phased vectors summed together — while studying wave interference in physics, a result circular statistics later adopted wholesale as the basis for testing directional uniformity (the Rayleigh test this tool reports as $Z$). Von Mises (1918) supplied the circular analogue of the normal distribution, and Mardia & Jupp (2000) and Fisher (1993) later consolidated the field into the modern reference texts this implementation follows.

Boeing (2019) applied exactly this framework to street-network orientation at a global, comparative scale, quantifying the "griddedness" of hundreds of cities via the same mean-resultant-length statistic ($\bar{R}$) this tool computes — the planning-applications guidance below draws directly on that framework.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer (Line) | — | Input line layer (LineString or MultiLineString)
OUTPUT | Vector Layer (Line) | — | Output single trend line with diagnostic attributes

Implicit length weighting. Each line's contribution to the circular mean is weighted by its Euclidean length $\ell_i = \sqrt{(x_{end} - x_{start})^2 + (y_{end} - y_{start})^2}$. Longer lines carry proportionally more influence on the mean direction. For multi-part geometries, only the first polyline component is used. This length-weighting is intrinsic to the algorithm and does not require a user-supplied weight field.

##### Output Fields

`mean_angle` — mean compass bearing in degrees ($0^\circ$ = North, clockwise) · `mean_length` — arithmetic mean of input line lengths, used as the trend line's total length (map units) · `center_x` — X coordinate of the trend line midpoint (geographic mean of all line midpoints) · `center_y` — Y coordinate of the trend line midpoint · `line_count` — number of valid line features processed

##### Equations

Individual line bearing (compass convention: $0^\circ$ = North, clockwise from North):
$$ \theta_i = \arctan\!2(dx_i,\; dy_i) \qquad\text{where}\qquad dx_i = x_{end} - x_{start},\;\; dy_i = y_{end} - y_{start} $$
Note: $\arctan\!2(dx, dy)$ rather than the standard $\arctan\!2(y, x)$ — this swap produces a compass bearing where $0^\circ$ points North. The angle increases clockwise: $90^\circ$ = East, $180^\circ$ = South, $270^\circ$ = West.
Line length (implicit weight):
$$ \ell_i = \sqrt{dx_i^2 + dy_i^2} $$
Circular mean of bearings (length-weighted):
$$ \bar{\theta} = \arctan\!2\!\left(\sum_{i=1}^{N} \ell_i \sin\theta_i,\;\; \sum_{i=1}^{N} \ell_i \cos\theta_i\right) \bmod 360^\circ $$
This uses the vector-addition principle of circular statistics: represent each bearing as a unit vector, scale by length, sum the vectors, and take the resultant direction.
Mean resultant length $ \bar{R} $ (measure of directional concentration, $0 \le \bar{R} \le 1$):
$$ \bar{R} = \frac{1}{\sum \ell_i} \cdot \sqrt{\left(\sum \ell_i \sin\theta_i\right)^2 + \left(\sum \ell_i \cos\theta_i\right)^2} $$
Circular variance (dispersion measure):
$$ V = 1 - \bar{R} \qquad (0 \le V \le 1) $$
Circular standard deviation (in radians):
$$ \nu = \sqrt{-2 \ln \bar{R}} \qquad (\text{valid when } \bar{R} > 0) $$
Rayleigh test statistic for uniformity (tests $H_0$: directions are uniformly distributed around the circle):
$$ Z = N \cdot \bar{R}^2 $$
A large $Z$ (or equivalently, $\bar{R}$ near 1) rejects the null of uniformity — the data have a preferred direction. Critical values: for $N > 50$, $Z > 3.0$ is significant at $\alpha = 0.05$.
Trend line center (geographic mean of line midpoints):
$$ \bar{X}_{mid} = \frac{1}{N}\sum_{i=1}^{N} \frac{x_{start,i} + x_{end,i}}{2} \qquad \bar{Y}_{mid} = \frac{1}{N}\sum_{i=1}^{N} \frac{y_{start,i} + y_{end,i}}{2} $$
Trend line geometry: The output line extends $\bar{\ell}/2$ in each direction from $(\bar{X}_{mid}, \bar{Y}_{mid})$ along bearing $\bar{\theta}$, where $\bar{\ell} = \frac{1}{N}\sum \ell_i$.
$$ (x_{\pm}, y_{\pm}) = \left(\bar{X}_{mid} \pm \frac{\bar{\ell}}{2} \sin\bar{\theta},\;\; \bar{Y}_{mid} \pm \frac{\bar{\ell}}{2} \cos\bar{\theta}\right) $$

##### Interpretation

Directional agreement vs. randomness. $\bar{R}$ quantifies how strongly lines agree on a direction. $\bar{R} \approx 1$ means nearly all lines point the same way (strong directional consensus). $\bar{R} \approx 0$ means lines point in all directions with no preference — as in a perfect orthogonal grid where each direction is equally represented. Most urban street networks show $\bar{R}$ in the $0.1$ – $0.5$ range, reflecting the dominance of orthogonal grid alignments without a single preferred compass direction.
Planning applications. (1) Street network analysis: Compute LDM for a city's street centerlines to identify the dominant grid orientation. Compare across neighborhoods — an old-medieval district typically shows $\bar{R} \approx 0$ (no dominant direction), while a 19th-century gridiron neighborhood shows $\bar{R} \approx 0.5$ with the mean angle aligned to the grid. (2) Migration analysis: Compute LDM on inter-regional migration flow lines to determine the net directional tendency of population movement. (3) Geological fabric analysis: Compute LDM on fault traces to characterize regional tectonic stress orientation. (4) Ecological corridors: Compute LDM on wildlife movement paths to identify prevailing migration direction.
Axis ambiguity. Note that the mean direction is an axial measure: a line pointing $45^\circ$ (NE) and a line pointing $225^\circ$ (SW) point in opposite directions. The LDM treats them as having different bearings. For undirected line analysis (e.g., street orientation where N-S streets are symmetric), consider doubling the angles ($\theta_i' = 2\theta_i \bmod 360^\circ$), computing the circular mean, and halving the result — this is the axial mean rather than the directional mean. The current implementation computes the directional mean; users needing the axial mean can transform angles before and after computation.

##### References

Mardia, K.V. & Jupp, P.E. (2000). Directional Statistics. Wiley. doi:10.1002/9780470316979 · Fisher, N.I. (1993). Statistical Analysis of Circular Data. Cambridge University Press. doi:10.1017/CBO9780511564345 · Batschelet, E. (1981). Circular Statistics in Biology. Academic Press. ISBN 0-12-081050-6 · Rayleigh, Lord (J.W. Strutt) (1880). "On the Resultant of a Large Number of Vibrations of the Same Pitch and of Arbitrary Phase." Philosophical Magazine 10(60): 73–78. doi:10.1080/14786448008626905 · von Mises, R. (1918). "Uber die 'Ganzzahligkeit' der Atomgewichte und verwandte Fragen." Physikalische Zeitschrift 19: 490–500. (Origin of the von Mises distribution for circular data) · Jammalamadaka, S.R. & SenGupta, A. (2001). Topics in Circular Statistics. World Scientific. doi:10.1142/4031 · Berens, P. (2009). "CircStat: A MATLAB Toolbox for Circular Statistics." Journal of Statistical Software 31(10): 1–21. doi:10.18637/jss.v031.i10 · Mitchell, A. (2005). The ESRI Guide to GIS Analysis, Volume 2. ESRI Press. ISBN 1-58948-116-1 · Boeing, G. (2019). "Urban Street Network Orientation." Applied Network Science 4(1): 1–19. doi:10.1007/s41109-019-0189-1 · Davis, J.C. (2002). Statistics and Data Analysis in Geology (3rd ed.). Wiley. ISBN 0-471-17275-8
05

### Models and Scenarios

Spatial econometric and regression models that estimate relationships between a dependent variable and explanatory variables, with explicit treatment of spatial dependence and spatial heterogeneity. This group progresses from aspatial screening (OLS, Exploratory Regression) through a formal specification test (Lagrange Multiplier Diagnostics) to spatial dependence models (Spatial Lag, Spatial Error, Spatial Durbin), an eigenvector-based alternative that avoids estimating an autoregressive parameter entirely (Eigenvector Spatial Filtering), and local and multiscale models (GWR, MGWR), with tools for sensitivity testing and model comparison.

Prerequisite knowledge. Tools in this group assume familiarity with linear regression diagnostics (VIF, residual analysis, AIC-based model selection) and the distinction between spatial lag dependence (substantive spatial spillover) and spatial error dependence (nuisance spatial autocorrelation in residuals). The Workflow Advisor (00) can recommend an entry point based on your analytical goal.
📊

#### Ordinary Least Squares (OLS) Spatial Regression

ols_regression
The foundational regression estimator in spatial econometrics. OLS models a continuous dependent variable as a linear combination of explanatory variables plus an intercept, minimising the sum of squared residuals. GeoStats Lab's OLS extends the standard estimator with a full battery of spatial and distributional diagnostics — Jarque-Bera normality, Koenker's studentised Breusch-Pagan heteroskedasticity, and Moran's I on residuals — so the analyst can judge whether the classical assumptions hold before committing to a spatial specification. Always run this before any spatial regression variant. Implemented entirely in NumPy; requires no external packages.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry type)
DEP_VAR | Numeric Field | — | Dependent variable (continuous, unbounded)
INDEPENDENTS | Field (multi-select) | — | Explanatory variable fields (one or more numeric)
OUTPUT | Vector Layer | — | Output layer with residual and std. residual fields + graduated renderer
HTML_REPORT | File (HTML) | — | Output regression diagnostics report (optional)

##### Output Fields (per feature, appended to source)

`residual` — raw residual (observed − predicted) · `std_res` — standardised residual (residual / σ), auto-styled with 7-class diverging red-white-blue graduated renderer centred on zero

##### Diagnostics in HTML Report

Coefficient table — estimate, SE, t-statistic, p-value for each predictor plus intercept · Model fit — R², adjusted R², residual standard error (RSE), residual degrees of freedom · Jarque-Bera — skewness/kurtosis normality test on residuals (JB statistic, p-value), flagged "Normally Distributed" or "Non-Normal Residuals" · Koenker's Breusch-Pagan — studentised heteroskedasticity test (BP statistic, p-value), flagged "Homoskedastic" or "Heteroskedastic" · Residual Moran's I — spatial autocorrelation index on residuals, flagged when |I| > 0.15 (screening threshold) · Model quality — record completeness, predictor count, skipped-record tally, constant-variable warnings

##### Core Estimator

OLS estimator.
$$\hat{\boldsymbol{\beta}} = (\mathbf{X}^\top \mathbf{X})^{-1} \mathbf{X}^\top \mathbf{y}$$
$$\hat{\mathbf{y}} = \mathbf{X}\hat{\boldsymbol{\beta}}, \quad \mathbf{e} = \mathbf{y} - \mathbf{X}\hat{\boldsymbol{\beta}}$$
$$\hat{\sigma}^2 = \frac{\mathbf{e}^\top \mathbf{e}}{n - k - 1} = \frac{\text{RSS}}{n - k - 1}$$
$$\text{Var}(\hat{\boldsymbol{\beta}}) = \hat{\sigma}^2 (\mathbf{X}^\top \mathbf{X})^{-1}, \quad \text{SE}(\hat{\beta}_j) = \sqrt{\text{Var}(\hat{\beta}_j)_{jj}}$$
$$t_j = \frac{\hat{\beta}_j}{\text{SE}(\hat{\beta}_j)}, \quad p_j = 2\left[1 - \Phi(|t_j|)\right]$$

##### Model Fit and Selection Criteria

$$R^2 = 1 - \frac{\text{RSS}}{\text{TSS}}, \quad \text{TSS} = \sum_{i=1}^{n} (y_i - \bar{y})^2$$
$$R^2_{\text{adj}} = 1 - (1 - R^2) \frac{n-1}{n-k-1}$$
$$\text{AIC} = n \ln\!\left(\frac{\text{RSS}}{n}\right) + 2k$$
$$\text{AICc} = \text{AIC} + \frac{2k(k+1)}{n-k-1} \quad \text{(Hurvich & Tsai, 1989)}$$

##### Multicollinearity Diagnostics

$$\text{VIF}_j = \frac{1}{1 - R_j^2}$$
where $R_j^2$ is the $R^2$ obtained by regressing predictor $j$ on all other predictors. VIF > 10 signals severe collinearity (Belsley, Kuh & Welsch, 1980).

##### Residual Diagnostics

Jarque-Bera normality test (Jarque & Bera, 1987).
$$S = \frac{\frac{1}{n}\sum e_i^3}{\left(\frac{1}{n}\sum e_i^2\right)^{3/2}}, \quad K = \frac{\frac{1}{n}\sum e_i^4}{\left(\frac{1}{n}\sum e_i^2\right)^2}$$
$$\text{JB} = \frac{n}{6}\left(S^2 + \frac{(K-3)^2}{4}\right) \sim \chi^2(2)$$
Koenker's Breusch-Pagan heteroskedasticity test (Breusch & Pagan, 1979; Koenker, 1981).
$$g_i = e_i^2, \quad \text{BP} = n \cdot R_{\text{aux}}^2 \sim \chi^2(k)$$
where $R_{\text{aux}}^2$ is obtained from regressing $g$ on $\mathbf{X}$. The Koenker variant studentises the auxiliary regression, making it robust to non-normality.
Moran's I on residuals (Cliff & Ord, 1981; Anselin, 1988).
$$I_{\text{resid}} = \frac{n}{S_0} \cdot \frac{\mathbf{e}^\top \mathbf{W} \mathbf{e}}{\mathbf{e}^\top \mathbf{e}}, \quad S_0 = \sum_i \sum_j w_{ij}$$ A significant $I_{\text{resid}}$ (screening threshold $|I| > 0.15$) indicates residual spatial autocorrelation, violating the OLS assumption of independent errors.

##### Interpretation Guide

Step 1 — Coefficient sign and significance. Check that coefficient signs align with planning theory. For each predictor: if p < 0.05, the effect is statistically distinguishable from zero at the 95% level. Standard errors from the diagonal of $\hat{\sigma}^2(\mathbf{X}^\top\mathbf{X})^{-1}$ assume homoskedasticity — if Koenker's BP is significant, these SEs are unreliable.
Step 2 — Model fit. R² measures the proportion of variance explained. In cross-sectional planning data, R² of 0.3–0.7 is typical; values above 0.9 often signal overfitting or that the dependent variable is a linear combination of predictors. Adjusted R² penalises unnecessary predictors; use AICc for model comparison.
Step 3 — Residual diagnostics. Jarque-Bera significant (p < 0.05) → residuals are non-normal; t-tests and p-values should be interpreted cautiously. Koenker's BP significant → heteroskedasticity present; consider robust SEs or variable transformations. Moran's I significant → spatial structure remains in residuals; a spatial model (SAR or SEM) is indicated.
Step 4 — Diagnostic hierarchy. Address multicollinearity first (drop or combine high-VIF variables), then re-run OLS. If residual Moran's I remains significant, the best-fitting OLS specification still violates the independence assumption: progress to SAR or SEM. If all diagnostics are clean, OLS coefficients may be used as a global baseline for spatial comparison.
See also: Exploratory Regression · Generalized Linear Regression · Spatial Lag Regression (SAR) · Spatial Error Regression (SEM)

##### Key Academic References

1. Belsley, D.A., Kuh, E. & Welsch, R.E. (1980). Regression Diagnostics: Identifying Influential Data and Sources of Collinearity. Wiley. DOI: 10.1002/0471725153

2. Breusch, T.S. & Pagan, A.R. (1979). "A Simple Test for Heteroscedasticity and Random Coefficient Variation." Econometrica 47(5): 1287–1294. DOI: 10.2307/1911963

3. Jarque, C.M. & Bera, A.K. (1987). "A Test for Normality of Observations and Regression Residuals." International Statistical Review 55(2): 163–172. DOI: 10.2307/1403192

4. Koenker, R. (1981). "A Note on Studentizing a Test for Heteroscedasticity." Journal of Econometrics 17(1): 107–112. DOI: 10.1016/0304-4076(81)90062-2

5. Moran, P.A.P. (1950). "Notes on Continuous Stochastic Phenomena." Biometrika 37(1/2): 17–23. DOI: 10.1093/biomet/37.1-2.17

6. Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. Pion, London. ISBN: 978-0-85086-081-8

7. Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer, Dordrecht. DOI: 10.1007/978-94-015-7799-1

8. Hurvich, C.M. & Tsai, C.L. (1989). "Regression and Time Series Model Selection in Small Samples." Biometrika 76(2): 297–307. DOI: 10.1093/biomet/76.2.297

9. Akaike, H. (1974). "A New Look at the Statistical Model Identification." IEEE Transactions on Automatic Control 19(6): 716–723. DOI: 10.1109/TAC.1974.1100705

10. White, H. (1980). "A Heteroskedasticity-Consistent Covariance Matrix Estimator and a Direct Test for Heteroskedasticity." Econometrica 48(4): 817–838. DOI: 10.2307/1912934

11. Anselin, L. & Bera, A.K. (1998). "Spatial Dependence in Linear Regression Models with an Introduction to Spatial Econometrics." In Handbook of Applied Economic Statistics, Marcel Dekker, pp. 237–289. DOI: 10.1201/9781482273847

12. LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. CRC Press, Boca Raton. DOI: 10.1201/9781420064254

🌿

#### Lagrange Multiplier Diagnostics (Spatial Model Selection)

lm_diagnostics
The formal test this plugin's OLS, Spatial Lag, and Spatial Error tools have always referenced but never provided: Anselin, Bera, Florax and Yoon's (1996) Lagrange Multiplier battery, which tests OLS residuals for two distinct forms of spatial dependence — a missing spatially lagged dependent variable (LM-lag) and spatially correlated errors (LM-error) — and provides ROBUST versions of each that remain valid even when the other form of dependence is also present. This is the formal answer to "should I use Spatial Lag or Spatial Error," replacing guesswork or a residual-map eyeball test with a citable chi-square(1) hypothesis test and an explicit decision rule.

##### 1. Theoretical Background

Origins. Luc Anselin had already derived the individual LM-lag and LM-error tests in his 1988 textbook Spatial Econometrics: Methods and Models, building on the general Lagrange Multiplier testing framework of Breusch and Pagan (1980). The 1996 paper with Bera, Florax and Yoon, published in Regional Science and Urban Economics, solved a specific practical problem: the classic LM-lag and LM-error tests each have poor power when the OTHER form of dependence is present but ignored — LM-lag can appear significant purely because of unmodeled spatial error correlation, and vice versa. Their robust versions correct each test for the presence of the other, making the four-statistic battery together a genuinely reliable specification-search tool rather than two easily-confused single tests.

Why this fills a real gap in the plugin. This plugin's OLS Regression tool already reports residual Moran's I and explicitly recommends a spatial specification when it is significant; its Spatial Autoregression and Spatial Error Regression tools both explain the theoretical difference between a spillover process (favoring SAR) and nuisance spatially-structured omitted variables (favoring SEM) — but neither ever gave the analyst a formal statistical test to make that choice. Significant residual Moran's I alone cannot distinguish a lag process from an error process; the LM battery can.

The information-matrix structure. Both the classic and robust LM statistics are built from the same three quantities: the two "scores" (\(e'Wy\) and \(e'We\), how strongly OLS residuals correlate with the spatial lags of \(y\) and of the residuals themselves) and two information-matrix terms \(T\) and \(D\) that depend on the spatial weights matrix and, for \(D\), on the fitted values. \(T\) is common to both the lag and error tests (it appears as the LM-error denominator and as part of the LM-lag denominator \(D\)), which is precisely why the robust corrections take the clean algebraic form they do — each robust statistic subtracts off exactly the contribution the OTHER score would explain given this shared structure.

A mathematical identity used to validate this implementation. LM-lag + Robust LM-error is algebraically guaranteed to equal LM-error + Robust LM-lag — both expressions equal the joint "SARMA" statistic testing for lag AND error dependence simultaneously (a chi-square(2) test). This plugin's engine was validated against this exact identity (to floating-point precision) on multiple synthetic datasets, plus directional checks confirming that a true spatial-lag data-generating process produces a large, significant LM-lag AND Robust LM-lag with a small, non-significant Robust LM-error, and symmetrically for a true spatial-error process — the textbook-predicted behavior in both cases.

##### 2. Mathematical Formulation

Let \(e\) be the OLS residual vector, \(\hat{y}\) the OLS fitted values, \(\sigma^2 = e'e/n\), \(W\) the row-standardized spatial weights matrix, and \(M = I - X(X'X)^{-1}X'\) the OLS residual-maker matrix.

Common building blocks:

$$T = \text{tr}(W'W + W^2), \qquad D = T + \frac{(W\hat{y})'M(W\hat{y})}{\sigma^2} \tag{1}$$ $$S_\rho = \frac{e'Wy}{\sigma^2} \quad \text{(lag score)}, \qquad S_\lambda = \frac{e'We}{\sigma^2} \quad \text{(error score)} \tag{2}$$

Classic LM tests (each ignores the other form of dependence):

$$LM_{\text{error}} = \frac{S_\lambda^2}{T}, \qquad LM_{\text{lag}} = \frac{S_\rho^2}{D} \tag{3}$$

Robust LM tests (each corrected for the presence of the other):

$$RLM_{\text{lag}} = \frac{(S_\rho - S_\lambda)^2}{D - T}, \qquad RLM_{\text{error}} = \frac{\left(S_\lambda - \frac{T}{D}S_\rho\right)^2}{T\left(1 - \frac{T}{D}\right)} \tag{4}$$

Joint SARMA test and the validating identity:

$$SARMA = LM_{\text{lag}} + RLM_{\text{error}} = LM_{\text{error}} + RLM_{\text{lag}} \sim \chi^2(2) \tag{5}$$

p-values (exact, not approximated):

$$p_{\chi^2(1)}(x) = 1 - \text{erf}\left(\sqrt{x/2}\right), \qquad p_{\chi^2(2)}(x) = e^{-x/2} \tag{6}$$
Implementation note. The engine (`core/advanced_stats_engines.py::calculate_lm_diagnostics`) fits OLS internally via the normal equations, builds a dense weights matrix from the plugin's standard neighbor/weight dictionaries, and computes \((W\hat{y})'M(W\hat{y})\) without ever forming the full \(n \times n\) matrix \(M\) explicitly (using the algebraic identity \(a'Ma = a'a - (a'X)(X'X)^{-1}(X'a)\)). Validated on synthetic spatial-lag and spatial-error data-generating processes on an 8×8 grid: the true-lag DGP returned LM-lag=47.1 (p<0.0001), Robust LM-lag=33.3 (p<0.0001), Robust LM-error=0.03 (p=0.87); the true-error DGP returned LM-error=8.8 (p=0.003), Robust LM-error=7.3 (p=0.007), Robust LM-lag=0.03 (p=0.87) — the textbook-predicted directional pattern in both cases, and the SARMA identity held to floating-point precision throughout.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
DEP_VAR | Numeric Field | — | — | Dependent variable field
INDEPENDENTS | Numeric Fields | — | ≥ 1 field | Independent variable fields
WEIGHT_TYPE | Enum | Queen contiguity | Queen / Rook / KNN / Distance Band | Spatial relationship used to build the weights matrix
KNN | Integer | 8 | ≥ 1 | Number of neighbors (KNN weights only)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (Distance Band weights only)
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report

##### 4. Output Description

Field | Type | Description
--- | --- | ---
lm_lag / lm_lag_p | Double | Classic LM-lag statistic and chi-square(1) p-value
lm_error / lm_error_p | Double | Classic LM-error statistic and chi-square(1) p-value
rlm_lag / rlm_lag_p | Double | Robust LM-lag statistic and chi-square(1) p-value
rlm_error / rlm_error_p | Double | Robust LM-error statistic and chi-square(1) p-value
sarma / sarma_p | Double | Joint SARMA statistic and chi-square(2) p-value
recommendation | String | Plain-language specification recommendation following Anselin's classification rule

##### 5. Interpretation Guide

Anselin's classification rule.

Pattern | Recommended Specification
--- | ---
Neither LM-lag nor LM-error significant | OLS is adequate — no spatial specification indicated
Only LM-lag significant | Spatial Lag (SAR) or Spatial Durbin
Only LM-error significant | Spatial Error (SEM)
Both significant, only Robust LM-lag significant | Spatial Lag (SAR) or Spatial Durbin
Both significant, only Robust LM-error significant | Spatial Error (SEM)
Both significant, both robust tests significant | Spatial Durbin Model or another combined lag+error specification

Do not skip straight to the robust tests. The robust corrections exist specifically to resolve ambiguity when BOTH classic tests are significant; when only one classic test is significant, that result alone is already sufficient and reliable — checking the robust versions in that case adds no information and, applied incorrectly as the primary criterion, can needlessly override a clear classic-test signal.

See also: OLS Regression · Spatial Lag Regression (SAR) · Spatial Error Regression (SEM) · Spatial Durbin Model

##### 6. Literature

Anselin, L., Bera, A.K., Florax, R. & Yoon, M.J. (1996). "Simple Diagnostic Tests for Spatial Dependence." Regional Science and Urban Economics 26(1): 77–104. DOI: 10.1016/0166-0462(95)02111-6 — The paper this tool implements; introduces the robust LM tests and the classification decision rule.

Anselin, L. (1988). Spatial Econometrics: Methods and Models. Dordrecht: Kluwer. DOI: 10.1007/978-94-015-7799-1 — Derives the original (non-robust) LM-lag and LM-error tests this paper's robust versions build on.

Breusch, T.S. & Pagan, A.R. (1980). "The Lagrange Multiplier Test and Its Applications to Model Specification in Econometrics." Review of Economic Studies 47(1): 239–253. DOI: 10.2307/2297111 — The general LM testing framework this spatial application is built on.

Anselin, L. & Rey, S. (1991). "Properties of Tests for Spatial Dependence in Linear Regression Models." Geographical Analysis 23(2): 112–131. DOI: 10.1111/j.1538-4632.1991.tb00228.x — Monte Carlo evidence on the power of the classic (non-robust) LM tests, motivating the robust extension.

Florax, R.J.G.M., Folmer, H. & Rey, S.J. (2003). "Specification Searches in Spatial Econometrics: The Relevance of Hendry's Methodology." Regional Science and Urban Economics 33(5): 557–579. DOI: 10.1016/S0166-0462(03)00002-4 — Discusses the LM-based specification search as a systematic model-building strategy.

LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. Boca Raton: CRC Press. DOI: 10.1201/9781420064254 — Textbook treatment situating LM diagnostics within the broader spatial model selection workflow, including the Spatial Durbin alternative.

📈

#### Generalized Linear Regression (GLR)

generalized_linear_regression
Extends regression beyond the continuous-normal assumption using the Generalized Linear Model (GLM) framework of Nelder & Wedderburn (1972). Supports three distribution families: Gaussian (identity link — equivalent to OLS), Logistic (logit link — binary 0/1 outcomes), and Poisson (log link — non-negative integer counts). The model is estimated via Iteratively Reweighted Least Squares (IRLS), a Newton-Raphson procedure that converges to the maximum-likelihood solution. Essential when the dependent variable is a count, a binary classification, or any quantity where the variance is a known function of the mean. Implemented in pure NumPy; requires no external packages.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry type)
DEP_VAR | Numeric Field | — | Dependent variable (continuous, binary 0/1, or non-negative integer counts)
INDEPENDENTS | Field (multi-select) | — | Explanatory variable fields
FAMILY | Enum | Gaussian | Gaussian (continuous OLS-equivalent) / Logistic (binary 0/1) / Poisson (count)
OUTPUT | Vector Layer | — | Output predictions layer with fitted values and residuals
HTML_REPORT | File (HTML) | — | Output GLR diagnostics report (optional)

##### Output Fields

`glr_fit` — fitted value ($\hat{\mu}_i$ on the response scale) · `glr_resid` — response residual ($y_i - \hat{\mu}_i$) · `glr_used` — 1 if the feature was used in the fitted model, otherwise 0 · `glr_class` — predicted class (0/1, logistic only, threshold = 0.5)

##### Generalised Linear Model Framework

Three components of a GLM (McCullagh & Nelder, 1989).
$$\text{Random component: } y_i \sim \mathcal{F}(\mu_i, \phi) \quad \text{(distribution from the exponential family)}$$
$$\text{Systematic component: } \eta_i = \mathbf{x}_i^\top \boldsymbol{\beta} \quad \text{(linear predictor)}$$
$$\text{Link function: } g(\mu_i) = \eta_i$$

##### Link Functions and Distributions

Gaussian (identity link). Equivalent to OLS; solved directly without iteration.
$$\mu_i = \eta_i = \mathbf{x}_i^\top \boldsymbol{\beta}, \quad y_i \sim \mathcal{N}(\mu_i, \sigma^2)$$
Logistic (logit link). Binary outcomes; estimated by IRLS (max. 100 iterations, convergence tol. $10^{-6}$).
$$\eta_i = \log\!\left(\frac{p_i}{1 - p_i}\right) = \mathbf{x}_i^\top \boldsymbol{\beta}, \quad p_i = \frac{1}{1 + e^{-\eta_i}}$$
$$y_i \sim \text{Bernoulli}(p_i), \quad \text{Var}(y_i) = p_i(1-p_i)$$
$$\ell(\boldsymbol{\beta}) = \sum_{i=1}^{n} \left[ y_i \log p_i + (1 - y_i) \log(1 - p_i) \right]$$
Poisson (log link). Count data; estimated by IRLS. Values are clipped at $\eta \in [-30, 30]$ for numerical stability.
$$\eta_i = \log(\mu_i) = \mathbf{x}_i^\top \boldsymbol{\beta}, \quad \mu_i = e^{\eta_i}$$
$$y_i \sim \text{Poisson}(\mu_i), \quad \mathbb{E}[y_i] = \text{Var}(y_i) = \mu_i \;\; \text{(equidispersion)}$$
$$\ell(\boldsymbol{\beta}) = \sum_{i=1}^{n} \left[ y_i \log \mu_i - \mu_i - \log(y_i!) \right]$$

##### IRLS Algorithm (Logistic and Poisson)

At iteration $t+1$, with current estimate $\boldsymbol{\beta}^{(t)}$, working response $z_i$, and working weights $w_i$:
$$\boldsymbol{\beta}^{(t+1)} = (\mathbf{X}^\top \mathbf{W}^{(t)} \mathbf{X})^{-1} \mathbf{X}^\top \mathbf{W}^{(t)} \mathbf{z}^{(t)}$$
Logistic: $w_i = p_i(1-p_i)$, $z_i = \eta_i + \frac{y_i - p_i}{w_i}$, with $p_i$ clamped from $\eta_i \in [-35, 35]$
Poisson: $w_i = \mu_i$, $z_i = \eta_i + \frac{y_i - \mu_i}{\mu_i}$, with $\mu_i \ge 10^{-9}$
Convergence declared when $\max|\boldsymbol{\beta}^{(t+1)} - \boldsymbol{\beta}^{(t)}| < 10^{-6}$.

##### Model Fit and Inference

$$\text{AIC} = -2\ell(\hat{\boldsymbol{\beta}}) + 2k_{\text{params}}$$
$$\text{Cov}(\hat{\boldsymbol{\beta}}) = (\mathbf{X}^\top \hat{\mathbf{W}} \mathbf{X})^{-1}, \quad \text{SE}(\hat{\beta}_j) = \sqrt{\text{Cov}(\hat{\beta}_j)_{jj}}$$
$$z_j = \frac{\hat{\beta}_j}{\text{SE}(\hat{\beta}_j)} \;\; \text{(asymptotically normal under MLE)}$$

##### Interpretation Guide

Gaussian family. Coefficients are interpreted as in OLS — a one-unit increase in $x_j$ changes $y$ by $\beta_j$ units, holding all else constant. The residual spatial autocorrelation test (Moran's I on $\mathbf{e}$) is included in every report.
Logistic family. Coefficients are log-odds ratios. $\exp(\beta_j)$ is the odds ratio: a one-unit increase in $x_j$ multiplies the odds of $y = 1$ by $e^{\beta_j}$. Example: $\beta_j = 0.5$ → $e^{0.5} \approx 1.65$, meaning the odds of the outcome increase by 65%. The report includes a `glr_class` field with threshold = 0.5 for classification accuracy inspection.
Poisson family. Coefficients are log-rate ratios. $\exp(\beta_j)$ is the incidence rate ratio: a one-unit increase in $x_j$ multiplies the expected count by $e^{\beta_j}$. Example: $\beta_j = 0.3$ → $e^{0.3} \approx 1.35$, a 35% increase in expected count. Equidispersion ($\mathbb{E}[y] = \text{Var}(y)$) is assumed; if the residual deviance substantially exceeds the residual degrees of freedom, the data are overdispersed and a negative-binomial model may be warranted.
Warning. The GLR implementations are self-contained NumPy engines. They do not compute deviance residuals, leverage, or Cook's distance. For full GLM diagnostics (including overdispersion tests, Pearson residuals, and influence measures), export the data to R or use `statsmodels` in Python. The output layer includes `glr_fit` and `glr_resid` for manual inspection.
See also: OLS Regression

##### Key Academic References

1. Nelder, J.A. & Wedderburn, R.W.M. (1972). "Generalized Linear Models." Journal of the Royal Statistical Society, Series A 135(3): 370–384. DOI: 10.2307/2344614

2. McCullagh, P. & Nelder, J.A. (1989). Generalized Linear Models (2nd ed.). Chapman & Hall, London. DOI: 10.1007/978-1-4899-3242-6

3. Hilbe, J.M. (2011). Negative Binomial Regression (2nd ed.). Cambridge University Press. DOI: 10.1017/CBO9780511973420

4. Cameron, A.C. & Trivedi, P.K. (2013). Regression Analysis of Count Data (2nd ed.). Cambridge University Press. DOI: 10.1017/CBO9781139013567

5. Hosmer, D.W., Lemeshow, S. & Sturdivant, R.X. (2013). Applied Logistic Regression (3rd ed.). Wiley. DOI: 10.1002/9781118548387

6. Wedderburn, R.W.M. (1974). "Quasi-Likelihood Functions, Generalized Linear Models, and the Gauss-Newton Method." Biometrika 61(3): 439–447. DOI: 10.1093/biomet/61.3.439

7. Akaike, H. (1974). "A New Look at the Statistical Model Identification." IEEE Transactions on Automatic Control 19(6): 716–723. DOI: 10.1109/TAC.1974.1100705

8. Burnham, K.P. & Anderson, D.R. (2002). Model Selection and Multimodel Inference: A Practical Information-Theoretic Approach (2nd ed.). Springer. DOI: 10.1007/b97636

9. Agresti, A. (2015). Foundations of Linear and Generalized Linear Models. Wiley. ISBN: 978-1-118-73030-0

10. Dobson, A.J. & Barnett, A.G. (2018). An Introduction to Generalized Linear Models (4th ed.). Chapman & Hall/CRC. DOI: 10.1201/9781315182780

11. Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer, Dordrecht. DOI: 10.1007/978-94-015-7799-1 — for spatial diagnostics on GLR residuals

12. Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. Pion, London. ISBN: 978-0-85086-081-8

🔄

#### Spatial Lag Regression (SAR / Spatial Autoregressive Model)

spatial_autoregression
The Spatial Autoregressive Model (SAR), also known as the spatial lag model, incorporates the spatially lagged dependent variable $\mathbf{W}\mathbf{y}$ as an additional regressor. This models substantive spatial dependence — the idea that the outcome at location $i$ is directly influenced by outcomes at neighbouring locations $j$. The key parameter $\rho$ (rho) measures the strength and direction of this spatial spillover. Estimated via maximum likelihood using PySAL `spreg.ML_Lag`. Requires the optional `libpysal` and `spreg` packages.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry type)
DEP_VAR | Numeric Field | — | Dependent variable
INDEPENDENTS | Field (multi-select) | — | Explanatory variable fields
WEIGHT_TYPE | Enum | KNN (8) | Queen contiguity / Rook contiguity / K-Nearest Neighbours / Distance Band
KNN | Integer | 8 | Number of neighbours (KNN only)
DISTANCE_BAND | Double | 1000.0 | Distance threshold in map units (distance band only)
OUTPUT | Vector Layer | — | Output layer with predictions, residuals, spatial lag, and audit fields
HTML_REPORT | File (HTML) | — | Output SAR diagnostic report (optional)

##### Output Fields (per feature, appended to source)

`sar_pred` — predicted dependent value ($\hat{y}_i$) · `sar_resid` — residual ($y_i - \hat{y}_i$) · `sar_stdres` — standardised residual (auto-styled with 7-class diverging renderer) · `sar_lag_y` — row-standardised spatial lag of the dependent variable ($\mathbf{W}\mathbf{y}$) · `sar_nbrs` — count of valid neighbours used in the weights graph · `sar_used` — 1 when the feature was used in model fitting; 0 otherwise

##### Model Specification

Spatial Lag Model (SAR).
$$\mathbf{y} = \rho \mathbf{W} \mathbf{y} + \mathbf{X}\boldsymbol{\beta} + \boldsymbol{\varepsilon}, \quad \boldsymbol{\varepsilon} \sim \mathcal{N}(\mathbf{0}, \sigma^2 \mathbf{I}_n)$$
where $\rho$ is the spatial autoregressive coefficient, $\mathbf{W}$ is the row-standardised spatial weights matrix ($n \times n$), $\mathbf{X}$ is the $n \times (k+1)$ design matrix (including intercept), and $\boldsymbol{\beta}$ is the $(k+1) \times 1$ coefficient vector.

##### Reduced Form and Spatial Multiplier

Reduced form.
$$\mathbf{y} = (\mathbf{I}_n - \rho\mathbf{W})^{-1} \mathbf{X}\boldsymbol{\beta} + (\mathbf{I}_n - \rho\mathbf{W})^{-1} \boldsymbol{\varepsilon}$$
$$(\mathbf{I}_n - \rho\mathbf{W})^{-1} = \mathbf{I}_n + \rho\mathbf{W} + \rho^2\mathbf{W}^2 + \rho^3\mathbf{W}^3 + \cdots$$
This spatial multiplier (or Leontief inverse) is the mathematical reason OLS and SAR coefficients are not directly comparable. A change in $x_{jk}$ at location $k$ affects $y$ at location $i$ through: (i) the direct effect via $\beta_j$, (ii) the first-order neighbour effect via $\rho w_{ik}$, (iii) second-order effects via $\rho^2$, and so on (LeSage & Pace, 2009).

##### Maximum-Likelihood Estimation

The log-likelihood function for the spatial lag model (Anselin, 1988, Ch. 6):
$$\ln L(\boldsymbol{\beta}, \rho, \sigma^2) = -\frac{n}{2}\ln(2\pi\sigma^2) + \ln|\mathbf{I}_n - \rho\mathbf{W}| - \frac{(\mathbf{y} - \rho\mathbf{W}\mathbf{y} - \mathbf{X}\boldsymbol{\beta})^\top(\mathbf{y} - \rho\mathbf{W}\mathbf{y} - \mathbf{X}\boldsymbol{\beta})}{2\sigma^2}$$
The Jacobian term $\ln|\mathbf{I}_n - \rho\mathbf{W}|$ ensures that the parameter space of $\rho$ is properly constrained: $\rho \in (1/\lambda_{\min}, 1/\lambda_{\max})$ where $\lambda_{\min}, \lambda_{\max}$ are the eigenvalues of $\mathbf{W}$. For row-standardised $\mathbf{W}$, $\lambda_{\max} = 1$, giving $\rho \in (1/\lambda_{\min}, 1)$. In practice, $|\rho| < 1$ is a necessary condition for stationarity.

##### Spatial Dependence Diagnostics (LM Tests)

The standard Lagrange Multiplier tests (Anselin, 1988; Burridge, 1980) guide the choice between SAR and SEM using OLS residuals $\mathbf{e}$:
LM-Lag (test for spatial lag dependence):
$$\text{LM}_{\text{lag}} = \frac{\left( \frac{\mathbf{e}^\top \mathbf{W} \mathbf{y}}{\mathbf{e}^\top\mathbf{e}/n} \right)^2}{\frac{(\mathbf{W}\mathbf{X}\hat{\boldsymbol{\beta}})^\top(\mathbf{I} - \mathbf{X}(\mathbf{X}^\top\mathbf{X})^{-1}\mathbf{X}^\top)(\mathbf{W}\mathbf{X}\hat{\boldsymbol{\beta}})}{\hat{\sigma}^2} + T}$$
where $T = \text{tr}(\mathbf{W}^2 + \mathbf{W}^\top\mathbf{W})$. Under $H_0: \rho = 0$, $\text{LM}_{\text{lag}} \sim \chi^2(1)$.
LM-Error (test for spatial error dependence):
$$\text{LM}_{\text{err}} = \frac{\left( \frac{\mathbf{e}^\top \mathbf{W} \mathbf{e}}{\mathbf{e}^\top\mathbf{e}/n} \right)^2}{T} \sim \chi^2(1)$$
Robust LM tests (Anselin et al., 1996) adjust each LM statistic for the presence of the other form of dependence, enabling discrimination when both are significant.

##### Model Fit Statistics

$$\text{Pseudo-}R^2 = \frac{\text{Var}(\hat{\mathbf{y}})}{\text{Var}(\mathbf{y})} \quad \text{(squared correlation between observed and predicted)}$$
$$\text{AIC} = -2\ln L(\hat{\boldsymbol{\beta}}, \hat{\rho}, \hat{\sigma}^2) + 2(k+2)$$
$$\text{Schwarz criterion (BIC)} = -2\ln L + (k+2)\ln n$$

##### Interpretation Guide

Rho ($\rho$). The spatial autoregressive coefficient is the signature parameter of the SAR model. $\rho > 0$ and significant → positive spatial spillover: high nearby values of the dependent variable are associated with a higher value at the target location, after controlling for $\mathbf{X}$. In planning terms, this suggests agglomeration, diffusion, or shared amenity effects. $\rho < 0$ and significant → negative spillover: competition, displacement, or checkerboard patterns. $\rho \approx 0$ → the spatial lag adds nothing; OLS is adequate.
Feedback effects. Because $\mathbf{W}\mathbf{y}$ appears on the right-hand side, a change in $x_{jk}$ propagates through the spatial system. The total effect of a variable is the sum of its direct effect (own-location) and indirect effect (spillover to neighbours). SAR coefficients $\beta_j$ from the structural form are not directly comparable to OLS coefficients $\beta_j^{\text{OLS}}$ because they exclude the spatial multiplier. Report direct, indirect, and total effects alongside the structural coefficients (LeSage & Pace, 2009, Ch. 2).
SAR vs. SEM decision. Run OLS first. If residual Moran's I is significant: (a) if LM-lag is significant but LM-error is not → SAR; (b) if LM-error is significant but LM-lag is not → SEM; (c) if both are significant → compare robust forms; (d) if neither is significant but residual Moran's I persists → re-examine the spatial weights definition. The plugin's Model Comparison tool automates this flow.
Weight sensitivity. The spatial autoregressive coefficient is sensitive to $\mathbf{W}$. Test stability by re-running SAR with at least two weight specifications (e.g., KNN $k=8$ vs. Queen contiguity). If $\rho$ changes sign or loses significance, the spatial process may not be robustly identified — be cautious about policy interpretation.
See also: Spatial Error Regression (SEM) · OLS Regression · Model Comparison Matrix

##### Key Academic References

1. Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer, Dordrecht. DOI: 10.1007/978-94-015-7799-1

2. LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. CRC Press, Boca Raton. DOI: 10.1201/9781420064254

3. Burridge, P. (1980). "On the Cliff-Ord Test for Spatial Correlation." Journal of the Royal Statistical Society, Series B 42(1): 107–108. DOI: 10.1111/j.2517-6161.1980.tb01108.x

4. Anselin, L., Bera, A.K., Florax, R. & Yoon, M.J. (1996). "Simple Diagnostic Tests for Spatial Dependence." Regional Science and Urban Economics 26(1): 77–104. DOI: 10.1016/0166-0462(95)02111-6

5. Ord, J.K. (1975). "Estimation Methods for Models of Spatial Interaction." Journal of the American Statistical Association 70(349): 120–126. DOI: 10.1080/01621459.1975.10480272

6. Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. Pion, London. ISBN: 978-0-85086-081-8

7. Anselin, L. & Florax, R.J.G.M. (1995). "Small Sample Properties of Tests for Spatial Dependence in Regression Models." In New Directions in Spatial Econometrics, Springer, pp. 21–74. DOI: 10.1007/978-3-642-79877-1_2

8. Kelejian, H.H. & Prucha, I.R. (1998). "A Generalized Spatial Two-Stage Least Squares Procedure for Estimating a Spatial Autoregressive Model with Autoregressive Disturbances." Journal of Real Estate Finance and Economics 17(1): 99–121. DOI: 10.1023/A:1007707430416

9. Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, Springer, pp. 175–193. DOI: 10.1007/978-3-642-03647-7_11

10. Anselin, L. & Bera, A.K. (1998). "Spatial Dependence in Linear Regression Models with an Introduction to Spatial Econometrics." In Handbook of Applied Economic Statistics, Marcel Dekker, pp. 237–289. DOI: 10.1201/9781482273847

11. Elhorst, J.P. (2014). Spatial Econometrics: From Cross-Sectional Data to Spatial Panels. Springer. DOI: 10.1007/978-3-642-40340-8

12. Arbia, G. (2014). A Primer for Spatial Econometrics: With Applications in R. Palgrave Macmillan. DOI: 10.1057/9781137317940

⚠️

#### Spatial Error Regression (SEM / Spatial Error Model)

spatial_error_regression
The Spatial Error Model (SEM) treats spatial dependence as a nuisance — a property of the unobserved error process rather than a substantive spillover mechanism. In SEM, the error term $\mathbf{u}$ itself follows a spatial autoregressive process: $\mathbf{u} = \lambda\mathbf{W}\mathbf{u} + \boldsymbol{\varepsilon}$. This specification is appropriate when spatial autocorrelation in OLS residuals is likely caused by omitted variables that are themselves spatially clustered (unmeasured neighbourhood quality, historical district boundaries, shared environmental exposures) rather than by direct causal interaction between neighbouring outcomes. Estimated via maximum likelihood using PySAL `spreg.ML_Error`. Requires the optional `libpysal` and `spreg` packages.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry type)
DEP_VAR | Numeric Field | — | Dependent variable
INDEPENDENTS | Field (multi-select) | — | Explanatory variable fields
WEIGHT_TYPE | Enum | KNN (8) | Queen contiguity / Rook contiguity / K-Nearest Neighbours / Distance Band
KNN | Integer | 8 | Number of neighbours (KNN only)
DISTANCE_BAND | Double | 1000.0 | Distance threshold in map units (distance band only)
OUTPUT | Vector Layer | — | Output layer with predictions, residuals, and audit fields
HTML_REPORT | File (HTML) | — | Output SEM diagnostic report (optional)

##### Output Fields (per feature, appended to source)

`sem_pred` — predicted dependent value ($\hat{y}_i$) · `sem_resid` — residual ($y_i - \hat{y}_i$) · `sem_stdres` — standardised residual (auto-styled with 7-class diverging renderer) · `sem_nbrs` — count of valid neighbours used in the weights graph · `sem_used` — 1 when the feature was used in model fitting; 0 otherwise

##### Model Specification

Spatial Error Model (SEM).
$$\mathbf{y} = \mathbf{X}\boldsymbol{\beta} + \mathbf{u}, \quad \mathbf{u} = \lambda \mathbf{W} \mathbf{u} + \boldsymbol{\varepsilon}, \quad \boldsymbol{\varepsilon} \sim \mathcal{N}(\mathbf{0}, \sigma^2 \mathbf{I}_n)$$
where $\lambda$ is the spatial error parameter, $\mathbf{W}$ is the row-standardised spatial weights matrix, and $\boldsymbol{\varepsilon}$ is a vector of independent and identically distributed normal errors.

##### Reduced Form and Error Structure

Reduced form.
$$\mathbf{y} = \mathbf{X}\boldsymbol{\beta} + (\mathbf{I}_n - \lambda\mathbf{W})^{-1} \boldsymbol{\varepsilon}$$
Error covariance matrix.
$$\text{Var}(\mathbf{u}) = \sigma^2 (\mathbf{I}_n - \lambda\mathbf{W})^{-1} (\mathbf{I}_n - \lambda\mathbf{W}^\top)^{-1}$$
The error at location $i$ is correlated with errors at neighbouring locations $j$ through the spatial multiplier $(\mathbf{I}_n - \lambda\mathbf{W})^{-1}$. Unlike the SAR model, the explanatory variables $\mathbf{X}$ do not propagate through space — only the unobserved disturbances do. This makes SEM a correction model: it corrects the covariance structure used for inference rather than adding a new causal channel.

##### Maximum-Likelihood Estimation

The concentrated log-likelihood function for the spatial error model (Anselin, 1988, Ch. 6):
$$\ln L(\boldsymbol{\beta}, \lambda, \sigma^2) = -\frac{n}{2}\ln(2\pi\sigma^2) + \ln|\mathbf{I}_n - \lambda\mathbf{W}| - \frac{(\mathbf{y} - \mathbf{X}\boldsymbol{\beta})^\top (\mathbf{I}_n - \lambda\mathbf{W})^\top (\mathbf{I}_n - \lambda\mathbf{W}) (\mathbf{y} - \mathbf{X}\boldsymbol{\beta})}{2\sigma^2}$$
For a given $\lambda$, the GLS estimator for $\boldsymbol{\beta}$ is:
$$\hat{\boldsymbol{\beta}}(\lambda) = [\mathbf{X}^\top (\mathbf{I}_n - \lambda\mathbf{W})^\top (\mathbf{I}_n - \lambda\mathbf{W}) \mathbf{X}]^{-1} \mathbf{X}^\top (\mathbf{I}_n - \lambda\mathbf{W})^\top (\mathbf{I}_n - \lambda\mathbf{W}) \mathbf{y}$$
This is the feasible generalised least squares (FGLS) form: transform both $\mathbf{y}$ and $\mathbf{X}$ by $(\mathbf{I}_n - \lambda\mathbf{W})$ — a spatial Cochrane-Orcutt transformation — then apply OLS to the transformed variables.

##### SEM and OLS: When Coefficients Differ

SEM and OLS produce identical coefficient estimates when $\mathbf{X}$ is orthogonal to the spatial error structure — in which case OLS remains unbiased (though inefficient, with incorrect standard errors). They differ when $\lambda$ is non-zero and the eigenvectors of $\mathbf{W}$ overlap with $\mathbf{X}$. In practice, SEM coefficients are often close to OLS coefficients because the spatial transformation operates only on the errors, while OLS already projects onto the column space of $\mathbf{X}$. The primary gain of SEM is in inference quality: standard errors, t-statistics, and p-values that correctly account for spatial error correlation.

##### Interpretation Guide

Lambda ($\lambda$). The spatial error parameter captures the intensity of spatial autocorrelation in the unobserved component. $\lambda > 0$ and significant → positive spatial error dependence: unobserved factors at neighbouring locations are similar (shared context). $\lambda < 0$ → negative error dependence: the unobserved factors alternate in sign across neighbours (checkerboard pattern, possible model mis-specification). $\lambda \approx 0$ → no spatial structure in the residuals after conditioning on $\mathbf{X}$; OLS standard errors are adequate.
SAR vs. SEM — which to choose? This is the central specification decision in spatial econometrics. The decision logic (Anselin, 2005; Florax et al., 2003): (1) Run OLS and inspect residual Moran's I. (2) Compute LM-lag and LM-error from OLS residuals. (3) If LM-lag is significant but LM-error is not: SAR is the correct specification (the spatial process is substantive). (4) If LM-error is significant but LM-lag is not: SEM is correct (the spatial process is a nuisance). (5) If both are significant: consult the robust forms; if robust LM-lag > robust LM-error, choose SAR; otherwise SEM. (6) If neither LM test is significant but residual Moran's I persists: re-examine the weights matrix $\mathbf{W}$ — the spatial structure may operate at a different scale than the one defined by $\mathbf{W}$. Model Comparison tool automates this flow.
Planning interpretation. Prefer SEM when spatial dependence is believed to come from unmeasured context (historical planning districts, environmental gradients, infrastructure quality) that affects the outcome but is not of direct analytical interest. Prefer SAR when the outcome at neighbouring locations is theoretically and causally expected to influence the local outcome (property values, service demand, congestion, innovation diffusion). When in doubt, estimate both and compare AICc.
Residual re-check. After fitting SEM, inspect `sem_stdres` on the map and check the post-SEM Moran's I on residuals in the HTML report. If residuals remain spatially autocorrelated after SEM, the model may need additional explanatory variables, a different $\mathbf{W}$, a higher-order spatial process (SARAR model), or a locally varying specification (GWR).
See also: Spatial Lag Regression (SAR) · OLS Regression · Model Comparison Matrix

##### Key Academic References

1. Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer, Dordrecht. DOI: 10.1007/978-94-015-7799-1

2. LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. CRC Press, Boca Raton. DOI: 10.1201/9781420064254

3. Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. Pion, London. ISBN: 978-0-85086-081-8

4. Anselin, L., Bera, A.K., Florax, R. & Yoon, M.J. (1996). "Simple Diagnostic Tests for Spatial Dependence." Regional Science and Urban Economics 26(1): 77–104. DOI: 10.1016/0166-0462(95)02111-6

5. Florax, R.J.G.M., Folmer, H. & Rey, S.J. (2003). "Specification Searches in Spatial Econometrics: The Relevance of Hendry's Methodology." Regional Science and Urban Economics 33(5): 557–579. DOI: 10.1016/S0166-0462(03)00002-4

6. Anselin, L. & Florax, R.J.G.M. (1995). "Small Sample Properties of Tests for Spatial Dependence in Regression Models." In New Directions in Spatial Econometrics, Springer, pp. 21–74. DOI: 10.1007/978-3-642-79877-1_2

7. Kelejian, H.H. & Prucha, I.R. (2010). "Specification and Estimation of Spatial Autoregressive Models with Autoregressive and Heteroskedastic Disturbances." Journal of Econometrics 157(1): 53–67. DOI: 10.1016/j.jeconom.2009.10.025

8. Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, Springer, pp. 175–193. DOI: 10.1007/978-3-642-03647-7_11

9. Arbia, G. (2014). A Primer for Spatial Econometrics: With Applications in R. Palgrave Macmillan. DOI: 10.1057/9781137317940

10. Elhorst, J.P. (2014). Spatial Econometrics: From Cross-Sectional Data to Spatial Panels. Springer. DOI: 10.1007/978-3-642-40340-8

11. Burridge, P. (1980). "On the Cliff-Ord Test for Spatial Correlation." Journal of the Royal Statistical Society, Series B 42(1): 107–108. DOI: 10.1111/j.2517-6161.1980.tb01108.x

12. Pace, R.K. & LeSage, J.P. (2008). "A Spatial Hausman Test." Economics Letters 101(3): 282–284. DOI: 10.1016/j.econlet.2008.09.002

🔗

#### Spatial Durbin Model (SDM)

spatial_durbin_model
Lags both the dependent variable and every explanatory variable: \(y = \rho Wy + X\beta + WX\theta + \varepsilon\) (LeSage & Pace, 2009). SDM nests Spatial Lag (SAR) as the restricted case \(\theta = 0\), and a restricted form of Spatial Error (SEM) as the case \(\theta = -\rho\beta\) — making it the natural specification when Lagrange Multiplier Diagnostics flags BOTH robust LM-lag and robust LM-error as significant, since neither a pure lag nor a pure error model can then fully resolve the dependence. Estimated by Spatial Two-Stage Least Squares (Kelejian & Prucha, 1998) rather than Maximum Likelihood, trading a small amount of asymptotic efficiency for a much smaller, closed-form correctness surface with no eigenvalue/log-determinant machinery and no optional dependency required.

##### 1. Theoretical Background

Origins. James LeSage and Robert Kelley Pace's 2009 textbook Introduction to Spatial Econometrics popularized the Spatial Durbin Model as the preferred default specification for applied spatial regression, arguing (in work extending Harry Kelejian and Ingmar Prucha's earlier spatial-econometrics program) that SDM's flexibility — nesting both SAR and a restricted SEM — makes it a safer starting point than committing to either pure specification upfront. The name honors James Durbin's 1960s work on including lagged regressors alongside a lagged dependent variable in time-series models; the spatial version applies the identical logic across a cross-sectional neighborhood structure instead of a time lag.

The nesting relationships, precisely. Setting \(\theta = 0\) collapses SDM to the plugin's existing Spatial Autoregression (SAR) tool exactly. The SEM nesting is more subtle: SDM reduces to SEM's reduced form only under the "common factor" restriction \(\theta = -\rho\beta\), a testable constraint (the classical common-factor / Common Factor Hypothesis test, not implemented in this release) rather than an automatic equivalence. In practice this means SDM is best understood as a genuine third, more general specification rather than a mechanical combination of the other two — its own coefficient estimates and fit should be evaluated on their own terms.

Why 2SLS instead of Maximum Likelihood. \(Wy\) is endogenous in this specification: because \(y\) appears on both sides of the equation through the spatial lag, \(Wy\) is correlated with \(\varepsilon\) through the simultaneous feedback loop each observation has with its neighbors, and OLS applied directly would be inconsistent. The standard fix in the literature is either Maximum Likelihood (requiring the log-determinant of \(I - \rho W\), typically via the eigenvalues of \(W\)) or Instrumental Variables / 2SLS (requiring a valid instrument for \(Wy\)). This plugin uses spatial 2SLS with \([WX, W^2X]\) as instruments — the standard, well-established instrument set from Kelejian and Prucha (1998), later refined by Lee (2003) — because it avoids computing eigenvalues of a potentially non-symmetric row-standardized \(W\) (which can have complex eigenvalues in general, complicating a naive log-determinant computation) in favor of ordinary closed-form linear algebra.

Coefficients are not marginal effects. Because \(\rho Wy\) on the right-hand side creates feedback (a change in one location's \(X\) ripples through its neighbors, then back through \(\rho\), and so on), the raw \(\beta\) and \(\theta\) coefficients in SDM do NOT directly measure "the effect of a one-unit change in \(X_j\) on \(y\)" the way an OLS coefficient does. LeSage and Pace's direct/indirect/total impact decomposition — which integrates out this feedback using the matrix \((I - \rho W)^{-1}\) — is the theoretically correct way to recover interpretable marginal effects from an SDM fit, and is a natural, well-scoped extension for a future plugin version. Until then, treat this tool's coefficient table as a specification and significance screen, not a final marginal-effects report.

##### 2. Mathematical Formulation

Let \(X\) include an intercept column, \(p\) the number of explanatory variables, and \(W\) the row-standardized spatial weights matrix.

Model specification:

$$y = \rho Wy + X\beta + WX\theta + \varepsilon \tag{1}$$

Stacked regressor and instrument matrices:

$$Z = [X,\; WX,\; Wy], \qquad H = [X,\; WX,\; W^2X] \tag{2}$$

Spatial 2SLS estimator:

$$\hat{Z} = H(H'H)^{-1}H'Z, \qquad \hat{\delta} = \left(\hat{Z}'Z\right)^{-1}\hat{Z}'y, \qquad \delta = [\beta_0, \beta, \theta, \rho] \tag{3}$$

Residuals and variance (using the ORIGINAL, not projected, Z for consistency):

$$e = y - Z\hat{\delta}, \qquad \hat{\sigma}^2 = \frac{e'e}{n-k}, \qquad \text{Var}(\hat{\delta}) = \hat{\sigma}^2 \left(\hat{Z}'\hat{Z}\right)^{-1} \tag{4}$$
Implementation note. The engine (`core/advanced_stats_engines.py::calculate_spatial_durbin`) forms the projection \(\hat{Z} = H(H'H)^{-1}H'Z\) via the Moore-Penrose pseudoinverse for numerical stability, then solves the 2SLS normal equations directly. Validated on a synthetic 8×8 grid with a known true SDM data-generating process (\(\rho=0.6\), known \(\beta\), known \(\theta\)): the estimator recovered \(\hat{\rho}=0.517\) (true 0.6), coefficient estimates within a small finite-sample-bias margin of their true values, and correct signs throughout, with R² = 0.95 — consistent with expected 2SLS finite-sample behavior at n=64, not evidence of an implementation error.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
DEP_VAR | Numeric Field | — | — | Dependent variable field
INDEPENDENTS | Numeric Fields | — | ≥ 1 field | Independent variable fields
WEIGHT_TYPE | Enum | Queen contiguity | Queen / Rook / KNN / Distance Band | Spatial relationship used to build the weights matrix
KNN | Integer | 8 | ≥ 1 | Number of neighbors (KNN weights only)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (Distance Band weights only)
OUTPUT | Vector Layer | — | — | Output layer with residual/fitted fields
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report

##### 4. Output Description

Field | Type | Description
--- | --- | ---
residual | Double | Observed minus fitted dependent value
fitted | Double | Fitted (predicted) dependent value

The HTML report additionally lists coefficients (Intercept, each X variable, each WX variable, and rho) with standard errors, t-statistics, and p-values.

##### 5. Interpretation Guide

Reading rho and the WX terms together.

Pattern | Interpretation
--- | ---
rho significant and positive | Genuine spatial spillover/feedback in \(y\) beyond what WX alone explains — supports retaining the full SDM specification over a simpler alternative.
rho not significant, WX terms significant | The spatial structure may be adequately captured by lagged X alone — compare against a plain OLS-with-WX (SLX) specification.
Both rho and WX terms weak | Reconsider whether a spatial specification is needed at all — re-check Lagrange Multiplier Diagnostics.

See also: Lagrange Multiplier Diagnostics · Spatial Lag Regression (SAR) · Spatial Error Regression (SEM) · Model Comparison Matrix

##### 6. Literature

LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. Boca Raton: CRC Press. DOI: 10.1201/9781420064254 — The primary reference for the Spatial Durbin Model and its nesting relationships, plus the direct/indirect/total impact decomposition.

Kelejian, H.H. & Prucha, I.R. (1998). "A Generalized Spatial Two-Stage Least Squares Procedure for Estimating a Spatial Autoregressive Model with Autoregressive Disturbances." Journal of Real Estate Finance and Economics 17(1): 99–121. DOI: 10.1023/A:1007707430416 — The 2SLS estimation approach and instrument set this tool implements.

Lee, L.F. (2003). "Best Spatial Two-Stage Least Squares Estimators for a Spatial Autoregressive Model with Autoregressive Disturbances." Econometric Reviews 22(4): 307–335. DOI: 10.1081/ETC-120025891 — Refines the choice of instrument set for spatial 2SLS, motivating the \([WX, W^2X]\) instruments used here.

Anselin, L. (1988). Spatial Econometrics: Methods and Models. Dordrecht: Kluwer. DOI: 10.1007/978-94-015-7799-1 — Establishes the SAR/SEM/SDM model family this tool's specification sits within.

Elhorst, J.P. (2010). "Applied Spatial Econometrics: Raising the Bar." Spatial Economic Analysis 5(1): 9–28. DOI: 10.1080/17421770903541772 — Argues for SDM as a safer general starting specification than committing to SAR or SEM directly, the practical motivation echoed in this card.

Kelejian, H.H. & Prucha, I.R. (1999). "A Generalized Moments Estimator for the Autoregressive Parameter in a Spatial Model." International Economic Review 40(2): 509–533. DOI: 10.1111/1468-2354.00027 — Companion estimation-theory paper in the same spatial-2SLS/GMM research program.

🔬

#### Exploratory Regression

exploratory_regression
A systematic model-screening algorithm that enumerates all possible combinations of candidate explanatory variables (up to a user-specified maximum per model, capped at 8), fits an OLS regression for every combination, and ranks the resulting models by AICc (corrected Akaike Information Criterion). Designed as a hypothesis-generation tool — not an automatic model selector — to help the analyst discover which variable sets are empirically competitive before committing to a single specification for diagnostic testing. Safety-limited to 5,000 combinations to prevent combinatorial explosion (e.g., choosing 3 from 20 fields = 1,350 models; choosing 4 from 30 fields = 31,465, which exceeds the limit). Implemented in pure NumPy using `numpy.linalg.pinv` for numerical stability.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry type)
DEPENDENT_FIELD | Numeric Field | — | Dependent variable (must differ from explanatory fields)
EXPLANATORY_FIELDS | Field (multi-select) | — | Candidate explanatory variables (2+ recommended)
MAX_VARIABLES | Integer | 3 | Maximum predictors per tested model (1–8, capped by both user choice and sample size)
HTML_REPORT | File (HTML) | — | Output ranked-model report (top 20 by AICc)

##### Combinatorial Enumeration

For $M$ candidate explanatory fields and maximum $k$ variables per model, the number of fitted models is:
$$N_{\text{models}} = \sum_{j=1}^{\min(k, M)} \binom{M}{j} = \binom{M}{1} + \binom{M}{2} + \cdots + \binom{M}{\min(k,M)}$$
Example: $M = 10$ fields, $k = 3$ max → $N_{\text{models}} = 10 + 45 + 120 = 175$ models. Each model is fitted independently; runtime scales linearly with $N_{\text{models}}$ and sample size $n$.

##### Model Estimation and Fit Criteria

For each variable subset $\mathcal{S} \subseteq \{1, \ldots, M\}$ with $|\mathcal{S}| = p \le k$:
$$\hat{\boldsymbol{\beta}}_{\mathcal{S}} = (\mathbf{X}_{\mathcal{S}}^\top \mathbf{X}_{\mathcal{S}})^{-1} \mathbf{X}_{\mathcal{S}}^\top \mathbf{y}$$
$$R^2_{\mathcal{S}} = 1 - \frac{\text{RSS}_{\mathcal{S}}}{\text{TSS}}, \quad R^2_{\text{adj},\mathcal{S}} = 1 - (1 - R^2_{\mathcal{S}})\frac{n-1}{n-p-1}$$
$$\ell_{\mathcal{S}} = -\frac{n}{2}\left[\ln(2\pi \cdot \text{RSS}_{\mathcal{S}}/n) + 1\right], \quad \text{AIC} = -2\ell_{\mathcal{S}} + 2(p+2)$$
$$\text{AICc}_{\mathcal{S}} = \text{AIC} + \frac{2(p+2)(p+3)}{n - p - 3} \quad \text{(Hurvich & Tsai, 1989)}$$

##### Information-Theoretic Ranking

Models are ranked by AICc ascending (lower = better fit-parsimony tradeoff). For the set of candidate models $\{\mathcal{M}_1, \ldots, \mathcal{M}_R\}$:
$$\Delta_i = \text{AICc}_i - \min_j \text{AICc}_j$$
Rules of thumb (Burnham & Anderson, 2002): $\Delta_i \le 2$ → substantial support; $4 \le \Delta_i \le 7$ → considerably less support; $\Delta_i > 10$ → essentially no support. The report displays $\Delta_i$ for the top 20 models.

##### Report Structure

The HTML report contains, for each of the top 20 models: (1) Rank, (2) variable names, (3) variable count, (4) $R^2$, (5) adjusted $R^2$, (6) AICc, (7) delta-AICc relative to the best model, and (8) the full coefficient vector (intercept + each variable's estimate). The report also includes a model-quality summary flagging constant/near-constant predictors, low-variance variables, and record completeness.

##### Interpretation Guide

What exploratory regression IS. A hypothesis-generation tool. It answers: "Which variable combinations explain the most variance in $y$ for the fewest parameters, purely empirically?" It rewards parsimony through AICc's penalty term and provides a ranked shortlist for the analyst to evaluate against planning theory.
What exploratory regression IS NOT. (1) It does not test causal validity — the best-AICc model may include a theoretically nonsensical combination of variables. (2) It does not check spatial dependence — every model is plain OLS; residual autocorrelation is not tested. (3) It does not enforce domain constraints — it will happily include collinear variables, mediate-outcome pairs, or variables with the wrong temporal ordering. (4) It is not a substitute for model diagnostics — the top model must be re-estimated in OLS Regression for residual checking and, if spatial dependence is present, in SAR or SEM.
Recommended workflow. (a) Define a candidate set grounded in theory — do not feed "everything available" into the tool. (b) Run Exploratory Regression and inspect the top ~5 models by AICc. (c) Eliminate any model whose coefficient signs contradict theory, even if AICc is excellent. (d) For the surviving candidates, re-estimate each in OLS Regression and inspect residual diagnostics. (e) If residual Moran's I is significant, estimate the corresponding SAR and SEM specifications. (f) Select the final model based on theoretical coherence, diagnostic cleanliness, and AICc — in that order of priority.
Common pitfalls. (a) "The best AICc model must be the right model" — AICc selects the model that best approximates the data-generating process from the candidate set; if the true model is not in the candidate set, AICc cannot find it. (b) "More variables = better fit" — AICc penalises complexity; adding a spurious variable can worsen AICc. (c) "All high-ranked models are interchangeable" — two models with similar AICc may have completely different coefficient interpretations; read the coefficient column in the report.
See also: OLS Regression · Data Readiness Audit

##### Key Academic References

1. Burnham, K.P. & Anderson, D.R. (2002). Model Selection and Multimodel Inference: A Practical Information-Theoretic Approach (2nd ed.). Springer, New York. DOI: 10.1007/b97636

2. Hurvich, C.M. & Tsai, C.L. (1989). "Regression and Time Series Model Selection in Small Samples." Biometrika 76(2): 297–307. DOI: 10.1093/biomet/76.2.297

3. Akaike, H. (1974). "A New Look at the Statistical Model Identification." IEEE Transactions on Automatic Control 19(6): 716–723. DOI: 10.1109/TAC.1974.1100705

4. Florax, R.J.G.M., Folmer, H. & Rey, S.J. (2003). "Specification Searches in Spatial Econometrics: The Relevance of Hendry's Methodology." Regional Science and Urban Economics 33(5): 557–579. DOI: 10.1016/S0166-0462(03)00002-4

5. Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer, Dordrecht. DOI: 10.1007/978-94-015-7799-1

6. LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. CRC Press, Boca Raton. DOI: 10.1201/9781420064254

7. Belsley, D.A., Kuh, E. & Welsch, R.E. (1980). Regression Diagnostics: Identifying Influential Data and Sources of Collinearity. Wiley. DOI: 10.1002/0471725153

8. Hendry, D.F. & Krolzig, H.-M. (2004). "The Properties of Automatic Gets Modelling." Economic Journal 115(502): C32–C61. DOI: 10.1111/j.0013-0133.2005.00979.x

9. Schwarz, G. (1978). "Estimating the Dimension of a Model." Annals of Statistics 6(2): 461–464. DOI: 10.1214/aos/1176344136

10. George, E.I. (2000). "The Variable Selection Problem." Journal of the American Statistical Association 95(452): 1304–1308. DOI: 10.1080/01621459.2000.10474336

11. Tibshirani, R. (1996). "Regression Shrinkage and Selection via the Lasso." Journal of the Royal Statistical Society, Series B 58(1): 267–288. DOI: 10.1111/j.2517-6161.1996.tb02080.x

12. Claeskens, G. & Hjort, N.L. (2008). Model Selection and Model Averaging. Cambridge University Press. DOI: 10.1017/CBO9780511790485

🌍

#### Geographically Weighted Regression (GWR)

gwr_regression
Geographically Weighted Regression is a local spatial modeling technique that fits a separate linear regression at every feature location, weighting neighboring observations by a spatial kernel so that nearby points contribute more to the local estimate than distant points. Unlike OLS — which produces one global coefficient per variable — GWR produces a surface of coefficients, revealing where a relationship is stronger, weaker, positive, or negative. The method was introduced by Brunsdon, Fotheringham & Charlton (1996) to address spatial nonstationarity: the fundamental insight that relationships between variables often change depending on where you measure them. Implemented in pure NumPy — no external packages required. The engine computes the full local coefficient matrix, standard errors, t-statistics, local R², and AICc via the hat-matrix trace.

##### Display Equations

1. GWR Model Specification. For each location $i$ with coordinates $(u_i, v_i)$:
$$y_i = \beta_0(u_i, v_i) + \sum_{k=1}^{p} \beta_k(u_i, v_i)\, x_{ik} + \varepsilon_i, \qquad \varepsilon_i \sim \mathcal{N}(0, \sigma^2)$$
2. Weighted Least Squares Estimator. Coefficients at each location are obtained via:
$$\hat{\boldsymbol{\beta}}(u_i, v_i) = \bigl( \mathbf{X}^{\mathsf{T}} \mathbf{W}(u_i, v_i) \mathbf{X} \bigr)^{-1} \mathbf{X}^{\mathsf{T}} \mathbf{W}(u_i, v_i) \mathbf{y}$$ where $\mathbf{W}(u_i, v_i) = \operatorname{diag}(w_{i1}, w_{i2}, \dots, w_{in})$ is an $n \times n$ diagonal weights matrix.
3. Fixed Gaussian Kernel. Every feature receives a non-zero weight decaying with squared distance:
$$w_{ij} = \exp\!\left(-\frac{d_{ij}^{\,2}}{2b^{2}}\right)$$ where $d_{ij}$ is the Euclidean distance between locations $i$ and $j$, and $b$ is the bandwidth.
4. Fixed Bisquare Kernel. A hard cut-off kernel that sets weights to zero beyond the bandwidth:
$$w_{ij} = \begin{cases} \left(1 - \left(\frac{d_{ij}}{b}\right)^{2}\right)^{2}, & d_{ij} \lt b \\[4pt] 0, & d_{ij} \geq b \end{cases}$$
5. Adaptive Bisquare Kernel. Bandwidth is the number of nearest neighbors $k$ (not a distance); the effective radius $d_k$ is the distance to the $k$-th neighbor:
$$w_{ij} = \begin{cases} \left(1 - \left(\frac{d_{ij}}{d_k}\right)^{2}\right)^{2}, & d_{ij} \lt d_k \\[4pt] 0, & d_{ij} \geq d_k \end{cases}$$ This kernel guarantees a constant number of non-zero-weight neighbors, making it robust to varying feature density.
6. Hat Matrix and Effective Degrees of Freedom. The GWR prediction can be written $\hat{\mathbf{y}} = \mathbf{S} \mathbf{y}$ where $\mathbf{S}$ is the hat (projection) matrix. Its row vectors are:
$$\mathbf{s}_i = \mathbf{x}_i^{\mathsf{T}} \bigl( \mathbf{X}^{\mathsf{T}} \mathbf{W}_i \mathbf{X} \bigr)^{-1} \mathbf{X}^{\mathsf{T}} \mathbf{W}_i$$ Effective degrees of freedom: $\displaystyle \nu = \operatorname{tr}(\mathbf{S}) = \sum_{i=1}^{n} s_{ii}$
7. Corrected Akaike Information Criterion (AICc). The primary criterion for comparing GWR specifications:
$$\text{AICc} = n \ln\!\left(\frac{\text{RSS}}{n}\right) + n \ln(2\pi) + n \left(\frac{n + \operatorname{tr}(\mathbf{S})}{n - 2 - \operatorname{tr}(\mathbf{S})}\right)$$ where $\text{RSS} = \sum_{i=1}^{n} (y_i - \hat{y}_i)^2$ is the residual sum of squares.
8. Local Coefficient of Determination. For each location $i$, the local $R^2$ measures how well the weighted local regression fits the data as seen from location $i$:
$$R_i^2 = 1 - \frac{\sum_{j=1}^{n} w_{ij} (y_j - \hat{y}_j)^2}{\sum_{j=1}^{n} w_{ij} (y_j - \bar{y}_w)^2}, \qquad \bar{y}_w = \frac{\sum_{j=1}^{n} w_{ij} y_j}{\sum_{j=1}^{n} w_{ij}}$$
9. Local Standard Errors and t-Statistics. Under the local weighted least-squares framework, for coefficient $k$ at location $i$:
$$\operatorname{SE}\bigl(\hat{\beta}_{ik}\bigr) = \hat{\sigma}_i \sqrt{ \bigl[ (\mathbf{X}^{\mathsf{T}} \mathbf{W}_i \mathbf{X})^{-1} \bigr]_{kk} }, \qquad t_{ik} = \frac{\hat{\beta}_{ik}}{\operatorname{SE}(\hat{\beta}_{ik})}$$ where $\hat{\sigma}_i^{2} = \sum_j w_{ij}(y_j - \hat{y}_j)^2 \,/\, (\sum_j w_{ij} - p - 1)$ for $p$ predictors.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroids are used for distance computation)
DEP_VAR | Numeric Field | — | Dependent variable (must be continuous; non-constant)
INDEPENDENTS | Field (multi) | — | Independent (explanatory) variable fields. At least one required; prefer 2–5 for interpretable coefficient surfaces
KERNEL_TYPE | Enum | Adaptive Bisquare | Fixed Gaussian: continuous decay, all features contribute. Fixed Bisquare: hard cutoff at bandwidth. Adaptive Bisquare: bandwidth = neighbor count (recommended for uneven density)
BANDWIDTH | Double | 30.0 | For fixed kernels: distance in map units. For adaptive kernels: number of nearest neighbors. Determines the spatial scale of analysis
OUTPUT | Vector Layer | — | Output feature layer with local coefficients, standard errors, t-values, local R², residuals. Graduated on `local_r2`
HTML_REPORT | File (HTML) | — | Diagnostics report: global R², AICc, RSS, effective df, local R² distribution, low-support count, residual spatial autocorrelation, kernel configuration, model quality warnings, next-action recommendation

##### Output Fields

Field | Type | Content
--- | --- | ---
y_observed | Double | Observed dependent-variable value used in the GWR model
y_predicted | Double | GWR-predicted value at this location ($\hat{y}_i$)
residual | Double | Observed minus predicted residual ($y_i - \hat{y}_i$)
local_r2 | Double | Local coefficient of determination ($R_i^2$). Values near 1 = excellent local fit; near 0 = poor fit at that location
gwr_nbrs | Integer | Number of features with non-zero kernel weight for this local regression (local support count)
coef_int | Double | Local intercept coefficient $\hat{\beta}_{i0}$
se_int | Double | Standard error of local intercept
t_int | Double | t-statistic for local intercept
coef_* | Double | Local coefficient for each predictor (field name truncated to first 5 characters)
se_* | Double | Standard error of each local predictor coefficient
t_* | Double | t-statistic for each local predictor coefficient; |t| > 2 indicates approximate stability

##### HTML Report Diagnostics

Executive summary with record count and skipped-record tally · Global R² (fraction of total variance captured by GWR predictions) · AICc (for bandwidth comparison — lower is better) · Residual Sum of Squares and Effective Degrees of Freedom · Residual spatial autocorrelation (Moran's I on GWR residuals with z-score and p-value; significant residual autocorrelation signals omitted spatial structure) · Kernel configuration table (kernel type, bandwidth, local R² distribution min/median/max, local kernel support min/median/max, count of low-support regressions) · Model quality warnings (small n, constant variables, missingness) · CRS unit warning (if geographic CRS detected with fixed-distance kernel) · Recommended analyst action (context-sensitive: revisit bandwidth, inspect residuals, compare kernels, or map coefficient surfaces)

##### Extended Interpretation Guide

1. Map local R² first. `local_r2` is the most important diagnostic surface. Areas with low local R² (e.g., < 0.25) are regions where the model — with its chosen variables and bandwidth — explains little variation. These areas may need additional predictors, a different bandwidth, or may reflect genuinely noisy local processes. Plotting local R² alongside the study area map often reveals whether poor fit is spatially clustered (suggesting a missing regional variable) or scattered (suggesting measurement noise or irreducible local heterogeneity).
2. Coefficient sign switches. GWR's diagnostic power lies in revealing where a predictor's effect changes sign. Use `coef_*` surfaces to identify zones where the relationship is positive vs. negative. A coefficient that switches sign across the study area is evidence of spatial nonstationarity — the relationship itself depends on location. Verify that sign-switching areas are supported by adequate local sample (check `gwr_nbrs`) and that the corresponding t-values are stable.
3. Local t-value maps. Map `t_*` to identify where coefficient estimates are statistically distinguishable from zero. Use |t| > 2 as a rough screening threshold for local stability, but do not treat it as a formal hypothesis test — local t-statistics are not independent across locations. Clusters of significant t-values are more analytically meaningful than isolated significant locations.
4. Bandwidth sensitivity. GWR results are conditional on the chosen bandwidth. A small bandwidth produces highly local, potentially noisy coefficient surfaces; a large bandwidth approaches the global OLS solution. Best practice: run GWR at two or three substantively defensible bandwidths (e.g., the Incremental Autocorrelation peak distance, half that distance, and double it) and compare the stability of coefficient patterns. If the sign-switching geography changes dramatically with bandwidth, the findings are bandwidth-sensitive and should be reported with caution.
5. Residual analysis. Map `residual` to identify systematic over- and under-prediction. Spatially clustered positive residuals indicate areas where the model consistently underpredicts; clustered negative residuals indicate overprediction. The HTML report's residual Moran's I test is a formal check: a significant result (p < 0.05) means the GWR specification did not fully absorb the spatial structure, suggesting that either (a) an important spatially-patterned variable is omitted, (b) the bandwidth is too large to capture local variation, or (c) MGWR is needed because different variables operate at different scales.

##### Algorithm Implementation Notes

Engine. GWR is implemented in `core/stats_engines.py` as `calculate_gwr()`. The function constructs design matrices, computes the full $n \times n$ distance matrix, applies the selected kernel, solves $n$ local weighted least-squares problems via NumPy pseudoinverse, and computes the hat-matrix trace for AICc. Records with missing values in any selected field or without valid geometry are excluded from the model. Features excluded from the model (invalid geometry, missing data) appear in the output layer with NULL diagnostic fields.
Computational scaling. The engine computes an $n \times n$ distance matrix and solves $n$ local regressions, each requiring an $(p+1) \times (p+1)$ matrix pseudoinverse. For $n = 1{,}000$ features and $p = 3$ predictors, the computation is nearly instantaneous. For $n = 10{,}000$, expect tens of seconds. For very large datasets ($n \gt 20{,}000$), consider aggregating to a coarser spatial unit or using a fixed kernel with a well-chosen bandwidth to reduce the effective local sample size.
See also: MGWR · OLS Regression · Model Comparison Matrix

##### Academic References

[GWR-1] Brunsdon, C., Fotheringham, A.S. & Charlton, M.E. (1996). "Geographically Weighted Regression: A Method for Exploring Spatial Nonstationarity." Geographical Analysis 28(4): 281–298. doi:10.1111/j.1538-4632.1996.tb00936.x
[GWR-2] Fotheringham, A.S., Charlton, M.E. & Brunsdon, C. (1998). "Geographically Weighted Regression: A Natural Evolution of the Expansion Method for Spatial Data Analysis." Environment and Planning A 30(11): 1905–1927. doi:10.1068/a301905
[GWR-3] Fotheringham, A.S., Brunsdon, C. & Charlton, M. (2002). Geographically Weighted Regression: The Analysis of Spatially Varying Relationships. Chichester: Wiley. ISBN: 978-0-471-49616-8.
[GWR-4] Paez, A., Uchida, T. & Miyamoto, K. (2002). "A General Framework for Estimation and Inference of Geographically Weighted Regression Models." Environment and Planning A 34(4): 733–754. doi:10.1068/a34148
[GWR-5] Leung, Y., Mei, C.L. & Zhang, W.X. (2000). "Statistical Tests for Spatial Nonstationarity Based on the Geographically Weighted Regression Model." Environment and Planning A 32(1): 9–32. doi:10.1068/a3162
[GWR-6] Wheeler, D. & Tiefelsdorf, M. (2005). "Multicollinearity and Correlation Among Local Regression Coefficients in Geographically Weighted Regression." Journal of Geographical Systems 7(2): 161–187. doi:10.1007/s10109-005-0155-6
[GWR-7] Wheeler, D.C. (2007). "Diagnostic Tools and a Remedial Method for Collinearity in Geographically Weighted Regression." Environment and Planning A 39(10): 2464–2481. doi:10.1068/a38325
[GWR-8] Farber, S. & Paez, A. (2007). "A Systematic Investigation of Cross-Validation in GWR Model Estimation: Empirical Analysis and Monte Carlo Simulations." Journal of Geographical Systems 9(4): 371–396. doi:10.1007/s10109-007-0051-3
[GWR-9] Fotheringham, A.S. & Oshan, T.M. (2016). "Geographically Weighted Regression and Multicollinearity: Dispelling the Myth." Journal of Geographical Systems 18(4): 303–329. doi:10.1007/s10109-016-0239-5
[GWR-10] Gollini, I., Lu, B., Charlton, M., Brunsdon, C. & Harris, P. (2015). "GWmodel: An R Package for Exploring Spatial Heterogeneity Using Geographically Weighted Models." Journal of Statistical Software 63(17): 1–50. doi:10.18637/jss.v063.i17
[GWR-11] Fotheringham, A.S. & Brunsdon, C. (1999). "Local Forms of Spatial Analysis." Geographical Analysis 31(4): 340–358. doi:10.1111/j.1538-4632.1999.tb00989.x
[GWR-12] Cleveland, W.S. & Devlin, S.J. (1988). "Locally Weighted Regression: An Approach to Regression Analysis by Local Fitting." Journal of the American Statistical Association 83(403): 596–610. doi:10.1080/01621459.1988.10478639
🌐

#### Multiscale Geographically Weighted Regression (MGWR)COMPUTE-INTENSIVE

multiscale_geographically_weighted_regression
Multiscale Geographically Weighted Regression extends GWR by allowing each explanatory variable to operate at its own spatial bandwidth. In standard GWR, all variables share one bandwidth. MGWR, introduced by Fotheringham, Yang & Kang (2017), recognizes that planning relationships function at different spatial scales: a parcel-level accessibility measure may be highly local (small bandwidth), while metropolitan labor-market effects may be nearly global (large bandwidth converging to $n$). The algorithm uses a backfitting procedure: it initializes from a standard GWR fit, then iteratively optimizes each variable's bandwidth while holding all others fixed, cycling until convergence. Bandwidth selection at each step minimizes the chosen information criterion (AICc by default). Requires the optional `mgwr` Python package. The engine wraps `mgwr.sel_bw.Sel_BW` for multi-bandwidth selection and `mgwr.gwr.MGWR` for final model fitting.

##### Display Equations

1. MGWR Model Specification. Each predictor $k$ has its own bandwidth $bw_k$, producing spatially varying coefficients at potentially different spatial scales:
$$y_i = \sum_{k=0}^{p} \beta_k(bw_k;\, u_i, v_i)\, x_{ik} + \varepsilon_i, \qquad x_{i0} \equiv 1 \text{ (intercept)}$$ where $\beta_k(bw_k; u_i, v_i)$ is the local coefficient for the $k$-th variable estimated using bandwidth $bw_k$.
2. Backfitting Algorithm. The MGWR estimator is obtained by iteratively solving for each variable's coefficient surface while treating the partial residuals from all other variables as the response. At iteration $t$, for variable $k$:
$$\mathbf{f}_k^{(t)} = \mathbf{y} - \sum_{\substack{j=0 \\ j \neq k}}^{p} \mathbf{S}_j^{(t-1)} \mathbf{y}$$ $$\hat{\boldsymbol{\beta}}_k^{(t)} = \mathbf{S}_k^{(t)} \mathbf{f}_k^{(t)}$$ where $\mathbf{S}_k$ is the GWR hat matrix using bandwidth $bw_k$, and the process cycles through $k = 0, 1, \dots, p$ until $\text{SOC}_f \lt \tau$.
3. Convergence Criterion. The backfitting loop terminates when the score of change falls below tolerance:
$$\text{SOC}_f = \frac{\sqrt{ \sum_{j=1}^{n} \left( \hat{y}_j^{(t)} - \hat{y}_j^{(t-1)} \right)^2 }}{\sum_{j=1}^{n} \left| \hat{y}_j^{(t-1)} \right|}$$ where convergence is declared when $\text{SOC}_f \lt 10^{-5}$ or the maximum iteration count is reached.
4. Variable-Specific Bandwidth Selection. For each variable $k$, the bandwidth $bw_k$ is chosen to minimize the chosen criterion given the current partial residuals from all other variables:
$$bw_k = \underset{bw \in [bw_{\min},\, bw_{\max}]}{\operatorname{argmin}} \; \operatorname{Criterion}\bigl( \mathbf{f}_k, \mathbf{S}_k(bw) \bigr)$$ For AICc (the default): $\operatorname{AICc}(bw) = 2n\ln(\hat{\sigma}) + n\ln(2\pi) + n\frac{n + \operatorname{tr}(\mathbf{S}_k(bw))}{n - 2 - \operatorname{tr}(\mathbf{S}_k(bw))}$
5. Effective Number of Parameters per Variable (ENP_j). MGWR decomposes model complexity by variable, providing scale-specific diagnostics:
$$\text{ENP}_j = \operatorname{tr}(\mathbf{S}_j) - 1 \quad \text{(for non-intercept terms)}$$ A variable with $\text{ENP}_j \approx 0$ has global-scale influence; a variable with $\text{ENP}_j \gg 1$ is highly local.
6. MGWR Prediction and Residuals. After convergence, the fitted values and model residuals are:
$$\hat{\mathbf{y}} = \mathbf{S}_{\text{MGWR}} \, \mathbf{y}, \qquad \mathbf{e} = \mathbf{y} - \hat{\mathbf{y}}$$ Standardized residuals: $\displaystyle e_i^{\text{std}} = \frac{e_i}{\hat{\sigma} \sqrt{1 - h_{ii}}}$, where $h_{ii}$ is the $i$-th diagonal of the combined hat matrix.
7. Model Fit Statistics. The MGWR global diagnostics are computed from the combined fit:
$$R^2 = 1 - \frac{\sum_{i=1}^{n} (y_i - \hat{y}_i)^2}{\sum_{i=1}^{n} (y_i - \bar{y})^2}, \qquad R^2_{\text{adj}} = 1 - \frac{n-1}{n - \operatorname{tr}(\mathbf{S})} (1 - R^2)$$ $$\text{BIC} = n\ln\!\left(\frac{\text{RSS}}{n}\right) + n\ln(2\pi) + \operatorname{tr}(\mathbf{S}) \ln(n)$$
8. Akaike Weights for Bandwidth Uncertainty. Following Li et al. (2020), when multiple bandwidths are competitive, Akaike weights quantify the relative support for each:
$$w_m = \frac{ \exp\!\left(-\frac{1}{2}\Delta_m\right) }{ \sum_{r=1}^{M} \exp\!\left(-\frac{1}{2}\Delta_r\right) }, \qquad \Delta_m = \text{AICc}_m - \min(\text{AICc})$$ where $w_m$ is the weight for candidate bandwidth $m$ and $\Delta_m$ is its AICc difference from the best model.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroids used for distance computation)
DEP_VAR | Numeric Field | — | Dependent variable (must be continuous; non-constant)
INDEPENDENTS | Field (multi) | — | Explanatory variables. At least one required. MGWR is most informative with 3–6 variables spanning potential scales
KERNEL_TYPE | Enum | Adaptive Bisquare | 6 kernel options: Adaptive or Fixed, each combined with Bisquare, Gaussian, or Exponential weighting. Adaptive kernels recommended for variable-density data
CRITERION | Enum | AICc | Bandwidth selection criterion: AICc (recommended for small samples), AIC, BIC (prefers simpler models), CV (cross-validation, most computationally expensive)
MIN_BW | Double | 0 | Minimum bandwidth or neighbor count. 0 = automatic bound (2 + p for adaptive kernels)
MAX_BW | Double | 0 | Maximum bandwidth or neighbor count. 0 = automatic bound (n − 1 for adaptive kernels). Constrain this to test "is the relationship truly global?"
MAX_ITER | Integer | 50 | Maximum backfitting iterations. Typical convergence occurs within 5–20 iterations; increase if convergence is slow
N_CHUNKS | Integer | 1 | Number of chunks for memory-constrained fitting. Higher values reduce peak memory at the cost of runtime
SPHERICAL | Boolean | false | Use great-circle (spherical) distances for longitude/latitude coordinates. Enable only if your CRS is geographic; otherwise use a projected CRS
OUTPUT | Vector Layer | — | Output feature layer with MGWR local diagnostics. Graduated on standardized residuals (`mgwr_std`) with a diverging 7-class scheme
HTML_REPORT | File (HTML) | — | Diagnostics report: bandwidths per variable, ENP_j, model fit statistics, residual spatial autocorrelation, model quality warnings, interpretation and caveats

##### Output Fields

Field | Type | Content
--- | --- | ---
mgwr_pred | Double | MGWR predicted dependent-variable value ($\hat{y}_i$)
mgwr_resid | Double | Observed minus predicted MGWR residual ($y_i - \hat{y}_i$)
mgwr_std | Double | Standardized residual ($e_i / \hat{\sigma}$). Values beyond $\pm 2.5$ are highlighted in the diverging renderer
mgwr_minbw | Double | Minimum selected bandwidth across all model terms (scale summary)
mgwr_maxbw | Double | Maximum selected bandwidth across all model terms (scale summary)
mgwr_used | Integer | 1 = feature used in model fitting; 0 = skipped (missing geometry/data)
mg_b0 | Double | MGWR local intercept coefficient
mg_se0 | Double | Standard error of local intercept
mg_t0 | Double | t-statistic for local intercept
mg_* | Double | Local coefficient for each predictor (base name shortened to 5 chars)
mgs_* | Double | Standard error of each local predictor coefficient
mgt_* | Double | t-statistic for each local predictor coefficient

##### HTML Report Diagnostics

Executive summary — dependent variable, explanatory variables list, kernel type and criterion used, complete record count · Model fit cards — R², adjusted R², AICc in a dashboard grid · Bandwidth selection table — search configuration (criterion, bandwidth type, bounds, iterations, spherical setting, skipped records) · Variable-scale table — for each term (Intercept + predictors): selected bandwidth, effective parameters $\text{ENP}_j$, coefficient distribution (min / median / max), median absolute t-value · Model fit statistics table — AIC, AICc, BIC, $\hat{\sigma}^2$, trace of hat matrix $\operatorname{tr}(\mathbf{S})$ · Residual spatial autocorrelation — Moran's I on MGWR residuals (z-score and p-value). A significant result means the MGWR specification, despite its multiscale flexibility, still fails to absorb all spatial structure · Model quality warnings — small sample warning, constant-value detections, CRS warnings when fixed kernels are used without spherical distance · Interpretation guidance — scale-aware narrative: "map residuals and strongest local coefficients, then compare their geography with planning theory" · Recommended analyst action — context-dependent: compare MGWR against OLS, GWR, and residual diagnostics; review whether variable set is too broad; map coefficient surfaces

##### Extended Interpretation Guide

1. The bandwidth table is the primary analytical product. Each variable's selected bandwidth reveals its characteristic spatial scale. Variables with small bandwidths (e.g., 10–50 neighbors) operate at a highly local scale — their effect varies from neighborhood to neighborhood. Variables with bandwidths approaching $n$ (the total number of features) are effectively global — their effect does not vary spatially and the MGWR coefficient is indistinguishable from an OLS coefficient. MGWR is most informative when bandwidths differ substantially across variables, confirming that the studied phenomenon is genuinely multiscale.
2. Effective parameters (ENP_j) as a diagnostic. $\text{ENP}_j$ quantifies how many effective parameters each variable consumes. A large $\text{ENP}_j$ (relative to other variables) indicates a highly localized relationship that requires many degrees of freedom to represent. The sum of $\text{ENP}_j$ across all variables approximates the total effective degrees of freedom $\operatorname{tr}(\mathbf{S})$. Variables consuming most of the model's degrees of freedom warrant scrutiny — their local variation may be real or may reflect noise amplified by overly small bandwidths.
3. Comparing GWR and MGWR. If all MGWR bandwidths are similar (within a factor of 2–3), the standard GWR model with a single bandwidth is likely adequate — the added complexity of MGWR is not justified. MGWR earns its computational cost when bandwidths differ by an order of magnitude or more, confirming that the variables truly operate at different spatial scales. Run both GWR and MGWR and use the Model Comparison Matrix to evaluate whether the multiscale extension improves fit without overfitting.
4. Coefficient and t-value mapping. After identifying which variables operate at which scales, map the local coefficient surfaces (`mg_*`) and their t-values (`mgt_*`) to visualize spatial variation in each relationship. Focus on variables whose coefficients switch sign across the study area — these are the relationships where MGWR's local perspective is most valuable. Use the standardized residual map (`mgwr_std`) to identify locations where the model systematically mispredicts, and cross-reference with the original GWR local R² map to see whether MGWR improves fit in those areas.
5. Convergence and bandwidth instability. If the backfitting algorithm reaches `MAX_ITER` without convergence, the selected bandwidths may be unstable — the model oscillates between competing scale configurations. This is more common with highly correlated predictors or very small samples. In such cases: (a) reduce the number of predictors, (b) tighten the bandwidth bounds, or (c) accept that the data may not support multiscale inference and fall back to GWR. The HTML report flags cases where convergence was not achieved.

##### Algorithm Implementation Notes

Engine. MGWR is implemented in `algorithms/alg_mgwr.py`. The algorithm delegates bandwidth selection to `mgwr.sel_bw.Sel_BW` with `multi=True` and fitting to `mgwr.gwr.MGWR`. Parameters ($\hat{\boldsymbol{\beta}}$, standard errors, t-values, predicted values, residuals, standardized residuals, bandwidths, $\text{ENP}_j$) are extracted from the fitted MGWR object. Records with missing values are excluded; they appear in the output layer with NULL diagnostics and `mgwr_used=0`. The algorithm validates sample size ($n \gt p + 3$), checks for constant dependent variables, and warns when samples fall below recommended thresholds for multiscale bandwidth search.
Computational scaling. MGWR is the most computationally expensive algorithm in GeoStats Lab. The backfitting loop runs $p+1$ bandwidth optimization problems per iteration, each of which evaluates multiple candidate bandwidths via GWR fits. For $n = 500$ features and $p = 3$ predictors, expect 10–60 seconds. For $n = 2000$, expect 2–10 minutes. For $n \gt 5000$, expect tens of minutes. The `N_CHUNKS` parameter controls a memory-time tradeoff: higher values reduce peak memory usage but increase wall-clock time due to chunking overhead. Consider subsampling or spatial aggregation for very large layers.
See also: GWR · Model Comparison Matrix

##### Academic References

[MGWR-1] Fotheringham, A.S., Yang, W. & Kang, W. (2017). "Multiscale Geographically Weighted Regression (MGWR)." Annals of the American Association of Geographers 107(6): 1247–1265. doi:10.1080/24694452.2017.1352480
[MGWR-2] Yu, H., Fotheringham, A.S., Li, Z., Oshan, T., Kang, W. & Wolf, L.J. (2020). "Inference in Multiscale Geographically Weighted Regression." Geographical Analysis 52(1): 87–106. doi:10.1111/gean.12189
[MGWR-3] Oshan, T.M., Li, Z., Kang, W., Wolf, L.J. & Fotheringham, A.S. (2019). "mgwr: A Python Implementation of Multiscale Geographically Weighted Regression for Investigating Process Spatial Heterogeneity and Scale." ISPRS International Journal of Geo-Information 8(6): 269. doi:10.3390/ijgi8060269
[MGWR-4] Li, Z., Fotheringham, A.S., Oshan, T.M. & Wolf, L.J. (2020). "Measuring Bandwidth Uncertainty in Multiscale Geographically Weighted Regression Using Akaike Weights." Annals of the American Association of Geographers 110(5): 1500–1520. doi:10.1080/24694452.2019.1704680
[MGWR-5] Wolf, L.J., Oshan, T.M. & Fotheringham, A.S. (2018). "Single and Multiscale Models of Process Spatial Heterogeneity." Geographical Analysis 50(3): 223–246. doi:10.1111/gean.12147
[MGWR-6] Fotheringham, A.S., Yue, H. & Li, Z. (2019). "Examining the Influences of Airbnb on Neighborhood Crime Using Multiscale Geographically Weighted Regression." Geographical Analysis 51(3): 280–300. doi:10.1111/gean.12184
[MGWR-7] Hastie, T. & Tibshirani, R. (1986). "Generalized Additive Models." Statistical Science 1(3): 297–310. doi:10.1214/ss/1177013604
[MGWR-8] Loader, C. (1999). Local Regression and Likelihood. New York: Springer. ISBN: 978-0-387-98775-0.
[MGWR-9] Cleveland, W.S. & Devlin, S.J. (1988). "Locally Weighted Regression: An Approach to Regression Analysis by Local Fitting." Journal of the American Statistical Association 83(403): 596–610. doi:10.1080/01621459.1988.10478639
[MGWR-10] Fotheringham, A.S. & Brunsdon, C. (1999). "Local Forms of Spatial Analysis." Geographical Analysis 31(4): 340–358. doi:10.1111/j.1538-4632.1999.tb00989.x
[MGWR-11] Burnham, K.P. & Anderson, D.R. (2002). Model Selection and Multimodel Inference: A Practical Information-Theoretic Approach (2nd ed.). New York: Springer. doi:10.1007/b97636
[MGWR-12] Sugiura, N. (1978). "Further Analysis of the Data by Akaike's Information Criterion and the Finite Corrections." Communications in Statistics – Theory and Methods 7(1): 13–26. doi:10.1080/03610927808827599
🌊

#### Eigenvector Spatial Filtering (ESF) Regression

esf_regression
Griffith's (2003) alternative to the entire Maximum-Likelihood spatial regression family: rather than estimating an autoregressive parameter (rho or lambda) to model spatial dependence directly, ESF adds a small set of data-driven "spatial filter" eigenvectors of the spatial weights matrix as extra OLS predictors, then fits the whole augmented model by ordinary least squares. Selection is a forward stepwise procedure that stops once residual Global Moran's I is no longer significant. The appeal: zero endogeneity, no log-determinant/Jacobian term, no numerical optimization over an autoregressive parameter — once eigenvectors are selected, it is exactly OLS, so every standard OLS diagnostic and standard-error formula applies unmodified.

##### 1. Theoretical Background

Origins. Daniel Griffith introduced eigenvector spatial filtering in his 2003 monograph Spatial Autocorrelation and Spatial Filtering, building on the observation (later formalized by Tiefelsdorf and Griffith, 2007) that the eigenvectors of a doubly-centered, symmetrized spatial weights matrix form an orthogonal basis of achievable spatial patterns, each with a known, exact relationship to the Moran's I coefficient that pattern would produce under the same weights. This gives ESF a genuinely different theoretical foundation from SAR/SEM/SDM: rather than modeling autocorrelation through a single scalar autoregressive parameter multiplying the whole weights matrix, ESF represents spatial structure as a linear combination of a small number of these orthogonal patterns, selected empirically to match what the data actually needs.

The Moran Eigenvector Map (MEM). The candidate eigenvector set is built from \(M_C = (I - \mathbf{11}'/n)\,W\,(I - \mathbf{11}'/n)\), symmetrized. The projection matrix \((I - \mathbf{11}'/n)\) removes the constant (mean) component, so every eigenvector of \(M_C\) is automatically orthogonal to an intercept — the resulting decomposition is often called a Moran Eigenvector Map (MEM) in the spatial-ecology and spatial-econometrics literature, since each eigenvector's eigenvalue is directly proportional to the Moran's I coefficient that eigenvector achieves under \(W\). This plugin restricts the candidate set to POSITIVE eigenvalues only (Griffith's standard practical convention), since negative-eigenvalue eigenvectors represent negative/checkerboard autocorrelation patterns rarely relevant to the smooth, positively-autocorrelated processes typical of planning data.

Forward stepwise selection, not a fixed count. Rather than selecting a pre-specified number of eigenvectors, this tool's engine adds them one at a time — always the remaining candidate most correlated with the CURRENT residual, not a fixed rank ordering by eigenvalue — refitting OLS after each addition and re-checking residual Global Moran's I via this plugin's own existing residual-autocorrelation diagnostic. Selection stops as soon as residual autocorrelation is no longer significant (or a user-set maximum eigenvector count is reached), which tends to select fewer eigenvectors than a naive "take the top-K by eigenvalue" rule when the data's actual autocorrelation is weaker than the full candidate set's theoretical maximum.

Eigenvectors are a control, not an explanation. A selected eigenvector is a mathematical basis function that happens to correlate with whatever unmodeled spatial process is present in the residuals — it is not itself a measured variable with a substantive planning interpretation, the way a lagged X variable or an explicit spatial-lag term is. ESF's proper use is to CONTROL for nuisance spatial autocorrelation so that the X-variable coefficients (and their standard errors, which OLS otherwise understates in the presence of unmodeled spatial dependence) can be trusted, not to explain WHY the spatial pattern exists in the first place.

##### 2. Mathematical Formulation

Let \(W\) be the row-standardized spatial weights matrix and \(\mathbf{1}\) the length-\(n\) vector of ones.

Doubly-centered, symmetrized weights matrix:

$$M_C = \left(I - \frac{\mathbf{1}\mathbf{1}'}{n}\right) W \left(I - \frac{\mathbf{1}\mathbf{1}'}{n}\right), \qquad M_C \leftarrow \frac{M_C + M_C'}{2} \tag{1}$$

Eigendecomposition and candidate restriction:

$$M_C = E \Lambda E', \qquad \text{candidates} = \{E_k : \lambda_k > 0\} \tag{2}$$

Forward stepwise selection (repeated until the stopping rule triggers):

$$k^* = \arg\max_{k \in \text{remaining candidates}} \left| \text{corr}(E_k, \, r^{(t)}) \right|, \qquad r^{(t)} = y - \left[X, E_{\text{selected so far}}\right]\hat{\gamma}^{(t)} \tag{3}$$

Final model (ordinary OLS on the augmented design):

$$y = X\beta + E_{\text{selected}}\gamma + \varepsilon \tag{4}$$
Implementation note. The engine (`core/advanced_stats_engines.py::select_esf_eigenvectors`) uses `numpy.linalg.eigh` (the symmetric-matrix eigensolver, guaranteeing real eigenvalues and orthonormal eigenvectors with no numerical risk of complex results) and reuses this plugin's existing `residual_spatial_autocorrelation_summary` for the stopping check rather than a new formula, minimizing new-code correctness surface. Validated on a synthetic 8×8 grid with a strong true spatial-error process: residual Global Moran's I dropped from 0.285 (p=0.001, significant) to 0.120 (p=0.14, non-significant) after selecting 6 eigenvectors — the intended behavior, confirming both the selection order and the stopping rule work correctly together.

##### 3. Parameters

Parameter | Type | Default | Constraints | Description
--- | --- | --- | --- | ---
INPUT | Vector Layer | — | Any geometry type | Input vector layer
DEP_VAR | Numeric Field | — | — | Dependent variable field
INDEPENDENTS | Numeric Fields | — | ≥ 1 field | Independent variable fields
WEIGHT_TYPE | Enum | Queen contiguity | Queen / Rook / KNN / Distance Band | Spatial relationship used to build the weights matrix
KNN | Integer | 8 | ≥ 1 | Number of neighbors (KNN weights only)
DISTANCE_BAND | Double | 1000.0 | ≥ 0.0001 | Distance threshold in map units (Distance Band weights only)
MAX_EIGENVECTORS | Integer | 10 | 1–50 | Maximum spatial filter eigenvectors to select
OUTPUT | Vector Layer | — | — | Output layer with residual/fitted/spatial_filter fields
HTML_REPORT | File (HTML) | — | Optional path; auto-temp if omitted | Output diagnostic report

##### 4. Output Description

Field | Type | Description
--- | --- | ---
residual | Double | Observed minus fitted dependent value
fitted | Double | Fitted (predicted) dependent value, including the spatial filter contribution
spatial_filter | Double | Contribution of the selected eigenvectors alone to the fitted value - the isolated spatial-structure component, useful to map on its own

##### 5. Interpretation Guide

Reading the ESF report.

Signal | Meaning | Recommended Next Step
--- | --- | ---
Residual Moran's I significant before, non-significant after | Filter succeeded — X coefficients and standard errors are now trustworthy | Report the filtered X coefficients; map spatial_filter to see the isolated spatial structure the filter absorbed.
Zero eigenvectors selected | Residual autocorrelation was already non-significant, or MAX_EIGENVECTORS is too low | If Lagrange Multiplier Diagnostics indicated spatial dependence but ESF selected nothing, raise MAX_EIGENVECTORS before concluding no filtering is needed.
A large fraction of MAX_EIGENVECTORS selected | The filter may be doing too much work relative to sample size | Check residual degrees of freedom and compare adjusted fit against a simpler SAR/SEM/SDM specification via Model Comparison Matrix.

See also: OLS Regression · Lagrange Multiplier Diagnostics · Spatial Durbin Model · Model Comparison Matrix

##### 6. Literature

Griffith, D.A. (2003). Spatial Autocorrelation and Spatial Filtering: Gaining Understanding Through Theory and Scientific Visualization. Berlin: Springer. DOI: 10.1007/978-3-540-24806-4 — The foundational monograph introducing eigenvector spatial filtering.

Tiefelsdorf, M. & Griffith, D.A. (2007). "Semiparametric Filtering of Spatial Autocorrelation: The Eigenvector Approach." Environment and Planning A 39(5): 1193–1221. DOI: 10.1068/a37378 — Formalizes the Moran Eigenvector Map relationship and the eigenvalue-to-Moran's-I correspondence this tool's candidate restriction relies on.

Griffith, D.A. & Peres-Neto, P.R. (2006). "Spatial Modeling in Ecology: The Flexibility of Eigenfunction Spatial Analyses." Ecology 87(10): 2603–2613. DOI: 10.1890/0012-9658(2006)87[2603:SMIETF]2.0.CO;2 — Cross-disciplinary application of the same eigenvector-filtering logic in spatial ecology (where it is often called Moran's Eigenvector Maps, MEM).

Dray, S., Legendre, P. & Peres-Neto, P.R. (2006). "Spatial Modelling: A Comprehensive Framework for Principal Coordinate Analysis of Neighbour Matrices (PCNM)." Ecological Modelling 196(3–4): 483–493. DOI: 10.1016/j.ecolmodel.2006.02.015 — Closely related eigenvector-based spatial modeling framework, useful comparative reading.

Chun, Y. & Griffith, D.A. (2013). Spatial Statistics and Geostatistics: Theory and Applications for Geographic Information Science and Technology. London: SAGE. ISBN: 978-1-4462-1183-1 — Accessible textbook treatment of ESF alongside classical spatial autoregression.

Griffith, D.A. (2000). "A Linear Regression Solution to the Spatial Autocorrelation Problem." Journal of Geographical Systems 2(2): 141–156. DOI: 10.1007/PL00011451 — Earlier statement of the core idea: solving spatial autocorrelation within a linear regression framework rather than through an autoregressive parameter.

🎲

#### Attribute Randomization Sensitivity TestMONTE CARLO

sensitivity_test
Monte Carlo permutation test that assesses whether an observed Global Moran's I could have arisen by chance. The observed $I$ is compared against a reference distribution of $I$ values generated by randomly shuffling attribute values across features (breaking any real spatial structure while preserving the marginal distribution of the variable and the fixed spatial configuration). This technique, rooted in the randomization inference framework of Fisher (1935) and extended to spatial data by Cliff & Ord (1981), constructs the sampling distribution empirically rather than relying on asymptotic normality assumptions. The test produces an HTML report containing the observed $I$, the simulation reference distribution (visualized as an inline SVG histogram), an empirical pseudo-p-value, a sensitivity verdict with color-coded confidence level, and context-sensitive analyst-action recommendations. Pure NumPy implementation — no external packages required.

##### Display Equations

1. Observed Global Moran's I. The test statistic computed from the actual spatial arrangement of attribute values:
$$I_{\text{obs}} = \frac{n}{S_0} \cdot \frac{\sum_{i=1}^{n} \sum_{j=1}^{n} w_{ij} (x_i - \bar{x})(x_j - \bar{x})}{\sum_{i=1}^{n} (x_i - \bar{x})^2}, \qquad S_0 = \sum_{i=1}^{n} \sum_{j=1}^{n} w_{ij}$$ where $w_{ij}$ is the spatial weight between features $i$ and $j$ (binary distance-band weights with $w_{ii} = 0$).
2. Permutation Mechanism. In each simulation $s$, the attribute values are randomly permuted across the fixed spatial locations while preserving the weight matrix $\mathbf{W}$:
$$\mathbf{x}^{(s)} = \pi_s(\mathbf{x}), \qquad I_{\text{sim}}^{(s)} = \frac{n}{S_0} \cdot \frac{\mathbf{z}^{(s)\mathsf{T}} \mathbf{W} \mathbf{z}^{(s)}}{\mathbf{z}^{(s)\mathsf{T}} \mathbf{z}^{(s)}}$$ where $\pi_s$ is a random permutation of the $n$ indices and $\mathbf{z}^{(s)} = \mathbf{x}^{(s)} - \bar{x}^{(s)} \mathbf{1}$.
3. Reference Distribution and Empirical p-value. After $M$ simulations, the empirical two-tailed p-value is computed as:
$$p_{\text{emp}} = \frac{\sum_{s=1}^{M} \mathbb{I}\bigl(|I_{\text{sim}}^{(s)}| \geq |I_{\text{obs}}|\bigr) + 1}{M + 1}$$ The addition of 1 to numerator and denominator (the Davison & Hinkley correction) ensures that $p_{\text{emp}} \gt 0$ and avoids degenerate p-values when $M$ is small. For $M = 999$, the minimum achievable p-value is $1/1000 = 0.001$.
4. Simulation Moments. The simulated mean and standard deviation characterize the reference distribution:
$$\bar{I}_{\text{sim}} = \frac{1}{M} \sum_{s=1}^{M} I_{\text{sim}}^{(s)}, \qquad \sigma_{\text{sim}} = \sqrt{ \frac{1}{M-1} \sum_{s=1}^{M} \bigl( I_{\text{sim}}^{(s)} - \bar{I}_{\text{sim}} \bigr)^2 }$$ Under the null hypothesis of random spatial arrangement, $\bar{I}_{\text{sim}} \approx E(I) = -1/(n-1)$.
5. Percentile-Based Confidence Bounds. The 90% reference interval is:
$$\bigl[ I_{[0.05]}^{\text{sim}}, \; I_{[0.95]}^{\text{sim}} \bigr]$$ where $I_{[q]}^{\text{sim}}$ denotes the $q$-th empirical quantile of the simulated $I$ values. If $I_{\text{obs}}$ lies outside this interval, the spatial pattern is robust at $\alpha = 0.10$ (two-tailed).
6. Sensitivity Verdict Logic. The verdict is determined by the empirical p-value against conventional significance thresholds:
$$\text{Verdict} = \begin{cases} \text{ROBUST} & p_{\text{emp}} \lt 0.05 \\ \text{SENSITIVE} & p_{\text{emp}} \geq 0.05 \end{cases}$$ ROBUST: The observed spatial structure is unlikely under random reassignment of attribute values — the pattern is statistically defensible for this neighborhood definition.
SENSITIVE: The observed pattern falls within the range expected from random attribute arrangements — the apparent clustering is not robust enough to treat as planning evidence without additional verification.
7. Neighborhood Topology Diagnostics. The sensitivity result is qualified by the neighborhood graph structure. Key diagnostics include:
$$n_{\text{isolated}} = \sum_{i=1}^{n} \mathbb{I}\!\left( \sum_{j} w_{ij} = 0 \right), \qquad d_{\text{density}} = \frac{\sum_i \sum_j w_{ij}}{n(n-1)}$$ where $n_{\text{isolated}}$ is the count of features with zero neighbors (requires distance-band increase) and $d_{\text{density}}$ is the graph density (high density risks over-smoothing).

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
INPUT | Vector Layer | — | Input vector layer (any geometry; centroids used for distance computation)
FIELD | Numeric Field | — | Target variable for sensitivity assessment. Must have variation (non-constant); non-numeric or NULL values are skipped with a diagnostic count
DISTANCE_BAND | Double | 1000.0 | Distance threshold in map units for spatial-weight construction. Features within this distance are neighbors. Use Calculate Distance Band (Group 01) or Incremental Autocorrelation (Group 02) to determine a data-driven threshold
SIMULATIONS | Integer | 999 | Number of Monte Carlo permutations (99–9999). Higher values produce more stable p-values: 999 is standard, 9999 recommended for publication-quality inference. Runtime scales linearly with simulation count
HTML_REPORT | File (HTML) | — | Output sensitivity report: verdict box, observed vs. simulated statistics table, inline SVG histogram of reference distribution with observed-I marker, diagnostic tables (numeric quality, neighborhood topology, CRS warning), sensitivity cautions, recommended next action, and methodological caveats

##### HTML Report Diagnostics

Header — attribute name, feature count, distance band, simulation count, skipped-record count · Verdict box (color-coded) — ROBUST (green: $p_{\text{emp}} \lt 0.05$) or SENSITIVE (red: $p_{\text{emp}} \geq 0.05$), with a plain-language description of what the verdict means for planning evidence · Executive summary — narrative describing the test logic and scope of inference · Simulation statistics table — observed $I$, simulated mean $I$, simulated std dev, empirical p-value, 5th and 95th percentiles of the reference distribution · Numeric quality diagnostics — sample size, missing count, constant-value check, value range, mean, std dev · Neighborhood topology diagnostics — neighbor count distribution (min/median/max), isolated feature count, distance-band configuration, neighborhood density label · CRS warning (if geographic CRS detected with distance-band weights) · Inline SVG histogram — reference distribution of simulated $I$ values (20-bin histogram) with a dashed red vertical line marking the observed $I$ position · Recommended analyst action — context-sensitive: if ROBUST → "treat pattern as robust for follow-up local analysis"; if SENSITIVE → "revisit variable choice, study area, or neighborhood definition"; if isolated features present → "increase distance band before relying on result" · Sensitivity cautions — specific warnings about isolation, over-smoothing, and neighborhood definition · Methodological caveats — permutation-test assumptions, scope of inference, and comparison with analytical z-score approaches

##### Extended Interpretation Guide

1. ROBUST vs. SENSITIVE — what the verdict means. A ROBUST verdict means the observed spatial autocorrelation is statistically unusual given the neighborhood definition — the pattern would be unlikely to emerge from randomly relocating attribute values. This does not confirm causation or identify the generating process; it confirms that the spatial structure merits further investigation. A SENSITIVE verdict means the observed pattern could plausibly arise from random attribute assignment — the apparent clustering is not distinguishable from noise at this spatial scale. This does not mean there is no pattern; it means the evidence is insufficient.
2. The role of the distance band. The sensitivity result is conditional on the chosen distance band. A pattern that is ROBUST at one spatial scale may be SENSITIVE at another (this is what the Incremental Autocorrelation tool in Group 02 is designed to explore). Best practice: run the sensitivity test at two or three defensible distance bands (e.g., the Incremental Autocorrelation peak, half that, double that) and compare verdicts. A pattern that is ROBUST across multiple scales is stronger evidence than one that depends on a particular bandwidth.
3. Comparing empirical p-values with analytical z-scores. The analytical z-score for Moran's I (from the Global Moran's I tool in Group 02) assumes asymptotic normality of the test statistic. When the underlying variable is heavily skewed, has extreme outliers, or when $n$ is small, this assumption can be violated. The permutation test makes no distributional assumptions — it constructs the reference distribution empirically from the data itself. If the analytical z-score suggests significance (p < 0.05) but the permutation p-value does not, the analytical result may be inflated by non-normality.
4. Neighborhood topology as a diagnostic. The report flags isolated features (zero neighbors at the chosen distance band) and graph density. Isolated features reduce effective sample size and can inflate or deflate $I$ depending on their attribute values. A "Very dense" neighborhood graph means most features are mutual neighbors, which produces over-smoothed local statistics. The HTML report provides specific action guidance for both conditions.
5. From robustness to evidence. Sensitivity testing is a screening step, not a final answer. A ROBUST result justifies proceeding to local analysis (LISA, Gi*) to identify where the pattern is concentrated. A SENSITIVE result does not invalidate the variable — it suggests that (a) the spatial scale may be wrong, (b) the attribute distribution may be too noisy, or (c) the study area may be too heterogeneous to produce a detectable global pattern. In all cases, the sensitivity report provides structured evidence for the modeling workflow decision, not a binary gate.

##### Algorithm Implementation Notes

Engine. The sensitivity simulation is implemented in `core/stats_engines.py` as `run_sensitivity_simulation()`. The function constructs a dense $n \times n$ binary weight matrix from the distance band, computes the observed Moran's $I$ using a fast quadratic-form computation ($\mathbf{z}^{\mathsf{T}}\mathbf{W}\mathbf{z}$ via NumPy), then performs $M$ random permutations of the attribute vector using `numpy.random.default_rng` with a fixed seed for reproducibility. Each permutation's $I$ is computed using the same fast path. The function returns the observed $I$, the full simulated distribution (as a Python list for histogram construction), and summary statistics. The verdict logic in `core/sensitivity_audit.py` transforms the numerical results into the color-coded verdict, cautions list, and analyst-action recommendations that appear in the HTML report.
Computational scaling. Each simulation requires one permutation and one matrix-vector product. For $n = 500$ features and $M = 999$ simulations, runtime is under one second. For $n = 5000$, runtime is approximately 5–15 seconds depending on weight-matrix density. The weight matrix is stored densely ( $n \times n$ floats), so memory usage is approximately $8n^2$ bytes (e.g., ~200 MB for $n = 5000$). For very large datasets, consider spatial subsampling before running the sensitivity test.
See also: Global Moran's I

##### Academic References

[SENS-1] Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models and Applications. London: Pion. ISBN: 978-0-85086-081-8.
[SENS-2] Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115. doi:10.1111/j.1538-4632.1995.tb00338.x
[SENS-3] Besag, J. & Diggle, P.J. (1977). "Simple Monte Carlo Tests for Spatial Pattern." Journal of the Royal Statistical Society: Series C (Applied Statistics) 26(3): 327–333. doi:10.2307/2346974
[SENS-4] Hope, A.C.A. (1968). "A Simplified Monte Carlo Significance Test Procedure." Journal of the Royal Statistical Society: Series B (Methodological) 30(3): 582–598. doi:10.1111/j.2517-6161.1968.tb00759.x
[SENS-5] Good, P. (2005). Permutation, Parametric, and Bootstrap Tests of Hypotheses (3rd ed.). New York: Springer. doi:10.1007/b138696
[SENS-6] Manly, B.F.J. (2007). Randomization, Bootstrap and Monte Carlo Methods in Biology (3rd ed.). Boca Raton: Chapman & Hall/CRC. ISBN: 978-1-58488-541-2.
[SENS-7] Edgington, E.S. & Onghena, P. (2007). Randomization Tests (4th ed.). Boca Raton: Chapman & Hall/CRC. doi:10.1201/9781420011814
[SENS-8] Anselin, L. & Rey, S.J. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, edited by M.M. Fischer & A. Getis, 175–193. Berlin: Springer. doi:10.1007/978-3-642-03647-7_11
[SENS-9] Efron, B. & Tibshirani, R.J. (1993). An Introduction to the Bootstrap. New York: Chapman & Hall/CRC. doi:10.1007/978-1-4899-4541-9
[SENS-10] Fortin, M.-J. & Dale, M.R.T. (2005). Spatial Analysis: A Guide for Ecologists. Cambridge: Cambridge University Press. ISBN: 978-0-521-00973-7.
[SENS-11] Moran, P.A.P. (1950). "Notes on Continuous Stochastic Phenomena." Biometrika 37(1/2): 17–23. doi:10.1093/biomet/37.1-2.17
[SENS-12] Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. doi:10.1017/CBO9780511802843
🏆

#### Model Comparison Matrix

model_comparison_matrix
Automatically detects and compares multiple PlanX GeoStats model output layers (OLS, GLR, SAR, SEM, GWR, MGWR) side by side, extracting observed values, predicted values, and residuals from each model's standard diagnostic fields. Computes a unified set of comparable metrics — R², RMSE, MAE, prediction bias, record coverage, and residual spatial autocorrelation (Moran's I with p-value) — across all detected models. Ranks models using a weighted composite audit score that balances predictive accuracy, spatial specification quality, and coverage completeness. Generates a structured HTML comparison report designed to make the model-selection logic transparent, auditable, and defensible in planning reports. Pure NumPy implementation — no external packages required.

##### Display Equations

1. Coefficient of Determination (R²). Computed from the extracted observed and predicted values for each model:
$$R^2 = 1 - \frac{\sum_{i=1}^{n} (y_i - \hat{y}_i)^2}{\sum_{i=1}^{n} (y_i - \bar{y})^2}, \qquad \bar{y} = \frac{1}{n} \sum_{i=1}^{n} y_i$$ Models with higher $R^2$ explain more variance, but $R^2$ alone is insufficient for model selection — it rewards complexity without penalizing it.
2. Root Mean Square Error (RMSE). Measures prediction error in the original units of the dependent variable:
$$\text{RMSE} = \sqrt{ \frac{1}{n} \sum_{i=1}^{n} (y_i - \hat{y}_i)^2 }$$ RMSE penalizes large errors quadratically, making it sensitive to outliers. Lower RMSE indicates better predictive accuracy.
3. Mean Absolute Error (MAE). An alternative error metric less sensitive to outliers than RMSE:
$$\text{MAE} = \frac{1}{n} \sum_{i=1}^{n} \bigl| y_i - \hat{y}_i \bigr|$$ MAE is interpretable as the average absolute deviation in the dependent variable's original units. For planning audiences, MAE is often more intuitive than RMSE.
4. Prediction Bias. The mean of residuals — a signed indicator of systematic over- or under-prediction:
$$\text{Bias} = \frac{1}{n} \sum_{i=1}^{n} (y_i - \hat{y}_i)$$ Positive bias indicates systematic under-prediction (observed values tend to exceed predictions); negative bias indicates systematic over-prediction. A well-specified model should have bias close to zero.
5. Model Coverage. The fraction of features in the model output layer with valid predictions and residuals:
$$\text{Coverage} = \frac{n_{\text{valid}}}{N_{\text{total}}}$$ where $n_{\text{valid}}$ is the count of features with non-null observed, predicted, and residual values, and $N_{\text{total}}$ is the total feature count. Low coverage reduces comparability — models fitted on different subsets of features produce metrics on different samples.
6. Residual Spatial Autocorrelation (Moran's I on Residuals). Tests whether model residuals retain spatial structure — a key diagnostic for spatial model adequacy:
$$I_{\text{resid}} = \frac{n}{\sum_i \sum_j w_{ij}} \cdot \frac{\sum_i \sum_j w_{ij} (e_i - \bar{e})(e_j - \bar{e})}{\sum_i (e_i - \bar{e})^2}$$ A significant $I_{\text{resid}}$ (p < 0.05) indicates that the model specification did not fully absorb the spatial pattern in the data. Clean residuals are a hallmark of a well-specified spatial model.
7. Composite Audit Score. Models are ranked by a weighted composite score designed to balance predictive accuracy, spatial specification, and data completeness:
$$\text{Score} = 0.45 \cdot \frac{\text{RMSE}}{\max(\text{RMSE})} \;+\; 0.25 \cdot \frac{\text{MAE}}{\max(\text{MAE})} \;+\; \delta_{\text{resid}} \;+\; 0.15 \cdot (1 - \text{Coverage})$$ where the residual spatial-pattern penalty $\delta_{\text{resid}}$ is: $$\delta_{\text{resid}} = \begin{cases} 0.35 & p_{\text{resid}} \lt 0.05 \text{ (significant residual autocorrelation)} \\ 0.25 & \text{residual diagnostics unavailable} \\ 0.00 & p_{\text{resid}} \geq 0.05 \text{ (spatially clean residuals)} \end{cases}$$ Lower scores are better. A model achieving the best RMSE and MAE with clean residuals receives the lowest (best) score.
8. Recommendation Logic. The report first identifies models with clean residuals ($p_{\text{resid}} \geq 0.05$). If such models exist, the one with the lowest composite score is recommended. If no model has clean residuals, the report notes that every candidate retains residual spatial structure and recommends inspecting residual maps rather than selecting by score alone.

##### Parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
MODEL_LAYERS | Multiple Vector Layers | — | Select two or more PlanX GeoStats model output layers. The tool auto-detects model type from diagnostic field signatures: `residual`/`y_predicted` → GWR; `mgwr_pred`/`mgwr_resid` → MGWR; `sar_pred`/`sar_resid` → SAR; `sem_pred`/`sem_resid` → SEM; `glr_fit`/`glr_resid` → GLR; `residual` alone → OLS
DEP_VAR | Numeric Field | — | Observed dependent variable field name. Must exist in ALL selected layers. The tool extracts observed values from this field in each layer and pairs them with each model's predicted values for metric computation
HTML_REPORT | File (HTML) | — | Output comparison report: executive summary with recommendation, ranked comparison table with per-model metrics and scores, interpretation guide, and recommended analyst actions

##### HTML Report Diagnostics

Header — observed dependent field name, number of compared layers · Executive summary — recommendation narrative: identifies the top-scoring model with clean residuals (if any exist), or flags that all models retain spatial structure · Comparison table — one row per model, sorted by rank (best first): layer name, detected model type, rank, composite score, $n$ (valid records), coverage, $R^2$, RMSE, MAE, bias, residual Moran's $I$, residual p-value, residual status ("Clean" / "Spatial pattern" / "Not available") · Row highlighting — rows with significant residual autocorrelation are highlighted with a warning background · Unusable-layer rows — layers that lack recognized diagnostic fields are listed with a diagnostic message · Reading guide — narrative explaining how to interpret the table, the limitations of fit-only model selection, and the importance of residual diagnostics · Recommended analyst actions — four-item checklist: inspect residual clusters, verify comparable coverage, use OLS/GLR as baselines, document the final choice with theory and diagnostics

##### Extended Interpretation Guide

1. The composite score is a discussion aid, not a decision rule. The score aggregates RMSE, MAE, residual spatial structure, and coverage into a single number for ranking convenience. A model that ranks first by score but relies on variables that are expensive to measure, politically contentious, or theoretically unsupported should not be selected over a close second-ranked model with stronger substantive grounding. The score narrows the field; the analyst makes the call.
2. Residual spatial autocorrelation is the highest-weight diagnostic. A model can achieve excellent predictive fit (high $R^2$, low RMSE) while still leaving strong spatial structure in its residuals. This indicates that the model is capturing the non-spatial variation well but missing a spatially-organized component — possibly an omitted variable, a boundary effect, or a scale mismatch. The comparison report's residual diagnostics help identify which models are spatially well-specified versus which are merely well-fitting.
3. Coverage comparability. If models were run on the same input layer with the same dependent variable and same missing-data handling, coverage should be equal across models. Coverage differences indicate that one model excluded records that another included — for example, a spatial autoregression model might drop isolated features that a GWR model retains. When coverage differs by more than a few percent, the metrics are not strictly comparable (they describe performance on different subsets of features). The report flags this implicitly; analysts should verify comparable coverage before drawing conclusions.
4. The role of model complexity. The composite score does not include a direct complexity penalty beyond what is implicit in the residual spatial-pattern penalty (more complex spatial models should produce cleaner residuals if the added complexity is warranted). For a formal complexity-penalized comparison, use AICc from each model's individual HTML report. The Comparison Matrix complements AICc-based selection with error-metric and diagnostic perspectives that AICc alone does not provide.
5. From comparison to reporting. After selecting a model, document: (a) why this model class (OLS, GWR, MGWR, SAR, SEM) is appropriate for the planning question, (b) which variables were included and why, (c) the spatial weights specification (queen/rook/KNN/distance-band), (d) the key diagnostic results (RMSE, residual Moran's I, and local diagnostics if applicable), and (e) the limitations acknowledged. The comparison report provides all of this evidence in a structured, reproducible format suitable for inclusion in a planning report appendix.

##### Recognized Model Types and Field Signatures

Model | Required Diagnostic Fields | Residual Field | Predicted Field | Used Flag
--- | --- | --- | --- | ---
OLS Regression | `residual` | `residual` | — | —
Generalized Linear Regression | `glr_fit`, `glr_resid` | `glr_resid` | `glr_fit` | `glr_used`
GWR | `y_predicted`, `residual` | `residual` | `y_predicted` | —
MGWR | `mgwr_pred`, `mgwr_resid` | `mgwr_resid` | `mgwr_pred` | `mgwr_used`
Spatial Lag (SAR) | `sar_pred`, `sar_resid` | `sar_resid` | `sar_pred` | `sar_used`
Spatial Error (SEM) | `sem_pred`, `sem_resid` | `sem_resid` | `sem_pred` | `sem_used`

##### Algorithm Implementation Notes

Engine. Model comparison is implemented in `algorithms/alg_model_comparison.py`. The algorithm iterates over each selected layer, detects its model type by checking for the diagnostic field signatures defined in `MODEL_SPECS`, extracts observed ($y_i$), predicted ($\hat{y}_i$), and residual ($e_i$) values for all valid features (skipping features marked as unused via the model-specific flag field), computes fit metrics via `core/analysis_diagnostics.model_fit_summary()`, builds spatial weights for residual autocorrelation testing (Queen for polygons, KNN=8 for points/lines), and computes residual Moran's I via `residual_spatial_autocorrelation_summary()`. Composite scores are assigned by `core/model_audit.assign_model_scores()`, which normalizes RMSE and MAE by their maximum values, adds the residual-pattern penalty, and adds a coverage penalty. The recommendation text is generated by `model_recommendation()`, which prioritizes models with clean residuals when they exist.
Computational scaling. The tool reads each layer's attribute table (I/O-bound), computes fit metrics (trivial), and runs residual spatial autocorrelation diagnostics (requires spatial-weight construction per layer). For layers with thousands of features, weight construction dominates runtime. For $k$ layers each with $n \approx 1000$ features, total runtime is a few seconds. The comparison tool is designed to be run interactively as the final step in a modeling session.
See also: OLS Regression · GWR · MGWR · Spatial Lag Regression (SAR) · Spatial Error Regression (SEM)

##### Academic References

[COMP-1] Burnham, K.P. & Anderson, D.R. (2002). Model Selection and Multimodel Inference: A Practical Information-Theoretic Approach (2nd ed.). New York: Springer. doi:10.1007/b97636
[COMP-2] Akaike, H. (1974). "A New Look at the Statistical Model Identification." IEEE Transactions on Automatic Control 19(6): 716–723. doi:10.1109/TAC.1974.1100705
[COMP-3] Schwarz, G. (1978). "Estimating the Dimension of a Model." Annals of Statistics 6(2): 461–464. doi:10.1214/aos/1176344136
[COMP-4] Hurvich, C.M. & Tsai, C.-L. (1989). "Regression and Time Series Model Selection in Small Samples." Biometrika 76(2): 297–307. doi:10.1093/biomet/76.2.297
[COMP-5] Sugiura, N. (1978). "Further Analysis of the Data by Akaike's Information Criterion and the Finite Corrections." Communications in Statistics – Theory and Methods 7(1): 13–26. doi:10.1080/03610927808827599
[COMP-6] LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. Boca Raton: CRC Press. doi:10.1201/9781420064254
[COMP-7] Anselin, L. (1988). Spatial Econometrics: Methods and Models. Dordrecht: Kluwer. doi:10.1007/978-94-015-7799-1
[COMP-8] Moran, P.A.P. (1950). "Notes on Continuous Stochastic Phenomena." Biometrika 37(1/2): 17–23. doi:10.1093/biomet/37.1-2.17
[COMP-9] Fotheringham, A.S., Brunsdon, C. & Charlton, M. (2002). Geographically Weighted Regression: The Analysis of Spatially Varying Relationships. Chichester: Wiley. ISBN: 978-0-471-49616-8.
[COMP-10] Fotheringham, A.S., Yang, W. & Kang, W. (2017). "Multiscale Geographically Weighted Regression (MGWR)." Annals of the American Association of Geographers 107(6): 1247–1265. doi:10.1080/24694452.2017.1352480
[COMP-11] Anselin, L. & Florax, R.J.G.M. (1995). "Small Sample Properties of Tests for Spatial Dependence in Regression Models." In New Directions in Spatial Econometrics, edited by L. Anselin & R.J.G.M. Florax, 21–74. Berlin: Springer. doi:10.1007/978-3-642-79877-1_2
[COMP-12] Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models and Applications. London: Pion. ISBN: 978-0-85086-081-8.

## Methodological Notes

##### Spatial Weights Matrix

The spatial weights matrix W is the single most consequential modeling choice in spatial statistics. GeoStats Lab supports four weight specifications, each appropriate for different data geometries and analytical questions:

- Queen contiguity — features sharing a boundary or a vertex are neighbors. Appropriate for polygon tessellations (census tracts, administrative units).
- Rook contiguity — features sharing a boundary (but not only a vertex) are neighbors. More restrictive than Queen; appropriate when corner-touching polygons are not meaningfully adjacent.
- K-Nearest Neighbors (KNN) — each feature's K closest features (by centroid distance) are neighbors. Guarantees every feature has exactly K neighbors. Recommended when feature density varies, or for point data.
- Distance Band — all features within a fixed distance threshold are neighbors. Appropriate when the spatial process has a known or theorized range. Use Calculate Distance Band (01) or Incremental Spatial Autocorrelation (02) to determine the threshold.

##### Row-Standardization

All weights are row-standardized (each row of W sums to 1) before use in spatial statistics. Row-standardization makes the spatial lag Wy interpretable as a local average of neighbors' values. The exception is distance-decay kernels in GWR/MGWR, where weights are used in their natural (non-standardized) form to preserve the distance gradient.

##### Coordinate Reference Systems

Distance-based methods (Distance Band, KNN, Ripley's K, GWR/MGWR with fixed kernels) assume Euclidean distances in map units. Always use a projected CRS (e.g., UTM, State Plane) for distance-based analyses. Geographic CRS (latitude/longitude) produce distorted distances that vary with latitude. Contiguity-based weights (Queen, Rook) are unaffected by the CRS. MGWR offers a spherical-distance option for longitude/latitude coordinates.

##### Multiple Testing and Inference

Local statistics (Gi*, LISA, Bivariate LISA) perform a separate hypothesis test at each feature. With N features, this means N simultaneous tests. The default significance threshold of p < 0.05 is not corrected for multiple comparisons. For conservative inference, consider a Bonferroni-adjusted threshold (p < 0.05/N) or use the permutation-based p-values from Bivariate LISA. The plugin reports uncorrected p-values and confidence bins; the analyst decides the appropriate significance level for their use case. See de Castro & Singer (2006) and Anselin (2019) for guidance on multiple-testing correction in LISA.

##### Software Provenance

GeoStats Lab implements its own NumPy-based engines for all core computations (Moran's I, Gi*, LISA, GWR, Ripley's K, SDE, clustering, Gini decomposition). Where optional libraries are used (MGWR via `mgwr`; SAR/SEM via `spreg`), the library name and version are reported in every output. This hybrid approach balances the reliability of hand-audited implementations for common methods with the power of community-vetted packages for advanced methods. All engines are exercised against the bundled QA datasets in automated smoke tests.

## Academic References

The following works inform the methodological choices in PlanX GeoStats Lab. Each algorithm's documentation page cites the specific references most relevant to its implementation.

Anselin, L. (1988). Spatial Econometrics: Methods and Models. Dordrecht: Kluwer Academic Publishers.

Anselin, L. (1995). "Local Indicators of Spatial Association — LISA." Geographical Analysis 27(2): 93–115.

Anselin, L. (2005). Exploring Spatial Data with GeoDa: A Workbook. Center for Spatially Integrated Social Science, UIUC.

Anselin, L. (2019). "A Local Indicator of Multivariate Spatial Association." Geographical Analysis 51(2): 133–150.

Anselin, L., Syabri, I. & Smirnov, O. (2002). "Visualizing Multivariate Spatial Correlation with Dynamically Linked Windows." In New Tools for Spatial Data Analysis, UIUC.

Anselin, L., Syabri, I. & Kho, Y. (2006). "GeoDa: An Introduction to Spatial Data Analysis." Geographical Analysis 38(1): 5–22.

Belsley, D.A., Kuh, E. & Welsch, R.E. (1980). Regression Diagnostics: Identifying Influential Data and Sources of Collinearity. Wiley.

Besag, J. (1977). "Discussion on Dr. Ripley's paper." Journal of the Royal Statistical Society B 39(2): 193–195.

Clark, P.J. & Evans, F.C. (1954). "Distance to Nearest Neighbor as a Measure of Spatial Relationships in Populations." Ecology 35(4): 445–453.

Cliff, A.D. & Ord, J.K. (1981). Spatial Processes: Models & Applications. London: Pion.

de Castro, M.C. & Singer, B.H. (2006). "Controlling the False Discovery Rate: A New Application to Account for Multiple and Dependent Tests in Local Statistics of Spatial Association." Geographical Analysis 38(2): 180–208.

Fotheringham, A.S., Brunsdon, C. & Charlton, M. (2002). Geographically Weighted Regression: The Analysis of Spatially Varying Relationships. Chichester: Wiley.

Fotheringham, A.S., Yang, W. & Kang, W. (2017). "Multiscale Geographically Weighted Regression (MGWR)." Annals of the American Association of Geographers 107(6): 1247–1265.

Getis, A. & Aldstadt, J. (2004). "Constructing the Spatial Weights Matrix Using a Local Statistic." Geographical Analysis 36(2): 90–104.

Getis, A. & Ord, J.K. (1992). "The Analysis of Spatial Association by Use of Distance Statistics." Geographical Analysis 24(3): 189–206.

Hilbe, J.M. (2011). Negative Binomial Regression (2nd ed.). Cambridge University Press.

Kuhn, H.W. (1973). "A Note on Fermat's Problem." Mathematical Programming 4(1): 98–107.

Lee, S.-I. (2001). "Developing a Bivariate Spatial Association Measure: An Integration of Pearson's r and Moran's I." Journal of Geographical Systems 3(4): 369–385.

Lefever, D.W. (1926). "Measuring Geographic Concentration by Means of the Standard Deviational Ellipse." American Journal of Sociology 32(1): 88–94.

LeSage, J. & Pace, R.K. (2009). Introduction to Spatial Econometrics. Boca Raton: CRC Press.

Mardia, K.V. & Jupp, P.E. (2000). Directional Statistics. Chichester: Wiley.

Moran, P.A.P. (1950). "Notes on Continuous Stochastic Phenomena." Biometrika 37(1/2): 17–23.

Nelder, J.A. & Wedderburn, R.W.M. (1972). "Generalized Linear Models." Journal of the Royal Statistical Society A 135(3): 370–384.

Ord, J.K. & Getis, A. (1995). "Local Spatial Autocorrelation Statistics: Distributional Issues and an Application." Geographical Analysis 27(4): 286–306.

Rey, S.J. (2009). "Show Me the Code: Spatial Analysis and Open Source." Journal of Geographical Systems 11(2): 191–207.

Rey, S.J. & Anselin, L. (2010). "PySAL: A Python Library of Spatial Analytical Methods." In Handbook of Applied Spatial Analysis, Springer, 175–193.

Rey, S.J. & Smith, R.J. (2013). "A Spatial Decomposition of the Gini Coefficient." Letters in Spatial and Resource Sciences 6(2): 55–70.

Ripley, B.D. (1976). "The Second-Order Analysis of Stationary Point Processes." Journal of Applied Probability 13(2): 255–266.

Weiszfeld, E. (1937). "Sur le point pour lequel la somme des distances de n points donnés est minimum." Tohoku Mathematical Journal 43: 355–386.

Yuill, R.S. (1971). "The Standard Deviational Ellipse: An Updated Tool for Spatial Description." Geografiska Annaler B 53(1): 28–39.

Centrography, Directional Statistics & Dispersion (Group 04).

Furfey, P.H. (1927). "A Note on Lefever's 'Standard Deviational Ellipse'." American Journal of Sociology 33(1): 94–98. DOI: 10.1086/214336

Sviatlovsky, E.E. & Eells, W.C. (1937). "The Centrographical Method and Regional Analysis." Geographical Review 27(2): 240–254. DOI: 10.2307/210093

Bachi, R. (1963). "Standard Distance Measures and Related Methods for Spatial Analysis." Papers of the Regional Science Association 10(1): 83–132. DOI: 10.1007/BF01934680

Kuhn, H.W. & Kuenne, R.E. (1962). "An Efficient Algorithm for the Numerical Solution of the Generalized Weber Problem in Spatial Economics." Journal of Regional Science 4(2): 21–33. DOI: 10.1111/j.1467-9787.1962.tb00902.x

Fisher, N.I. (1993). Statistical Analysis of Circular Data. Cambridge University Press. DOI: 10.1017/CBO9780511564345

Batschelet, E. (1981). Circular Statistics in Biology. Academic Press. ISBN: 0-12-081050-6.

Gong, J. (2002). "Clarifying the Standard Deviational Ellipse." Geographical Analysis 34(2): 155–167. DOI: 10.1111/j.1538-4632.2002.tb01082.x

Austin, R.F. (1984). "Measuring and Comparing Two-Dimensional Shapes." In Gaile, G.L. & Willmott, C.J. (eds.), Spatial Statistics and Models, D. Reidel, pp. 293–312. DOI: 10.1007/978-94-017-3048-8_16

Kellerman, A. (1981). Centrographic Measures in Geography. CATMOG 32. Geo Abstracts, Norwich. ISBN: 0-86094-081-2.

Burt, J.E. & Barber, G.M. (1996). Elementary Statistics for Geographers (2nd ed.). Guilford Press. ISBN: 1-57230-003-8.

Mitchell, A. (2005). The ESRI Guide to GIS Analysis, Volume 2: Spatial Measurements and Statistics. ESRI Press. ISBN: 978-1-58948-116-9.

Cromley, R.G. & McLafferty, S.L. (2012). GIS and Public Health (2nd ed.). Guilford Press. ISBN: 978-1-60918-750-7.

Wong, D.W.S. & Lee, J. (2005). Statistical Analysis of Geographic Information with ArcView GIS and ArcGIS. Wiley. ISBN: 0-471-46899-8.

Boeing, G. (2019). "Urban Street Network Orientation." Applied Network Science 4(1): 1–19. DOI: 10.1007/s41109-019-0189-1

Vardi, Y. & Zhang, C.-H. (2000). "The Multivariate $L_1$-Median and Associated Data Depth." Proceedings of the National Academy of Sciences 97(4): 1423–1426. DOI: 10.1073/pnas.97.4.1423

Regression and Spatial Econometrics (Group 05a).

Agresti, A. (2015). Foundations of Linear and Generalized Linear Models. Wiley. ISBN: 978-1-118-73030-0.

Akaike, H. (1974). "A New Look at the Statistical Model Identification." IEEE Transactions on Automatic Control 19(6): 716–723. DOI: 10.1109/TAC.1974.1100705

Anselin, L. & Bera, A.K. (1998). "Spatial Dependence in Linear Regression Models with an Introduction to Spatial Econometrics." In Handbook of Applied Economic Statistics, Marcel Dekker, pp. 237–289. DOI: 10.1201/9781482273847

Anselin, L., Bera, A.K., Florax, R. & Yoon, M.J. (1996). "Simple Diagnostic Tests for Spatial Dependence." Regional Science and Urban Economics 26(1): 77–104. DOI: 10.1016/0166-0462(95)02111-6

Anselin, L. & Florax, R.J.G.M. (1995). "Small Sample Properties of Tests for Spatial Dependence in Regression Models." In New Directions in Spatial Econometrics, Springer, pp. 21–74. DOI: 10.1007/978-3-642-79877-1_2

Arbia, G. (2014). A Primer for Spatial Econometrics: With Applications in R. Palgrave Macmillan. DOI: 10.1057/9781137317940

Breusch, T.S. & Pagan, A.R. (1979). "A Simple Test for Heteroscedasticity and Random Coefficient Variation." Econometrica 47(5): 1287–1294. DOI: 10.2307/1911963

Burnham, K.P. & Anderson, D.R. (2002). Model Selection and Multimodel Inference: A Practical Information-Theoretic Approach (2nd ed.). Springer. DOI: 10.1007/b97636

Burridge, P. (1980). "On the Cliff-Ord Test for Spatial Correlation." Journal of the Royal Statistical Society, Series B 42(1): 107–108. DOI: 10.1111/j.2517-6161.1980.tb01108.x

Cameron, A.C. & Trivedi, P.K. (2013). Regression Analysis of Count Data (2nd ed.). Cambridge University Press. DOI: 10.1017/CBO9781139013567

Claeskens, G. & Hjort, N.L. (2008). Model Selection and Model Averaging. Cambridge University Press. DOI: 10.1017/CBO9780511790485

Dobson, A.J. & Barnett, A.G. (2018). An Introduction to Generalized Linear Models (4th ed.). Chapman & Hall/CRC. DOI: 10.1201/9781315182780

Elhorst, J.P. (2014). Spatial Econometrics: From Cross-Sectional Data to Spatial Panels. Springer. DOI: 10.1007/978-3-642-40340-8

Florax, R.J.G.M., Folmer, H. & Rey, S.J. (2003). "Specification Searches in Spatial Econometrics: The Relevance of Hendry's Methodology." Regional Science and Urban Economics 33(5): 557–579. DOI: 10.1016/S0166-0462(03)00002-4

George, E.I. (2000). "The Variable Selection Problem." Journal of the American Statistical Association 95(452): 1304–1308. DOI: 10.1080/01621459.2000.10474336

Hendry, D.F. & Krolzig, H.-M. (2004). "The Properties of Automatic Gets Modelling." Economic Journal 115(502): C32–C61. DOI: 10.1111/j.0013-0133.2005.00979.x

Hosmer, D.W., Lemeshow, S. & Sturdivant, R.X. (2013). Applied Logistic Regression (3rd ed.). Wiley. DOI: 10.1002/9781118548387

Hurvich, C.M. & Tsai, C.L. (1989). "Regression and Time Series Model Selection in Small Samples." Biometrika 76(2): 297–307. DOI: 10.1093/biomet/76.2.297

Jarque, C.M. & Bera, A.K. (1987). "A Test for Normality of Observations and Regression Residuals." International Statistical Review 55(2): 163–172. DOI: 10.2307/1403192

Kelejian, H.H. & Prucha, I.R. (1998). "A Generalized Spatial Two-Stage Least Squares Procedure for Estimating a Spatial Autoregressive Model with Autoregressive Disturbances." Journal of Real Estate Finance and Economics 17(1): 99–121. DOI: 10.1023/A:1007707430416

Kelejian, H.H. & Prucha, I.R. (2010). "Specification and Estimation of Spatial Autoregressive Models with Autoregressive and Heteroskedastic Disturbances." Journal of Econometrics 157(1): 53–67. DOI: 10.1016/j.jeconom.2009.10.025

Koenker, R. (1981). "A Note on Studentizing a Test for Heteroscedasticity." Journal of Econometrics 17(1): 107–112. DOI: 10.1016/0304-4076(81)90062-2

McCullagh, P. & Nelder, J.A. (1989). Generalized Linear Models (2nd ed.). Chapman & Hall, London. DOI: 10.1007/978-1-4899-3242-6

Ord, J.K. (1975). "Estimation Methods for Models of Spatial Interaction." Journal of the American Statistical Association 70(349): 120–126. DOI: 10.1080/01621459.1975.10480272

Pace, R.K. & LeSage, J.P. (2008). "A Spatial Hausman Test." Economics Letters 101(3): 282–284. DOI: 10.1016/j.econlet.2008.09.002

Schwarz, G. (1978). "Estimating the Dimension of a Model." Annals of Statistics 6(2): 461–464. DOI: 10.1214/aos/1176344136

Tibshirani, R. (1996). "Regression Shrinkage and Selection via the Lasso." Journal of the Royal Statistical Society, Series B 58(1): 267–288. DOI: 10.1111/j.2517-6161.1996.tb02080.x

Wedderburn, R.W.M. (1974). "Quasi-Likelihood Functions, Generalized Linear Models, and the Gauss-Newton Method." Biometrika 61(3): 439–447. DOI: 10.1093/biomet/61.3.439

White, H. (1980). "A Heteroskedasticity-Consistent Covariance Matrix Estimator and a Direct Test for Heteroskedasticity." Econometrica 48(4): 817–838. DOI: 10.2307/1912934

Hot Spots, LISA and Spatial Clustering (Group 03).

Anselin, L. (1996). "The Moran Scatterplot as an ESDA Tool to Assess Local Instability in Spatial Association." In M. Fischer, H. Scholten & D. Unwin (eds.), Spatial Analytical Perspectives on GIS, pp. 111–125. London: Taylor & Francis.

Arthur, D. & Vassilvitskii, S. (2007). "k-means++: The Advantages of Careful Seeding." Proceedings of the 18th Annual ACM-SIAM Symposium on Discrete Algorithms (SODA), pp. 1027–1035.

Assuncao, R.M., Neves, M.C., Camara, G. & Freitas, C.D.C. (2006). "Efficient Regionalization Techniques for Socio-Economic Geographical Units Using Minimum Spanning Trees." International Journal of Geographical Information Science 20(7): 797–811. DOI: 10.1080/13658810600665111

Beyer, K., Goldstein, J., Ramakrishnan, R. & Shaft, U. (1999). "When Is 'Nearest Neighbor' Meaningful?" In Database Theory — ICDT '99, LNCS 1540, pp. 217–235. Berlin: Springer. DOI: 10.1007/3-540-49257-7_15

Boots, B. & Tiefelsdorf, M. (2000). "Global and Local Spatial Autocorrelation in Bounded Regular Tessellations." Journal of Geographical Systems 2(4): 319–348. DOI: 10.1007/PL00011461

Calinski, T. & Harabasz, J. (1974). "A Dendrite Method for Cluster Analysis." Communications in Statistics — Theory and Methods 3(1): 1–27. DOI: 10.1080/03610927408827101

Chainey, S. & Ratcliffe, J. (2005). GIS and Crime Mapping. Chichester: Wiley. DOI: 10.1002/9781118685181

Cover, T.M. & Hart, P.E. (1967). "Nearest Neighbor Pattern Classification." IEEE Transactions on Information Theory 13(1): 21–27. DOI: 10.1109/TIT.1967.1053964

Dasarathy, B.V. (ed.) (1991). Nearest Neighbor (NN) Norms: NN Pattern Classification Techniques. Los Alamitos: IEEE Computer Society Press.

Davison, A.C. & Hinkley, D.V. (1997). Bootstrap Methods and Their Application. Cambridge: Cambridge University Press. DOI: 10.1017/CBO9780511802843

Deza, M.M. & Deza, E. (2009). Encyclopedia of Distances. Berlin: Springer. DOI: 10.1007/978-3-642-00234-2

Everitt, B.S., Landau, S., Leese, M. & Stahl, D. (2011). Cluster Analysis (5th ed.). Chichester: Wiley.

Fischer, M.M. & Getis, A. (eds.) (2010). Handbook of Applied Spatial Analysis. Berlin: Springer. DOI: 10.1007/978-3-642-03647-7

Fortin, M.-J. & Dale, M.R.T. (2005). Spatial Analysis: A Guide for Ecologists. Cambridge: Cambridge University Press.

Getis, A. (1991). "Spatial Interaction and Spatial Autocorrelation: A Cross-Product Approach." Environment and Planning A 23(9): 1269–1277. DOI: 10.1068/a231269

Getis, A. & Ord, J.K. (1996). "Local Spatial Statistics: An Overview." In P. Longley & M. Batty (eds.), Spatial Analysis: Modelling in a GIS Environment, pp. 261–277. Cambridge: GeoInformation International.

Griffith, D.A. (2003). Spatial Autocorrelation and Spatial Filtering. Berlin: Springer. DOI: 10.1007/978-3-540-24806-4

Griffith, D.A. & Layne, L.J. (1999). A Casebook for Spatial Statistical Data Analysis: A Compilation of Analyses of Different Thematic Datasets. New York: Oxford University Press.

Griffith, D.A. & Paelinck, J.H.P. (2011). Non-standard Spatial Statistics and Spatial Econometrics. Berlin: Springer. DOI: 10.1007/978-3-642-21543-8

Haining, R.P. (2003). Spatial Data Analysis: Theory and Practice. Cambridge: Cambridge University Press. DOI: 10.1017/CBO9780511754944

Hartigan, J.A. & Wong, M.A. (1979). "Algorithm AS 136: A K-Means Clustering Algorithm." Journal of the Royal Statistical Society C (Applied Statistics) 28(1): 100–108. DOI: 10.2307/2346830

Hastie, T., Tibshirani, R. & Friedman, J. (2009). The Elements of Statistical Learning (2nd ed.). New York: Springer. DOI: 10.1007/978-0-387-84858-7

Hubert, L.J., Golledge, R.G. & Costanzo, C.M. (1981). "Generalized Procedures for Evaluating Spatial Autocorrelation." Geographical Analysis 13(3): 224–233. DOI: 10.1111/j.1538-4632.1981.tb00731.x

Jain, A.K. (2010). "Data Clustering: 50 Years Beyond K-Means." Pattern Recognition Letters 31(8): 651–666. DOI: 10.1016/j.patrec.2009.09.011

Kaufman, L. & Rousseeuw, P.J. (1990). Finding Groups in Data: An Introduction to Cluster Analysis. New York: Wiley. DOI: 10.1002/9780470316801

Lee, S.-I. (2004). "A Generalized Measure of Spatial Association." Journal of the Korean Geographical Society 39(1): 132–149.

Lee, S.-I. (2009). "A Generalized Randomization Approach to Local Measures of Spatial Association." Geographical Analysis 41(3): 221–248. DOI: 10.1111/j.1538-4632.2009.00755.x

Legendre, P. & Legendre, L. (2012). Numerical Ecology (3rd English ed.). Amsterdam: Elsevier.

Lloyd, S.P. (1982). "Least Squares Quantization in PCM." IEEE Transactions on Information Theory 28(2): 129–137. DOI: 10.1109/TIT.1982.1056489

MacQueen, J. (1967). "Some Methods for Classification and Analysis of Multivariate Observations." In Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability, Vol. 1, pp. 281–297. Berkeley: University of California Press.

Maimon, O. & Rokach, L. (eds.) (2005). Data Mining and Knowledge Discovery Handbook. New York: Springer. DOI: 10.1007/b107408

Mantel, N. (1967). "The Detection of Disease Clustering and a Generalized Regression Approach." Cancer Research 27(2): 209–220.

Milligan, G.W. & Cooper, M.C. (1985). "An Examination of Procedures for Determining the Number of Clusters in a Data Set." Psychometrika 50(2): 159–179. DOI: 10.1007/BF02294245

Openshaw, S. (1977). "A Geographical Solution to Scale and Aggregation Problems in Region-Building, Partitioning and Spatial Modelling." Transactions of the Institute of British Geographers 2(4): 459–472. DOI: 10.2307/622300

Openshaw, S. & Taylor, P.J. (1979). "A Million or So Correlation Coefficients: Three Experiments on the Modifiable Areal Unit Problem." In N. Wrigley (ed.), Statistical Applications in the Spatial Sciences, pp. 127–144. London: Pion.

Ord, J.K. & Getis, A. (2001). "Testing for Local Spatial Autocorrelation in the Presence of Global Autocorrelation." Journal of Regional Science 41(3): 411–432. DOI: 10.1111/0022-4146.00224

Rogerson, P.A. (2001). Statistical Methods for Geography. London: SAGE.

Rousseeuw, P.J. (1987). "Silhouettes: A Graphical Aid to the Interpretation and Validation of Cluster Analysis." Journal of Computational and Applied Mathematics 20: 53–65. DOI: 10.1016/0377-0427(87)90125-7

Samet, H. (2006). Foundations of Multidimensional and Metric Data Structures. San Francisco: Morgan Kaufmann.

Shepard, R.N. (1962). "The Analysis of Proximities: Multidimensional Scaling with an Unknown Distance Function." Psychometrika 27(2): 125–140. DOI: 10.1007/BF02289630

Sokal, R.R., Oden, N.L. & Thomson, B.A. (1998). "Local Spatial Autocorrelation in Biological Variables." Biological Journal of the Linnean Society 65(1): 41–62. DOI: 10.1006/bijl.1998.0253

Tiefelsdorf, M. (2000). Modelling Spatial Processes: The Identification and Analysis of Spatial Relationships in Regression Residuals by Means of Moran's I. Berlin: Springer. DOI: 10.1007/BFb0058623

Wartenberg, D. (1985). "Multivariate Spatial Correlation: A Method for Exploratory Geographical Analysis." Geographical Analysis 17(4): 263–283. DOI: 10.1111/j.1538-4632.1985.tb00849.x