parkingstudy 0.1.0__py3-none-any.whl

parkingstudy/__init__.py

@@ -0,0 +1,137 @@
+"""parkingstudy: parking occupancy and turnover survey analysis.
+
+Quick start::
+
+    from parkingstudy import read_inventory, read_counts, capacity_assessment
+
+    inv = read_inventory("inventory.csv")
+    counts = read_counts("counts.csv")
+    for row in capacity_assessment(inv, counts, by="zone", target=0.85):
+        print(row.key, row.peak_occupied, row.effective_capacity, row.above_target)
+
+Licence plates are anonymised on input with a salted keyed hash
+(:class:`PlateHasher`); raw plates are never stored or written.
+"""
+
+from ._time import parse_beat, parse_windows
+from ._version import __version__
+from .errors import DataError, ParkingStudyError, PrivacyError
+from .geojson import JoinResult, join_to_geojson, load_geojson, rows_by_key, write_geojson
+from .heatmap import HeatmapTable, utilization_heatmap
+from .inventory import GROUPINGS, Inventory, InventoryRecord
+from .io import (
+    anonymise_csv,
+    read_counts,
+    read_inventory,
+    read_sightings,
+    records_to_rows,
+    write_rows,
+)
+from .lpr import (
+    Sighting,
+    Stay,
+    TurnoverRow,
+    accumulation_from_stays,
+    build_stays,
+    duration_distribution,
+    survey_hours_from_beats,
+    turnover_summary,
+)
+from .occupancy import (
+    DEFAULT_PRACTICAL_FACTORS,
+    DEFAULT_TARGET,
+    CapacityAssessment,
+    Count,
+    OccupancyRow,
+    SpaceHours,
+    accumulation_curve,
+    capacity_assessment,
+    effective_capacity,
+    infer_beat_minutes,
+    occupancy_by_beat,
+    peak_occupancy,
+    practical_capacity,
+    space_hours,
+)
+from .pricing import (
+    POLICIES,
+    SFMTA_POLICY,
+    SFPARK_PILOT_POLICY,
+    PriceBand,
+    PriceRecommendation,
+    PricingPolicy,
+    mean_occupancy,
+    recommend_rate,
+    recommend_rates,
+)
+from .privacy import PlateHasher, anonymise_rows, generate_salt, normalize_plate
+
+__all__ = [
+    "__version__",
+    # errors
+    "ParkingStudyError",
+    "DataError",
+    "PrivacyError",
+    # time helpers
+    "parse_beat",
+    "parse_windows",
+    # inventory
+    "GROUPINGS",
+    "Inventory",
+    "InventoryRecord",
+    # occupancy
+    "DEFAULT_TARGET",
+    "DEFAULT_PRACTICAL_FACTORS",
+    "Count",
+    "OccupancyRow",
+    "CapacityAssessment",
+    "SpaceHours",
+    "occupancy_by_beat",
+    "peak_occupancy",
+    "effective_capacity",
+    "practical_capacity",
+    "capacity_assessment",
+    "accumulation_curve",
+    "infer_beat_minutes",
+    "space_hours",
+    # licence-plate survey
+    "Sighting",
+    "Stay",
+    "TurnoverRow",
+    "build_stays",
+    "turnover_summary",
+    "accumulation_from_stays",
+    "duration_distribution",
+    "survey_hours_from_beats",
+    # heatmap
+    "HeatmapTable",
+    "utilization_heatmap",
+    # pricing
+    "PriceBand",
+    "PricingPolicy",
+    "PriceRecommendation",
+    "SFMTA_POLICY",
+    "SFPARK_PILOT_POLICY",
+    "POLICIES",
+    "recommend_rate",
+    "recommend_rates",
+    "mean_occupancy",
+    # geojson
+    "JoinResult",
+    "join_to_geojson",
+    "load_geojson",
+    "write_geojson",
+    "rows_by_key",
+    # privacy
+    "PlateHasher",
+    "generate_salt",
+    "normalize_plate",
+    "anonymise_rows",
+    # io
+    "read_inventory",
+    "read_counts",
+    "read_sightings",
+    "anonymise_csv",
+    "write_rows",
+    "records_to_rows",
+]

parkingstudy/__main__.py

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

parkingstudy/_time.py

