Suggestions

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 lit les scores précalculés quand il y en a, et s’en sert pour trouver plus vite ses candidats — surtout pour les médicaments.

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 ~4 M concepts OMOP (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 avec 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.

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 (Jaro-Winkler) et sémantiques (embeddings BioLORD) donnent à chaque concept source une liste de candidats classés avant qu’aucun agent ne s’y penche. Ils se calculent hors de Linkr, dans un terminal, avec les deux scripts Python fournis avec le skill, dans son dossier scripts/. Le fichier produit se charge ensuite dans le projet ; cette partie fonctionne aussi dans une installation sans backend.

Prérequis

Les deux scripts

• embed_concepts.py — calcule les embeddings BioLORD des concepts OMOP et écrit concept_embeddings.parquet à côté de CONCEPT.parquet. À lancer une fois par version du vocabulaire : le fichier sert à tous les projets.
• compute_scores.py — compare les concepts source d’un projet aux concepts OMOP et écrit similarity-scores.parquet. À lancer une fois par projet. Par défaut, il calcule Jaro-Winkler et BioLORD ; sans concept_embeddings.parquet, seulement le score syntaxique.

Le script de scoring attend un CSV de concepts source à trois colonnes : terminology, concept_code et concept_name. Le source-concepts.csv d’un export Linkr ZIP du projet fait l’affaire, en renommant ses colonnes si besoin.

python scripts/compute_scores.py \
  --source source-concepts.csv \
  --concept /chemin/vers/vocabulaire/CONCEPT.parquet \
  --embeddings /chemin/vers/vocabulaire/concept_embeddings.parquet \
  --only-standard --only-valid --domain Measurement Observation

Lancez-le dans votre propre terminal, où vous pouvez surveiller la mémoire et l’arrêter avec Ctrl-C. Chaque script affiche l’ensemble de ses options avec --help.

Charger les scores dans Linkr

Dans l’éditeur d’alignements, mode Suggestions : Gérer les suggestions → Importer un fichier, puis choisissez similarity-scores.parquet.

Fichiers produits

Le script de scoring écrit deux fichiers :

• source_embeddings.parquet — les vecteurs d’embeddings des concepts source. Conservé pour ré-utiliser les embeddings lors d’un prochain lancement sans avoir à tout ré-encoder.
• similarity-scores.parquet — un score par triplet (source, candidat, méthode). C’est ce fichier que vous chargez dans Linkr, et c’est aussi là que Linkr range les suggestions des agents.

Aperçu de source_embeddings.parquet :

Aperçu de similarity-scores.parquet pour un concept source (TA systolique invasive), après le passage d’un agent :

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.

Reprise sur interruption

Les scripts écrivent leur sortie de manière incrémentale, ce qui permet de reprendre là où le précédent run s’est arrêté :

• embed_concepts.py enregistre sa progression toutes les 50 batches (~25 000 concepts) — vous pouvez interrompre sans perdre le travail.
• compute_scores.py enregistre toutes les 100 concepts source — les paires (source_vocabulary_id, source_concept_code) déjà scorées sont sautées au redémarrage.

C’est important pour les vocabulaires complets (4 M concepts) qui peuvent prendre des heures.

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.