parkingstudy 0.1.0__py3-none-any.whl

parkingstudy/io.py

@@ -0,0 +1,251 @@
+"""CSV readers and writers for inventories, counts, sightings and result tables.
+
+Column names (case-insensitive, surrounding spaces ignored):
+
+* **inventory**: ``block_face_id``, ``spaces`` (required); ``zone``,
+  ``space_type``, ``facility``, ``time_limit_min``, ``restriction``,
+  ``unavailable`` (``"07:00-09:00;16:00-18:00"``), ``hourly_rate``.
+* **counts**: ``block_face_id``, ``beat``, ``occupied`` (required);
+  ``space_type``; ``date`` (``YYYY-MM-DD``, combined with a clock-time beat).
+* **sightings**: ``block_face_id``, ``beat`` and either ``plate_token``
+  (already anonymised) or ``plate`` (raw, hashed on read; a
+  :class:`~parkingstudy.privacy.PlateHasher` is then mandatory); optional
+  ``space_type`` and ``date``.
+"""
+
+from __future__ import annotations
+
+import csv
+import datetime as _dt
+import io
+import json
+import math
+import sys
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Mapping, Optional, Sequence, TextIO, Union
+
+from ._time import format_beat, parse_beat
+from .errors import DataError, PrivacyError
+from .inventory import Inventory, InventoryRecord
+from .lpr import Sighting
+from .occupancy import Count
+from .privacy import PlateHasher
+
+PathLike = Union[str, Path]
+
+
+def _rows(path: PathLike) -> Iterator[Dict[str, str]]:
+    with open(path, encoding="utf-8-sig", newline="") as fh:
+        reader = csv.DictReader(fh)
+        if reader.fieldnames is None:
+            return
+        names = [(n or "").strip().lower() for n in reader.fieldnames]
+        for line_no, raw in enumerate(reader, start=2):
+            row = {
+                names[i]: (v or "").strip()
+                for i, v in enumerate(raw.get(f) for f in reader.fieldnames)
+            }
+            if not any(row.values()):
+                continue
+            row["__line__"] = str(line_no)
+            yield row
+
+
+def _req(row: Mapping[str, str], name: str, path: PathLike) -> str:
+    value = row.get(name, "")
+    if value == "":
+        raise DataError(f"{path}:{row.get('__line__')}: missing value for {name!r}")
+    return value
+
+
+def _opt_float(row: Mapping[str, str], name: str, path: PathLike) -> Optional[float]:
+    value = row.get(name, "")
+    if value == "":
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        raise DataError(
+            f"{path}:{row.get('__line__')}: {name} is not a number: {value!r}"
+        ) from None
+
+
+def _int(row: Mapping[str, str], name: str, path: PathLike) -> int:
+    value = _req(row, name, path)
+    try:
+        number = float(value)
+    except ValueError:
+        raise DataError(
+            f"{path}:{row.get('__line__')}: {name} is not a number: {value!r}"
+        ) from None
+    if number != int(number):
+        raise DataError(f"{path}:{row.get('__line__')}: {name} must be a whole number")
+    return int(number)
+
+
+def _beat(row: Mapping[str, str], path: PathLike) -> _dt.datetime:
+    beat = _req(row, "beat", path)
+    date = row.get("date", "")
+    try:
+        if date:
+            return parse_beat(f"{date}T{beat}" if len(beat) <= 8 else beat)
+        return parse_beat(beat)
+    except DataError as exc:
+        raise DataError(f"{path}:{row.get('__line__')}: {exc}") from None
+
+
+def read_inventory(path: PathLike) -> Inventory:
+    """Read an inventory CSV."""
+    records = []
+    for row in _rows(path):
+        try:
+            records.append(
+                InventoryRecord(
+                    block_face_id=_req(row, "block_face_id", path),
+                    spaces=_int(row, "spaces", path),
+                    zone=row.get("zone", ""),
+                    space_type=row.get("space_type", "") or "general",
+                    facility=row.get("facility", "") or "on_street",
+                    time_limit_min=_opt_float(row, "time_limit_min", path),
+                    restriction=row.get("restriction", ""),
+                    unavailable=row.get("unavailable", ""),  # type: ignore[arg-type]
+                    hourly_rate=_opt_float(row, "hourly_rate", path),
+                )
+            )
+        except DataError as exc:
+            if str(path) in str(exc):
+                raise
+            raise DataError(f"{path}:{row.get('__line__')}: {exc}") from None
+    return Inventory(records)
+
+
+def read_counts(path: PathLike) -> List[Count]:
+    """Read an occupancy count CSV."""
+    return [
+        Count(
+            block_face_id=_req(row, "block_face_id", path),
+            beat=_beat(row, path),
+            occupied=_int(row, "occupied", path),
+            space_type=row.get("space_type", ""),
+        )
+        for row in _rows(path)
+    ]
+
+
+def read_sightings(
+    path: PathLike,
+    hasher: Optional[PlateHasher] = None,
+    *,
+    plate_column: str = "plate",
+    token_column: str = "plate_token",
+) -> List[Sighting]:
+    """Read a licence-plate survey CSV, anonymising raw plates on the fly.
+
+    If the file has a ``token_column`` it is used as is. Otherwise raw plates in
+    ``plate_column`` are hashed with ``hasher``; without a hasher a
+    :class:`~parkingstudy.errors.PrivacyError` is raised. Raw plates are never
+    kept in memory beyond the row being read.
+    """
+    plate_column = plate_column.lower()
+    token_column = token_column.lower()
+    out: List[Sighting] = []
+    for row in _rows(path):
+        token = row.get(token_column, "")
+        if not token:
+            if plate_column not in row:
+                raise DataError(f"{path}: needs a {token_column!r} or {plate_column!r} column")
+            if hasher is None:
+                raise PrivacyError(
+                    f"{path} contains raw plates; supply a PlateHasher (salt) to anonymise them"
+                )
+            token = hasher.hash(_req(row, plate_column, path))
+        out.append(
+            Sighting(
+                plate_token=token,
+                block_face_id=_req(row, "block_face_id", path),
+                beat=_beat(row, path),
+                space_type=row.get("space_type", ""),
+            )
+        )
+    return out
+
+
+def anonymise_csv(
+    src: PathLike,
+    dst: PathLike,
+    hasher: PlateHasher,
+    *,
+    plate_column: str = "plate",
+    token_column: str = "plate_token",
+) -> int:
+    """Copy a CSV replacing the raw plate column with tokens; returns rows written.
+
+    Column order is kept, with the token column in place of the plate column.
+    """
+    with open(src, encoding="utf-8-sig", newline="") as fin:
+        reader = csv.DictReader(fin)
+        if reader.fieldnames is None or plate_column not in reader.fieldnames:
+            raise DataError(f"{src}: no {plate_column!r} column")
+        fields = [token_column if f == plate_column else f for f in reader.fieldnames]
+        n = 0
+        with open(dst, "w", encoding="utf-8", newline="") as fout:
+            writer = csv.DictWriter(fout, fieldnames=fields, lineterminator="\n")
+            writer.writeheader()
+            for row in reader:
+                raw = row.pop(plate_column, "") or ""
+                if not raw.strip():
+                    continue
+                row[token_column] = hasher.hash(raw)
+                writer.writerow(row)
+                n += 1
+    return n
+
+
+def _cell(value: Any, digits: Optional[int]) -> Any:
+    if isinstance(value, _dt.datetime):
+        return format_beat(value)
+    if isinstance(value, float):
+        if math.isinf(value) or math.isnan(value):
+            return None
+        return round(value, digits) if digits is not None else value
+    return value
+
+
+def write_rows(
+    rows: Sequence[Mapping[str, Any]],
+    target: Union[PathLike, TextIO, None] = None,
+    *,
+    fmt: str = "csv",
+    digits: Optional[int] = 4,
+) -> str:
+    """Write result rows as CSV or JSON to a path, a stream or stdout; return the text."""
+    clean = [{k: _cell(v, digits) for k, v in row.items()} for row in rows]
+    if fmt == "json":
+        text = json.dumps(clean, ensure_ascii=False, indent=1) + "\n"
+    elif fmt == "csv":
+        fields: List[str] = []
+        for row in clean:
+            for k in row:
+                if k not in fields:
+                    fields.append(k)
+        buf = io.StringIO()
+        writer = csv.DictWriter(buf, fieldnames=fields, lineterminator="\n")
+        writer.writeheader()
+        for row in clean:
+            writer.writerow({k: ("" if v is None else v) for k, v in row.items()})
+        text = buf.getvalue()
+    else:
+        raise ValueError("fmt must be 'csv' or 'json'")
+    if target is None:
+        sys.stdout.write(text)
+    elif isinstance(target, (str, Path)):
+        with open(target, "w", encoding="utf-8", newline="") as fh:
+            fh.write(text)
+    else:
+        target.write(text)
+    return text
+
+
+def records_to_rows(items: Iterable[Any]) -> List[Dict[str, Any]]:
+    """Convert result objects with ``as_dict()`` to plain dict rows."""
+    return [item.as_dict() for item in items]

