multimodalpy 0.2.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. multimodalpy-0.4.0/ARCHITECTURE.md +71 -0
  2. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/CHANGELOG.md +87 -2
  3. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/CITATION.cff +3 -2
  4. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/DATA_SCHEMA.md +147 -18
  5. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/PKG-INFO +134 -19
  6. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/README.md +131 -17
  7. multimodalpy-0.4.0/docs/api.md +12 -0
  8. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/docs/conf.py +2 -0
  9. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/docs/index.md +14 -5
  10. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/pyproject.toml +5 -5
  11. multimodalpy-0.4.0/src/multimodalpy/__init__.py +56 -0
  12. multimodalpy-0.4.0/src/multimodalpy/__main__.py +6 -0
  13. multimodalpy-0.4.0/src/multimodalpy/_boundaries.py +674 -0
  14. multimodalpy-0.4.0/src/multimodalpy/_cli.py +114 -0
  15. multimodalpy-0.2.0/src/multimodalpy/process_gtfs.py → multimodalpy-0.4.0/src/multimodalpy/_gtfs.py +145 -3
  16. multimodalpy-0.4.0/src/multimodalpy/_matrix.py +767 -0
  17. multimodalpy-0.4.0/src/multimodalpy/_nap.py +316 -0
  18. multimodalpy-0.2.0/src/multimodalpy/process_osm.py → multimodalpy-0.4.0/src/multimodalpy/_osm.py +298 -6
  19. multimodalpy-0.4.0/src/multimodalpy/_text.py +104 -0
  20. multimodalpy-0.4.0/src/multimodalpy/_writers.py +366 -0
  21. multimodalpy-0.4.0/src/multimodalpy/analysis/__init__.py +26 -0
  22. multimodalpy-0.4.0/src/multimodalpy/analysis/_common.py +238 -0
  23. multimodalpy-0.4.0/src/multimodalpy/analysis/_isochrones.py +310 -0
  24. multimodalpy-0.4.0/src/multimodalpy/analysis/_shortest_path.py +342 -0
  25. multimodalpy-0.4.0/src/multimodalpy/area.py +17 -0
  26. multimodalpy-0.4.0/src/multimodalpy/io.py +155 -0
  27. multimodalpy-0.4.0/src/multimodalpy/network.py +497 -0
  28. multimodalpy-0.2.0/tests/test_get_area_boundaries.py → multimodalpy-0.4.0/tests/test_area.py +24 -22
  29. multimodalpy-0.2.0/tests/test_get_area_cities.py → multimodalpy-0.4.0/tests/test_area_cities.py +33 -39
  30. multimodalpy-0.2.0/tests/test_process_gtfs.py → multimodalpy-0.4.0/tests/test_gtfs.py +13 -14
  31. multimodalpy-0.4.0/tests/test_isochrones.py +325 -0
  32. multimodalpy-0.4.0/tests/test_matrix.py +314 -0
  33. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/tests/test_multipart_area.py +25 -21
  34. multimodalpy-0.2.0/tests/test_get_network.py → multimodalpy-0.4.0/tests/test_network.py +351 -168
  35. multimodalpy-0.4.0/tests/test_network_loading.py +215 -0
  36. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/tests/test_output_format.py +27 -39
  37. multimodalpy-0.4.0/tests/test_public_api.py +94 -0
  38. multimodalpy-0.4.0/tests/test_shortest_path.py +273 -0
  39. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/tests/test_topology_crs.py +5 -5
  40. multimodalpy-0.2.0/ARCHITECTURE.md +0 -50
  41. multimodalpy-0.2.0/docs/api.md +0 -12
  42. multimodalpy-0.2.0/src/multimodalpy/__init__.py +0 -46
  43. multimodalpy-0.2.0/src/multimodalpy/get_area.py +0 -1380
  44. multimodalpy-0.2.0/src/multimodalpy/get_network.py +0 -913
  45. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/.github/workflows/docs.yml +0 -0
  46. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/.github/workflows/publish.yml +0 -0
  47. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/.github/workflows/tests.yml +0 -0
  48. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/.gitignore +0 -0
  49. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/.readthedocs.yaml +0 -0
  50. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/CODE_OF_CONDUCT.md +0 -0
  51. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/CONTRIBUTING.md +0 -0
  52. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/LICENSE +0 -0
  53. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/docs/_static/.gitkeep +0 -0
  54. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/docs/requirements.txt +0 -0
  55. {multimodalpy-0.2.0 → multimodalpy-0.4.0}/tests/conftest.py +0 -0
