# Documentation des Scripts de Démonstration

## Vue d'ensemble

Ce document présente la documentation complète des deux scripts de démonstration créés pour illustrer les fonctionnalités des classes de données du wrapper API Atmo Data. Ces scripts utilisent des données réelles de l'API pour démontrer chaque méthode et propriété disponible.

---

## 📊 Script 1 : `demo_atmo_functions.py`

### Description générale
Script de démonstration complet pour la classe `IndiceAtmo`, illustrant toutes les fonctionnalités liées aux indices de qualité de l'air ATMO.

### Configuration
- **Région testée** : Île-de-France (AASQA 11)
- **Source de données** : API Atmo Data en temps réel
- **Date** : Jour d'exécution du script
- **Format** : GeoJSON
- **Conformité** : Notice officielle du 1er avril 2025

### Sections démontrées

#### 1. Propriétés de base (héritées d'AtmoDataBase)
```python
# Informations générales
atmo.aasqa           # Code AASQA
atmo.lib_zone        # Nom de la zone
atmo.source          # Nom de l'organisme
atmo.type_zone       # 'commune' ou 'EPCI'
atmo.code_zone       # Code INSEE

# Données temporelles
atmo.date_ech        # Date d'échéance
atmo.date_dif        # Date de diffusion

# Coordonnées
atmo.has_coordinates()    # Disponibilité coordonnées
atmo.coordinates          # Objet Coordinates si disponible
atmo.x_reg, atmo.y_reg   # Coordonnées réglementaires
atmo.epsg_reg            # Système de projection
```

#### 2. Propriétés spécifiques ATMO
```python
# Indice global
atmo.code_qual       # Code qualificatif (0-7)
atmo.lib_qual        # Libellé ("Bon", "Dégradé"...)
atmo.coul_qual       # Couleur hexadécimale

# Codes par polluant
atmo.code_no2        # Niveau NO2
atmo.code_so2        # Niveau SO2
atmo.code_o3         # Niveau O3
atmo.code_pm10       # Niveau PM10
atmo.code_pm25       # Niveau PM2.5

# Concentrations facultatives (μg/m³)
atmo.conc_no2        # Concentration NO2
atmo.conc_so2        # Concentration SO2
atmo.conc_o3         # Concentration O3
atmo.conc_pm10       # Concentration PM10
atmo.conc_pm25       # Concentration PM2.5
```

#### 3. Méthodes helper essentielles
```python
# Qualificatif et apparence
atmo.get_qualificatif()          # → "Dégradé"
atmo.get_color()                 # → ("#F0E641", (240, 230, 65))
atmo.get_emoji("round")          # → "🟡"
atmo.get_emoji("square")         # → "🟨"

# Tests de qualité
atmo.is_good_quality()           # → True si niveaux 1-2
atmo.is_poor_quality()           # → True si niveaux 4+

# Analyse des polluants
atmo.get_worst_pollutant()       # → ("O3", 3)
atmo.get_pollutants_summary()    # → Dict complet par polluant
atmo.get_concentrations()        # → Dict concentrations
atmo.get_responsible_pollutants() # → ["O3"] (règle officielle)

# Conformité notice officielle
atmo.is_commune_level()          # → True si type_zone='commune'
atmo.is_epci_level()            # → True si type_zone='EPCI'
```

#### 4. Fonctions centralisées (base)
```python
# Émojis et couleurs par niveau
atmo.get_emoji_by_level(3, "round")    # → "🟡"
atmo.get_emoji_by_level(3, "square")   # → "🟨"
atmo.get_color_by_level(3)             # → ("#F0E641", (240, 230, 65))
```

### Exemple de sortie
```
📍 Station sélectionnée: Tousson
🎯 ANALYSE RAPIDE:
   • Qualité globale: Dégradé (niveau 3)
   • Polluant problématique: ozone (niveau 3)
   • Couleur d'affichage: #F0E641 🟡

📈 ANALYSE PAR POLLUANT:
   • Dioxyde d'azote: 🔵 Bon (niveau 1)
   • Ozone: 🟡 Dégradé (niveau 3)
   • Particules PM10: 🔵 Bon (niveau 1)
```

### Usage
```bash
python demo_atmo_functions.py
```

---

## 🌸 Script 2 : `demo_pollen_functions.py`

### Description générale
Script de démonstration complet pour la classe `IndicePollen`, illustrant toutes les fonctionnalités liées aux indices pollen.

