Guide de lecture du portail

Le portail rassemble beaucoup de pages : plus de 150. Ce guide explique comment elles s'articulent, ce que vous trouverez en haut et en bas de chacune, et par où commencer selon votre rôle dans l'équipe.

Organisation du portail

Comment lire une page

Les pages suivent toutes le même ordre de lecture. Quatre repères reviennent.

1. En haut, l'encadré « En bref ». Il dit en quatre lignes pour qui est la page, ce qu'elle contient, quelles données elle utilise et quand elle a été mise à jour. S'il ne vous concerne pas, passez à la page suivante.
2. Le contenu, découpé en sections courtes, avec des titres qui posent une question ou annoncent un résultat.
3. Sous chaque graphique ou tableau, « Comment lire ». Une ou deux phrases qui disent ce que représente chaque axe, chaque couleur ou chaque colonne, et la source (le fichier du bucket).
4. En bas, la section « Limites ». Ce que les données ne permettent pas de dire, et les précautions avant de réutiliser un chiffre.

Voici à quoi ressemblent ces repères :

Les conventions du portail

Les quatre gabarits de page

Pour ajouter une page, copiez le gabarit qui correspond, puis remplacez les textes entre crochets. Chaque gabarit respecte l'ordre de lecture commun. Les composants EnBref, CommentLire, Limites, Parcours et Terme sont disponibles dans toutes les pages .mdx sans import. Dans un fichier .md, qui n'accepte pas les composants, utilisez l'encadré :::info{title="En bref"}.

1. Page de données

Pour décrire un fichier ou une famille de fichiers du bucket (onglet Données SSP Cloud).

Code
---
title: "[Nom de la famille de données]"
sidebar_label: "[Libellé court]"
sidebar_icon: "database"
description: "[Une phrase : ce que contiennent les fichiers et à quoi ils servent.]"
---

<EnBref
  pourQui="[Data scientists, développeurs…]"
  contenu="[Les fichiers, leurs colonnes, leur période et un exemple de chargement.]"
  donnees="[Dossier du bucket, par exemple Fréquentation/…]"
  maj="[JJ/MM/AAAA]"
/>

[Deux ou trois phrases : d'où viennent les données, qui les produit, ce qu'elles mesurent.]

## Les fichiers

| Fichier | Lignes | Période | Granularité |
|---|---:|---|---|
| `[dossier/fichier.csv]` | [12 345] | [2021-2025] | [commune, jour] |

<CommentLire>
[Une ligne par fichier. « Granularité » dit à quel niveau chaque ligne se situe.]
</CommentLire>

## Les colonnes

| Colonne | Type | Exemple | Sens |
|---|---|---|---|
| `[code_insee]` | texte | 38185 | [Code de la commune] |

<CommentLire>
[Comment repérer la clé de jointure et les colonnes utiles.]
</CommentLire>

## Charger les données

```python
import duckdb
duckdb.sql("SELECT * FROM '[fichier.parquet]' LIMIT 5")
```

## Pièges

- [Encodage, doublons, codes de communes anciens…]

## Limites

<Limites>
- [Ce que ces données ne couvrent pas : période, territoire, unité.]
</Limites>

2. Fiche de site

Pour un site touristique (onglet Sites). Ces fiches sont des fichiers .md : l'encadré « En bref » s'écrit avec :::info. Le bloc entre les marqueurs AUTO est rempli par le script de génération : ne rien écrire dedans à la main.

Code
---
title: "[Nom du site]"
sidebar_label: "[Nom court]"
sidebar_icon: "map-pin"
description: "[Type de site, enjeu principal. Toute la donnée disponible et un plan de recherche.]"
site_key: "[cle-du-site]"
---

:::info{title="En bref"}
- **Pour qui** : [équipes qui travaillent sur P1, P3…]
- **Ce que vous trouverez** : fiche d'identité, enjeux de flux, données du SSP Cloud, sources publiques, plan de recherche.
- **Données utilisées** : [fichiers du bucket, BD TOPO, API Géo, sources publiques].
- **Mise à jour** : [JJ/MM/AAAA] ; bloc « Données du SSP Cloud » régénéré par script.
:::

[Deux phrases de présentation.]

## Fiche d'identité

| | |
|---|---|
| **Type** | [Lac, station, monument…] |
| **Commune** | [Nom (code INSEE), habitants] |
| **Centre** | [latitude N ; longitude E (source)] |
| **Accès** | [Route, transports en commun] |

## Enjeux de flux

- [Enjeu, rattaché à une problématique P1 à P5.]

<!-- AUTO:donnees-ssp:START -->
<!-- AUTO:donnees-ssp:END -->

## Plan de recherche

1. **[Question]**
   Données : [fichiers]. Livrable : [carte, indicateur…].

## Manques et à qui les demander

- **[Donnée manquante]** : [organisme ou expert].

## Limites

- [Chiffres à vérifier, période couverte, sources secondaires.]

3. Page DataViz

Pour une visualisation qui croise plusieurs fichiers autour d'une problématique (onglet DataViz). Le nom de fichier commence par un numéro pour l'ordre : 09-dataviz/[NN]-[nom].mdx, publié à l'adresse /dataviz/[nom]. Les composants de visualisation disponibles sont listés dans le registre src/components/dataviz/index.ts.

