Suggestions

2:45

Pourquoi un onglet séparé

Aligner 1 000 codes locaux à la main contre les 4 millions de concepts du vocabulaire OMOP est long. Trois familles d’algorithmes ont chacune leur biais :

• La comparaison de chaînes rate les synonymes (« HR » vs « heart rate »).
• Les embeddings sémantiques confondent parfois deux concepts proches (« créatinine sérique » vs « créatininémie urinaire »).
• Un agent IA ajoute du contexte clinique mais coûte cher si on l’applique à 4 millions de paires.

L’onglet Suggestions cumule plusieurs méthodes en un seul score et expose les détails ligne par ligne, pour que vous gardiez la main sur la décision finale.

D’où viennent les suggestions

Les deux se complètent : l’agent part des scores précalculés, sa première source de candidats, et interroge l’index sémantique pour les concepts qu’ils laissent sans cible. Il ne lance jamais lui-même un calcul.

L’onglet Suggestions dans Linkr

Méthodes de similarité

Quatre familles de méthodes peuvent contribuer au pré-classement des candidats. Chacune attaque le problème sous un angle différent, et leurs erreurs ne se recoupent pas — c’est pourquoi les combiner donne de meilleurs résultats qu’utiliser une seule famille.

Dans Linkr, chaque méthode est représentée à droite du score combiné par une pastille colorée (couleurs ci-dessus) suivie de son pourcentage. Au survol, une infobulle indique le nom exact de l’algorithme. Cela permet de comprendre l’origine d’un score élevé : un candidat noté 92 % uniquement par la méthode syntaxique est probablement un faux ami textuel, tandis qu’un candidat noté 80 % par sémantique + IA est plus solide.

1. Syntaxique — comparer les chaînes de caractères

On compare les chaînes des libellés telles quelles, sans rien comprendre à leur sens. Utile parce que les libellés sources et les libellés OMOP suivent souvent des conventions d’écriture différentes : casse, espaces ou underscores, accents, abréviations, ordre des mots, ponctuation. Trois algorithmes au catalogue :

• Jaro-Winkler — proximité lettre à lettre, avec bonus pour les préfixes communs. Rapproche « hemoglobin_a1c » et « Hemoglobin A1c » malgré la casse et le séparateur.
• Token-Sort — découpe les libellés en mots, les trie alphabétiquement, puis compare. Indifférent à l’ordre (« blood pressure systolic » ≈ « systolic blood pressure »).
• N-gram IDF — découpe en n-grammes de caractères (sous-séquences de N lettres), pondère chaque n-gramme par sa rareté dans le vocabulaire. Méthode historique d’Usagi.

Forces — détecte les correspondances quasi-littérales malgré les variantes d’écriture (casse, espaces, abréviations, ordre des mots), très rapide (millisecondes par paire).

Limites — ne prend pas en compte les synonymes : « créatinine » et « creat » sont proches, mais « heart rate » et « pulse » sont à zéro.

2. Sémantique — comparer le sens

On encode chaque libellé en vecteur numérique via un modèle de phrase-embedding, puis on mesure l’angle entre les vecteurs via la similarité cosinus. Deux libellés au sens proche produiront des vecteurs proches, même si les mots sont différents.

Modèle par défaut : BioLORD-2023-M, entraîné sur des textes biomédicaux et multilingue (français, anglais, espagnol, allemand…).

Modèles alternatifs configurables — n’importe quel modèle BERT compatible Sentence-Transformers :

• PubMedBERT, SapBERT, ClinicalBERT — spécialisés biomédicaux mais anglais uniquement.
• all-MiniLM-L6-v2 — généraliste, anglais uniquement, beaucoup plus rapide.
• paraphrase-multilingual-MiniLM-L12-v2, LaBSE — multilingues généralistes.

Forces — capte les synonymes (« heart rate » ≈ « pulse »), les reformulations, les variantes terminologiques.

Limites — peut rapprocher deux concepts proches mais distincts (« créatinine sérique » vs « créatininémie urinaire »). Coûteux à pré-calculer sur les ~3,5 M concepts OMOP standard : quelques heures, une fois par espace de travail (GPU recommandé).

3. Statistique — comparer les distributions de valeurs

Pour les variables numériques (Measurement uniquement), on compare la distribution statistique des valeurs entre concept source et candidats : min, P25, médiane, P75, max, moyenne, écart-type. Deux variables qui prennent leurs valeurs dans la même plage, avec la même forme, sont probablement la même mesure.

Concrètement, on utilise un test statistique pour quantifier l’écart entre les deux distributions :

