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 »).
• Une validation 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.

Le workflow

1. Dans Linkr — exportez le projet en ZIP depuis l’onglet Export. Le ZIP contient project.json, mappings.json et source-concepts.csv.
2. Dans Claude Code — lancez le skill concept-mapping (voir plus bas). Il calcule les scores, propose des alignements via un LLM, et produit un fichier similarity-scores.parquet.
3. De retour dans Linkr — ouvrez l’éditeur d’alignements, basculez sur le mode Suggestions, cliquez Gérer → Importer et chargez le .parquet.

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 (Claude), piloté de façon agentique (le LLM décide quels outils invoquer : lecture des libellés, consultation de la hiérarchie OMOP, calculs sur les valeurs source), relit les N meilleurs candidats sortis des autres méthodes avec tout le contexte disponible : libellé source, statistiques, unités, fréquence, exemples de valeurs. Il propose un ou plusieurs alignements assortis d’une équivalence SKOS (exactMatch, narrowMatch, broadMatch, relatedMatch) et d’une courte justification clinique.

Forces — la seule méthode qui « comprend » la sémantique clinique (qualifiers, contexte de mesure, équivalences nuancées). Sait dire « ce n’est pas exact, c’est un sous-type » via narrowMatch.

Limites — lent et coûteux (appels API tokenisés), 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 pouvez aussi y voir le nombre de scores chargés, importer un nouveau fichier, ou tout supprimer.

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 proposée par l’IA agentique (exactMatch, narrowMatch, broadMatch, 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.

Le Skill Claude concept-mapping

Le skill est situé dans le dépôt Linkr, sous .claude/skills/concept-mapping/. C’est un dossier autonome qui contient :

• SKILL.md — l’orchestrateur, lu par Claude Code quand vous tapez /concept-mapping.
• reference.md — patterns DuckDB, types TypeScript, heuristiques par domaine, schéma parquet.
• scripts/embed_concepts.py — génère les embeddings BioLORD pour le vocabulaire OMOP (à exécuter une fois par version de vocabulaire).
• scripts/compute_scores.py — calcule les scores pour un projet donné (à exécuter une fois par projet).
• scripts/update_state.py — recalcule state.json (progression, sessions, fichiers présents).
• review-template/ — dashboard HTML statique copié dans le dossier projet la première fois que vous lancez le serveur de revue.

Et deux sous-skills complémentaires, invoqués automatiquement par l’orchestrateur :

• concept-mapping-ai — Measurement, Condition, Procedure, Observation.
• concept-mapping-drug — médicaments (RxNorm, dosages, formes pharmaceutiques).

Prérequis

Configuration

Plutôt que de répéter les chemins à chaque exécution, créez un config.local.json à la racine du projet :

{
  "concept-mapping": {
    "vocab_dir":     "/path/to/ohdsi-vocabularies",
    "models_dir":    "/path/to/bert-models-cache",
    "projects_dir":  "/path/to/mapping-projects"
  }
}

Détail des trois clés :

• vocab_dir — dossier contenant les vocabulaires OHDSI téléchargés depuis ATHENA (CONCEPT.parquet, CONCEPT_SYNONYM.parquet, CONCEPT_RELATIONSHIP.parquet, CONCEPT_ANCESTOR.parquet, plus VOCABULARY.parquet et DOMAIN.parquet). Compte environ 10–30 Go selon les vocabulaires activés. Le skill charge ces fichiers en DuckDB au lancement.
• models_dir — cache local des modèles de phrase-embedding (par défaut BioLORD-2023-M, ~500 Mo). Si vous changez de modèle (PubMedBERT, SapBERT…), il est téléchargé ici à la première utilisation. Évite de re-télécharger plusieurs gigaoctets à chaque projet.
• projects_dir — racine des projets d’alignement. Chaque sous-dossier correspond à un projet exporté depuis Linkr (project.json, mappings.json, source-concepts.csv) et reçoit en retour les fichiers de scores (similarity-scores.parquet, source_embeddings.parquet, state.json).

Le skill lit ces valeurs au lancement et ne demande plus rien d’autre.

Les étapes du skill

L’orchestrateur enchaîne automatiquement les étapes suivantes :

L’agent réutilise les similarités produites par les méthodes décrites plus haut (syntaxique, sémantique, statistique) pour pré-classer les candidats avant de prendre sa décision — il n’invente pas un nouveau scoring. Il ajoute simplement sa propre ligne ai/<model-id> à côté des autres, avec une équivalence SKOS et un commentaire justifiant son choix.

Fichiers produits

Le skill écrit deux fichiers dans le dossier projet :

• 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 ré-importez dans Linkr.

Aperçu de source_embeddings.parquet :

Aperçu de similarity-scores.parquet pour un concept source (TA systolique invasive) :

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.