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.

v0.9.20 34 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.

Processing Algorithms

Analytical Groups

Regression Variants

Weight Types

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

Setup & Diagnostics

5 tools

→

Data & Neighborhoods

2 tools

→

Urban Pattern Scan

6 tools

→

Hot Spots & Outliers

6 tools

→

Centers & Dispersion

6 tools

→

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.

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_data_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 planning sample (237 polygon features at EPSG:5253 with English-named fields covering heat, green-space, built-form, population, and network 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{planx\_geostats\_izmir\_neighborhoods}\} \quad\text{(1 layer, 237 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 planning 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 (heat scan, green cooling, equity, accessibility) pairing Izmir 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 sample contains realistic spatial structure — the heat-island gradient from coast to inland is strong and spatially autocorrelated, so Global Moran's I on median_land_surface_temp_c should return a 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.

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 green-cooling 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 heat-pattern 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 spatial-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):

Layer integrity — feature count, geometry type, CRS (projected vs. geographic), empty/invalid/multipart geometry counts.
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⁻⁹) are flagged as unanalysable.
Multicollinearity screening — pairwise Pearson correlation via np.corrcoef; pairs with |r| ≥ 0.85 reported, |r| ≥ 0.95 flagged as severe.
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⁻⁹) 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.

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.

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:

Type checking — binary outcomes map to logistic GLM, counts to Poisson GLM, continuous outcomes to OLS/GWR/MGWR, lines to directional tools.
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.
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 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.

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

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.

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.

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), inequality decomposition (Spatial Gini), high/low clustering (General G), scale-dependence (Incremental Autocorrelation), point-process intensity (Ripley's K), and first-order dispersion (Nearest Neighbor).

🌐

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, y_i the observed value at location i, and W = [w_ij] 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 S₀, row/column sums (w_i·, w_·i); second to accumulate S₁ 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.

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)

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 = G_neighbor + G_non-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.

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

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.

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_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.

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.

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.

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.

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), cross-variable spatial association (Bivariate LISA, Lee's L), multivariate similarity groups (K-Means), 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.

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.

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)

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.

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.

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

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.

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.

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 Feature

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?").

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.

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.

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.

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.

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.

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.

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.

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$.

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

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 spatial dependence diagnostics (Spatial Lag, Spatial Error) to 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.

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

📈

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.

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.

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).

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

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

🔬

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.

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.

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)

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.

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

🎲

Attribute Randomization Sensitivity Test

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.

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.

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

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

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.

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)

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