@@ -0,0 +1,110 @@
+"""Parsing of survey beat times and time-of-day windows (internal)."""
+
+from __future__ import annotations
+
+import datetime as _dt
+from typing import Iterable, List, Sequence, Tuple, Union
+
+from .errors import DataError
+
+TimeLike = Union[str, _dt.datetime, _dt.time]
+
+#: Date attached to beats given as bare clock times ("08:30").
+BASE_DATE = _dt.date(2000, 1, 1)
+
+Window = Tuple[int, int]
+
+
+def parse_beat(value: TimeLike) -> _dt.datetime:
+    """Parse a beat time.
+
+    Accepts a :class:`datetime.datetime`, a :class:`datetime.time`, an ISO 8601
+    date-time string (``"2026-03-10T08:30"`` or ``"2026-03-10 08:30"``) or a bare
+    clock time (``"8:30"``, ``"08:30:00"``). Bare clock times are attached to a
+    fixed placeholder date so that single-day surveys need no date column.
+    Time zones are not supported: aware values are rejected.
+    """
+    if isinstance(value, _dt.datetime):
+        result = value
+    elif isinstance(value, _dt.time):
+        result = _dt.datetime.combine(BASE_DATE, value)
+    else:
+        text = str(value).strip()
+        if not text:
+            raise DataError("empty beat time")
+        try:
+            if "-" in text[:10] and len(text) >= 10:
+                result = _dt.datetime.fromisoformat(text)
+            else:
+                parts = text.split(":")
+                if len(parts) not in (2, 3):
+                    raise ValueError(text)
+                hour, minute = int(parts[0]), int(parts[1])
+                second = int(float(parts[2])) if len(parts) == 3 else 0
+                result = _dt.datetime.combine(BASE_DATE, _dt.time(hour, minute, second))
+        except ValueError as exc:
+            raise DataError(f"cannot parse beat time {value!r}") from exc
+    if result.tzinfo is not None:
+        raise DataError(f"time-zone aware beat times are not supported: {value!r}")
+    return result
+
+
+def format_beat(value: _dt.datetime) -> str:
+    """Format a beat as ``HH:MM`` (bare clock times) or ISO ``YYYY-MM-DDTHH:MM``."""
+    if value.date() == BASE_DATE:
+        return value.strftime("%H:%M")
+    return value.isoformat(timespec="minutes")
+
+
+def minute_of_day(value: _dt.datetime) -> float:
+    """Minutes since midnight."""
+    return value.hour * 60 + value.minute + value.second / 60.0
+
+
+def _parse_clock(text: str) -> int:
+    parts = text.strip().split(":")
+    if len(parts) != 2:
+        raise DataError(f"expected HH:MM, got {text!r}")
+    hour, minute = int(parts[0]), int(parts[1])
+    if not (0 <= hour <= 24 and 0 <= minute < 60) or (hour == 24 and minute):
+        raise DataError(f"invalid clock time {text!r}")
+    return hour * 60 + minute
+
+
+def parse_windows(text: Union[str, Iterable[Window], None]) -> Tuple[Window, ...]:
+    """Parse time-of-day windows such as ``"07:00-09:00;16:00-18:30"``.
+
+    Windows are half-open ``[start, end)`` in minutes after midnight. A window
+    whose end is before its start wraps past midnight (``"22:00-06:00"``).
+    Already-parsed ``(start, end)`` pairs are passed through.
+    """
+    if text is None:
+        return ()
+    if not isinstance(text, str):
+        return tuple((int(a), int(b)) for a, b in text)
+    windows: List[Window] = []
+    for chunk in text.replace(",", ";").split(";"):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        if "-" not in chunk:
+            raise DataError(f"window must look like HH:MM-HH:MM, got {chunk!r}")
+        start, end = chunk.split("-", 1)
+        windows.append((_parse_clock(start), _parse_clock(end)))
+    return tuple(windows)
+
+
+def in_windows(minute: float, windows: Sequence[Window]) -> bool:
+    """Whether a minute-of-day falls inside any half-open window."""
+    for start, end in windows:
+        if start <= end:
+            if start <= minute < end:
+                return True
+        elif minute >= start or minute < end:
+            return True
+    return False
+
+
+def minutes_between(a: _dt.datetime, b: _dt.datetime) -> float:
+    """``b - a`` in minutes."""
+    return (b - a).total_seconds() / 60.0

