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.
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/ARCHITECTURE.md +4 -2
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/CHANGELOG.md +38 -2
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/CITATION.cff +3 -2
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/DATA_SCHEMA.md +129 -1
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/PKG-INFO +80 -5
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/README.md +77 -3
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/api.md +1 -2
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/index.md +3 -1
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/pyproject.toml +3 -2
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/src/multimodalpy/__init__.py +14 -11
- multimodalpy-0.3.0/src/multimodalpy/_matrix.py +767 -0
- multimodalpy-0.2.0/src/multimodalpy/process_gtfs.py → multimodalpy-0.3.0/src/multimodalpy/_process_gtfs.py +3 -0
- multimodalpy-0.2.0/src/multimodalpy/process_osm.py → multimodalpy-0.3.0/src/multimodalpy/_process_osm.py +3 -1
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/src/multimodalpy/get_area.py +16 -14
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/src/multimodalpy/get_network.py +197 -14
- multimodalpy-0.3.0/src/multimodalpy/isochrones.py +512 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_get_network.py +151 -1
- multimodalpy-0.3.0/tests/test_isochrones.py +323 -0
- multimodalpy-0.3.0/tests/test_matrix.py +315 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_multipart_area.py +2 -1
- multimodalpy-0.3.0/tests/test_network_loading.py +216 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_output_format.py +3 -2
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_process_gtfs.py +2 -2
- multimodalpy-0.3.0/tests/test_public_api.py +61 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_topology_crs.py +1 -1
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.github/workflows/docs.yml +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.github/workflows/publish.yml +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.github/workflows/tests.yml +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.gitignore +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/.readthedocs.yaml +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/CODE_OF_CONDUCT.md +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/CONTRIBUTING.md +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/LICENSE +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/_static/.gitkeep +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/conf.py +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/docs/requirements.txt +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/conftest.py +0 -0
- {multimodalpy-0.2.0 → multimodalpy-0.3.0}/tests/test_get_area_boundaries.py +0 -0
- {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
|
-
│ ├──
|
|
26
|
-
│
|
|
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.
|
|
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.
|
|
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
|
-
|
|
14
|
-
|
|
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.
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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,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
|
|
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.
|
|
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
|
-
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
- get_area :
|
|
13
|
-
-
|
|
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,
|
|
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
|
-
"
|
|
44
|
-
"process_gtfs",
|
|
47
|
+
"isochrones",
|
|
45
48
|
"__version__",
|
|
46
|
-
]
|
|
49
|
+
]
|