parkingstudy 0.1.0__py3-none-any.whl

parkingstudy-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+parkingstudy/__init__.py,sha256=poF-4qVoE_DMGSnu8LJGzcvF-1dV5KKB5SLnMqmENMA,3222
+parkingstudy/__main__.py,sha256=7qAmboxkh6K-H3Cnl81UQ63qzYybylKGiga0_j-9cyA,87
+parkingstudy/_time.py,sha256=iTNL2u9e1JghwAn1nAJ7zaSEZOqFMf34d--L3VcTqlQ,4021
+parkingstudy/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+parkingstudy/cli.py,sha256=HeQIJTagM5CxcGU-rdPTq_67FpHPAZn_dB49ATbWoX4,12526
+parkingstudy/errors.py,sha256=KEoR7_SZQYdv3XHTeZ1e8tm1kFvO0nefMUIAU_V5V4s,424
+parkingstudy/geojson.py,sha256=dIww7-gq_VtBGIUYzk9Pt-KsT9Vj5Ehav615O8rKt34,4113
+parkingstudy/heatmap.py,sha256=7SZaa8pHY0B4pSayQWWKQMNYJrGS_mDLhc6OeWmkSZ8,4454
+parkingstudy/inventory.py,sha256=n1mvB0YK_hAiDuIpARweXm_Sfw9QQrUzmzUtN2PpE3o,10224
+parkingstudy/io.py,sha256=Y9CHmk3cu0Sd1PXFtIg1Th7TVX83J6WLCUk0zD5uR4I,8866
+parkingstudy/lpr.py,sha256=8XrqiBP7iYdQXqsuCSF5l_3oskUsdRMDrzkD2uM-yfM,16255
+parkingstudy/occupancy.py,sha256=moq2bANo-xJx0Rk4y5RWhXpGu7z4M2Tb-BKp-pS1bgs,11806
+parkingstudy/pricing.py,sha256=Fp2ITj2bxtynqbKdR6LZczKnwyl74Mhgy6HBC-MvDOY,7616
+parkingstudy/privacy.py,sha256=4SC-N_jxQfiYYHf1Qvsf6dh9zbPS_jN26poiimGngTU,5430
+parkingstudy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+parkingstudy-0.1.0.dist-info/licenses/LICENSE,sha256=Z9meOk3opsRgHOqC5mA4B8NjZoU5WU1Kqhn82FL4ICs,1072
+parkingstudy-0.1.0.dist-info/METADATA,sha256=ClS2C1brsThWTnHTKX00nDrwqOAl8tdy4Ze2Zdc3GIc,11985
+parkingstudy-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+parkingstudy-0.1.0.dist-info/entry_points.txt,sha256=bLsx4cerRONmmsBrSLDekLgkzsX1eikj7Rcvd5HR3dE,55
+parkingstudy-0.1.0.dist-info/top_level.txt,sha256=66lvWZGOjLlJdTNVFPsexS7V9rxDJf5YSOS1dqxbfSs,13
+parkingstudy-0.1.0.dist-info/RECORD,,

parkingstudy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

parkingstudy-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+parkingstudy = parkingstudy.cli:main

parkingstudy-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+parkingstudy