In short
This page answers one question: what is actually in this database? It browses the connected database’s dictionary — whatever its model — and gives, for each concept, how many records, how many patients and the distribution of its values. The concepts you keep gather into a concept list that travels with the project.
Knowing what you have before looking for it
A health warehouse describes thousands of possible concepts. Your database holds only a fraction of them, and nothing says in advance which: an ICU warehouse will have ventilation and vasopressors in abundance, and almost nothing in oncology.
Hence the order of operations. Before writing a cohort criterion on “lactate”, you need to know whether lactate is present, under which code, how many times, and with what values. That is what this page gives you.
The database’s dictionary
The page imposes no data model. It reads the dictionary table — or tables — that the database’s schema declares, and adapts to what it finds there.
An OMOP database
The concept table: identifier, name, code, vocabulary, domain, class, standard status. The page shows every one of those columns.
A MIMIC database
d_items and d_labitems, often declared together. No standardized vocabulary, and d_items has no code column: those columns simply do not appear.
A home-grown model
Your own reference table. It only needs an identifier and a label; everything else is optional.
A database can have several dictionaries
When the schema declares more than one, the page brings them together and adds a column saying which dictionary each row came from. On MIMIC, that is how d_items and d_labitems are browsed as one.
With no dictionary declared, the page stays empty
It then reports that no concept table was found. It is the schema mapping that names that table — it must be declared before this page is of any use.
The table
One row per concept, with two columns that carry the page’s whole value:
- Records — how many times this concept appears in the database;
- Patients — how many distinct patients it covers.
The gap between the two is readable. Three hundred thousand heart-rate records for eight hundred patients is continuous monitoring. Eight hundred records for eight hundred patients is a single measurement on admission. The two are not analysed the same way.
The other columns depend on the dictionary: vocabulary, code, domain, class, validity. They resize, reorder by dragging, and hide.
When the model distinguishes a standard code from an original one
Some models, OMOP among them, record an event under two concepts: the standard one and the original source one. Linkr then counts both, and a concept appears in the counts whether it figures under one form or the other. So you do not miss badly aligned data. On a model without that distinction there is only one code, and the question does not arise.
Searching and filtering
Search covers the name, the code and the identifier, tolerating typos.
Search runs on Enter, not as you type
This is deliberate. A full dictionary can exceed a million rows: re-running a fuzzy search on every keystroke would make the page unusable. Type, then press Enter. Esc clears it.
A filter button gathers the dictionary’s filterable columns. Which ones, again, depends on the database: domain and class if the model declares them, vocabulary if it has one, and the Std status — Standard, Classification, Non-standard — on models that carry one.
A concept’s details
Clicking a row opens the right-hand panel: the concept’s metadata, then its statistics.
For a concept carrying a numeric value — a lab result, a vital sign — Linkr computes minimum, maximum, mean, median, standard deviation, and draws a histogram.
It is an immediate quality check. A creatinine averaging 1.2 is in mg/dL; averaging 105, in µmol/L. A weight reaching 7,000 signals grams mixed in with kilograms. These problems are visible on the histogram in seconds, and cost weeks when discovered after the analysis.
Exclude outliers to read the chart
A single absurd value flattens the whole histogram. The Exclude outliers option clips it to the 1st–99th percentiles. Use it to read the distribution — but the outliers themselves still need dealing with.
A button shows the SQL behind these statistics, useful to check what is being counted, or to reuse the query elsewhere.
Statistics can be turned off in the settings if you are browsing many concepts and want to move faster.
Building the list
Counting each concept’s occurrences across a whole warehouse is expensive. In server mode Linkr therefore computes these counts once and keeps them.
On a fresh database a banner says the list has not been built yet and offers to build it — an operation that can take a while on a large database. A Refresh button rebuilds it afterwards, showing the last refresh date.
Refresh after loading data into the database
The counts date from the last build. After new data is loaded by an ETL pipeline, the page still shows the old figures until you refresh.
Gathering concepts into a list
As you browse, you spot the concepts that matter to you: the six codes standing for mechanical ventilation, the four ways a creatinine is recorded. A concept list gathers them.
Select one or more rows, then + to add them to the active list. The dropdown beside it switches the destination list or creates one; the list icon opens its contents.
From that window a list can be renamed, emptied, and above all copied as SQL, R or Python. This is the biggest time-saver: your thirty ventilation codes land in a script without a single manual retype.
Copying by identifier or by code
Both are offered when the dictionary has a code column. When it does not — d_items on MIMIC, for instance — only the identifier is available: copying codes would produce nothing but empty strings.
A list travels with the project
It is exported, versioned and shared with it. The work of finding those concepts — often several hours — therefore passes to whoever takes the project on, instead of being redone.
Concept list and concept set: two different things
The names look alike. They do not play the same role.
Concept list
Yours, built by hand.
Attached to the project. You fill it while browsing the table, you change it at will, and it leaves with the project.
Concept set
Imported, read-only.
Comes from a data dictionary installed in the workspace — a reference published by a research network. Shared by every project.
Put differently: a concept set is a reference you receive, a concept list is a selection you produce.
Enriching the table with a reference
The page’s settings let you import a data dictionary — not to be confused with the database’s own dictionary, which comes from the schema. This one is an external reference: its concept sets appear as extra columns — name, category, subcategory.
Matching is done on the concept’s vocabulary and code. Those columns are therefore only offered if the database declares both.
The benefit: you see immediately that a concept belongs to the “inflammatory markers” group defined by the reference, without having to know it. The concept set’s name is clickable and opens its details.
The reference is shared by the whole workspace
The page holds only one at a time, and Replace swaps it for another. Since concept sets are shared with every project in the workspace — including concept mapping projects — that replacement affects them all, and cannot be undone. The old one is only deleted once the new one has landed: cancelling the import breaks nothing.
A concept list does not yet fill a cohort criterion
A cohort criterion’s concepts are picked independently. For now a list serves patient data tracking and export into your scripts — not filling in a criterion.
Going further
- Schemas — declaring a database’s dictionary, without which this page stays empty.
- Cohorts — using a concept found here as a criterion.
- Concept mapping — matching your local codes to a standard terminology.
- Introduction to OMOP — one standard data model and its terminologies.