vendredi, 24 avril, 2026
Base de référence
La base de référence molecules_reference.db est le socle de données partagé qui alimente tout le volet moléculaire d'IsoFind. Elle contient 156 molécules normalisées en 11 familles, leurs 50 voies de dégradation tabulées, 56 fractionnements isotopiques et 49 relations parent-métabolite. Cette page décrit la structure technique de cette base, la distinction entre référentiel et catalogue utilisateur, le mode d'interrogation et les modalités d'enrichissement.
Structure générale
La base de référence est une base SQLite en lecture seule depuis le point de vue d'un projet. Elle est distribuée avec l'application et mise à jour lors des publications IsoFind. Cinq tables structurent l'information, liées par des clés étrangères qui garantissent la cohérence.
| Table | Rôle | Lignes |
|---|---|---|
| ref_molecules | Catalogue principal des molécules avec métadonnées et seuils | 156 |
| molecule_degradation_pathways | Voies de dégradation avec conditions, cinétique, métabolites | 50 |
| molecule_isotope_fractionation | Fractionnements isotopiques par voie et élément | 56 |
| molecule_metabolites | Relations parent-métabolite avec rendements | 49 |
| ref_molecules_isotopes | Interprétation isotopique par molécule et élément | 18 |
Table ref_molecules : les 24 champs
La table principale porte 24 colonnes qui couvrent l'identité chimique, la taxinomie, les seuils réglementaires, les limites analytiques et la gestion de catalogue. Certains champs sont systématiquement remplis, d'autres optionnels selon la molécule.
| Champ | Type | Défaut | Remplissage |
|---|---|---|---|
| id | INTEGER | - | Clé primaire auto-incrémentée |
| nom | TEXT | - | Systématique (nom usuel, obligatoire) |
| nom_iupac | TEXT | - | Optionnel, rempli à 49 % (80 nulls sur 156) |
| cas | TEXT | - | Systématique pour les molécules du catalogue |
| formule | TEXT | - | Systématique (formule brute) |
| masse_molaire | REAL | - | Systématique (g/mol) |
| mz_principal | REAL | - | Systématique (transition MS principale) |
| mz_secondaires | TEXT | - | Rempli à 86 % (liste séparée par virgules) |
| famille | TEXT | - | Systématique (obligatoire, 11 valeurs) |
| sous_famille | TEXT | - | Systématique |
| type_polluant | TEXT | - | Organique (144) ou inorganique (12) |
| niveau_acces | TEXT | 'gratuit' | gratuit / pro / defense |
| seuil_eau | REAL | - | Rempli à 77 % (36 molécules sans seuil EU/EPA) |
| seuil_sol | REAL | - | Rempli à 24 % (peu documenté en réglementaire sol) |
| seuil_unit | TEXT | 'µg/L' | 149 µg/L, 4 pg/L (dioxines), 3 mg/L |
| reglementation | TEXT | - | Texte libre décrivant les cadres applicables |
| notes | TEXT | - | Rempli à 74 % (commentaires scientifiques) |
| unite_defaut | TEXT | 'µg/L' | 101 µg/L, 45 ng/L (PFAS, HAP), 6 pg/L, 4 mg/L |
| lod | REAL | - | Limite de détection analytique |
| loq | REAL | - | Limite de quantification |
| methode_ref | TEXT | - | Normes d'analyse applicables (ISO, EPA, EN) |
| version_db | TEXT | '2.0' | Version des données (126 en 2.0, 30 en 2) |
| actif | INTEGER | 1 | Flag de désactivation logique, 156 actifs |
| created_at | TEXT | datetime('now') | Horodatage de création de la fiche |
Le flag actif permet de retirer une molécule du catalogue visible sans la supprimer physiquement, ce qui préserve les références des mesures historiques à une molécule désactivée. Les 156 molécules actuelles sont toutes actives.
Exemple complet : la fiche PFOA
Voici le contenu exact d'une fiche de la base, pour illustrer la richesse typique d'une entrée bien documentée.
id = 2
nom = 'PFOA'
nom_iupac = 'Perfluorooctanoic acid'
cas = '335-67-1'
formule = 'C8HF15O2'
masse_molaire = 414,07
mz_principal = 413,0
mz_secondaires = '169.0,219.0,269.0,319.0,369.0'
famille = 'PFAS'
sous_famille = 'PFCA-C8'
type_polluant = 'organique'
niveau_acces = 'gratuit'
seuil_eau = 0,1
seuil_sol = 2,0
seuil_unit = 'µg/L'
reglementation = 'EU 2020/2184 (somme 4 PFAS ≤0.10) ; REACH Ann.XVII interdit fab. 2020'
unite_defaut = 'ng/L'
lod = 0,001
loq = 0,005
methode_ref = 'ISO 21675:2019 ; EN 17892:2023 ; EPA 537.1'
version_db = '2.0'
actif = 1
nom = 'PFOA'
nom_iupac = 'Perfluorooctanoic acid'
cas = '335-67-1'
formule = 'C8HF15O2'
masse_molaire = 414,07
mz_principal = 413,0
mz_secondaires = '169.0,219.0,269.0,319.0,369.0'
famille = 'PFAS'
sous_famille = 'PFCA-C8'
type_polluant = 'organique'
niveau_acces = 'gratuit'
seuil_eau = 0,1
seuil_sol = 2,0
seuil_unit = 'µg/L'
reglementation = 'EU 2020/2184 (somme 4 PFAS ≤0.10) ; REACH Ann.XVII interdit fab. 2020'
unite_defaut = 'ng/L'
lod = 0,001
loq = 0,005
methode_ref = 'ISO 21675:2019 ; EN 17892:2023 ; EPA 537.1'
version_db = '2.0'
actif = 1
Plusieurs éléments méritent d'être notés : l'unité de seuil est en µg/L mais l'unité par défaut d'affichage en ng/L parce que les laboratoires rendent les PFAS en ng/L pour la lisibilité. IsoFind normalise automatiquement ces deux unités pour la comparaison au seuil. Les transitions MS secondaires sont stockées en texte virgule-séparé pour rester souples, et trois normes méthodes sont citées ensemble pour couvrir les pratiques différentes des laboratoires américains et européens.
Référentiel vs catalogue utilisateur
IsoFind distingue deux niveaux de stockage pour les molécules : la base de référence partagée (ref_molecules) et le catalogue utilisateur propre à chaque projet (user_molecules). Cette distinction est fondamentale pour le modèle de données d'IsoFind.
| Aspect | ref_molecules (référentiel) | user_molecules (catalogue utilisateur) |
|---|---|---|
| Statut | Lecture seule, distribuée avec IsoFind | Éditable, propre au projet |
| Portée | Commune à tous les projets | Isolée par projet |
| Évolution | Mises à jour lors des publications IsoFind | À la main de l'utilisateur |
| Suppression | Impossible, désactivation via flag actif | Possible à l'échelle du projet |
| Référencée par les mesures | Non (pas de lien direct) | Oui (clé étrangère molecule_id) |
Pour utiliser une molécule de référence sur un projet, il faut explicitement l'importer dans user_molecules. Cette copie ponctuelle permet à l'utilisateur de retoucher localement les seuils ou les LOQ sans impacter les autres projets. L'endpoint dédié à cette opération est POST /api/molecules/reference/{ref_id}/importer.
L'import détecte les doublons par CAS : si la molécule existe déjà dans le catalogue utilisateur avec le même CAS, l'import retourne l'identifiant existant sans créer de doublon. Ce comportement protège contre les imports multiples accidentels mais n'exclut pas les doublons introduits manuellement avec des noms distincts et des CAS différents.
Endpoints du module reference
Six endpoints exposent la base de référence aux applications clientes, tous sous le préfixe /api/molecules/reference/.
| Méthode | Chemin | Usage |
|---|---|---|
| GET | /reference/catalogue | Catalogue filtré par famille, niveau_acces, recherche texte |
| GET | /reference/familles | Liste des 11 familles avec comptage et niveaux d'accès |
| GET | /reference/{ref_id} | Fiche complète d'une molécule de référence |
| GET | /reference/{ref_id}/isotopes | Données isotopiques associées (CSIA et interprétations) |
| POST | /reference/{ref_id}/importer | Copie une molécule vers user_molecules du projet |
| POST | /reference/importer-batch | Import en lot par liste d'identifiants |
L'endpoint catalogue accepte trois paramètres optionnels : famille (filtre exact), niveau_acces (gratuit / pro / defense) et q (recherche texte sur nom, CAS, formule). La limite par défaut est de 200 molécules par requête, ajustable via limit.
Le endpoint familles
L'endpoint /reference/familles est utile pour peupler les interfaces de navigation. Il retourne la liste des familles avec leur compteur et la répartition par niveau d'accès, ce qui permet d'afficher en interface le nombre de molécules disponibles par famille avec la licence courante.
| Famille | Molécules | gratuit / pro / defense |
|---|---|---|
| Pesticides | 38 | Distribution selon les molécules |
| PFAS | 26 | 23 / 3 / 0 |
| Médicaments / PE | 21 | Mixte |
| HAP | 19 | 1 / 18 / 0 |
| Solvants chlorés | 16 | 4 / 12 / 0 |
| Explosifs | 12 | Partage défense important |
| PCB | 9 | Mixte |
| Perchlorates | 4 | Gratuit |
| Dioxines / Furanes | 4 | Pro |
| Cyanures | 4 | Gratuit |
| Inorganiques (oxyanions) | 3 | Gratuit |
| Total | 156 | 67 / 77 / 12 |
Cohérence et validation
La base de référence est vérifiée à chaque publication IsoFind par une série de contrôles automatiques qui garantissent la cohérence des données. Ces contrôles portent à la fois sur la structure et sur le contenu.
- Unicité du CAS : aucun doublon n'est autorisé sur le champ cas pour les molécules actives.
- Cohérence des familles : la valeur du champ famille doit appartenir à la liste fermée des 11 familles officielles.
- Plausibilité des seuils : les valeurs de seuil_eau sont encadrées par des bornes physiques (positives, inférieures à 10 mg/L en µg/L équivalent).
- Clés étrangères : les molécules citées dans molecule_degradation_pathways, molecule_isotope_fractionation et molecule_metabolites doivent toutes exister dans ref_molecules.
- Présence minimale des métadonnées essentielles : nom, CAS, formule, masse molaire, famille sont obligatoires.
Enrichissement et évolution
La base évolue par versions. Le champ version_db de chaque fiche porte la version sous laquelle elle a été créée ou modifiée pour la dernière fois. La version courante majoritaire est 2.0 (126 fiches), avec 30 fiches encore en 2 qui correspondent à des ajouts anciens non encore retouchés depuis la migration du format.
Les enrichissements futurs concernent quatre axes identifiés.
| Axe d'enrichissement | Exemples prévus |
|---|---|
| Extension du catalogue moléculaire | BTEX, hydrocarbures C10-C40, phtalates, retardateurs de flamme bromés |
| Densification CSIA | Fractionnements CSIA sur pesticides néonicotinoïdes, solvants chlorés manquants |
| Voies de dégradation manquantes | Voies aérobies pour HAP 4+ cycles, photolyse PFAS aqueuse |
| Seuils sol | Rattrapage du seuil_sol actuellement à 24 % rempli |
Les contributions d'utilisateurs à la base de référence peuvent être soumises à IsoFind SAS pour intégration dans les publications futures. La procédure demande une référence bibliographique vérifiable pour chaque ajout. Les enrichissements purement locaux restent stockés dans le catalogue utilisateur du projet sans remonter dans le référentiel partagé.
Sauvegarde et intégrité
La base de référence est un fichier SQLite binaire. Son emplacement sur le disque dépend de la configuration d'installation d'IsoFind. Elle est chargée au démarrage et mise en cache pour les requêtes fréquentes. Une altération accidentelle du fichier est détectée au chargement par vérification d'intégrité ; dans ce cas, le module moléculaire retourne des listes vides avec le flag ref_disponible: false plutôt que de lever une erreur qui bloquerait l'application.
Cette dégradation silencieuse permet à l'utilisateur de continuer à travailler sur les mesures existantes (qui pointent vers user_molecules) pendant qu'une restauration de la base de référence est mise en place. La restauration consiste simplement à remettre le fichier fourni par l'installation, aucune migration de données n'est nécessaire.
Pour aller plus loin
- Volet moléculaire : panorama des 11 familles et navigation de la base.
- Voies de dégradation : détail des 50 voies et leur intégration dans le moteur de simulation.
- Isotopie CSIA : structure du bridge CSIA qui exploite la base.
- API IsoFind : endpoints généraux, au-delà du module molécules.