parkingstudy/lpr.py

@@ -0,0 +1,421 @@
+"""Licence-plate (beat) surveys: stays, durations, turnover and overstay.
+
+In a licence-plate survey, surveyors (or an LPR camera vehicle) pass every
+block face at a fixed interval, the *beat*, and record the plates of the
+parked vehicles. A vehicle seen at consecutive beats on the same block face is
+assumed to have stayed in between. With beat length ``b`` and a vehicle first
+seen at ``t1`` and last seen at ``tn``:
+
+* minimum duration = ``tn - t1`` (the vehicle was certainly there that long);
+* estimated duration = ``tn - t1 + b``: each sighting represents one beat
+  interval, i.e. ``n * b`` for ``n`` consecutive sightings. This is the usual
+  beat-survey convention; the true duration lies in ``(tn - t1, tn - t1 + 2b)``.
+
+Stays whose first sighting is on the first beat of a survey session are
+*left-censored* (they may have started earlier); stays seen on the last beat are
+*right-censored*. Both are flagged rather than dropped.
+
+Turnover is reported two ways: vehicles per space over the survey period
+(``vehicles / spaces``) and per hour (that value divided by the survey hours).
+
+Only anonymous plate tokens are handled here; see :mod:`parkingstudy.privacy`.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import statistics
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Optional, Sequence, Tuple
+
+from ._time import TimeLike, format_beat, minutes_between, parse_beat
+from .errors import DataError, PrivacyError
+from .inventory import Inventory, check_grouping
+
+#: Levels at which stays can be linked.
+STAY_LEVELS = ("block_face", "zone")
+
+#: Bases for overstay assessment.
+OVERSTAY_BASES = ("minimum", "estimate")
+
+
+@dataclass(frozen=True)
+class Sighting:
+    """One anonymous plate token observed on a block face at a beat."""
+
+    plate_token: str
+    block_face_id: str
+    beat: _dt.datetime
+    space_type: str = ""
+
+    def __post_init__(self) -> None:
+        if not str(self.plate_token).strip():
+            raise PrivacyError("empty plate token")
+        object.__setattr__(self, "beat", parse_beat(self.beat))
+
+    @classmethod
+    def make(
+        cls, plate_token: str, block_face_id: str, beat: TimeLike, space_type: str = ""
+    ) -> Sighting:
+        """Build a sighting, parsing ``beat`` from a string if needed."""
+        return cls(plate_token, block_face_id, parse_beat(beat), space_type)
+
+
+@dataclass(frozen=True)
+class Stay:
+    """A continuous stay of one vehicle at one location."""
+
+    plate_token: str
+    level: str
+    location: str
+    first_seen: _dt.datetime
+    last_seen: _dt.datetime
+    sightings: int
+    beat_minutes: float
+    left_censored: bool
+    right_censored: bool
+    time_limit_min: Optional[float] = None
+
+    @property
+    def minimum_duration_min(self) -> float:
+        """Time between first and last sighting."""
+        return minutes_between(self.first_seen, self.last_seen)
+
+    @property
+    def estimated_duration_min(self) -> float:
+        """Minimum duration plus one beat (``n`` sightings x beat when there is no gap)."""
+        return self.minimum_duration_min + self.beat_minutes
+
+    @property
+    def censored(self) -> bool:
+        """Stay touches the start or end of a survey session."""
+        return self.left_censored or self.right_censored
+
+    def overstay(self, basis: str = "minimum") -> Optional[bool]:
+        """Whether the stay exceeds the posted limit (``None`` without a limit).
+
+        ``basis="minimum"`` (default) counts only stays *certainly* longer than
+        the limit: a conservative, enforcement-grade test. ``basis="estimate"``
+        uses the estimated duration and gives a higher, best-estimate share.
+        """
+        if basis not in OVERSTAY_BASES:
+            raise ValueError(f"basis must be one of {OVERSTAY_BASES}")
+        if self.time_limit_min is None:
+            return None
+        duration = self.minimum_duration_min if basis == "minimum" else self.estimated_duration_min
+        return duration > self.time_limit_min + 1e-9
+
+    def as_dict(self, include_token: bool = True) -> Dict[str, object]:
+        """Plain-dict form; ``include_token=False`` drops even the anonymous token."""
+        row: Dict[str, object] = {}
+        if include_token:
+            row["plate_token"] = self.plate_token
+        row.update(
+            {
+                "level": self.level,
+                "location": self.location,
+                "first_seen": format_beat(self.first_seen),
+                "last_seen": format_beat(self.last_seen),
+                "sightings": self.sightings,
+                "minimum_duration_min": self.minimum_duration_min,
+                "estimated_duration_min": self.estimated_duration_min,
+                "left_censored": self.left_censored,
+                "right_censored": self.right_censored,
+                "time_limit_min": self.time_limit_min,
+                "overstay": self.overstay("minimum"),
+            }
+        )
+        return row
+
+
+class _BeatIndex:
+    """Ordered survey beats split into sessions (days or separate survey periods)."""
+
+    def __init__(self, beats: Iterable[_dt.datetime], beat_minutes: float) -> None:
+        self.beats = sorted(set(beats))
+        if not self.beats:
+            raise DataError("no beats")
+        self.index = {b: i for i, b in enumerate(self.beats)}
+        self.session: Dict[_dt.datetime, int] = {}
+        self.first_in_session: Dict[int, _dt.datetime] = {}
+        self.last_in_session: Dict[int, _dt.datetime] = {}
+        sid = 0
+        for i, b in enumerate(self.beats):
+            if i and minutes_between(self.beats[i - 1], b) > 1.5 * beat_minutes:
+                sid += 1
+            self.session[b] = sid
+            self.first_in_session.setdefault(sid, b)
+            self.last_in_session[sid] = b
+
+
+def build_stays(
+    sightings: Iterable[Sighting],
+    beat_minutes: float,
+    *,
+    inventory: Optional[Inventory] = None,
+    level: str = "block_face",
+    beats: Optional[Iterable[TimeLike]] = None,
+    max_gap_beats: int = 0,
+) -> List[Stay]:
+    """Link sightings of the same token into stays.
+
+    Parameters
+    ----------
+    sightings:
+        Anonymous sightings.
+    beat_minutes:
+        Survey beat length in minutes.
+    inventory:
+        Supplies time limits and, for ``level="zone"``, the zone of each face.
+    level:
+        ``"block_face"`` (a move to another face starts a new stay) or ``"zone"``
+        (moves within a zone are one stay, e.g. for area-wide time limits).
+    beats:
+        Full list of survey beat times. Defaults to the beats present in the
+        sightings; pass it explicitly when some beats recorded no vehicles.
+    max_gap_beats:
+        Number of missed beats tolerated inside one stay (default 0: a vehicle
+        absent at one beat has left). A tolerance of 1 absorbs occasional
+        missed reads at the cost of merging genuine short absences.
+
+    The time limit of a stay is the limit of the block face (and space type) of
+    its first sighting.
+    """
+    if level not in STAY_LEVELS:
+        raise ValueError(f"level must be one of {STAY_LEVELS}")
+    if level == "zone" and inventory is None:
+        raise ValueError("level='zone' requires an inventory")
+    if beat_minutes <= 0:
+        raise ValueError("beat_minutes must be positive")
+    if max_gap_beats < 0:
+        raise ValueError("max_gap_beats must not be negative")
+    items = list(sightings)
+    beat_list = [parse_beat(b) for b in beats] if beats is not None else []
+    beat_list.extend(s.beat for s in items)
+    if not items:
+        return []
+    idx = _BeatIndex(beat_list, beat_minutes)
+
+    groups: Dict[Tuple[str, str], List[Sighting]] = OrderedDict()
+    for s in items:
+        if inventory is not None and s.block_face_id not in inventory:
+            raise DataError(f"block face {s.block_face_id!r} is not in the inventory")
+        loc = s.block_face_id
+        if level == "zone":
+            assert inventory is not None
+            loc = inventory.zone_of(s.block_face_id)
+        groups.setdefault((s.plate_token, loc), []).append(s)
+
+    max_minutes = (max_gap_beats + 1) * beat_minutes + 0.5 * beat_minutes
+    stays: List[Stay] = []
+    for (token, loc), group in groups.items():
+        group.sort(key=lambda s: s.beat)
+        runs: List[List[Sighting]] = []
+        for s in group:
+            if runs:
+                prev = runs[-1][-1]
+                if s.beat == prev.beat:
+                    continue  # same vehicle twice at one beat (e.g. two faces in a zone)
+                same_session = idx.session[s.beat] == idx.session[prev.beat]
+                step = idx.index[s.beat] - idx.index[prev.beat]
+                if (
+                    same_session
+                    and step <= max_gap_beats + 1
+                    and minutes_between(prev.beat, s.beat) <= max_minutes
+                ):
+                    runs[-1].append(s)
+                    continue
+            runs.append([s])
+        for run in runs:
+            first, last = run[0], run[-1]
+            sid = idx.session[first.beat]
+            limit = None
+            if inventory is not None:
+                limit = inventory.time_limit(first.block_face_id, first.space_type or None)
+            stays.append(
+                Stay(
+                    plate_token=token,
+                    level=level,
+                    location=loc,
+                    first_seen=first.beat,
+                    last_seen=last.beat,
+                    sightings=len(run),
+                    beat_minutes=float(beat_minutes),
+                    left_censored=first.beat == idx.first_in_session[sid],
+                    right_censored=last.beat == idx.last_in_session[sid],
+                    time_limit_min=limit,
+                )
+            )
+    stays.sort(key=lambda st: (st.location, st.first_seen, st.plate_token))
+    return stays
+
+
+def survey_hours_from_beats(beats: Iterable[TimeLike], beat_minutes: float) -> float:
+    """Survey duration: number of distinct beats x beat length (each beat is one interval)."""
+    distinct = {parse_beat(b) for b in beats}
+    return len(distinct) * beat_minutes / 60.0
+
+
+@dataclass(frozen=True)
+class TurnoverRow:
+    """Turnover and duration statistics for one key."""
+
+    key: str
+    spaces: int
+    vehicles: int
+    survey_hours: float
+    space_hours: float
+    mean_duration_min: Optional[float]
+    median_duration_min: Optional[float]
+    overstays: int
+    assessed: int
+    censored: int
+
+    @property
+    def turnover(self) -> Optional[float]:
+        """Vehicles per space over the survey period."""
+        return self.vehicles / self.spaces if self.spaces else None
+
+    @property
+    def turnover_per_hour(self) -> Optional[float]:
+        """Vehicles per space per hour."""
+        t = self.turnover
+        return t / self.survey_hours if t is not None and self.survey_hours else None
+
+    @property
+    def utilization(self) -> Optional[float]:
+        """Space-hours used / space-hours supplied (time-averaged occupancy)."""
+        supply = self.spaces * self.survey_hours
+        return self.space_hours / supply if supply else None
+
+    @property
+    def overstay_share(self) -> Optional[float]:
+        """Share of time-limited stays that overstayed (``None`` if none limited)."""
+        return self.overstays / self.assessed if self.assessed else None
+
+    def as_dict(self) -> Dict[str, object]:
+        """Plain-dict form."""
+        return {
+            "key": self.key,
+            "spaces": self.spaces,
+            "vehicles": self.vehicles,
+            "survey_hours": self.survey_hours,
+            "turnover": self.turnover,
+            "turnover_per_hour": self.turnover_per_hour,
+            "mean_duration_min": self.mean_duration_min,
+            "median_duration_min": self.median_duration_min,
+            "space_hours": self.space_hours,
+            "utilization": self.utilization,
+            "overstays": self.overstays,
+            "assessed_for_overstay": self.assessed,
+            "overstay_share": self.overstay_share,
+            "censored_stays": self.censored,
+        }
+
+
+def _stay_key(stay: Stay, inventory: Inventory, by: str) -> str:
+    if stay.level == "block_face":
+        return inventory.key_of(stay.location, by)
+    if by == "block_face":
+        raise ValueError("zone-level stays cannot be summarised by block_face")
+    return stay.location if by == "zone" else "total"
+
+
+def turnover_summary(
+    stays: Sequence[Stay],
+    inventory: Inventory,
+    *,
+    by: str = "zone",
+    survey_hours: Optional[float] = None,
+    beats: Optional[Iterable[TimeLike]] = None,
+    overstay_basis: str = "minimum",
+) -> List[TurnoverRow]:
+    """Turnover, duration, space-hours and overstay statistics per key.
+
+    Survey hours come from ``survey_hours``, else from ``beats``
+    (:func:`survey_hours_from_beats`), else from the span of the stays
+    (first sighting to last sighting plus one beat, a single-session assumption).
+    Spaces are the full inventory of each key (part-time windows ignored);
+    keys of the inventory without any stay are reported with zero vehicles.
+    """
+    check_grouping(by)
+    if overstay_basis not in OVERSTAY_BASES:
+        raise ValueError(f"overstay_basis must be one of {OVERSTAY_BASES}")
+    if survey_hours is None:
+        if not stays:
+            raise DataError("no stays and no survey_hours/beats given")
+        beat = stays[0].beat_minutes
+        if beats is not None:
+            survey_hours = survey_hours_from_beats(beats, beat)
+        else:
+            start = min(s.first_seen for s in stays)
+            end = max(s.last_seen for s in stays)
+            survey_hours = (minutes_between(start, end) + beat) / 60.0
+    if survey_hours <= 0:
+        raise ValueError("survey_hours must be positive")
+
+    if by == "block_face":
+        keys = inventory.face_ids()
+    elif by == "zone":
+        keys = inventory.zones()
+    else:
+        keys = ["total"]
+    grouped: Dict[str, List[Stay]] = OrderedDict((k, []) for k in keys)
+    for st in stays:
+        grouped.setdefault(_stay_key(st, inventory, by), []).append(st)
+
+    rows: List[TurnoverRow] = []
+    for key, group in grouped.items():
+        durations = [s.estimated_duration_min for s in group]
+        flags = [s.overstay(overstay_basis) for s in group]
+        assessed = [f for f in flags if f is not None]
+        rows.append(
+            TurnoverRow(
+                key=key,
+                spaces=inventory.capacity_for_key(key, by),
+                vehicles=len(group),
+                survey_hours=survey_hours,
+                space_hours=sum(durations) / 60.0,
+                mean_duration_min=statistics.mean(durations) if durations else None,
+                median_duration_min=statistics.median(durations) if durations else None,
+                overstays=sum(1 for f in assessed if f),
+                assessed=len(assessed),
+                censored=sum(1 for s in group if s.censored),
+            )
+        )
+    return rows
+
+
+def accumulation_from_stays(
+    stays: Iterable[Stay], beats: Iterable[TimeLike]
+) -> List[Tuple[_dt.datetime, int]]:
+    """Vehicles parked at each beat according to the stays (accumulation curve)."""
+    stay_list = list(stays)
+    times = sorted({parse_beat(b) for b in beats})
+    return [(t, sum(1 for s in stay_list if s.first_seen <= t <= s.last_seen)) for t in times]
+
+
+def duration_distribution(
+    stays: Iterable[Stay], edges_min: Sequence[float] = (30, 60, 120, 180, 240)
+) -> List[Dict[str, object]]:
+    """Frequency table of estimated durations in classes bounded by ``edges_min``.
+
+    Classes are ``<= e1``, ``(e1, e2]``, ..., ``> ek``.
+    """
+    edges = sorted(edges_min)
+    durations = [s.estimated_duration_min for s in stays]
+    labels = [f"<= {edges[0]:g} min"]
+    labels += [f"{a:g}-{b:g} min" for a, b in zip(edges, edges[1:])]
+    labels.append(f"> {edges[-1]:g} min")
+    counts = [0] * len(labels)
+    for d in durations:
+        pos = 0
+        while pos < len(edges) and d > edges[pos] + 1e-9:
+            pos += 1
+        counts[pos] += 1
+    total = len(durations)
+    return [
+        {"class": lab, "stays": n, "share": (n / total if total else None)}
+        for lab, n in zip(labels, counts)
+    ]