Merge branch 'master' into krish

Author: charafkamel

.github/workflows/deploy.yml

@@ -0,0 +1,54 @@
+name: Deploy site to GitHub Pages
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Build
+        env:
+          # Vite resolves base from index.html `./` so this isn't strictly required,
+          # but exposing PUBLIC_BASE lets future code branch on dev vs prod paths.
+          PUBLIC_BASE: ./
+        run: npm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,33 @@
+# Build artifacts
+dist/
+.vite/
+
+# Dependencies
+node_modules/
+.venv/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Python EDA scratch
+__pycache__/
+*.pyc
+.ipynb_checkpoints/
+.vercel
+
+docs/assets/
+docs/screenshots/
+docs/sketches/
+notebooks/
+data/
+process_book.md
+process_book.pdf
+screencast.md

.vercelignore

@@ -0,0 +1,24 @@
+# What NOT to upload to Vercel. The build only needs index.html, src/, public/,
+# data/processed/, vite.config.js and package*.json. Everything below is course
+# material, source data, or planning docs that would just bloat the upload.
+
+node_modules
+.git
+dist
+.vite
+.DS_Store
+
+# Course material & heavy source docs (254 MB of lecture PDFs, etc.)
+lectures/
+docs/
+notebooks/
+data/raw/
+.github/
+
+# Submission PDFs & planning / internal docs
+Milestone_*.pdf
+CLAUDE.md
+HANDOFF.md
+PLAN.md
+sketches.md
+Deep-research-data-sources.md

CLAUDE.md