### Configuration
- **Ville testée** : Tomblaine (INSEE 54526)
- **Région** : Grand Est (AASQA 44)
- **Source de données** : API Atmo Data en temps réel
- **Date** : Jour d'exécution du script
- **Format** : GeoJSON

### Sections démonstrées

#### 1. Propriétés de base (héritées d'AtmoDataBase)
```python
# Informations générales
pollen.aasqa         # Code AASQA
pollen.lib_zone      # Nom de la zone
pollen.source        # Nom de l'organisme
pollen.alerte        # Statut d'alerte (True/False)

# Coordonnées et fonctions centralisées
pollen.has_coordinates()              # Disponibilité coordonnées
pollen.get_emoji_by_level(2, "round") # → "🟢"
pollen.get_color_by_level(2)          # → ("#50CCAA", (80, 204, 170))
```

#### 2. Propriétés spécifiques pollen
```python
# Codes par taxon (espèce)
pollen.code_ambr     # Ambroisie (0-6)
pollen.code_arm      # Armoise (0-6)
pollen.code_aul      # Aulne (0-6)
pollen.code_boul     # Bouleau (0-6)
pollen.code_gram     # Graminées (0-6)
pollen.code_oliv     # Olivier (0-6)

# Concentrations (grains/m³)
pollen.conc_ambr     # Concentration ambroisie
pollen.conc_arm      # Concentration armoise
pollen.conc_aul      # Concentration aulne
pollen.conc_boul     # Concentration bouleau
pollen.conc_gram     # Concentration graminées
pollen.conc_oliv     # Concentration olivier

# Taxons responsables (API)
pollen.pollen_resp   # Chaîne brute de l'API
```

#### 3. Méthodes helper spécialisées
```python
# Détection d'alertes
pollen.is_alert_active()             # → False

# Analyse des niveaux
pollen.get_highest_pollen()          # → ("arm", 2.0)
pollen.get_highest_concentration()   # → ("gram", 28.0)
pollen.get_dangerous_pollens()       # → [] (niveau ≥ 4)

# Taxons responsables (parsing intelligent)
pollen.get_responsible_pollens()     # → ["Armoise", "Graminées"]

# Données quantitatives
pollen.get_concentrations()          # → {"gram": 28.0, "arm": 5.9, ...}

# Résumé complet avec styles d'émojis
pollen.get_pollens_summary("round")  # Style rond par défaut
pollen.get_pollens_summary("square") # Style carré
```

#### 4. Structure du résumé complet
```python
summary = pollen.get_pollens_summary()
# Retourne pour chaque taxon :
{
    'code': 2.0,                           # Niveau de pollen
    'concentration': 5.9,                  # Grains/m³
    'qualificatif': 'Faible',             # Texte du niveau
    'espece': 'Armoise',                   # Nom complet
    'couleur': ('#50CCAA', (80, 204, 170)), # Hex + RGB
    'emoji': '🟢',                         # Émoji selon style
    'emoji_round': '🟢',                   # Émoji rond
    'emoji_square': '🟩'                   # Émoji carré
}
```

### Exemple de sortie
```
📍 Station sélectionnée: Tomblaine
🎯 5. TAXONS RESPONSABLES DE L'INDICE (API):
   • get_responsible_pollens(): ['Armoise', 'Graminées']
   → Espèces responsables selon l'API: Armoise, Graminées

🔬 3. CONCENTRATION LA PLUS ÉLEVÉE:
   • get_highest_concentration(): ('gram', 28.0)
   → Espèce: Graminées
   → Concentration: 28.0 grains/m³

🎨 8. TEST DES STYLES D'ÉMOJIS:
   • Comparaison des styles par défaut:
     - Armoise: Rond=🟢 | Carré=🟩
     - Graminées: Rond=🟢 | Carré=🟩
```

### Usage
```bash
python demo_pollen_functions.py
```

---

## 🔧 Fonctionnalités communes

### Système d'émojis unifié
Les deux scripts démontrent le système d'émojis centralisé :

```python
# Styles disponibles
"round"  → 🟢 🟡 🔴 🟣 ⚫  # Formes rondes
"square" → 🟩 🟨 🟥 🟪 ⬛  # Formes carrées

# Usage dans les classes
atmo.get_emoji("round")                    # IndiceAtmo
pollen.get_pollens_summary("square")       # IndicePollen avec style
```

