transitfreq 0.1.0__py3-none-any.whl

transitfreq/__init__.py

@@ -0,0 +1,74 @@
+"""transitfreq: transit service frequency analysis from GTFS Schedule feeds.
+
+Quick start::
+
+    import transitfreq as tf
+
+    day = tf.ServiceDay("gtfs.zip", "2024-05-06")
+    for r in day.route_summaries(["07:00-09:00", "09:00-15:00"]):
+        print(r.route_name, r.direction_id, r.windows[0].mean_headway_min, r.hours_los)
+    print(day.frequent_routes())
+    tf.write_geojson(tf.stops_geojson(day), "stops.geojson")
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .analysis import FrequentCriteria, RouteSummary, ServiceDay, StopSummary, service_day
+from .errors import GTFSError
+from .feed import GTFSFeed, load_feed
+from .geojson import routes_geojson, stops_geojson, write_geojson
+from .headway import (
+    HeadwayStats,
+    Span,
+    headway_stats,
+    span_of_service,
+    tcqsm_hours_of_service,
+    trips_per_hour,
+)
+from .los import (
+    TCQSM2_FREQUENCY_LOS,
+    TCQSM2_HOURS_LOS,
+    TCQSM_FREQUENCY_LOS,
+    TCQSM_HOURS_LOS,
+    FrequencyBand,
+    HoursBand,
+    frequency_los,
+    hours_of_service_los,
+)
+from .schedule import Departure, active_service_ids, service_departures
+from .timeutil import format_time, parse_time
+
+__all__ = [
+    "__version__",
+    "Departure",
+    "FrequencyBand",
+    "FrequentCriteria",
+    "GTFSError",
+    "GTFSFeed",
+    "HeadwayStats",
+    "HoursBand",
+    "RouteSummary",
+    "ServiceDay",
+    "Span",
+    "StopSummary",
+    "TCQSM2_FREQUENCY_LOS",
+    "TCQSM2_HOURS_LOS",
+    "TCQSM_FREQUENCY_LOS",
+    "TCQSM_HOURS_LOS",
+    "active_service_ids",
+    "format_time",
+    "frequency_los",
+    "headway_stats",
+    "hours_of_service_los",
+    "load_feed",
+    "parse_time",
+    "routes_geojson",
+    "service_day",
+    "service_departures",
+    "span_of_service",
+    "stops_geojson",
+    "tcqsm_hours_of_service",
+    "trips_per_hour",
+    "write_geojson",
+]

transitfreq/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m transitfreq``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

transitfreq/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

transitfreq/analysis.py

@@ -0,0 +1,407 @@
+"""Service-day frequency analysis: stops, routes, the frequent network and LOS."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple, Union
+
+from .feed import GTFSFeed, PathLike
+from .headway import HeadwayStats, headway_stats, span_of_service, trips_per_hour
+from .los import (
+    TCQSM_FREQUENCY_LOS,
+    TCQSM_HOURS_LOS,
+    FrequencyBand,
+    HoursBand,
+    frequency_los,
+    hours_of_service_los,
+)
+from .schedule import Departure, active_service_ids, service_departures
+from .timeutil import DateLike, Window, format_time, parse_date, parse_windows, window_label
+
+WindowSpec = Union[str, Sequence[object]]
+RouteKey = Tuple[str, Optional[int]]
+
+DEFAULT_WINDOWS: Tuple[str, ...] = ("07:00-19:00",)
+
+
+@dataclass(frozen=True)
+class FrequentCriteria:
+    """Definition of "frequent service" (configurable; there is no universal standard).
+
+    The default, a headway of **15 minutes or better from 07:00 to 19:00**, is a common
+    planning convention for "frequent network" maps (see J. Walker, *Human Transit*,
+    Island Press, 2012; TCQSM 3rd ed. Exhibit 5-2 notes that 11-15 min service is "often
+    branded as 'frequent service'"). Agencies use other values (10 or 12 min,
+    06:00-22:00, weekends ...), so every field is configurable.
+
+    Attributes
+    ----------
+    max_headway_min:
+        Threshold in minutes.
+    windows:
+        Time windows (``"HH:MM-HH:MM"``) that must *all* satisfy the threshold.
+    measure:
+        ``"max"`` (default; the longest wait in each window must not exceed the
+        threshold, see :mod:`transitfreq.headway`) or ``"mean"`` (average headway).
+    all_directions:
+        For routes, require every operated direction to qualify (default ``True``).
+    """
+
+    max_headway_min: float = 15.0
+    windows: Tuple[str, ...] = DEFAULT_WINDOWS
+    measure: str = "max"
+    all_directions: bool = True
+
+    def __post_init__(self) -> None:
+        if self.measure not in ("max", "mean"):
+            raise ValueError("measure must be 'max' or 'mean'")
+        if self.max_headway_min <= 0:
+            raise ValueError("max_headway_min must be positive")
+
+    def parsed_windows(self) -> List[Window]:
+        """Windows in seconds."""
+        return parse_windows(list(self.windows))
+
+    def is_met(self, times: Sequence[int]) -> bool:
+        """Whether sorted departure ``times`` meet the criteria in every window."""
+        for w in self.parsed_windows():
+            st = headway_stats(times, w)
+            if st.n_departures == 0:
+                return False
+            value = st.max_headway_min if self.measure == "max" else st.mean_headway_min
+            if value is None or value > self.max_headway_min + 1e-9:
+                return False
+        return True
+
+
+def _flatten_windows(stats: Sequence[HeadwayStats], los: Dict[str, str]) -> Dict[str, object]:
+    out: Dict[str, object] = {}
+    for st in stats:
+        p = st.window.replace(":", "")
+        out[f"{p}_departures"] = st.n_departures
+        out[f"{p}_trips_per_hour"] = round(st.trips_per_hour, 3)
+        out[f"{p}_mean_headway_min"] = _r(st.mean_headway_min)
+        out[f"{p}_max_headway_min"] = _r(st.max_headway_min)
+        out[f"{p}_frequency_los"] = los.get(st.window, "")
+    return out
+
+
+def _r(v: Optional[float]) -> Optional[float]:
+    return None if v is None else round(v, 2)
+
+
+@dataclass(frozen=True)
+class StopSummary:
+    """Combined service at a stop (or station) across all routes."""
+
+    stop_id: str
+    stop_name: str
+    lat: Optional[float]
+    lon: Optional[float]
+    n_departures: int
+    route_ids: Tuple[str, ...]
+    first_departure: Optional[int]
+    last_departure: Optional[int]
+    span_hours: float
+    hours_of_service: int
+    peak_trips_per_hour: int
+    windows: Tuple[HeadwayStats, ...] = field(default=())
+    frequency_los: Dict[str, str] = field(default_factory=dict)
+    hours_los: str = ""
+    frequent: bool = False
+
+    def as_dict(self) -> Dict[str, object]:
+        """Flat dict for CSV/JSON/GeoJSON properties (times as ``HH:MM:SS``)."""
+        d: Dict[str, object] = {
+            "stop_id": self.stop_id,
+            "stop_name": self.stop_name,
+            "lat": self.lat,
+            "lon": self.lon,
+            "n_departures": self.n_departures,
+            "n_routes": len(self.route_ids),
+            "route_ids": " ".join(self.route_ids),
+            "first_departure": format_time(self.first_departure),
+            "last_departure": format_time(self.last_departure),
+            "span_hours": round(self.span_hours, 2),
+            "hours_of_service": self.hours_of_service,
+            "peak_trips_per_hour": self.peak_trips_per_hour,
+        }
+        d.update(_flatten_windows(self.windows, self.frequency_los))
+        d["hours_los"] = self.hours_los
+        d["frequent"] = self.frequent
+        return d
+
+
+@dataclass(frozen=True)
+class RouteSummary:
+    """Service of one route in one direction, measured at trip start times."""
+
+    route_id: str
+    route_name: str
+    route_type: int
+    direction_id: Optional[int]
+    n_trips: int
+    first_departure: Optional[int]
+    last_departure: Optional[int]
+    span_hours: float
+    hours_of_service: int
+    peak_trips_per_hour: int
+    windows: Tuple[HeadwayStats, ...] = field(default=())
+    frequency_los: Dict[str, str] = field(default_factory=dict)
+    hours_los: str = ""
+    frequent: bool = False
+
+    def as_dict(self) -> Dict[str, object]:
+        """Flat dict for CSV/JSON/GeoJSON properties (times as ``HH:MM:SS``)."""
+        d: Dict[str, object] = {
+            "route_id": self.route_id,
+            "route_name": self.route_name,
+            "route_type": self.route_type,
+            "direction_id": "" if self.direction_id is None else self.direction_id,
+            "n_trips": self.n_trips,
+            "first_departure": format_time(self.first_departure),
+            "last_departure": format_time(self.last_departure),
+            "span_hours": round(self.span_hours, 2),
+            "hours_of_service": self.hours_of_service,
+            "peak_trips_per_hour": self.peak_trips_per_hour,
+        }
+        d.update(_flatten_windows(self.windows, self.frequency_los))
+        d["hours_los"] = self.hours_los
+        d["frequent"] = self.frequent
+        return d
+
+
+class ServiceDay:
+    """All scheduled service of one date in a GTFS feed, ready for frequency analysis.
+
+    Parameters
+    ----------
+    feed:
+        A :class:`~transitfreq.feed.GTFSFeed` or a path to a feed (zip or folder).
+    date:
+        The service date (``YYYY-MM-DD``, ``YYYYMMDD`` or :class:`datetime.date`).
+    include_previous_day:
+        Add after-midnight trips of the previous service day (see
+        :func:`~transitfreq.schedule.service_departures`).
+    frequency_table, hours_table:
+        LOS tables (default TCQSM 3rd ed. Exhibits 5-2 and 5-3).
+    criteria:
+        :class:`FrequentCriteria` used for the ``frequent`` flags.
+    """
+
+    def __init__(
+        self,
+        feed: Union[GTFSFeed, PathLike],
+        date: DateLike,
+        *,
+        include_previous_day: bool = False,
+        frequency_table: Sequence[FrequencyBand] = TCQSM_FREQUENCY_LOS,
+        hours_table: Sequence[HoursBand] = TCQSM_HOURS_LOS,
+        criteria: Optional[FrequentCriteria] = None,
+    ) -> None:
+        self.feed = feed if isinstance(feed, GTFSFeed) else GTFSFeed(feed)
+        self.date = parse_date(date)
+        self.service_ids: Set[str] = active_service_ids(self.feed, self.date)
+        self.departures: List[Departure] = service_departures(
+            self.feed, self.date, include_previous_day=include_previous_day
+        )
+        self.frequency_table = frequency_table
+        self.hours_table = hours_table
+        self.criteria = criteria or FrequentCriteria()
+
+    # ------------------------------------------------------------------ grouping
+    def _station_of(self, stop_id: str) -> str:
+        stop = self.feed.stops.get(stop_id)
+        return stop.parent_station if stop and stop.parent_station else stop_id
+
+    def stop_departure_times(
+        self, *, by_station: bool = False, route_ids: Optional[Iterable[str]] = None
+    ) -> Dict[str, List[int]]:
+        """Sorted boarding times per stop (or parent station), all routes combined."""
+        keep = set(route_ids) if route_ids is not None else None
+        out: Dict[str, List[int]] = defaultdict(list)
+        for d in self.departures:
+            if not d.boarding or (keep is not None and d.route_id not in keep):
+                continue
+            key = self._station_of(d.stop_id) if by_station else d.stop_id
+            out[key].append(d.time)
+        return {k: sorted(v) for k, v in out.items()}
+
+    def route_start_times(self) -> Dict[RouteKey, List[int]]:
+        """Sorted trip start times per ``(route_id, direction_id)``."""
+        out: Dict[RouteKey, List[int]] = defaultdict(list)
+        for d in self.departures:
+            if d.first_stop:
+                out[(d.route_id, d.direction_id)].append(d.time)
+        return {k: sorted(v) for k, v in out.items()}
+
+    def trips_per_hour(self, by: str = "route") -> Dict[object, List[int]]:
+        """Departures per clock hour.
+
+        ``by`` is ``"route"`` (trip starts per route), ``"route_direction"`` (keys are
+        ``(route_id, direction_id)``), ``"stop"`` (boardings per stop, all routes) or
+        ``"stop_route"`` (keys are ``(stop_id, route_id)``).
+        """
+        groups: Dict[object, List[int]] = defaultdict(list)
+        for d in self.departures:
+            if by == "route":
+                if d.first_stop:
+                    groups[d.route_id].append(d.time)
+            elif by == "route_direction":
+                if d.first_stop:
+                    groups[(d.route_id, d.direction_id)].append(d.time)
+            elif by == "stop":
+                if d.boarding:
+                    groups[d.stop_id].append(d.time)
+            elif by == "stop_route":
+                if d.boarding:
+                    groups[(d.stop_id, d.route_id)].append(d.time)
+            else:
+                raise ValueError("by must be 'route', 'route_direction', 'stop' or 'stop_route'")
+        hours = max([24] + [max(v) // 3600 + 1 for v in groups.values() if v])
+        return {k: trips_per_hour(v, hours=hours) for k, v in groups.items()}
+
+    # ------------------------------------------------------------------ summaries
+    def _windows(self, windows: Optional[Sequence[WindowSpec]]) -> List[Window]:
+        return parse_windows(list(windows) if windows else list(DEFAULT_WINDOWS))
+
+    def _measure(
+        self, times: List[int], windows: List[Window]
+    ) -> Tuple[Tuple[HeadwayStats, ...], Dict[str, str], int]:
+        stats = tuple(headway_stats(times, w) for w in windows)
+        los = {s.window: frequency_los(s.mean_headway_min, self.frequency_table) for s in stats}
+        peak = max(trips_per_hour(times)) if times else 0
+        return stats, los, peak
+
+    def stop_summaries(
+        self,
+        windows: Optional[Sequence[WindowSpec]] = None,
+        *,
+        by_station: bool = False,
+        route_ids: Optional[Iterable[str]] = None,
+    ) -> List[StopSummary]:
+        """Combined headways across routes at each served stop (or parent station).
+
+        Only boarding events count (not the last stop of a trip, not ``pickup_type=1``).
+        """
+        wins = self._windows(windows)
+        stops = self.feed.stops
+        rmap: Dict[str, Set[str]] = defaultdict(set)
+        keep = set(route_ids) if route_ids is not None else None
+        for d in self.departures:
+            if d.boarding and (keep is None or d.route_id in keep):
+                rmap[self._station_of(d.stop_id) if by_station else d.stop_id].add(d.route_id)
+        out: List[StopSummary] = []
+        for sid, times in sorted(
+            self.stop_departure_times(by_station=by_station, route_ids=route_ids).items()
+        ):
+            stats, los, peak = self._measure(times, wins)
+            sp = span_of_service(times)
+            stop = stops.get(sid)
+            out.append(
+                StopSummary(
+                    stop_id=sid,
+                    stop_name=stop.name if stop else "",
+                    lat=stop.lat if stop else None,
+                    lon=stop.lon if stop else None,
+                    n_departures=len(times),
+                    route_ids=tuple(sorted(rmap[sid])),
+                    first_departure=sp.first,
+                    last_departure=sp.last,
+                    span_hours=sp.span_hours,
+                    hours_of_service=sp.hours_of_service,
+                    peak_trips_per_hour=peak,
+                    windows=stats,
+                    frequency_los=los,
+                    hours_los=hours_of_service_los(sp.hours_of_service, self.hours_table),
+                    frequent=self.criteria.is_met(times),
+                )
+            )
+        return out
+
+    def route_summaries(self, windows: Optional[Sequence[WindowSpec]] = None) -> List[RouteSummary]:
+        """Service summary per route and direction, measured at trip start times.
+
+        Trip start times (first stop of each trip) are used as the reference, which is
+        exact for simple routes; for routes with short-turn or branch patterns all starts
+        are pooled per direction.
+        """
+        wins = self._windows(windows)
+        routes = self.feed.routes
+        out: List[RouteSummary] = []
+        items = sorted(
+            self.route_start_times().items(),
+            key=lambda kv: (kv[0][0], -1 if kv[0][1] is None else kv[0][1]),
+        )
+        for (rid, did), times in items:
+            stats, los, peak = self._measure(times, wins)
+            sp = span_of_service(times)
+            route = routes.get(rid)
+            out.append(
+                RouteSummary(
+                    route_id=rid,
+                    route_name=route.name if route else rid,
+                    route_type=route.route_type if route else -1,
+                    direction_id=did,
+                    n_trips=len(times),
+                    first_departure=sp.first,
+                    last_departure=sp.last,
+                    span_hours=sp.span_hours,
+                    hours_of_service=sp.hours_of_service,
+                    peak_trips_per_hour=peak,
+                    windows=stats,
+                    frequency_los=los,
+                    hours_los=hours_of_service_los(sp.hours_of_service, self.hours_table),
+                    frequent=self.criteria.is_met(times),
+                )
+            )
+        return out
+
+    # ------------------------------------------------------------------ frequent network
+    def frequent_routes(self, criteria: Optional[FrequentCriteria] = None) -> List[str]:
+        """Route ids that meet ``criteria`` (default: the day's :class:`FrequentCriteria`)."""
+        crit = criteria or self.criteria
+        per_route: Dict[str, List[bool]] = defaultdict(list)
+        for (rid, _), times in self.route_start_times().items():
+            per_route[rid].append(crit.is_met(times))
+        return sorted(
+            rid for rid, flags in per_route.items() if (all if crit.all_directions else any)(flags)
+        )
+
+    def frequent_stops(
+        self, criteria: Optional[FrequentCriteria] = None, *, by_station: bool = False
+    ) -> List[str]:
+        """Stops whose combined service (all routes) meets ``criteria``."""
+        crit = criteria or self.criteria
+        return sorted(
+            sid
+            for sid, times in self.stop_departure_times(by_station=by_station).items()
+            if crit.is_met(times)
+        )
+
+    def summary(self, windows: Optional[Sequence[WindowSpec]] = None) -> Dict[str, object]:
+        """System-level overview of the day."""
+        starts = [d.time for d in self.departures if d.first_stop]
+        sp = span_of_service(starts)
+        routes = self.route_summaries(windows)
+        return {
+            "date": self.date.isoformat(),
+            "service_ids": sorted(self.service_ids),
+            "n_trips": len(starts),
+            "n_routes": len({r.route_id for r in routes}),
+            "n_stops_served": len(self.stop_departure_times()),
+            "first_departure": format_time(sp.first),
+            "last_departure": format_time(sp.last),
+            "frequent_routes": self.frequent_routes(),
+            "criteria": {
+                "max_headway_min": self.criteria.max_headway_min,
+                "windows": [window_label(w) for w in self.criteria.parsed_windows()],
+                "measure": self.criteria.measure,
+            },
+        }
+
+
+def service_day(feed: Union[GTFSFeed, PathLike], date: DateLike, **kwargs: object) -> ServiceDay:
+    """Shortcut for :class:`ServiceDay` ``(feed, date, **kwargs)``."""
+    return ServiceDay(feed, date, **kwargs)  # type: ignore[arg-type]

transitfreq/cli.py

@@ -0,0 +1,191 @@
+"""Command line interface: ``transitfreq <command> FEED --date YYYY-MM-DD``."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from typing import Dict, List, Optional, Sequence, TextIO
+
+from ._version import __version__
+from .analysis import FrequentCriteria, ServiceDay
+from .errors import GTFSError
+from .geojson import routes_geojson, stops_geojson, write_geojson
+from .schedule import active_service_ids
+from .timeutil import format_time
+
+
+def _write_rows(rows: List[Dict[str, object]], fmt: str, out: TextIO) -> None:
+    if fmt == "json":
+        json.dump(rows, out, ensure_ascii=False, indent=1)
+        out.write("\n")
+        return
+    if not rows:
+        return
+    fields: List[str] = []
+    for r in rows:
+        for k in r:
+            if k not in fields:
+                fields.append(k)
+    if fmt == "csv":
+        w = csv.DictWriter(out, fieldnames=fields, lineterminator="\n")
+        w.writeheader()
+        w.writerows(rows)
+        return
+    # plain table
+    cells = [[("" if r.get(f) is None else str(r.get(f, ""))) for f in fields] for r in rows]
+    widths = [max(len(f), *(len(c[i]) for c in cells)) for i, f in enumerate(fields)]
+    out.write("  ".join(f.ljust(widths[i]) for i, f in enumerate(fields)).rstrip() + "\n")
+    for c in cells:
+        out.write("  ".join(v.ljust(widths[i]) for i, v in enumerate(c)).rstrip() + "\n")
+
+
+def _emit(rows: List[Dict[str, object]], args: argparse.Namespace) -> None:
+    if args.output:
+        with open(args.output, "w", encoding="utf-8", newline="") as fh:
+            _write_rows(rows, args.format if args.format != "table" else "csv", fh)
+    else:
+        _write_rows(rows, args.format, sys.stdout)
+
+
+def _criteria(args: argparse.Namespace) -> FrequentCriteria:
+    return FrequentCriteria(
+        max_headway_min=args.threshold,
+        windows=tuple(args.frequent_window or args.window or ("07:00-19:00",)),
+        measure=args.measure,
+        all_directions=not args.any_direction,
+    )
+
+
+def _day(args: argparse.Namespace) -> ServiceDay:
+    return ServiceDay(
+        args.feed,
+        args.date,
+        include_previous_day=args.include_previous_day,
+        criteria=_criteria(args),
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Argument parser (exposed for documentation and tests)."""
+    p = argparse.ArgumentParser(
+        prog="transitfreq",
+        description="Transit service frequency analysis from a GTFS Schedule feed.",
+    )
+    p.add_argument("--version", action="version", version=f"transitfreq {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("feed", help="GTFS feed (.zip or folder)")
+    common.add_argument("--date", required=True, help="service date, YYYY-MM-DD or YYYYMMDD")
+    common.add_argument(
+        "--window",
+        action="append",
+        metavar="HH:MM-HH:MM",
+        help="analysis window (repeatable; default 07:00-19:00)",
+    )
+    common.add_argument(
+        "--include-previous-day",
+        action="store_true",
+        help="add after-midnight trips of the previous service day",
+    )
+    common.add_argument(
+        "--threshold", type=float, default=15.0, help="frequent headway in minutes (15)"
+    )
+    common.add_argument(
+        "--frequent-window",
+        action="append",
+        metavar="HH:MM-HH:MM",
+        help="windows for the frequent test (default: --window, else 07:00-19:00)",
+    )
+    common.add_argument("--measure", choices=("max", "mean"), default="max")
+    common.add_argument(
+        "--any-direction", action="store_true", help="a route is frequent if any direction is"
+    )
+    common.add_argument("--format", choices=("table", "csv", "json"), default="table")
+    common.add_argument("-o", "--output", help="write to this file instead of stdout")
+
+    sub.add_parser("summary", parents=[common], help="system overview of the day")
+    sub.add_parser("services", parents=[common], help="service_ids active on the date")
+    sub.add_parser("routes", parents=[common], help="per route-direction summary")
+    sp = sub.add_parser("stops", parents=[common], help="combined headways per stop")
+    sp.add_argument("--by-station", action="store_true", help="group platforms by parent")
+    sub.add_parser("frequent", parents=[common], help="frequent routes and stops")
+    tp = sub.add_parser("tph", parents=[common], help="trips per hour table")
+    tp.add_argument(
+        "--by", choices=("route", "route_direction", "stop", "stop_route"), default="route"
+    )
+    gp = sub.add_parser("geojson", parents=[common], help="export stops/routes GeoJSON")
+    gp.add_argument("--stops", help="output path for stops GeoJSON")
+    gp.add_argument("--routes", help="output path for routes GeoJSON")
+    gp.add_argument("--by-station", action="store_true")
+    return p
+
+
+def run(args: argparse.Namespace) -> int:
+    """Execute a parsed command; returns the exit code."""
+    cmd = args.command
+    if cmd == "services":
+        services: List[Dict[str, object]] = [
+            {"service_id": s} for s in active_service_ids_for(args)
+        ]
+        _emit(services, args)
+        return 0
+    day = _day(args)
+    if cmd == "summary":
+        info = day.summary(args.window)
+        if args.format == "json" or args.output:
+            _emit([info], args)
+        else:
+            for k, v in info.items():
+                print(f"{k}: {v}")
+    elif cmd == "routes":
+        _emit([r.as_dict() for r in day.route_summaries(args.window)], args)
+    elif cmd == "stops":
+        _emit(
+            [s.as_dict() for s in day.stop_summaries(args.window, by_station=args.by_station)],
+            args,
+        )
+    elif cmd == "frequent":
+        rows: List[Dict[str, object]] = []
+        rows.extend({"kind": "route", "id": r} for r in day.frequent_routes())
+        rows.extend({"kind": "stop", "id": s} for s in day.frequent_stops())
+        _emit(rows, args)
+    elif cmd == "tph":
+        rows = []
+        for key, counts in sorted(day.trips_per_hour(args.by).items(), key=lambda kv: str(kv[0])):
+            label = key if isinstance(key, str) else "|".join(str(k) for k in key)  # type: ignore[attr-defined]
+            row: Dict[str, object] = {"key": label}
+            for h, c in enumerate(counts):
+                row[format_time(h * 3600)[:5]] = c
+            rows.append(row)
+        _emit(rows, args)
+    elif cmd == "geojson":
+        if not args.stops and not args.routes:
+            print("geojson: give --stops and/or --routes output paths", file=sys.stderr)
+            return 2
+        if args.stops:
+            write_geojson(stops_geojson(day, args.window, by_station=args.by_station), args.stops)
+        if args.routes:
+            write_geojson(routes_geojson(day, args.window), args.routes)
+    return 0
+
+
+def active_service_ids_for(args: argparse.Namespace) -> List[str]:
+    """Active service ids for the parsed ``feed``/``date`` arguments."""
+    from .feed import GTFSFeed
+
+    with GTFSFeed(args.feed) as feed:
+        return sorted(active_service_ids(feed, args.date))
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point of the ``transitfreq`` console script."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return run(args)
+    except (GTFSError, ValueError, OSError) as exc:
+        print(f"transitfreq: error: {exc}", file=sys.stderr)
+        return 1

transitfreq/errors.py

@@ -0,0 +1,7 @@
+"""Exceptions raised by transitfreq."""
+
+from __future__ import annotations
+
+
+class GTFSError(ValueError):
+    """A GTFS feed is missing a required file/column or contains an invalid value."""