# Observable Workspace — In-N-Out x Séismes x OVNIs (Californie)

Workspace **Observable Framework** orienté data storytelling avec deux analyses géospatiales en Californie :

- **In-N-Out Seismic Challenge** : classement des restaurants In‑N‑Out selon une exposition aux séismes.
- **Paradoxe de l’Animal Style** : corrélation exploratoire entre observations OVNI et proximité d’un In‑N‑Out.

## Objectifs

- Démontrer une chaîne complète de visualisation interactive avec Observable Framework.
- Croiser des données hétérogènes (OSM/Overpass, USGS, jeu OVNI) avec un traitement géospatial léger.
- Produire des pages analytiques reproductibles, versionnables et publiables statiquement.

## Stack technique

- **Runtime / Build** : `@observablehq/framework` (v1.x)
- **Langage** : JavaScript ESM (`"type": "module"`)
- **Parsing CSV** : `d3-dsv`
- **Visualisation** : `Plot` (via Observable), `d3`, `topojson-client`
- **Topologie US** : `us-atlas@3` (chargement CDN)

## Architecture du projet

```text
observablehq.config.js      # Configuration Observable Framework
package.json                # Scripts npm + dépendances
docs/
  index.md                  # Page d'accueil
  in-n-out-california.md    # Analyse séismes ↔ In-N-Out
  ufo-animal-style-paradox.md # Analyse OVNI ↔ In-N-Out
  data/
    in-n-out-ca-overpass.json.js
    ca-earthquakes-last365d.json.js
    in-n-out-ca-csv.json.js
    ufo-ca-sightings-v2.json.js
    ...
```

## Configuration Observable

Le fichier `observablehq.config.js` définit :

- `root: "docs"` : toutes les pages et données vivent sous `docs/`
- `title: "Observable Workspace"`
- `pager: false`
- `toc: true`
- `theme: "dashboard"`

## Pipeline de données

### 1) In-N-Out (source primaire Overpass)

Le module `docs/data/in-n-out-ca-overpass.json.js` :

- interroge Overpass API pour les POI In‑N‑Out (`node/way/relation`),
- normalise les attributs (`id`, `latitude`, `longitude`, `name`, `city`, `address`, `postcode`),
- déduplique par coordonnée arrondie,
- tente plusieurs endpoints Overpass (fallback de résilience),
- bascule sur un fallback CSV GitHub en cas d’échec.

### 2) Séismes Californie

Le dataset `ca-earthquakes-last365d.json` est utilisé dans la page `in-n-out-california.md` pour :

- filtrer les séismes dans une bounding box Californie,
- calculer la distance haversine de chaque séisme à chaque magasin,
- agréger des métriques locales (`quakeCount`, `maxMagnitude`, `avgMagnitude`, `nearestKm`),
- produire un **Shake Index** composite.

Formule utilisée :

`shakeIndex = quakeCount * 1.5 + maxMagnitude * 12 + max(0, radiusKm - min(nearestKm, radiusKm)) * 0.25`

### 3) OVNI Californie

La page `ufo-animal-style-paradox.md` :

- charge les observations OVNI et les points In‑N‑Out,
- calcule le magasin le plus proche pour chaque observation (distance haversine),
- marque `closeToBurger` selon un rayon interactif,
- agrège des hotspots via regroupement par magasin le plus proche,
- expose des KPIs interactifs (taux de proximité, volume, durée moyenne, etc.).

## Visualisations

- Bar charts classés (top/bottom stores)
- Carte Californie (projection Albers)
- Nuages de points et outils de filtrage (`Inputs.select`, `Inputs.range`)
- Tooltips détaillés pour exploration ad hoc

## Exécution locale

Pré-requis :

- Node.js 18+ recommandé
- npm

Installation :

```bash
npm install
```

Développement (live preview) :

```bash
npm run dev
```

Build statique :

```bash
npm run build
```

## Sorties et dossiers générés

- `dist/` : artefacts de build statique (à ne pas versionner)
- `docs/.observablehq/` : cache/framework interne (à ne pas versionner)

Le `.gitignore` est configuré pour ignorer ces dossiers de cache/génération.

## Qualité, limites et reproductibilité

- Les données externes (Overpass, CDN, sources tierces) peuvent varier dans le temps.
- Les métriques proposées sont exploratoires et non causales.
- Le pipeline privilégie robustesse et disponibilité (fallback réseau) plutôt qu’une ETL lourde.

## Scripts npm

- `npm run dev` → `observable preview`
- `npm run build` → `observable build`

## Publication Git

Ce dépôt est prévu pour être poussé sur un remote Gitea.
Le README sert de documentation technique de référence pour maintenance, reprise et extension du projet.