Suggestions

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”).
• AI validation 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.

The workflow

1. In Linkr — export the project as a ZIP from the Export tab. The ZIP contains project.json, mappings.json and source-concepts.csv.
2. In Claude Code — run the concept-mapping skill (see below). It computes the scores, drafts mappings via an LLM, and produces a similarity-scores.parquet file.
3. Back in Linkr — open the mapping editor, switch to Suggestions mode, click Manage → Import and load the .parquet.

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 ~4M OMOP concepts (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 (Claude), driven agentically (the LLM decides which tools to invoke: reading labels, browsing the OMOP hierarchy, computing on source values), re-reads the top N candidates from the other methods with all the context available: source label, statistics, units, frequency, value examples. It proposes one or more mappings carrying a SKOS equivalence (exactMatch, narrowMatch, broadMatch, relatedMatch) and a short clinical justification.

Strengths — the only method that “understands” clinical semantics (qualifiers, measurement context, nuanced equivalences). Can say “this is not exact, it’s a sub-type” via narrowMatch.

Limits — slow and expensive (tokenised API calls), 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 sliders to tune each weight in real time — the table re-sorts automatically. From there you can also see the number of loaded scores, import a new file, or wipe everything.

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 SKOS equivalence proposed by the agentic AI (exactMatch, narrowMatch, broadMatch, relatedMatch) — you can accept it in one click, or open the dropdown to pick a different equivalence if you disagree.

The Claude concept-mapping Skill

The skill is located in the Linkr repository, under .claude/skills/concept-mapping/. It is a standalone folder that holds:

• SKILL.md — the orchestrator, read by Claude Code when you type /concept-mapping.
• reference.md — DuckDB patterns, TypeScript types, domain heuristics, parquet schema.
• scripts/embed_concepts.py — generates BioLORD embeddings for the OMOP vocabulary (run once per vocabulary release).
• scripts/compute_scores.py — computes scores for a given project (run once per project).
• scripts/update_state.py — recomputes state.json (progress, sessions, file presence).
• review-template/ — static HTML dashboard copied into the project folder the first time you launch the review server.

Plus two companion sub-skills, invoked automatically by the orchestrator:

• concept-mapping-ai — Measurement, Condition, Procedure, Observation.
• concept-mapping-drug — drugs (RxNorm, dosages, pharmaceutical forms).

Requirements

Configuration

Rather than typing paths every run, create a config.local.json at the project root:

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

Details of the three keys:

• vocab_dir — folder holding the OHDSI vocabularies downloaded from ATHENA (CONCEPT.parquet, CONCEPT_SYNONYM.parquet, CONCEPT_RELATIONSHIP.parquet, CONCEPT_ANCESTOR.parquet, plus VOCABULARY.parquet and DOMAIN.parquet). Roughly 10–30 GB depending on the active vocabularies. The skill loads these files into DuckDB at launch.
• models_dir — local cache for phrase-embedding models (by default BioLORD-2023-M, ~500 MB). If you switch model (PubMedBERT, SapBERT…), it is downloaded here on first use. Avoids re-downloading several gigabytes for every project.
• projects_dir — root of mapping projects. Each subfolder is a project exported from Linkr (project.json, mappings.json, source-concepts.csv) and ends up receiving the score files (similarity-scores.parquet, source_embeddings.parquet, state.json).

The skill reads these values on launch and stops asking.

Skill steps

The orchestrator runs through the following steps automatically:

The agent reuses the similarities produced by the methods described above (syntactic, semantic, statistical) to pre-rank candidates before deciding — it does not invent a new scoring. It simply adds its own ai/<model-id> line next to the others, with a SKOS equivalence and a comment justifying its choice.

Output files

The skill writes two files to the project folder:

• source_embeddings.parquet — the embedding vectors of source concepts. Kept so embeddings can be reused on the next run without recomputing everything.
• similarity-scores.parquet — one score per (source, candidate, method) triple. This is the file you re-import into Linkr.

Preview of source_embeddings.parquet:

Preview of similarity-scores.parquet for a source concept (invasive systolic BP):

Resume on interrupt

The scripts write their output incrementally, which lets you resume where the previous run stopped:

• embed_concepts.py saves progress every 50 batches (~25,000 concepts) — you can interrupt without losing work.
• compute_scores.py saves every 100 source concepts — already-scored (source_vocabulary_id, source_concept_code) pairs are skipped on restart.

This matters for full vocabularies (4M concepts) that can take hours.