75 lines
4.9 KiB
Markdown
75 lines
4.9 KiB
Markdown
# PulseCast / Cool City paper
|
||
|
||
## Branch `feat/cool-city` — event paper
|
||
|
||
This branch is the **Cool City** event report. `main.md` is the 4-page event paper and `CoolCity-Hackathon-Report.pdf` is the generated PDF. The prior staffing paper remains published at the DOI below; `PulseCast-*.pdf` and `main-extended.md` are the prior paper, not the Cool City event report. Do not merge this branch until the event review.
|
||
|
||
## Published (prior staffing paper)
|
||
|
||
**Zenodo:** https://zenodo.org/records/24217623
|
||
**DOI:** https://doi.org/10.5281/zenodo.24217623
|
||
**Concept DOI:** https://doi.org/10.5281/zenodo.24217622
|
||
|
||
| File | What it is | Status |
|
||
|---|---|---|
|
||
| `CoolCity-Hackathon-Report.pdf` | 4-page A4 Cool City event report | Final draft (branch) |
|
||
| `main.md` | Cool City event report source | Final draft (branch) |
|
||
| `PulseCast-Hackathon-Report.pdf` | Prior staffing event report | Published; do not edit |
|
||
| `PulseCast-Extended-Paper.pdf` | Prior staffing extended paper | Published; do not edit |
|
||
| `main-extended.md` | Prior staffing extended source | Cool City rewrite post-event/TBD |
|
||
| `ZENODO.md` | Prior paper metadata; Cool City metadata TBD | Working document |
|
||
| `references.md` | Prior paper reference list | Working document |
|
||
| `OUTLINE.md` | Prior writing plan | Working document |
|
||
| `figures/` | Figures for both papers | Mixed; `fig_cool_routes.png` is the Cool City route map |
|
||
| `research/` | Research notes (code audit, privacy law, sensing, heatmap, PETs, applications, data quality) | Private; do not upload |
|
||
| `build/` | HTML/CSS/PDF build artifacts | Working files |
|
||
|
||
## Build
|
||
|
||
The upload-ready PDFs were generated from Markdown via `marked` and headless Chrome with `build/style.css` (A4; 4 pages for the short report, 11 pages for the extended paper). `build/` is a working directory, not an upload artifact. Figure paths are relative to the repository root:
|
||
|
||
```text
|
||
figures/fig_sensor_map.png
|
||
figures/fig_hourly_profile.png
|
||
figures/fig_quantization.png
|
||
figures/fig_architecture.png
|
||
figures/fig_plan.png
|
||
figures/fig_forecast.png
|
||
```
|
||
|
||
`fig_plan.png` is a print reconstruction of the live plan screen for `scenario=sunny-saturday-market`, `standard=standard` (live API query, 14 Nov 2026; values: 5 peak staff, 172 staff-hours, €2,752, 100% coverage, €5,600 flat schedule). Replace it with the raw screenshot file if you prefer the exact pixels.
|
||
|
||
## Verification status
|
||
|
||
- Numbers: checked against `OKF_Vault/mission/data.md`, the generated `metrics.json`, and `research/07-data-quality.md`.
|
||
- Canonical metrics: production 7-day **3.32 / 27.5% / 0.777**; day-ahead weather **3.36 / 27.8% / 0.763**; seasonal naive **5.40 / 44.7% / 0.462**. The mission brief’s 3.36/27.8/0.779 was the quick baseline; the paper explains the difference once.
|
||
- Deployment: live app https://pulse.noelsabia.dev; API https://api-pulse.noelsabia.dev.
|
||
- v1.1 images: api 16.9 MB, web 249 MB, ml 952 MB.
|
||
- Plan latency: 19 ms cold on v1.1; contract < 2 s.
|
||
- v1.1 120-client Cloudflare k6: 120/120 SSE opened and closed, 0 connection errors, p95 event 331 ms, p95 scenario 646 ms, presenter POST 49.60 ms, 4m57.9s. The v1.0 baseline was 1.03 s / 194 ms / 82.69 ms / 4m53s; the papers report v1.1.
|
||
- Per-sensor MAE: computed from the production 7-day model; `n ≈ 669` per sensor.
|
||
- Figures: generated from the raw CSV and the trained model; the plan screen is a print reconstruction of the provided screenshot.
|
||
- References: 9 in Version A, 44 in Version B; all are real sources from the research notes. Verify DOIs/URLs before submission.
|
||
- AI disclosure: included in both versions; the text says the authors checked each number and citation, and flags legal/guidance/inference sources rather than claiming universal verification.
|
||
|
||
## Open items (not upload blockers)
|
||
|
||
- [x] Canonical metrics (3.32/27.5/0.777 production; 3.36/27.8/0.763 day-ahead).
|
||
- [x] v1.1 120-client k6 result, image sizes, and plan latency.
|
||
- [x] Live app/API URLs.
|
||
- [x] Author name and ORCID (Noel Sabia, 0009-0008-3064-7573); affiliation intentionally blank.
|
||
- [x] Cold deployment time documented as not measured.
|
||
- [x] Version A page count: 4 A4 pages.
|
||
- [ ] Optional: replace the print reconstruction with the raw plan screenshot file.
|
||
- [ ] Optional: replace internal project-note citations with public artifacts if a venue requires it.
|
||
|
||
## Source-of-truth rules
|
||
|
||
- Never invent a number, citation, dataset, result, or quote.
|
||
- Every number must match `OKF_Vault/mission/data.md`, the generated `metrics.json`, or a measured result.
|
||
- Weather is observed in training; forecast/current weather is used in the dashboard and scenarios.
|
||
- Values are estimated devices, not people; device penetration is unknown.
|
||
- The 8-sensor / 5-month / 580 m limitation is explicit.
|
||
- No city-wide heatmap, no annual seasonality, no live sensor feed, no proven ROI.
|
||
- The deployment description matches the real system: Nuxt SSR + Onyx, Go API/SSE, FastAPI, SKE namespace-only, Cloudflare Tunnel, build-time batch, cached fallback.
|