streetlos 0.1.0__tar.gz

streetlos-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- Walkway LOS by space per pedestrian and unit flow rate, with average-flow and
+  platoon-adjusted criteria (FHWA-RD-98-107; HCM 2000 walkway tables).
+- Effective sidewalk width with building and curb shy distances and street furniture.
+- Corner and crosswalk circulation area with the time-space method.
+- Pedestrian and bicycle segment (link) LOS score models of NCHRP Report 616 in the
+  HCM 2010 form, returning every factor.
+- Pedestrian comfort and bicycle facility indicators with configurable thresholds
+  (PROWAG clear-width minimum).
+- Overridable, cited `LosTable` threshold tables.
+- `streetlos` command line tool: CSV of segments in, LOS table out, US or SI units,
+  JSON table overrides.

streetlos-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "streetlos"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://gitlab.com/geophilo1/streetlos_sdk"
+url: "https://pypi.org/project/streetlos/"
+abstract: "Multimodal street level-of-service screening: walkway LOS by flow and space (average and platoon-adjusted), corner and crosswalk circulation area, NCHRP Report 616 / HCM 2010 pedestrian and bicycle segment LOS scores, and comfort indicators, with a CSV command line tool."
+keywords:
+  - level of service
+  - pedestrian
+  - bicycle
+  - complete streets
+  - transportation planning

streetlos-0.1.0/LICENSE

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

streetlos-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/streetlos/py.typed
+recursive-include src/streetlos *.py
+recursive-include tests *.py
+recursive-include examples *.py *.csv

