Mapping Editor

At a glance

The editor is a resizable two-column layout, separated by a divider you can drag to adjust the space to your preference:

The workflow is always the same:

1. Select a source concept in the left table.
2. Find the target concept in the right pane (via a concept set or a search in the OHDSI vocabularies).
3. Click Exact match — or pick another equivalence level from the dropdown (more on this below).

Source concepts

The left table lists all the concepts to map with infinite scroll — rows load progressively as you scroll down.

Search bar

A full-width search bar sits above the table. Type a name, code or identifier, then press Enter or click Search. The search combines three strategies ranked by relevance:

1. Exact match on the numeric identifier.
2. Substring match on name and code.
3. Fuzzy match via Jaro-Winkler (threshold ≥ 0.8) — handles typos and spelling variants.

Table columns

Available columns depend on the data present in your source. The button at the bottom of the table lets you show or hide columns:

• Status (small coloured dot) — see below.
• Vocabulary * — source terminology (e.g., Laboratory, ICCA…).
• Category — useful for filtering source concepts by clinical domain and working through an entire category at once.
• Source concept ID — numeric ID used in OMOP exports. For file sources without an ID column, this is the ID assigned from the global view.
• Concept name — label of the concept.
• Concept code * — local code of the concept in your source system.
• Patients and Records — observed frequencies in your database. Essential for prioritising the most common concepts.
• Metadata — visible only when the Metadata (JSON) column was configured at import. Clicking it opens the concept detail view.

* required columns at import.

Inline filters

A second header row, directly below the column titles, holds the filters. They combine in real time:

• Mapping status — dropdown with options: All · Unmapped · Mapped · Mapped elsewhere.
• Concept name — exact text match, unlike the search bar above which performs a fuzzy search.
• Code and ID — text fields.
• Vocabulary, Category, Subcategory, Domain, Class — multi-select menus, populated from the distinct values in your source.

The status dot

Each row starts with a coloured dot indicating the mapping state of the concept:

Green dot — hovering shows a summary of existing mappings for this concept in this project: target concept, vocabulary, equivalence, and received reviews.

Blue dot — the same code has already been mapped in another project of the workspace. Clicking it opens a popover listing those mappings, with an Import button to bring them into the current project in one click.

Concept metadata

If your source includes metadata, the icon at the end of a row opens the concept metadata view in place of the source table. This view displays, depending on the content:

• A descriptive statistics card (min, median, mean, max, standard deviation…) with a boxplot.
• Interactive charts (distribution histogram, bar chart, pie chart, temporal trend by year).
• A breakdown by hospital unit.
• A free-form properties table.
• The full raw JSON ({} button in the top right).

A ← Back button returns to the source table, preserving your scroll position.

Expected JSON structure

The Metadata (JSON) column must contain a JSON object. Linkr recognises two formats.

{
  "metadata": {
    "granularity": "Day",
    "completeness": "98 %"
  },
  "statistics": {
    "min": 0,
    "p25": 45,
    "median": 72,
    "p75": 110,
    "max": 980,
    "mean": 78.4,
    "std": 32.1,
    "count": 12450
  },
  "distributions": [
    {
      "name": "Distribution by sex",
      "type": "pie",
      "data": [
        { "label": "Female", "value": 6230 },
        { "label": "Male", "value": 6220 }
      ]
    },
    {
      "name": "Trend by year",
      "type": "line",
      "data": [
        { "label": "2020", "value": 3100 },
        { "label": "2021", "value": 4200 }
      ]
    }
  ],
  "properties": [
    { "label": "Unit", "value": "mg/dL" },
    { "label": "Source", "value": "LAB" }
  ]
}

Target concepts

The right pane has three modes, toggled via a switcher at the top: Concept sets, Search and Suggestions. Each has its own logic, but all three let you select a target concept that you then map using the action bar.

”Concept sets” mode

A concept set is a group of standard concepts gathered around the same clinical reality (e.g. Heart rate, Creatinine), with expert notes attached: definition, included/excluded concepts, mapping rules. It guides you by narrowing the choice to candidates already validated for that category, instead of trawling the millions of ATHENA concepts.

