Suggestions

2:51

Why a separate tab

Mapping 1,000 local codes by hand against the 4 million concepts of the OMOP vocabulary is slow. Each algorithm family has its own bias:

• String comparison misses synonyms (“HR” vs “heart rate”).
• Semantic embeddings occasionally confuse close-but-different concepts (“serum creatinine” vs “urine creatinine”).
• An AI agent adds clinical context but is expensive to run over 4 million pairs.

The Suggestions tab combines several methods into a single score and surfaces the per-method details, so you keep the final decision.

Where suggestions come from

The two complement each other: the agent starts from the precomputed scores, its first source of candidates, and queries the semantic index for the concepts they leave without a target. It never starts a computation itself.

The Suggestions tab in Linkr

Similarity methods

Four method families can feed the candidate ranking. Each attacks the problem from a different angle, and their failure modes don’t overlap — which is why combining them beats any single family.

In Linkr, every method is represented next to the combined score by a coloured dot (colours above) followed by its percentage. On hover, a tooltip names the exact algorithm. This helps understand why a score is high: a candidate scoring 92% from the syntactic method alone is likely a textual false friend, while one scoring 80% from semantic + AI is much more solid.

1. Syntactic — compare character strings

We compare label strings as-is, without any understanding of their meaning. Useful because source and OMOP labels often follow different writing conventions: case, spaces or underscores, accents, abbreviations, word order, punctuation. Three algorithms in the catalogue:

• Jaro-Winkler — letter-level proximity with a bonus for shared prefixes. Matches “hemoglobin_a1c” with “Hemoglobin A1c” despite the case and separator differences.
• Token-Sort — splits labels into words, sorts them alphabetically, then compares. Word-order agnostic (“blood pressure systolic” ≈ “systolic blood pressure”).
• N-gram IDF — splits into character n-grams (subsequences of N letters), weights each n-gram by its rarity in the vocabulary. Usagi’s historical method.

Strengths — catches near-literal matches despite writing variants (case, spaces, abbreviations, word order), very fast (milliseconds per pair).

Limits — does not account for synonyms: “creatinine” and “creat” are close, but “heart rate” and “pulse” score zero.

2. Semantic — compare meaning

Each label is encoded as a numerical vector through a sentence-embedding model, then we measure the angle between vectors via cosine similarity. Two labels with close meanings will produce close vectors, even if the words differ.

Default model: BioLORD-2023-M, trained on biomedical text and multilingual (French, English, Spanish, German…).

Configurable alternatives — any Sentence-Transformers compatible BERT model:

• PubMedBERT, SapBERT, ClinicalBERT — biomedical-specialised but English-only.
• all-MiniLM-L6-v2 — general-purpose, English-only, much faster.
• paraphrase-multilingual-MiniLM-L12-v2, LaBSE — general-purpose, multilingual.

Strengths — catches synonyms (“heart rate” ≈ “pulse”), rephrasings, terminology variants.

Limits — can conflate two close-but-distinct concepts (“serum creatinine” vs “urine creatinine”). Expensive to pre-compute over the ~3.5M standard OMOP concepts: a few hours, once per workspace (GPU recommended).

3. Statistical — compare value distributions

For numerical variables (Measurement only), we compare the statistical distribution of values between source concept and candidates: min, P25, median, P75, max, mean, standard deviation. Two variables taking values in the same range with the same shape are probably the same measurement.

Concretely, we use a statistical test to quantify the gap between the two distributions:

• Kolmogorov-Smirnov test (KS) — maximum gap between cumulative distribution functions. KS = 0 → identical distributions; KS close to 1 → very different distributions.
• Wasserstein distance — “cost” of transporting the mass of one distribution onto the other. More robust than KS when supports are shifted (unit change).

Strengths — works even when the label is ambiguous or missing. Very discriminating: hard to confuse creatinine (60–120 µmol/L) with sodium (135–145 mmol/L).

Limits — only applicable to numerical variables with enough values for the distribution to be representative. Sensitive to data-entry artifacts (outliers, mixed units).

4. Agentic AI — let an LLM reason about it

An LLM driven agentically — it decides which tools to call: reading a source concept and its metadata, searching the OMOP vocabulary, browsing a candidate’s hierarchy — examines the best candidates with all the context available: source label, unit, value distribution, wards where the code is used. It proposes one or more mappings carrying a SKOS equivalence (exactMatch, closeMatch, broadMatch, narrowMatch, relatedMatch) and a comment justifying the choice.

Its proposals show up in the tab as one more method, named ai/<model> after the model that produced them, in the Agentic category. The Mapping with an AI agent page explains how to start it.

Strengths — the only method that “understands” clinical semantics (qualifiers, measurement context, nuanced equivalences). Can say “this is not exact, the target is more general” via broadMatch, and says in its comment what differs.

Limits — slow and compute-hungry, risk of hallucinations on rare cases, still requires human validation.

The combined score

The combined score (left column, green bar) is a weighted average of each method’s score. Default weights are:

