parkingstudy 0.1.0__tar.gz

parkingstudy-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- `Inventory` / `InventoryRecord`: spaces by block face, zone, space type and facility, with
+  time limits, free-text restrictions, part-time availability windows and hourly rates;
+  supply summaries.
+- Occupancy counts by beat: `occupancy_by_beat`, `peak_occupancy`, `effective_capacity`
+  (85 % target, configurable), `practical_capacity` (overridable facility factors),
+  `capacity_assessment`, `accumulation_curve`, `space_hours`.
+- Licence-plate beat surveys: `build_stays` (gap tolerance, session-aware censoring flags,
+  block-face or zone linking), `turnover_summary` (turnover, mean/median duration,
+  space-hours, utilization, overstay share on a conservative or best-estimate basis),
+  `accumulation_from_stays`, `duration_distribution`.
+- `utilization_heatmap` tables (key x time-of-day bin) with CSV export.
+- Demand-responsive pricing: `PricingPolicy`, `SFMTA_POLICY` (SFMTA 2017 meter policy),
+  `SFPARK_PILOT_POLICY`, `recommend_rate(s)`, `mean_occupancy`.
+- Privacy: `PlateHasher` (HMAC-SHA256 with a secret salt), `generate_salt`,
+  `normalize_plate`, `anonymise_rows`, `anonymise_csv`; readers refuse raw plates without
+  a salt and no output contains raw plates.
+- GeoJSON join of results to block faces (`join_to_geojson`).
+- `parkingstudy` command line: `salt`, `hash-plates`, `inventory`, `occupancy`, `turnover`,
+  `heatmap`, `pricing`, `geojson`.

parkingstudy-0.1.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "parkingstudy"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://gitlab.com/geophilo1/parkingstudy_sdk"
+url: "https://pypi.org/project/parkingstudy/"
+abstract: "Parking occupancy and turnover survey analysis: supply inventory by block face, zone and space type; occupancy by time beat with peak, effective (85 % target) and practical capacity; licence-plate beat surveys giving durations, turnover, overstay and space-hours with salted HMAC plate anonymisation; zone-by-hour utilization heatmaps; configurable SFMTA/SFpark-style demand-responsive pricing rules; and GeoJSON joins to block faces."
+keywords:
+  - parking
+  - parking occupancy
+  - parking turnover
+  - licence plate survey
+  - demand-responsive pricing
+  - transport planning

parkingstudy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parkingstudy-0.1.0/MANIFEST.in

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