@@ -0,0 +1,71 @@
1
+ multimodalpy/
2
+ ├── LICENSE
3
+ ├── README.md
4
+ ├── ARCHITECTURE.md
5
+ ├── CONTRIBUTING.md
6
+ ├── CODE_OF_CONDUCT.md
7
+ ├── CITATION.cff
8
+ ├── CHANGELOG.md
9
+ ├── pyproject.toml
10
+ ├── .gitignore
11
+ ├── .readthedocs.yaml
12
+ │
13
+ ├── .github/
14
+ │ └── workflows/
15
+ │ ├── tests.yml # pytest on Python 3.11-3.13, on push/PR
16
+ │ ├── docs.yml # Sphinx build check, on push/PR
17
+ │ └── publish.yml # build + publish to (Test)PyPI on release
18
+ │
19
+ ├── src/
20
+ │ └── multimodalpy/
21
+ │ ├── __init__.py # package shortcuts (download_network, find_area, ...)
22
+ │ ├── __main__.py # python -m multimodalpy
23
+ │ ├── network.py # public: download_network, download_osm, download_gtfs
24
+ │ ├── area.py # public: find_area
25
+ │ ├── io.py # public: read_matrix, read_graph
26
+ │ ├── analysis/ # public: isochrones, shortest_path (one private file each)
27
+ │ │ ├── __init__.py
28
+ │ │ ├── _common.py # shared: network loading, snapping, cutoffs, Dijkstra
29
+ │ │ ├── _isochrones.py
30
+ │ │ └── _shortest_path.py
31
+ │ ├── _cli.py # the `multimodalpy` command
32
+ │ ├── _boundaries.py # boundaries file (pooch), study-area lookup, provinces
33
+ │ ├── _nap.py # NAP client: API key, .env, GTFS feed downloads
34
+ │ ├── _osm.py # OSM download and standardization per mode
35
+ │ ├── _gtfs.py # GTFS download and standardization
36
+ │ ├── _matrix.py # CSR matrix (matrix.npz) and network loading
37
+ │ ├── _writers.py # writing every output format
38
+ │ └── _text.py # name normalisation, edit distances, slugs
39
+ │
40
+ ├── tests/ # one file per module, plus end-to-end output checks
41
+ │ ├── test_public_api.py
42
+ │ ├── test_network.py
43
+ │ ├── test_area.py
44
+ │ ├── test_area_cities.py
45
+ │ ├── test_multipart_area.py
46
+ │ ├── test_gtfs.py
47
+ │ ├── test_matrix.py
48
+ │ ├── test_network_loading.py
49
+ │ ├── test_isochrones.py
50
+ │ ├── test_shortest_path.py
51
+ │ ├── test_output_format.py
52
+ │ └── test_topology_crs.py
53
+ │
54
+ └── docs/
55
+ ├── conf.py # Sphinx config (pydata-sphinx-theme)
56
+ ├── index.md
57
+ ├── api.md # autosummary-generated API reference
58
+ └── requirements.txt # pinned docs deps for Read the Docs' isolated build
59
+
60
+ Notes
61
+ -----
62
+ - No `data/` folder is tracked in the repository. The default study-area
63
+ boundaries are downloaded on demand via `pooch.retrieve()` from a GitHub
64
+ release asset and cached locally (see `_boundaries.py`); this keeps the repo
65
+ small and avoids committing large binary geospatial files to git history.
66
+ - `dist/` (build artifacts from `python -m build`) is git-ignored; each
67
+ release version's wheel/sdist filenames are permanently reserved by
68
+ PyPI/TestPyPI once uploaded, so they must never be committed.
69
+ - Documentation is built by Read the Docs from `.readthedocs.yaml` +
70
+ `docs/`; `docs.yml` in CI is a build-check only (fails PRs that break the
71
+ Sphinx build), it does not deploy.
@@ -5,6 +5,91 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.4.0] - 2026-11-03
9
+
10
+ ### Changed
11
+ - **Breaking:** the public API is reorganised into four modules, one per task,
12
+ with clearer names (#77). There are no compatibility aliases; update your
13
+ code with this table:
14
+
15
+ | 0.3.0 | Now |
16
+ |---|---|
17
+ | `get_network.main()` | `multimodalpy.download_network()` (`network.download_network`) |
18
+ | `get_area.find_area_boundary()` | `multimodalpy.find_area()` (`area.find_area`) |
19
+ | `get_area.download_osm_layers()` | `network.download_osm()` |
20
+ | `get_area.download_gtfs_layers()` | `network.download_gtfs()` |
21
+ | `get_area.AmbiguousAreaError` | `area.AmbiguousAreaError` |
22
+ | `get_area.NAPAuthenticationError` | `network.NAPAuthenticationError` |
23
+ | `get_network.read_matrix()` | `multimodalpy.read_matrix()` (`io.read_matrix`) |
24
+ | `get_network.read_graph_json()` | `multimodalpy.read_graph()` (`io.read_graph`) |
25
+ | `from multimodalpy.isochrones import isochrones` | `multimodalpy.isochrones()` (`analysis.isochrones`) |
26
+ | `python -m multimodalpy.get_network` | `multimodalpy` or `python -m multimodalpy` |
27
+
28
+ - **Breaking:** `download_network()` parameters renamed: `output_path` →
29
+ `output_dir`, `output_file_type` → `formats`, `schedule` →
30
+ `write_schedule`, `gtfs_zips` → `keep_gtfs_zips`. The manifest it returns
31
+ uses `formats` and `output_dir` as keys. Command-line flags follow:
32
+ `--output-dir`, `--formats`, `--write-schedule`, `--keep-gtfs-zips`.
33
+ - The remaining helpers of `get_area` (`slugify`, `normalize_name`,
34
+ `levenshtein_*`, `resolve_nap_api_key`, `find_dotenv`, ...) are now private.
35
+ - The API reference documents only each module's public names.
36
+
37
+ ### Added
38
+ - `shortest_path()` (`multimodalpy.analysis`, #78): the shortest path from
39
+ every origin to every destination (node ids or coordinates) within a
40
+ threshold in minutes (`weight="tts"`) or metres (`weight="length"`), on a
41
+ walking, bike or driving network in any output format. Returns a
42
+ GeoDataFrame with `origin`, `destination`, `time_min`, `length_m`,
43
+ `n_edges` and the path as a line (`geometry=False` for large tables); pairs
44
+ beyond the threshold are left out. Bus and train raise
45
+ `NotImplementedError` until the multimodal network is available.
46
+ - `multimodalpy` command, installed with the package
47
+ (`multimodalpy --area Valencia --modes walking`).
48
+ - `find_area()` has a full docstring (parameters, errors, examples).
49
+
50
+ ### Removed
51
+ - The `multimodal` parameter of `download_network()`, which only raised
52
+ `NotImplementedError`; it will come back with the multimodal network.
53
+ - The `--clean-gtfs` command-line flag, which had no effect.
54
+
55
+ [0.4.0]: https://github.com/aivilor/multimodalpy/compare/v0.3.0...v0.4.0
56
+
57
+ ## [0.3.0] - 2026-10-30
58
+
59
+ ### Added
60
+ - New output format `matrix` (#63): `output_file_type="matrix"` (or
61
+ `--output-file-type matrix`) writes each network as one `matrix.npz`, a
62
+ directed sparse adjacency matrix in CSR form for shortest-path calculations.
63
+ Walking, bike and driving matrices carry `tts` and `length`; bus and train
64
+ matrices carry the 18 travel-time columns of the GTFS edge layer. Parallel
65
+ edges keep the minimum of each weight, and GTFS periods without service are
66
+ `inf`. The file opens with `scipy.sparse.load_npz`. The layout is described
67
+ in the "Matrix" section of `DATA_SCHEMA.md`.
68
+ - `multimodalpy.read_matrix()` reads a `matrix.npz` (or its folder) and returns
69
+ the matrix of one weight as a `scipy.sparse.csr_array`, the node table and
70
+ the metadata.
71
+ - `scipy` is now a required dependency.
72
+ - New public module `multimodalpy.isochrones` (#64). `isochrones()` computes
73
+ the area reachable from one or more origins (node ids or coordinates) within
74
+ each cutoff, in minutes (`weight="tts"`) or metres (`weight="length"`), on a
75
+ walking, bike or driving network. It reads the network in any output format
76
+ (output folder, network folder, `matrix.npz`, `graph.json`, GeoPackage,
77
+ GeoJSON, Shapefile, or the result of `read_matrix` / `read_graph_json`) and
78
+ returns a GeoDataFrame with one polygon per origin and cutoff, nested and in
79
+ the network's CRS. `method="edges"` (default) buffers the streets reached,
80
+ including the reached part of edges crossing the cutoff; `method="hull"`
81
+ draws a concave hull. Bus and train isochrones raise `NotImplementedError`
82
+ until the multimodal network is available.
83
+ - `shapely>=2.0` is now required explicitly (for `shapely.concave_hull`).
84
+
85
+ ### Changed
86
+ - **Breaking:** `process_osm` and `process_gtfs` are now private modules
87
+ (`_process_osm`, `_process_gtfs`) and are no longer part of the public API:
88
+ `multimodalpy.process_osm` and `multimodalpy.process_gtfs` no longer exist,
89
+ and both modules are gone from the API reference. The public API is
90
+ `get_network`, `get_area` and the names in `multimodalpy.__all__`. Code that
91
+ imported them directly should use `get_network.main()` or the `get_area`
92
+ download functions, which return the standardized layers.
8
93
 
9
94
  ## [0.2.0] - 2026-10-29
10
95
 
@@ -35,7 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
35
120
  - `.env` and `.venv/` are in `.gitignore`, so a NAP key in `.env` is not
36
121
  committed by accident (#62).
37
122
 
38
- [0.2.0]: https://github.com/aivilor/multimodalpy/compare/v0.1.5...v0.2.0
123
+ [0.3.0]: https://github.com/aivilor/multimodalpy/compare/v0.2.0...v0.3.0
39
124
 
40
125
  ## [0.1.5] - 2026-10-14
41
126
 
@@ -177,7 +262,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
177
262
  conflict resolution.
178
263
 
179
264
 
180
- [Unreleased]: https://github.com/aivilor/multimodalpy/compare/v0.1.3...HEAD
265
+ [Unreleased]: https://github.com/aivilor/multimodalpy/compare/v0.4.0...HEAD
181
266
  [0.1.3]: https://github.com/aivilor/multimodalpy/compare/v0.1.2...v0.1.3
182
267
  [0.1.1]: https://github.com/aivilor/multimodalpy/compare/v0.1.0...v0.1.1
183
268
  [0.1.0]: https://github.com/aivilor/multimodalpy/releases/tag/v0.1.0
@@ -10,8 +10,9 @@ authors:
10
10
  given-names: "Aida"
11
11
  email: "aivilor@upv.es"
12
12
  affiliation: "Universitat Politècnica de València"
13
- version: 0.1.3
14
- date-released: 2026-09-30
13
+ orcid: "https://orcid.org/0009-0003-7173-452X"
14
+ version: 0.4.0
15
+ date-released: 2026-11-03
15
16
  url: "https://github.com/aivilor/multimodalpy"
16
17
  repository-code: "https://github.com/aivilor/multimodalpy"
17
18
  license: MIT
@@ -1,28 +1,29 @@
1
1
  # Data schema
2
2
 
3
- Reference for everything `multimodalpy.get_network.main()` writes to disk: where
3
+ Reference for everything `multimodalpy.download_network()` writes to disk: where
4
4
  each layer goes, what every column means and how each value is computed.
5
5
 
6
6
  ## Output layout
7
7
 
8
8
  ```
9
- output_path/
9
+ output_dir/
10
10
  ├── study_area_boundary.geojson
11
11
  ├── driving/ nodes edges
12
12
  ├── walking/ nodes edges
13
13
  ├── bike/ nodes edges
14
14
  ├── bus/<dataset>/ nodes edges schedule.csv
15
15
  ├── train/<dataset>/ nodes edges schedule.csv
16
- ├── gtfs_zips/ only with gtfs_zips=True
17
- └── <area>.gpkg only with output_file_type="geopackage"
16
+ ├── gtfs_zips/ only with keep_gtfs_zips=True
17
+ └── <area>.gpkg only with formats="geopackage"
18
18
  ```
19
19
 
20
20
  GeoJSON and Shapefile write one file per layer inside its mode folder (a
21
21
  Shapefile is five files: `.shp`, `.shx`, `.dbf`, `.prj`, `.cpg`). GeoPackage is a
22
22
  single file at the root holding every layer, so it is not split into folders.
23
- `schedule.csv` is only written with `schedule=True`. NetworkX writes one `graph.json`
23
+ `schedule.csv` is only written with `write_schedule=True`. NetworkX writes one `graph.json`
24
24
  per mode folder instead of `nodes` and `edges`
25
- (see [NetworkX graphs](#networkx-graphs-graphjson)).
25
+ (see [NetworkX graphs](#networkx-graphs-graphjson)), and the matrix export one
26
+ `matrix.npz` (see [Matrix](#matrix-matrixnpz)).
26
27
 
27
28
 
28
29
 
@@ -47,18 +48,18 @@ funicular 7, monorail 12) and under `bus/` otherwise. The feed itself is read
47
48
  rather than the NAP metadata, because the NAP declares some datasets as bus and
48
49
  rail at once (Cercanías Renfe). An unreadable feed is treated as bus.
49
50
 
50
- ## `main()` parameters that shape the output
51
+ ## `download_network()` parameters that shape the output
51
52
 
52
53
  | Parameter | Default | Effect |
53
54
  |---|---|---|
54
- | `output_file_type` | `"geojson"` | A format or a list of formats. With a list, download and normalisation run once and only the writing step repeats. |
55
+ | `formats` | `"geojson"` | A format or a list of formats. With a list, download and normalisation run once and only the writing step repeats. |
55
56
  | `crs` | `"EPSG:4326"` | CRS of every output layer. |
56
57
  | `connect_parts` | `True` | Add the roads joining the parts of a multi-part municipality (see "Municipalities in several parts"). |
57
- | `schedule` | `False` | Also write the trip-by-trip timetable of each GTFS feed. Off by default because it is by far the largest part of a download. |
58
- | `gtfs_zips` | `False` | Keep the zips downloaded from the NAP. Off by default: they are only the raw input and can be downloaded again. |
59
- | `multimodal` | `False` | Reserved for the multimodal network, not implemented yet. `True` raises `NotImplementedError`. |
58
+ | `write_schedule` | `False` | Also write the trip-by-trip timetable of each GTFS feed. Off by default because it is by far the largest part of a download. |
59
+ | `keep_gtfs_zips` | `False` | Keep the zips downloaded from the NAP. Off by default: they are only the raw input and can be downloaded again. |
60
60
 
61
- `main()` prints nothing. It returns a manifest with the files written and, when a
61
+ `download_network()` prints nothing. It returns a manifest with the files written
62
+ (`files`, and `files_by_format` when several formats were asked for) and, when a
62
63
  public transport mode was requested but produced no data, a `gtfs_status` field
63
64
  saying why. When parts of a multi-part municipality could not be connected, an
64
65
  `unconnected_parts` field lists them per mode, e.g. `{"driving": [3]}`. Diagnostic messages go through `logging` and are silent unless the
@@ -279,13 +280,13 @@ any other way. `tm_` is mean travel time and `trp_` is number of trips.
279
280
 
280
281
  ## GTFS schedule
281
282
 
282
- Written only with `schedule=True`: one row per trip and edge, with no geometry.
283
+ Written only with `write_schedule=True`: one row per trip and edge, with no geometry.
283
284
  It is **not** clipped to the study area, so it holds the full timetable of every
284
285
  downloaded feed, including operators with no stop inside the area.
285
286
 
286
287
  ## NetworkX graphs (`graph.json`)
287
288
 
288
- With `output_file_type="networkx"` each network is written as one
289
+ With `formats="networkx"` each network is written as one
289
290
  `graph.json`: `<mode>/graph.json` for OSM and `<bus|train>/<dataset>/graph.json`
290
291
  for GTFS, next to `study_area_boundary.geojson`. Each file is a NetworkX
291
292
  `MultiDiGraph` in node-link JSON:
@@ -304,7 +305,7 @@ for GTFS, next to `study_area_boundary.geojson`. Each file is a NetworkX
304
305
  - The edge list is always under `"edges"`, whatever networkx version wrote it.
305
306
  Files written before this was fixed may use `"links"`.
306
307
  - `graph.crs` is the CRS of the node `x` / `y` and of the edge geometries, the
307
- same as the `crs` passed to `main()`.
308
+ same as the `crs` passed to `download_network()`.
308
309
  - `geometry` is WKT text.
309
310
  - Several edges can join the same pair of nodes; `key` tells them apart.
310
311
 
@@ -321,13 +322,13 @@ A GTFS edge that crosses the study-area boundary keeps its stop outside the
321
322
  area, which the stops layer drops. In the graph that stop is still a node, with
322
323
  its position taken from the edge geometry and its name from the feed.
323
324
 
324
- Read a file with `multimodalpy.read_graph_json`, which accepts either edge key
325
+ Read a file with `multimodalpy.read_graph`, which accepts either edge key
325
326
  and turns `geometry` into shapely objects:
326
327
 
327
328
  ```python
328
- from multimodalpy import read_graph_json
329
+ from multimodalpy import read_graph
329
330
 
330
- G = read_graph_json("output/walking/graph.json")
331
+ G = read_graph("output/walking/graph.json")
331
332
  G.graph["crs"] # 'EPSG:4326'
332
333
  u, v, k, attrs = next(iter(G.edges(keys=True, data=True)))
333
334
  attrs["geometry"] # shapely LineString
@@ -336,6 +337,131 @@ attrs["geometry"] # shapely LineString
336
337
  Without multimodalpy, use networkx directly:
337
338
  `json_graph.node_link_graph(json.load(f), edges="edges")`.
338
339
 
340
+ ## Matrix (`matrix.npz`)
341
+
342
+ With `formats="matrix"` each network is written as one `matrix.npz`:
343
+ `<mode>/matrix.npz` for OSM and `<bus|train>/<dataset>/matrix.npz` for GTFS,
344
+ next to `study_area_boundary.geojson`. It is the network as a **directed sparse
345
+ adjacency matrix** in CSR (compressed sparse row) form, made for shortest-path
346
+ calculations such as isochrones: row = origin node, column = destination node,
347
+ and one value per edge for each weight.
348
+
349
+ It is built from the same final layers as the other formats, but it only keeps
350
+ what a shortest-path calculation needs. Edge geometries, `edge_id`, names and
351
+ trip counts stay in the layers.
352
+
353
+ ### Contents
354
+
355
+ A `.npz` file is a zip of NumPy arrays, each under a key:
356
+
357
+ | Key | Type | Content |
358
+ |---|---|---|
359
+ | `format`, `shape`, `indptr`, `indices`, `data` | | The scipy CSR layout. `data` is the default weight again, so `scipy.sparse.load_npz` opens the file directly. |
360
+ | `w_<weight>` | float64 | One vector per weight (`w_tts`, `w_tts_m_pam`, …), aligned with `indices`. |
361
+ | `node_id` | integer (OSM) / text (GTFS) | The `node_id` of each row, as in the `nodes` layer. |
362
+ | `node_x`, `node_y` | float64 | Node position, in the CRS given in `meta`. |
363
+ | `node_in_area` | boolean | `false` for GTFS stops outside the study area (see below). |
364
+ | `node_layer` | text | Network of the node: `walking`, `bike`, `driving`, `bus/<dataset>` or `train/<dataset>`. |
365
+ | `meta` | text | JSON metadata, see below. |
366
+
367
+ No array holds Python objects, so the file is read without pickle.
368
+
369
+ ### How CSR stores the edges
370
+
371
+ `indices` and every weight vector list all the edges one after another, grouped
372
+ by origin row and sorted by destination. `indptr` has one value per row plus
373
+ one: the edges leaving row `i` are at positions `indptr[i]` to
374
+ `indptr[i + 1] - 1`. Two equal values in a row mean that node has no outgoing
375
+ edges. With three nodes and the edges A→B 30 s, A→C 50 s, B→C 20 s and
376
+ C→A 45 s:
377
+
378
+ | | A (0) | B (1) | C (2) |
379
+ |---|---|---|---|
380
+ | **A (0)** | | 30 | 50 |
381
+ | **B (1)** | | | 20 |
382
+ | **C (2)** | 45 | | |
383
+
384
+ ```
385
+ indptr = [0, 2, 3, 4]
386
+ indices = [1, 2, 2, 0]
387
+ w_tts = [30, 50, 20, 45]
388
+ ```
389
+
390
+ The matrix is not symmetric: a one-way street, or different times in each
391
+ direction, is an edge in one direction only, or with a different weight in each.
392
+
393
+ ### Weights
394
+
395
+ | Network | Weights | Unit | Default |
396
+ |---|---|---|---|
397
+ | walking, bike, driving | `tts`, `length` | seconds, metres | `tts` |
398
+ | bus, train | the 18 travel-time columns of the [GTFS edges](#gtfs-edges): `tts_m`, `tts_md`, `tts_mn`, `tts_mx`, `tts_m_pam`, …, `tm_rod_we` | seconds | `tts_m` |
399
+
400
+ A GTFS matrix only has the weights present in its edge layer.
401
+
402
+ ### Rules
403
+
404
+ - **One entry per (origin, destination) pair.** Parallel edges (several OSM ways
405
+ merged into one edge, several routes between the same two stops) keep the
406
+ **minimum of each weight, taken separately**, so the minimum `tts` and the
407
+ minimum `length` can come from different edges.
408
+ - **`inf`** means the edge exists but cannot be travelled with that weight, e.g.
409
+ a GTFS edge with no trips in that period, or a missing value. A missing entry
410
+ means there is no edge.
411
+ - **Zero weights are kept** as edges; shortest-path algorithms such as scipy's
412
+ `dijkstra` treat them as free edges.
413
+ - **Self-loops are dropped**: they never shorten a path.
414
+ - **Direction.** OSM edges are already directed (a two-way street is one edge in
415
+ each direction), so one-way streets are respected.
416
+ - **Node order.** OSM rows follow the `nodes` layer, including isolated nodes,
417
+ which are rows with no edges. GTFS rows follow the stops layer first, then the
418
+ stops outside the study area that are reached by an edge crossing the
419
+ boundary, with `node_in_area = false` and their position taken from the edge
420
+ geometry, as in the [NetworkX graphs](#networkx-graphs-graphjson).
421
+
422
+ ### Metadata (`meta`)
423
+
424
+ | Field | Content |
425
+ |---|---|
426
+ | `format_version` | Version of this layout, currently 1. |
427
+ | `layer`, `mode`, `dataset` | Network of the file (`dataset` is `null` for OSM). |
428
+ | `area` | Municipality name passed to `download_network()`. |
429
+ | `crs` | CRS of `node_x` / `node_y`, the `crs` passed to `download_network()`. |
430
+ | `weights` | Weight names and units, e.g. `[{"name": "tts", "unit": "s"}, …]`. |
431
+ | `default_weight` | Weight stored in `data`. |
432
+ | `gtfs_periods` | GTFS only: start and end hour of each peak period behind `pam` / `ppm`, e.g. `{"peak_am": [7, 9], "peak_pm": [17, 20]}`. `rod` is every other hour. |
433
+ | `gtfs_hour_range` | GTFS only: the `gtfs_hour_range` passed to `download_network()`, or `null`. |
434
+ | `multimodalpy_version` | Version that wrote the file. |
435
+
436
+ A newer `format_version` is rejected when reading instead of being misread.
437
+ Later versions may add arrays (for the multimodal network, e.g. an `edge_type`
438
+ per edge), which older readers simply ignore.
439
+
440
+ ### Reading
441
+
442
+ `multimodalpy.read_matrix` takes the file or its folder and returns the matrix
443
+ of one weight as a `scipy.sparse.csr_array`, the node table and the metadata:
444
+
445
+ ```python
446
+ from scipy.sparse.csgraph import dijkstra
447
+
448
+ from multimodalpy import read_matrix
449
+
450
+ data = read_matrix("output/walking") # default weight: tts
451
+ data.meta["crs"] # 'EPSG:4326'
452
+ origin = data.nodes.index[data.nodes["node_id"] == 1234][0]
453
+ seconds = dijkstra(data.matrix, indices=origin, limit=600)
454
+ reached = data.nodes[seconds <= 600] # nodes within 10 minutes
455
+
456
+ peak = read_matrix("output/bus/<dataset>", weight="tm_pam_wd")
457
+ ```
458
+
459
+ Without multimodalpy, `scipy.sparse.load_npz(path)` returns the default weight
460
+ and `numpy.load(path)` every array.
461
+
462
+ The functions of `multimodalpy.analysis` (`isochrones`, `shortest_path`) work on
463
+ this matrix, and turn every other format into it first.
464
+
339
465
  ---
340
466
 
341
467
  ## From municipality to data
@@ -396,6 +522,9 @@ directly as the region id.
396
522
  - `lanes` is still exported as text and can hold `;`-joined values.
397
523
  - In the **networkx** export, OSM node ids are integers and GTFS node ids are
398
524
  text, so the graphs cannot be joined on node id as they are.
525
+ - In the **matrix** export, the routes between the same two stops are merged
526
+ into one GTFS edge with the fastest time, and waiting times, frequencies and
527
+ transfers are not modelled: a GTFS matrix gives in-vehicle travel times only.
399
528
 
400
529
  ## Abbreviations
401
530
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: multimodalpy
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: Easy creation of multimodal transport networks
5
5
  Project-URL: Homepage, https://github.com/aivilor/multimodalpy
6
6
  Project-URL: Documentation, https://multimodalpy.readthedocs.io
@@ -27,7 +27,8 @@ Requires-Dist: osmnx
27
27
  Requires-Dist: pandas
28
28
  Requires-Dist: pooch>=1.8
29
29
  Requires-Dist: requests
30
- Requires-Dist: shapely
30
+ Requires-Dist: scipy>=1.11
31
+ Requires-Dist: shapely>=2.0
31
32
  Description-Content-Type: text/markdown
32
33
 
33
34
  # multimodalpy
@@ -50,7 +51,10 @@ standardizes its transport networks, one layer per mode:
50
51
  edges with travel times and trip counts by period of the day.
51
52
 
52
53
  All modes share the same column names, and the layers are written as GeoJSON,
53
- Shapefile, GeoPackage or NetworkX graphs, ready for GIS or network analysis.
54
+ Shapefile, GeoPackage, NetworkX graphs or sparse matrices, ready for GIS or
55
+ network analysis. On the walking, cycling and driving networks, `multimodalpy`
56
+ also computes isochrones (the area reachable from a point within a travel time)
57
+ and shortest paths between sets of points.
54
58
 
55
59
  > **Scope.** Only municipalities in Spain are supported: peninsular Spain, the
56
60
  > Balearic Islands, Ceuta and Melilla. The Canary Islands are not in the default
@@ -92,13 +96,13 @@ pip install -e . --group dev
92
96
  Street networks need no setup:
93
97
 
94
98
  ```python
95
- from multimodalpy import get_network
99
+ import multimodalpy as mmp
96
100
 
97
- manifest = get_network.main(
101
+ manifest = mmp.download_network(
98
102
  "Valencia",
99
103
  modes=["walking", "bike", "driving"],
100
- output_path="output",
101
- output_file_type="geojson",
104
+ output_dir="output",
105
+ formats="geojson",
102
106
  )
103
107
  print(manifest["files"])
104
108
  ```
@@ -112,7 +116,7 @@ Public transport data comes from the NAP API, which needs a free API key:
112
116
  register on the [NAP portal](https://nap.transportes.gob.es). The key is looked
113
117
  for in this order:
114
118
 
115
- 1. `main(..., api_key="...")`, or `--api-key` in the command line;
119
+ 1. `download_network(..., api_key="...")`, or `--api-key` in the command line;
116
120
  2. the `NAP_API_KEY` environment variable;
117
121
  3. a `.env` file in the folder you run Python from **or any parent folder**
118
122
  (so a `.env` at the root of your project also works from `notebooks/`):
@@ -126,7 +130,7 @@ accident. Prefer the environment variable or `.env` over `--api-key`, which
126
130
  stays in your shell history.
127
131
 
128
132
  ```python
129
- manifest = get_network.main("Valencia", modes=["walking", "bus", "train"])
133
+ manifest = mmp.download_network("Valencia", modes=["walking", "bus", "train"])
130
134
  ```
131
135
 
132
136
  The key is checked before anything is downloaded. Without one, a warning says
@@ -138,11 +142,12 @@ also written and a warning explains why there is no bus or train data
138
142
  ### Command line
139
143
 
140
144
  ```bash
141
- python -m multimodalpy.get_network --area Valencia --modes walking bus \
142
- --output output --output-file-type geojson geopackage --buffer-m 500
145
+ multimodalpy --area Valencia --modes walking bus \
146
+ --output-dir output --formats geojson geopackage --buffer-m 500
143
147
  ```
144
148
 
145
- Run `python -m multimodalpy.get_network --help` for every option.
149
+ Run `multimodalpy --help` for every option. `python -m multimodalpy` works the
150
+ same way.
146
151
 
147
152
  ## What you get
148
153
 
@@ -154,7 +159,7 @@ output/
154
159
  ├── driving/ nodes edges
155
160
  ├── bus/<dataset>/ nodes edges schedule.csv
156
161
  ├── train/<dataset>/ nodes edges schedule.csv
157
- └── <area>.gpkg only with output_file_type="geopackage"
162
+ └── <area>.gpkg only with formats="geopackage"
158
163
  ```
159
164
 
160
165
  - **Street edges** (every mode): `edge_id`, `from_node`, `to_node`, `highway`,
@@ -169,24 +174,109 @@ output/
169
174
  Every column, the travel-time model and how each value is computed are described
170
175
  in [DATA_SCHEMA.md](DATA_SCHEMA.md).
171
176
 
177
+ ### Shortest paths: the matrix format
178
+
179
+ `formats="matrix"` writes each network as one `matrix.npz`: a directed
180
+ sparse adjacency matrix (CSR) with one vector per weight (`tts` and `length`
181
+ for streets, the travel-time statistics for bus and train). Read it with
182
+ `read_matrix` and pass it to scipy's shortest-path functions:
183
+
184
+ ```python
185
+ from scipy.sparse.csgraph import dijkstra
186
+
187
+ from multimodalpy import read_matrix
188
+
189
+ data = read_matrix("output/walking")
190
+ origin = data.nodes.index[data.nodes["node_id"] == 1234][0]
191
+ seconds = dijkstra(data.matrix, indices=origin, limit=600)
192
+ ```
193
+
194
+ For bus and train the matrix holds in-vehicle times only: waiting and transfers
195
+ are not modelled. See the
196
+ [Matrix section of DATA_SCHEMA.md](DATA_SCHEMA.md#matrix-matrixnpz).
197
+
198
+ ### Isochrones
199
+
200
+ `isochrones` draws the area reachable from one or more origins within each
201
+ travel time, on a walking, bike or driving network:
202
+
203
+ ```python
204
+ from multimodalpy import isochrones
205
+
206
+ areas = isochrones(
207
+ "output", # output folder of download_network()
208
+ origins=(-0.3763, 39.4699), # (x, y) in the network's CRS, or a node_id
209
+ cutoffs=[5, 10, 15], # minutes
210
+ mode="walking",
211
+ )
212
+ areas.to_file("isochrones.geojson")
213
+ ```
214
+
215
+ It reads the network in any output format (`matrix.npz` is the fastest) and
216
+ returns one polygon per origin and cutoff, in the network's CRS. By default
217
+ (`method="edges"`) the area is a band of `buffer_distance` metres (25) along the
218
+ streets reached, so it follows the street network; `method="hull"` draws a
219
+ concave hull around them instead, faster when most of the network is reached.
220
+ With `weight="length"` the cutoffs are metres. Coordinates are snapped to the
221
+ nearest node within `max_snap_distance` metres (250). Bus and train isochrones
222
+ will come with the multimodal network.
223
+
224
+ ### Shortest paths
225
+
226
+ `shortest_path` finds the shortest path from every origin to every destination
227
+ within a travel time or distance, on a walking, bike or driving network:
228
+
229
+ ```python
230
+ from multimodalpy import shortest_path
231
+
232
+ paths = shortest_path(
233
+ "output",
234
+ origins=[(-0.3763, 39.4699)], # node_ids or (x, y)
235
+ destinations=[(-0.3546, 39.4562), (-0.3881, 39.4789)],
236
+ threshold=30, # minutes
237
+ mode="walking",
238
+ )
239
+ paths[["origin", "destination", "time_min", "length_m"]]
240
+ ```
241
+
242
+ It returns a GeoDataFrame with one row per origin and destination within the
243
+ threshold: the travel time (`time_min`) and length (`length_m`) of the path,
244
+ whatever it minimises (`weight="tts"`, the default, or `weight="length"`), its
245
+ number of edges and the path as a line. Pairs beyond the threshold are left
246
+ out. For large origin-destination tables, `geometry=False` skips drawing the
247
+ paths and is much faster.
248
+
172
249
  ## Main options
173
250
 
174
251
  | Option | Default | What it does |
175
252
  |---|---|---|
176
253
  | `modes` | `["walking"]` | Any of `walking`, `bike`, `driving`, `bus`, `train`. Spanish synonyms work too (`caminable`, `bicicleta`, `coche`). |
177
- | `output_file_type` | `"geojson"` | `geojson`, `shapefile`, `geopackage`, `networkx`, or a list to write several at once. |
254
+ | `output_dir` | `"output"` | Folder to write to. |
255
+ | `formats` | `"geojson"` | `geojson`, `shapefile`, `geopackage`, `networkx`, `matrix`, or a list to write several at once. |
178
256
  | `crs` | `"EPSG:4326"` | CRS of every output layer, e.g. `"EPSG:25830"` for metres in Spain. |
179
257
  | `province` | `None` | Province name or INE code, to choose between towns that share a name (e.g. `"Castejón"` exists in Cuenca and Navarra). |
180
258
  | `area_code` | `None` | The municipality's 5-digit INE code (`"46250"` for València) or its full INSPIRE `NATCODE`. |
181
259
  | `buffer_m` | `0` | Widen the download area by this many metres, so streets and routes crossing the municipal boundary are not cut. The exported boundary stays exact. |
182
260
  | `connect_parts` | `True` | For municipalities in several separate parts (e.g. Donostia/San Sebastián), add the shortest roads joining them, marked `connector=True`. `--no-connect-parts` in the CLI. |
183
261
  | `boundaries_path` | packaged file | Your own boundaries file (Shapefile or GeoJSON). |
184
- | `schedule` | `False` | Also write the trip-by-trip timetable of each GTFS feed. |
262
+ | `write_schedule` | `False` | Also write the trip-by-trip timetable of each GTFS feed. |
263
+ | `keep_gtfs_zips` | `False` | Keep the GTFS zips downloaded from the NAP. |
185
264
  | `gtfs_hour_range` | `None` | Only keep trips in an hour window, e.g. `(7, 9)`. |
186
265
 
187
- `main()` writes the files and returns a manifest (a dictionary listing them).
188
- To work with the layers in memory instead, use the functions in
189
- `multimodalpy.get_area`, which return GeoDataFrames. See the
266
+ `download_network()` writes the files and returns a manifest (a dictionary
267
+ listing them).
268
+
269
+ ## The library
270
+
271
+ | Module | What it is for |
272
+ |---|---|
273
+ | `multimodalpy.network` | `download_network()`; `download_osm()` and `download_gtfs()` return the layers in memory (GeoDataFrames) instead of writing them. |
274
+ | `multimodalpy.area` | `find_area()`: the municipality's boundary. |
275
+ | `multimodalpy.io` | `read_matrix()` and `read_graph()`, to read the files written. |
276
+ | `multimodalpy.analysis` | `isochrones()`, `shortest_path()` and the other network analyses. |
277
+
278
+ `download_network`, `find_area`, `read_matrix`, `read_graph`, `isochrones` and
279
+ `shortest_path` are also available from the package itself (`multimodalpy.find_area`). See the
190
280
  [API reference](https://multimodalpy.readthedocs.io/en/latest/api.html).
191
281
 
192
282
  ## How it works
@@ -223,4 +313,29 @@ details are in [DATA_SCHEMA.md](DATA_SCHEMA.md), and changes between versions in
223
313
 
224
314
  ## Citation
225
315
 
226
- If you use `multimodalpy` in your research, please cite it. Citation metadata is in [`CITATION.cff`](CITATION.cff); on GitHub, use the "Cite this repository" button in the sidebar to get a formatted citation (APA, BibTeX, etc.).
316
+ If you use `multimodalpy` in your research, please cite the software and state
317
+ the version you used. On GitHub, the "Cite this repository" button in the
318
+ sidebar gives a ready-made citation (APA, BibTeX) from
319
+ [`CITATION.cff`](CITATION.cff).
320
+
321
+ > Villalba Ortiz, A. (2026). *multimodalpy: Easy creation of multimodal
322
+ > transport networks from OpenStreetMap and GTFS data* (Version X.Y.Z)
323
+ > [Computer software]. https://doi.org/10.5281/zenodo.NNNNNNN
324
+
325
+ ```bibtex
326
+ @software{villalba_multimodalpy,
327
+ author = {Villalba Ortiz, Aida},
328
+ title = {multimodalpy: Easy creation of multimodal transport networks
329
+ from OpenStreetMap and GTFS data},
330
+ year = {2026},
331
+ version = {0.4.0},
332
+ doi = {10.5281/zenodo.NNNNNNN},
333
+ url = {https://github.com/aivilor/multimodalpy},
334
+ license = {MIT}
335
+ }
336
+ ```
337
+
338
+ Each release is archived on Zenodo with its own DOI; the DOI above is the one
339
+ for all versions. Use the version DOI listed on the
340
+ [Zenodo record](https://doi.org/10.5281/zenodo.NNNNNNN) when you need to cite
341
+ the exact release you ran.