Code
---
title: "[Question posée, par exemple : quand les sentiers saturent-ils ?]"
sidebar_label: "[Libellé court]"
sidebar_icon: "chart-line"
description: "[Ce que la visualisation croise et pour quelle problématique.]"
---

<EnBref
  pourQui="[Équipes P2, chargés de mission…]"
  contenu="[Le croisement proposé et ce qu'il montre.]"
  donnees="[Fichier 1 du bucket ; fichier 2 du bucket]"
  maj="[JJ/MM/AAAA] ; agrégats calculés par [script]"
/>

<Problems ids="[P2]" />

## La question

[Deux phrases : ce que l'on cherche et pourquoi ces fichiers.]

## La visualisation

{/* Composant de visualisation du registre datavizComponents, ou diagramme Mermaid. */}

```mermaid
xychart-beta
  title "[Titre du graphique]"
  x-axis [jan, fev, mar]
  y-axis "[Unité]" 0 --> 100
  bar [20, 45, 80]
```

<CommentLire>
[Ce que représentent les axes, les couleurs, l'unité.] Source : `[dossier/fichier]` (bucket SSP Cloud).
</CommentLire>

## Ce qu'on en retient

- [Constat 1, avec son chiffre.]
- [Constat 2 (déduit), si le chiffre est calculé.]

## Pour aller plus loin

- [Lien vers l'analyse détaillée, la fiche de données, la problématique.]

## Limites

<Limites>
- [Période, couverture, biais de mesure.]
</Limites>

4. Page d'analyse

Pour présenter des valeurs lues dans un fichier : saisonnalité, pics, comparaisons (onglet Analyses).

Code
---
title: "[Thème analysé]"
sidebar_label: "[Libellé court]"
sidebar_icon: "chart-column"
description: "[Les valeurs analysées et la période.]"
---

<EnBref
  pourQui="[Data scientists, jury…]"
  contenu="[Les analyses de la page, en une phrase.]"
  donnees="[Fichiers du bucket]"
  maj="[JJ/MM/AAAA], produit par scripts/analyse_ssp.py"
/>

## [Analyse 1 : question]

**Méthode.** [Filtre, agrégation, unité.]

```mermaid
xychart-beta
  title "[Titre]"
  x-axis [2021, 2022, 2023]
  y-axis "[Unité]" 0 --> 1000
  line [400, 650, 900]
```

<CommentLire>
[Axes, unité, période.] Source : `[dossier/fichier]` (bucket SSP Cloud).
</CommentLire>

**Résultat.** [Une phrase avec le chiffre clé ; « (déduit) » s'il est calculé.]

## Limites

<Limites>
- [Données manquantes, changement de méthode de comptage, valeurs aberrantes écartées.]
</Limites>

Parcours de lecture par profil

Quatre parcours, de cinq étapes chacun. Ils partent du même point, la présentation du hackathon, puis divergent selon ce que vous avez à produire.

Data scientist

1. 1
   Choisir une problématique10 min

   Les cinq questions et leurs cas d'usage.
2. 2
   Voir les données croisées15 min

   Les rapprochements déjà faits entre fichiers, par problématique.
3. 3
   Lire les analyses20 min

   Saisonnalité, pics, population présente : ce que disent déjà les valeurs.
4. 4
   Ouvrir les fichiers30 min

   Colonnes, volumes, périodes de chacun des 748 fichiers.
5. 5
   Éviter les pièges10 min

   Les erreurs relevées dans les sources avant de s'y fier.

Développeur

1. 1
   Accéder au SSP Cloud et au dépôt10 min

   Stockage S3, clés d'accès en variables d'environnement.
2. 2
   Parcourir les scripts15 min

   Un script par API : authentification et paquets nécessaires.
3. 3
   Charger les transports20 min

   Catalogue des jeux GTFS et temps réel couvrant l'Isère.
4. 4
   Ajouter les fonds de carte15 min

   BD TOPO, géocodage, serveurs MCP de l'IGN.
5. 5
   Outils d'accès aux données15 min

   API data.gouv.fr, exports Parquet, API Géo.

Chargé de mission tourisme

1. 1
   Comprendre les problématiques10 min

   Ce que les territoires attendent du hackathon.
2. 2
   Ouvrir la fiche d'un site connu15 min

   Lac de Paladru, Bastille, Les 2 Alpes… et toute la donnée disponible.
3. 3
   La grille Optimum touristique10 min

   Les trois dimensions pour juger d'un niveau de fréquentation.
4. 4
   Regarder les visualisations15 min

   Les croisements de données, lisibles sans code.
5. 5
   Vérifier un mot5 min

   Les sigles du portail expliqués simplement.

Jury

1. 1
   Le cadre du hackathon5 min

   Organisateur, territoire, ressources mises à disposition.
2. 2
   Les cinq problématiques10 min

   Les questions auxquelles les équipes répondent.
3. 3
   Les projets proposés10 min

   Six projets réalisables en deux jours, avec leurs pièges.
4. 4
   Ce que montrent déjà les données10 min

   Pour situer les résultats présentés par les équipes.
5. 5
   Les données disponibles5 min

   Pour juger de ce qui était faisable avec les données fournies.

Limites