Skip to content

Governance and handoff

The pipeline works. Now make it survive the person who built it leaving, and make it defensible to the people responsible for the data.

ETL documentation that survives turnover

The test is specific: could a competent person who has never seen this project reproduce your instance from your documentation and your code, and get the same answer?

If the answer depends on asking you a question, the documentation is incomplete, and the incompleteness will become visible at the least convenient time.

What has to be in it:

Section Contents
Source description What system, what population, what date range, how the Group was defined, what access mechanism
Acquisition Export parameters, resource types requested and received, manifest handling, incremental strategy
Coding policy Which coding is chosen from a multi-coding CodeableConcept, and why
Status policy Per resource type, which status values load and which do not, with counts
Table-by-table mapping Field by field, with the source path and any transformation
Visit construction The rule, with numeric parameters, and the collapse ratio observed
Observation period The derivation rule and what it does and does not represent
Imputations and defaults Every one, with the rule and the affected row count
Local mappings Reference to the reviewed mapping file, with reasoning and confidence
Vocabulary Version, load date, and upgrade policy
Known gaps Resource types absent, elements unpopulated, tables intentionally empty
Quality results Latest Data Quality Dashboard run, with an annotation on each expected failure

Rabbit in a Hat produces a structured ETL specification document and it serves well even when the source is FHIR rather than a relational database, because the output format is familiar to OHDSI reviewers.

The conversation with the data steward

At some point someone accountable for the source data asks what you did to it. That conversation goes better with preparation.

What they usually want to know:

  • Did the data leave the environment it was authorized to be in?
  • Are direct identifiers present in the instance, and where?
  • Who has access, and how is that access reviewed?
  • Can a person be re-identified from what you built?
  • If a person withdraws consent, can you find and remove their data?
  • What happens to the instance when the project ends?

The re-identification question deserves a real answer rather than a reassurance. An OMOP instance without direct identifiers is not de-identified in any strong sense. Dates of service, postal codes, rare diagnoses, and unusual event sequences are all quasi-identifiers, and a OMOP CDM instance is rich in all four. Whether your instance meets a given de-identification standard is a determination someone qualified should make, and the honest framing is usually "limited data set" rather than "de-identified".

The withdrawal question is the one most often unprepared for. Removing a person from an OMOP CDM instance means removing them from every clinical table, from any derived era tables, from cohorts already generated, and from any downstream extracts. The person_source_value mapping is what makes this possible at all. Design for it before you need it.

Access and change control

Access. Who can query the instance, at what granularity, is a governance decision with a technical implementation. Row-level access, column-level restriction on NOTE and identifier columns, and query logging are all reasonable depending on sensitivity.

Change control. An OMOP CDM instance that changes without notice breaks reproducibility. A study run in March against an instance that was reloaded in April cannot be reproduced. Options are versioned snapshots, an append-only history, or a documented reload schedule with advance notice. Pick one and tell your users which.

Vocabulary upgrades are a change. They alter mappings, which alters cohorts, which alters results. Treat them as a versioned event with a diff, not as routine maintenance.

Working with people with lived experience

If your instance covers a condition with an active advocacy community, that community has expertise your project needs and is frequently consulted too late or not at all.

Where their input changes technical decisions:

Unmapped codes. Someone who knows the condition can tell you whether a code that failed to map represents something clinically important or an administrative artifact. That judgment is not available from the vocabulary alone, and it is exactly the judgment that determines whether a rare condition survives the transformation.

Which distinctions matter. A clinical distinction that looks minor from the outside may be the difference between two disease subtypes with different natural histories. Collapsing it in a mapping decision destroys the ability to study it.

Which outcomes to capture. Registries and instances built without community input reliably capture what is easy to code and miss what people actually care about.

Whether the governance is acceptable. Communities that have been researched extensively without benefit have well-founded views about data use, and those views are more usefully heard during design than after.

For rare disease work particularly, the practical point is concrete: the standard vocabularies have uneven coverage of rare conditions, unmapped codes cluster there, and a pipeline that silently drops unmapped codes deletes the rare disease population from an instance that otherwise looks complete. Someone who lives with the condition or advocates for it will notice that when a general reviewer will not.

The handoff checklist

Before you consider a pipeline finished:

  • [ ] ETL documentation complete enough that a stranger could reproduce the instance
  • [ ] Code and mapping files in version control, with the vocabulary version pinned
  • [ ] Raw layer retained, with a documented retention period
  • [ ] The person_source_value mapping stored securely and backed up
  • [ ] Surrogate keys deterministic or persistently mapped, so a reload does not renumber people
  • [ ] CDM_SOURCE populated, including a real description paragraph
  • [ ] Data Quality Dashboard run, with every expected failure annotated
  • [ ] Achilles characterization reviewed by someone who knows the population
  • [ ] Clinical review of a record sample completed
  • [ ] Resource-to-row reconciliation report generated
  • [ ] Unmapped code report generated, with the top codes triaged
  • [ ] Withdrawal procedure defined and tested
  • [ ] Reload and vocabulary upgrade policy documented and communicated
  • [ ] A named person responsible for the instance after you

That last item is the one most often left blank, and it is the one that determines whether the other thirteen stay true.

Next