20 KiB
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)
# 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
# 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
# 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)
# É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
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)
# 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
# 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
# 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
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
python demo_pollen_functions.py
🔧 Fonctionnalités communes
Système d'émojis unifié
Les deux scripts démontrent le système d'émojis centralisé :
# 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
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
- Connexion et récupération des données
- Propriétés de base (héritées)
- Propriétés spécifiques (ATMO/Pollen)
- Méthodes helper (une par une)
- Exemples pratiques d'utilisation
- 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
- Vérifier le fichier
credentials.json
- Tester la connexion API manuellement
- Contrôler la disponibilité des données (weekend/jours fériés)
- 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)
# 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
# É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
# 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)
# É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
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)
# 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
# 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
# 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
# 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
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 :
# 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
# 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
# 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
# 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
# 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