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

58 lines
3.1 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; ~5–6 pages in a compact layout |
| `main-extended.md` | Version B — 10–12 page Zenodo paper | Draft; ~9,200 words |
| `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`.
- Metrics discrepancy: `metrics.json` reports **3.32 / 27.5% / 0.777** for the production 7-day model and **3.36 / 27.8% / 0.763** for the day-ahead model; the mission brief lists **3.36 / 27.8% / 0.779**. The paper uses the generated metrics and flags the difference. The human must confirm the canonical run.
- k6: only a local 3-VU SSE smoke test (p95 656 ms) exists. The 120-client cluster run is still `[TODO]`.
- 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, 35 in Version B; all are real sources from the research notes. Verify DOIs/URLs before submission.
- AI disclosure: included in both versions.
## Known TODOs
- [ ] Canonical metrics decision (3.32/27.5/0.777 vs 3.36/27.8/0.779).
- [ ] 120-client k6 result and system metrics (image sizes, cold deployment time).
- [ ] Live plan-screen screenshot.
- [ ] Demo URL and public code repository URL.
- [ ] Author names and affiliation.
- [ ] 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.