bikelts 0.1.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 (46) hide show
  1. bikelts-0.1.0/CHANGELOG.md +35 -0
  2. bikelts-0.1.0/CITATION.cff +48 -0
  3. bikelts-0.1.0/LICENSE +21 -0
  4. bikelts-0.1.0/MANIFEST.in +9 -0
  5. bikelts-0.1.0/PKG-INFO +284 -0
  6. bikelts-0.1.0/README.md +241 -0
  7. bikelts-0.1.0/examples/quickstart.py +50 -0
  8. bikelts-0.1.0/examples/sample_area.osm +89 -0
  9. bikelts-0.1.0/examples/segments.csv +7 -0
  10. bikelts-0.1.0/pyproject.toml +129 -0
  11. bikelts-0.1.0/setup.cfg +4 -0
  12. bikelts-0.1.0/src/bikelts/__init__.py +102 -0
  13. bikelts-0.1.0/src/bikelts/__main__.py +7 -0
  14. bikelts-0.1.0/src/bikelts/classify.py +210 -0
  15. bikelts-0.1.0/src/bikelts/cli.py +233 -0
  16. bikelts-0.1.0/src/bikelts/defaults.py +245 -0
  17. bikelts-0.1.0/src/bikelts/intersections.py +275 -0
  18. bikelts-0.1.0/src/bikelts/model.py +154 -0
  19. bikelts-0.1.0/src/bikelts/network.py +691 -0
  20. bikelts-0.1.0/src/bikelts/osm.py +210 -0
  21. bikelts-0.1.0/src/bikelts/overpass.py +63 -0
  22. bikelts-0.1.0/src/bikelts/params.py +88 -0
  23. bikelts-0.1.0/src/bikelts/py.typed +0 -0
  24. bikelts-0.1.0/src/bikelts/rules/__init__.py +49 -0
  25. bikelts-0.1.0/src/bikelts/rules/base.py +125 -0
  26. bikelts-0.1.0/src/bikelts/rules/bikeottawa.py +331 -0
  27. bikelts-0.1.0/src/bikelts/rules/furth2017.py +262 -0
  28. bikelts-0.1.0/src/bikelts/rules/mekuria2012.py +173 -0
  29. bikelts-0.1.0/src/bikelts/tags.py +806 -0
  30. bikelts-0.1.0/src/bikelts/units.py +152 -0
  31. bikelts-0.1.0/src/bikelts.egg-info/PKG-INFO +284 -0
  32. bikelts-0.1.0/src/bikelts.egg-info/SOURCES.txt +44 -0
  33. bikelts-0.1.0/src/bikelts.egg-info/dependency_links.txt +1 -0
  34. bikelts-0.1.0/src/bikelts.egg-info/entry_points.txt +2 -0
  35. bikelts-0.1.0/src/bikelts.egg-info/requires.txt +18 -0
  36. bikelts-0.1.0/src/bikelts.egg-info/top_level.txt +1 -0
  37. bikelts-0.1.0/tests/conftest.py +123 -0
  38. bikelts-0.1.0/tests/test_bikeottawa.py +211 -0
  39. bikelts-0.1.0/tests/test_furth2017_tables.py +223 -0
  40. bikelts-0.1.0/tests/test_intersections.py +166 -0
  41. bikelts-0.1.0/tests/test_mekuria2012_tables.py +143 -0
  42. bikelts-0.1.0/tests/test_network.py +307 -0
  43. bikelts-0.1.0/tests/test_osm_io.py +203 -0
  44. bikelts-0.1.0/tests/test_records_cli.py +263 -0
  45. bikelts-0.1.0/tests/test_tags.py +464 -0
  46. bikelts-0.1.0/tests/test_units_defaults.py +193 -0
