Files
paper-how-to-use-this-techn…/README.md
T

63 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PulseCast paper
Two versions of the paper, plus the research trail.
| File | What it is | Status |
|---|---|---|
| `main.md` | Version A — 4–5 page hackathon technical report | Draft; ~3,600 words, 5 figures, 4 tables |
| `main-extended.md` | Version B — 10–12 page Zenodo paper | Draft; ~9,600 words, 37 references |
| `references.md` | Canonical reference list and verification checklist | Draft |
| `OUTLINE.md` | Writing plan, claims/non-claims, figures/tables | Working document |
| `figures/` | Generated figures used by both versions | Draft figures |
| `research/` | Research notes (code audit, privacy law, sensing, heatmap, PETs, applications, data quality) | Complete |
## Build
There is no Pandoc/LaTeX in this workspace. Render with any Markdown-to-PDF tool, or use a two-column template. Figure paths are relative to `paper/`:
```text
paper/figures/fig_sensor_map.png
paper/figures/fig_hourly_profile.png
paper/figures/fig_quantization.png
paper/figures/fig_architecture.png
paper/figures/fig_plan.png
paper/figures/fig_forecast.png
```
`fig_plan.png` is a print reconstruction of the provided live plan screen (same values: 5 staff, 100% coverage, €3,360, 25 h over / 0 h under). 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 `paper/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: 42.8 ms local v1.1; contract < 2 s.
- 120-client Cloudflare k6: 120/120 SSE opened and closed, 0 connection errors, p95 event 1.03 s, p95 scenario 194 ms, presenter POST 82.69 ms, 2,760 events, 4m53s.
- 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, 43 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.
## Known TODOs
- [x] Canonical metrics (3.32/27.5/0.777 production; 3.36/27.8/0.763 day-ahead).
- [x] 120-client k6 result, image sizes, and plan latency.
- [x] Live app/API URLs.
- [ ] Plan figure: currently reconstructed from the provided screenshot for print legibility. Replace with the raw screenshot file if you prefer the exact pixels.
- [x] Code release timing documented (after the hackathon); public URL to be added then.
- [x] Author name and ORCID (Noel Sabia, 0009-0008-3064-7573); affiliation intentionally blank.
- [ ] Cold deployment time.
- [ ] Replace internal project-note citations with public artifacts if a venue requires it.
- [ ] Final page-count trim for Version A if a strict 4–5 page limit applies.
## 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.