Metadata-Version: 2.4
Name: pandarm
Version: 0.0.5
Summary: The Pandas Routing Machine
Project-URL: Home, https://github.com/oturns/pandarm/
Project-URL: Repository, https://github.com/oturns/pandarm
Keywords: routing, network analysis, accessibility, shortest paths, isochrone
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geopandas>=1.1
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: scikit-learn>=1.4
Requires-Dist: tables>=3.10
Provides-Extra: plus
Requires-Dist: osmnx>=2.0; extra == "plus"
Provides-Extra: dev
Requires-Dist: codecov; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: docs
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: sphinx_bootstrap_theme; extra == "docs"
Provides-Extra: all
Requires-Dist: pandarm[dev,docs,plus]; extra == "all"
Dynamic: license-file

# pandarm

[![Continuous Integration](https://github.com/oturns/pandarm/actions/workflows/unittests.yml/badge.svg)](https://github.com/oturns/pandarm/actions/workflows/unittests.yml)
[![codecov](https://codecov.io/gh/oturns/pandarm/graph/badge.svg?)](https://codecov.io/gh/oturns/pandarm)
[![PyPI version](https://badge.fury.io/py/pandarm.svg)](https://badge.fury.io/py/pandarm)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/pandarm.svg)](https://anaconda.org/conda-forge/pandarm)
[![DOI](https://zenodo.org/badge/1091508504.svg)](https://doi.org/10.5281/zenodo.18728076)


A pandas-centric interface to highly performant travel network analysis leveraging [contraction hierarchies](https://en.wikipedia.org/wiki/Contraction_hierarchies) provided by code from the Open Source Routing Machine (OSRM). Hence, the *pandas routing machine*, `pandarm`. This package is a friendly fork of the [pandana](https://github.com/UDST/pandana) library, originally written by Fletcher Foti and UrbanSim Inc. Despite fantastic work by the original authors, maintaining open-source software is a great deal of work and the pandana library is [no longer compatible](https://github.com/UDST/pandana/pull/196) with the current pydata stack (specifically as of numpy version 2.0). This fork reinstates compatibility and brings along a few new modern touches and enhancements. Pull requests are very welcome. 

## Features

Main features of the package include 

- multi-threaded calculation of shortest path routes and distances
- network aggregations (i.e. accessibility metrics)
- network-based isochrones

See more in the [example notebook](examples/example_notebook.ipynb)

### Aggregations

![Access to Restaurants in D.C.](docs/img/dc_restaurants.png)

### Shortest Path

![Shortest Path from UCI School of Social Ecology to Rancho San Joaquin M.S.](docs/img/sse_path.png)

### Isochrones

![Destinations Within 2km of UCI Langson Library](docs/img/langson_iso.png)

## Installation

Install from either PyPI or Conda Forge (though the latter is recommended).

- `pip install pandarm`
- `conda install pandarm --channel conda-forge`

## Development

To install a development version of the package (with proper multithreading) you need an OpenMP compatible C++ compiler. The best way to do this is by installing everything from conda-forge using

```bash
conda env create
conda activate pandarm
pip install -e .
```

This will install all necessary package dependencies, including the platform-appropriate compiler, then build the C++ extension and install the package in editable mode

## Why this fork?

Apart from bringing compatibility with numpy>=2 and the rest of the pydata stack, I have a few feature goals to merge into the codebase that make things easier to do, given today's toolset. When the original `pandana` was written 10 years ago, geopandas was fairly immature, and `osmnx` was not yet written; both of these make life much easier. 

- download OSM networks from `osmnx` instead of `OSMNet` (the former is more performant and easier to work with)
- store network geometries using geopandas
  - allow geopandas-based plotting
  - allow reprojecting node x/y coordinates (particularly important for snapping destinations to the network)
- move isochrone polygons [from geosnap](https://oturns.github.io/geosnap-guide/isochrone_example.html)

## Acknowledgments

The original pandana package from which this fork was derived was created by [Fletcher Foti](https://github.com/fscottfoti), with subsequent contributions from [Matt Davis](https://github.com/jiffyclub), [Federico Fernandez](https://github.com/federicofernandez), [Sam Maurer](https://github.com/smmaurer), and others. The package relies on contraction hierarchy code from [Dennis Luxen](https://github.com/DennisOSRM) and his [OSRM project](https://github.com/DennisOSRM/Project-OSRM).

## Academic literature

A [paper on Pandana](http://onlinepubs.trb.org/onlinepubs/conferences/2012/4thITM/Papers-A/0117-000062.pdf) was presented at the Transportation Research Board Annual Conference in 2012. Please cite this paper when referring to the methods implemented by this library:

* **Foti, F., Waddell, P., & Luxen, D.** (2012). *A Generalized Computational Framework for Accessibility: From the Pedestrian to the Metropolitan Scale*. Transportation Research Board Annual Conference, 1–14. https://onlinepubs.trb.org/onlinepubs/conferences/2012/4thITM/Papers-A/0117-000062.pdf

If you would like to cite this package, you can do so using the [Zenodo DOI](https://doi.org/10.5281/zenodo.18728076). If you do so, we ask that you also please cite the original paper/implementation listed above.

## Related packages

Note the original pandana is still available but can only be used with older versions of numpy. Alternatively, Fletcher has recently released a *pure Python* library, `pandana2`, which calculates network-based aggregations, albeit at a bit of a performance cost, though it (currently at least) lacks routing and shortest-path functionality.

- [OSMnet](https://github.com/udst/osmnet)
- [UrbanAccess](https://github.com/udst/urbanaccess)
- [pandana](https://github.com/udst/pandana)
- [pandana2](https://github.com/mapcraftlabs/pandana2)