parkingstudy/_version.py

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

parkingstudy/cli.py

@@ -0,0 +1,326 @@
+"""Command-line interface: ``parkingstudy <command> ...``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Dict, List, Optional, Sequence
+
+from ._version import __version__
+from .errors import ParkingStudyError
+from .geojson import join_to_geojson, load_geojson, rows_by_key, write_geojson
+from .heatmap import utilization_heatmap
+from .inventory import GROUPINGS
+from .io import (
+    anonymise_csv,
+    read_counts,
+    read_inventory,
+    read_sightings,
+    records_to_rows,
+    write_rows,
+)
+from .lpr import build_stays, duration_distribution, turnover_summary
+from .occupancy import (
+    DEFAULT_PRACTICAL_FACTORS,
+    DEFAULT_TARGET,
+    capacity_assessment,
+    infer_beat_minutes,
+    occupancy_by_beat,
+    space_hours,
+)
+from .pricing import POLICIES, mean_occupancy, recommend_rates
+from .privacy import SALT_ENV_VAR, PlateHasher, generate_salt, resolve_hasher
+
+
+def _add_output(p: argparse.ArgumentParser) -> None:
+    p.add_argument("-o", "--output", help="output file (default: standard output)")
+    p.add_argument("--format", choices=("csv", "json"), default="csv", help="output format")
+
+
+def _add_salt(p: argparse.ArgumentParser, required: bool = False) -> None:
+    g = p.add_argument_group("plate anonymisation (salt source)")
+    g.add_argument("--salt-file", help="file whose first line is the secret salt")
+    g.add_argument(
+        "--salt-env",
+        default=SALT_ENV_VAR if required else None,
+        help=f"environment variable holding the salt (default for hash-plates: {SALT_ENV_VAR})",
+    )
+
+
+def _factors(values: Optional[List[str]]) -> Dict[str, float]:
+    table = dict(DEFAULT_PRACTICAL_FACTORS)
+    for item in values or []:
+        name, _, val = item.partition("=")
+        if not val:
+            raise ParkingStudyError(f"--factor must look like facility=0.9, got {item!r}")
+        table[name.strip()] = float(val)
+    return table
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argument parser (exposed for documentation and tests)."""
+    parser = argparse.ArgumentParser(
+        prog="parkingstudy",
+        description="Parking occupancy and turnover survey analysis.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("salt", help="print a new random salt for plate hashing")
+    p.add_argument("--bytes", type=int, default=32, help="salt length in bytes (default 32)")
+
+    p = sub.add_parser("hash-plates", help="replace raw plates in a CSV with salted tokens")
+    p.add_argument("input")
+    p.add_argument("-o", "--output", required=True, help="anonymised CSV to write")
+    p.add_argument("--plate-col", default="plate")
+    p.add_argument("--token-col", default="plate_token")
+    _add_salt(p, required=True)
+
+    p = sub.add_parser("inventory", help="summarise supply by zone and space type")
+    p.add_argument("inventory")
+    p.add_argument(
+        "--group",
+        default="zone,space_type",
+        help="comma-separated grouping among zone, space_type, facility, block_face_id",
+    )
+    _add_output(p)
+
+    p = sub.add_parser("occupancy", help="occupancy by beat, or peak capacity assessment")
+    p.add_argument("inventory")
+    p.add_argument("counts")
+    p.add_argument("--by", choices=GROUPINGS, default="zone")
+    p.add_argument(
+        "--peak", action="store_true", help="one row per key: peak vs effective capacity"
+    )
+    p.add_argument("--space-hours", action="store_true", help="space-hour demand and supply")
+    p.add_argument("--target", type=float, default=DEFAULT_TARGET, help="target occupancy")
+    p.add_argument(
+        "--factor",
+        action="append",
+        metavar="FACILITY=F",
+        help="practical-capacity factor, e.g. on_street=0.85 (repeatable)",
+    )
+    p.add_argument("--beat-minutes", type=float, help="beat length (default: inferred)")
+    _add_output(p)
+
+    p = sub.add_parser("turnover", help="licence-plate survey: turnover, duration, overstay")
+    p.add_argument("inventory")
+    p.add_argument("sightings")
+    p.add_argument("--by", choices=GROUPINGS, default="zone")
+    p.add_argument("--beat-minutes", type=float, help="beat length (default: inferred)")
+    p.add_argument("--level", choices=("block_face", "zone"), default="block_face")
+    p.add_argument("--max-gap-beats", type=int, default=0)
+    p.add_argument("--overstay-basis", choices=("minimum", "estimate"), default="minimum")
+    p.add_argument("--stays", help="also write individual stays (tokens omitted) to this CSV")
+    p.add_argument(
+        "--durations", action="store_true", help="output the duration distribution instead"
+    )
+    _add_salt(p)
+    _add_output(p)
+
+    p = sub.add_parser("heatmap", help="occupancy rate table, key x time-of-day bin")
+    p.add_argument("inventory")
+    p.add_argument("counts")
+    p.add_argument("--by", choices=GROUPINGS, default="zone")
+    p.add_argument("--bin-minutes", type=int, default=60)
+    p.add_argument("-o", "--output", help="output CSV (default: standard output)")
+
+    p = sub.add_parser("pricing", help="demand-responsive rate recommendations")
+    p.add_argument("inventory", help="inventory CSV with an hourly_rate column")
+    p.add_argument("counts")
+    p.add_argument("--by", choices=("block_face", "zone"), default="block_face")
+    p.add_argument("--policy", choices=sorted(POLICIES), default="sfmta")
+    p.add_argument("--from", dest="start", help="first beat time of the rate period, HH:MM")
+    p.add_argument("--to", dest="end", help="end of the rate period (exclusive), HH:MM")
+    p.add_argument("--default-rate", type=float, help="rate for faces without hourly_rate")
+    _add_output(p)
+
+    p = sub.add_parser("geojson", help="join a result CSV to block-face GeoJSON")
+    p.add_argument("geojson", help="block-face FeatureCollection")
+    p.add_argument("results", help="result CSV produced by another command")
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--id-property", default="block_face_id")
+    p.add_argument("--key-col", default="key", help="key column of the result CSV")
+    p.add_argument("--prefix", default="")
+    p.add_argument("--drop-unmatched", action="store_true")
+    return parser
+
+
+def _clock(text: Optional[str]) -> Optional[float]:
+    if not text:
+        return None
+    hh, _, mm = text.partition(":")
+    return int(hh) * 60 + int(mm or 0)
+
+
+def _coerce(text: Optional[str]) -> object:
+    """CSV cell to int, float, bool or None where unambiguous (for GeoJSON properties)."""
+    if text is None or text == "":
+        return None
+    if text in ("True", "False"):
+        return text == "True"
+    for conv in (int, float):
+        try:
+            return conv(text)
+        except ValueError:
+            pass
+    return text
+
+
+def _run(args: argparse.Namespace) -> int:
+    cmd = args.command
+    if cmd == "salt":
+        print(generate_salt(args.bytes))
+        return 0
+
+    if cmd == "hash-plates":
+        hasher = resolve_hasher(salt_file=args.salt_file, salt_env=args.salt_env)
+        assert hasher is not None
+        n = anonymise_csv(
+            args.input,
+            args.output,
+            hasher,
+            plate_column=args.plate_col,
+            token_column=args.token_col,
+        )
+        print(f"{n} rows anonymised -> {args.output}", file=sys.stderr)
+        return 0
+
+    if cmd == "inventory":
+        inv = read_inventory(args.inventory)
+        group = [g.strip() for g in args.group.split(",") if g.strip()]
+        write_rows(inv.summary(group), args.output, fmt=args.format)
+        return 0
+
+    if cmd == "occupancy":
+        inv = read_inventory(args.inventory)
+        counts = read_counts(args.counts)
+        if args.peak:
+            res = capacity_assessment(
+                inv, counts, by=args.by, target=args.target, factors=_factors(args.factor)
+            )
+            rows = records_to_rows(res)
+        elif args.space_hours:
+            rows = records_to_rows(
+                space_hours(inv, counts, by=args.by, beat_minutes=args.beat_minutes)
+            )
+        else:
+            rows = [
+                {
+                    "key": r.key,
+                    "beat": r.beat,
+                    "occupied": r.occupied,
+                    "capacity": r.capacity,
+                    "rate": r.rate,
+                }
+                for r in occupancy_by_beat(inv, counts, by=args.by)
+            ]
+        write_rows(rows, args.output, fmt=args.format)
+        return 0
+
+    if cmd == "turnover":
+        inv = read_inventory(args.inventory)
+        plate_hasher: Optional[PlateHasher] = resolve_hasher(
+            salt_file=args.salt_file, salt_env=args.salt_env
+        )
+        sightings = read_sightings(args.sightings, plate_hasher)
+        beats = [s.beat for s in sightings]
+        beat_minutes = args.beat_minutes or infer_beat_minutes(beats)
+        stays = build_stays(
+            sightings,
+            beat_minutes,
+            inventory=inv,
+            level=args.level,
+            max_gap_beats=args.max_gap_beats,
+        )
+        if args.stays:
+            write_rows([s.as_dict(include_token=False) for s in stays], args.stays)
+        if args.durations:
+            rows = duration_distribution(stays)
+        else:
+            rows = records_to_rows(
+                turnover_summary(
+                    stays, inv, by=args.by, beats=beats, overstay_basis=args.overstay_basis
+                )
+            )
+        write_rows(rows, args.output, fmt=args.format)
+        return 0
+
+    if cmd == "heatmap":
+        inv = read_inventory(args.inventory)
+        table = utilization_heatmap(
+            inv, read_counts(args.counts), by=args.by, bin_minutes=args.bin_minutes
+        )
+        text = table.to_csv(args.output)
+        if not args.output:
+            sys.stdout.write(text)
+        return 0
+
+    if cmd == "pricing":
+        inv = read_inventory(args.inventory)
+        counts = read_counts(args.counts)
+        start, end = _clock(args.start), _clock(args.end)
+
+        def in_period(minute: float) -> bool:
+            return (start is None or minute >= start) and (end is None or minute < end)
+
+        counts = [c for c in counts if in_period(c.beat.hour * 60 + c.beat.minute)]
+        occ = mean_occupancy(occupancy_by_beat(inv, counts, by=args.by))
+        rates: Dict[str, Optional[float]] = {}
+        if args.by == "block_face":
+            rates = {f: inv.hourly_rate(f) for f in inv.face_ids()}
+        else:
+            for zone in inv.zones():
+                priced = [
+                    (inv.capacity(block_face_id=f), inv.hourly_rate(f))
+                    for f in inv.face_ids()
+                    if inv.zone_of(f) == zone
+                ]
+                pairs = [(n, r) for n, r in priced if r is not None]
+                total = sum(n for n, _ in pairs)
+                rates[zone] = sum(n * r for n, r in pairs) / total if total else None
+        recs = recommend_rates(
+            occ, rates, policy=POLICIES[args.policy], default_rate=args.default_rate
+        )
+        write_rows(records_to_rows(recs), args.output, fmt=args.format)
+        return 0
+
+    if cmd == "geojson":
+        import csv
+
+        with open(args.results, encoding="utf-8-sig", newline="") as fh:
+            result_rows = [
+                {k: (v if k == args.key_col else _coerce(v)) for k, v in r.items()}
+                for r in csv.DictReader(fh)
+            ]
+        joined = join_to_geojson(
+            load_geojson(args.geojson),
+            rows_by_key(result_rows, args.key_col),
+            id_property=args.id_property,
+            prefix=args.prefix,
+            keep_unmatched=not args.drop_unmatched,
+        )
+        write_geojson(joined.geojson, args.output)
+        print(
+            f"{joined.matched} keys joined; {len(joined.unmatched_features)} features and "
+            f"{len(joined.unmatched_keys)} result keys unmatched -> {args.output}",
+            file=sys.stderr,
+        )
+        return 0
+
+    raise AssertionError(cmd)  # pragma: no cover
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point; returns the process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return _run(args)
+    except (ParkingStudyError, ValueError, OSError) as exc:
+        print(f"parkingstudy: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

parkingstudy/errors.py

@@ -0,0 +1,15 @@
+"""Exception hierarchy."""
+
+from __future__ import annotations
+
+
+class ParkingStudyError(Exception):
+    """Base class for all errors raised by :mod:`parkingstudy`."""
+
+
+class DataError(ParkingStudyError, ValueError):
+    """Survey data is malformed, inconsistent or refers to unknown block faces."""
+
+
+class PrivacyError(ParkingStudyError):
+    """Raw licence plates would be processed or written without anonymisation."""