Metadata-Version: 2.4
Name: macroneighborhoods
Version: 0.0.2
Summary: Construct interpretable macro-neighborhoods from spatial data using adjacency-aware regional aggregation.
Author: Chhaya Kulkarni
License-Expression: MIT
Keywords: geospatial,spatial analysis,regionalization,macro-neighborhoods,Voronoi,LISA,Moran's I,hotspot analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: scipy
Requires-Dist: libpysal
Requires-Dist: esda
Requires-Dist: geovoronoi
Requires-Dist: pyarrow
Requires-Dist: matplotlib
Requires-Dist: contextily
Dynamic: license-file

# 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:

```bash
pip install macroneighborhoods
```

For local development from the project repository:

```bash
pip install -e .
```

## Command-line usage

Display the available command-line options:

```bash
macro-nbds --help
```

A general command follows this structure:

```bash
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:

```bash
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.