streetlos-0.1.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: streetlos
+Version: 0.1.0
+Summary: Multimodal street level-of-service screening: walkway LOS by flow and space (average and platoon-adjusted), corner and crosswalk circulation area, NCHRP 616 / HCM 2010 pedestrian and bicycle segment LOS scores, and comfort indicators, with a CSV command line tool.
+Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/geophilo1/streetlos_sdk
+Project-URL: Repository, https://gitlab.com/geophilo1/streetlos_sdk
+Project-URL: Issues, https://gitlab.com/geophilo1/streetlos_sdk/-/work_items
+Project-URL: Changelog, https://gitlab.com/geophilo1/streetlos_sdk/-/blob/main/CHANGELOG.md
+Keywords: level-of-service,multimodal-los,pedestrian,bicycle,walkability,sidewalk,complete-streets,highway-capacity-manual,nchrp-616,transportation-planning,urban-planning,gis
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# streetlos
+
+[![PyPI version](https://img.shields.io/pypi/v/streetlos.svg?color=3b82f6)](https://pypi.org/project/streetlos/)
+[![Python version support](https://img.shields.io/pypi/pyversions/streetlos.svg?color=10b981)](https://pypi.org/project/streetlos/)
+[![pipeline](https://gitlab.com/geophilo1/streetlos_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/streetlos_sdk/-/pipelines)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/streetlos_sdk/-/blob/main/LICENSE)
+
+**Multimodal street level-of-service screening for walking and cycling.**
+
+`streetlos` scores street segments for pedestrians and cyclists from a plain CSV
+of street attributes. It is written for planners and researchers who need a
+transparent, reproducible screening (which streets look poor, and why) rather
+than a black box. Every threshold table is cited and can be overridden.
+
+- **Walkway LOS** by space per pedestrian and unit flow rate, with the
+  average-flow and the **platoon-adjusted** criteria.
+- **Effective sidewalk width** after shy distances and street furniture.
+- **Corner and crosswalk circulation area** with the time-space method.
+- **Pedestrian and bicycle segment LOS scores** from NCHRP Report 616
+  (Dowling et al. 2008), in the form adopted by HCM 2010.
+- **Comfort indicators**: clear width against the PROWAG minimum, buffer,
+  traffic speed and volume per lane, bike lane width and door-zone exposure.
+- **CLI**: CSV of segments in, LOS table out. US (ft, mph) or SI (m, km/h) units.
+
+No runtime dependencies: the standard library is enough.
+
+```bash
+pip install streetlos
+```
+
+Requires Python 3.9 or newer.
+
+> **About the HCM.** The *Highway Capacity Manual* is a copyrighted publication
+> of the Transportation Research Board. `streetlos` does not reproduce its text.
+> It implements published equations and numeric thresholds, cites the openly
+> accessible documents they were checked against, and lets you replace every
+> table (for example with the values of the HCM edition your agency uses).
+
+---
+
+## Quickstart
+
+```python
+import streetlos as sl
+
+# Walkway: 8.5 ft effective width, 600 pedestrians in the peak 15 minutes
+w = sl.walkway_los(8.5, 600)
+print(w.unit_flow_p_min_ft, w.space_ft2_p, w.los)        # 4.71  56.1  'B'
+print(sl.walkway_los(8.5, 600, platoon=True).los)        # 'C'
+
+# Effective width: 10 ft sidewalk, building facade, no buffer, a light pole
+sl.effective_walkway_width(10, building_edge="building", obstructions=["light_pole"])  # 3.5
+
+# Pedestrian segment LOS score for one side of the street
+p = sl.pedestrian_link_score(
+    outside_lane_ft=12, bike_lane_ft=5, shoulder_ft=8, parking_occupancy=0.5,
+    buffer_ft=4, sidewalk_ft=6, volume_vph=800, through_lanes=2, running_speed_mph=30,
+)
+print(round(p.score, 3), p.los)                           # 1.997 'A'
+
+# Bicycle segment LOS score for one direction
+b = sl.bicycle_link_score(
+    outside_lane_ft=12, bike_lane_ft=5, volume_vph=800, through_lanes=2,
+    running_speed_mph=35, heavy_vehicle_pct=2, pavement_rating=4,
+)
+print(round(b.score, 3), b.los)                           # 2.232 'B'
+
+# Corner circulation area (time-space)
+c = sl.corner_circulation(10, 12, 15, cycle_s=90, circulating_peds_per_cycle=120,
+                          waiting=[(20, 60), (25, 55)])
+print(round(c.space_ft2_p, 2), c.los)                     # 4.9 'F'
+```
+
+### Command line
+
+```bash
+streetlos segments.csv -o segments_los.csv            # US units (ft, mph)
+streetlos segments.csv --units si                     # metres, km/h -> segments_los.csv
+streetlos segments.csv --platoon                      # platoon-adjusted walkway criteria
+streetlos segments.csv --tables my_tables.json        # override breakpoints
+streetlos --list-tables                               # print tables and sources
+```
+
+One row per segment side (pedestrian) or direction (bicycle). Recognised columns
+(all optional; a model runs only when its inputs are present, and `notes` says
+what was skipped):
+
+| column | meaning | unit (us / si) |
+|---|---|---|
+| `segment_id` | identifier, copied through | |
+| `outside_lane` | outside through lane width | ft / m |
+| `bike_lane` | bicycle lane width | ft / m |
+| `shoulder` | paved shoulder or parking lane width | ft / m |
+| `curb` | curb present (yes/no, default yes) | |
+| `parking_occupancy` | share of on-street parking occupied, 0-1 | |
+| `parking_striped` | parking spaces striped (yes/no) | |
+| `buffer` | buffer between sidewalk and road | ft / m |
+| `barrier` | continuous barrier at least 3 ft high in the buffer | |
+| `sidewalk_width` | sidewalk width, excluding the buffer | ft / m |
+| `building_edge` | `none`, `building`, `window_display`, `fence`, `low_wall` | |
+| `obstructions` | `;`-separated names or widths in the walking path | ft / m |
+| `volume_vph` | motor vehicle flow in this direction | veh/h |
+| `through_lanes` | through lanes in this direction | |
+| `speed` | motor vehicle running speed | mph / km/h |
+| `heavy_vehicle_pct` | heavy vehicles | % |
+| `pavement_rating` | pavement condition, 0.5-5 (default 4) | |
+| `divided` | divided street (yes/no) | |
+| `ped_volume_15min` / `ped_volume_hour` + `phf` | two-way pedestrian volume | p |
+| `walk_speed` | walking speed (default 4.4 ft/s) | ft/s / m/s |
+| `facility` | `none`, `shared`, `bike_lane`, `buffered_lane`, `separated`, `path` | |
+| `bike_buffer` | buffer beside the bike lane | ft / m |
+
+Output columns: effective width, unit flow, space per pedestrian, walkway LOS
+(space, flow, overall), pedestrian score and LOS, bicycle score and LOS,
+`ped_flags`, `bike_flags`, `notes`. See `examples/segments.csv`.
+
+Override file format (`--tables`): `{"walkway_flow": [5, 7, 10, 15, 23]}`, i.e.
+five A-E breakpoints per table name (`streetlos --list-tables` shows the names).
+
+---
+
+## API overview
+
+| function | purpose |
+|---|---|
+| `walkway_los(width, peds_15min, platoon=False)` | walkway LOS by space and flow; worse governs |
+| `effective_walkway_width(total, building_edge, has_buffer, obstructions)` | effective width W_E |
+| `unit_flow_rate`, `pedestrian_space` | v_p = v15 / (15 W_E); A_p = 60 S_p / v_p |
+| `corner_circulation`, `crosswalk_circulation` | time-space circulation area per pedestrian |
+| `pedestrian_link_score(...)` | NCHRP 616 / HCM 2010 pedestrian link score, factors and LOS |
+| `bicycle_link_score(...)` | NCHRP 616 / HCM 2010 bicycle link score, factors and LOS |
+| `pedestrian_comfort`, `bicycle_facility` | screening indicators and flags (`ComfortThresholds`) |
+| `evaluate_segment`, `evaluate_rows`, `evaluate_csv` | batch evaluation of segment tables |
+| `LosTable`, `DEFAULT_TABLES`, `tables_with_overrides` | inspect and replace thresholds |
+
+All functions take US customary units (ft, mph, veh/h), because that is how the
+models were calibrated. `streetlos.units` converts from SI.
+
+---
+
+## Method and sources
+
+### Walkway LOS
+Unit flow `v_p = v_15 / (15 W_E)` (p/min/ft) and space `A_p = 60 S_p / v_p`
+(ft²/p), where `S_p` defaults to 4.4 ft/s (3.3 ft/s where more than 20 % of
+pedestrians are elderly). Breakpoints:
+
+| LOS | space, ft²/p | flow, p/min/ft | platoon space | platoon flow |
+|---|---|---|---|---|
+| A | > 60 | ≤ 5 | > 530 | ≤ 0.5 |
+| B | > 40 | ≤ 7 | > 90 | ≤ 3 |
+| C | > 24 | ≤ 10 | > 40 | ≤ 6 |
+| D | > 15 | ≤ 15 | > 23 | ≤ 11 |
+| E | > 8 | ≤ 23 | > 11 | ≤ 18 |
+| F | ≤ 8 | > 23 | ≤ 11 | > 18 |
+
+Sources: Rouphail et al. (1998) FHWA-RD-98-107, Tables 4 and 6 (adopted in HCM
+2000); NYC Department of City Planning (2006), *Pedestrian Level of Service
+Study, Phase I*, Tables 2.1-2.2. The original platoon research is Pushkarev &
+Zupan (1975), *Urban Space for Pedestrians*.
+
+### Effective width
+Building-side shy distance (3 ft window display, 2 ft building facade, 1.5 ft
+fence or low wall), 1.5 ft curb shy distance where there is no buffer, and the
+effective width of obstructions in the walking path (HCM 6th edition values as
+reported by McTrans). The default street-furniture widths are **not verified**
+(see Limitations); measure them or pass numbers.
+
+### Corners and crosswalks (time-space)
+Fruin's time-space concept as used by the HCM: available time-space
+(area × cycle) minus the time-space held by waiting pedestrians, divided by the
+pedestrian occupancy time. The corner area loses `(1 − π/4) R² ≈ 0.215 R²` to
+the curb return; waiting time per cycle for uniform arrivals is `N r² / (2C)`;
+circulation time is the HCM constant of 4 s per pedestrian, or Fruin, Ketcham
+and Hecht's `0.12 (W_a + W_b) + 1.4` s (`fruin_circulation_time`). See
+FHWA-RD-98-107 Section 4.
+
+### Pedestrian segment (link) LOS score
+`I_p = 6.0468 + F_w + F_v + F_s`, with
+`F_w = −1.2276 ln(W_v + 0.5 W_1 + 50 p_pk + W_buf f_b + W_aA f_sw)`,
+`F_v = 0.0091 v_m / (4 N_th)` and `F_s = 4 (S_R/100)²`, plus the HCM 2010
+width adjustments (`f_b = 5.37` with a continuous barrier, `f_sw = 6.0 − 0.3 W_aA`,
+`W_aA ≤ 10 ft`, volume-adjusted `W_v`, parking-dependent `W_1`). If a pedestrian
+space is known, the reported LOS is the worse of the score LOS and the space LOS.
+
+### Bicycle segment (link) LOS score
+`I_b = 0.760 + F_w + F_v + F_s + F_p`, with `F_w = −0.005 W_e²`,
+`F_v = 0.507 ln(v_ma / (4 N_th))`,
+`F_s = 0.199 [1.1199 ln(S_Ra − 20) + 0.8103] (1 + 0.1038 P_HVa)²` and
+`F_p = 7.066 / P_c²`, plus the adjustments `S_Ra ≥ 21 mph`, `v_ma ≥ 4 N_th`
+and the 50 % heavy-vehicle cap at low volumes.
+
+Score letters (both models): A ≤ 2.00, B ≤ 2.75, C ≤ 3.50, D ≤ 4.25, E ≤ 5.00, F > 5.00.
+
+Sources: Dowling et al. (2008), *Multimodal Level of Service Analysis for Urban
+Streets*, NCHRP Report 616 (note its published erratum for the pedestrian
+segment equation); HCM 2010 Chapter 17, checked against the open restatement in
+Lewis Center for Regional Policy Studies, UCLA (2014), *HCM Bicycle and
+Pedestrian Level of Service: The Ultimate White Paper*. The models descend from
+Landis et al. (1997, TRR 1578) and Landis et al. (2001, TRR 1773).
+
+### Comfort indicators
+Clear width is checked against the 4.0 ft (1.2 m) minimum and 5.0 ft passing
+width of the US Access Board's Public Right-of-Way Accessibility Guidelines
+(36 CFR Part 1190, R302.3-R302.4). The other flags (speed above 30 mph without a
+buffer, more than 600 veh/h per lane, bike lane narrower than 5 ft, mixed
+traffic above 25 mph, unbuffered bike lane next to parking) are **screening
+heuristics** with defaults you set through `ComfortThresholds`.
+
+### Related package
+For **Bicycle Level of Traffic Stress** (LTS 1-4, Mekuria, Furth & Nixon 2012)
+use [`bikelts`](https://pypi.org/project/bikelts/). `streetlos` gives the
+perception-based LOS scores and walking measures; `bikelts` gives the stress
+classification and low-stress connectivity.
+
+---
+
+## Limitations
+
+- **Screening, not a full HCM analysis.** Intersection LOS, mid-segment
+  crossing difficulty, pedestrian delay and facility (multi-segment) aggregation
+  are not implemented.
+- The segment models were calibrated on US urban streets, in US units. Results
+  elsewhere (for example in Türkiye) indicate relative quality; they are not
+  calibrated perceptions.
+- The HCM 2010 bicycle width rule counts the bike lane and shoulder twice when
+  their combined width is at least 4 ft (as restated by the Lewis Center paper).
+  It is implemented as published. Wide, low-volume cross sections can give
+  negative scores, which map to LOS A.
+- Walking speed is taken as constant; the speed-flow reduction of newer HCM
+  editions is not applied. Pass `walk_speed_ft_s` if you have a measured speed.
+- **Not verified from an open source:** the street-furniture effective widths
+  in `walkway.OBSTRUCTION_WIDTH_FT` (midpoints recalled from the HCM 2000
+  fixed-object table), and the use of walkway space breakpoints for corner and
+  crosswalk circulation area (`CORNER_CROSSWALK_SPACE`, flagged `verified=False`).
+- Comfort thresholds other than the PROWAG widths are heuristics.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+python -m ruff check . && python -m ruff format --check src tests
+python -m mypy src
+```
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_streetlos,
+  author  = {Eminoğlu, Yusuf},
+  title   = {streetlos},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://gitlab.com/geophilo1/streetlos_sdk}
+}
+```
+
+## License
+
+MIT © 2026 Yusuf Eminoğlu. Contact: geospacephilo@gmail.com

streetlos-0.1.0/README.md

@@ -0,0 +1,263 @@
+# streetlos
+
+[![PyPI version](https://img.shields.io/pypi/v/streetlos.svg?color=3b82f6)](https://pypi.org/project/streetlos/)
+[![Python version support](https://img.shields.io/pypi/pyversions/streetlos.svg?color=10b981)](https://pypi.org/project/streetlos/)
+[![pipeline](https://gitlab.com/geophilo1/streetlos_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/streetlos_sdk/-/pipelines)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/streetlos_sdk/-/blob/main/LICENSE)
+
+**Multimodal street level-of-service screening for walking and cycling.**
+
+`streetlos` scores street segments for pedestrians and cyclists from a plain CSV
+of street attributes. It is written for planners and researchers who need a
+transparent, reproducible screening (which streets look poor, and why) rather
+than a black box. Every threshold table is cited and can be overridden.
+
+- **Walkway LOS** by space per pedestrian and unit flow rate, with the
+  average-flow and the **platoon-adjusted** criteria.
+- **Effective sidewalk width** after shy distances and street furniture.
+- **Corner and crosswalk circulation area** with the time-space method.
+- **Pedestrian and bicycle segment LOS scores** from NCHRP Report 616
+  (Dowling et al. 2008), in the form adopted by HCM 2010.
+- **Comfort indicators**: clear width against the PROWAG minimum, buffer,
+  traffic speed and volume per lane, bike lane width and door-zone exposure.
+- **CLI**: CSV of segments in, LOS table out. US (ft, mph) or SI (m, km/h) units.
+
+No runtime dependencies: the standard library is enough.
+
+```bash
+pip install streetlos
+```
+
+Requires Python 3.9 or newer.
+
+> **About the HCM.** The *Highway Capacity Manual* is a copyrighted publication
+> of the Transportation Research Board. `streetlos` does not reproduce its text.
+> It implements published equations and numeric thresholds, cites the openly
+> accessible documents they were checked against, and lets you replace every
+> table (for example with the values of the HCM edition your agency uses).
+
+---
+
+## Quickstart
+
+```python
+import streetlos as sl
+
+# Walkway: 8.5 ft effective width, 600 pedestrians in the peak 15 minutes
+w = sl.walkway_los(8.5, 600)
+print(w.unit_flow_p_min_ft, w.space_ft2_p, w.los)        # 4.71  56.1  'B'
+print(sl.walkway_los(8.5, 600, platoon=True).los)        # 'C'
+
+# Effective width: 10 ft sidewalk, building facade, no buffer, a light pole
+sl.effective_walkway_width(10, building_edge="building", obstructions=["light_pole"])  # 3.5
+
+# Pedestrian segment LOS score for one side of the street
+p = sl.pedestrian_link_score(
+    outside_lane_ft=12, bike_lane_ft=5, shoulder_ft=8, parking_occupancy=0.5,
+    buffer_ft=4, sidewalk_ft=6, volume_vph=800, through_lanes=2, running_speed_mph=30,
+)
+print(round(p.score, 3), p.los)                           # 1.997 'A'
+
+# Bicycle segment LOS score for one direction
+b = sl.bicycle_link_score(
+    outside_lane_ft=12, bike_lane_ft=5, volume_vph=800, through_lanes=2,
+    running_speed_mph=35, heavy_vehicle_pct=2, pavement_rating=4,
+)
+print(round(b.score, 3), b.los)                           # 2.232 'B'
+
+# Corner circulation area (time-space)
+c = sl.corner_circulation(10, 12, 15, cycle_s=90, circulating_peds_per_cycle=120,
+                          waiting=[(20, 60), (25, 55)])
+print(round(c.space_ft2_p, 2), c.los)                     # 4.9 'F'
+```
+
+### Command line
+
+```bash
+streetlos segments.csv -o segments_los.csv            # US units (ft, mph)
+streetlos segments.csv --units si                     # metres, km/h -> segments_los.csv
+streetlos segments.csv --platoon                      # platoon-adjusted walkway criteria
+streetlos segments.csv --tables my_tables.json        # override breakpoints
+streetlos --list-tables                               # print tables and sources
+```
+
+One row per segment side (pedestrian) or direction (bicycle). Recognised columns
+(all optional; a model runs only when its inputs are present, and `notes` says
+what was skipped):
+
+| column | meaning | unit (us / si) |
+|---|---|---|
+| `segment_id` | identifier, copied through | |
+| `outside_lane` | outside through lane width | ft / m |
+| `bike_lane` | bicycle lane width | ft / m |
+| `shoulder` | paved shoulder or parking lane width | ft / m |
+| `curb` | curb present (yes/no, default yes) | |
+| `parking_occupancy` | share of on-street parking occupied, 0-1 | |
+| `parking_striped` | parking spaces striped (yes/no) | |
+| `buffer` | buffer between sidewalk and road | ft / m |
+| `barrier` | continuous barrier at least 3 ft high in the buffer | |
+| `sidewalk_width` | sidewalk width, excluding the buffer | ft / m |
+| `building_edge` | `none`, `building`, `window_display`, `fence`, `low_wall` | |
+| `obstructions` | `;`-separated names or widths in the walking path | ft / m |
+| `volume_vph` | motor vehicle flow in this direction | veh/h |
+| `through_lanes` | through lanes in this direction | |
+| `speed` | motor vehicle running speed | mph / km/h |
+| `heavy_vehicle_pct` | heavy vehicles | % |
+| `pavement_rating` | pavement condition, 0.5-5 (default 4) | |
+| `divided` | divided street (yes/no) | |
+| `ped_volume_15min` / `ped_volume_hour` + `phf` | two-way pedestrian volume | p |
+| `walk_speed` | walking speed (default 4.4 ft/s) | ft/s / m/s |
+| `facility` | `none`, `shared`, `bike_lane`, `buffered_lane`, `separated`, `path` | |
+| `bike_buffer` | buffer beside the bike lane | ft / m |
+
+Output columns: effective width, unit flow, space per pedestrian, walkway LOS
+(space, flow, overall), pedestrian score and LOS, bicycle score and LOS,
+`ped_flags`, `bike_flags`, `notes`. See `examples/segments.csv`.
+
+Override file format (`--tables`): `{"walkway_flow": [5, 7, 10, 15, 23]}`, i.e.
+five A-E breakpoints per table name (`streetlos --list-tables` shows the names).
+
+---
+
+## API overview
+
+| function | purpose |
+|---|---|
+| `walkway_los(width, peds_15min, platoon=False)` | walkway LOS by space and flow; worse governs |
+| `effective_walkway_width(total, building_edge, has_buffer, obstructions)` | effective width W_E |
+| `unit_flow_rate`, `pedestrian_space` | v_p = v15 / (15 W_E); A_p = 60 S_p / v_p |
+| `corner_circulation`, `crosswalk_circulation` | time-space circulation area per pedestrian |
+| `pedestrian_link_score(...)` | NCHRP 616 / HCM 2010 pedestrian link score, factors and LOS |
+| `bicycle_link_score(...)` | NCHRP 616 / HCM 2010 bicycle link score, factors and LOS |
+| `pedestrian_comfort`, `bicycle_facility` | screening indicators and flags (`ComfortThresholds`) |
+| `evaluate_segment`, `evaluate_rows`, `evaluate_csv` | batch evaluation of segment tables |
+| `LosTable`, `DEFAULT_TABLES`, `tables_with_overrides` | inspect and replace thresholds |
+
+All functions take US customary units (ft, mph, veh/h), because that is how the
+models were calibrated. `streetlos.units` converts from SI.
+
+---
+
+## Method and sources
+
+### Walkway LOS
+Unit flow `v_p = v_15 / (15 W_E)` (p/min/ft) and space `A_p = 60 S_p / v_p`
+(ft²/p), where `S_p` defaults to 4.4 ft/s (3.3 ft/s where more than 20 % of
+pedestrians are elderly). Breakpoints:
+
+| LOS | space, ft²/p | flow, p/min/ft | platoon space | platoon flow |
+|---|---|---|---|---|
+| A | > 60 | ≤ 5 | > 530 | ≤ 0.5 |
+| B | > 40 | ≤ 7 | > 90 | ≤ 3 |
+| C | > 24 | ≤ 10 | > 40 | ≤ 6 |
+| D | > 15 | ≤ 15 | > 23 | ≤ 11 |
+| E | > 8 | ≤ 23 | > 11 | ≤ 18 |
+| F | ≤ 8 | > 23 | ≤ 11 | > 18 |
+
+Sources: Rouphail et al. (1998) FHWA-RD-98-107, Tables 4 and 6 (adopted in HCM
+2000); NYC Department of City Planning (2006), *Pedestrian Level of Service
+Study, Phase I*, Tables 2.1-2.2. The original platoon research is Pushkarev &
+Zupan (1975), *Urban Space for Pedestrians*.
+
+### Effective width
+Building-side shy distance (3 ft window display, 2 ft building facade, 1.5 ft
+fence or low wall), 1.5 ft curb shy distance where there is no buffer, and the
+effective width of obstructions in the walking path (HCM 6th edition values as
+reported by McTrans). The default street-furniture widths are **not verified**
+(see Limitations); measure them or pass numbers.
+
+### Corners and crosswalks (time-space)
+Fruin's time-space concept as used by the HCM: available time-space
+(area × cycle) minus the time-space held by waiting pedestrians, divided by the
+pedestrian occupancy time. The corner area loses `(1 − π/4) R² ≈ 0.215 R²` to
+the curb return; waiting time per cycle for uniform arrivals is `N r² / (2C)`;
+circulation time is the HCM constant of 4 s per pedestrian, or Fruin, Ketcham
+and Hecht's `0.12 (W_a + W_b) + 1.4` s (`fruin_circulation_time`). See
+FHWA-RD-98-107 Section 4.
+
+### Pedestrian segment (link) LOS score
+`I_p = 6.0468 + F_w + F_v + F_s`, with
+`F_w = −1.2276 ln(W_v + 0.5 W_1 + 50 p_pk + W_buf f_b + W_aA f_sw)`,
+`F_v = 0.0091 v_m / (4 N_th)` and `F_s = 4 (S_R/100)²`, plus the HCM 2010
+width adjustments (`f_b = 5.37` with a continuous barrier, `f_sw = 6.0 − 0.3 W_aA`,
+`W_aA ≤ 10 ft`, volume-adjusted `W_v`, parking-dependent `W_1`). If a pedestrian
+space is known, the reported LOS is the worse of the score LOS and the space LOS.
+
+### Bicycle segment (link) LOS score
+`I_b = 0.760 + F_w + F_v + F_s + F_p`, with `F_w = −0.005 W_e²`,
+`F_v = 0.507 ln(v_ma / (4 N_th))`,
+`F_s = 0.199 [1.1199 ln(S_Ra − 20) + 0.8103] (1 + 0.1038 P_HVa)²` and
+`F_p = 7.066 / P_c²`, plus the adjustments `S_Ra ≥ 21 mph`, `v_ma ≥ 4 N_th`
+and the 50 % heavy-vehicle cap at low volumes.
+
+Score letters (both models): A ≤ 2.00, B ≤ 2.75, C ≤ 3.50, D ≤ 4.25, E ≤ 5.00, F > 5.00.
+
+Sources: Dowling et al. (2008), *Multimodal Level of Service Analysis for Urban
+Streets*, NCHRP Report 616 (note its published erratum for the pedestrian
+segment equation); HCM 2010 Chapter 17, checked against the open restatement in
+Lewis Center for Regional Policy Studies, UCLA (2014), *HCM Bicycle and
+Pedestrian Level of Service: The Ultimate White Paper*. The models descend from
+Landis et al. (1997, TRR 1578) and Landis et al. (2001, TRR 1773).
+
+### Comfort indicators
+Clear width is checked against the 4.0 ft (1.2 m) minimum and 5.0 ft passing
+width of the US Access Board's Public Right-of-Way Accessibility Guidelines
+(36 CFR Part 1190, R302.3-R302.4). The other flags (speed above 30 mph without a
+buffer, more than 600 veh/h per lane, bike lane narrower than 5 ft, mixed
+traffic above 25 mph, unbuffered bike lane next to parking) are **screening
+heuristics** with defaults you set through `ComfortThresholds`.
+
+### Related package
+For **Bicycle Level of Traffic Stress** (LTS 1-4, Mekuria, Furth & Nixon 2012)
+use [`bikelts`](https://pypi.org/project/bikelts/). `streetlos` gives the
+perception-based LOS scores and walking measures; `bikelts` gives the stress
+classification and low-stress connectivity.
+
+---
+
+## Limitations
+
+- **Screening, not a full HCM analysis.** Intersection LOS, mid-segment
+  crossing difficulty, pedestrian delay and facility (multi-segment) aggregation
+  are not implemented.
+- The segment models were calibrated on US urban streets, in US units. Results
+  elsewhere (for example in Türkiye) indicate relative quality; they are not
+  calibrated perceptions.
+- The HCM 2010 bicycle width rule counts the bike lane and shoulder twice when
+  their combined width is at least 4 ft (as restated by the Lewis Center paper).
+  It is implemented as published. Wide, low-volume cross sections can give
+  negative scores, which map to LOS A.
+- Walking speed is taken as constant; the speed-flow reduction of newer HCM
+  editions is not applied. Pass `walk_speed_ft_s` if you have a measured speed.
+- **Not verified from an open source:** the street-furniture effective widths
+  in `walkway.OBSTRUCTION_WIDTH_FT` (midpoints recalled from the HCM 2000
+  fixed-object table), and the use of walkway space breakpoints for corner and
+  crosswalk circulation area (`CORNER_CROSSWALK_SPACE`, flagged `verified=False`).
+- Comfort thresholds other than the PROWAG widths are heuristics.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+python -m ruff check . && python -m ruff format --check src tests
+python -m mypy src
+```
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_streetlos,
+  author  = {Eminoğlu, Yusuf},
+  title   = {streetlos},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://gitlab.com/geophilo1/streetlos_sdk}
+}
+```
+
+## License
+
+MIT © 2026 Yusuf Eminoğlu. Contact: geospacephilo@gmail.com