Pipeline EBV

Le pipeline EBV est le moteur d'evaluation genetique de BeePass. Son objectif : transformer les observations de terrain (kilos de miel, scores de douceur, resultats de tests hygieniques) en valeurs genetiques comparables entre eleveurs, entre regions et entre annees.

Pourquoi est-ce necessaire ? Parce qu'une reine qui produit 40 kg de miel dans un rucher de montagne n'est pas necessairement moins bonne genetiquement qu'une reine qui en produit 60 kg en plaine. L'environnement (altitude, meteo, pression florale) explique une grande partie des differences observees. Le pipeline retire statistiquement ces effets environnementaux pour ne garder que la composante genetique -- la valeur intrinseque de la reine, independamment de l'endroit ou elle se trouve.

Le pipeline execute une chaine de calcul en 8 etapes transformant les donnees brutes de terrain en valeurs genetiques normalisees (les EBV, pour Estimated Breeding Values), comparables entre eleveurs et entre annees.

Statut des modules

• Module H (Moteur EBV) : 90% -- pipeline ONE SHOT complet, 5 traits evalues, UI admin + affichage EBV. Reste : integration 3 traits comportementaux.
• Module G (Environnement) : 70% -- env_compute worker operationnel, geocodage + altitude + meteo. Reste : enrichissement features supplementaires.
• Module L (AINV-honeybees) : 90% -- package TypeScript v20, 56 tests, mapping SDI/MDI, phantom dams. Reste : integration AINV.giv dans BLUPF90+ (AINV-03).

L'evaluation genetique chez l'abeille mellifere (Apis mellifera) presente des defis specifiques qui la distinguent de l'evaluation bovine ou porcine classique : systeme haplo-diploide (les males n'ont qu'un seul jeu de chromosomes), polyandrie (la reine est fecondee par 10 a 20 drones), double effet genetique (la performance de la colonie depend a la fois de la reine et de ses ouvrieres) et environnement heterogene. Le pipeline s'appuie sur les travaux de Brascamp & Bijma (2014), le systeme BeeBreed (Bienefeld et al.) et la suite logicielle BLUPF90 (Misztal et al., 2002).

Architecture ONE SHOT

Le pipeline suit le principe ONE SHOT : les 8 etapes s'enchainent sequentiellement, comme une chaine de montage ou chaque poste depend du precedent. Un verrou consultatif PostgreSQL (advisory xact lock 45) empeche toute execution concurrente -- on ne peut pas lancer deux evaluations en parallele, ce qui garantit la coherence des resultats. En cas d'echec a n'importe quelle etape, les resultats partiels sont annules par transaction atomique.

Etape 1 -- SNAPSHOT GUARD
|   pg_dump des tables EBV-relevant -> SHA256
|   Point de reference immutable
|
Etape 2 -- ENV COMPUTE
|   Geocodage (code postal -> lat/lon)
|   Altitude (Google Elevation)
|   Meteo saisonniere (200 jours, 15/03 -> 30/09)
|
Etape 3 -- XGB TRAIN
|   Entrainement XGBRegressor sur log1p(honey_kg)
|   Features : [altitude, pluie, temperature, jours chauds]
|   -> Modele .ubj versionne et signe SHA256
|
Etape 4 -- XGB APPLY
|   Prediction effet environnemental par evaluation
|   y_corr = log1p(honey_kg) - f_env(X)
|
Etape 5 -- BLUPF90+ (HONEY)
|   Modele animal mixte : CG(fixe) + reine(aleatoire, A)
|   REML integre (OPTION method VCE)
|   -> EBV bruts trait HONEY + fiabilite r2
|
Etape 6A - THRGIBBS ORD (VIGOR, WINTERING)
|   Modele a seuil (probit, 4 categories)
|   Gibbs sampler, SANS poids (Weight = 0)
|
Etape 6B - THRGIBBS HYG (HYG6, HYG24)
|   Modele continu pondere par time_quality
|   Poids : exact=1.0, declared=0.5, unknown=exclu
|
Etape 7 -- NORMALISATION
|   BeeBreed-like : EBV_norm = 100 + 10 x (EBV_brut - u) / s
|   Base de reference : reines des 5 dernieres annees
|
Etape 8 -- STORE
|   staging persistee -> promote atomique -> ebv_results

Proprietes du pipeline

Ces proprietes garantissent que le pipeline est fiable et auditable :

