multimodalpy 0.2.0__tar.gz → 0.3.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 (39) hide show
  1. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/ARCHITECTURE.md +4 -2
  2. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/CHANGELOG.md +38 -2
  3. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/CITATION.cff +3 -2
  4. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/DATA_SCHEMA.md +129 -1
  5. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/PKG-INFO +80 -5
  6. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/README.md +77 -3
  7. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/api.md +1 -2
  8. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/index.md +3 -1
  9. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/pyproject.toml +3 -2
  10. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/src/multimodalpy/__init__.py +14 -11
  11. multimodalpy-0.3.0/src/multimodalpy/_matrix.py +767 -0
  12. multimodalpy-0.2.0/src/multimodalpy/process_gtfs.py → multimodalpy-0.3.0/src/multimodalpy/_process_gtfs.py +3 -0
  13. multimodalpy-0.2.0/src/multimodalpy/process_osm.py → multimodalpy-0.3.0/src/multimodalpy/_process_osm.py +3 -1
  14. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/src/multimodalpy/get_area.py +16 -14
  15. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/src/multimodalpy/get_network.py +197 -14
  16. multimodalpy-0.3.0/src/multimodalpy/isochrones.py +512 -0
  17. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_get_network.py +151 -1
  18. multimodalpy-0.3.0/tests/test_isochrones.py +323 -0
  19. multimodalpy-0.3.0/tests/test_matrix.py +315 -0
  20. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_multipart_area.py +2 -1
  21. multimodalpy-0.3.0/tests/test_network_loading.py +216 -0
  22. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_output_format.py +3 -2
  23. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_process_gtfs.py +2 -2
  24. multimodalpy-0.3.0/tests/test_public_api.py +61 -0
  25. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_topology_crs.py +1 -1
  26. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.github/workflows/docs.yml +0 -0
  27. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.github/workflows/publish.yml +0 -0
  28. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.github/workflows/tests.yml +0 -0
  29. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.gitignore +0 -0
  30. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.readthedocs.yaml +0 -0
  31. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/CODE_OF_CONDUCT.md +0 -0
  32. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/CONTRIBUTING.md +0 -0
  33. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/LICENSE +0 -0
  34. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/_static/.gitkeep +0 -0
  35. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/conf.py +0 -0
  36. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/requirements.txt +0 -0
  37. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/conftest.py +0 -0
  38. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_get_area_boundaries.py +0 -0
  39. {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_get_area_cities.py +0 -0
@@ -22,8 +22,10 @@ multimodalpy/
22
22
  │ ├── get_area.py # study-area boundary resolution (pooch-fetched
23
23
  │ │ # default boundaries; see DATA_SCHEMA.md)
24
24
  │ ├── get_network.py # main() entry point: OSM + GTFS -> network
25
- │ ├── process_osm.py # OSM download/normalization per mode
26
- │ └── process_gtfs.py # GTFS download/normalization via NAP
25
+ │ ├── isochrones.py # public: isochrones on walking/bike/driving
26
+ │ ├── _matrix.py # private: CSR matrix export (matrix.npz)
27
+ │ ├── _process_osm.py # private: OSM normalization per mode
28
+ │ └── _process_gtfs.py # private: GTFS normalization
27
29
  │
28
30
  ├── tests/
29
31
  │ ├── test_get_area_cities.py
@@ -5,6 +5,42 @@ 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.3.0] - 2026-10-30
9
+
10
+ ### Added
11
+ - New output format `matrix` (#63): `output_file_type="matrix"` (or
12
+ `--output-file-type matrix`) writes each network as one `matrix.npz`, a
13
+ directed sparse adjacency matrix in CSR form for shortest-path calculations.
14
+ Walking, bike and driving matrices carry `tts` and `length`; bus and train
15
+ matrices carry the 18 travel-time columns of the GTFS edge layer. Parallel
16
+ edges keep the minimum of each weight, and GTFS periods without service are
17
+ `inf`. The file opens with `scipy.sparse.load_npz`. The layout is described
18
+ in the "Matrix" section of `DATA_SCHEMA.md`.
19
+ - `multimodalpy.read_matrix()` reads a `matrix.npz` (or its folder) and returns
20
+ the matrix of one weight as a `scipy.sparse.csr_array`, the node table and
21
+ the metadata.
22
+ - `scipy` is now a required dependency.
23
+ - New public module `multimodalpy.isochrones` (#64). `isochrones()` computes
24
+ the area reachable from one or more origins (node ids or coordinates) within
25
+ each cutoff, in minutes (`weight="tts"`) or metres (`weight="length"`), on a
26
+ walking, bike or driving network. It reads the network in any output format
27
+ (output folder, network folder, `matrix.npz`, `graph.json`, GeoPackage,
28
+ GeoJSON, Shapefile, or the result of `read_matrix` / `read_graph_json`) and
29
+ returns a GeoDataFrame with one polygon per origin and cutoff, nested and in
30
+ the network's CRS. `method="edges"` (default) buffers the streets reached,
31
+ including the reached part of edges crossing the cutoff; `method="hull"`
32
+ draws a concave hull. Bus and train isochrones raise `NotImplementedError`
33
+ until the multimodal network is available.
34
+ - `shapely>=2.0` is now required explicitly (for `shapely.concave_hull`).
35
+
36
+ ### Changed
37
+ - **Breaking:** `process_osm` and `process_gtfs` are now private modules
38
+ (`_process_osm`, `_process_gtfs`) and are no longer part of the public API:
39
+ `multimodalpy.process_osm` and `multimodalpy.process_gtfs` no longer exist,
40
+ and both modules are gone from the API reference. The public API is
41
+ `get_network`, `get_area` and the names in `multimodalpy.__all__`. Code that
42
+ imported them directly should use `get_network.main()` or the `get_area`
43
+ download functions, which return the standardized layers.
8
44
 
9
45
  ## [0.2.0] - 2026-10-29
10
46
 
@@ -35,7 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
35
71
  - `.env` and `.venv/` are in `.gitignore`, so a NAP key in `.env` is not
36
72
  committed by accident (#62).
37
73
 
38
- [0.2.0]: https://github.com/aivilor/multimodalpy/compare/v0.1.5...v0.2.0
74
+ [0.3.0]: https://github.com/aivilor/multimodalpy/compare/v0.2.0...v0.3.0
39
75
 
40
76
  ## [0.1.5] - 2026-10-14
41
77
 
@@ -177,7 +213,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
177
213
  conflict resolution.
178
214
 
179
215
 
180
- [Unreleased]: https://github.com/aivilor/multimodalpy/compare/v0.1.3...HEAD
216
+ [Unreleased]: https://github.com/aivilor/multimodalpy/compare/v0.3.0...HEAD
181
217
  [0.1.3]: https://github.com/aivilor/multimodalpy/compare/v0.1.2...v0.1.3
182
218
  [0.1.1]: https://github.com/aivilor/multimodalpy/compare/v0.1.0...v0.1.1
183
219
  [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.3.0
15
+ date-released: 2026-10-30
15
16
  url: "https://github.com/aivilor/multimodalpy"
16
17
  repository-code: "https://github.com/aivilor/multimodalpy"
17
18
  license: MIT
@@ -22,7 +22,8 @@ Shapefile is five files: `.shp`, `.shx`, `.dbf`, `.prj`, `.cpg`). GeoPackage is
22
22
  single file at the root holding every layer, so it is not split into folders.
23
23
  `schedule.csv` is only written with `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
 
@@ -336,6 +337,130 @@ 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 `output_file_type="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 `main()`. |
429
+ | `crs` | CRS of `node_x` / `node_y`, the `crs` passed to `main()`. |
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 `main()`, 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
+ `multimodalpy.isochrones.isochrones` works on this matrix, and turns every other
462
+ format into it first.
463
+
339
464
  ---
340
465
 
341
466
  ## From municipality to data
@@ -396,6 +521,9 @@ directly as the region id.
396
521
  - `lanes` is still exported as text and can hold `;`-joined values.
397
522
  - In the **networkx** export, OSM node ids are integers and GTFS node ids are
398
523
  text, so the graphs cannot be joined on node id as they are.
524
+ - In the **matrix** export, the routes between the same two stops are merged
525
+ into one GTFS edge with the fastest time, and waiting times, frequencies and
526
+ transfers are not modelled: a GTFS matrix gives in-vehicle travel times only.
399
527
 
400
528
  ## Abbreviations
401
529
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: multimodalpy
3
- Version: 0.2.0
3
+ Version: 0.3.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,9 @@ 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.
54
57
 
55
58
  > **Scope.** Only municipalities in Spain are supported: peninsular Spain, the
56
59
  > Balearic Islands, Ceuta and Melilla. The Canary Islands are not in the default
@@ -169,12 +172,59 @@ output/
169
172
  Every column, the travel-time model and how each value is computed are described
170
173
  in [DATA_SCHEMA.md](DATA_SCHEMA.md).
171
174
 
175
+ ### Shortest paths: the matrix format
176
+
177
+ `output_file_type="matrix"` writes each network as one `matrix.npz`: a directed
178
+ sparse adjacency matrix (CSR) with one vector per weight (`tts` and `length`
179
+ for streets, the travel-time statistics for bus and train). Read it with
180
+ `read_matrix` and pass it to scipy's shortest-path functions:
181
+
182
+ ```python
183
+ from scipy.sparse.csgraph import dijkstra
184
+
185
+ from multimodalpy import read_matrix
186
+
187
+ data = read_matrix("output/walking")
188
+ origin = data.nodes.index[data.nodes["node_id"] == 1234][0]
189
+ seconds = dijkstra(data.matrix, indices=origin, limit=600)
190
+ ```
191
+
192
+ For bus and train the matrix holds in-vehicle times only: waiting and transfers
193
+ are not modelled. See the
194
+ [Matrix section of DATA_SCHEMA.md](DATA_SCHEMA.md#matrix-matrixnpz).
195
+
196
+ ### Isochrones
197
+
198
+ `isochrones` draws the area reachable from one or more origins within each
199
+ travel time, on a walking, bike or driving network:
200
+
201
+ ```python
202
+ from multimodalpy.isochrones import isochrones
203
+
204
+ areas = isochrones(
205
+ "output", # output folder of main()
206
+ origins=(-0.3763, 39.4699), # (x, y) in the network's CRS, or a node_id
207
+ cutoffs=[5, 10, 15], # minutes
208
+ mode="walking",
209
+ )
210
+ areas.to_file("isochrones.geojson")
211
+ ```
212
+
213
+ It reads the network in any output format (`matrix.npz` is the fastest) and
214
+ returns one polygon per origin and cutoff, in the network's CRS. By default
215
+ (`method="edges"`) the area is a band of `buffer_distance` metres (25) along the
216
+ streets reached, so it follows the street network; `method="hull"` draws a
217
+ concave hull around them instead, faster when most of the network is reached.
218
+ With `weight="length"` the cutoffs are metres. Coordinates are snapped to the
219
+ nearest node within `max_snap_distance` metres (250). Bus and train isochrones
220
+ will come with the multimodal network.
221
+
172
222
  ## Main options
173
223
 
174
224
  | Option | Default | What it does |
175
225
  |---|---|---|
176
226
  | `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. |
227
+ | `output_file_type` | `"geojson"` | `geojson`, `shapefile`, `geopackage`, `networkx`, `matrix`, or a list to write several at once. |
178
228
  | `crs` | `"EPSG:4326"` | CRS of every output layer, e.g. `"EPSG:25830"` for metres in Spain. |
179
229
  | `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
230
  | `area_code` | `None` | The municipality's 5-digit INE code (`"46250"` for València) or its full INSPIRE `NATCODE`. |
@@ -223,4 +273,29 @@ details are in [DATA_SCHEMA.md](DATA_SCHEMA.md), and changes between versions in
223
273
 
224
274
  ## Citation
225
275
 
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.).
276
+ If you use `multimodalpy` in your research, please cite the software and state
277
+ the version you used. On GitHub, the "Cite this repository" button in the
278
+ sidebar gives a ready-made citation (APA, BibTeX) from
279
+ [`CITATION.cff`](CITATION.cff).
280
+
281
+ > Villalba Ortiz, A. (2026). *multimodalpy: Easy creation of multimodal
282
+ > transport networks from OpenStreetMap and GTFS data* (Version X.Y.Z)
283
+ > [Computer software]. https://doi.org/10.5281/zenodo.NNNNNNN
284
+
285
+ ```bibtex
286
+ @software{villalba_multimodalpy,
287
+ author = {Villalba Ortiz, Aida},
288
+ title = {multimodalpy: Easy creation of multimodal transport networks
289
+ from OpenStreetMap and GTFS data},
290
+ year = {2026},
291
+ version = {0.3.0},
292
+ doi = {10.5281/zenodo.NNNNNNN},
293
+ url = {https://github.com/aivilor/multimodalpy},
294
+ license = {MIT}
295
+ }
296
+ ```
297
+
298
+ Each release is archived on Zenodo with its own DOI; the DOI above is the one
299
+ for all versions. Use the version DOI listed on the
300
+ [Zenodo record](https://doi.org/10.5281/zenodo.NNNNNNN) when you need to cite
301
+ the exact release you ran.
@@ -18,7 +18,9 @@ standardizes its transport networks, one layer per mode:
18
18
  edges with travel times and trip counts by period of the day.
19
19
 
20
20
  All modes share the same column names, and the layers are written as GeoJSON,
21
- Shapefile, GeoPackage or NetworkX graphs, ready for GIS or network analysis.
21
+ Shapefile, GeoPackage, NetworkX graphs or sparse matrices, ready for GIS or
22
+ network analysis. On the walking, cycling and driving networks, `multimodalpy`
23
+ also computes isochrones: the area reachable from a point within a travel time.
22
24
 
23
25
  > **Scope.** Only municipalities in Spain are supported: peninsular Spain, the
24
26
  > Balearic Islands, Ceuta and Melilla. The Canary Islands are not in the default
@@ -137,12 +139,59 @@ output/
137
139
  Every column, the travel-time model and how each value is computed are described
138
140
  in [DATA_SCHEMA.md](DATA_SCHEMA.md).
139
141
 
142
+ ### Shortest paths: the matrix format
143
+
144
+ `output_file_type="matrix"` writes each network as one `matrix.npz`: a directed
145
+ sparse adjacency matrix (CSR) with one vector per weight (`tts` and `length`
146
+ for streets, the travel-time statistics for bus and train). Read it with
147
+ `read_matrix` and pass it to scipy's shortest-path functions:
148
+
149
+ ```python
150
+ from scipy.sparse.csgraph import dijkstra
151
+
152
+ from multimodalpy import read_matrix
153
+
154
+ data = read_matrix("output/walking")
155
+ origin = data.nodes.index[data.nodes["node_id"] == 1234][0]
156
+ seconds = dijkstra(data.matrix, indices=origin, limit=600)
157
+ ```
158
+
159
+ For bus and train the matrix holds in-vehicle times only: waiting and transfers
160
+ are not modelled. See the
161
+ [Matrix section of DATA_SCHEMA.md](DATA_SCHEMA.md#matrix-matrixnpz).
162
+
163
+ ### Isochrones
164
+
165
+ `isochrones` draws the area reachable from one or more origins within each
166
+ travel time, on a walking, bike or driving network:
167
+
168
+ ```python
169
+ from multimodalpy.isochrones import isochrones
170
+
171
+ areas = isochrones(
172
+ "output", # output folder of main()
173
+ origins=(-0.3763, 39.4699), # (x, y) in the network's CRS, or a node_id
174
+ cutoffs=[5, 10, 15], # minutes
175
+ mode="walking",
176
+ )
177
+ areas.to_file("isochrones.geojson")
178
+ ```
179
+
180
+ It reads the network in any output format (`matrix.npz` is the fastest) and
181
+ returns one polygon per origin and cutoff, in the network's CRS. By default
182
+ (`method="edges"`) the area is a band of `buffer_distance` metres (25) along the
183
+ streets reached, so it follows the street network; `method="hull"` draws a
184
+ concave hull around them instead, faster when most of the network is reached.
185
+ With `weight="length"` the cutoffs are metres. Coordinates are snapped to the
186
+ nearest node within `max_snap_distance` metres (250). Bus and train isochrones
187
+ will come with the multimodal network.
188
+
140
189
  ## Main options
141
190
 
142
191
  | Option | Default | What it does |
143
192
  |---|---|---|
144
193
  | `modes` | `["walking"]` | Any of `walking`, `bike`, `driving`, `bus`, `train`. Spanish synonyms work too (`caminable`, `bicicleta`, `coche`). |
145
- | `output_file_type` | `"geojson"` | `geojson`, `shapefile`, `geopackage`, `networkx`, or a list to write several at once. |
194
+ | `output_file_type` | `"geojson"` | `geojson`, `shapefile`, `geopackage`, `networkx`, `matrix`, or a list to write several at once. |
146
195
  | `crs` | `"EPSG:4326"` | CRS of every output layer, e.g. `"EPSG:25830"` for metres in Spain. |
147
196
  | `province` | `None` | Province name or INE code, to choose between towns that share a name (e.g. `"Castejón"` exists in Cuenca and Navarra). |
148
197
  | `area_code` | `None` | The municipality's 5-digit INE code (`"46250"` for València) or its full INSPIRE `NATCODE`. |
@@ -191,4 +240,29 @@ details are in [DATA_SCHEMA.md](DATA_SCHEMA.md), and changes between versions in
191
240
 
192
241
  ## Citation
193
242
 
194
- 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.).
243
+ If you use `multimodalpy` in your research, please cite the software and state
244
+ the version you used. On GitHub, the "Cite this repository" button in the
245
+ sidebar gives a ready-made citation (APA, BibTeX) from
246
+ [`CITATION.cff`](CITATION.cff).
247
+
248
+ > Villalba Ortiz, A. (2026). *multimodalpy: Easy creation of multimodal
249
+ > transport networks from OpenStreetMap and GTFS data* (Version X.Y.Z)
250
+ > [Computer software]. https://doi.org/10.5281/zenodo.NNNNNNN
251
+
252
+ ```bibtex
253
+ @software{villalba_multimodalpy,
254
+ author = {Villalba Ortiz, Aida},
255
+ title = {multimodalpy: Easy creation of multimodal transport networks
256
+ from OpenStreetMap and GTFS data},
257
+ year = {2026},
258
+ version = {0.3.0},
259
+ doi = {10.5281/zenodo.NNNNNNN},
260
+ url = {https://github.com/aivilor/multimodalpy},
261
+ license = {MIT}
262
+ }
263
+ ```
264
+
265
+ Each release is archived on Zenodo with its own DOI; the DOI above is the one
266
+ for all versions. Use the version DOI listed on the
267
+ [Zenodo record](https://doi.org/10.5281/zenodo.NNNNNNN) when you need to cite
268
+ the exact release you ran.
@@ -7,6 +7,5 @@
7
7
 
8
8
  multimodalpy.get_network
9
9
  multimodalpy.get_area
10
- multimodalpy.process_osm
11
- multimodalpy.process_gtfs
10
+ multimodalpy.isochrones
12
11
  ```
@@ -7,7 +7,9 @@ Give `multimodalpy` the name of a municipality in Spain and it downloads and
7
7
  standardizes its transport networks, one layer per mode: walking, cycling and
8
8
  driving from OpenStreetMap, and bus and train from the official GTFS feeds of
9
9
  Spain's National Access Point (NAP). The layers share the same column names and
10
- are written as GeoJSON, Shapefile, GeoPackage or NetworkX graphs.
10
+ are written as GeoJSON, Shapefile, GeoPackage, NetworkX graphs or sparse
11
+ matrices for shortest-path calculations. On the walking, cycling and driving
12
+ networks it also computes isochrones (`multimodalpy.isochrones`).
11
13
 
12
14
  Only municipalities in Spain are supported (not the Canary Islands with the
13
15
  default boundaries file). Each mode is exported as its own network; linking them
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "multimodalpy"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "Easy creation of multimodal transport networks"
9
9
  readme = "README.md"
10
10
 
@@ -38,8 +38,9 @@ dependencies = [
38
38
  "osmnx",
39
39
  "pandas",
40
40
  "requests",
41
- "shapely",
41
+ "shapely>=2.0",
42
42
  "pooch>=1.8",
43
+ "scipy>=1.11",
43
44
  ]
44
45
 
45
46
 
@@ -6,11 +6,15 @@ Basic usage:
6
6
 
7
7
  main("Valencia", modes=["walking", "bike"], output_path="output")
8
8
 
9
- Modules:
10
- - process_osm : OSM data standardization (building intersections).
11
- - process_gtfs : GTFS data standardization + bus/train cleanup.
12
- - get_area : downloads from OSM and GTFS APIs.
13
- - get_network : local download per the user's settings (main()).
9
+ Public modules:
10
+ - get_network : main() entry point; downloads, standardizes and writes
11
+ the networks per the user's settings.
12
+ - get_area : study-area boundary lookup and OSM / GTFS downloads.
13
+ - isochrones : area reachable from a point within a travel time
14
+ (``from multimodalpy.isochrones import isochrones``).
15
+
16
+ OSM and GTFS standardization happen in private modules (``_process_osm``,
17
+ ``_process_gtfs``) that are not part of the public API.
14
18
  """
15
19
 
16
20
  from __future__ import annotations
@@ -18,10 +22,9 @@ from __future__ import annotations
18
22
  import logging
19
23
  from importlib.metadata import PackageNotFoundError, version
20
24
 
21
- from . import get_area, get_network, process_gtfs, process_osm
25
+ from . import get_area, get_network, isochrones
22
26
  from .get_area import find_area_boundary
23
- from .get_network import main, read_graph_json
24
-
27
+ from .get_network import main, read_graph_json, read_matrix
25
28
 
26
29
  # A library shouldn't write to the terminal on its own: without this
27
30
  # handler, Python would print WARNING-level alerts to stderr even if the
@@ -37,10 +40,10 @@ except PackageNotFoundError:
37
40
  __all__ = [
38
41
  "main",
39
42
  "read_graph_json",
43
+ "read_matrix",
40
44
  "find_area_boundary",
41
45
  "get_network",
42
46
  "get_area",
43
- "process_osm",
44
- "process_gtfs",
47
+ "isochrones",
45
48
  "__version__",
46
- ]
49
+ ]