macroneighborhoods

macroneighborhoods is a research-oriented Python package for constructing larger spatial regions, called macro-neighborhoods, from georeferenced observations.

The package generates local micro-neighborhoods, determines spatial adjacency, and merges neighboring regions based on feature similarity. It can also compute spatial autocorrelation outputs using Global Moran's I and Local Indicators of Spatial Association (LISA).

The package is intended to support reproducible research workflows in geospatial data mining, environmental informatics, remote sensing, climate analysis, urban analytics, and related fields.

Why use macro-neighborhoods?

Spatial datasets often contain many point observations, grid cells, or small local regions. Although these fine-scale units preserve detail, they can be difficult to analyze and interpret collectively.

macroneighborhoods helps organize these units into larger, spatially connected regions that reflect both geographic adjacency and similarity in selected attributes.

Main capabilities

• Generate Voronoi-based micro-neighborhoods from spatial observations
• Determine spatial adjacency among local regions
• Compare neighboring regions using selected feature variables
• Merge adjacent and similar micro-neighborhoods into macro-neighborhoods
• Export reusable GeoJSON files
• Generate PNG maps for visual inspection
• Optionally compute Global Moran's I
• Optionally generate LISA cluster outputs for a selected feature

Installation

Install the package from PyPI:

pip install macroneighborhoods

For local development from the project repository:

pip install -e .

Command-line usage

Display the available command-line options:

macro-nbds --help

A general command follows this structure:

macro-nbds \
  --input path/to/input_data.parquet \
  --output path/to/output_macro_neighborhoods.geojson \
  --lisa-feature feature_name

Replace the input path, output path, and feature name with values appropriate for your dataset.

Repository demonstration

When working from the project repository, the included satellite snowmelt demonstration can be run using:

macro-nbds \
  --input demo_data/SATELLITE_with_smlt.parquet \
  --output outputs/live_satellite_snowmelt_demo.geojson \
  --lisa-feature smlt

Outputs

Depending on the selected options, the package can produce:

• a micro-neighborhood map and GeoJSON file;
• a macro-neighborhood map and GeoJSON file;
• a LISA cluster map and GeoJSON file when a feature is specified;
• spatial autocorrelation statistics for the selected feature.

PNG outputs support quick visual inspection. GeoJSON outputs can be opened in QGIS, ArcGIS, GeoPandas, or other geospatial analysis environments.

Research and reproducibility

The resulting macro-neighborhoods depend on the input data, coordinate reference system, selected feature variables, preprocessing decisions, and similarity settings.

Researchers should document these choices when reporting results so that the analysis can be interpreted and reproduced.

Citation

When using this package in academic research, please cite:

• the macroneighborhoods package;
• the specific software version used;
• the associated publication or archived software record, when available.

Development status

macroneighborhoods is early-stage research software and is under active development.

Version 0.0.2 improves the package documentation and PyPI metadata. Future development may include additional tests, expanded examples, threshold sensitivity summaries, and broader documentation.