transitfreq 0.1.0__tar.gz

transitfreq-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- `GTFSFeed`: zip or folder input, streaming CSV reading (UTF-8 with or without BOM),
+  feeds nested in a zip sub-folder, cached stops/routes/trips/frequencies, shapes.
+- Service calendar resolution from `calendar.txt` and `calendar_dates.txt`.
+- Stop events for a service day: `frequencies.txt` expansion, interpolation of untimed
+  stops, times past 24:00, optional after-midnight trips of the previous day, boarding
+  flags (last stop and `pickup_type=1` excluded).
+- `ServiceDay`: trips per hour by route, route-direction, stop or stop-route; route and
+  stop summaries with trips/h, mean/max headway and mean gap per time window, span of
+  service, TCQSM hours of service, quality-of-service bands and frequent flags; stops
+  combined across routes and optionally grouped by parent station.
+- Configurable `FrequentCriteria` (default 15 min or better, 07:00-19:00, every direction).
+- TCQSM 3rd ed. (2013) frequency and hours-of-service bands (Exhibits 5-2, 5-3), optional
+  2nd ed. letter-grade tables, and custom tables.
+- GeoJSON export of stops (Point) and routes (MultiLineString from `shapes.txt` or stop
+  sequences) with frequency attributes.
+- CLI: `transitfreq summary|services|routes|stops|frequent|tph|geojson`.
+- Optional pandas helpers: `departures_frame`, `stops_frame`, `routes_frame`.

transitfreq-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: "transitfreq"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/transitfreq_sdk"
+url: "https://pypi.org/project/transitfreq/"
+abstract: "Transit service frequency analysis from GTFS Schedule feeds: service calendars, frequencies.txt expansion, trips per hour, average and maximum headways, span and hours of service, frequent network identification, TCQSM quality-of-service bands and GeoJSON export."
+keywords:
+  - gtfs
+  - public transport
+  - headway
+  - service frequency
+  - transport planning

transitfreq-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.

transitfreq-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/transitfreq/py.typed
+recursive-include src/transitfreq *.py
+recursive-include tests *.py
+recursive-include tests/data *.txt
+recursive-include examples *.py

