parkingstudy 0.1.0__py3-none-any.whl

parkingstudy/geojson.py

@@ -0,0 +1,111 @@
+"""Join survey results to block-face geometries in GeoJSON (RFC 7946)."""
+
+from __future__ import annotations
+
+import copy
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple, Union
+
+from .errors import DataError, PrivacyError
+
+#: Property names that must never be written to an output map.
+_FORBIDDEN_PROPERTIES = ("plate", "plate_number", "licence_plate", "license_plate", "plaka")
+
+
+@dataclass(frozen=True)
+class JoinResult:
+    """Outcome of :func:`join_to_geojson`."""
+
+    geojson: Dict[str, Any]
+    matched: int
+    unmatched_features: Tuple[str, ...]
+    unmatched_keys: Tuple[str, ...]
+
+
+def load_geojson(path: Union[str, Path]) -> Dict[str, Any]:
+    """Read a GeoJSON FeatureCollection."""
+    with open(path, encoding="utf-8-sig") as fh:
+        data = json.load(fh)
+    if not isinstance(data, dict) or data.get("type") != "FeatureCollection":
+        raise DataError(f"{path}: not a GeoJSON FeatureCollection")
+    return data
+
+
+def write_geojson(data: Mapping[str, Any], path: Union[str, Path]) -> None:
+    """Write GeoJSON as UTF-8."""
+    with open(path, "w", encoding="utf-8", newline="\n") as fh:
+        json.dump(data, fh, ensure_ascii=False, indent=1)
+        fh.write("\n")
+
+
+def rows_by_key(
+    rows: Iterable[Mapping[str, Any]], key_field: str = "key"
+) -> Dict[str, Dict[str, Any]]:
+    """Index result rows (e.g. ``TurnoverRow.as_dict()``) by their key field.
+
+    The key field itself is dropped from the indexed dicts.
+    """
+    out: Dict[str, Dict[str, Any]] = {}
+    for row in rows:
+        if key_field not in row:
+            raise DataError(f"result row has no {key_field!r} field")
+        key = str(row[key_field])
+        if key in out:
+            raise DataError(f"duplicate result key {key!r}")
+        out[key] = {k: v for k, v in row.items() if k != key_field}
+    return out
+
+
+def join_to_geojson(
+    feature_collection: Mapping[str, Any],
+    results: Mapping[str, Mapping[str, Any]],
+    *,
+    id_property: str = "block_face_id",
+    prefix: str = "",
+    keep_unmatched: bool = True,
+) -> JoinResult:
+    """Attach result attributes to features whose ``id_property`` matches a result key.
+
+    The input collection is not modified. Feature ids are compared as strings;
+    the feature-level ``id`` member is used when ``id_property`` is ``"id"`` and
+    no such property exists. Unmatched features are kept (with no added
+    attributes) unless ``keep_unmatched=False``. Result attributes that look like
+    raw licence plates are refused.
+    """
+    if feature_collection.get("type") != "FeatureCollection":
+        raise DataError("expected a GeoJSON FeatureCollection")
+    for attrs in results.values():
+        for name in attrs:
+            if name.lower() in _FORBIDDEN_PROPERTIES:
+                raise PrivacyError(f"refusing to write attribute {name!r} to a map")
+    features_out: List[Dict[str, Any]] = []
+    unmatched_features: List[str] = []
+    used = set()
+    for feature in feature_collection.get("features", []):
+        feat = copy.deepcopy(feature)
+        props = feat.get("properties") or {}
+        raw_id: Optional[Any] = props.get(id_property)
+        if raw_id is None and id_property == "id":
+            raw_id = feat.get("id")
+        fid = None if raw_id is None else str(raw_id)
+        if fid is not None and fid in results:
+            used.add(fid)
+            props = dict(props)
+            for name, value in results[fid].items():
+                props[prefix + name] = value
+            feat["properties"] = props
+            features_out.append(feat)
+        else:
+            unmatched_features.append("" if fid is None else fid)
+            if keep_unmatched:
+                features_out.append(feat)
+    out = {k: copy.deepcopy(v) for k, v in feature_collection.items() if k != "features"}
+    out["features"] = features_out
+    return JoinResult(
+        geojson=out,
+        matched=len(used),
+        unmatched_features=tuple(unmatched_features),
+        unmatched_keys=tuple(k for k in results if k not in used),
+    )

parkingstudy/heatmap.py

