Français | English

Traitement, analyse et modélisation des données agricoles et économiques

KadiPy : le "pandas" de l'agriculture africaine

KadiPy est une bibliothèque Python open source conçue pour les agronomes, chercheurs et développeurs travaillant sur l'agriculture au Bénin et en Afrique de l'Ouest. Elle offre une interface unifiée pour ingérer, nettoyer, analyser et modéliser des données météorologiques, des prix de marchés agricoles, des coûts logistiques et des séries de récoltes, avec un fonctionnement conçu en priorité pour le mode hors ligne (offline-first).

Fonctionnalités principales

• Ingestion et E/S unifiées (kadi.io) : fonctions expressives read_csv, read_excel, read_json, read_netcdf, read_api avec détection automatique du format, et leurs équivalents en écriture (write_csv, write_excel, etc.). Les fonctions write, info et ping fonctionnent avec n'importe quel format.

• Météorologie agronomique (kadi.weather) : façade Weather pour les données météo historiques et prévisionnelles (CHIRPS + Open-Meteo), détection des saisons des pluies (Sivakumar, Walter-Anyadike), bilan hydrique des sols (FAO-56), évapotranspiration (ET0 Hargreaves-Samani) et indices de sécheresse (SPI, Markov, Hurst).

• Économie agricole et marchés (kadi.market) : façade Market pour le suivi des prix réels (WFP/HAPI HumData), prévisions de prix (Forecasting), calculs de coûts logistiques routiers (Logistics) et aide à la décision (Advisor) pour l'arbitrage spatial et le stockage stratégique.

• Pipeline et standardisation (kadi.kidas) : nettoyage des données brutes (Cleaner), validation de schémas (Validator), normalisation des noms de cultures et coordonnées GPS (Normalizer), persistance SQLite locale (Cache) et chaîne de traitement complète (Pipeline).

Installation

Via PyPI

pip install kadipy

Depuis les sources

git clone https://github.com/delsDin/kadipy.git
cd kadipy
pip install -e ".[dev]"

Dépendances optionnelles

# Support des anciens fichiers Excel (.xls, antérieurs à 2003)
pip install "kadipy[xls]"

# Traitements géospatiaux (découpage de rasters CHIRPS)
pip install "kadipy[geospatial]"

Configuration de l'environnement

Créez un fichier .env à la racine du projet pour activer les sources de données réelles :

# Clé API WFP DataBridges (facultatif : des données publiques HAPI HumData
# sont utilisées sans elle)
WFP_API_Token=votre_cle_ici

# Prix du carburant manuel en XOF/litre (facultatif)
BENIN_FUEL_PRICE=680

Vue d'ensemble des modules

Structure du projet

kadipy/
├── kadi/
│   ├── io/              # Entrées et sorties unifiées
│   ├── market/          # Économie agricole et marchés
│   ├── weather/         # Météorologie agronomique
│   ├── kidas/           # Pipeline de traitement et standardisation
│   ├── _sources/        # Clients externes (WFP, CHIRPS, SoilGrids)
│   ├── cache.py         # Cache SQLite partagé
│   ├── config.py        # Configuration centralisée
│   └── exceptions.py    # Exceptions personnalisées
├── tests/               # Suite de tests (pytest)
├── docs/                # Documentation MkDocs
├── examples/            # Notebooks d'exemples Jupyter
├── config/              # Fichiers de configuration
└── pyproject.toml       # Dépendances et métadonnées du package

Lancer les tests

# Exécution simple
pytest tests/ -q

# Avec rapport de couverture de code
pytest tests/ --cov=kadi --cov-report=term-missing

Les tests couvrent l'ensemble des modules (io, market, weather, kidas), y compris les connecteurs distants sans dépendance réseau et les composants d'infrastructure (kadi.cache, kadi.config). Aucune clé API n'est nécessaire pour les exécuter. La CI GitHub Actions contrôle que la couverture globale reste supérieure à 70 %.

Rétrocompatibilité

Les anciens noms de classes issus des versions antérieures à v1.2.0 émettent un DeprecationWarning et seront supprimés dans KadiPy v2.0 :

Zone géographique (v1.x)

KadiPy v1.x est conçu exclusivement pour le Bénin. La validation des coordonnées GPS, les algorithmes phénologiques, les facteurs logistiques et les données de prix sont calibrés pour le contexte béninois.

Le support d'autres pays d'Afrique de l'Ouest est prévu dans les versions futures.

Documentation

La documentation complète (guides d'API, exemples) est disponible sur : https://delsDin.github.io/kadipy/

Licence et contribution

• Licence : MIT
• Dépôt GitHub : https://github.com/delsDin/kadipy
• Compatibilité Python : >= 3.9
• Version courante : 1.2.0