The Manage suggestions button (top left) opens a dialog with two tabs. The Methods tab has sliders to tune each weight in real time — the table re-sorts automatically; it also shows the number of loaded scores, and lets you Import a file or Delete all. The Compute tab computes the scores — see Precomputing the scores.

In server mode, the Methods in the file section lists every method present — syntactic/jaro-winkler, semantic/biolord, ai/<model>… — each with a bin: Remove the suggestions of a method deletes all its rows from the scores file, keeping the other methods and the mappings. This is how you remove in one go what an agent left.

Selection and mapping

• Click a row to select it. The action bar at the top then shows the usual mapping buttons (Exact match + SKOS dropdown + comment button).
• Candidates already mapped for this source concept are greyed out and not re-selectable.
• The ⓘ icon at the row end opens the target OMOP concept’s detail (description, synonyms, hierarchy).

The main alignment button “Exact” is pre-filled with the selected suggestion’s SKOS equivalence — the one the agent proposed, for an ai/… row (exactMatch, closeMatch, broadMatch, narrowMatch, relatedMatch). You can accept it in one click, or open the dropdown to pick a different equivalence if you disagree. Linkr never maps on its own from a suggestion: that click is what creates the mapping.

AI agent suggestions

An AI agent can leave its own suggestions in the tab, each with a SKOS equivalence and a comment justifying the choice. The Mapping with an AI agent page explains how to put it to work, what it writes into the project and how to follow its work.

Precomputing the scores

Syntactic and semantic scores give every source concept a ranked list of candidates before any agent looks at it. They are computed in Linkr, on the server: Manage suggestions → Compute tab. The computation runs as a background job; you can close the dialog and keep working.

What you need

• The OMOP vocabularies imported in the workspace — see Target concepts. Candidates are taken from their concepts.
• For the syntactic methods: nothing else. They run in the database.
• For the semantic method: an embeddings runtime, a model, and a configuration with a built index. The Models and configurations button of the Compute tab sets it all up.

Models and configurations

The Models and configurations button of the Compute tab opens a dialog with two tabs: Embeddings and models — the embeddings runtime, that is the Python packages that run the models (torch, sentence-transformers, about 2 GB, shared by every workspace of the server), then the models — and Configurations, described below.

Under the list of models, three tiles offer to add one; clicking one opens its form right below:

• BioLORD-2023-M — Proposed by default, the shortest path. Install:
  1. installs the embeddings runtime if needed;
  2. downloads BioLORD-2023-M from Hugging Face (about 1 GB, not shipped with Linkr);
  3. creates a configuration over every standard, valid concept, drugs included.
• Hugging Face — another model of the Hub, named by its owner/name (for instance cambridgeltl/SapBERT-from-PubMedBERT-fulltext), then Download. Needs the embeddings runtime.
• From a folder — the folder of a model downloaded elsewhere, chosen on your computer (it is sent to the server and copied into the workspace) or on the server (read in place). This is how you bring a model into an environment without internet access.

You then build the configuration’s index — the Build button, in the Configurations tab: each target concept is encoded once, and the index then serves every project of the workspace. Count a few hours for about 3.5 million concepts, much less with a GPU (NVIDIA or Apple Silicon). A stopped build resumes where it stopped.

Configurations

A configuration pairs a model with what it encodes. Its scores are written as the semantic/<identifier> method. New creates another one, for instance with another model or over a narrower scope:

The index is built per vocabulary: each is built, not built, or out of date when the vocabulary was re-imported since — an out-of-date index still answers, Rebuild brings it up to date. Changing a configuration’s model, encoded text or target concepts deletes its index.

Running the computation

In the Compute tab:

• Syntactic methods — Jaro-Winkler, Token-Sort, N-gram IDF. N-gram IDF is slow (about an hour of CPU on the whole vocabulary): narrow the targets.
• Semantic method — one of the configurations with a built index, or none.
• Target concepts — standard, valid, domains, vocabularies, classes. For the semantic method, targets are further limited to what its configuration encoded.
• Candidates per concept and method — how many targets each method keeps for each source concept.
• Only the source concepts these methods have not scored yet — to complete a computation rather than redo it.

Compute starts the job. Each method computed replaces its previous scores in the project; the other methods — an agent’s suggestions in particular — are kept. Pause stops the computation: what is finished is already in the scores, and Resume carries on from the percentage reached. Start over drops the paused computation and starts a new one with the settings shown.

Importing a scores file

A scores file computed outside Linkr — by another tool, or in an install without a backend — is loaded through Manage suggestions → Methods tab → Import a file (.parquet or .csv). Its rows are added to the project’s scores and replace the existing ones for the same source concept, target and method.

The file holds one score per (source, candidate, method) triple:

Two columns complete the file: concept_set_uid and concept_set_source_repo, filled in when a suggestion was taken from a concept set of a data dictionary.

Going further

• Mapping with an AI agent — putting an agent to work, following and reviewing its suggestions.
• Agents — what an agent can do in Linkr, and how you stay in control.
• MCP server — create your API key and connect LibreChat or OpenCode.
• Evaluation — review and validate mappings, including those created by an agent.