### Conformité réglementaire
Les deux scripts valident la conformité avec :
- **Arrêté du 10 juillet 2020** (réglementation ATMO)
- **Notice technique du 1er avril 2025** (spécifications officielles)
- **Structure des données API** (pages 12-14 de la notice)
- **Codes couleur officiels** (tableau page 6 de la notice)

### Gestion des erreurs
```python
try:
    # Connexion API
    client = AtmoDataClient()
    success = client.auto_login()
    
    # Récupération données
    data = client.get_indices_atmo(...)
    
except AtmoDataException as e:
    print(f"❌ Erreur API: {e}")
except Exception as e:
    print(f"❌ Erreur inattendue: {e}")
```

---

## 📋 Informations techniques

### Prérequis
- **Python 3.7+**
- **Fichier `credentials.json`** configuré
- **Connexion internet** pour l'API
- **Modules** : `atmo_data_client`, `atmo_data_models`, `constantes`

### Données utilisées
- **ATMO** : 1288+ stations Île-de-France
- **Pollen** : Données Tomblaine (Grand Est)
- **Format** : GeoJSON avec objets typés
- **Temps réel** : Date du jour d'exécution

### Structure de sortie
1. **Connexion et récupération** des données
2. **Propriétés de base** (héritées)
3. **Propriétés spécifiques** (ATMO/Pollen)
4. **Méthodes helper** (une par une)
5. **Exemples pratiques** d'utilisation
6. **Informations techniques** et conformité

### Performance
- **Temps d'exécution** : ~3-5 secondes
- **Données récupérées** : 1-1500 objets selon l'endpoint
- **Mémoire** : ~10-50 MB selon le volume
- **Connexions** : 1 session HTTP réutilisée

---

## 💡 Cas d'usage

### Pour les développeurs
- **Apprentissage** : Comprendre l'utilisation de chaque méthode
- **Tests** : Valider le bon fonctionnement des classes
- **Intégration** : Voir des exemples concrets d'usage
- **Débogage** : Identifier les problèmes potentiels

### Pour la documentation
- **Exemples vivants** : Code qui fonctionne avec vraies données
- **Référence complète** : Toutes les méthodes illustrées
- **Validation** : Preuve de conformité réglementaire
- **Formation** : Support pour apprendre l'API

### Pour les tests
- **Validation fonctionnelle** : Chaque méthode testée
- **Tests d'intégration** : API + classes + méthodes
- **Tests de régression** : Vérifier les mises à jour
- **Tests de conformité** : Respect des spécifications

---

## 🚀 Extensions possibles

### Nouvelles fonctionnalités
- **Comparaison multi-dates** : Évolution dans le temps
- **Analyse géographique** : Comparaison multi-zones
- **Export des résultats** : Sauvegarde des démonstrations
- **Mode interactif** : Choix de la zone/date par l'utilisateur

### Optimisations
- **Cache des données** : Éviter les appels répétés
- **Mode offline** : Utilisation de données pré-enregistrées
- **Parallélisation** : Récupération simultanée des données
- **Configuration** : Paramètres externalisés

---

## 📞 Support

### En cas de problème
1. **Vérifier** le fichier `credentials.json`
2. **Tester** la connexion API manuellement
3. **Contrôler** la disponibilité des données (weekend/jours fériés)
4. **Consulter** les logs d'erreurs détaillés

### Maintenance
- **Mise à jour** selon les évolutions de l'API
- **Adaptation** aux nouvelles spécifications réglementaires
- **Extension** pour de nouveaux types de données
- **Optimisation** des performances selon l'usage

---

## 📈 Script 3 : `demo_emission_functions.py`

### Description générale
Script de démonstration complet pour la classe `EmissionData`, illustrant toutes les fonctionnalités liées aux données d'émissions atmosphériques.

### Configuration
- **Zones testées** : Principales métropoles françaises (Nancy, Strasbourg, Metz, Paris, Lyon, Marseille, etc.)
- **Source de données** : Données simulées basées sur des valeurs réalistes
- **Type** : Émissions par polluant et par secteur d'activité
- **Format** : GeoJSON avec coordonnées géographiques

### Sections démonstrées

#### 1. Propriétés de base (héritées d'AtmoDataBase)
```python
# Informations générales
emission.code             # Code zone (INSEE)
emission.name             # Nom de la zone
emission.aasqa            # Code AASQA
emission.source           # Nom de l'organisme
emission.date_maj         # Date de mise à jour

# Données démographiques
emission.population       # Nombre d'habitants
emission.superficie       # Superficie en km²

# Coordonnées géographiques
emission.has_coordinates()     # Disponibilité coordonnées
emission.coordinates           # Objet Coordinates
```