You browse the concept sets linked to the project (those imported from the Target Concepts tab), sorted and filtered by Category, Subcategory and name. The Items, Version and Provenance columns are hidden by default.

The ⓘ icon opens a side sheet detailing the concept set: expert-written description, usage statistics, resolved concepts and the raw expression. That’s where you find the mapping rules — e.g. “map plain HR to the generic concept, not the pulse-oximeter variant”.

Click a row to open the concept set in the main pane: the top bar shows its name, category and concept count. You see its resolved concepts, navigate via search and column filters, and pick the one that matches. Concepts already mapped to the source concept appear greyed out.

This is the fast and focused mode when your source concept belongs to a clinical category already covered by a reference concept set.

”Search” mode

Type a name, code or numeric ID and Linkr queries the ATHENA reference loaded into the project. Like the source-concept search, it combines exact match (on the ID), substring (every word in the query), and fuzzy (Jaro-Winkler ≥ 0.8) — useful for typos and spelling variants. Results are ranked by relevance.

The filters button (icon on the left of the search bar) opens a popover to restrict the search to specific vocabularies, domains, concept classes or standard concepts only. You also set the max result count there (default 1,000; over 10,000 will slow the browser).

Target concept sheet

The ⓘ icon at the end of a row — available in both Search and Suggestions modes — opens a side sheet detailing the OMOP concept: its properties, its relations (Maps to, Has component, Has method…), its ancestor/descendant hierarchy, and its synonyms. Essential to confirm a candidate is standard, current, and that its position in the hierarchy matches your source code.

”Suggestions” mode

You browse pre-computed candidates for the selected source concept, ranked by combined score. Each row exposes the per-method scores (Syntactic, Semantic, Statistical, AI) as colour-coded dots, and a Manage suggestions button lets you import the scores file, tune the weights, or wipe everything.

These scores are not computed by Linkr: they come from a .parquet file produced by the Claude concept-mapping Skill, run outside the app on the ZIP export of your project.

Action bar

The action bar is only visible when a source concept is selected on the left. Its content changes depending on whether a target concept is selected on the right.

Map

When a source concept and a target concept are both selected, two elements appear:

• Green “Exact” button (SKOS badge, with dropdown arrow ) — a direct click creates the mapping as skos:exactMatch. The arrow opens a menu to pick another equivalence (Close, Broad, Narrow, Related); the button badge then changes colour accordingly.
• button (Map with comment) — opens a dialog where you pick the equivalence and type an explanatory comment.

The mapping is created immediately with status Unchecked, ready to be validated in the Evaluation tab.

Ignore

When a source concept is selected but no target concept is, the action bar switches to the ignore buttons:

• “Ignore” button — marks the source concept as having no standard equivalent. It leaves the count of concepts to map and appears in the “Ignored” KPI on the project dashboard. If the concept is already ignored, the button reads Remove ignored status.
• button (Ignore with comment) — same action, with a dialog to explain why (e.g., “admin identifier with no clinical meaning”).

Choosing the SKOS equivalence

Linkr uses the SKOS (Simple Knowledge Organization System) W3C standard to qualify how strong a mapping is. SSSOM exports (Simple Standard for Sharing Ontological Mappings) consume the same predicates. Five levels, from most precise to broadest:

Practical rule: if you hesitate between Exact and Close, prefer Close and add a comment — a reviewer can escalate to Exact during evaluation. Avoid Related unless no other equivalence fits: OMOP exports (source_to_concept_map) treat all levels the same, but a Related in an SSSOM export signals to partners that the mapping is weak.

See also the Mapping section of the SKOS Primer for the W3C examples.

Multiple mappings

A single source concept can have multiple mappings to different targets. This is common when distinguishing the value, unit and instrument of a single measurement (e.g., maps_to, maps_to_value, maps_to_unit in OMOP nomenclature). Just re-select the source concept and map again; extra mappings stack and appear together in the Evaluation tab.

Workflow summary