A pattern encyclopedia for clinical analytics: adding context, time and uncertainty on top of existing EHR data
By [author name]. Written for clinical health informatics readers.
Most EHR data reaches analysts as flat labels: a diagnosis code, a drug code, a date. The clinical reasoning that produced those labels, such as how the diagnosis changed, which qualifiers applied and how sure anyone was, is mostly lost. This article explains the reasoning behind a design for the Vibe Rounds clinical analytics app: a clinical pattern encyclopedia that sits on top of data an institution already has, expresses clinical knowledge in plain English and in machine-readable form, runs it with deterministic code, and attaches explicit labels for uncertainty to every result.
Status. The analytics engine, terminology tools and review workflows described in section 7 exist in the app. The encyclopedia itself is a design plan that has not been built yet. Where this article describes planned work, it says so.
1. The problem: a diagnosis that does not stay still
A patient arrives and is given a diagnosis. Qualifiers are added. The diagnosis is refined, sometimes replaced. Other departments join, each with its own vocabulary: pathology describes morphology, radiology describes imaging findings, primary care describes syndromes. Complexity grows with every handover.
A single code at the end of the episode cannot hold this story. Yet the questions analysts and researchers ask later often depend on exactly the lost detail: which side, how severe, confirmed or only suspected, treated or not, and in what order.
2. What SNOMED CT gives you, and what it does not
SNOMED CT is a clinical terminology, not a patient database. It contributes three things that matter here.
- A hierarchy built on description logic. Concepts are linked by is-a relationships, so a query for a parent concept can include every child. A record coded with a specific disorder is still found by a query for its broader category.
- Post-coordination. When no single concept captures the clinical meaning, a concept can be combined with attribute-value pairs such as finding site or laterality. The Machine Readable Concept Model (MRCM) defines which attributes may attach to which concepts, which in principle prevents impossible combinations.
- History of the terminology itself. Retired or replaced concepts carry historical associations, so old records stay interpretable across releases.
What SNOMED CT does not do is store a timeline. How a diagnosis moves from suspected to confirmed to resolved, who changed it and when, is the job of the record model. In FHIR, for example, the Condition resource has fields for clinical status, verification status, severity, body site, onset and abatement. SNOMED CT supplies the meaning of the values; the record structure supplies the time and the status.
3. Where context gets captured
Context can be added at three points, and they are not equal.
- At the point of care. The clinician chooses qualifiers in the interface and the system builds the structured record. This is a deterministic assertion: the clinician said it.
- At mapping time. A terminologist maps local codes to concepts or expressions when legacy systems are connected.
- Retrospectively, in an analytics layer. Code, rules or models read what exists and reconstruct context afterward. This is inference, not assertion. If laterality was never recorded, no reconstruction can supply it.
Two storage choices follow. One is to store post-coordinated expressions as strings. The other is to decompose them into dedicated fields, such as body site, severity and verification status. Decomposed fields are far easier to index and query in a relational database without a live reasoner, which is why many pragmatic designs prefer them.
A subtler problem is where the terminology ends and the data model begins. Is “suspected acute appendicitis” one concept, or appendicitis plus a verification status plus an acuity? Two hospitals can make different choices, and both can be standards-compliant. The result is data that can be exchanged but whose clinical context is not interoperable. Documentation habits add another layer: if a screen makes qualifiers easy to record, one site looks sicker than another simply because it recorded more detail.
In practice, ontology-driven data entry, where the terminology itself decides which qualifiers the form asks for, is uncommon in routine clinical systems. Most deployments use templates and value sets that informaticists maintain by hand, which keeps screens predictable and fast. Specialized platforms built on FHIR questionnaires with a terminology server, and openEHR systems built on archetypes and templates, can enforce more structure, but they bring their own cost: dedicated repositories, a different query language and substantial modelling work before the first screen exists. They are powerful and heavy.
4. Two halves of one problem
The central insight of this design is that the problem splits into two parts that need different treatment.
Representation is translating clinical meaning into a machine-readable form. It is an engineering problem. With good terminology, careful profiling and validation, it is solvable.
Epistemics is about what kind of knowledge a record holds. A serum creatinine value is a measurement. “Acute-on-chronic kidney injury secondary to sepsis” is a clinician’s synthesis that may be revised tomorrow. A working diagnosis is not a confirmed one. Two skilled clinicians document at different levels of detail. No amount of better representation removes this. It has to be carried with the data and shown to the reader.
Many systems solve the first half and silently ignore the second. This design treats both as first-class.
5. The middle-module idea
Waiting for every EHR to redesign its screens is not a plan. The alternative is a module that sits downstream of the existing registry, reads the data already there and adds meaning afterward. It needs no change to clinical workflow and works on historical data, which makes it backward compatible until systems capture richer context at source.
The cost is honesty about what retrospective work can do. It is reconstruction, not assertion. So every reconstructed element needs provenance and a label that says how it was obtained. Section 10 describes those labels.
A custom study pipeline solves one question at a time. The step proposed here is to make the knowledge reusable: an encyclopedia of patterns, each stored, reviewed and runnable, in the way a terminology stores concepts.
6. Temporality: code instead of CQL, for now
Clinical Quality Language (CQL) is the standard for expressing clinical logic with time, such as “within 30 days after discharge”. Its strengths are real: portability between systems, the ability to run published quality measures, and interval operators designed for clinical time. Its costs depend on the setting. CQL is translated to an intermediate form and executed by an engine that usually evaluates one patient at a time, which adds toolchain and can be slow for population analytics.
Vibe Rounds takes a different route. FHIR data is imported into PostgreSQL tables, grouped in batches and populations, and temporal logic is written as set-based SQL with an explicit as-of date. The existing analytics already compute time windows, first and last events, time to event, 30-day readmission, medication fill intervals and persistence, and landmark study designs.
The decision for now is to stay with SQL and to keep the new pattern specification declarative and small, so it can later be exported to a standard format. What is given up is the ability to run third-party measures as written. If that becomes a requirement, an import path can be added.
7. What the app already does
The encyclopedia is designed to reuse existing parts, not replace them.
- Data and scope. Imported FHIR resources live in per-batch PostgreSQL tables. Populations, batches and saved cohorts define the scope of every analysis.
- Data-quality levels. The analytics catalog runs in five modes, from text matching only, through source codes, to codes with time and reviewed enrichment. A reader can see how much each result depends on code quality.
- Dictionary and hierarchy. A dictionary can be built from the codes actually present in the imported data. A separate hierarchy of is-a links can be loaded from a bundled demo set, a CSV file or real SNOMED CT release files. A query builder uses it to include descendants or ancestors. The dictionary alone does not create hierarchy; the loaded links do. Today only the query builder and cohort criteria use hierarchy.
- Reviewed enrichment. Free-text entries can be proposed codes by a model, then approved, edited or rejected by a person. The record keeps assertion (confirmed, suspected, negated), confidence, model, prompt version and reviewer.
- Guardrailed AI. A study-planning feature lets a model propose analyses from aggregate counts only. The server rebuilds every proposal from a fixed list of templates and drops unknown codes. A read-only SQL guard protects free-form queries.
- Exploration and trace. Care pathways, a patient explorer, a cohort knowledge graph and an audit log, including a class for requests sent to an external model.
Two limits matter for what follows. First, resolution dates, medication end dates and stop reasons are not extracted as fields, so they cannot define a pattern yet. Second, the app does not capture post-coordinated qualifiers at entry; it works with what the source data contains.
8. The pattern encyclopedia
An entry has four parts: a plain-English statement, a machine-readable specification, epistemic labels, and a review state. Entries are data, so adding knowledge does not require adding code.
The specification uses only things the app can already compute.
- Value sets. Named sets of codes for conditions, medications, labs or procedures, either exact codes or a concept with its descendants, taken from the loaded hierarchy.
- Events. For example, the first diagnosis from a value set, or the first fill of a drug on or after it.
- Time relations. A short, fixed list: within a number of days, before, after, none in a window, no refill after the supply ends plus a grace period, return within a number of days, latest value in a window, and at least a number of occurrences. These mirror logic the analytics already run. Anything outside the list is rejected.
- Needs. The fields a patient must have to be evaluated.
The executor is ordinary code. It turns a validated specification into parameterized SQL over the same scoped views the analytics use. No model text ever enters SQL. A patient who lacks the needed dates is reported as “cannot evaluate”, with the reason, and is never silently counted as “no match”. Small groups are hidden using the same minimum-cell rule the care-pathway feature uses.
Three ways to create a pattern
All three produce a draft that a reviewer must approve before it can run on a full population.
- From one case. A clinician picks a patient. Code abstracts the case: identifiers, names, birth date and address are removed, dates become day offsets from the first event, age becomes a band, and free-text narrative is dropped. A draft specification is built from the ordered events. A model may be used only to word the plain-English statement, and only if an explicit setting allows it and the request is audited. A single abstracted case can still be identifying when the combination of events is rare, so this is a policy decision as much as a technical one.
- From a few cases. Code finds the codes shared by most selected patients, including descendants when a hierarchy is loaded, together with their usual order and the range of days between events. Only these aggregates are used, and groups below the minimum-cell rule are not summarized.
- From an external library. Patterns can be imported from a file in the app’s own format, which also allows export between deployments. Every imported pattern is validated and arrives as a draft. Converters from other formats, such as OHDSI cohort definitions or CQL, are future work.
9. Where AI fits
The model is a drafter and an explainer, not a source of numbers or diagnoses.
- It writes the specification as structured data, never SQL. A validator rejects unknown relations, fields and out-of-range values.
- Code choices come from candidate lists built from the app’s dictionary. The model may not invent codes.
- Every draft records the model, prompt version, time and source.
- A model can never raise certainty above “hypothesis”. Only a reviewer can.
- Counts come only from the executor. The explanation step may not add figures, and it must state the uncertainty labels first.
This follows a pattern the app already uses for study planning: the model proposes, the server checks, and only checked output reaches the user.
10. Epistemic uncertainty
Uncertainty lives at three layers, and each gets a few fixed labels now. A free list of tags is reserved so a broader structure can be added later without changing the specification.
Knowledge layer (the pattern). How well established is the clinical statement?
- Certainty: established (a guideline or consensus states it), supported (some studies or clear expert practice), hypothesis (plausible or seen in data, not confirmed), contested (sources disagree, and a note says how).
- Basis: guideline, literature, expert, observed in data, model suggested.
- Claim: descriptive (what usually happens), association (two things go together), causal (one is claimed to cause the other).
Data layer (each record). How firm is the fact in the source?
- Assertion: confirmed, suspected, negated (already in the app).
- Evidence: documented (a coded field in the source), derived (computed from dates and gaps, for example “stopped” meaning no refill), inferred (from text or a model).
Run layer (this result). Can this run be trusted as it stands? Code computes these from numbers alone.
- Thin: fewer eligible patients than a low-number limit, or matches below the minimum-cell rule.
- Gappy: a large share of eligible patients cannot be evaluated because data is missing.
- Weak hierarchy: the pattern uses descendants but only demo links, or none, are loaded.
Several rules keep the labels honest. Model drafts and patterns mined from cases start at “hypothesis”. “Established” and “supported” require a source note. A causal claim requires at least “supported”, otherwise it is rejected and the result is treated as an association. Suspected and negated records are not counted as confirmed unless the pattern says so. Every change of certainty is written to the audit log with who, when, from, to and why.
Every result carries three chips: knowledge, data and run. For example: Knowledge: hypothesis, observed in data. Data: 70% documented, 30% derived. Run: thin, gappy. A reader sees at a glance how much weight the result can bear.
11. A worked example
Take the plain-English statement: viral fever patients were given antibiotics for five days, but the illness resolved in three days, so they stopped the medication.
The sentence mixes three kinds of meaning. The concepts (viral illness, antibacterial drug) belong to the terminology. The timing (given for five days, resolved in three) belongs to temporal logic. The causal clause (so they stopped) is an interpretation that no database field can confirm.
In the app today there is no resolution date and no medication end date as fields. The pattern is therefore written with definitions derived from what exists:
- the illness is “resolved” when there is no further record of it within a window after the first diagnosis;
- the antibiotic is “stopped” when there is no refill after the supply period plus a grace period;
- the antibiotic starts within a few days of diagnosis.
The run reports how many patients match, how many could not be evaluated and why, and how much of the evidence was derived. The pattern is labeled as an association at the “hypothesis” level.
The reading of such a result needs care. A missing record does not prove recovery: the patient may have gone elsewhere, or the first diagnosis may have been wrong. That is why derived evidence and the claim type are shown next to the count, and why the explanation is limited to “is associated with”.
12. Limits and open questions
- Derived is not documented. Absence of a record is not absence of an event. Derived definitions should be replaced by documented fields when the data allows.
- Retrospective work cannot create context that was never recorded. The design reports gaps; it does not fill them with guesses.
- Hierarchy quality depends on what is loaded. Real descendants need a real terminology release, and its licence terms must be checked for the deployment’s country.
- Documentation bias remains. A pattern may look rare because one site rarely records the needed fields. A per-site completeness report is planned.
- Privacy of single cases is reduced by abstraction but not eliminated.
- Not decision support. Patterns are for exploration, research and review, not for guiding treatment.
- Prior art exists. Cohort and phenotype definitions in the OHDSI community already store concept sets with descendants and temporal criteria in a structured format. What this design adds is the combination: a plain-English encyclopedia, a validated compile-and-review loop, and uncertainty labels that travel with every result.
- It needs evaluation. Clinician agreement with drafted patterns, and the accuracy of derived definitions against documented ones, should be measured on real data.
13. Roadmap
The plan has six build phases, each small and tested on synthetic data:
- A pattern store and validator, including the uncertainty fields and their rules.
- An executor with three hand-written patterns, one checked against the existing readmission analytic, and computation of the run labels.
- Creation from one case.
- Creation from a few cases.
- Import and export of a library file.
- A review screen and a patterns tab showing the three chips on every result.
Future development covers: reading resolution, stop and status fields from the source, using the hierarchy throughout the analytics catalog, loading SNOMED attributes for constraint queries, hierarchies for drugs and labs, post-coordinated qualifiers as fields, pattern discovery from frequent sequences, converters for other pattern formats, other source formats such as openEHR, per-site documentation-bias reports, pattern sharing with versioning, and a broader uncertainty structure with graded evidence and listed supporting and conflicting sources.
14. Conclusion
The design rests on a simple separation. Terminologies such as SNOMED CT give machines a precise language. Record standards such as FHIR give that language a time and a status. A deterministic engine gives questions a reliable answer. And an explicit uncertainty layer keeps anyone, human or model, from mistaking an inference for a fact.
Building this as a middle module over existing data means the approach can start small, with a few patterns and a few dozen patients, and grow with the data and the institution. The most important feature is not any one pattern. It is that every result says what kind of knowledge it is, where it came from and how far it can be trusted.
Where feedback would help
- Are four certainty labels and three claim types the right size to start with, or are they too coarse?
- Which derived definitions, such as “resolved” or “stopped”, would your clinicians accept before documented fields exist?
- What would you need to see before trusting a pattern drafted from a single abstracted case?