• Test de Kolmogorov-Smirnov (KS) — écart maximal entre les fonctions de répartition. KS = 0 → distributions identiques ; KS proche de 1 → distributions très différentes.
• Divergence de Wasserstein — « coût » pour transporter la masse d’une distribution vers l’autre. Plus robuste que KS quand les supports sont déplacés (changement d’unité).

Forces — fonctionne même quand le libellé est ambigu ou absent. Très discriminant : difficile de confondre la créatinine (60–120 µmol/L) avec la natrémie (135–145 mmol/L).

Limites — uniquement applicable aux variables numériques avec assez de valeurs pour que la distribution soit représentative. Sensible aux artefacts de saisie (valeurs aberrantes, unités mélangées).

4. IA agentique — laisser un LLM raisonner

Un LLM piloté de façon agentique — c’est lui qui décide quels outils appeler : lire un concept source et ses métadonnées, chercher dans le vocabulaire OMOP, consulter la hiérarchie d’un candidat — examine les meilleurs candidats avec tout le contexte disponible : libellé source, unité, distribution des valeurs, services où le code est utilisé. Il propose un ou plusieurs alignements assortis d’une équivalence SKOS (exactMatch, closeMatch, broadMatch, narrowMatch, relatedMatch) et d’un commentaire qui justifie le choix.

Ses propositions apparaissent dans l’onglet comme une méthode de plus, nommée ai/<modèle> d’après le modèle qui les a produites, dans la catégorie Agentique. La page Aligner avec un agent IA explique comment le lancer.

Forces — la seule méthode qui « comprend » la sémantique clinique (qualificatifs, contexte de mesure, équivalences nuancées). Sait dire « ce n’est pas exact, la cible est plus générale » via broadMatch, et dit dans son commentaire ce qui diffère.

Limites — lente et coûteuse en calcul, risque d’hallucinations sur les cas rares, nécessite toujours une validation humaine.

Le score combiné

Le score combiné (colonne de gauche, barre verte) est une moyenne pondérée des scores de chaque méthode. Les poids par défaut sont :

Le bouton Gérer les suggestions (en haut à gauche) ouvre une boîte de dialogue à deux onglets. L’onglet Méthodes a des curseurs pour ajuster chaque poids en temps réel — le tableau se re-trie automatiquement ; vous y voyez aussi le nombre de scores chargés, et vous pouvez Importer un fichier ou Tout supprimer. L’onglet Calcul lance le calcul des scores — voir Précalculer les scores.

En mode serveur, la section Méthodes du fichier liste chaque méthode présente — syntactic/jaro-winkler, semantic/biolord, ai/<modèle>… — avec une corbeille : Retirer les suggestions d’une méthode supprime toutes ses lignes du fichier de scores, en conservant les autres méthodes et les alignements. C’est le moyen de retirer d’un coup ce qu’un agent a déposé.

Sélection et alignement

• Cliquez sur une ligne pour la sélectionner. La barre d’actions en haut affiche alors les boutons d’alignement habituels (Exact match + menu déroulant SKOS + bouton commentaire).
• Les candidats déjà alignés pour ce concept source sont grisés et ne sont pas re-sélectionnables.
• L’icône ⓘ en bout de ligne ouvre la fiche du concept OMOP cible (description, synonymes, hiérarchie).

Le bouton d’alignement principal « Exact » est pré-rempli avec l’équivalence SKOS de la suggestion sélectionnée — celle proposée par l’agent pour une ligne ai/… (exactMatch, closeMatch, broadMatch, narrowMatch, relatedMatch). Vous pouvez l’accepter en un clic, ou ouvrir le menu déroulant pour choisir une autre équivalence si vous n’êtes pas d’accord. Linkr n’aligne jamais seul à partir d’une suggestion : c’est ce clic qui crée l’alignement.

Suggestions d’un agent IA

Un agent IA peut déposer ses propres suggestions dans l’onglet, chacune avec une équivalence SKOS et un commentaire qui justifie le choix. La page Aligner avec un agent IA explique comment le faire travailler, ce qu’il écrit dans le projet et comment suivre son travail.

Précalculer les scores

Les scores syntaxiques et sémantiques donnent à chaque concept source une liste de candidats classés avant qu’aucun agent ne s’y penche. Ils se calculent dans Linkr, sur le serveur : Gérer les suggestions → onglet Calcul. Le calcul tourne en tâche de fond, on peut fermer la fenêtre et continuer à travailler.

Ce qu’il faut

