aperta 0.1.0a0__tar.gz

aperta-0.1.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Miotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aperta-0.1.0a0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: aperta
+Version: 0.1.0a0
+Summary: Python toolkit for cross-modal accessibility analysis on transport networks.
+Author-email: Marco Miotti <marco@miotti.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mmiotti/aperta
+Project-URL: Documentation, https://aperta.readthedocs.io/
+Project-URL: Repository, https://github.com/mmiotti/aperta
+Project-URL: Issues, https://github.com/mmiotti/aperta/issues
+Project-URL: Changelog, https://github.com/mmiotti/aperta/blob/main/CHANGELOG.md
+Keywords: accessibility,transport,mobility,urban,routing,networks,gis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: geopandas>=1.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: numba>=0.60
+Requires-Dist: matplotlib>=3.8
+Provides-Extra: osm
+Requires-Dist: osmnx>=2.0; extra == "osm"
+Provides-Extra: topo
+Requires-Dist: rasterio>=1.3; extra == "topo"
+Requires-Dist: requests>=2.28; extra == "topo"
+Provides-Extra: h3
+Requires-Dist: h3>=4.0; extra == "h3"
+Provides-Extra: examples
+Requires-Dist: aperta[osm]; extra == "examples"
+Requires-Dist: aperta[h3]; extra == "examples"
+Requires-Dist: jupytext>=1.16; extra == "examples"
+Requires-Dist: contextily>=1.4; extra == "examples"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0; extra == "docs"
+Requires-Dist: furo>=2024.0; extra == "docs"
+Requires-Dist: myst-parser>=4.0; extra == "docs"
+Dynamic: license-file
+
+# aperta
+
+[![tests](https://github.com/mmiotti/aperta/actions/workflows/test.yml/badge.svg)](https://github.com/mmiotti/aperta/actions/workflows/test.yml)
+[![docs](https://readthedocs.org/projects/aperta/badge/?version=latest)](https://aperta.readthedocs.io/en/latest/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![license](https://img.shields.io/github/license/mmiotti/aperta.svg)](LICENSE)
+
+A Python toolkit for **cross-modal accessibility analysis on transport networks** — routing, distance/time computation, utility-based travel costs, and gravity- and logsum-based accessibility metrics on `networkx` graphs (routed via `scipy.sparse.csgraph`).
+
+![Three families of aperta capabilities, illustrated on the Bern region: network preparation (estimated traffic volumes and calibrated edge speeds), path feature collection (bike-comfort scores along realized routes and aggregated per origin cell), and accessibility analysis (time-based access to hiking opportunities and cross-modal utility-based access to groceries).](docs/assets/hero.jpg)
+
+The name is Latin/Italian for *open* — the condition that accessibility, at root, measures.
+
+## Status
+
+**Pre-1.0, alpha.** Published alongside a toolkit paper (in submission). APIs may change without notice until v1.0.
+
+## Install
+
+```bash
+pip install aperta              # algorithms only
+pip install 'aperta[osm]'       # + OSM ingestion (osmnx)
+pip install 'aperta[examples]'  # + everything needed to run the example notebooks
+```
+
+Requires Python ≥ 3.11.
+
+The `osm_helpers` and `topography` modules import their backing libraries
+(`osmnx`, `rasterio`, `requests`) lazily — install the matching `[osm]` /
+`[topo]` extra if you use them, otherwise an `ImportError` surfaces at first use.
+
+For development:
+
+```bash
+git clone git@github.com:mmiotti/aperta.git
+cd aperta
+pip install -e ".[osm,topo,h3]"
+python -m unittest discover -s tests -t .
+```
+
+> If you plan to edit the example notebooks under `examples/`, run the
+> [jupytext + nbstripout setup](CONTRIBUTING.md#editing-notebooks) once
+> after cloning. Not needed if you're only using the library or
+> modifying Python source.
+
+## Workflow
+
+Aperta is organized around a six-phase workflow. Phases 4 and 5's calibration sub-step are optional; the rest is the minimum end-to-end pipeline.
+
+1. **Load and prepare data** — networks (one per mode), land use, topography, optional ground-truth data (traffic counters, travel-survey times).
+2. **Map data to units** — aggregate source data into the `cells → zones` hierarchy; snap geo units to network nodes.
+3. **Build sparse OD pairs** — the tiered OD structure (three distance tiers) with per-cell origins at near range and zone-aggregated destinations at far range, keeping per-origin compute bounded independently of network extent.
+4. **(Optional) Estimate traffic flows** — sampled betweenness centrality; optionally calibrate against observed counter data.
+5. **Estimate travel costs** — shortest paths on the routing graph plus per-cell trip overheads. Optionally: utility-based generalized costs and edge-weight calibration against observed travel times.
+6. **Calculate accessibilities** — cumulative-opportunity, gravity, nearest-k, logsum (and cross-modal aggregation across per-mode results).
+
+See the [API reference](https://aperta.readthedocs.io/en/latest/api/) for which module covers each phase and for the specific functions.
+
+Runnable examples, in increasing depth:
+
+- [examples/minimal/accessibility.ipynb](examples/minimal/accessibility.ipynb) — what aperta does in ~50 lines using only OpenStreetMap. Cambridge MA, ~10 s.
+- [examples/walkthrough/accessibility.ipynb](examples/walkthrough/accessibility.ipynb) — guided tour of every primitive; walking + cycling, cross-modal logsum, path-first per-edge feature aggregation. Central Paris, ~1 min end-to-end.
+- [examples/extended/](examples/extended/) — production-scale Bern + 40 km: prep pipeline, calibration against observed travel times, traffic-flow estimation, accessibility analysis. ~30 min.
+
+The toy-world end-to-end test in [tests/test_workflow.py](tests/test_workflow.py) doubles as the smallest possible walk-through (~150 lines, runs in a second).
+
+## Quick example
+
+The three-line core of an accessibility analysis: build the tiered OD pairs, route shortest paths, count opportunities within a travel-time budget.
+
+```python
+from aperta import accessibility, od_pairs, routing
+
+pairs = od_pairs.get_pairs(cells, r_cells=2000.0, node_column='node_id')
+times = routing.tiered_path_costs(pairs, graph, weight='walk_time_s')
+acc   = accessibility.cumulative_opportunities(
+    times, {'supermarkets': weights}, {},
+    [accessibility.Bin('15min', 0, 15 * 60)],
+)
+```
+
+A complete, runnable version (OSM ingestion, plotting): [`examples/minimal/accessibility.ipynb`](examples/minimal/accessibility.ipynb).
+
+## Modules
+
+See the [API reference](https://aperta.readthedocs.io/en/latest/api/) for module-by-module documentation.
+
+## Design
+
+What aperta is:
+
+- **Path-first.** Routing returns the realized route alongside the cost as a single primitive, so per-edge attributes (gradient, exposure, surface, perceived safety) aggregate along the path natively — the architectural prerequisite for utility-based and route-aware accessibility.
+- **Cross-modal.** Mode and network are orthogonal: one network per mode, with `min` / `logsum` aggregation across modes as a first-class operation. Generalizes to any axis of network variation — time-of-day, congestion regime, infrastructure scenario.
+- **Multi-scale.** A tiered cell / zone OD structure bounds per-origin computation independently of network extent — country-scale reach without country-scale destination counts.
+- **Live-graph routing.** Dijkstra on the graph directly, no precomputed index. Slower per query than contraction-hierarchy tools, but edge-weight changes are immediate — what makes iterative calibration and scenario comparison practical.
+
+What aperta is not:
+
+- **No filesystem assumptions.** Algorithm functions take plain `networkx` graphs, `pandas` / `geopandas` frames, and `numpy` arrays — no file I/O.
+- **No DAG engine, no global state.** No caching, no dependency tracking, no orchestration. Every function takes its inputs explicitly. For DAG features, layer [DVC](https://dvc.org/) or [Snakemake](https://snakemake.readthedocs.io/) on top.
+
+## Interoperability with other accessibility tools
+
+Aperta deliberately doesn't try to do everything in-house. Two interoperability patterns are worth flagging:
+
+- **Public transit via R5.** Aperta has no native public-transit support right now (no GTFS reader, no RAPTOR-style time-dependent routing). Anything that can be expressed as a `networkx` graph with appropriate edge weights — including simplified transit-as-graph models — will route in aperta like any other network. For full GTFS-based transit routing (calendars, transfers, frequency-based services), the pragmatic pattern is to compute the transit OD cost matrix with [R5](https://github.com/conveyal/r5) (via [r5py](https://r5py.readthedocs.io/)), align its origins/destinations to the same cell layer aperta uses, and feed the resulting per-mode cost ODM into `od_pairs.aggregate_across_modes` alongside the walk / cycle / car ODMs computed by aperta. The cross-modal aggregation proceeds identically whether each per-mode ODM came from aperta's router or elsewhere.
+- **Faster cost-only routing via Pandana/pandarm.** Aperta's live-graph routing is the right trade-off for path-first, iterative, and scenario-comparative workloads, but for one-shot cost-only accessibility on a large fixed network, contraction-hierarchy backends like [Pandana](https://udst.github.io/pandana/) (and its recent modernized fork pandarm) route faster per query. The calibrated edge weights produced by `calibration.calibrate_edge_weights` are plain per-edge attributes on the `networkx` graph and transfer cleanly to a Pandana/pandarm network built from the same OSM extract — i.e., you can calibrate edge weights in aperta and then route with them in Pandana/pandarm.
+
+## Benchmark vs Pandana
+
+Ultimate speed for the full accessibility stack was not aperta's goal. Nonetheless, aperta typically runs within 1–5× of Pandana on equivalent cumulative-opportunity workloads. When the area of interest (for which to calculate accessibilities) is substantially smaller than the buffer zone (destinations to consider), or when aiming to recalculate accessibilities for a select subset of locations after a graph topology or edge weight change, aperta can even be faster than Pandana. See the [benchmark](https://aperta.readthedocs.io/en/latest/benchmark.html) for the full setup and numbers, or run [`examples/extended/benchmark.py`](examples/extended/benchmark.py) to reproduce.
+
+## Acknowledgments
+
+Aperta was developed at the [Chair of Ecological Systems Design](https://esd.ifu.ethz.ch/) at [ETH Zurich](https://ethz.ch) in the context of the [BlueCity](https://www.epfl.ch/schools/enac/blue-city-project/) project and [LUMOS](https://csfm.ethz.ch/en/research/projects/lumos.html).
+
+## Cite this
+
+If you use aperta in a publication, please cite the archived release:
+
+```bibtex
+@software{miotti_aperta_2026,
+  author    = {Miotti, Marco},
+  title     = {{Aperta: Path-first, cross-modal accessibility analysis in Python}},
+  year      = 2026,
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.XXXXXXX},
+  url       = {https://doi.org/10.5281/zenodo.XXXXXXX}
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

aperta-0.1.0a0/README.md

@@ -0,0 +1,134 @@
+# aperta
+
+[![tests](https://github.com/mmiotti/aperta/actions/workflows/test.yml/badge.svg)](https://github.com/mmiotti/aperta/actions/workflows/test.yml)
+[![docs](https://readthedocs.org/projects/aperta/badge/?version=latest)](https://aperta.readthedocs.io/en/latest/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![license](https://img.shields.io/github/license/mmiotti/aperta.svg)](LICENSE)
+
+A Python toolkit for **cross-modal accessibility analysis on transport networks** — routing, distance/time computation, utility-based travel costs, and gravity- and logsum-based accessibility metrics on `networkx` graphs (routed via `scipy.sparse.csgraph`).
+
+![Three families of aperta capabilities, illustrated on the Bern region: network preparation (estimated traffic volumes and calibrated edge speeds), path feature collection (bike-comfort scores along realized routes and aggregated per origin cell), and accessibility analysis (time-based access to hiking opportunities and cross-modal utility-based access to groceries).](docs/assets/hero.jpg)
+
+The name is Latin/Italian for *open* — the condition that accessibility, at root, measures.
+
+## Status
+
+**Pre-1.0, alpha.** Published alongside a toolkit paper (in submission). APIs may change without notice until v1.0.
+
+## Install
+
+```bash
+pip install aperta              # algorithms only
+pip install 'aperta[osm]'       # + OSM ingestion (osmnx)
+pip install 'aperta[examples]'  # + everything needed to run the example notebooks
+```
+
+Requires Python ≥ 3.11.
+
+The `osm_helpers` and `topography` modules import their backing libraries
+(`osmnx`, `rasterio`, `requests`) lazily — install the matching `[osm]` /
+`[topo]` extra if you use them, otherwise an `ImportError` surfaces at first use.
+
+For development:
+
+```bash
+git clone git@github.com:mmiotti/aperta.git
+cd aperta
+pip install -e ".[osm,topo,h3]"
+python -m unittest discover -s tests -t .
+```
+
+> If you plan to edit the example notebooks under `examples/`, run the
+> [jupytext + nbstripout setup](CONTRIBUTING.md#editing-notebooks) once
+> after cloning. Not needed if you're only using the library or
+> modifying Python source.
+
+## Workflow
+
+Aperta is organized around a six-phase workflow. Phases 4 and 5's calibration sub-step are optional; the rest is the minimum end-to-end pipeline.
+
+1. **Load and prepare data** — networks (one per mode), land use, topography, optional ground-truth data (traffic counters, travel-survey times).
+2. **Map data to units** — aggregate source data into the `cells → zones` hierarchy; snap geo units to network nodes.
+3. **Build sparse OD pairs** — the tiered OD structure (three distance tiers) with per-cell origins at near range and zone-aggregated destinations at far range, keeping per-origin compute bounded independently of network extent.
+4. **(Optional) Estimate traffic flows** — sampled betweenness centrality; optionally calibrate against observed counter data.
+5. **Estimate travel costs** — shortest paths on the routing graph plus per-cell trip overheads. Optionally: utility-based generalized costs and edge-weight calibration against observed travel times.
+6. **Calculate accessibilities** — cumulative-opportunity, gravity, nearest-k, logsum (and cross-modal aggregation across per-mode results).
+
+See the [API reference](https://aperta.readthedocs.io/en/latest/api/) for which module covers each phase and for the specific functions.
+
+Runnable examples, in increasing depth:
+
+- [examples/minimal/accessibility.ipynb](examples/minimal/accessibility.ipynb) — what aperta does in ~50 lines using only OpenStreetMap. Cambridge MA, ~10 s.
+- [examples/walkthrough/accessibility.ipynb](examples/walkthrough/accessibility.ipynb) — guided tour of every primitive; walking + cycling, cross-modal logsum, path-first per-edge feature aggregation. Central Paris, ~1 min end-to-end.
+- [examples/extended/](examples/extended/) — production-scale Bern + 40 km: prep pipeline, calibration against observed travel times, traffic-flow estimation, accessibility analysis. ~30 min.
+
+The toy-world end-to-end test in [tests/test_workflow.py](tests/test_workflow.py) doubles as the smallest possible walk-through (~150 lines, runs in a second).
+
+## Quick example
+
+The three-line core of an accessibility analysis: build the tiered OD pairs, route shortest paths, count opportunities within a travel-time budget.
+
+```python
+from aperta import accessibility, od_pairs, routing
+
+pairs = od_pairs.get_pairs(cells, r_cells=2000.0, node_column='node_id')
+times = routing.tiered_path_costs(pairs, graph, weight='walk_time_s')
+acc   = accessibility.cumulative_opportunities(
+    times, {'supermarkets': weights}, {},
+    [accessibility.Bin('15min', 0, 15 * 60)],
+)
+```
+
+A complete, runnable version (OSM ingestion, plotting): [`examples/minimal/accessibility.ipynb`](examples/minimal/accessibility.ipynb).
+
+## Modules
+
+See the [API reference](https://aperta.readthedocs.io/en/latest/api/) for module-by-module documentation.
+
+## Design
+
+What aperta is:
+
+- **Path-first.** Routing returns the realized route alongside the cost as a single primitive, so per-edge attributes (gradient, exposure, surface, perceived safety) aggregate along the path natively — the architectural prerequisite for utility-based and route-aware accessibility.
+- **Cross-modal.** Mode and network are orthogonal: one network per mode, with `min` / `logsum` aggregation across modes as a first-class operation. Generalizes to any axis of network variation — time-of-day, congestion regime, infrastructure scenario.
+- **Multi-scale.** A tiered cell / zone OD structure bounds per-origin computation independently of network extent — country-scale reach without country-scale destination counts.
+- **Live-graph routing.** Dijkstra on the graph directly, no precomputed index. Slower per query than contraction-hierarchy tools, but edge-weight changes are immediate — what makes iterative calibration and scenario comparison practical.
+
+What aperta is not:
+
+- **No filesystem assumptions.** Algorithm functions take plain `networkx` graphs, `pandas` / `geopandas` frames, and `numpy` arrays — no file I/O.
+- **No DAG engine, no global state.** No caching, no dependency tracking, no orchestration. Every function takes its inputs explicitly. For DAG features, layer [DVC](https://dvc.org/) or [Snakemake](https://snakemake.readthedocs.io/) on top.
+
+## Interoperability with other accessibility tools
+
+Aperta deliberately doesn't try to do everything in-house. Two interoperability patterns are worth flagging:
+
+- **Public transit via R5.** Aperta has no native public-transit support right now (no GTFS reader, no RAPTOR-style time-dependent routing). Anything that can be expressed as a `networkx` graph with appropriate edge weights — including simplified transit-as-graph models — will route in aperta like any other network. For full GTFS-based transit routing (calendars, transfers, frequency-based services), the pragmatic pattern is to compute the transit OD cost matrix with [R5](https://github.com/conveyal/r5) (via [r5py](https://r5py.readthedocs.io/)), align its origins/destinations to the same cell layer aperta uses, and feed the resulting per-mode cost ODM into `od_pairs.aggregate_across_modes` alongside the walk / cycle / car ODMs computed by aperta. The cross-modal aggregation proceeds identically whether each per-mode ODM came from aperta's router or elsewhere.
+- **Faster cost-only routing via Pandana/pandarm.** Aperta's live-graph routing is the right trade-off for path-first, iterative, and scenario-comparative workloads, but for one-shot cost-only accessibility on a large fixed network, contraction-hierarchy backends like [Pandana](https://udst.github.io/pandana/) (and its recent modernized fork pandarm) route faster per query. The calibrated edge weights produced by `calibration.calibrate_edge_weights` are plain per-edge attributes on the `networkx` graph and transfer cleanly to a Pandana/pandarm network built from the same OSM extract — i.e., you can calibrate edge weights in aperta and then route with them in Pandana/pandarm.
+
+## Benchmark vs Pandana
+
+Ultimate speed for the full accessibility stack was not aperta's goal. Nonetheless, aperta typically runs within 1–5× of Pandana on equivalent cumulative-opportunity workloads. When the area of interest (for which to calculate accessibilities) is substantially smaller than the buffer zone (destinations to consider), or when aiming to recalculate accessibilities for a select subset of locations after a graph topology or edge weight change, aperta can even be faster than Pandana. See the [benchmark](https://aperta.readthedocs.io/en/latest/benchmark.html) for the full setup and numbers, or run [`examples/extended/benchmark.py`](examples/extended/benchmark.py) to reproduce.
+
+## Acknowledgments
+
+Aperta was developed at the [Chair of Ecological Systems Design](https://esd.ifu.ethz.ch/) at [ETH Zurich](https://ethz.ch) in the context of the [BlueCity](https://www.epfl.ch/schools/enac/blue-city-project/) project and [LUMOS](https://csfm.ethz.ch/en/research/projects/lumos.html).
+
+## Cite this
+
+If you use aperta in a publication, please cite the archived release:
+
+```bibtex
+@software{miotti_aperta_2026,
+  author    = {Miotti, Marco},
+  title     = {{Aperta: Path-first, cross-modal accessibility analysis in Python}},
+  year      = 2026,
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.XXXXXXX},
+  url       = {https://doi.org/10.5281/zenodo.XXXXXXX}
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

aperta-0.1.0a0/pyproject.toml

@@ -0,0 +1,145 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aperta"
+version = "0.1.0a0"
+description = "Python toolkit for cross-modal accessibility analysis on transport networks."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Marco Miotti", email = "marco@miotti.me"},
+]
+keywords = [
+    "accessibility",
+    "transport",
+    "mobility",
+    "urban",
+    "routing",
+    "networks",
+    "gis",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "numpy>=2.0",
+    "pandas>=2.0",
+    "geopandas>=1.0",
+    "networkx>=3.0",        # input graph type; routing converts to scipy CSR
+    "scipy>=1.10",          # routing (csgraph.dijkstra), KDTree, sparse matrices
+    "statsmodels>=0.14",    # calibration.calibrate_edge_weights (OLS)
+    "numba>=0.60",          # @njit hot loops in od_pairs + traffic_flows
+    "matplotlib>=3.8",      # visualization module
+]
+
+# Optional feature extras. Core routing / accessibility / OD-pairs work
+# on any networkx graph without any of these.
+#
+#   - `osm`: OSM-derived networks. `osmnx` covers all three uses in
+#     aperta core:
+#       * `osm_helpers.fetch_network` / `categorize_edges` — OSM downloads;
+#       * `network_processing.consolidate_intersections` — wraps
+#         `osmnx.consolidate_intersections` for OSMnx-output cleanup;
+#       * `network_processing.load_consolidated_graphml` — graphml load
+#         with custom-dtype casts.
+#   - `topo`: `topography.fetch_copernicus_dem` + `geo_processing.
+#     sample_raster_at_points` need `rasterio` (raster I/O) and `requests`
+#     (DEM tile download).
+#   - `h3`: `geo_processing.build_h3_grid` (and any other h3-based helper).
+#   - `examples`: everything needed to run the example notebooks. Rolls up
+#     the three domain extras + notebook tooling (`jupytext`), basemap
+#     tiles (`contextily`), and Swiss-specific BFS PC-Axis parsing
+#     (`pyaxis`).
+#
+# Install with `pip install 'aperta[osm]'` (or any other extra), or
+# `pip install 'aperta[examples]'` for the full notebook environment.
+[project.urls]
+Homepage      = "https://github.com/mmiotti/aperta"
+Documentation = "https://aperta.readthedocs.io/"
+Repository    = "https://github.com/mmiotti/aperta"
+Issues        = "https://github.com/mmiotti/aperta/issues"
+Changelog     = "https://github.com/mmiotti/aperta/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+osm = ["osmnx>=2.0"]
+topo = ["rasterio>=1.3", "requests>=2.28"]
+h3 = ["h3>=4.0"]
+examples = [
+    "aperta[osm]",
+    "aperta[h3]",
+    "jupytext>=1.16",
+    "contextily>=1.4",
+]
+# Building the Sphinx docs site (read by .readthedocs.yaml).
+docs = [
+    "sphinx>=8.0",
+    "furo>=2024.0",
+    "myst-parser>=4.0",
+]
+
+# Src layout: package code lives under `src/aperta/`. Prevents accidental
+# imports of the local source (Python won't find `aperta` unless it's
+# actually `pip install`-ed), which catches "works on my machine but
+# breaks when installed" bugs early.
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# mypy: static type checker. Loose initial config (non-strict mode) +
+# escape hatches for libraries without type stubs. Tighten over time.
+[tool.mypy]
+python_version = "3.11"
+files = ["src/aperta"]
+# Common libraries without complete type stubs in this stack. Silences
+# "no type stubs for X" errors without disabling type checking of our
+# own code that uses them.
+[[tool.mypy.overrides]]
+module = [
+    "pandas.*",
+    "geopandas.*",
+    "shapely.*",
+    "networkx.*",
+    "scipy.*",
+    "rasterio.*",
+    "osmnx.*",
+    "h3.*",
+    "contextily.*",
+    "matplotlib.*",
+    "mpl_toolkits.*",
+    "statsmodels.*",
+    "numba.*",
+    "pyaxis.*",
+    "requests.*",
+]
+ignore_missing_imports = true
+
+# Ruff: linter + formatter. Lenient initial config; extend rule sets
+# (B, UP, SIM, ...) as the project matures.
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["examples/", "build/", "dist/"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes (unused imports, undefined names, etc.)
+    "W",   # pycodestyle warnings
+    "I",   # isort (import ordering)
+]
+# E501 (line too long) is handled by the formatter; allowing it here
+# means the linter doesn't complain about strings/comments that the
+# formatter chose not to break.
+ignore = ["E501"]

aperta-0.1.0a0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aperta-0.1.0a0/src/aperta/__init__.py

@@ -0,0 +1,70 @@
+"""
+aperta — cross-modal accessibility analysis on transport networks.
+
+The library is organized around a six-phase workflow:
+
+  1. Load and prepare data  — networks (per mode), land use, topography.
+  2. Map data to units      — `cells → zones` aggregation hierarchy
+                              (`geo_mapping`, `network_processing.snap_to_network_nodes`,
+                              `network_processing.assign_to_eligible_centroid`).
+  3. Build sparse OD pairs  — `od_pairs.get_pairs` returns a `TieredODNodePairs`
+                              (three distance tiers: cells_to_cells,
+                              cells_to_zones, zones_to_zones). Lift to
+                              `TieredODGeoPairs` via
+                              `od_pairs.reindex_by_geo_unit` for cross-modal
+                              alignment / geo-unit-keyed overheads.
+  4. Estimate traffic flows — `traffic_flows.nested_node_sample` +
+                              `network_processing.get_*_betweenness*`.
+  5. Estimate travel costs  — `routing.tiered_path_costs` /
+                              `routing.tiered_path_aggregate` (Dijkstra on any
+                              networkx graph; the latter also aggregates
+                              per-edge / per-node features along realised
+                              routes via `PathAggregation` / `NodeAggregation`)
+                              + the `overhead` module
+                              (`add_node_overheads` for node-keyed,
+                              `add_geo_overheads` / `add_origin_cell_overhead`
+                              for geo-keyed). `utility.route_utility` +
+                              `add_endpoint_utility` for utility-based costs.
+                              `routing.aggregate_along_paths` is the path-walker
+                              primitive when you have a pre-computed list of
+                              paths rather than a `TieredODPairs`.
+  6. Calculate accessibility — `accessibility.cumulative_opportunities` (cumulative),
+                               `accessibility.gravity`, `accessibility.nearest_k`.
+                               Cross-modal: combine per-mode `TieredODGeoPairs`
+                               with `od_pairs.aggregate_across_modes` first.
+
+All algorithm modules (`od_pairs`, `routing`, `overhead`, `accessibility`,
+`utility`, `traffic_flows`, `geo_processing`, `geo_mapping`,
+`network_processing`, `visualization`, `osm_helpers`, `calibration`,
+`topography`, `errors`) operate on plain numpy / pandas / networkx inputs — no
+filesystem assumptions, no opinionated project structure.
+See `tests/test_workflow.py` for the ~150-line end-to-end toy-world
+example, `examples/minimal/accessibility.ipynb` for a ~50-line OSM
+quickstart, `examples/walkthrough/accessibility.ipynb` for the full
+guided tour, and `examples/extended/` for a multi-notebook showcase
+with published-paper calibration (Bern + 40 km).
+
+Key types:
+  - `od_pairs.TieredODNodePairs` — three-tier OD dict-of-arrays keyed by network
+                                   node IDs. Output of routing.
+  - `od_pairs.TieredODGeoPairs`  — three-tier OD dict-of-arrays keyed by
+                                   geo-unit IDs (cells / zones).
+                                   Mode-agnostic; required for cross-modal
+                                   accessibility and geo-unit-keyed overhead.
+  - `od_pairs.TieredODPairs`     — abstract base of the two above; use as a
+                                   type hint when key space doesn't matter.
+  - `accessibility.Bin`       — half-open cost bin for `cumulative_opportunities`.
+  - `accessibility.Decay`     — named cost-decay callable for `gravity`.
+  - `utility.Utility`         — linear utility spec (constant + cost + route
+                                + origin + destination feature coefficients).
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("aperta")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]