transitfreq-0.1.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: transitfreq
+Version: 0.1.0
+Summary: Transit service frequency analysis from GTFS Schedule feeds: service calendars, frequencies.txt expansion, trips per hour, headways, span of service, frequent network, TCQSM quality-of-service bands and GeoJSON export.
+Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YusufEminoglu/transitfreq_sdk
+Project-URL: Repository, https://github.com/YusufEminoglu/transitfreq_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/transitfreq_sdk/issues
+Project-URL: Changelog, https://github.com/YusufEminoglu/transitfreq_sdk/blob/main/CHANGELOG.md
+Keywords: gtfs,transit,public-transport,headway,frequency,frequent-network,span-of-service,tcqsm,level-of-service,transport-planning,geojson,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: 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: pandas
+Requires-Dist: pandas>=1.3.0; extra == "pandas"
+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
+
+# transitfreq
+
+[![PyPI version](https://img.shields.io/pypi/v/transitfreq.svg)](https://pypi.org/project/transitfreq/)
+[![Python versions](https://img.shields.io/pypi/pyversions/transitfreq.svg)](https://pypi.org/project/transitfreq/)
+[![CI](https://github.com/YusufEminoglu/transitfreq_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/transitfreq_sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/transitfreq_sdk/blob/main/LICENSE)
+
+**Transit service frequency analysis from a GTFS Schedule feed.**
+
+`transitfreq` answers the everyday service-planning questions about a GTFS feed for
+one date: which services run, how many trips per hour each route and stop gets, what
+the average and worst headways are in a time window, how long the span of service is,
+which routes and stops form the *frequent network*, and how they fall into the
+TCQSM quality-of-service bands. Results export to CSV/JSON and to GeoJSON with the
+frequency attributes attached, ready for QGIS or a web map.
+
+- Reads a `.zip` or an unpacked folder, streaming `stop_times.txt` and `shapes.txt` with the standard `csv` module.
+- No runtime dependencies (standard library only); `pandas` is an optional extra.
+- Resolves `calendar.txt` + `calendar_dates.txt`, expands `frequencies.txt`, interpolates untimed stops, handles times past `24:00:00`.
+- Command line tool and a small, typed Python API.
+
+```bash
+pip install transitfreq            # stdlib only
+pip install "transitfreq[pandas]"  # + DataFrame helpers
+```
+
+Requires Python 3.9 or newer.
+
+> `transitfreq` does not validate feeds. Check a feed first with a validator such as
+> [`gtfslint-cli`](https://pypi.org/project/gtfslint-cli/) (`pip install gtfslint-cli`)
+> or the MobilityData GTFS Validator; broken calendars or stop times give misleading
+> frequencies.
+
+---
+
+## Quick start (command line)
+
+```bash
+# What runs on that date?
+transitfreq services gtfs.zip --date 2024-05-06
+
+# Route / direction summary for the AM peak and midday, as CSV
+transitfreq routes gtfs.zip --date 2024-05-06 \
+    --window 07:00-09:00 --window 09:00-15:00 --format csv -o routes.csv
+
+# Combined headways at each stop (platforms grouped by parent station)
+transitfreq stops gtfs.zip --date 2024-05-06 --by-station --format csv -o stops.csv
+
+# Frequent network: 10 minutes or better, 06:00-21:00, every direction
+transitfreq frequent gtfs.zip --date 2024-05-06 --threshold 10 --window 06:00-21:00
+
+# Trips per hour per route and direction
+transitfreq tph gtfs.zip --date 2024-05-06 --by route_direction --format csv
+
+# GeoJSON layers with frequency attributes
+transitfreq geojson gtfs.zip --date 2024-05-06 --stops stops.geojson --routes routes.geojson
+
+transitfreq summary gtfs.zip --date 2024-05-06
+```
+
+Common options: `--window HH:MM-HH:MM` (repeatable, default `07:00-19:00`),
+`--threshold` (frequent headway in minutes, default 15), `--frequent-window`,
+`--measure max|mean`, `--any-direction`, `--include-previous-day`,
+`--format table|csv|json`, `-o FILE`. `python -m transitfreq` works too.
+
+## Quick start (Python)
+
+```python
+import transitfreq as tf
+
+day = tf.ServiceDay("gtfs.zip", "2024-05-06")
+print(sorted(day.service_ids))
+
+for r in day.route_summaries(["07:00-09:00", "09:00-15:00"]):
+    am = r.windows[0]
+    print(r.route_name, r.direction_id, am.trips_per_hour, am.mean_headway_min,
+          am.max_headway_min, r.frequency_los[am.window], r.hours_of_service, r.hours_los)
+
+for s in day.stop_summaries(by_station=True):
+    print(s.stop_name, s.route_ids, s.windows[0].mean_headway_min, s.frequent)
+
+print(day.frequent_routes())                                    # <= 15 min, 07:00-19:00
+print(day.frequent_routes(tf.FrequentCriteria(max_headway_min=10,
+                                              windows=("06:00-21:00",))))
+
+tf.write_geojson(tf.stops_geojson(day), "stops.geojson")
+tf.write_geojson(tf.routes_geojson(day), "routes.geojson")
+```
+
+A runnable example over the bundled synthetic feed is in
+[`examples/quickstart.py`](examples/quickstart.py).
+
+## API overview
+
+| Object | Purpose |
+|---|---|
+| `GTFSFeed(path)` / `load_feed(path)` | Zip or folder; `iter_rows(file)` streams any table; cached `stops`, `routes`, `trips`, `frequencies`; `shapes(ids)` |
+| `active_service_ids(feed, date)` | `service_id`s running on a date (`calendar` + `calendar_dates`) |
+| `service_departures(feed, date, include_previous_day=False)` | Every stop event of the service day as `Departure(time, stop_id, trip_id, route_id, direction_id, stop_sequence, first_stop, boarding)`, with `frequencies.txt` expanded |
+| `ServiceDay(feed, date, ...)` | The analysis object below |
+| `.route_summaries(windows)` | `RouteSummary` per route and direction (trip start times): trips, first/last trip, span, hours of service, peak trips/h, per-window `HeadwayStats`, LOS bands, `frequent` |
+| `.stop_summaries(windows, by_station=False, route_ids=None)` | `StopSummary` per stop or parent station, all routes combined |
+| `.trips_per_hour(by)` | Hourly counts by `route`, `route_direction`, `stop` or `stop_route` |
+| `.frequent_routes(criteria)`, `.frequent_stops(criteria)` | The frequent network under a `FrequentCriteria` |
+| `.summary()` | System overview |
+| `headway_stats(times, window)`, `span_of_service(times)`, `tcqsm_hours_of_service(times)`, `trips_per_hour(times)` | Pure functions on sorted departure times |
+| `frequency_los(headway, table)`, `hours_of_service_los(hours, table)` | Quality-of-service bands; `TCQSM_*` (3rd ed.) or `TCQSM2_*` (2nd ed. letters) tables, or your own `FrequencyBand` / `HoursBand` list |
+| `stops_geojson(day)`, `routes_geojson(day)`, `write_geojson(fc, path)` | GeoJSON export |
+| `transitfreq.pandas_ext` | `departures_frame`, `stops_frame`, `routes_frame` |
+
+Every summary has `.as_dict()` giving flat columns such as `0700-0900_trips_per_hour`,
+`0700-0900_mean_headway_min`, `0700-0900_max_headway_min` and `0700-0900_frequency_los`.
+
+## Method and sources
+
+**Service calendar.** A `service_id` is active when `calendar.txt` covers the date and the
+weekday flag is 1, then `calendar_dates.txt` adds (`exception_type=1`) or removes (`2`) it
+for that date ([GTFS Schedule Reference](https://gtfs.org/documentation/schedule/reference/)).
+Feeds that use only `calendar_dates.txt` work.
+
+**Service day and times.** GTFS times count from the start of the service day and may
+exceed 24:00:00; they are kept as seconds since the start of the service day. With
+`include_previous_day=True` the after-midnight part of the previous day's trips is added,
+shifted by -24 h.
+
+**Frequency-based trips.** For each `frequencies.txt` row, trips start at
+`start_time, start_time + headway_secs, ...` strictly before `end_time`, and the template
+trip's stop-time offsets are replayed for each start. `exact_times=0` and `1` are expanded
+the same way.
+
+**Untimed stops** are interpolated linearly by stop order between the surrounding timed
+stops.
+
+**Departures that count.** At stops, only boarding opportunities count: the last stop of a
+trip and stops with `pickup_type=1` are excluded. Routes are measured at trip start times
+(the first stop of each trip), per direction.
+
+**Headway measures** for a half-open window `[start, end)` holding `n` departures:
+
+| Measure | Definition |
+|---|---|
+| trips per hour | `n / window hours` |
+| mean headway | `window minutes / n`, i.e. 60 / vehicles per hour, the TCQSM "average headway" |
+| mean gap | average interval between consecutive departures in the window |
+| max headway | longest wait for a passenger arriving at any moment in the window: largest difference in `[start, t1, ..., tn, end]` |
+
+Worked example: departures at 07:00, 07:05 and 07:30 in 07:00-08:00 give 3 trips/h, a mean
+headway of 20 min, a mean gap of 15 min and a max headway of 30 min (07:30 to 08:00).
+
+**Span and hours of service.** `span_hours` is last minus first departure.
+`hours_of_service` follows TCQSM 3rd ed., Chapter 5, p. 5-7: for service at least hourly,
+last minus first departure plus 1 h, rounded down; for hourly-or-worse service, the
+number of departures. Days that mix both are split into runs with gaps of at most 60 min
+and the first rule is applied to each run. The manual's examples are reproduced in the
+tests: every 30 min from 05:30 to 20:00 gives 15 h; departures at 5:30, 6:30, 7:30, 10:00,
+13:00, 15:30, 16:30 and 17:30 give 8 h.
+
+**Quality-of-service bands.** The default tables come from TCRP Report 165, *Transit
+Capacity and Quality of Service Manual*, 3rd ed. (TRB, 2013), Chapter 5:
+
+| Exhibit 5-2: average headway | Exhibit 5-3: hours of service |
+|---|---|
+| `<=5 min`, `>5-10 min`, `11-15 min`, `16-30 min`, `31-59 min`, `60 min`, `>60 min` | `>18 h`, `15-18 h`, `12-14 h`, `7-11 h`, `4-6 h`, `<4 h` |
+
+The 3rd edition attaches **no A-F letter grades** to these measures (p. 5-1), so band
+labels are returned. For non-integer averages the ranges are closed upward (10.5 min falls
+in `11-15 min`). For users who need letters, `TCQSM2_FREQUENCY_LOS` and `TCQSM2_HOURS_LOS`
+give the 2nd edition (TCRP Report 100, 2003) A-F grades, but these values were **not
+checked against the primary document** for this release. All thresholds are
+configurable: pass any list of `FrequencyBand` / `HoursBand` as `frequency_table=` /
+`hours_table=`.
+
+**Frequent network.** The default `FrequentCriteria()` is *15 min or better, 07:00-19:00,
+in every direction, measured by max headway*. This is a common planning convention used
+in frequent network maps (J. Walker, *Human Transit*, 2012), and TCQSM Exhibit 5-2 notes
+that 11-15 min service is "often branded as 'frequent service'". It is not a standard:
+the threshold, windows, measure (`max` or `mean`) and direction rule can all be changed.
+
+**GeoJSON.** Stops are Points with `StopSummary` attributes. Routes are one
+MultiLineString per route and direction built from every distinct `shapes.txt` shape used
+that day; trips without a `shape_id` fall back to straight segments between their stops
+(`geometry_source` tells which). Coordinates are WGS 84 longitude/latitude (RFC 7946).
+
+## Limitations
+
+- Scheduled service only: no GTFS Realtime, no reliability or headway adherence measures.
+- No feed validation (see `gtfslint-cli`), no `timezone` handling, no GTFS-Flex or `location_groups`.
+- Route-level figures use trip start times; on branching or short-turn routes, all starts in a direction are pooled.
+- Combined stop headways count every route equally, even when two routes leave within the same minute.
+- Untimed stops are interpolated by stop order, not by `shape_dist_traveled`.
+- All active stop times of the chosen date are held in memory (the whole feed is not); very large feeds need a few hundred MB for a busy weekday.
+- `exact_times=0` frequency trips are placed exactly at `start_time + k * headway_secs`.
+
+## Development
+
+```bash
+pip install -e ".[dev,pandas]"
+python -m pytest
+python -m ruff check . && python -m ruff format --check src tests
+python -m mypy src
+```
+
+The tests use a small synthetic GTFS feed in `tests/data/mini_gtfs` (frequency-based and
+scheduled trips, a holiday exception, a calendar_dates-only service, a parent station,
+untimed stops, a trip past midnight and a shape) with hand-computed expected values.
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_transitfreq,
+  author  = {Eminoğlu, Yusuf},
+  title   = {transitfreq},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/transitfreq_sdk}
+}
+```
+
+See also `CITATION.cff`.
+
+## License
+
+MIT License, copyright (c) 2026 Yusuf Eminoğlu. See [LICENSE](LICENSE).
+Contact: geospacephilo@gmail.com

transitfreq-0.1.0/README.md

@@ -0,0 +1,224 @@
+# transitfreq
+
+[![PyPI version](https://img.shields.io/pypi/v/transitfreq.svg)](https://pypi.org/project/transitfreq/)
+[![Python versions](https://img.shields.io/pypi/pyversions/transitfreq.svg)](https://pypi.org/project/transitfreq/)
+[![CI](https://github.com/YusufEminoglu/transitfreq_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/transitfreq_sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/transitfreq_sdk/blob/main/LICENSE)
+
+**Transit service frequency analysis from a GTFS Schedule feed.**
+
+`transitfreq` answers the everyday service-planning questions about a GTFS feed for
+one date: which services run, how many trips per hour each route and stop gets, what
+the average and worst headways are in a time window, how long the span of service is,
+which routes and stops form the *frequent network*, and how they fall into the
+TCQSM quality-of-service bands. Results export to CSV/JSON and to GeoJSON with the
+frequency attributes attached, ready for QGIS or a web map.
+
+- Reads a `.zip` or an unpacked folder, streaming `stop_times.txt` and `shapes.txt` with the standard `csv` module.
+- No runtime dependencies (standard library only); `pandas` is an optional extra.
+- Resolves `calendar.txt` + `calendar_dates.txt`, expands `frequencies.txt`, interpolates untimed stops, handles times past `24:00:00`.
+- Command line tool and a small, typed Python API.
+
+```bash
+pip install transitfreq            # stdlib only
+pip install "transitfreq[pandas]"  # + DataFrame helpers
+```
+
+Requires Python 3.9 or newer.
+
+> `transitfreq` does not validate feeds. Check a feed first with a validator such as
+> [`gtfslint-cli`](https://pypi.org/project/gtfslint-cli/) (`pip install gtfslint-cli`)
+> or the MobilityData GTFS Validator; broken calendars or stop times give misleading
+> frequencies.
+
+---
+
+## Quick start (command line)
+
+```bash
+# What runs on that date?
+transitfreq services gtfs.zip --date 2024-05-06
+
+# Route / direction summary for the AM peak and midday, as CSV
+transitfreq routes gtfs.zip --date 2024-05-06 \
+    --window 07:00-09:00 --window 09:00-15:00 --format csv -o routes.csv
+
+# Combined headways at each stop (platforms grouped by parent station)
+transitfreq stops gtfs.zip --date 2024-05-06 --by-station --format csv -o stops.csv
+
+# Frequent network: 10 minutes or better, 06:00-21:00, every direction
+transitfreq frequent gtfs.zip --date 2024-05-06 --threshold 10 --window 06:00-21:00
+
+# Trips per hour per route and direction
+transitfreq tph gtfs.zip --date 2024-05-06 --by route_direction --format csv
+
+# GeoJSON layers with frequency attributes
+transitfreq geojson gtfs.zip --date 2024-05-06 --stops stops.geojson --routes routes.geojson
+
+transitfreq summary gtfs.zip --date 2024-05-06
+```
+
+Common options: `--window HH:MM-HH:MM` (repeatable, default `07:00-19:00`),
+`--threshold` (frequent headway in minutes, default 15), `--frequent-window`,
+`--measure max|mean`, `--any-direction`, `--include-previous-day`,
+`--format table|csv|json`, `-o FILE`. `python -m transitfreq` works too.
+
+## Quick start (Python)
+
+```python
+import transitfreq as tf
+
+day = tf.ServiceDay("gtfs.zip", "2024-05-06")
+print(sorted(day.service_ids))
+
+for r in day.route_summaries(["07:00-09:00", "09:00-15:00"]):
+    am = r.windows[0]
+    print(r.route_name, r.direction_id, am.trips_per_hour, am.mean_headway_min,
+          am.max_headway_min, r.frequency_los[am.window], r.hours_of_service, r.hours_los)
+
+for s in day.stop_summaries(by_station=True):
+    print(s.stop_name, s.route_ids, s.windows[0].mean_headway_min, s.frequent)
+
+print(day.frequent_routes())                                    # <= 15 min, 07:00-19:00
+print(day.frequent_routes(tf.FrequentCriteria(max_headway_min=10,
+                                              windows=("06:00-21:00",))))
+
+tf.write_geojson(tf.stops_geojson(day), "stops.geojson")
+tf.write_geojson(tf.routes_geojson(day), "routes.geojson")
+```
+
+A runnable example over the bundled synthetic feed is in
+[`examples/quickstart.py`](examples/quickstart.py).
+
+## API overview
+
+| Object | Purpose |
+|---|---|
+| `GTFSFeed(path)` / `load_feed(path)` | Zip or folder; `iter_rows(file)` streams any table; cached `stops`, `routes`, `trips`, `frequencies`; `shapes(ids)` |
+| `active_service_ids(feed, date)` | `service_id`s running on a date (`calendar` + `calendar_dates`) |
+| `service_departures(feed, date, include_previous_day=False)` | Every stop event of the service day as `Departure(time, stop_id, trip_id, route_id, direction_id, stop_sequence, first_stop, boarding)`, with `frequencies.txt` expanded |
+| `ServiceDay(feed, date, ...)` | The analysis object below |
+| `.route_summaries(windows)` | `RouteSummary` per route and direction (trip start times): trips, first/last trip, span, hours of service, peak trips/h, per-window `HeadwayStats`, LOS bands, `frequent` |
+| `.stop_summaries(windows, by_station=False, route_ids=None)` | `StopSummary` per stop or parent station, all routes combined |
+| `.trips_per_hour(by)` | Hourly counts by `route`, `route_direction`, `stop` or `stop_route` |
+| `.frequent_routes(criteria)`, `.frequent_stops(criteria)` | The frequent network under a `FrequentCriteria` |
+| `.summary()` | System overview |
+| `headway_stats(times, window)`, `span_of_service(times)`, `tcqsm_hours_of_service(times)`, `trips_per_hour(times)` | Pure functions on sorted departure times |
+| `frequency_los(headway, table)`, `hours_of_service_los(hours, table)` | Quality-of-service bands; `TCQSM_*` (3rd ed.) or `TCQSM2_*` (2nd ed. letters) tables, or your own `FrequencyBand` / `HoursBand` list |
+| `stops_geojson(day)`, `routes_geojson(day)`, `write_geojson(fc, path)` | GeoJSON export |
+| `transitfreq.pandas_ext` | `departures_frame`, `stops_frame`, `routes_frame` |
+
+Every summary has `.as_dict()` giving flat columns such as `0700-0900_trips_per_hour`,
+`0700-0900_mean_headway_min`, `0700-0900_max_headway_min` and `0700-0900_frequency_los`.
+
+## Method and sources
+
+**Service calendar.** A `service_id` is active when `calendar.txt` covers the date and the
+weekday flag is 1, then `calendar_dates.txt` adds (`exception_type=1`) or removes (`2`) it
+for that date ([GTFS Schedule Reference](https://gtfs.org/documentation/schedule/reference/)).
+Feeds that use only `calendar_dates.txt` work.
+
+**Service day and times.** GTFS times count from the start of the service day and may
+exceed 24:00:00; they are kept as seconds since the start of the service day. With
+`include_previous_day=True` the after-midnight part of the previous day's trips is added,
+shifted by -24 h.
+
+**Frequency-based trips.** For each `frequencies.txt` row, trips start at
+`start_time, start_time + headway_secs, ...` strictly before `end_time`, and the template
+trip's stop-time offsets are replayed for each start. `exact_times=0` and `1` are expanded
+the same way.
+
+**Untimed stops** are interpolated linearly by stop order between the surrounding timed
+stops.
+
+**Departures that count.** At stops, only boarding opportunities count: the last stop of a
+trip and stops with `pickup_type=1` are excluded. Routes are measured at trip start times
+(the first stop of each trip), per direction.
+
+**Headway measures** for a half-open window `[start, end)` holding `n` departures:
+
+| Measure | Definition |
+|---|---|
+| trips per hour | `n / window hours` |
+| mean headway | `window minutes / n`, i.e. 60 / vehicles per hour, the TCQSM "average headway" |
+| mean gap | average interval between consecutive departures in the window |
+| max headway | longest wait for a passenger arriving at any moment in the window: largest difference in `[start, t1, ..., tn, end]` |
+
+Worked example: departures at 07:00, 07:05 and 07:30 in 07:00-08:00 give 3 trips/h, a mean
+headway of 20 min, a mean gap of 15 min and a max headway of 30 min (07:30 to 08:00).
+
+**Span and hours of service.** `span_hours` is last minus first departure.
+`hours_of_service` follows TCQSM 3rd ed., Chapter 5, p. 5-7: for service at least hourly,
+last minus first departure plus 1 h, rounded down; for hourly-or-worse service, the
+number of departures. Days that mix both are split into runs with gaps of at most 60 min
+and the first rule is applied to each run. The manual's examples are reproduced in the
+tests: every 30 min from 05:30 to 20:00 gives 15 h; departures at 5:30, 6:30, 7:30, 10:00,
+13:00, 15:30, 16:30 and 17:30 give 8 h.
+
+**Quality-of-service bands.** The default tables come from TCRP Report 165, *Transit
+Capacity and Quality of Service Manual*, 3rd ed. (TRB, 2013), Chapter 5:
+
+| Exhibit 5-2: average headway | Exhibit 5-3: hours of service |
+|---|---|
+| `<=5 min`, `>5-10 min`, `11-15 min`, `16-30 min`, `31-59 min`, `60 min`, `>60 min` | `>18 h`, `15-18 h`, `12-14 h`, `7-11 h`, `4-6 h`, `<4 h` |
+
+The 3rd edition attaches **no A-F letter grades** to these measures (p. 5-1), so band
+labels are returned. For non-integer averages the ranges are closed upward (10.5 min falls
+in `11-15 min`). For users who need letters, `TCQSM2_FREQUENCY_LOS` and `TCQSM2_HOURS_LOS`
+give the 2nd edition (TCRP Report 100, 2003) A-F grades, but these values were **not
+checked against the primary document** for this release. All thresholds are
+configurable: pass any list of `FrequencyBand` / `HoursBand` as `frequency_table=` /
+`hours_table=`.
+
+**Frequent network.** The default `FrequentCriteria()` is *15 min or better, 07:00-19:00,
+in every direction, measured by max headway*. This is a common planning convention used
+in frequent network maps (J. Walker, *Human Transit*, 2012), and TCQSM Exhibit 5-2 notes
+that 11-15 min service is "often branded as 'frequent service'". It is not a standard:
+the threshold, windows, measure (`max` or `mean`) and direction rule can all be changed.
+
+**GeoJSON.** Stops are Points with `StopSummary` attributes. Routes are one
+MultiLineString per route and direction built from every distinct `shapes.txt` shape used
+that day; trips without a `shape_id` fall back to straight segments between their stops
+(`geometry_source` tells which). Coordinates are WGS 84 longitude/latitude (RFC 7946).
+
+## Limitations
+
+- Scheduled service only: no GTFS Realtime, no reliability or headway adherence measures.
+- No feed validation (see `gtfslint-cli`), no `timezone` handling, no GTFS-Flex or `location_groups`.
+- Route-level figures use trip start times; on branching or short-turn routes, all starts in a direction are pooled.
+- Combined stop headways count every route equally, even when two routes leave within the same minute.
+- Untimed stops are interpolated by stop order, not by `shape_dist_traveled`.
+- All active stop times of the chosen date are held in memory (the whole feed is not); very large feeds need a few hundred MB for a busy weekday.
+- `exact_times=0` frequency trips are placed exactly at `start_time + k * headway_secs`.
+
+## Development
+
+```bash
+pip install -e ".[dev,pandas]"
+python -m pytest
+python -m ruff check . && python -m ruff format --check src tests
+python -m mypy src
+```
+
+The tests use a small synthetic GTFS feed in `tests/data/mini_gtfs` (frequency-based and
+scheduled trips, a holiday exception, a calendar_dates-only service, a parent station,
+untimed stops, a trip past midnight and a shape) with hand-computed expected values.
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_transitfreq,
+  author  = {Eminoğlu, Yusuf},
+  title   = {transitfreq},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/transitfreq_sdk}
+}
+```
+
+See also `CITATION.cff`.
+
+## License
+
+MIT License, copyright (c) 2026 Yusuf Eminoğlu. See [LICENSE](LICENSE).
+Contact: geospacephilo@gmail.com

transitfreq-0.1.0/examples/quickstart.py

@@ -0,0 +1,48 @@
+"""Quick start: analyse the small synthetic GTFS feed shipped with the tests.
+
+Run from the repository root:
+
+    python examples/quickstart.py [path/to/gtfs.zip] [YYYY-MM-DD]
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import transitfreq as tf
+
+HERE = Path(__file__).resolve().parent
+feed = sys.argv[1] if len(sys.argv) > 1 else HERE.parent / "tests" / "data" / "mini_gtfs"
+date = sys.argv[2] if len(sys.argv) > 2 else "2024-05-06"
+
+day = tf.ServiceDay(feed, date)
+print(f"Service on {day.date}: {sorted(day.service_ids)}")
+
+print("\nRoutes (trip starts), AM peak and midday:")
+for r in day.route_summaries(["07:00-09:00", "09:00-15:00"]):
+    am, mid = r.windows
+    print(
+        f"  route {r.route_name:>3} dir {r.direction_id}: {r.n_trips:3d} trips, "
+        f"AM {am.trips_per_hour:4.1f} trips/h ({r.frequency_los[am.window]}), "
+        f"midday max headway {mid.max_headway_min:5.1f} min, "
+        f"{r.hours_of_service} h of service ({r.hours_los})"
+    )
+
+print("\nStops, combined across routes, 07:00-19:00:")
+for s in day.stop_summaries(by_station=True):
+    w = s.windows[0]
+    print(
+        f"  {s.stop_name:<16} routes={','.join(s.route_ids):<6} "
+        f"mean headway={w.mean_headway_min or float('nan'):5.1f} min  frequent={s.frequent}"
+    )
+
+print("\nFrequent network (<= 15 min, 07:00-19:00):", day.frequent_routes())
+ten = tf.FrequentCriteria(max_headway_min=10, windows=("07:00-09:00", "16:00-18:00"))
+print("Routes with <= 10 min peak service:", day.frequent_routes(ten))
+
+out = HERE / "out"
+out.mkdir(exist_ok=True)
+tf.write_geojson(tf.stops_geojson(day), out / "stops.geojson")
+tf.write_geojson(tf.routes_geojson(day), out / "routes.geojson")
+print(f"\nGeoJSON written to {out}")