• Les vocabulaires OMOP importés dans l’espace de travail — voir Concepts cibles. Les candidats sont pris parmi leurs concepts.
• Pour les méthodes syntaxiques : rien d’autre. Elles s’exécutent dans la base.
• Pour la méthode sémantique : un environnement d’embeddings, un modèle et une configuration dont l’index est construit. Le bouton Modèles et configurations de l’onglet Calcul installe le tout.

Modèles et configurations

Le bouton Modèles et configurations de l’onglet Calcul ouvre une fenêtre à deux onglets : Embeddings et modèles — l’environnement d’embeddings, c’est-à-dire les paquets Python qui font tourner les modèles (torch, sentence-transformers, environ 2 Go, partagés par tous les espaces de travail du serveur), puis les modèles — et Configurations, décrit plus bas.

Sous la liste des modèles, trois tuiles proposent d’en ajouter un ; un clic sur l’une ouvre son formulaire juste en dessous :

• BioLORD-2023-M — Proposé par défaut, la voie la plus courte. Installer :
  1. installe l’environnement d’embeddings si besoin ;
  2. télécharge BioLORD-2023-M depuis Hugging Face (environ 1 Go, non livré avec Linkr) ;
  3. crée une configuration qui couvre tous les concepts standard et valides, médicaments compris.
• Hugging Face — un autre modèle du Hub, désigné par son propriétaire/nom (par exemple cambridgeltl/SapBERT-from-PubMedBERT-fulltext), puis Télécharger. Demande l’environnement d’embeddings.
• Depuis un dossier — le dossier d’un modèle déjà téléchargé ailleurs, choisi sur votre ordinateur (il est envoyé au serveur et copié dans l’espace de travail) ou sur le serveur (lu sur place). C’est ainsi qu’on apporte un modèle dans un environnement sans accès internet.

Il reste à construire l’index de la configuration — bouton Construire, dans l’onglet Configurations : chaque concept cible est encodé une fois, puis l’index sert à tous les projets de l’espace de travail. Comptez quelques heures pour environ 3,5 millions de concepts, beaucoup moins avec un GPU (NVIDIA ou Apple Silicon). Une construction arrêtée reprend là où elle s’était arrêtée.

Les configurations

Une configuration associe un modèle à ce qu’il encode. Ses scores sont écrits sous la méthode semantic/<identifiant>. Nouvelle en crée une autre, par exemple avec un autre modèle ou sur un périmètre plus étroit :

L’index est construit par vocabulaire : chacun est construit, non construit, ou périmé quand le vocabulaire a été réimporté depuis — un index périmé répond encore, Reconstruire le remet à jour. Modifier le modèle, le texte encodé ou les concepts cibles d’une configuration supprime son index.

Lancer le calcul

Dans l’onglet Calcul :

• Méthodes syntaxiques — Jaro-Winkler, Token-Sort, N-gram IDF. N-gram IDF est lent (environ une heure de CPU sur tout le vocabulaire) : restreignez les cibles.
• Méthode sémantique — une des configurations dont l’index est construit, ou aucune.
• Concepts cibles — standard, valides, domaines, vocabulaires, classes. Pour la méthode sémantique, les cibles sont en plus limitées à ce que sa configuration a encodé.
• Candidats par concept et par méthode — combien de cibles chaque méthode garde pour chaque concept source.
• Seulement les concepts sources que ces méthodes n’ont pas encore scorés — pour compléter un calcul plutôt que le refaire.

Calculer lance la tâche. Chaque méthode calculée remplace ses scores précédents dans le projet ; les autres méthodes — les suggestions d’un agent notamment — sont conservées. Pause arrête le calcul : ce qui est fini est déjà dans les scores, et Reprendre repart du pourcentage atteint. Recommencer abandonne le calcul en pause et en lance un nouveau avec les réglages affichés.

Importer un fichier de scores

Un fichier de scores calculé hors de Linkr — par un autre outil, ou dans une installation sans backend — se charge par Gérer les suggestions → onglet Méthodes → Importer un fichier (.parquet ou .csv). Ses lignes s’ajoutent aux scores du projet et remplacent celles qui existent déjà pour le même concept source, la même cible et la même méthode.

Le fichier contient un score par triplet (source, candidat, méthode) :

Deux colonnes complètent le fichier : concept_set_uid et concept_set_source_repo, remplies quand une suggestion a été prise dans un concept set d’un dictionnaire de données.

Pour aller plus loin

• Aligner avec un agent IA — faire travailler un agent, suivre et relire ses suggestions.
• Agents — ce qu’un agent peut faire dans Linkr, et comment vous gardez la main.
• Serveur MCP — créer sa clé API et brancher LibreChat ou OpenCode.
• Évaluation — relire et valider les alignements, y compris ceux créés par un agent.