Metadata-Version: 2.4
Name: todindex
Version: 0.1.0
Summary: Transit-oriented development (TOD) assessment of station areas: catchments, 3D/5D built-environment indicators, Bertolini node-place model and a composite TOD index with AHP or PCA weights.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/todindex_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/todindex_sdk
Project-URL: Issues, https://gitlab.com/geophilo1/todindex_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/todindex_sdk/-/blob/main/CHANGELOG.md
Keywords: transit-oriented-development,tod,node-place-model,built-environment,5d,density,land-use-mix,walkability,accessibility,ahp,pca,composite-indicator,urban-planning,gis
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# todindex

[![PyPI version](https://img.shields.io/pypi/v/todindex.svg)](https://pypi.org/project/todindex/)
[![Python versions](https://img.shields.io/pypi/pyversions/todindex.svg)](https://pypi.org/project/todindex/)
[![pipeline](https://gitlab.com/geophilo1/todindex_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/todindex_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Transit-oriented development (TOD) assessment of station areas.**

`todindex` measures how transit-oriented the areas around stations are. It covers:

- **Station catchments**: Euclidean buffers (400 m and 800 m by default), your own
  polygons (for example pedestrian-network service areas from a GIS), or network
  catchments built from a table of network distances.
- **Built-environment indicators** in the "3D/5D" framework (Cervero & Kockelman
  1997; Ewing & Cervero 2010): density, diversity, design, destination
  accessibility and distance to transit.
- The **node-place model** (Bertolini 1999): node and place indices and the five
  classes balanced, unsustained node, unsustained place, stress and dependency.
- A **composite TOD index** with min-max or z-score normalisation and equal,
  user-defined, AHP (pairwise comparisons) or PCA weights.
- **Outputs** as GeoJSON, CSV and Markdown reports, plus a command-line tool.

It needs only the Python standard library and NumPy. Geometry (clipping streets
and land-use polygons to catchments) is exact planar computation in pure Python.

```bash
pip install todindex
```

Requires Python 3.9 or newer.

---

## Quick start (Python)

```python
from todindex import (
    Station, PointFeature, LineFeature, AreaFeature,
    assess, node_place, composite_index, ahp_weights, pairwise_matrix,
)

stations = [
    Station("Centre", 0, 0, {"departures": 600, "lines": 5}),
    Station("Suburb", 3000, 0, {"departures": 180, "lines": 1}),
]
population = [PointFeature(120, 80, weight=350), PointFeature(3100, 50, weight=90)]
jobs = [PointFeature(-60, 40, weight=900), PointFeature(2900, -100, weight=40)]
streets = [LineFeature([(-1000, 0), (0, 0), (4000, 0)]),
           LineFeature([(0, -1000), (0, 0), (0, 1000)], pedestrian=True)]

rows = assess(stations, population=population, jobs=jobs, streets=streets,
              radii=(400, 800))
rows[0]["activity_density_800"]      # residents + jobs per hectare
rows[0]["intersection_density_400"]  # intersections per km2

np_res = node_place(rows, ["departures", "lines"],
                    ["activity_density_800", "intersection_density_800"])
np_res.classes                       # e.g. ['stress', 'dependency']

tod = composite_index(rows, ["activity_density_800", "intersection_density_800"],
                      normalization="minmax", weights="equal")
tod.scores, tod.ranks
```

Longitude/latitude input: pass `lonlat=True` to `assess`; coordinates are projected
with a local equirectangular projection centred on the stations.

A longer synthetic example is in [`examples/quickstart.py`](examples/quickstart.py).

## Quick start (command line)

```bash
# 5D indicators for 400 m and 800 m buffers, from GeoJSON layers in lon/lat
todindex assess stations.geojson --station-id code \
    --population blocks.geojson --population-field pop \
    --jobs firms.geojson --jobs-field employees \
    --landuse parcels.geojson --landuse-field landuse \
    --streets osm_streets.geojson \
    --stops bus_stops.geojson \
    -o indicators.csv --geojson indicators.geojson \
    --catchments buffers.geojson --report report.md

# node-place model from any table (CSV or GeoJSON)
todindex nodeplace indicators.csv --node departures,lines \
    --place activity_density_800,landuse_entropy_800 -o nodeplace.csv

# AHP weights and consistency ratio from a pairwise matrix ("1/3" allowed)
todindex ahp matrix.csv

# composite index with AHP weights; walk distance is a cost indicator
todindex composite indicators.csv \
    --indicators activity_density_800,landuse_entropy_800,mean_distance_to_station_800 \
    --cost mean_distance_to_station_800 --ahp matrix.csv -o tod.csv
```

Use `--crs projected` when the layers are in a metric projected CRS. `todindex ahp`
exits with code 3 when the consistency ratio exceeds 0.10.

## API overview

| Function / class | Purpose |
|---|---|
| `Station`, `PointFeature`, `LineFeature`, `AreaFeature` | Input data model (projected metres or lon/lat) |
| `stations_from_geojson`, `points_from_geojson`, `lines_from_geojson`, `areas_from_geojson` | GeoJSON loaders |
| `Catchment.buffer / .polygon / .network` | Station catchments |
| `assess(stations, population=..., jobs=..., ...)` | 5D indicators per station and catchment |
| `entropy`, `jobs_population_balance`, `street_intersections` | Individual indicator functions |
| `node_place`, `classify_node_place` | Node-place model |
| `normalize`, `ahp_weights`, `pairwise_matrix`, `pca_weights`, `composite_index` | Composite TOD index |
| `stations_geojson`, `catchments_geojson`, `write_geojson`, `write_csv`, `read_table`, `markdown_report` | Outputs |

### Indicators produced by `assess`

Each column is suffixed with the catchment label (`_400`, `_800`, `_net800`, `_poly` ...).

| D | Column | Definition |
|---|---|---|
| Density | `population`, `jobs`, `dwellings` | Sum of point weights inside the catchment |
| | `population_density`, `job_density`, `dwelling_density` | Per hectare of catchment |
| | `activity_density` | (residents + jobs) per hectare |
| Diversity | `landuse_entropy` | `-sum p_j ln p_j / ln K`, K = all land-use categories in the study |
| | `jobs_population_balance` | `1 - abs(J - rP) / (J + rP)`, r = regional jobs per resident by default |
| Design | `street_length_km` | Street length clipped to the catchment |
| | `intersection_count`, `intersection_density` | Nodes of degree >= 3; per km² |
| | `pedestrian_street_share` | Share of street length flagged pedestrian-oriented |
| Destination accessibility | `destinations` | (Weighted) destinations inside |
| | `destination_gravity` | Hansen (1959): `sum w exp(-beta d)` (if `gravity_beta` given) |
| Distance to transit | `transit_stops` | Other stops inside the catchment |
| | `mean_distance_to_station` | Population-weighted mean distance to the station (network distance when available) |
| | `nearest_station_m` | Distance to the nearest other station |

Land use can be polygons (the clipped area is the amount) or points with a weight
such as floor area. Streets must be noded like OpenStreetMap ways (streets crossing
at grade share a vertex). By default the OSM `highway` values `pedestrian`,
`footway`, `living_street`, `path`, `steps` and `residential` count as
pedestrian-oriented; pass your own set with `pedestrian_values`.

## Method and sources

- **Catchments.** 400 m and 800 m are the customary 5- and 10-minute walking
  radii around stations (see e.g. Guerra, Cervero & Tischler 2012 on the half-mile
  circle). They are defaults only. Network catchments use your distance table, so
  the package does no routing itself.
- **3D/5D.** Cervero, R. & Kockelman, K. (1997). Travel demand and the 3Ds:
  density, diversity, and design. *Transportation Research Part D* 2(3), 199-219.
  Ewing, R. & Cervero, R. (2010). Travel and the built environment: a
  meta-analysis. *Journal of the American Planning Association* 76(3), 265-294.
- **Land-use entropy.** The normalised entropy of Cervero & Kockelman (1997) and
  Frank et al. (2004). It is the same index as `landmix.entropy_index` in the
  companion package [`landmix`](https://pypi.org/project/landmix/), which offers
  further mix measures (HHI, Simpson, Hill numbers, dissimilarity).
- **Destination accessibility.** Hansen, W. G. (1959). How accessibility shapes
  land use. *Journal of the American Institute of Planners* 25(2), 73-76.
- **Node-place model.** Bertolini, L. (1999). Spatial development patterns and
  public transport: the application of an analytical model in the Netherlands.
  *Planning Practice & Research* 14(2), 199-210. Node and place indices are
  weighted means of min-max normalised indicators, as in later quantitative
  applications (e.g. Reusser et al. 2008; Vale 2015).
- **AHP.** Saaty, T. L. (1980). *The Analytic Hierarchy Process*. McGraw-Hill.
  Weights from the principal eigenvector (or row geometric means),
  `CI = (lambda_max - n)/(n - 1)`, `CR = CI / RI` with Saaty's random index table
  (`RANDOM_INDEX`, replaceable), and CR <= 0.10 as the acceptance rule.
- **Composite index and PCA weights.** OECD & JRC (2008). *Handbook on
  Constructing Composite Indicators: Methodology and User Guide*. PCA weights:
  components with eigenvalue > 1, squared loadings scaled to unit sum, each
  indicator weighted by its largest scaled squared loading times the component's
  share of retained variance.
- **Context: ITDP TOD Standard.** The Institute for Transportation and Development
  Policy publishes a TOD Standard with its own scoring for development projects.
  `todindex` does not reproduce that scoring; its indicators are research
  measures for comparing station areas.

## Limitations

- Densities assign each point feature wholly to the catchment containing it
  (census blocks or buildings as centroids); there is no areal interpolation of
  population polygons.
- Euclidean buffers overstate walkable areas where the street network is sparse;
  use network catchments (`Catchment.network` with a service-area polygon) when
  this matters.
- Node-place class thresholds (`band=0.2`, `stress=0.7`, `dependency=0.3`) are
  conventions of this package; Bertolini's model is diagrammatic and gives no
  numeric cut-offs. Indices are relative to the stations analysed together.
- PCA weights use unrotated components (the OECD/JRC Handbook rotates with
  varimax); results are the same when a single component is retained.
- The local projection for lon/lat input is meant for city-scale study areas
  (error about 0.3 % at 41° N over a 28 km north-south span).
- Coincident polygon edges are handled, but self-intersecting polygons are not
  supported.

## Development

```bash
pip install -e ".[dev]"
python -m pytest
python -m ruff check . && python -m ruff format --check src tests
python -m mypy src
```

## Academic citation

```bibtex
@software{eminoglu_todindex,
  author  = {Eminoğlu, Yusuf},
  title   = {todindex},
  year    = {2026},
  version = {0.1.0},
  url     = {https://gitlab.com/geophilo1/todindex_sdk}
}
```

## License

MIT License. Copyright (c) 2026 Yusuf Eminoğlu. See [LICENSE](LICENSE).
