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

63 lines
3.4 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 layout placeholder; replace it with a live screenshot before submission.
## 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 placeholder.
- References: 12 in Version A, 37 in Version B; all are real sources from the research notes. Verify DOIs/URLs before submission.
- AI disclosure: included in both versions.
## 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.
- [ ] Live plan-screen screenshot (the current figure is a labelled placeholder).
- [ ] Public code repository URL (demo is filled; code is still `[TODO]`).
- [ ] Author names and affiliation.
- [ ] 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.