Mapping projects

Project list

Each project shows up in the list as a card with the key information:

• Name — short project label (here MIMIC-IV lab data).
• Source — connected database or imported file (spreadsheet icon + filename).
• Badges — colored free labels to group projects (by hospital, team, study…). A project can carry several.
• Status — colored pill: In progress (blue), On hold (amber) or Completed (green).
• Progress — bar showing mapped / total, with the approved count in green above.

Creating a project

Click New mapping project at the top of the list. A dialog opens:

You fill in:

• Name (required) and a technical identifier (a slug used in the URL and exports, auto-generated from the name).
• Description of the scope.
• Initial status — three options, usually In progress at creation:
  • In progress — active work. Most projects sit here.
  • On hold — paused (waiting on validation, data, etc.).
  • Completed — mapping done and exported. Keep for traceability.
• Badges — colored free labels to group projects (by hospital, team, study…). Pick a colour, type a label, confirm. Multiple badges allowed. If other projects in the workspace already use badges, they’re suggested for reuse.
• Source type — toggle button:
  • Source database: pick a database already connected to your workspace. Its concepts are then extracted from the Source Concepts tab (see below).
  • File import: drop a .csv, .tsv, .txt, .xlsx, .xls or .parquet file. A second settings page appears automatically (see below).

Import settings (file only)

For file sources, a second page of the dialog appears:

Two blocks to fill in (a third one, the Preview, is computed automatically by Linkr and lets you verify that parsing is correct):

Parsing options

Linkr provides sensible defaults that work for most files; tweak as needed:

• Delimiter — auto-detected by default. Can be forced to comma, semicolon, tab or pipe.
• Encoding — UTF-8 by default. ISO-8859-1 or Windows-1252 available for older Excel/Windows files.
• Skip rows — useful if the file has decorative headers before the actual first row.
• Header row — Yes if the first row contains column names (standard case).

Column mapping

For each column in your file, indicate what it represents:

• Vocabulary * — name of the source terminology, usually local (e.g. ICCA for codes from the ICCA ICU software, Labs for the laboratory system…). Used to filter by vocabulary later.
• Category — grouping present in the source system (e.g. lab parameter family, prescription type, clinical specialty…) that helps identify concepts and chunk the work.
• Concept code * — source code of the concept, e.g. itemid in MIMIC.
• Source concept ID — numeric ID matching the source_concept_id used in the OMOP ETL (source_to_concept_map table). Fill it in if your file already has one; otherwise Linkr can generate one automatically in the OMOP custom range (see Overview).
• Concept name — label of the concept, e.g. label in MIMIC.
• Record count / Patient count — frequencies observed in the source database. Very useful to prioritise the most common concepts.
• Info (JSON) — column with JSON metadata (distributions, statistics) shown in the detail panel. The expected structure is detailed on the Mapping Editor page.
• Extra columns — any other columns you want to keep as free-form metadata.

* required.

Extracting the concepts of a database

For a project on a source database, Linkr does not read the concepts to map straight from the database: it extracts them once, from the project’s Source Concepts tab. Until something has been extracted, the Mapping Editor shows “Source concepts not extracted yet” and a Go to Source Concepts button.

The reason is volume. Counting each concept’s records and patients, or computing its distribution, scans the clinical tables — on a warehouse of several hundred million rows, that takes minutes, even hours. The extraction does this work once; from then on, the editor, its sorting and its filters read a local table and answer at once.

Options

• Concept dictionary — the schema’s concept tables to extract. All of them by default.
• Compute concept metadata — when off, Linkr only copies the list (codes, names, categories), with no counts and no profile. Much faster.
• Only concepts present in the data — on by default. Skips the dictionary concepts that no record uses. On OMOP, the dictionary is the whole concept table: hundreds of thousands of concepts, of which only a small share appears in your data.
• What to compute for each concept — the blocks of the profile: record and patient counts, completeness, value statistics and distribution, unit, distribution over time…
• Screen first and Order — the order concepts are extracted in. By default, Concepts with the most records, Largest first: if you pause, you already have the most frequent concepts.
• Minimum patients and Minimum occurrences per value — confidentiality thresholds. Below the first, a concept keeps its counts but gets no profile; below the second, a categorical value is left out.

When the database links one dictionary to several event tables — on OMOP, measurements, drugs, conditions, procedures… — each concept is counted and profiled in the table holding most of its records.

Start, pause, resume

Click Start extraction. Progress is counted in concepts and saved as it goes: Pause at any point, then Resume, even days later. The concepts extracted so far are available in the editor at once. Start over runs the extraction again from the beginning, Discard deletes it; either way, the mappings you have already made are not affected.

The result is a table of concepts identical to an imported file: it travels with the project on export and git sync.

ZIP import / export

Two actions, in two different places:

• Import — button above the project list, to load a Linkr ZIP file (typically a project exported from another instance or shared by a colleague).
• Export — on each project card, via the … icon at the top right.

The ZIP format is detailed on the Export page — it contains entity.json (the project’s identity record), all mappings, the source concepts, the README and the licence. The SSSOM, C/CR and Usagi files are not in it: they are derived from the mappings and obtained from the Export tab. The ZIP re-imports as-is.