Propriete	Description
Idempotent	Memes donnees + meme seed + memes versions = memes sorties (tolerance Gibbs inferieure a 1e-6). Autrement dit, relancer le pipeline sur les memes donnees produira toujours le meme resultat
Atomique	Ecriture dans ebv_results_staging (persistee, isolee par run_id), puis promotion transactionnelle. Si une etape echoue, rien n'est publie
Tracable	Logs structures + artefacts hashes (SHA256) + metriques Prometheus. Chaque run peut etre audite completement
Singleton	pg_try_advisory_xact_lock(45) -- un seul run a la fois, pour eviter les resultats incoherents
Reproductible	OMP_NUM_THREADS=1 + OPENBLAS_NUM_THREADS=1 (force les calculs mathematiques a utiliser un seul thread, ce qui elimine les variations liees au parallelisme)

Traits evalues

Le formulaire d'evaluation collecte 8 traits au niveau de la colonie. Parmi ceux-ci, 5 sont actuellement evalues genetiquement par le pipeline. Les 3 restants sont collectes mais en attente d'integration.

Traits evalues (5)

Trait	Code	Type	Echelle	Moteur	Etape
Production de miel	HONEY	Continu	kg (echelle log)	BLUPF90+	5
Vigueur printaniere	VIGOR	Ordinal	1-4	THRGIBBS1F90	6A
Hivernage	WINTERING	Ordinal	1-4	THRGIBBS1F90	6A
Comportement hygienique 6h	HYG6	Continu pondere	k/50 cellules	THRGIBBS1F90	6B
Comportement hygienique 24h	HYG24	Continu pondere	k/50 cellules	THRGIBBS1F90	6B

Traits collectes, non encore evalues (3)

Trait	Code	Type	Echelle	Methode prevue
Douceur	GENTLENESS	Ordinal	1-4	THRGIBBS1F90 (6A)
Tenue de cadre	COMB_SITTING	Ordinal	1-4	THRGIBBS1F90 (6A)
Non-essaimage	SWARMING	Ordinal	1-4	THRGIBBS1F90 (6A)

Ces 3 traits comportementaux seront integres dans le run 6A. Les donnees sont deja collectees.

Etape 1 -- Snapshot Guard

Avant de lancer quoi que ce soit, le pipeline cree une photographie de la base de donnees a l'instant T. Pourquoi ? Pour garantir qu'on sait exactement sur quelles donnees l'evaluation a ete faite. Si quelqu'un modifie une reine pendant le calcul, le snapshot permet de prouver quelles donnees ont ete utilisees.

Element	Description
Methode	pg_dump --format=custom des tables EBV-relevant
Verification	SHA256 du fichier dump (empreinte numerique unique)
Stockage	Table snapshots_registry (trigger, file_sha256, size_bytes)
Politique	Si snapshot_policy = required et snapshot echoue, le run passe en failed

Retention : 5 derniers snapshots conserves, snapshots > 30 jours supprimes. Snapshot pre-run conserve tant que le run existe.

Securite pg_dump

Le mot de passe DB est passe via la variable d'environnement PGPASSWORD (jamais en argument CLI) pour eviter toute exposition dans /proc/{pid}/cmdline -- un fichier systeme lisible par d'autres processus sur le serveur.

Etape 2 -- Environnement (env_compute)

Cette etape enrichit chaque site d'evaluation avec des donnees environnementales. L'idee est de quantifier les conditions dans lesquelles chaque colonie a ete evaluee, pour pouvoir ensuite retirer l'effet de l'environnement dans les etapes suivantes.

Concretement, une evaluation faite en montagne sous la pluie et une evaluation faite en plaine avec du soleil ne sont pas comparables directement. Cette etape collecte les donnees qui permettront la comparaison.

Geocodage (Phase 1)

Transforme un couple (code_postal, pays) en coordonnees GPS, car les API meteo ont besoin de coordonnees, pas de codes postaux :

Priorite	Fournisseur	Endpoint	Fallback
1	OpenWeather	geo/1.0/zip	--
2	Google Maps	geocode/json (component filtering)	Si OpenWeather echoue