@@ -0,0 +1,188 @@
+# COM-480 Data Visualization — Project Guardrails
+
+> This file is the canonical guardrail for any future work in this repo.
+> It encodes (a) what the course expects, (b) what the lectures taught,
+> (c) the milestone schedule, and (d) the working constraints for this team.
+> Read this first before writing or planning anything.
+
+---
+
+## 0. Critical context
+
+- **Course:** EPFL COM-480 — *Data Visualization*.
+- **Deliverable:** an interactive, D3.js-based web visualization that **tells a story**.
+- **Today:** 2026-05-26. **M3 deadline:** Friday 2026-05-29, 5pm. **~3 days left.**
+- **Project topic:** "What's in a barrel?" — a scrollytelling piece about one barrel of crude oil, from distillation tower through end-uses to the objects in a reader's day, plus a closing May 2026 epilogue.
+- **2026 context that shapes the project:** Iran/Hormuz crisis began 28 Feb 2026 → largest oil-market disruption since COVID. EIA STEO May 2026 cut 2026 demand growth from +1.2 Mb/d (Feb) to +0.2 Mb/d (May). IEA OMR May 2026 expects a 420 kb/d contraction. OPEC MOMR May 2026 still projects +1.2 Mb/d. Scene 6.5 of the site uses this as the crisis epilogue. Background and source list in `Deep-research-data-sources.md`.
+- **Storytelling is graded heavily.** Lecture `12_1_Storytelling.pdf` is the load-bearing reference. Lecture `7_2_Do_and_dont_viz.pdf` is the second guardrail.
+
+---
+
+## 1. Milestone schedule and weight
+
+| Milestone | Deadline | Weight | Status |
+|-----------|---------|--------|--------|
+| M1 — dataset, problematic, EDA, related work | 2026-03-20 | 10% | overdue, do retroactively for feedback |
+| M2 — 2-page plan + sketches + working skeleton website | 2026-04-17 | 10% | overdue, do retroactively for feedback |
+| M3 — final D3 viz + screencast (2 min) + process book (≤8 pages) + GitHub repo | 2026-05-29 | 80% | **active — 3 days** |
+
+**M3 grade breakdown:** Visualization 35% • Technical Implementation 15% • Screencast 25% • Process book 25%.
+
+**Late policy:** <24h → 80%, <48h → 70%. Anything past that drops fast. Plan for **2026-05-28** as internal cut-off.
+
+---
+
+## 2. Lecture index (guardrails)
+
+All PDFs live in `lectures/`. Reach for them in this order depending on what you're doing.
+
+### Foundations (web stack)
+- `2_Javascript.pdf` — JS essentials.
+- `3_More_javascript.pdf` — modern JS (modules, async).
+- `4_1_Data.pdf` — data acquisition, formats (CSV, JSON, TSV), cleaning basics.
+- `4_2_D3.pdf` — D3 core: selections, data joins, scales, axes.
+
+### Interaction & D3 patterns
+- `5_1_Interaction.pdf` — interaction grammar (hover, brush, zoom, linked views).
+- `5_2_More_interactive_d3.pdf` — transitions, enter/update/exit, dispatch.
+
+### Visual perception & design
+- `6_1_Perception_colors.pdf` — colorblind-safe palettes, sequential vs diverging vs categorical.
+- `6_2_Mark_channel.pdf` — marks (point/line/area) × channels (position/length/color/shape) and their effectiveness ranking.
+- `7_1_Designing_viz.pdf` — design process, sketching, iteration.
+- **`7_2_Do_and_dont_viz.pdf`** — **Tufte integrity rules** (data-ink ratio, lie factor, chartjunk, no unjustified 3D, start bar charts at 0, consistent intervals). Apply to every chart.
+
+### Spatial, tabular, network, text, sound
+- `8_1_Maps.pdf` — projections, choropleths, geographic data.
+- `8_2_Practical_maps.pdf` — Leaflet, Mapbox, TopoJSON.
+- `9_Text.pdf` — text viz (word clouds, topic modeling outputs, NLP-fed visuals).
+- `10_Graphs.pdf` — networks (force layouts, matrix view, arc diagrams).
+- `11_1_Tabular_data.pdf` — tables, heatmaps, parallel coordinates, scatterplot matrix.
+- `11_2_Sound_viz.pdf` — audio visualization (waveform, spectrogram).
+
+### Storytelling capstones (study these closely for M3)
+- **`12_1_Storytelling.pdf`** — **the most important lecture for grading.** Key takeaways:
+  - Stories are *emotional, memorable, impactful*. Build one — don't just dump charts.
+  - **Freytag's pyramid:** Exposition → Rising action → **Climax** → Falling action → Resolution. Map this to your scrolly/slides.
+  - **Segel & Heer (2010) design space:** Visual Design + Messaging + Interactivity. Genres include *magazine style, annotated chart, slideshow, comic strip, movie, science-fair poster, flowchart*.
+  - **Author-driven** (strong ordering, heavy messaging, limited interactivity) vs **Reader-driven** (weak ordering, light messaging, free interactivity). Best work picks a hybrid.
+  - **Three canonical structures:** Martini glass (author-led then opens up), Interactive slideshow, Drill-down story.
+  - "Add structure!" → Even an exploratory tool should have a guided entry path.
+  - "Compare this / to this?" → Replace descriptive titles with active titles. Use color *strategically*, not decoratively. Order categorical data meaningfully.
+- `12_2_Beyond_visualization.pdf` — what comes after viz (deployment, ethics, advanced media).
+
+---
+
+## 3. Hard rules pulled from the lectures
+
+Apply mechanically. Each one is a place graders deduct points.
+
+1. **Active titles, not descriptive titles.** "We invest primarily in four areas" beats "Investment by area".
+2. **Start bar chart Y-axis at 0.** Truncated bars = lie factor > 1.
+3. **Show all the data on time series; start the axis at a value that doesn't distort the trend.**
+4. **Consistent intervals on axes.** Don't mix yearly and quarterly without making the change obvious.
+5. **No unjustified 3D. No drop shadows. No gradient fills. No skeuomorphism.**
+6. **Order categorical data by value or by meaning, never alphabetically by default.**
+7. **Color = meaning.** Highlight one or two categories; neutralize the rest in grey.
+8. **Colorblind-safe.** Test with a simulator. Avoid red/green as the only distinguishing channel.
+9. **Channel choice follows the Mackinlay ranking:** position > length > angle/slope > area > color hue > volume. Don't encode quantitative data with hue alone.
+10. **Annotate.** Every climactic chart needs labels, arrows, and a one-sentence interpretation directly on the chart.
+11. **Mobile second.** Author for desktop; degrade gracefully. Don't ship a mobile-broken site.
+12. **Accessibility.** Keyboard reachable, ARIA labels on interactive SVG, reduced-motion respected.
+
+---
+
+## 4. Working constraints (this repo)
+
+### Tech stack (commit to these — no swaps mid-build)
+- **D3.js v7** (the course expects it; required for M3 grading).
+- **Vite + vanilla JS** or **Next.js** for the shell. Pick **one** and stick to it. (Recommendation: Vite + vanilla — faster build, no SSR complications, lighter for a 3-day sprint.)
+- **Scrollama** for scroll-triggered storytelling (the "interactive slideshow" Segel/Heer genre maps cleanly to scrollytelling).
+- **TopoJSON + d3-geo** if maps are needed.
+- **GitHub Pages** for hosting (free, satisfies M3's "host on GitHub" requirement).
+- **Tailwind or plain CSS** — your call, but no UI library that injects its own opinions (no MUI, no Chakra). Charts should be hand-built.
+
+### File layout (target)
+```
+.
+├── CLAUDE.md                  (this file)
+├── README.md                  (M3 deliverable — technical setup, usage)
+├── Milestone_1.pdf, _2.pdf, _3.pdf
+├── lectures/                  (reference only, don't edit)
+├── docs/                      (M1, M2, M3 written submissions + sketches)
+│   ├── milestone1.md
+│   ├── milestone2.md
+│   ├── sketches/
+│   └── process_book.pdf       (M3 final)
+├── data/                      (cleaned dataset + raw)
+│   ├── raw/
+│   └── processed/
+├── notebooks/                 (Python EDA, optional)
+├── src/                       (web app)
+│   ├── index.html
+│   ├── main.js
+│   ├── scenes/                (one file per story scene)
+│   ├── components/            (chart modules)
+│   ├── lib/                   (scales, color, utils)
+│   └── styles/
+└── public/
+```
+
+### Code style
+- D3 chart modules export a `render(container, data, options)` function. **No god-files.**
+- Animate `transform` and `opacity` only.
+- Define design tokens (colors, fonts, spacing) as CSS custom properties.
+- One commit per scene / per chart. Conventional commits (`feat:`, `fix:`, `docs:`).
+
+---
+
+## 5. Story-quality bar
+
+A submission gets a top grade only if it passes all of these:
+
+- **One sentence story.** You can summarize the project's claim in one sentence. ("X happened, and the data shows it could have been prevented because…")
+- **Freytag arc maps to scenes.** Each scene has a purpose: exposition / rising / climax / falling / resolution.
+- **Climax has a single dominant chart**, annotated, with active title.
+- **The reader can re-explore freely after the guided tour** (martini-glass structure).
+- **Every chart answers a specific question** stated in its title.
+- **Interactivity has a payoff** — hover/filter/drill must reveal something not visible at rest.
+- **Annotations on the chart, not in a side caption.** Eyes don't bounce.
+- **No chart bigger than what its data justifies.**
+
+---
+
+## 6. Process-book bar (worth 25% on its own)
+
+- ≤ 8 pages, designed (not a Word dump).
+- Reuses and expands M1/M2 sketches — shows evolution.
+- Calls out design *decisions* and *trade-offs*, not just what you built.
+- Peer-assessment table at the end (who did what).
+- Export to PDF and check it on a phone.
+
+---
+
+## 7. Screencast bar (worth 25%)
+
+- **Exactly 2 minutes.** Over = penalty.
+- Open with the *story claim*, not the tech stack.
+- Show the climax interaction in the first 30 seconds.
+- Voiceover, not text-on-screen narration.
+- End with a 5-second call to action ("explore at <url>").
+
+---
+
+## 8. What this project is NOT
+
+- Not a dashboard. (Dashboards are explicitly the *anti-pattern* of the storytelling lecture.)
+- Not a Tableau-style "here are 12 charts, pick one".
+- Not a tutorial for D3.
+- Not a research paper. Process book is for design decisions, not literature review.
+
+---
+
+## 9. When in doubt
+
+1. Open `12_1_Storytelling.pdf` — does the current scene fit *some* slot in Freytag's pyramid?
+2. Open `7_2_Do_and_dont_viz.pdf` — does the current chart violate any Tufte rule?
+3. Open `6_2_Mark_channel.pdf` — is the encoding using the best channel for the data type?
+4. If three answers are all yes → ship it. If any is no → fix before moving on.