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 (typically a table containing the concepts to map).
  • 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.

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.