Resilience : retry backoff exponentiel (en cas d'erreur 429 ou 5xx, le systeme reessaie avec des delais croissants), circuit-breaker 5 min par couple (fournisseur, code_postal, pays). Groupage par triplet (CP normalise, pays, annee) -- un seul appel API par groupe, meme si plusieurs evaluations partagent le meme site.

Altitude (Phase 2)

L'altitude influence la saison apicole (floraisons plus tardives, temperatures plus basses). Elle est recuperee separement car les API de geocodage ne la fournissent pas toujours.

Source	Endpoint	Precision	Tolerance
Google Elevation API	elevation/json	6 decimales lat/lon, 2 decimales altitude	NULL si echec (non bloquant)

Meteo saisonniere (Phase 3)

Collecte sur une fenetre fixe de 200 jours (15 mars -> 30 septembre UTC) qui correspond a la saison apicole en Europe. Cette periode couvre le developpement printanier, la miellée principale et la fin de saison.

Variable	Formule	Unite
rain_sum_mm	Somme precipitations sur 200 jours	mm
temp_mean_c	Moyenne T_afternoon (fallback T_min+T_max/2)	Celsius
hot_days_count	Jours ou T_max >= 30 degres	jours

Source : OpenWeather day_summary API (One Call 3.0), 200 requetes par emplacement/annee.

Fingerprints

Chaque resultat environnemental est identifie par un fingerprint SHA256 canonique : lat/lon %.6f, alt %.2f. Les fingerprints garantissent la reproductibilite (memes coordonnees = meme empreinte) et la deduplication (pas d'appels API redondants).

Politique de cache (env_policy)

Pour des raisons de cout (les API meteo sont payantes) et de reproductibilite, le pipeline peut utiliser un cache des resultats environnementaux :

Politique	Description
require_cache	Cache manquant -> run fail (reproductibilite bit-a-bit garantie)
allow_live	Appels API autorises, cache utilise si present
refresh_cache	Force un nouvel appel API meme si cache existe

Etape 3 -- XGBoost Train

Pourquoi utiliser un modele de machine learning ici ? Parce que la relation entre l'environnement et la production de miel est complexe et non-lineaire. Par exemple, un peu de pluie est benefique (fleurs), mais trop de pluie est nuisible (les abeilles ne sortent pas). XGBoost capture ces interactions mieux qu'un simple modele lineaire.

Le modele XGBoost effectue une correction environnementale sur la production de miel.

Features d'entree

X_env = [alt_m, rain_sum_mm, temp_mean_c, hot_days_count]

Pas de location_year_encoded

La variable location_year_encoded est exclue des features XGBoost pour eviter une double correction avec le groupe contemporain g(c) dans BLUP/THRGIBBS. En d'autres termes, on ne corrige pas deux fois la meme chose.

Parametres

Parametre	Valeur	Description
Modele	XGBRegressor	Regression sur log1p(honey_kg) (transformation logarithmique pour normaliser la distribution)
Format	.ubj (natif XGBoost)	Pas de pickle (elimine le risque RCE -- un format binaire Python qui pourrait executer du code malveillant)
Split	Temporel (anti-fuite)	Les donnees passees entrainent le modele, les donnees recentes le testent -- pas de split aleatoire qui risquerait une fuite d'information
Threading	nthread=1	Reproductibilite bit-a-bit (le parallelisme introduit des variations)
Verification	SHA256 du fichier modele	Verifie avant chaque chargement
Donnees minimales	>= 100 observations	Seuil d'entrainement -- en dessous, le modele n'est pas fiable

Les hyperparametres, seed, version XGBoost, SHA256 du modele et des donnees sont stockes dans la table xgb_models.

Indicateur de qualite (xgb_quality)

Un flag xgb_quality est calcule pour chaque run. Si le RMSE (Root Mean Square Error, une mesure d'erreur de prediction) depasse le seuil versionne ou si le modele ne bat pas un baseline simple (moyenne par annee), le run est marque avec un avertissement de qualite.

Etape 4 -- XGBoost Apply

Une fois le modele entraine, il est applique a chaque evaluation pour retirer l'effet environnemental predit :

y_corr = log1p(honey_kg) - pred_env

Le resultat y_corr (la production de miel "corrigee" de l'environnement) est stocke dans queen_evaluations.y_corr_honey. La valeur honey_kg = 0 est traitee comme valide (pas missing) -- une colonie qui n'a pas produit de miel est une information pertinente.

Etape 5 -- BLUPF90+ (trait continu : miel)

L'etape BLUP est le coeur de l'evaluation genetique. Le BLUP (Best Linear Unbiased Prediction) fonctionne comme une moyenne ponderee sophistiquee qui tient compte simultanement de l'arbre genealogique, des performances des apparentees et de l'environnement. Une reine sans descendance evaluee peut quand meme recevoir un EBV si sa mere ou ses soeurs ont ete evaluees.

Elle utilise BLUPF90+ (UGA 2026) pour estimer les valeurs genetiques sur le trait continu (production de miel corrigee).

Modele animal mixte

y_corr = u + delta_{g(c)} + a_Q(q(c)) + e

Composante	Description
u	Moyenne generale (la production moyenne de toutes les reines)
delta_{g(c)}	Effet fixe du groupe contemporain (location_key x season_year) -- regroupe les colonies evaluees au meme endroit la meme annee
a_Q(q(c))	Effet aleatoire genetique de la reine (lie a la matrice A^-1, qui encode les liens de parente entre toutes les reines)
e	Residuelle (ce qui n'est explique ni par la genetique ni par l'environnement)

Le groupe contemporain est defini par g(c) = location_key(c) + season_year(c). L'environnement est deja retire par XGBoost -- delta_{g(c)} normalise les localisations residuelles (differences d'environnement que XGBoost n'a pas capturees).

REML integre

BLUPF90+ estime les composantes de variance (quelle proportion de la variation totale est due a la genetique vs l'environnement) via OPTION method VCE (REML integre). Plus besoin d'un programme AIREML90 separe.

Matrice A^-1

La matrice inverse des relations genetiques additives est le "carnet de famille" mathematique du pipeline. Elle quantifie la proximite genetique entre chaque paire de reines. Plus deux reines sont apparentees, plus l'information de l'une aide a estimer la valeur genetique de l'autre.

Elle est calculee par le package ainv-honeybees v20 (packages/ainv-honeybees/, TypeScript + R, 56 tests). Elle integre le modele haplo-diploide de Brascamp & Bijma (2014) avec :

• Mapping strict 18 colonnes du format pedigree v20 (DOI: 10.5281/zenodo.7951334)
• Groupes de peres (sire-groups) pour SDI et MDI
• Phantom dams automatiques (AINV-01/02 implementes)
• Politique parents inconnus versionnee (founder fallback)
• Fingerprint : ainv_sha256 = SHA256(pedigree_sorted_csv + resolver_version + config)

AINV-03 (TODO)

L'integration du fichier AINV.giv genere par ainv-honeybees dans le pipeline BLUPF90+ n'est pas encore implementee. Actuellement, BLUPF90+ utilise le pedigree standard (renadd01.ped). L'etape AINV-03 remplacera ce fichier par la matrice A^-1 pre-calculee, ce qui ameliorera la precision pour les cas SDI et les pedigrees complexes.

Fichiers generes

Fichier	Description
renf90.par	Parametres modele (Value of Missing Trait = -999)
renf90.dat	Phenotypes (mapping colonnes versionne)
renadd01.ped	Pedigree BLUPF90 (tri topologique -- les parents apparaissent avant les enfants)
solutions	EBV bruts (reine + worker)

Etape 6A -- THRGIBBS ORD (traits ordinaux)

Les traits comme la vigueur ou l'hivernage sont notes sur une echelle de 1 a 4. Ce ne sont pas des mesures continues comme les kilos de miel -- un "3" n'est pas mathematiquement 3 fois un "1". Le modele a seuil (threshold model) gere cette particularite en postulant une variable latente continue sous-jacente, et en definissant des seuils qui determinent dans quelle categorie tombe l'observation.

Le programme THRGIBBS1F90 (Gibbs sampler, un algorithme qui explore iterativement l'espace des solutions possibles pour converger vers la meilleure estimation) traite les traits ordinaux a 4 categories par un modele a seuil probit.

Traits traites

Trait	Code	Categories	Direction
Vigueur printaniere	VIGOR	1 (faible) -> 4 (forte)	Plus = mieux
Hivernage	WINTERING	1 (mauvais) -> 4 (excellent)	Plus = mieux

Modele liability

l = u + delta_{g(c)} + beta_alt x alt + beta_met x Met + a_W + a_Q + e

Observation : y = k si tau_{k-1} < l <= tau_k (la categorie observee depend de la position de la variable latente par rapport aux seuils tau).

Parametrage

Parametre	Valeur
Position of Weight(s)	0 (pas de poids)
Value of Missing Trait	-999
Covariables	delta_{g(c)} + alt_m + meteo saison (beta fixes)
Identifiabilite	sigma_e = 1 (probit, convention standard)
Threading	OMP_NUM_THREADS=1

Parametres Gibbs sampler

Le Gibbs sampler genere des milliers d'echantillons pour explorer la distribution des parametres. Les echantillons initiaux (burn-in) sont jetes car ils ne sont pas representatifs -- l'algorithme a besoin de temps pour "se stabiliser".

Parametre	Valeur
Total iterations	50 000
Burn-in	10 000 (iterations initiales ignorees)
Thin	10 (on ne garde qu'un echantillon sur 10 pour reduire la correlation entre echantillons successifs)
Seed	Obligatoire, stockee dans genetic_runs.seed

Etape 6B -- THRGIBBS HYG (traits hygieniques)

Les traits hygieniques mesurent la capacite des abeilles a detecter et nettoyer les cellules malades -- un trait fondamental pour la resistance aux maladies. La particularite de ces traits est que la fiabilite de la mesure varie selon les conditions du test. Un test chronometrre precisement (timing "exact") est plus informatif qu'un test dont l'heure n'est qu'approximative ("declared").

Les traits hygieniques utilisent le meme Gibbs sampler mais avec ponderation par la qualite temporelle de la mesure.

Traits traites

Trait	Code	Donnee	Direction
Hygienique 6h	HYG6	Cellules nettoyees / 50 (Pin Test)	Plus = mieux
Hygienique 24h	HYG24	Cellules nettoyees / 50 (Pin Test)	Plus = mieux

Protocole Pin Test

Le test hygienique Pin Test est un protocole standardise pour mesurer le comportement hygienique d'une colonie :

1. Perforer 50 cellules de couvain operculees (perforation_at)
2. Lire a 6h le nombre de cellules nettoyees (read6_at, hyg6_cleaned) -- une colonie tres hygienique aura deja nettoye la majorite des cellules
3. Lire a 24h le nombre de cellules nettoyees (read24_at, hyg24_cleaned) -- pratiquement toutes les colonies ont nettoye a 24h, donc la lecture 6h est plus discriminante

La qualite temporelle (time_quality) de chaque lecture determine son poids dans le modele :

time_quality	Variance omega	Poids hyg_weight_w	Effet
exact	1.0	1.0	Plein poids -- le timing a ete mesure avec precision
declared	lambda > 1	1/lambda	Poids reduit -- le timing est approximatif
unknown	--	Exclu	Import-only, exclu du dataset -- on ne sait pas quand la lecture a ete faite

Split 6A/6B obligatoire

Pourquoi separer les traits ordinaux (6A) et hygieniques (6B) au lieu de les traiter ensemble ? C'est une limitation technique du logiciel THRGIBBS1F90 : le parametre WEIGHT(S) ne fournit qu'une seule colonne de poids par ligne. Si les traits ordinaux et hygieniques etaient traites ensemble, le poids s'appliquerait aussi aux traits ordinaux (ce qui est incorrect -- les notes de 1 a 4 n'ont pas de "qualite de mesure" variable).

Limitation v8.1

Le split 6A/6B implique que le moteur n'estime pas de covariances genetiques entre les traits ordinaux (2 a 6) et les traits hygieniques (7 et 8). Concretement, cela signifie qu'on ne mesure pas si les reines genetiquement bonnes en vigueur sont aussi genetiquement bonnes en comportement hygienique.

Format 2 lignes par evaluation

Pour gerer des time_quality differents entre HYG6 et HYG24 (un eleveur peut avoir chronometre precisement la lecture 6h mais pas la lecture 24h), chaque evaluation produit 2 lignes dans evaluations_hyg.dat :

Ligne	hyg6_r	hyg24_r	hyg_weight_w	Effet
Ligne HYG6	k6	-999	f(time_quality_hyg6)	Seul HYG6 contribue
Ligne HYG24	-999	k24	f(time_quality_hyg24)	Seul HYG24 contribue

Un fichier sidecar evaluations_hyg_rows.csv trace la correspondance (row_idx, evaluation_id, hyg_row_kind) pour audit.

Etape 7 -- Normalisation BeeBreed-like

Les EBV bruts sortis de BLUPF90+ et THRGIBBS sont des nombres sans echelle intuitive. Pour qu'un eleveur puisse comprendre immediatement si sa reine est "bonne" ou "exceptionnelle", les EBV sont convertis en scores BeeBreed-like centres sur 100.

Le principe est simple : la reine "moyenne" de la population recente obtient 100. Chaque tranche de 10 points represente un ecart-type. C'est le meme systeme que le QI (centre sur 100, ecart-type 15) mais adapte a la genetique apicole.

Formule

EBV_normalise = 100 + 10 x (EBV_brut - moyenne) / ecart_type

Parametre	Valeur
Moyenne de reference (mu)	Calculee sur les reines des 5 dernieres annees (base de reference glissante)
Ecart-type (sigma)	Calculee sur la meme population de reference
Echelle	Centre = 100, ecart-type = 10

Interpretation

Score	Signification
130	Exceptionnelle (+3 sigma -- top 0.1% de la population)
120	Tres bonne (+2 sigma -- top 2.5%)
115	Bonne (+1.5 sigma -- top 7%)
110	Au-dessus de la moyenne (+1 sigma -- top 16%)
100	Moyenne de la population
90	En-dessous de la moyenne (-1 sigma)
80	Faible (-2 sigma)

Les scores sont calcules pour chaque trait independamment. Une reine peut etre "120" en miel et "95" en douceur -- les traits ne sont pas correles de la meme facon.

La fiabilite r2 (reliability) indique la precision de l'estimation -- une reine avec plus de filles evaluees aura un r2 plus eleve. Un r2 de 0.9 signifie qu'on est tres confiant dans l'EBV, un r2 de 0.3 signifie que l'estimation est encore imprecise et pourrait evoluer avec plus de donnees.

Fiabilite (r2) BeeBreed-like

La fiabilite est calculee selon la methodologie BeeBreed (Sicherheit). Elle depend du nombre de descendantes evaluees, de la qualite du pedigree et de l'heritabilite du trait. C'est un indicateur essentiel pour les eleveurs : un EBV de 120 avec un r2 de 0.9 est beaucoup plus fiable qu'un EBV de 120 avec un r2 de 0.3.

Etape 8 -- Store (promotion atomique)

Pourquoi ne pas ecrire directement dans la table finale ? Parce qu'un run peut echouer en cours de route (bug, timeout, donnees invalides). En utilisant une table staging intermediaire, on s'assure que les utilisateurs ne voient jamais des resultats partiels ou incoherents.

Les resultats sont stockes dans une table staging persistee (ebv_results_staging) isolee par run_id, puis promus atomiquement vers ebv_results :

1. Ecriture dans ebv_results_staging (isolee par run_id)
2. Transaction atomique : DELETE + INSERT INTO ebv_results SELECT FROM staging
3. Nettoyage staging (succes ou echec)

Execution

Page d'administration

La page /backoffice/env-compute affiche 5 sections correspondant aux modes d'execution. En temps normal, on utilise le mode ONE SHOT qui execute tout d'un coup. Les modes individuels sont utiles pour le debug ou pour relancer une etape specifique apres correction d'un probleme.

Section	Description	API
ONE SHOT	Execute les 8 etapes sequentiellement	/api/ebv/oneshot
ENV	Etape environnement seule	/api/env/compute
XGB	Entrainement + application XGBoost	/api/xgb/compute
EBV	BLUPF90+ seul (trait miel)	/api/ebv/compute
THRG	THRGIBBS seul (6A + 6B)	/api/thrg/compute

Modes d'execution

Mode	Description	Usage
ONE SHOT	Execute les 8 etapes sequentiellement	Execution standard (evaluation complete)
Etape individuelle	Execute une seule etape	Debogage ou re-execution partielle

Suivi en temps reel

Pendant l'execution, l'interface affiche un tableau de progression qui permet de suivre l'avancement et d'identifier rapidement les eventuels problemes :

Indicateur	Description
Elements traites	Nombre de reines/sites traites
Elements en cache	Nombre de resultats recuperes depuis le cache (pas d'appel API)
Appels API	Nombre d'appels aux services externes (geocodage, meteo)
Echecs	Nombre d'erreurs rencontrees
Ignores	Nombre d'elements ignores (donnees insuffisantes pour l'evaluation)

Statuts des jobs

Statut	Description
pending	En attente d'execution dans la queue Redis
running	En cours de traitement par le worker
completed	Termine avec succes
failed	Termine en erreur (staging non promue -- les anciens resultats restent en place)

Idempotence

Tous les jobs du pipeline sont idempotents : relancer un job produit le meme resultat sans effet de bord. Les insertions utilisent des clauses UNIQUE et des operations UPSERT pour eviter les doublons. En cas de doute, on peut toujours relancer un run sans risque.

Worker Python

Le pipeline est execute par un worker Python monolithique dans le container Docker beepass-worker. Ce worker est le seul composant de la plateforme qui n'est pas en JavaScript/TypeScript -- le choix de Python est dicte par l'ecosysteme scientifique (XGBoost, BLUPF90+, numpy).

Architecture

Container beepass-worker (python:3.11-slim + gfortran + BLUPF90+)
|-- PID 1 : python main.py (FastAPI/uvicorn) -- accepte HTTP :8000
|-- PID 7 : rq worker -- consomme 5 queues Redis
    |-- Peut devenir ZOMBIE -> detecte par /health -> Docker restart

Binaires integres

Binaire	Programme	Description
blupf90	BLUPF90+ (UGA 2026)	Remplace blupf90 + airemlf90 (REML via OPTION method VCE)
thrgibbs1f90	GIBBSF90+ (UGA 2026)	Gibbs sampler traits ordinaux et hygieniques

Advisory locks (convention)

Chaque type de pipeline a son propre verrou pour eviter les conflits. Le lock 45 (ONE SHOT) bloque aussi les locks 42-44 puisqu'il enchaine tous les sous-pipelines.

Lock ID	Pipeline	Description
42	BLUPF90	Pipeline EBV continu
43	XGBoost	Pipeline correction environnementale
44	THRGIBBS	Pipeline traits ordinaux
45	ONE SHOT	Orchestrateur complet

Securite du worker

ID	Severite	Mesure
SEC-01	CRITICAL	Modeles XGBoost en format natif .ubj (pas pickle -- elimine le risque d'execution de code arbitraire)
SEC-02	CRITICAL	pg_dump : mot de passe via PGPASSWORD env var (pas en CLI, invisible aux autres processus)
SEC-04	HIGH	Verification SHA256 du modele XGBoost avant chargement (detecte toute modification non autorisee)
SEC-05	HIGH	Comparaison Bearer token via hmac.compare_digest() (timing-safe, empeche les attaques par mesure de temps)
SEC-07	HIGH	Validation format jobId (regex anti-SSRF, empeche l'injection d'URLs malveillantes)

Healthcheck

Le endpoint /health verifie que le processus rq worker n'est pas zombie (un processus qui semble vivant mais ne repond plus) via /proc/PID/status. Si zombie ou mort, HTTP 503 et Docker restart automatique (~90s).

Endpoint	Description	Reponse OK
/health	Liveness (detecte zombie)	200 {"status":"ok","rq_worker":"alive"}
/health/db	Connectivite PostgreSQL	200 {"status":"ok","server_time":"..."}
/db/reset-pool	Reset pool connexions (post-fork)	200 {"status":"pool_reset"}

Fork safety

Le worker demarre rq dans un process enfant via multiprocessing.Process. Le child doit appeler db.reset_pool() puis db.init_pool() pour creer ses propres connexions. Pourquoi ? Parce que les connexions du processus parent sont "cassees" dans le processus enfant apres un fork -- les file descriptors pointent vers les memes sockets, ce qui provoquerait des erreurs de lecture/ecriture melangees.

Resultats

Apres execution complete du pipeline, les resultats sont disponibles a plusieurs endroits :

Sortie	Description
EBV normalises	Scores BeeBreed-like ecrits dans ebv_results pour chaque reine et chaque trait
Fiabilite (r2)	Precision de l'estimation genetique, par trait et par reine
ProvenanceBlock	Bloc UI affichant la provenance des resultats (run_id, date, version) -- transparence totale pour l'eleveur
Hash de stabilite	SHA256 des inputs verifie : memes entrees = memes sorties = meme hash

Les EBV sont consultables :

• Sur la fiche reine (onglet Evaluations) dans F0_QueenView
• Dans l'onglet Soeurs (F0_SistersTab) avec profil de lignee
• Dans le passeport genetique public

Metriques Prometheus

Le worker expose des metriques pour Grafana, permettant de surveiller la sante et la performance du pipeline dans le temps :

Metrique	Type	Description
beepass_ebv_run_total	Counter	Nombre total de runs EBV (par statut)
beepass_ebv_run_duration_seconds	Histogram	Duree des runs EBV
beepass_ebv_pipeline_step_duration_seconds	Histogram	Duree par etape (snapshot, env, xgb_train, xgb_apply, blupf90, thrgibbs_ord, thrgibbs_hyg, normalize, store)
beepass_env_geocode_requests_total	Counter	Appels API geocodage (par provider, statut)
beepass_env_cache_hit_ratio	Gauge	Ratio cache geocodage (proche de 1.0 = economie d'appels API)
beepass_xgb_model_rmse	Gauge	RMSE du modele XGB actif (plus bas = meilleure prediction environnementale)
beepass_thrgibbs_ess	Gauge	ESS par bloc -- Effective Sample Size, mesure la qualite de convergence du Gibbs sampler (> 100 recommande)
beepass_thrgibbs_geweke_p	Gauge	p-value Geweke par bloc (diagnostic de convergence, > 0.05 = OK)
beepass_normalization_base_size	Gauge	Nombre de reines dans la base 5 ans (population de reference pour la normalisation)

Tracabilite complete

La tracabilite repond a une exigence scientifique : chaque resultat publie doit pouvoir etre reproduit. Si un eleveur conteste un EBV, on peut retrouver exactement quelles donnees, quel code et quelle configuration ont produit ce resultat.

Chaque run est enregistre dans la table genetic_runs avec :

Element	Colonne	Description
Code source	git_commit_sha	Commit exact execute
Image Docker	docker_image_digest	Digest image (reproductibilite BLAS)
Dependencies	dependency_lock_sha256	Hash lockfile worker
Config	config_sha256	Hash configuration YAML/JSON
Bundle	bundle_hash	SHA256 concat tous les artefacts
Pedigree	ainv_sha256	Hash fichier sparse A^-1
Data	data_export_sha256	Hash bundle donnees
Seed	seed	Seed Gibbs sampler

Convention missing value

-999 pour traits et covariables numeriques uniquement dans les fichiers .dat. 0 est une valeur valide (honey, HYG -- 0 kg de miel ou 0 cellules nettoyees sont des observations reelles). Jamais -999 pour les IDs : un ID manquant est rejete ou assigne a un groupe unknown_* explicite.

Glossaire pipeline

Terme	Definition
EBV	Estimated Breeding Value -- valeur genetique estimee d'un animal pour un trait donne
BLUP	Best Linear Unbiased Prediction -- methode statistique de reference pour l'evaluation genetique, qui separe les effets genetiques des effets environnementaux
REML	Restricted Maximum Likelihood -- methode pour estimer quelle part de la variation est genetique vs environnementale
AINV	Matrice inverse des relations genetiques additives (A^-1) -- encode mathematiquement les liens de parente entre toutes les reines
Sire-group	Groupe de peres (drones) utilise dans le modele genetique, car on connait rarement le drone individuel
SDI	Single Drone Insemination -- insemination par un seul drone (maximum de precision genetique)
MDI	Multiple Drone Insemination -- insemination par plusieurs drones (plus proche des conditions naturelles)
Threshold model	Modele statistique pour traits ordinaux (notes 1-4), qui postule une variable continue sous-jacente
Gibbs sampler	Algorithme MCMC (Monte Carlo par Chaines de Markov) qui explore iterativement l'espace des solutions pour converger vers la meilleure estimation
Probit	Fonction de lien pour les modeles a seuil, basee sur la distribution normale
time_quality	Qualite temporelle de la mesure HYG (exact = chronometre, declared = approximatif, unknown = non mesure)
r2 (reliability)	Fiabilite de l'estimation genetique (0 a 1), indiquant la precision de l'EBV. Plus une reine a de descendantes evaluees, plus son r2 est eleve
BeeBreed-like	Echelle de normalisation : centre=100, ecart-type=10 -- systeme comparable a celui utilise par BeeBreed (Allemagne)

Correctif v1.1.0 — Promotion ONE SHOT

Correctif critique (v1.1.0)

Les sous-pipelines BLUPF90 et THRGIBBS ne doivent jamais executer la promotion atomique en mode orchestre. Seul l'orchestrateur ONE SHOT execute la promotion globale (etape 8) apres que tous les sous-pipelines sont termines. Sans ce correctif, les resultats partiels pouvaient etre publies avant la fin du pipeline complet.

---

Voir aussi : Reines de reference | Vue d'ensemble