The tools¶
Five interactive tools, all free, all running entirely in your browser. Nothing you type is uploaded anywhere, which means you can use them during a working session without thinking about where the data goes. It also means that closing the tab clears your work, so use the download buttons where they exist.
Three of the tools are for practice. Two are for real work.
For practice¶
Domain Detective¶
Twenty routing cases, one at a time. You see a source code and its context, and you choose the OMOP table it belongs in. The tool then shows the concept lookup chain that produces the right answer, along with a short explanation of the reasoning.
The cases are chosen for the places where intuition fails. A family history code that looks like a condition. A numeric result that belongs in OBSERVATION rather than MEASUREMENT. A local code with no standard concept. A refuted diagnosis. By the end you will have made most of the routing mistakes it is possible to make, in a setting where they cost nothing.
Use it when: you have read Domain routing and want to know whether it stuck.
Time: about fifteen minutes for a full pass.
Field Mapper¶
Six fill-in-the-blank drills, one for each of the tables you will build most often: PERSON, VISIT_OCCURRENCE, CONDITION_OCCURRENCE, MEASUREMENT, OBSERVATION, and DRUG_EXPOSURE.
Each drill shows a FHIR resource as JSON above a table of OMOP CDM columns. You choose the source for each column from a dropdown. Check your answers to see hints on the rows you missed, or reveal the whole thing if you would rather read than guess. Every drill closes with a short note on what the mapping loses, gains, or assumes, because a column-by-column mapping that ignores that question is a lookup table rather than an understanding.
Use it when: you are working through the Transformation unit and want to test one table before moving to the next.
Time: five to ten minutes per drill.
Bundle Reader¶
Paste a FHIR bundle and see where every resource in it would go, before you write any code.
For each resource the tool predicts a destination table, then flags the things a careful engineer would notice: a birth date with no month, an encounter with no end, a status that inverts clinical meaning, a quantity with no UCUM code, a code from a local system. Flags come in three severities, so a bundle producing four notes and no stops is in a different state than one carrying a refuted condition.
Five exercises are built in. Each loads a bundle and asks one question before you press Read it, so you commit to an answer rather than reading the output and nodding along.
| Exercise | What it teaches |
|---|---|
| R. Alvarez | The running example, with six deliberate problems |
| Status and routing | Refuted, entered-in-error, and family history in one bundle |
| The quiet failures | Missing units, comparators, components, absent values |
| Medication provenance | Why one column decides whether adherence is answerable |
| HL7 discharge summary | A real specification example in R6 ballot syntax |
That last one is taken from the FHIR specification itself and is worth doing carefully. It uses medication.concept rather than medicationCodeableConcept, and actualPeriod rather than period, which is exactly how an R4-era parser produces drug rows with no concept and visits with no dates while raising no error at all. The tool reads R4, R5, and R6 syntax and labels which one it found.
The reader closes with a short section on what the bundle cannot give you no matter how well you map it, which is usually the more useful half.
Use synthetic data only. The tool does not upload anything, and there are no network calls of any kind, but a browser tab is not a controlled environment. For real records, press Download this tool and run the single HTML file offline in whatever environment your governance requires. It behaves identically with the network disconnected.
Use it when: you are about to scope a new source, or you want to show a colleague what the transformation is actually deciding.
For real work¶
Crosswalk Builder¶
Build the field-level mapping for eight OMOP CDM tables, with a column beside each row for what you assumed. Suggested FHIR paths are one click away, required columns you have not mapped stay highlighted, and the export is markdown you can paste straight into a repository or a protocol appendix.
The assumption column is the reason this exists. Most mapping specifications record a source path and stop, which is enough to write the code and not nearly enough to defend it eighteen months later when someone asks why the visit counts do not match the source system.
Use it when: you are scoping a real pipeline and need a specification you can circulate.
ETL Decision Log¶
The companion to the builder. Where the builder records what maps to what, this records the judgment calls: how you constructed a visit, how you derived an observation period, which condition statuses you excluded, what you did with codes that had no standard concept.
Each entry has four parts. What you did, why you did it, what it costs a future researcher, and how many rows or people it affects. That third field is the one people skip and the one reviewers read first.
Eighteen common decisions are pre-loaded with a starting point for the reasoning, so you can adapt rather than start from an empty box. The export sorts entries by their effect on what the data can be asked, and it reads like documentation rather than a form.
Use it when: you are building, not after. The reasoning is legible for about a week and then it is gone.
A note on how these fit together¶
The three practice tools teach the same material the written chapters teach, in a form that fails fast. Reading about domain routing and doing twenty routing cases produce different kinds of knowledge, and the second one is what survives contact with a real source.
The two work tools produce artifacts. If you use both on a real project, you finish with a mapping specification and a decision log, which together are most of what a data quality reviewer, an IRB, or a collaborating site will ask you for. They are also most of what you will want yourself when a study team asks a question the instance cannot answer and you need to explain why.
None of the tools require an account, a download, or an internet connection after the page loads. Save them locally if that is useful. They are single files with no dependencies.
These tools are not OHDSI tools¶
Everything here is a teaching aid I built for this curriculum. The community maintains the real ones, and you should use those for production work: ATLAS for cohort definition, Usagi for source code mapping, the Data Quality Dashboard for checks, Achilles for characterization, and Athena for the vocabularies.
What these five add is the step before that: understanding what your decisions cost, in a setting where being wrong is free. Once you are building for real, the OHDSI tools are better instrumented, better tested, and maintained by more people than me.