#### 2. Propriétés spécifiques émissions
```python
# Émissions par polluant (tonnes/an)
emission.nox              # Oxydes d'azote
emission.pm10             # Particules PM10
emission.pm25             # Particules PM2.5
emission.ges              # Gaz à effet de serre (CO2 eq.)

# Secteur d'activité
emission.code_pcaet       # Code secteur PCAET
```

#### 3. Méthodes helper essentielles
```python
# Calculs de densité
emission.get_emission_density('nox')      # → 8.36 tonnes/km²
emission.get_emission_density('pm10')     # → 2.85 tonnes/km²

# Calculs par habitant
emission.get_emission_per_capita('nox')   # → 0.001197 t/hab/an
emission.get_emission_per_capita('ges')   # → 0.008108 t/hab/an

# Données globales
emission.get_total_emissions()            # → Dict complet
emission.get_secteur_name()               # → "Transport routier"
```

#### 4. Fonctions centralisées (base)
```python
# Émojis et couleurs (niveau fictif pour visualisation)
emission.get_emoji_by_level(3, "round")    # → "🟡"
emission.get_color_by_level(3)             # → ("#F0E641", (240, 230, 65))
```

### Exemple de sortie
```
Zone: Nancy
Population: 104,885 habitants
Superficie: 15.01 km²

Émissions totales:
  - NOx: 125.5 tonnes/an
  - PM10: 45.2 tonnes/an
  - PM2.5: 28.7 tonnes/an
  - GES: 850.3 tonnes/an

Densités d'émission par km²:
  - NOx: 8.36 tonnes/km²
  - PM10: 3.01 tonnes/km²

Émissions par habitant:
  - NOx: 1.20 kg/hab/an
  - GES: 8.11 kg/hab/an
```

### Usage
```bash
python demo_emission_functions.py
```

---

## 🚨 Script 4 : `demo_episode_functions.py`

### Description générale
Script de démonstration complet pour la classe `EpisodePollution`, illustrant toutes les fonctionnalités liées aux épisodes de pollution.

### Configuration
- **Zones testées** : Principales agglomérations françaises
- **Types d'épisodes** : Information, Recommandation, Alerte
- **Polluants** : NO2, SO2, O3, PM10, PM2.5
- **Format** : GeoJSON avec géométries variées (Point, MultiPolygon)

### Sections démonstrées

#### 1. Propriétés de base (héritées d'AtmoDataBase)
```python
# Informations générales
episode.aasqa             # Code AASQA
episode.lib_zone          # Zone affectée
episode.source            # Nom de l'organisme
episode.date_maj          # Date de mise à jour

# Informations temporelles
episode.date_dif          # Date de diffusion
episode.date_ech          # Date d'échéance

# Géométrie
episode.geometry          # Géométrie GeoJSON
episode.has_coordinates() # Coordonnées disponibles
```

#### 2. Propriétés spécifiques épisodes
```python
# Polluant concerné
episode.code_pol          # Code polluant (1-6)
episode.lib_pol           # Nom polluant
episode.code_zone         # Code de la zone
episode.etat              # État de l'épisode

# États typiques:
# "PAS DE DEPASSEMENT"
# "PROCEDURE D'INFORMATION"
# "PROCEDURE D'INFORMATION ET DE RECOMMANDATION"
# "PROCEDURE D'ALERTE"
# "ALERTE NIVEAU 1"
```

#### 3. Méthodes helper spécialisées
```python
# Analyse des alertes
episode.is_alert_active()         # → True/False
episode.get_alert_level()         # → "Information"/"Alerte"/"Aucune"

# Analyse des polluants
episode.get_polluant_code()       # → "PM10" (normalisé)

# Analyse géométrique
episode.is_geometry_complex()     # → True si MultiPolygon
```

#### 4. Mapping des codes polluants
```python
# Codes API → Codes normalisés
'1' → 'NO2'      # Dioxyde d'azote
'2' → 'SO2'      # Dioxyde de soufre
'3' → 'O3'       # Ozone
'5' → 'PM10'     # Particules PM10
'6' → 'PM2.5'    # Particules PM2.5
```