parkingstudy-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: parkingstudy
+Version: 0.1.0
+Summary: Parking occupancy and turnover survey analysis: inventory, occupancy by beat, effective capacity, licence-plate turnover and overstay with salted plate hashing, heatmaps, demand-responsive pricing rules and GeoJSON block-face joins.
+Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/geophilo1/parkingstudy_sdk
+Project-URL: Repository, https://gitlab.com/geophilo1/parkingstudy_sdk
+Project-URL: Issues, https://gitlab.com/geophilo1/parkingstudy_sdk/-/work_items
+Project-URL: Changelog, https://gitlab.com/geophilo1/parkingstudy_sdk/-/blob/main/CHANGELOG.md
+Keywords: parking,parking-study,parking-occupancy,parking-turnover,licence-plate-survey,lpr,curb-management,demand-responsive-pricing,sfpark,transport-planning,urban-planning,geojson,gis
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# parkingstudy
+
+[![PyPI version](https://img.shields.io/pypi/v/parkingstudy.svg)](https://pypi.org/project/parkingstudy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/parkingstudy.svg)](https://pypi.org/project/parkingstudy/)
+[![pipeline](https://gitlab.com/geophilo1/parkingstudy_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/parkingstudy_sdk/-/pipelines)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/geophilo1/parkingstudy_sdk/-/blob/main/LICENSE)
+
+**Parking occupancy and turnover survey analysis for planners.**
+
+`parkingstudy` turns the spreadsheets of a classic parking study into the numbers
+a parking management plan needs:
+
+- **Inventory**: spaces by block face, zone, space type and facility, with time limits,
+  restrictions, part-time windows (clearways, street cleaning) and hourly rates.
+- **Occupancy counts by time beat**: occupancy rate, peak occupancy, effective capacity at
+  a target occupancy (85 % by default, configurable), practical capacity, accumulation
+  curve and space-hours of demand and supply.
+- **Licence-plate (beat / LPR) surveys**: stays and durations, turnover, mean and median
+  duration, overstay share against posted time limits, utilization.
+- **Heatmap tables** of occupancy by zone (or block face) x hour.
+- **Demand-responsive pricing rules**: the SFMTA occupancy-band policy and the SFpark
+  pilot table, both as configurable policies.
+- **GeoJSON join** of any result table to block-face geometries for mapping.
+- **Privacy by design**: licence plates are replaced on input by a salted keyed hash
+  (HMAC-SHA256). Raw plates are never stored in memory objects or written to outputs.
+
+Standard library only, no required dependencies. Requires Python 3.9 or newer.
+
+```bash
+pip install parkingstudy
+```
+
+---
+
+## Quick start (command line)
+
+Input files are plain CSV (column names are case-insensitive):
+
+| file | required columns | optional columns |
+|---|---|---|
+| inventory | `block_face_id`, `spaces` | `zone`, `space_type`, `facility` (`on_street`/`off_street`), `time_limit_min`, `restriction`, `unavailable` (`07:00-09:00;16:00-18:00`), `hourly_rate` |
+| counts | `block_face_id`, `beat`, `occupied` | `space_type`, `date` |
+| sightings | `block_face_id`, `beat`, and `plate_token` **or** `plate` | `space_type`, `date` |
+
+`beat` is a clock time (`08:30`) or an ISO date-time (`2026-03-10T08:30`).
+
+```bash
+# 1. Create a secret salt once per survey, keep it out of version control
+parkingstudy salt > survey.salt
+export PARKINGSTUDY_SALT=$(cat survey.salt)
+
+# 2. Anonymise the field sheets: the plate column is replaced by a token column
+parkingstudy hash-plates sightings_raw.csv -o sightings.csv
+
+# 3. Supply summary, occupancy by beat and peak vs. 85 % effective capacity
+parkingstudy inventory inventory.csv
+parkingstudy occupancy inventory.csv counts.csv --by zone -o occupancy.csv
+parkingstudy occupancy inventory.csv counts.csv --by zone --peak --target 0.85 \
+    --factor on_street=0.85 --factor off_street=0.90
+parkingstudy occupancy inventory.csv counts.csv --by zone --space-hours
+
+# 4. Turnover, duration and overstay from the plate survey
+parkingstudy turnover inventory.csv sightings.csv --by block_face --beat-minutes 30 \
+    --stays stays.csv -o turnover.csv
+parkingstudy turnover inventory.csv sightings.csv --durations      # duration classes
+
+# 5. Heatmap (zone x hour) and pricing recommendations for the 09:00-12:00 rate period
+parkingstudy heatmap inventory.csv counts.csv --by zone --bin-minutes 60 -o heatmap.csv
+parkingstudy pricing inventory.csv counts.csv --from 09:00 --to 12:00 --policy sfmta
+
+# 6. Map it: join any result CSV (key column) to block-face GeoJSON
+parkingstudy geojson block_faces.geojson turnover.csv -o turnover_map.geojson
+```
+
+Every analysis command writes CSV (or `--format json`) to standard output or `-o FILE`.
+`turnover` also accepts raw plates directly if a salt is supplied (`--salt-env VAR` or
+`--salt-file FILE`); without one it refuses to read them.
+
+## Quick start (Python)
+
+```python
+from parkingstudy import (
+    PlateHasher, read_inventory, read_counts, read_sightings,
+    capacity_assessment, build_stays, turnover_summary, utilization_heatmap,
+)
+
+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.spaces, row.effective_capacity, row.above_target)
+
+hasher = PlateHasher.from_env()            # salt from $PARKINGSTUDY_SALT
+sightings = read_sightings("sightings_raw.csv", hasher)   # plates hashed while reading
+stays = build_stays(sightings, beat_minutes=30, inventory=inv)
+for r in turnover_summary(stays, inv, by="block_face"):
+    print(r.key, r.turnover, r.mean_duration_min, r.overstay_share)
+
+print(utilization_heatmap(inv, counts, by="zone").to_csv())
+```
+
+See [`examples/quickstart.py`](examples/quickstart.py) for a complete synthetic survey.
+
+## API overview
+
+| area | objects |
+|---|---|
+| inventory | `InventoryRecord`, `Inventory` (`capacity`, `time_limit`, `hourly_rate`, `summary`) |
+| occupancy | `Count`, `occupancy_by_beat`, `peak_occupancy`, `effective_capacity`, `practical_capacity`, `capacity_assessment`, `accumulation_curve`, `space_hours`, `infer_beat_minutes` |
+| plate survey | `Sighting`, `build_stays`, `Stay`, `turnover_summary`, `TurnoverRow`, `accumulation_from_stays`, `duration_distribution` |
+| heatmap | `utilization_heatmap`, `HeatmapTable` (`get`, `max_cell`, `to_rows`, `to_csv`) |
+| pricing | `PricingPolicy`, `PriceBand`, `SFMTA_POLICY`, `SFPARK_PILOT_POLICY`, `recommend_rate`, `recommend_rates`, `mean_occupancy` |
+| GeoJSON | `join_to_geojson`, `rows_by_key`, `load_geojson`, `write_geojson` |
+| privacy | `PlateHasher`, `generate_salt`, `normalize_plate`, `anonymise_rows`, `anonymise_csv` |
+| I/O | `read_inventory`, `read_counts`, `read_sightings`, `write_rows`, `records_to_rows` |
+
+Aggregation everywhere uses `by="block_face" | "zone" | "total"`.
+
+## Method and sources
+
+**Occupancy.** Occupancy rate at a beat = vehicles / legal spaces available at that beat.
+Spaces inside an `unavailable` window count as zero supply; vehicles parked there are still
+counted, so rates above 100 % (illegal parking) are kept and flagged (`over_capacity`).
+Zone and total rates sum vehicles and spaces of the block faces counted at that beat.
+
+**Effective capacity** = spaces x target occupancy. The 85 % default is the
+"85 percent rule" for kerb parking advocated by D. Shoup, *The High Cost of Free Parking*
+(APA Planners Press, 2005): above roughly 85 % occupancy drivers start cruising for a space.
+**Practical capacity** (also "effective supply") multiplies spaces by an efficiency factor
+per facility type. The defaults (0.85 on-street, 0.90 off-street) are common planning rules
+of thumb rather than values from a standard; pass your own `factors=` / `--factor`.
+
+**Licence-plate beat survey.** A vehicle seen on consecutive beats at the same block face
+(or zone, `level="zone"`) is one stay. With beat length *b*, first and last sightings
+*t1* and *tn*: minimum duration = *tn - t1*; estimated duration = *tn - t1 + b* (each
+sighting stands for one beat, the usual beat-survey convention). The true duration lies
+between *tn - t1* and *tn - t1 + 2b*. Stays on the first or last beat of a survey session
+are flagged as censored. `max_gap_beats` tolerates missed reads.
+Turnover = vehicles / spaces over the survey period (and per hour). Space-hours of demand
+= sum of estimated durations; utilization = space-hours / (spaces x survey hours).
+**Overstay** compares a stay with the posted limit of its block face: the default
+`basis="minimum"` counts only stays certainly longer than the limit (enforcement-grade,
+conservative); `basis="estimate"` uses the estimated duration.
+
+**Pricing.** `SFMTA_POLICY` follows SFMTA, *Demand-responsive parking pricing policies:
+on-street parking meters and off-street lots* (5 December 2017): occupancy 80 % or above
+raises the hourly rate by 0.25, 60 % to below 80 % leaves it unchanged, below 60 % lowers
+it by 0.25, within 0.50 to 8.00 per hour. `SFPARK_PILOT_POLICY` is the four-band table
+reported for the 2011-2013 SFpark pilot (80-100 % +0.25, 60-80 % hold, 30-60 % -0.25,
+below 30 % -0.50, cap 6.00). Both are **configurable examples**: build a `PricingPolicy`
+with your own bands, steps, currency, floor, cap and rounding.
+
+**Plate anonymisation.** Plates are normalised (Unicode NFKC, upper case, letters and
+digits only) and replaced by HMAC-SHA256 (RFC 2104) keyed with a secret salt of at least
+16 bytes, truncated to 16 hex characters by default. Unlike an unsalted hash, tokens cannot
+be reversed by enumerating the small space of valid plates without the salt. Use a fresh
+salt per survey and destroy it afterwards. Licence plates are personal data under, for
+example, the EU GDPR and the Turkish KVKK (Law No. 6698); check the rules that apply to
+your survey.
+
+## Limitations
+
+- Beat surveys cannot see stays shorter than one beat that fall between two passes, so
+  turnover is underestimated and mean duration overestimated, more so with long beats.
+- Zone-level stays take the time limit of the first block face where the vehicle was seen.
+- A block face with several different time limits (for different space types) is not
+  assessed for overstay unless sightings carry a `space_type`.
+- No time zones; beats are naive local times. Bare clock times are treated as one day.
+- Practical-capacity factors and the SFpark pilot table are planning conventions and
+  secondary-source values; verify them for your context.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+python -m ruff check . && python -m ruff format --check src tests
+python -m mypy src
+```
+
+## License
+
+MIT License, see [LICENSE](LICENSE).
+
+## Academic citation
+
+If you use `parkingstudy` in research, please cite:
+
+```bibtex
+@software{eminoglu_parkingstudy,
+  author  = {Eminoğlu, Yusuf},
+  title   = {parkingstudy},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://gitlab.com/geophilo1/parkingstudy_sdk}
+}
+```

parkingstudy-0.1.0/README.md

@@ -0,0 +1,197 @@
+# parkingstudy
+
+[![PyPI version](https://img.shields.io/pypi/v/parkingstudy.svg)](https://pypi.org/project/parkingstudy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/parkingstudy.svg)](https://pypi.org/project/parkingstudy/)
+[![pipeline](https://gitlab.com/geophilo1/parkingstudy_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/parkingstudy_sdk/-/pipelines)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/geophilo1/parkingstudy_sdk/-/blob/main/LICENSE)
+
+**Parking occupancy and turnover survey analysis for planners.**
+
+`parkingstudy` turns the spreadsheets of a classic parking study into the numbers
+a parking management plan needs:
+
+- **Inventory**: spaces by block face, zone, space type and facility, with time limits,
+  restrictions, part-time windows (clearways, street cleaning) and hourly rates.
+- **Occupancy counts by time beat**: occupancy rate, peak occupancy, effective capacity at
+  a target occupancy (85 % by default, configurable), practical capacity, accumulation
+  curve and space-hours of demand and supply.
+- **Licence-plate (beat / LPR) surveys**: stays and durations, turnover, mean and median
+  duration, overstay share against posted time limits, utilization.
+- **Heatmap tables** of occupancy by zone (or block face) x hour.
+- **Demand-responsive pricing rules**: the SFMTA occupancy-band policy and the SFpark
+  pilot table, both as configurable policies.
+- **GeoJSON join** of any result table to block-face geometries for mapping.
+- **Privacy by design**: licence plates are replaced on input by a salted keyed hash
+  (HMAC-SHA256). Raw plates are never stored in memory objects or written to outputs.
+
+Standard library only, no required dependencies. Requires Python 3.9 or newer.
+
+```bash
+pip install parkingstudy
+```
+
+---
+
+## Quick start (command line)
+
+Input files are plain CSV (column names are case-insensitive):
+
+| file | required columns | optional columns |
+|---|---|---|
+| inventory | `block_face_id`, `spaces` | `zone`, `space_type`, `facility` (`on_street`/`off_street`), `time_limit_min`, `restriction`, `unavailable` (`07:00-09:00;16:00-18:00`), `hourly_rate` |
+| counts | `block_face_id`, `beat`, `occupied` | `space_type`, `date` |
+| sightings | `block_face_id`, `beat`, and `plate_token` **or** `plate` | `space_type`, `date` |
+
+`beat` is a clock time (`08:30`) or an ISO date-time (`2026-03-10T08:30`).
+
+```bash
+# 1. Create a secret salt once per survey, keep it out of version control
+parkingstudy salt > survey.salt
+export PARKINGSTUDY_SALT=$(cat survey.salt)
+
+# 2. Anonymise the field sheets: the plate column is replaced by a token column
+parkingstudy hash-plates sightings_raw.csv -o sightings.csv
+
+# 3. Supply summary, occupancy by beat and peak vs. 85 % effective capacity
+parkingstudy inventory inventory.csv
+parkingstudy occupancy inventory.csv counts.csv --by zone -o occupancy.csv
+parkingstudy occupancy inventory.csv counts.csv --by zone --peak --target 0.85 \
+    --factor on_street=0.85 --factor off_street=0.90
+parkingstudy occupancy inventory.csv counts.csv --by zone --space-hours
+
+# 4. Turnover, duration and overstay from the plate survey
+parkingstudy turnover inventory.csv sightings.csv --by block_face --beat-minutes 30 \
+    --stays stays.csv -o turnover.csv
+parkingstudy turnover inventory.csv sightings.csv --durations      # duration classes
+
+# 5. Heatmap (zone x hour) and pricing recommendations for the 09:00-12:00 rate period
+parkingstudy heatmap inventory.csv counts.csv --by zone --bin-minutes 60 -o heatmap.csv
+parkingstudy pricing inventory.csv counts.csv --from 09:00 --to 12:00 --policy sfmta
+
+# 6. Map it: join any result CSV (key column) to block-face GeoJSON
+parkingstudy geojson block_faces.geojson turnover.csv -o turnover_map.geojson
+```
+
+Every analysis command writes CSV (or `--format json`) to standard output or `-o FILE`.
+`turnover` also accepts raw plates directly if a salt is supplied (`--salt-env VAR` or
+`--salt-file FILE`); without one it refuses to read them.
+
+## Quick start (Python)
+
+```python
+from parkingstudy import (
+    PlateHasher, read_inventory, read_counts, read_sightings,
+    capacity_assessment, build_stays, turnover_summary, utilization_heatmap,
+)
+
+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.spaces, row.effective_capacity, row.above_target)
+
+hasher = PlateHasher.from_env()            # salt from $PARKINGSTUDY_SALT
+sightings = read_sightings("sightings_raw.csv", hasher)   # plates hashed while reading
+stays = build_stays(sightings, beat_minutes=30, inventory=inv)
+for r in turnover_summary(stays, inv, by="block_face"):
+    print(r.key, r.turnover, r.mean_duration_min, r.overstay_share)
+
+print(utilization_heatmap(inv, counts, by="zone").to_csv())
+```
+
+See [`examples/quickstart.py`](examples/quickstart.py) for a complete synthetic survey.
+
+## API overview
+
+| area | objects |
+|---|---|
+| inventory | `InventoryRecord`, `Inventory` (`capacity`, `time_limit`, `hourly_rate`, `summary`) |
+| occupancy | `Count`, `occupancy_by_beat`, `peak_occupancy`, `effective_capacity`, `practical_capacity`, `capacity_assessment`, `accumulation_curve`, `space_hours`, `infer_beat_minutes` |
+| plate survey | `Sighting`, `build_stays`, `Stay`, `turnover_summary`, `TurnoverRow`, `accumulation_from_stays`, `duration_distribution` |
+| heatmap | `utilization_heatmap`, `HeatmapTable` (`get`, `max_cell`, `to_rows`, `to_csv`) |
+| pricing | `PricingPolicy`, `PriceBand`, `SFMTA_POLICY`, `SFPARK_PILOT_POLICY`, `recommend_rate`, `recommend_rates`, `mean_occupancy` |
+| GeoJSON | `join_to_geojson`, `rows_by_key`, `load_geojson`, `write_geojson` |
+| privacy | `PlateHasher`, `generate_salt`, `normalize_plate`, `anonymise_rows`, `anonymise_csv` |
+| I/O | `read_inventory`, `read_counts`, `read_sightings`, `write_rows`, `records_to_rows` |
+
+Aggregation everywhere uses `by="block_face" | "zone" | "total"`.
+
+## Method and sources
+
+**Occupancy.** Occupancy rate at a beat = vehicles / legal spaces available at that beat.
+Spaces inside an `unavailable` window count as zero supply; vehicles parked there are still
+counted, so rates above 100 % (illegal parking) are kept and flagged (`over_capacity`).
+Zone and total rates sum vehicles and spaces of the block faces counted at that beat.
+
+**Effective capacity** = spaces x target occupancy. The 85 % default is the
+"85 percent rule" for kerb parking advocated by D. Shoup, *The High Cost of Free Parking*
+(APA Planners Press, 2005): above roughly 85 % occupancy drivers start cruising for a space.
+**Practical capacity** (also "effective supply") multiplies spaces by an efficiency factor
+per facility type. The defaults (0.85 on-street, 0.90 off-street) are common planning rules
+of thumb rather than values from a standard; pass your own `factors=` / `--factor`.
+
+**Licence-plate beat survey.** A vehicle seen on consecutive beats at the same block face
+(or zone, `level="zone"`) is one stay. With beat length *b*, first and last sightings
+*t1* and *tn*: minimum duration = *tn - t1*; estimated duration = *tn - t1 + b* (each
+sighting stands for one beat, the usual beat-survey convention). The true duration lies
+between *tn - t1* and *tn - t1 + 2b*. Stays on the first or last beat of a survey session
+are flagged as censored. `max_gap_beats` tolerates missed reads.
+Turnover = vehicles / spaces over the survey period (and per hour). Space-hours of demand
+= sum of estimated durations; utilization = space-hours / (spaces x survey hours).
+**Overstay** compares a stay with the posted limit of its block face: the default
+`basis="minimum"` counts only stays certainly longer than the limit (enforcement-grade,
+conservative); `basis="estimate"` uses the estimated duration.
+
+**Pricing.** `SFMTA_POLICY` follows SFMTA, *Demand-responsive parking pricing policies:
+on-street parking meters and off-street lots* (5 December 2017): occupancy 80 % or above
+raises the hourly rate by 0.25, 60 % to below 80 % leaves it unchanged, below 60 % lowers
+it by 0.25, within 0.50 to 8.00 per hour. `SFPARK_PILOT_POLICY` is the four-band table
+reported for the 2011-2013 SFpark pilot (80-100 % +0.25, 60-80 % hold, 30-60 % -0.25,
+below 30 % -0.50, cap 6.00). Both are **configurable examples**: build a `PricingPolicy`
+with your own bands, steps, currency, floor, cap and rounding.
+
+**Plate anonymisation.** Plates are normalised (Unicode NFKC, upper case, letters and
+digits only) and replaced by HMAC-SHA256 (RFC 2104) keyed with a secret salt of at least
+16 bytes, truncated to 16 hex characters by default. Unlike an unsalted hash, tokens cannot
+be reversed by enumerating the small space of valid plates without the salt. Use a fresh
+salt per survey and destroy it afterwards. Licence plates are personal data under, for
+example, the EU GDPR and the Turkish KVKK (Law No. 6698); check the rules that apply to
+your survey.
+
+## Limitations
+
+- Beat surveys cannot see stays shorter than one beat that fall between two passes, so
+  turnover is underestimated and mean duration overestimated, more so with long beats.
+- Zone-level stays take the time limit of the first block face where the vehicle was seen.
+- A block face with several different time limits (for different space types) is not
+  assessed for overstay unless sightings carry a `space_type`.
+- No time zones; beats are naive local times. Bare clock times are treated as one day.
+- Practical-capacity factors and the SFpark pilot table are planning conventions and
+  secondary-source values; verify them for your context.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+python -m ruff check . && python -m ruff format --check src tests
+python -m mypy src
+```
+
+## License
+
+MIT License, see [LICENSE](LICENSE).
+
+## Academic citation
+
+If you use `parkingstudy` in research, please cite:
+
+```bibtex
+@software{eminoglu_parkingstudy,
+  author  = {Eminoğlu, Yusuf},
+  title   = {parkingstudy},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://gitlab.com/geophilo1/parkingstudy_sdk}
+}
+```

parkingstudy-0.1.0/examples/quickstart.py

@@ -0,0 +1,121 @@
+"""Quick start: a synthetic one-morning parking survey analysed end to end.
+
+Run with ``python examples/quickstart.py``. Everything is generated in memory;
+the GeoJSON result is written to the system temporary directory.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import tempfile
+
+from parkingstudy import (
+    Count,
+    Inventory,
+    InventoryRecord,
+    PlateHasher,
+    Sighting,
+    build_stays,
+    capacity_assessment,
+    generate_salt,
+    join_to_geojson,
+    mean_occupancy,
+    occupancy_by_beat,
+    recommend_rates,
+    rows_by_key,
+    turnover_summary,
+    utilization_heatmap,
+    write_geojson,
+)
+
+rng = random.Random(42)
+
+# 1. Supply inventory --------------------------------------------------------
+inventory = Inventory(
+    [
+        InventoryRecord("N1", 12, "Centre", time_limit_min=60, hourly_rate=2.0),
+        InventoryRecord("N1", 2, "Centre", space_type="disabled"),
+        InventoryRecord("S1", 10, "Centre", time_limit_min=120, hourly_rate=2.0),
+        InventoryRecord("E1", 15, "Fringe", hourly_rate=1.0, unavailable="16:00-18:00"),
+    ]
+)
+
+# 2. Licence-plate beat survey, 08:00-12:00 every 30 minutes --------------------
+beats = [f"{h:02d}:{m:02d}" for h in range(8, 12) for m in (0, 30)] + ["12:00"]
+hasher = PlateHasher(generate_salt())  # in a real study: PlateHasher.from_env()
+sightings = []
+counts = []
+for face, spaces in (("N1", 14), ("S1", 10), ("E1", 15)):
+    parked = {}  # space index -> (raw plate, beats remaining)
+    for beat in beats:
+        for space in range(spaces):
+            plate, left = parked.get(space, (None, 0))
+            if left <= 0:
+                plate = None
+                if rng.random() < 0.75:
+                    plate = (
+                        f"35 {rng.choice('ABCDEFG')}{rng.choice('KLMN')} {rng.randint(100, 999)}"
+                    )
+                    left = rng.choice((1, 1, 2, 3, 4, 6))
+            if plate:
+                # The raw plate is hashed immediately and never stored.
+                sightings.append(Sighting.make(hasher(plate), face, beat))
+                parked[space] = (plate, left - 1)
+            else:
+                parked.pop(space, None)
+        n = sum(
+            1 for s in sightings if s.block_face_id == face and s.beat.strftime("%H:%M") == beat
+        )
+        counts.append(Count.make(face, beat, n))
+
+# 3. Occupancy and capacity -----------------------------------------------------
+print("Peak occupancy vs 85 % effective capacity")
+for row in capacity_assessment(inventory, counts, by="zone"):
+    print(
+        f"  {row.key:7s} peak {row.peak_occupied:3d}/{row.spaces} at {row.peak_beat:%H:%M}"
+        f"  effective {row.effective_capacity:5.1f}  surplus {row.surplus:+5.1f}"
+    )
+
+# 4. Turnover, duration and overstay -------------------------------------------
+stays = build_stays(sightings, 30, inventory=inventory, beats=beats)
+print("\nTurnover by block face")
+for r in turnover_summary(stays, inventory, by="block_face", beats=beats):
+    share = "-" if r.overstay_share is None else f"{r.overstay_share:.0%}"
+    print(
+        f"  {r.key}: {r.vehicles} vehicles, turnover {r.turnover:.2f}/space, "
+        f"mean stay {r.mean_duration_min:.0f} min, overstay {share}"
+    )
+
+# 5. Heatmap and pricing ---------------------------------------------------------
+print("\nOccupancy heatmap (zone x hour)")
+print(utilization_heatmap(inventory, counts, by="zone").to_csv(digits=2))
+occ = mean_occupancy(occupancy_by_beat(inventory, counts))
+rates = {f: inventory.hourly_rate(f) for f in inventory.face_ids()}
+for rec in recommend_rates(occ, rates):
+    print(
+        f"  {rec.key}: occupancy {rec.occupancy:.0%}, {rec.current_rate:.2f} -> {rec.new_rate:.2f}"
+    )
+
+# 6. Join to block-face geometry --------------------------------------------------
+faces = {
+    "type": "FeatureCollection",
+    "features": [
+        {
+            "type": "Feature",
+            "properties": {"block_face_id": fid},
+            "geometry": {
+                "type": "LineString",
+                "coordinates": [[27.13, 38.42 + i * 1e-3], [27.14, 38.42 + i * 1e-3]],
+            },
+        }
+        for i, fid in enumerate(inventory.face_ids())
+    ],
+}
+results = rows_by_key(
+    r.as_dict() for r in turnover_summary(stays, inventory, by="block_face", beats=beats)
+)
+joined = join_to_geojson(faces, results)
+path = os.path.join(tempfile.gettempdir(), "parkingstudy_quickstart.geojson")
+write_geojson(joined.geojson, path)
+print(f"\n{joined.matched} block faces written to {path}")