@@ -0,0 +1,35 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## [Unreleased]
6
+
7
+ ## [0.1.0] - 2026-11-09
8
+ ### Added
9
+ - **Rulesets** (`bikelts.rules`), selectable by name:
10
+ - `mekuria2012` - Mekuria, Furth & Nixon (2012), MTI Report 11-19: bike lanes alongside
11
+ parking (Table 2), not alongside parking (Table 3) and mixed traffic (Table 4), with
12
+ weakest-link aggregation and the footnotes of Tables 2 and 4.
13
+ - `furth2017` - Furth's LTS criteria for road segments v2.0 (June 2017): ADT-sensitive
14
+ mixed-traffic table, bike lanes/shoulders by width and speed, bike lanes alongside parking
15
+ by reach; non-qualifying or frequently blocked lanes fall back to mixed traffic.
16
+ - `bikeottawa` - port of the Bike Ottawa `stressmodel.js` v1.0.1 OSM rules (p/s/b/c/m rule
17
+ identifiers preserved).
18
+ - **Intersections** (`bikelts.intersections`): right-turn-lane approaches (Table 5),
19
+ unsignalized crossings with and without an island (Table 6a/6b), and detection of crossings of
20
+ dominant streets in OSM data (signals and islands from node tags).
21
+ - **OSM tag parsing** (`bikelts.tags`): `highway`, `bicycle`/`access`, `oneway`(`:bicycle`),
22
+ `cycleway` / `cycleway:left|right|both` incl. `lane`, `track`, `shared_lane`, `opposite*`,
23
+ `:buffer`, `:separation`, `:width`, `:oneway`, `sidewalk:*:bicycle`, shoulders, `maxspeed`
24
+ with units, implicit `XX:urban`-style values and zones, `lanes`(`:forward|backward|bus`),
25
+ `lane_markings`, both parking schemes, `surface`. Directional results (`lts_forward`,
26
+ `lts_backward`) and a per-segment assumption log.
27
+ - **Defaults** (`bikelts.defaults`): general speed limits for 35 countries, driving side, and
28
+ planning-level lane and ADT defaults by road class.
29
+ - **Tabular input** (`classify_record`, CSV in the CLI).
30
+ - **Network analysis** (`bikelts.network`): share of network by LTS, low-stress islands,
31
+ connectivity metrics, pure-Python Dijkstra with LTS caps and crossing restrictions,
32
+ origin-destination reachability and detour ratios.
33
+ - **I/O**: OSM XML, Overpass JSON and GeoJSON readers (offline), GeoJSON/CSV writers, optional
34
+ Overpass download with timeouts, optional geopandas and networkx converters.
35
+ - **CLI** `bikelts classify | islands | stats | reach | download | methods`.
@@ -0,0 +1,48 @@
1
+ cff-version: 1.2.0
2
+ message: "If you use this software, please cite it as below, together with the LTS method papers it implements."
3
+ authors:
4
+ - family-names: "Eminoğlu"
5
+ given-names: "Yusuf"
6
+ email: "yusufeminoglu@gmail.com"
7
+ orcid: "https://orcid.org/0009-0005-6000-2934"
8
+ title: "bikelts: Bicycle Level of Traffic Stress for Python"
9
+ version: "0.1.0"
10
+ date-released: "2026-11-09"
11
+ license: "MIT"
12
+ repository-code: "https://github.com/YusufEminoglu/bikelts_sdk"
13
+ url: "https://pypi.org/project/bikelts/"
14
+ abstract: "Level of Traffic Stress (LTS 1-4) classification of street segments and intersections for cycling from OpenStreetMap tags or tabular attributes, with selectable rulesets (Mekuria, Furth & Nixon 2012; Furth 2017; Bike Ottawa OSM rules), per-segment assumption logging and low-stress network connectivity analysis."
15
+ keywords:
16
+ - cycling
17
+ - level of traffic stress
18
+ - active transportation
19
+ - OpenStreetMap
20
+ - network connectivity
21
+ references:
22
+ - type: report
23
+ title: "Low-Stress Bicycling and Network Connectivity"
24
+ authors:
25
+ - family-names: "Mekuria"
26
+ given-names: "Maaza C."
27
+ - family-names: "Furth"
28
+ given-names: "Peter G."
29
+ - family-names: "Nixon"
30
+ given-names: "Hilary"
31
+ institution:
32
+ name: "Mineta Transportation Institute"
33
+ number: "11-19"
34
+ year: 2012
35
+ - type: generic
36
+ title: "Level of Traffic Stress Criteria for Road Segments, version 2.0"
37
+ authors:
38
+ - family-names: "Furth"
39
+ given-names: "Peter G."
40
+ institution:
41
+ name: "Northeastern University"
42
+ year: 2017
43
+ - type: software
44
+ title: "stressmodel: Level of Traffic Stress model for OpenStreetMap"
45
+ authors:
46
+ - name: "Bike Ottawa"
47
+ repository-code: "https://github.com/BikeOttawa/stressmodel"
48
+ version: "1.0.1"
bikelts-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Yusuf Eminoğlu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,9 @@
1
+ include LICENSE
2
+ include README.md
3
+ include CHANGELOG.md
4
+ include CITATION.cff
5
+ include pyproject.toml
6
+ include src/bikelts/py.typed
7
+ recursive-include src/bikelts *.py
8
+ recursive-include tests *.py
9
+ recursive-include examples *.py *.osm *.csv
bikelts-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,284 @@
1
+ Metadata-Version: 2.4
2
+ Name: bikelts
3
+ Version: 0.1.0
4
+ Summary: Bicycle Level of Traffic Stress (LTS 1-4) from OpenStreetMap tags or tables: Mekuria 2012, Furth 2017 and Bike Ottawa rulesets, assumption logging and low-stress connectivity analysis.
5
+ Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/YusufEminoglu/bikelts_sdk
8
+ Project-URL: Repository, https://github.com/YusufEminoglu/bikelts_sdk
9
+ Project-URL: Issues, https://github.com/YusufEminoglu/bikelts_sdk/issues
10
+ Project-URL: Changelog, https://github.com/YusufEminoglu/bikelts_sdk/blob/main/CHANGELOG.md
11
+ Keywords: cycling,bicycle,level-of-traffic-stress,lts,active-transportation,bike-network,low-stress-connectivity,openstreetmap,osm,transportation-planning,gis,accessibility
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Operating System :: OS Independent
21
+ Classifier: Topic :: Scientific/Engineering :: GIS
22
+ Classifier: Intended Audience :: Science/Research
23
+ Classifier: Intended Audience :: Developers
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.9
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Provides-Extra: geo
29
+ Requires-Dist: geopandas>=0.12.0; extra == "geo"
30
+ Requires-Dist: shapely>=2.0.0; extra == "geo"
31
+ Provides-Extra: graph
32
+ Requires-Dist: networkx>=2.8.0; extra == "graph"
33
+ Provides-Extra: all
34
+ Requires-Dist: geopandas>=0.12.0; extra == "all"
35
+ Requires-Dist: shapely>=2.0.0; extra == "all"
36
+ Requires-Dist: networkx>=2.8.0; extra == "all"
37
+ Provides-Extra: dev
38
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
39
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
40
+ Requires-Dist: ruff>=0.1.0; extra == "dev"
41
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
42
+ Dynamic: license-file
43
+
44
+ # bikelts
45
+
46
+ **Bicycle Level of Traffic Stress (LTS 1-4) for Python.** `bikelts` classifies street
47
+ segments and intersections for cycling from OpenStreetMap tags or from your own
48
+ tabular attributes, records *why* each segment got its score and *which inputs were
49
+ assumed*, and analyses the connectivity of the resulting low-stress network.
50
+
51
+ It is written for active-transportation planners and researchers who need a transparent,
52
+ reproducible LTS map rather than a black box.
53
+
54
+ - Three selectable, documented rulesets: **Mekuria, Furth & Nixon (2012)**,
55
+ **Furth (2017) v2.0**, and the **Bike Ottawa** OSM tag rules.
56
+ - Directional results (`lts_forward`, `lts_backward`) with contraflow handling.
57
+ - Per-segment reasons and an assumption log, e.g.
58
+ `maxspeed missing -> assumed 50 km/h from highway=residential urban default for country DE`.
59
+ - Intersection criteria: right-turn-lane approaches and unsignalized crossings.
60
+ - Network analysis in pure Python: LTS shares, low-stress islands, connectivity metrics,
61
+ Dijkstra with an LTS cap, origin-destination reachability and detour ratios.
62
+ - Offline readers for OSM XML, Overpass JSON and GeoJSON; optional Overpass download.
63
+ - No required dependencies; optional `geopandas` and `networkx` converters.
64
+
65
+ ## Installation
66
+
67
+ ```bash
68
+ pip install bikelts # core, no dependencies
69
+ pip install "bikelts[geo]" # + geopandas/shapely (to_geodataframe)
70
+ pip install "bikelts[graph]" # + networkx (to_networkx)
71
+ pip install "bikelts[all]"
72
+ ```
73
+
74
+ Python 3.9 or newer.
75
+
76
+ ## Quick start
77
+
78
+ ### Command line
79
+
80
+ ```bash
81
+ # Optional: fetch highways for a bounding box (south west north east) from Overpass
82
+ bikelts download --bbox 41.000 29.000 41.010 29.015 -o area.json --timeout 60
83
+
84
+ # Classify (OSM XML .osm, Overpass .json or GeoJSON) and write GeoJSON with LTS + reasons
85
+ bikelts classify area.osm -o lts.geojson --method furth2017 --country DE --intersections
86
+
87
+ # Low-stress islands, LTS shares and OD reachability
88
+ bikelts islands lts.geojson --max-lts 2 -o islands.geojson
89
+ bikelts stats lts.geojson --max-lts 2
90
+ bikelts reach lts.geojson --max-lts 2 --pairs 500 --max-detour 1.25
91
+
92
+ # Tabular input: CSV in, CSV out (columns listed below)
93
+ bikelts classify segments.csv -o segments_lts.csv --method mekuria2012
94
+
95
+ bikelts methods # list rulesets with their sources
96
+ ```
97
+
98
+ Every analysis command accepts `--json` for machine-readable output.
99
+
100
+ ### Python
101
+
102
+ ```python
103
+ from bikelts import LTSParameters, classify_tags
104
+
105
+ params = LTSParameters(country="DE")
106
+ r = classify_tags(
107
+ {"highway": "secondary", "maxspeed": "50", "cycleway:right": "lane", "parking:right": "lane"},
108
+ method="furth2017",
109
+ params=params,
110
+ )
111
+ r.lts_forward, r.lts_backward # (2, 3)
112
+ r.reasons
113
+ # ['forward: bike lane alongside parking: 1 lane per direction, reach 12-14 ft (reach 13 ft), 30 mph -> LTS 2',
114
+ # 'backward: mixed traffic, 1 thru lane per direction, ADT 3000+, 30 mph -> LTS 3']
115
+ r.assumptions
116
+ # ['ADT missing -> assumed 9000 veh/day from highway=secondary default',
117
+ # 'lanes missing -> assumed 2 from highway=secondary two-way default', ...]
118
+ ```
119
+
120
+ A whole extract and its network:
121
+
122
+ ```python
123
+ from bikelts import (LTSNetwork, LTSParameters, classify_osm, connectivity_metrics,
124
+ detect_crossings, low_stress_islands, od_reachability,
125
+ random_od_pairs, read_osm, to_geojson, write_geojson)
126
+
127
+ params = LTSParameters(country="DE")
128
+ data = read_osm("area.osm") # .osm, Overpass .json or .geojson
129
+ ways = classify_osm(data, "furth2017", params)
130
+ crossings = detect_crossings(data, ways, params)
131
+ write_geojson("lts.geojson", to_geojson(ways, crossings, data))
132
+
133
+ net = LTSNetwork.from_classified(ways, crossings)
134
+ islands = low_stress_islands(net, max_lts=2)
135
+ metrics = connectivity_metrics(net, max_lts=2)
136
+ results, summary = od_reachability(net, random_od_pairs(net, 500, seed=1), max_lts=2)
137
+ summary["low_stress_connected_share"] # share of OD pairs connected at LTS <= 2
138
+ ```
139
+
140
+ Tabular records (dicts or CSV rows) use `classify_record` / `classify_records`. See
141
+ [`examples/`](examples) for a runnable script, a synthetic OSM extract and a sample CSV.
142
+
143
+ ## Rulesets
144
+
145
+ Select with `method=` (Python) or `--method` (CLI).
146
+
147
+ | | `mekuria2012` | `furth2017` (default) | `bikeottawa` |
148
+ |---|---|---|---|
149
+ | Source | Mekuria, Furth & Nixon (2012), MTI Report 11-19 | Furth (2017), *LTS Criteria for Road Segments* v2.0 | Bike Ottawa `stressmodel.js` v1.0.1 |
150
+ | Mixed traffic | total lanes (2-3 / 4-5 / 6+) x speed (<=25 / 30 / 35+ mph); lower value when no centreline and ADT <= 3000 | thru lanes per direction (unlaned / 1 / 2 / 3+) x **ADT** x speed (<=20 ... 50+ mph); effective ADT = 1.5 x ADT on one-way roads | `maxspeed` (km/h), total `lanes`, `highway=residential`, service types |
151
+ | Bike lane, no parking | weakest link over lanes/median, width (6 ft), speed, blockage | lanes x width (6+ / 4-5 ft) x speed; < 4 ft does not qualify | lanes, explicit width, speed, residential |
152
+ | Bike lane with parking | weakest link over lanes, reach (15 / 14 / 13.5 ft), speed, blockage | lanes x reach (15+ / 12-14 ft) x speed (<= 35 mph); reach < 12 ft does not qualify | lanes, explicit width, speed, residential |
153
+ | Separated paths, cycle tracks | LTS 1 | LTS 1 | LTS 1 (also `highway=footway`) |
154
+ | Blocked lanes | blockage row (LTS 3) | rated as mixed traffic | not used |
155
+ | ADT, centreline | ADT <= 3000 + no centreline footnote | central | not used |
156
+ | Direction | per direction | per direction | one score per way |
157
+ | Intersections | Table 5 and 6 (below) | Table 5 and 6 (below) | Table 6 if requested |
158
+
159
+ Table numbers for the 2012 criteria follow Furth's republished *LTS Criteria Tables*:
160
+ Table 1 segments by bikeway type, Table 2 bike lanes alongside a parking lane, Table 3 bike
161
+ lanes not alongside a parking lane, Table 4 mixed traffic, Table 5 intersection approaches
162
+ with a right-turn lane, Table 6a/6b unsignalized crossings without/with a crossing island.
163
+ The 2017 v2.0 document has three unnumbered tables (mixed traffic; bike lanes and shoulders
164
+ not adjacent to a parking lane; bike lanes alongside a parking lane). The test suite checks
165
+ every cell of all of these tables.
166
+
167
+ ### Intersections
168
+
169
+ - **Right-turn lanes (Table 5)**: `right_turn_config(length_ft, bike_lane_position,
170
+ turning_speed_mph, rt_lanes, option_lane)` returns one of `short_straight` (LTS >= 2),
171
+ `long_straight` (>= 3), `shift_left` (>= 3) or `other` (4). A table row can carry
172
+ `rt_lane_config`; the floor is applied to bike lanes and mixed traffic, not to separated
173
+ facilities. OSM does not describe these geometries, so this is table input only.
174
+ - **Unsignalized crossings (Table 6)**: `unsignalized_crossing_lts(lanes, speed_mph, island)`.
175
+ In OSM data, `detect_crossings` finds nodes where a *dominant* street (the hardest to cross,
176
+ plus ways sharing its `name`/`ref`) passes through and a less major way meets it. Signals
177
+ (`highway=traffic_signals`, `crossing=traffic_signals`, `crossing:signals=yes`) give LTS 1;
178
+ islands come from `crossing:island=yes`, `crossing=island` or `traffic_calming=island`.
179
+ Furth's 2017 update revised segments only, so the 2012 intersection tables are used with
180
+ every ruleset.
181
+
182
+ In network analysis, a crossing with LTS above the cap blocks movements between two
183
+ non-dominant approaches (going straight across), while turning onto the dominant street is
184
+ governed by that street's own segment LTS.
185
+
186
+ ## Inputs, defaults and assumptions
187
+
188
+ ### OSM tags understood
189
+
190
+ | Topic | Tags |
191
+ |---|---|
192
+ | Access | `highway`, `bicycle` (`no`, `use_sidepath`, `dismount` close the way), `access`, `vehicle`, `motor_vehicle` |
193
+ | Direction | `oneway` (`yes`/`-1`/`reversible`), `oneway:bicycle`, `junction=roundabout`, `cycleway=opposite*`, `cycleway:<side>:oneway` |
194
+ | Bikeways | `cycleway`, `cycleway:left/right/both` = `lane`, `track`, `shared_lane`, `share_busway`, `opposite_lane`, `opposite_track`, `opposite`, `separate`, `no`; subkeys `:lane` (`advisory`, `pictogram`), `:width`, `:buffer`, `:separation` (kerb, bollard, flex_post... make a lane a protected lane), `sidewalk[:side]:bicycle=designated`, `shoulder[:side]` + `shoulder:access:bicycle` |
195
+ | Speed | `maxspeed` (`50`, `30 mph`, `DE:urban`, `FR:zone30`, `GB:nsl_single`, `none`, `walk`), `maxspeed:forward/backward`, `zone:maxspeed`, `source:maxspeed`, `bicycle_road`/`cyclestreet` |
196
+ | Lanes | `lanes`, `lanes:forward/backward`, `lanes:bus/psv` (excluded), `lane_markings`, `dual_carriageway` |
197
+ | Parking | new scheme `parking:<side>=lane/street_side/on_kerb/half_on_kerb/no/separate`, old scheme `parking:lane:<side>=parallel/diagonal/perpendicular/no_parking/no_stopping`, `parking:<side>:width` |
198
+ | Other | `surface` (paved / cobbled / unpaved classes), `adt`/`aadt` if you add counts |
199
+
200
+ Sides are mapped to travel directions using the driving side of the `country` (left-hand
201
+ traffic for GB, IE, JP, AU, NZ, IN, ZA and others).
202
+
203
+ ### Defaults (all logged when used)
204
+
205
+ | Missing input | Default |
206
+ |---|---|
207
+ | `maxspeed` | national urban/rural/motorway/living-street limit for 35 countries (`LTSParameters(country=..., context=...)`), generic 50/90/120 km/h otherwise; `service`/`track` capped at 30 km/h |
208
+ | `lanes` | by class: trunk 4, primary...residential 2 (one-way: half) |
209
+ | centreline | none on residential, living_street, service, track; marked elsewhere |
210
+ | ADT | planning-level guess by class: residential 600, unclassified 1500, tertiary 4000, secondary 9000, primary 15000, trunk 25000 veh/day (`adt_overrides` to change) |
211
+ | bike lane width | 1.5 m (about 5 ft); buffer `yes` = 0.5 m; shoulder 1.2 m |
212
+ | parking next to a bike lane | absent (`assume_parking=True` to flip); parking lane 2.4 m |
213
+ | blockage | rare (`default_blockage="frequent"`) |
214
+ | speed columns | metric speeds are rounded to the nearest 5 mph before the mph tables (50 km/h -> 30 mph); `speed_binning="exact"` disables this |
215
+ | widths | rounded to the nearest 0.5 ft before the ft tables |
216
+
217
+ ### Tabular columns
218
+
219
+ `id, highway, facility (mixed | bike_lane | shoulder | separated | no_motor_traffic),
220
+ speed_mph or speed_kmh, lanes or lanes_per_direction, oneway, contraflow, centerline, adt,
221
+ median, residential, blockage (rare | frequent), bike_lane_width_ft|_m, buffer_ft|_m, parking,
222
+ parking_width_ft|_m, reach_ft|_m, rt_lane_config, permitted, surface`. All optional; missing
223
+ values are assumed and logged.
224
+
225
+ ## Network analysis
226
+
227
+ - `lts_share(net)` - length and share by LTS (worst permitted direction).
228
+ - `low_stress_islands(net, max_lts=2)` - components of the network of edges with LTS <= k in
229
+ at least one direction, broken at crossings whose LTS exceeds k.
230
+ - `connectivity_metrics(net, max_lts)` - low-stress length and share, number of islands,
231
+ largest-island shares, concentration index sum(L_i^2)/(sum L_i)^2, alpha/beta/gamma indices.
232
+ - `shortest_path`, `distances_from` - Dijkstra with direction, an LTS cap and crossing
233
+ restrictions (states are node + incoming edge at crossing nodes).
234
+ - `od_reachability(net, pairs, max_lts=2, max_detour=1.25)` - for each OD pair the
235
+ unrestricted and the low-stress shortest distance and their ratio; the summary gives the
236
+ share reachable at low stress and the share *connected* within the detour allowance (25 %
237
+ by default, following Mekuria et al. 2012).
238
+ - `to_networkx(net, max_lts)` and `to_geodataframe(ways)` with the optional extras.
239
+
240
+ ## Limitations
241
+
242
+ - LTS is only as good as the tags. OSM rarely records ADT, bike lane width, parking, medians
243
+ or right-turn lane geometry; check the `assumptions` field and supply better data (tags,
244
+ `adt_overrides`, table input) where it matters.
245
+ - The speed used is the posted limit, not the prevailing (85th percentile) speed the criteria
246
+ prefer; pass measured speeds through table input when you have them.
247
+ - Divided roads mapped as two one-way ways are counted per carriageway; use
248
+ `dual_carriageway=yes` or `LTSParameters(infer_dual_carriageway=True)` for the 2012 street
249
+ width.
250
+ - Crossing detection is a heuristic (dominant street by Table 6 LTS, lanes and speed); left
251
+ turns, roundabouts and the draft roundabout criteria are not modelled.
252
+ - The `bikeottawa` port follows the reference rules but takes speeds and lanes from the bikelts
253
+ parser (country defaults, units) and uses widths only when tagged; see the module docstring.
254
+ - Surfaces are reported but not scored unless you opt in with `unpaved_min_lts`, which is an
255
+ extension and not part of any published criteria.
256
+ - Default speed tables reflect general national limits; regional and local rules differ.
257
+
258
+ ## References
259
+
260
+ - Mekuria, M. C., Furth, P. G., & Nixon, H. (2012). *Low-Stress Bicycling and Network
261
+ Connectivity* (MTI Report 11-19). Mineta Transportation Institute, San Jose State University.
262
+ - Furth, P. G. *LTS Criteria Tables* (republication of the 2012 criteria, Tables 1-6),
263
+ Northeastern University.
264
+ - Furth, P. G. (2017). *Level of Traffic Stress Criteria for Road Segments*, version 2.0, June
265
+ 2017. Northeastern University.
266
+ - Bike Ottawa. *stressmodel* (version 1.0.1), https://github.com/BikeOttawa/stressmodel
267
+ - OpenStreetMap Wiki. *Key:cycleway*, *Key:parking*, *Default speed limits*.
268
+ - Kansky, K. J. (1963). *Structure of Transportation Networks*. University of Chicago.
269
+
270
+ If you use bikelts in research, please cite the method papers above and this software (see
271
+ [`CITATION.cff`](CITATION.cff)).
272
+
273
+ ## Development
274
+
275
+ ```bash
276
+ pip install -e ".[dev]"
277
+ pytest --cov=bikelts
278
+ ruff check . && ruff format --check src tests && mypy src
279
+ ```
280
+
281
+ ## License
282
+
283
+ MIT, see [LICENSE](LICENSE). OSM data is (c) OpenStreetMap contributors under the ODbL; the
284
+ sample extract in `examples/` is synthetic.
@@ -0,0 +1,241 @@
1
+ # bikelts
2
+
3
+ **Bicycle Level of Traffic Stress (LTS 1-4) for Python.** `bikelts` classifies street
4
+ segments and intersections for cycling from OpenStreetMap tags or from your own
5
+ tabular attributes, records *why* each segment got its score and *which inputs were
6
+ assumed*, and analyses the connectivity of the resulting low-stress network.
7
+
8
+ It is written for active-transportation planners and researchers who need a transparent,
9
+ reproducible LTS map rather than a black box.
10
+
11
+ - Three selectable, documented rulesets: **Mekuria, Furth & Nixon (2012)**,
12
+ **Furth (2017) v2.0**, and the **Bike Ottawa** OSM tag rules.
13
+ - Directional results (`lts_forward`, `lts_backward`) with contraflow handling.
14
+ - Per-segment reasons and an assumption log, e.g.
15
+ `maxspeed missing -> assumed 50 km/h from highway=residential urban default for country DE`.
16
+ - Intersection criteria: right-turn-lane approaches and unsignalized crossings.
17
+ - Network analysis in pure Python: LTS shares, low-stress islands, connectivity metrics,
18
+ Dijkstra with an LTS cap, origin-destination reachability and detour ratios.
19
+ - Offline readers for OSM XML, Overpass JSON and GeoJSON; optional Overpass download.
20
+ - No required dependencies; optional `geopandas` and `networkx` converters.
21
+
22
+ ## Installation
23
+
24
+ ```bash
25
+ pip install bikelts # core, no dependencies
26
+ pip install "bikelts[geo]" # + geopandas/shapely (to_geodataframe)
27
+ pip install "bikelts[graph]" # + networkx (to_networkx)
28
+ pip install "bikelts[all]"
29
+ ```
30
+
31
+ Python 3.9 or newer.
32
+
33
+ ## Quick start
34
+
35
+ ### Command line
36
+
37
+ ```bash
38
+ # Optional: fetch highways for a bounding box (south west north east) from Overpass
39
+ bikelts download --bbox 41.000 29.000 41.010 29.015 -o area.json --timeout 60
40
+
41
+ # Classify (OSM XML .osm, Overpass .json or GeoJSON) and write GeoJSON with LTS + reasons
42
+ bikelts classify area.osm -o lts.geojson --method furth2017 --country DE --intersections
43
+
44
+ # Low-stress islands, LTS shares and OD reachability
45
+ bikelts islands lts.geojson --max-lts 2 -o islands.geojson
46
+ bikelts stats lts.geojson --max-lts 2
47
+ bikelts reach lts.geojson --max-lts 2 --pairs 500 --max-detour 1.25
48
+
49
+ # Tabular input: CSV in, CSV out (columns listed below)
50
+ bikelts classify segments.csv -o segments_lts.csv --method mekuria2012
51
+
52
+ bikelts methods # list rulesets with their sources
53
+ ```
54
+
55
+ Every analysis command accepts `--json` for machine-readable output.
56
+
57
+ ### Python
58
+
59
+ ```python
60
+ from bikelts import LTSParameters, classify_tags
61
+
62
+ params = LTSParameters(country="DE")
63
+ r = classify_tags(
64
+ {"highway": "secondary", "maxspeed": "50", "cycleway:right": "lane", "parking:right": "lane"},
65
+ method="furth2017",
66
+ params=params,
67
+ )
68
+ r.lts_forward, r.lts_backward # (2, 3)
69
+ r.reasons
70
+ # ['forward: bike lane alongside parking: 1 lane per direction, reach 12-14 ft (reach 13 ft), 30 mph -> LTS 2',
71
+ # 'backward: mixed traffic, 1 thru lane per direction, ADT 3000+, 30 mph -> LTS 3']
72
+ r.assumptions
73
+ # ['ADT missing -> assumed 9000 veh/day from highway=secondary default',
74
+ # 'lanes missing -> assumed 2 from highway=secondary two-way default', ...]
75
+ ```
76
+
77
+ A whole extract and its network:
78
+
79
+ ```python
80
+ from bikelts import (LTSNetwork, LTSParameters, classify_osm, connectivity_metrics,
81
+ detect_crossings, low_stress_islands, od_reachability,
82
+ random_od_pairs, read_osm, to_geojson, write_geojson)
83
+
84
+ params = LTSParameters(country="DE")
85
+ data = read_osm("area.osm") # .osm, Overpass .json or .geojson
86
+ ways = classify_osm(data, "furth2017", params)
87
+ crossings = detect_crossings(data, ways, params)
88
+ write_geojson("lts.geojson", to_geojson(ways, crossings, data))
89
+
90
+ net = LTSNetwork.from_classified(ways, crossings)
91
+ islands = low_stress_islands(net, max_lts=2)
92
+ metrics = connectivity_metrics(net, max_lts=2)
93
+ results, summary = od_reachability(net, random_od_pairs(net, 500, seed=1), max_lts=2)
94
+ summary["low_stress_connected_share"] # share of OD pairs connected at LTS <= 2
95
+ ```
96
+
97
+ Tabular records (dicts or CSV rows) use `classify_record` / `classify_records`. See
98
+ [`examples/`](examples) for a runnable script, a synthetic OSM extract and a sample CSV.
99
+
100
+ ## Rulesets
101
+
102
+ Select with `method=` (Python) or `--method` (CLI).
103
+
104
+ | | `mekuria2012` | `furth2017` (default) | `bikeottawa` |
105
+ |---|---|---|---|
106
+ | Source | Mekuria, Furth & Nixon (2012), MTI Report 11-19 | Furth (2017), *LTS Criteria for Road Segments* v2.0 | Bike Ottawa `stressmodel.js` v1.0.1 |
107
+ | Mixed traffic | total lanes (2-3 / 4-5 / 6+) x speed (<=25 / 30 / 35+ mph); lower value when no centreline and ADT <= 3000 | thru lanes per direction (unlaned / 1 / 2 / 3+) x **ADT** x speed (<=20 ... 50+ mph); effective ADT = 1.5 x ADT on one-way roads | `maxspeed` (km/h), total `lanes`, `highway=residential`, service types |
108
+ | Bike lane, no parking | weakest link over lanes/median, width (6 ft), speed, blockage | lanes x width (6+ / 4-5 ft) x speed; < 4 ft does not qualify | lanes, explicit width, speed, residential |
109
+ | Bike lane with parking | weakest link over lanes, reach (15 / 14 / 13.5 ft), speed, blockage | lanes x reach (15+ / 12-14 ft) x speed (<= 35 mph); reach < 12 ft does not qualify | lanes, explicit width, speed, residential |
110
+ | Separated paths, cycle tracks | LTS 1 | LTS 1 | LTS 1 (also `highway=footway`) |
111
+ | Blocked lanes | blockage row (LTS 3) | rated as mixed traffic | not used |
112
+ | ADT, centreline | ADT <= 3000 + no centreline footnote | central | not used |
113
+ | Direction | per direction | per direction | one score per way |
114
+ | Intersections | Table 5 and 6 (below) | Table 5 and 6 (below) | Table 6 if requested |
115
+
116
+ Table numbers for the 2012 criteria follow Furth's republished *LTS Criteria Tables*:
117
+ Table 1 segments by bikeway type, Table 2 bike lanes alongside a parking lane, Table 3 bike
118
+ lanes not alongside a parking lane, Table 4 mixed traffic, Table 5 intersection approaches
119
+ with a right-turn lane, Table 6a/6b unsignalized crossings without/with a crossing island.
120
+ The 2017 v2.0 document has three unnumbered tables (mixed traffic; bike lanes and shoulders
121
+ not adjacent to a parking lane; bike lanes alongside a parking lane). The test suite checks
122
+ every cell of all of these tables.
123
+
124
+ ### Intersections
125
+
126
+ - **Right-turn lanes (Table 5)**: `right_turn_config(length_ft, bike_lane_position,
127
+ turning_speed_mph, rt_lanes, option_lane)` returns one of `short_straight` (LTS >= 2),
128
+ `long_straight` (>= 3), `shift_left` (>= 3) or `other` (4). A table row can carry
129
+ `rt_lane_config`; the floor is applied to bike lanes and mixed traffic, not to separated
130
+ facilities. OSM does not describe these geometries, so this is table input only.
131
+ - **Unsignalized crossings (Table 6)**: `unsignalized_crossing_lts(lanes, speed_mph, island)`.
132
+ In OSM data, `detect_crossings` finds nodes where a *dominant* street (the hardest to cross,
133
+ plus ways sharing its `name`/`ref`) passes through and a less major way meets it. Signals
134
+ (`highway=traffic_signals`, `crossing=traffic_signals`, `crossing:signals=yes`) give LTS 1;
135
+ islands come from `crossing:island=yes`, `crossing=island` or `traffic_calming=island`.
136
+ Furth's 2017 update revised segments only, so the 2012 intersection tables are used with
137
+ every ruleset.
138
+
139
+ In network analysis, a crossing with LTS above the cap blocks movements between two
140
+ non-dominant approaches (going straight across), while turning onto the dominant street is
141
+ governed by that street's own segment LTS.
142
+
143
+ ## Inputs, defaults and assumptions
144
+
145
+ ### OSM tags understood
146
+
147
+ | Topic | Tags |
148
+ |---|---|
149
+ | Access | `highway`, `bicycle` (`no`, `use_sidepath`, `dismount` close the way), `access`, `vehicle`, `motor_vehicle` |
150
+ | Direction | `oneway` (`yes`/`-1`/`reversible`), `oneway:bicycle`, `junction=roundabout`, `cycleway=opposite*`, `cycleway:<side>:oneway` |
151
+ | Bikeways | `cycleway`, `cycleway:left/right/both` = `lane`, `track`, `shared_lane`, `share_busway`, `opposite_lane`, `opposite_track`, `opposite`, `separate`, `no`; subkeys `:lane` (`advisory`, `pictogram`), `:width`, `:buffer`, `:separation` (kerb, bollard, flex_post... make a lane a protected lane), `sidewalk[:side]:bicycle=designated`, `shoulder[:side]` + `shoulder:access:bicycle` |
152
+ | Speed | `maxspeed` (`50`, `30 mph`, `DE:urban`, `FR:zone30`, `GB:nsl_single`, `none`, `walk`), `maxspeed:forward/backward`, `zone:maxspeed`, `source:maxspeed`, `bicycle_road`/`cyclestreet` |
153
+ | Lanes | `lanes`, `lanes:forward/backward`, `lanes:bus/psv` (excluded), `lane_markings`, `dual_carriageway` |
154
+ | Parking | new scheme `parking:<side>=lane/street_side/on_kerb/half_on_kerb/no/separate`, old scheme `parking:lane:<side>=parallel/diagonal/perpendicular/no_parking/no_stopping`, `parking:<side>:width` |
155
+ | Other | `surface` (paved / cobbled / unpaved classes), `adt`/`aadt` if you add counts |
156
+
157
+ Sides are mapped to travel directions using the driving side of the `country` (left-hand
158
+ traffic for GB, IE, JP, AU, NZ, IN, ZA and others).
159
+
160
+ ### Defaults (all logged when used)
161
+
162
+ | Missing input | Default |
163
+ |---|---|
164
+ | `maxspeed` | national urban/rural/motorway/living-street limit for 35 countries (`LTSParameters(country=..., context=...)`), generic 50/90/120 km/h otherwise; `service`/`track` capped at 30 km/h |
165
+ | `lanes` | by class: trunk 4, primary...residential 2 (one-way: half) |
166
+ | centreline | none on residential, living_street, service, track; marked elsewhere |
167
+ | ADT | planning-level guess by class: residential 600, unclassified 1500, tertiary 4000, secondary 9000, primary 15000, trunk 25000 veh/day (`adt_overrides` to change) |
168
+ | bike lane width | 1.5 m (about 5 ft); buffer `yes` = 0.5 m; shoulder 1.2 m |
169
+ | parking next to a bike lane | absent (`assume_parking=True` to flip); parking lane 2.4 m |
170
+ | blockage | rare (`default_blockage="frequent"`) |
171
+ | speed columns | metric speeds are rounded to the nearest 5 mph before the mph tables (50 km/h -> 30 mph); `speed_binning="exact"` disables this |
172
+ | widths | rounded to the nearest 0.5 ft before the ft tables |
173
+
174
+ ### Tabular columns
175
+
176
+ `id, highway, facility (mixed | bike_lane | shoulder | separated | no_motor_traffic),
177
+ speed_mph or speed_kmh, lanes or lanes_per_direction, oneway, contraflow, centerline, adt,
178
+ median, residential, blockage (rare | frequent), bike_lane_width_ft|_m, buffer_ft|_m, parking,
179
+ parking_width_ft|_m, reach_ft|_m, rt_lane_config, permitted, surface`. All optional; missing
180
+ values are assumed and logged.
181
+
182
+ ## Network analysis
183
+
184
+ - `lts_share(net)` - length and share by LTS (worst permitted direction).
185
+ - `low_stress_islands(net, max_lts=2)` - components of the network of edges with LTS <= k in
186
+ at least one direction, broken at crossings whose LTS exceeds k.
187
+ - `connectivity_metrics(net, max_lts)` - low-stress length and share, number of islands,
188
+ largest-island shares, concentration index sum(L_i^2)/(sum L_i)^2, alpha/beta/gamma indices.
189
+ - `shortest_path`, `distances_from` - Dijkstra with direction, an LTS cap and crossing
190
+ restrictions (states are node + incoming edge at crossing nodes).
191
+ - `od_reachability(net, pairs, max_lts=2, max_detour=1.25)` - for each OD pair the
192
+ unrestricted and the low-stress shortest distance and their ratio; the summary gives the
193
+ share reachable at low stress and the share *connected* within the detour allowance (25 %
194
+ by default, following Mekuria et al. 2012).
195
+ - `to_networkx(net, max_lts)` and `to_geodataframe(ways)` with the optional extras.
196
+
197
+ ## Limitations
198
+
199
+ - LTS is only as good as the tags. OSM rarely records ADT, bike lane width, parking, medians
200
+ or right-turn lane geometry; check the `assumptions` field and supply better data (tags,
201
+ `adt_overrides`, table input) where it matters.
202
+ - The speed used is the posted limit, not the prevailing (85th percentile) speed the criteria
203
+ prefer; pass measured speeds through table input when you have them.
204
+ - Divided roads mapped as two one-way ways are counted per carriageway; use
205
+ `dual_carriageway=yes` or `LTSParameters(infer_dual_carriageway=True)` for the 2012 street
206
+ width.
207
+ - Crossing detection is a heuristic (dominant street by Table 6 LTS, lanes and speed); left
208
+ turns, roundabouts and the draft roundabout criteria are not modelled.
209
+ - The `bikeottawa` port follows the reference rules but takes speeds and lanes from the bikelts
210
+ parser (country defaults, units) and uses widths only when tagged; see the module docstring.
211
+ - Surfaces are reported but not scored unless you opt in with `unpaved_min_lts`, which is an
212
+ extension and not part of any published criteria.
213
+ - Default speed tables reflect general national limits; regional and local rules differ.
214
+
215
+ ## References
216
+
217
+ - Mekuria, M. C., Furth, P. G., & Nixon, H. (2012). *Low-Stress Bicycling and Network
218
+ Connectivity* (MTI Report 11-19). Mineta Transportation Institute, San Jose State University.
219
+ - Furth, P. G. *LTS Criteria Tables* (republication of the 2012 criteria, Tables 1-6),
220
+ Northeastern University.
221
+ - Furth, P. G. (2017). *Level of Traffic Stress Criteria for Road Segments*, version 2.0, June
222
+ 2017. Northeastern University.
223
+ - Bike Ottawa. *stressmodel* (version 1.0.1), https://github.com/BikeOttawa/stressmodel
224
+ - OpenStreetMap Wiki. *Key:cycleway*, *Key:parking*, *Default speed limits*.
225
+ - Kansky, K. J. (1963). *Structure of Transportation Networks*. University of Chicago.
226
+
227
+ If you use bikelts in research, please cite the method papers above and this software (see
228
+ [`CITATION.cff`](CITATION.cff)).
229
+
230
+ ## Development
231
+
232
+ ```bash
233
+ pip install -e ".[dev]"
234
+ pytest --cov=bikelts
235
+ ruff check . && ruff format --check src tests && mypy src
236
+ ```
237
+
238
+ ## License
239
+
240
+ MIT, see [LICENSE](LICENSE). OSM data is (c) OpenStreetMap contributors under the ODbL; the
241
+ sample extract in `examples/` is synthetic.