### Exemple de sortie
```
Zone affectée: Agglomération de Nancy
Polluant: PM10 (Code: 5)
Code polluant normalisé: PM10
État: PROCEDURE D'INFORMATION ET DE RECOMMANDATION
Alerte active: ✓
Niveau d'alerte: Information
Géométrie complexe: ✓

Comparaison des épisodes:
Zone            Polluant Niveau       Alerte   État
Paris           PM10     Information  ✓        PROCEDURE D'INFORMATION
Lyon            O3       Alerte       ✓        PROCEDURE D'ALERTE
Marseille       PM2.5    Alerte       ✓        ALERTE NIVEAU 1
Strasbourg      NO2      Aucune       ✗        PAS DE DEPASSEMENT
```

### Usage
```bash
python demo_episode_functions.py
```

---

## 🔧 Fonctionnalités communes (scripts 3-4)

### Gestion des données manquantes
Les deux nouveaux scripts démontrent la robustesse face aux cas particuliers :

```python
# Cas gérés automatiquement
- Population = 0     → émission par habitant = 0
- Superficie = 0     → densité = 0
- État vide         → alerte = False
- Code inconnu      → valeur par défaut
- Géométrie None    → coordonnées = None
```

### Calculs avancés
```python
# EmissionData
emission.get_emission_density('nox')      # Densité spatiale
emission.get_emission_per_capita('ges')   # Impact par habitant
emission.get_total_emissions()            # Vue d'ensemble

# EpisodePollution  
episode.is_alert_active()                 # Détection automatique
episode.get_alert_level()                 # Classification
episode.is_geometry_complex()             # Type de zone
```

### Analyses comparatives
```python
# Comparaison inter-zones (EmissionData)
for emission in emissions:
    nox_per_cap = emission.get_emission_per_capita('nox') * 1000
    print(f"{emission.name}: {nox_per_cap:.1f} kg/hab/an")

# Analyse d'alertes (EpisodePollution)
alertes_actives = sum(1 for ep in episodes if ep.is_alert_active())
print(f"Alertes actives: {alertes_actives}/{len(episodes)}")
```

---

## 📋 Informations techniques mises à jour

### Couverture complète du datamodel
Les 4 scripts couvrent désormais **toutes les classes** du datamodel :
- ✅ **IndiceAtmo** : Qualité de l'air (script 1)
- ✅ **IndicePollen** : Indices pollen (script 2)  
- ✅ **EmissionData** : Données d'émissions (script 3)
- ✅ **EpisodePollution** : Épisodes de pollution (script 4)

### Méthodes testées (au total)
**Classes spécialisées** : 25+ méthodes spécifiques  
**Classe de base** : 8 méthodes héritées  
**Propriétés** : 50+ propriétés documentées  
**Cas particuliers** : 15+ scénarios de robustesse  

### Types de données
- **Indices temps réel** : Qualité air + Pollen
- **Données statistiques** : Émissions par secteur
- **Alertes dynamiques** : Épisodes de pollution
- **Géométries** : Point, MultiPolygon, coordonnées

### Performance globale
- **Temps d'exécution** : 3-5 secondes par script
- **Données traitées** : 1-1500 objets selon le type
- **Mémoire** : 10-50 MB selon le volume
- **Robustesse** : Gestion complète des erreurs

---

## 💡 Cas d'usage étendus

### Analyse environnementale complète
```python
# Workflow complet avec les 4 classes
indices = get_indices_atmo(region="idf")      # Qualité air actuelle
pollens = get_indices_pollen(ville="nancy")   # Allergènes
emissions = get_emissions(zone="metropole")   # Sources pollution
episodes = get_episodes(region="nationale")   # Alertes actives

# Analyse croisée
if any(ep.is_alert_active() for ep in episodes):
    # Corréler avec indices et émissions
    responsible_sources = analyze_emission_sources(emissions)
    current_quality = analyze_air_quality(indices)
```

### Surveillance réglementaire
```python
# Conformité notice officielle (tous scripts)
- Respect codes couleur officiels
- Validation structure données API  
- Gestion coordonnées réglementaires
- Calculs selon arrêté du 10 juillet 2020
```

### Applications métier
- **Collectivités** : Surveillance qualité air + Alertes
- **Santé publique** : Pollens + Épisodes + Indices
- **Industrie** : Émissions + Conformité réglementaire  
- **Recherche** : Données complètes + Analyses croisées

---

*Documentation complète pour les 4 scripts de démonstration du wrapper API Atmo Data*  
*Conforme à la notice officielle du 1er avril 2025*