@@ -0,0 +1,117 @@
+"""Utilization heatmap tables: occupancy rate by key (zone / block face) x time of day."""
+
+from __future__ import annotations
+
+import csv
+import io
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Optional, TextIO, Tuple, Union
+
+from ._time import minute_of_day
+from .inventory import Inventory
+from .occupancy import Count, occupancy_by_beat
+
+
+@dataclass(frozen=True)
+class HeatmapTable:
+    """Occupancy rates arranged as rows (keys) x columns (time-of-day bins).
+
+    ``values[i][j]`` is the pooled occupancy rate of ``row_keys[i]`` in bin
+    ``column_labels[j]``, or ``None`` when that cell had no counts or no supply.
+    """
+
+    by: str
+    bin_minutes: int
+    row_keys: Tuple[str, ...]
+    column_labels: Tuple[str, ...]
+    values: Tuple[Tuple[Optional[float], ...], ...]
+
+    def get(self, key: str, label: str) -> Optional[float]:
+        """Cell value by row key and column label."""
+        return self.values[self.row_keys.index(key)][self.column_labels.index(label)]
+
+    def max_cell(self) -> Optional[Tuple[str, str, float]]:
+        """``(key, label, rate)`` of the highest cell, or ``None`` for an empty table."""
+        best: Optional[Tuple[str, str, float]] = None
+        for key, row in zip(self.row_keys, self.values):
+            for label, v in zip(self.column_labels, row):
+                if v is not None and (best is None or v > best[2]):
+                    best = (key, label, v)
+        return best
+
+    def to_rows(self, digits: Optional[int] = 3) -> List[Dict[str, object]]:
+        """One dict per key, columns named by bin start (``"08:00"``)."""
+        rows: List[Dict[str, object]] = []
+        for key, vals in zip(self.row_keys, self.values):
+            row: Dict[str, object] = {"key": key}
+            for label, v in zip(self.column_labels, vals):
+                row[label] = None if v is None else (round(v, digits) if digits is not None else v)
+            rows.append(row)
+        return rows
+
+    def to_csv(self, target: Union[str, TextIO, None] = None, digits: Optional[int] = 3) -> str:
+        """Write the table as CSV to a path or stream and return the CSV text."""
+        buf = io.StringIO()
+        writer = csv.writer(buf, lineterminator="\n")
+        writer.writerow(["key", *self.column_labels])
+        for row in self.to_rows(digits):
+            writer.writerow(
+                ["" if row[c] is None else row[c] for c in ["key", *self.column_labels]]
+            )
+        text = buf.getvalue()
+        if isinstance(target, str):
+            with open(target, "w", encoding="utf-8", newline="") as fh:
+                fh.write(text)
+        elif target is not None:
+            target.write(text)
+        return text
+
+
+def _label(minute: int) -> str:
+    return f"{minute // 60:02d}:{minute % 60:02d}"
+
+
+def utilization_heatmap(
+    inventory: Inventory,
+    counts: Iterable[Count],
+    *,
+    by: str = "zone",
+    bin_minutes: int = 60,
+) -> HeatmapTable:
+    """Pooled occupancy rate for each key and time-of-day bin.
+
+    Each cell is the sum of vehicles over the sum of available spaces for all
+    beats (on all survey days) whose time of day falls in the bin, which weights
+    beats by supply rather than averaging rates. Columns run contiguously from
+    the earliest to the latest bin that has data.
+    """
+    if bin_minutes <= 0 or 1440 % bin_minutes:
+        raise ValueError("bin_minutes must be a positive divisor of 1440")
+    rows = occupancy_by_beat(inventory, counts, by=by)
+    acc: Dict[Tuple[str, int], List[int]] = {}
+    keys: List[str] = []
+    for r in rows:
+        if r.key not in keys:
+            keys.append(r.key)
+        b = int(minute_of_day(r.beat) // bin_minutes) * bin_minutes
+        a = acc.setdefault((r.key, b), [0, 0])
+        a[0] += r.occupied
+        a[1] += r.capacity
+    if not acc:
+        return HeatmapTable(by, bin_minutes, (), (), ())
+    bins_present = [b for _, b in acc]
+    bins = list(range(min(bins_present), max(bins_present) + bin_minutes, bin_minutes))
+    values = []
+    for key in keys:
+        line: List[Optional[float]] = []
+        for b in bins:
+            cell = acc.get((key, b))
+            line.append(cell[0] / cell[1] if cell and cell[1] else None)
+        values.append(tuple(line))
+    return HeatmapTable(
+        by=by,
+        bin_minutes=bin_minutes,
+        row_keys=tuple(keys),
+        column_labels=tuple(_label(b) for b in bins),
+        values=tuple(values),
+    )

parkingstudy/inventory.py

@@ -0,0 +1,248 @@
+"""Parking supply inventory: spaces by block face, zone and space type."""
+
+from __future__ import annotations
+
+import datetime as _dt
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, Iterator, List, Optional, Sequence, Set, Tuple
+
+from ._time import Window, in_windows, minute_of_day, parse_windows
+from .errors import DataError
+
+#: Aggregation levels accepted by the ``by=`` arguments throughout the package.
+GROUPINGS = ("block_face", "zone", "total")
+
+
+def check_grouping(by: str) -> str:
+    """Validate a ``by=`` argument."""
+    if by not in GROUPINGS:
+        raise ValueError(f"by must be one of {GROUPINGS}, got {by!r}")
+    return by
+
+
+@dataclass(frozen=True)
+class InventoryRecord:
+    """One inventory line: a group of identical spaces on one block face.
+
+    A block face with several space types (general, disabled, loading, ...) is
+    described by several records sharing ``block_face_id``.
+
+    Attributes
+    ----------
+    block_face_id:
+        Identifier of the block face (one side of a street between two
+        intersections) or of an off-street facility.
+    spaces:
+        Number of legal spaces. For unmarked kerb this is the kerb length
+        divided by a design stall length chosen by the analyst.
+    zone:
+        Study zone or sub-area the block face belongs to.
+    space_type:
+        Free label such as ``general``, ``disabled``, ``loading``, ``ev``.
+    facility:
+        ``on_street`` or ``off_street`` (used for practical-capacity factors).
+    time_limit_min:
+        Posted maximum stay in minutes, or ``None`` when unrestricted.
+    restriction:
+        Free-text description of the regulation (e.g. ``"2h pay 08-19 Mon-Sat"``).
+    unavailable:
+        Time-of-day windows during which the spaces may not be used at all
+        (clearways, peak-hour no-parking, street cleaning), as ``(start, end)``
+        minutes after midnight or a string ``"07:00-09:00;16:00-18:00"``.
+    hourly_rate:
+        Current hourly price, used by the pricing rules.
+    """
+
+    block_face_id: str
+    spaces: int
+    zone: str = ""
+    space_type: str = "general"
+    facility: str = "on_street"
+    time_limit_min: Optional[float] = None
+    restriction: str = ""
+    unavailable: Tuple[Window, ...] = field(default=())
+    hourly_rate: Optional[float] = None
+
+    def __post_init__(self) -> None:
+        if not str(self.block_face_id).strip():
+            raise DataError("block_face_id must not be empty")
+        if int(self.spaces) != self.spaces or self.spaces < 0:
+            raise DataError(f"{self.block_face_id}: spaces must be a non-negative integer")
+        if self.time_limit_min is not None and self.time_limit_min <= 0:
+            raise DataError(f"{self.block_face_id}: time_limit_min must be positive")
+        if self.hourly_rate is not None and self.hourly_rate < 0:
+            raise DataError(f"{self.block_face_id}: hourly_rate must not be negative")
+        object.__setattr__(self, "spaces", int(self.spaces))
+        object.__setattr__(self, "unavailable", parse_windows(self.unavailable))
+
+    def available_at(self, when: Optional[_dt.datetime] = None) -> int:
+        """Legal spaces at a moment: 0 inside an ``unavailable`` window."""
+        if when is not None and self.unavailable:
+            if in_windows(minute_of_day(when), self.unavailable):
+                return 0
+        return self.spaces
+
+
+class Inventory:
+    """Collection of :class:`InventoryRecord` with lookup and aggregation helpers."""
+
+    def __init__(self, records: Iterable[InventoryRecord]) -> None:
+        self._records: List[InventoryRecord] = list(records)
+        self._by_face: Dict[str, List[InventoryRecord]] = OrderedDict()
+        seen: Set[Tuple[str, str]] = set()
+        for rec in self._records:
+            key = (rec.block_face_id, rec.space_type)
+            if key in seen:
+                raise DataError(
+                    f"duplicate inventory line for block face {rec.block_face_id!r}, "
+                    f"space type {rec.space_type!r}"
+                )
+            seen.add(key)
+            rows = self._by_face.setdefault(rec.block_face_id, [])
+            if rows and rows[0].zone != rec.zone:
+                raise DataError(f"block face {rec.block_face_id!r} is assigned to several zones")
+            rows.append(rec)
+
+    @property
+    def records(self) -> Tuple[InventoryRecord, ...]:
+        """All records in input order."""
+        return tuple(self._records)
+
+    def __len__(self) -> int:
+        return len(self._records)
+
+    def __iter__(self) -> Iterator[InventoryRecord]:
+        return iter(self._records)
+
+    def __contains__(self, block_face_id: object) -> bool:
+        return block_face_id in self._by_face
+
+    def face_ids(self) -> List[str]:
+        """Block face identifiers in input order."""
+        return list(self._by_face)
+
+    def zones(self) -> List[str]:
+        """Zone names in input order."""
+        return list(OrderedDict.fromkeys(rec.zone for rec in self._records))
+
+    def zone_of(self, block_face_id: str) -> str:
+        """Zone of a block face."""
+        return self._face(block_face_id)[0].zone
+
+    def key_of(self, block_face_id: str, by: str) -> str:
+        """Aggregation key of a block face for ``by`` in :data:`GROUPINGS`."""
+        check_grouping(by)
+        if by == "block_face":
+            self._face(block_face_id)
+            return block_face_id
+        if by == "zone":
+            return self.zone_of(block_face_id)
+        return "total"
+
+    def _face(self, block_face_id: str) -> List[InventoryRecord]:
+        try:
+            return self._by_face[block_face_id]
+        except KeyError:
+            raise DataError(f"block face {block_face_id!r} is not in the inventory") from None
+
+    def select(
+        self,
+        *,
+        block_face_id: Optional[str] = None,
+        zone: Optional[str] = None,
+        space_type: Optional[str] = None,
+    ) -> List[InventoryRecord]:
+        """Records matching every filter that is not ``None``."""
+        candidates: Iterable[InventoryRecord]
+        if block_face_id is not None:
+            candidates = self._face(block_face_id)
+        else:
+            candidates = self._records
+        return [
+            rec
+            for rec in candidates
+            if (zone is None or rec.zone == zone)
+            and (space_type is None or rec.space_type == space_type)
+        ]
+
+    def capacity(
+        self,
+        *,
+        block_face_id: Optional[str] = None,
+        zone: Optional[str] = None,
+        space_type: Optional[str] = None,
+        at: Optional[_dt.datetime] = None,
+    ) -> int:
+        """Number of legal spaces, optionally at a given moment (see ``unavailable``)."""
+        recs = self.select(block_face_id=block_face_id, zone=zone, space_type=space_type)
+        return sum(rec.available_at(at) for rec in recs)
+
+    def capacity_for_key(self, key: str, by: str, at: Optional[_dt.datetime] = None) -> int:
+        """Capacity of an aggregation key produced by :meth:`key_of`."""
+        check_grouping(by)
+        if by == "block_face":
+            return self.capacity(block_face_id=key, at=at)
+        if by == "zone":
+            return self.capacity(zone=key, at=at)
+        return self.capacity(at=at)
+
+    def time_limit(self, block_face_id: str, space_type: Optional[str] = None) -> Optional[float]:
+        """Posted time limit (minutes) applying to a block face.
+
+        With ``space_type`` the limit of that line is returned. Otherwise the limit
+        is returned only if all time-limited lines of the face share one value;
+        a face with mixed limits returns ``None`` (overstay not assessed).
+        """
+        recs = self._face(block_face_id)
+        if space_type:
+            recs = [r for r in recs if r.space_type == space_type]
+            if not recs:
+                raise DataError(f"block face {block_face_id!r} has no {space_type!r} spaces")
+        limits = {r.time_limit_min for r in recs if r.time_limit_min is not None}
+        return limits.pop() if len(limits) == 1 else None
+
+    def hourly_rate(self, block_face_id: str) -> Optional[float]:
+        """Space-weighted mean hourly rate of the priced lines of a face (``None`` if unpriced)."""
+        priced = [(r.spaces, r.hourly_rate) for r in self._face(block_face_id)]
+        pairs = [(n, float(rate)) for n, rate in priced if rate is not None]
+        if not pairs:
+            return None
+        spaces = sum(n for n, _ in pairs)
+        if spaces == 0:
+            return pairs[0][1]
+        return sum(n * rate for n, rate in pairs) / spaces
+
+    def summary(self, by: Sequence[str] = ("zone", "space_type")) -> List[Dict[str, object]]:
+        """Supply table grouped by any of ``zone``, ``space_type``, ``facility``.
+
+        Each row gives the number of block faces, spaces, time-limited spaces,
+        priced spaces and part-time spaces (those with an ``unavailable`` window).
+        """
+        allowed = ("zone", "space_type", "facility", "block_face_id")
+        for name in by:
+            if name not in allowed:
+                raise ValueError(f"summary grouping must be among {allowed}, got {name!r}")
+        counters: Dict[Tuple[str, ...], Dict[str, int]] = OrderedDict()
+        faces: Dict[Tuple[str, ...], Set[str]] = {}
+        for rec in self._records:
+            key = tuple(str(getattr(rec, name)) for name in by)
+            c = counters.setdefault(
+                key,
+                {"spaces": 0, "time_limited_spaces": 0, "priced_spaces": 0, "part_time_spaces": 0},
+            )
+            faces.setdefault(key, set()).add(rec.block_face_id)
+            c["spaces"] += rec.spaces
+            if rec.time_limit_min is not None:
+                c["time_limited_spaces"] += rec.spaces
+            if rec.hourly_rate:
+                c["priced_spaces"] += rec.spaces
+            if rec.unavailable:
+                c["part_time_spaces"] += rec.spaces
+        rows: List[Dict[str, object]] = []
+        for key, c in counters.items():
+            row: Dict[str, object] = dict(zip(by, key))
+            row["block_faces"] = len(faces[key])
+            row.update(c)
+            rows.append(row)
+        return rows