Metadata-Version: 2.4
Name: jp-station-neighborhoods
Version: 0.1.0
Summary: Generate 駅勢圏 (station catchment areas) for Japanese railway stations using Voronoi tessellation
Project-URL: Homepage, https://github.com/Leuvtern/jp-station-neighborhoods
Project-URL: Repository, https://github.com/Leuvtern/jp-station-neighborhoods
Project-URL: Issues, https://github.com/Leuvtern/jp-station-neighborhoods/issues
Author-email: William Ma <william.ma.japan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ekiseiken,geospatial,gis,japan,railway,stations,voronoi,駅勢圏
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: folium>=0.15
Requires-Dist: geopandas>=0.14
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: requests>=2.31
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: shapely>=2.0
Description-Content-Type: text/markdown

# jp-station-neighborhoods

Generate [ekiseiken](https://ja.wikipedia.org/wiki/%E9%A7%85%E5%8B%A2%E5%9C%8F) (station catchment areas) for Japanese railway stations using Voronoi tessellation.

## Install

```bash
pip install jp-station-neighborhoods
```

## Quick Start

```python
from jp_station_neighborhoods import (
    download_boundaries,
    run_station_neighborhoods,
    PREFECTURE_BBOX,
)

boundaries = download_boundaries(prefecture="tokyo")
neighborhoods = run_station_neighborhoods(
    boundaries_gdf=boundaries,
    bbox=PREFECTURE_BBOX["tokyo"],
    prefix="tokyo",
)
print(f"{len(neighborhoods)} neighborhoods")
# Output HTML map at ~/.cache/jp-station-neighborhoods/maps/tokyo_station_neighborhoods_map.html
```

## What is Ekiseiken?

Ekiseiken (literally "station influence area") is the walk-shed around a train station -- the area where that station is the closest or most convenient option. In Japanese real estate and urban planning, ekiseiken determines property values, commercial zoning, and transit-oriented development decisions. This package generates these catchment areas computationally using Voronoi tessellation, producing non-overlapping polygons that partition an entire study area among its stations.

## API Reference

### Pipeline

```python
run_station_neighborhoods(boundaries_gdf, bbox, output_dir=..., prefix="tokyo")
```
Full pipeline: download boundaries, fetch stations from OSM, cluster, Voronoi tessellate, save GeoParquet/GeoJSON, and build an interactive Folium map. Returns a `GeoDataFrame` of neighborhood polygons.

### Data Fetching

```python
fetch_stations(bbox, cache_dir) -> GeoDataFrame
```
Fetch railway stations from OpenStreetMap via Overpass API. Returns station points with line counts derived from route relations.

```python
download_boundaries(prefecture=None, scope="prefecture", cache_dir=...) -> GeoDataFrame
```
Download MLIT N03 administrative boundaries. Supports municipality-level (`scope="prefecture"`) or prefecture-level (`scope="country"`) polygons.

### Processing

```python
cluster_stations(stations_gdf) -> GeoDataFrame
```
Group nearby stations into blocks using DBSCAN (400m eps). Classifies each block as `major_hub` (3+ lines), `medium`, or `minor`.

```python
build_neighborhoods(blocks_gdf, study_area) -> GeoDataFrame
```
Generate Voronoi neighborhood polygons from station blocks. Clips to importance-based buffer circles and fills residual gaps.

### Visualization

```python
build_map(neighborhoods_gdf, stations_gdf, output_path) -> None
```
Create an interactive Folium HTML map with color-coded neighborhoods, station markers, and tooltips.

### Reference Data

```python
PREFECTURE_BBOX: dict[str, tuple[float, float, float, float]]
```
WGS84 bounding boxes `(west, south, east, north)` for all 47 Japanese prefectures.

## How It Works

1. **Fetch stations from OSM** -- Queries the Overpass API for railway stations, halts, and subway stops within a bounding box. Enriches each station with a line count from route relation data using spatial matching (200m radius).
2. **DBSCAN clustering (400m)** -- Groups stations within 400m into "station blocks" (e.g. JR Shinjuku + Seibu-Shinjuku + Shinjuku-sanchome become one block). Each block gets an importance class based on the maximum line count of its members.
3. **Voronoi tessellation** -- Computes Voronoi cells for each station block, then intersects each cell with an importance-based buffer circle (major hub: 1500m, medium/minor: 1200m) and the study area boundary.
4. **Clip and fill** -- Intersects all neighborhoods with administrative boundaries. Remaining gaps become "non-station zones," producing a complete partition of the study area with no overlaps.

## Data Sources

- **Stations**: [OpenStreetMap](https://www.openstreetmap.org/) via [Overpass API](https://overpass-api.de/)
- **Administrative boundaries**: [MLIT N03](https://nlftp.mlit.go.jp/ksj/gml/datalist/KsjTmplt-N03-v3_1.html) (Ministry of Land, Infrastructure, Transport and Tourism)

## Configuration

Key constants used in the pipeline:

| Parameter | Value | Description |
|---|---|---|
| `DBSCAN_EPS_M` | 400 | Clustering radius in meters |
| `MAJOR_HUB_LINES` | 3 | Minimum lines for major hub classification |
| Buffer (major hub) | 1500m | Neighborhood radius for major hubs |
| Buffer (medium/minor) | 1200m | Neighborhood radius for other stations |
| Projected CRS | EPSG:6677 | Japan Plane Rectangular IX (for metric ops) |
| Output CRS | EPSG:4326 | WGS84 (all outputs) |

## License

MIT -- see [LICENSE](LICENSE).
