Three lines from three different notes: no seizures, possible seizures, and father had seizures. Run them through a term matcher, and all three come back as HP:0001250, Seizure. Put that list in front of a clinical geneticist, and the first question is obvious. So, does this patient have seizures or not?
It gets worse at export time. In GA4GH Phenopacket Schema 2.0, the excluded field defaults to false. Forget to set it, and every one of those features goes out as observed. The file validates. The schema checks pass. And the phenotype now says something the note never said.
That is the real job of HPO phenotype data engineering. The vocabulary match is the easy part. The hard part is keeping track of who a finding belongs to, how sure anyone was, when it happened, and which sentence it came from. Only then can the team decide what each analysis should actually see.
Put simply, an HPO layer that holds up in production keeps the source assertion and its context, maps it against a pinned HPO release, and hands each consumer a versioned snapshot. The HPO identifier is one field among several. Subject, certainty, timing, and evidence have to travel with it, from ingestion through review and export.
The Human Phenotype Ontology supplies a standardized vocabulary for phenotypic abnormalities. That shared vocabulary makes features comparable across cases, which is why it sits at the center of rare disease research and diagnostics. The surrounding clinical context still needs a place in the data model.
Clinical phenotype normalization has to preserve the sentence
Start with what the output is supposed to say. This sounds like a small design decision until an analyst asks whether a missing term means not present, not assessed, or not extracted.
The following invented snippets illustrate six documentation situations. They are not patient cases or diagnostic recommendations.
| Documentation snippet | What the working record should preserve | What must not be inferred |
|---|---|---|
| Seizures documented in the patient. | Patient finding, source, and available timing | An onset age or seizure subtype that was not documented |
| No seizures at this assessment. | Explicit negative finding in its assessment context | Lifelong absence of seizures |
| Possible seizures; assessment pending. | Uncertainty and the need for clarification | A confirmed present feature |
| Father had childhood seizures. | The relative and relationship to the patient | Seizures in the patient |
| Seizures in infancy, resolved at age three. | Historical presence, onset information, and resolution | Either a currently active feature or a history with no seizures |
| Neurologic history unavailable. | Missing information | A negative neurologic assessment |
None of these distinctions can be recovered from an HPO identifier alone. A confidence score attached to the identifier does not tell the next user which meaning was lost.
Keep the source assertion, then derive the view the consumer needs. One algorithm may accept only present features. Another may use explicit exclusions and onset. Both can receive appropriate inputs without forcing the underlying clinical record into the limitations of either format.
This changes how quality should be judged. The proportion of mentions mapped to valid identifiers is useful, but it will not reveal how many relatives’ findings or uncertain statements became patient positives. Those errors need their own evaluation.
The working record behind HPO phenotype data engineering
The source document, the extracted mention, the interpreted assertion, and the phenotype snapshot each answer a different question.
The document tells the reviewer where the information came from. The mention points to the passage. The assertion records the meaning assigned to that passage. The snapshot records what an analysis actually received.
Keeping those records distinct gives the team somewhere to put a correction without losing the earlier evidence or silently changing an analysis that has already run.
A practical internal record needs the following context:
| Record element | Why it matters |
|---|---|
| Subject and experiencer | Distinguishes the patient from a relative or another person described in the record |
| Assertion context | Preserves presence, explicit absence, uncertainty, or missing information without collapsing them into one Boolean |
| Clinical timing | Keeps onset, assessment time, and resolution distinct from document and ingestion dates |
| Source reference | Identifies the document or resource version, section, and supporting passage |
| Candidate and selected concept | Preserves the original wording, proposed mapping, selected HPO identifier, and terminology release |
| Mapping provenance | Records the rule, model, prompt or template, or terminology service version used where applicable |
| Review and change history | Shows corrections, supersession, acceptance decisions, and the snapshot that consumed the assertion |
This is an internal design proposal. It is not a list of mandatory FHIR or Phenopacket fields. The team may use local review states such as candidate or needs clarification, but those labels should remain visibly separate from standard schema values.
Source references deserve some attention during ingestion. With OCR-derived text, retain the extracted-text version and a way to find the passage on the page. An offset into cleaned text will not necessarily locate the same characters in the PDF, and running OCR again may move the passage.
Reviewers also need appropriate access to the evidence. Being able to open a supporting passage does not require copying the full clinical note into every analytics table or application cache. Keep the source available through controlled access.
FHIR Condition and Observation require source-specific mapping
A structured feed is a useful starting point for FHIR to HPO mapping. It still needs to be read according to the meaning of its resources and fields.
In FHIR R4, Condition separates clinical status from verification status. A confirmed condition that later resolved has a different meaning from a condition that was refuted. Converting both records to the same phenotype status would discard information already present in the source.
Observation carries measurements and assertions, including values and clinically relevant timing. Its workflow status does not tell the mapper whether a phenotype is present. Final is not a positive finding, and dataAbsentReason explains why a result is missing rather than establishing that a phenotype is absent.
Read the code with the value and its context. A height measurement needs its unit and relevant reference information. One number is not enough to support a short-stature annotation without the information and approved interpretation required for that conclusion.
Relatives need particular care. FamilyMemberHistory represents significant conditions in relatives, but family-history statements can also appear in codes or narrative elsewhere. Inspect Observation.focus where applicable; in R4 it is a trial-use element, so confirm the source system populates it. A Patient reference does not establish that every finding described in the resource belongs to that patient.
The mapping has to be agreed against the profiles and fields the source actually supplies. EHRs need not expose identical resources, terminology, or detail. Notes, questionnaires, and referral documents may continue to hold information that the structured feed does not provide.
HPO phenotype mapping needs a versioned terminology service
Once the assertion is understood, the next job is to choose a supported concept and leave a record of that choice.
The mapper should resolve the phrase against an identified HPO release, return valid identifiers, and show where the candidate came from. An exact match, a curated synonym, a code mapping, and a model-generated suggestion should not arrive in the record looking like the same kind of evidence.
Specificity needs restraint. Use the most specific concept the documentation supports. If the note supports only a broad feature, a broad term is the appropriate result. Selecting a narrower subtype to improve a similarity score would add information that the clinician did not document.
Source codes need the same care. An ICD diagnosis, SNOMED CT concept, or LOINC-coded measurement should not be treated as having a universally equivalent HPO term. Retain the scope and dependencies of the mapping, including any interpretation involved. The service needs an honest way to return no suitable mapping or request review.
Historical mappings also need to remain understandable. The HPO consortium describes ontology and annotation updates as the resource develops. If every old record is resolved against today’s release, the team can lose the terminology context in which the original annotation was made.
Retain that release. An old label may have been valid then. An obsolete identifier should remain intelligible in the historical record, with a traceable decision for any replacement used in a new export. Updating the terminology service should not silently rewrite the original annotation.
The same principle applies beyond HPO. Record the mapping rules, extraction configuration, and review changes that produced a snapshot. Where prioritization uses disease-phenotype or gene-disease annotations, retain those versions separately from the patient assertions.
There is a good reason for that separation. If expected features of a candidate disease are used to fill gaps in the patient record, then scored as a match to that disease, the result partly reflects the system’s own inference. Documented findings and inferred expectations need to remain distinguishable.
Preserve clinical time, including findings that resolved
A note written today may be describing infancy. Its document date is useful provenance, but it is not necessarily the onset date. The ingestion date is another date again.
Give onset, assessment time, and resolution their own representation. Preserve the precision available in the source. In infancy, it should remain approximate rather than becoming an invented exact date. When timing is unknown, the first available note should not quietly become the onset record.
The Phenopacket PhenotypicFeature model supports onset and resolution alongside exclusion, severity, modifiers, and evidence. Those distinctions are useful when the documentation supports them and the receiving application can interpret them.
Take the earlier history of seizures that resolved at age three. It remains a history of seizures. A later statement that there are no current seizures should not erase it, while a query for currently active seizures should not automatically include the resolved feature.
Copied-forward text creates a separate problem. Ten notes carrying the same statement are not ten independent observations or ten onset events. Keep the sources, then apply documented duplication and clinical-context rules when deriving the analytical view.
Conflicting sources should stay visible until the relevant process resolves them. Choosing the latest timestamp is not a sufficient clinical conflict policy. Clinically consequential ambiguity needs appropriate review, and an amended source or an assertion entered in error needs a defined effect on future snapshots. Earlier analyses should still retain the history of what they used.
Give the phenotype data pipeline an explicit output contract
The question at the analytical interface is straightforward: what does this particular set of features represent?
For variant prioritization, it might be a reviewed set available at a stated clinical cutoff, with exclusions and onset included where supported. For cohort querying and analytics, the question might be whether a feature was ever documented, was present during a particular period, or was explicitly assessed as absent. Those questions need different views, even when they draw on the same assertions.
Give each snapshot an identifier and retain its source cutoff, inclusion rules, review policy, ontology release, and relevant transformation versions. An analysis can then point to the input it received rather than to a patient’s changing current HPO list.
Keep the time information became available separate from the period it describes. That distinction matters when reconstructing historical analyses or evaluating models against information available at the time.
The GA4GH Phenopackets standard provides a human- and machine-readable exchange model. The sending and receiving teams still have to agree which parts of that model the consumer understands. The same discipline sits behind the FAIR principles for genomic data: an exchange format only helps when both sides read it the same way.
Return to excluded, the field most likely to break a Phenopacket export. Leaving it unset must not turn an uncertain or unassessed mention into a present finding. Setting it to true is not a workaround for uncertainty either: it represents a feature assessed as absent. Keep unresolved mentions in the working store or use an explicitly agreed representation, rather than assigning a new meaning to the base field.
Some consumers accept only positive HPO identifiers. Document that limitation, provide the permitted view, and retain the richer record behind it. An export cannot claim to preserve exclusions or temporal distinctions that its format cannot carry.
For a cohort requested as patients without seizures, agree what qualifies. A documented negative assessment and a record with no usable seizure information are not interchangeable simply because neither produces a positive term in the export.
Evaluate the mistakes that matter to clinical users
A valid identifier assigned to the wrong person will pass a dictionary check. Evaluation needs to reach beyond the vocabulary.
Measure subject assignment, negation, uncertainty, timing, concept specificity, and source-link accuracy separately from overall term precision and recall. Otherwise, an acceptable aggregate score may conceal a category of false patient positives that reviewers would consider important.
AI-assisted deep phenotyping belongs under the same scrutiny. A 2025 deep-phenotyping study by Garcia et al. in Genome Medicine evaluated retrieval-augmented mapping on published case reports. Even in that setting, 19.1% of the terms it returned did not match the manual annotation. Those results apply to the evaluated setting; they do not guarantee performance on referral PDFs, copied problem lists, or another institution’s notes.
Local evaluation should reflect what the service will receive: the specialties, document types, formatting, sites, and relevant language variation. During development and evaluation, keep the same patients and near-duplicate note families from leaking across the data split.
Where generative AI proposes terms, constrain the candidates against the selected ontology release and retain the supporting passage and model configuration. Let the system abstain. Model confidence is not a clinical verification status, and unresolved clinically consequential cases need a route to qualified reviewers. Review policy should reflect the intended use and the consequences of error.
Corrections need to last. A reviewer should not fix a mapping only to have the next processing run replace it with the original suggestion. Preserve the amendment and its attribution. Where a correction changes a shared rule, regression testing should check its effect on other records before the rule is promoted.
Build the HPO layer as part of your clinical data platform
NonStop’s healthcare data engineering services cover ingestion, data modeling, orchestration, quality, metadata, and governed analytics. Its genomics data engineering services bring clinical records, phenotype information, and omic datasets together, and source adapters for HL7 v2 and FHIR R4 feeds draw on NonStop’s FHIR genomics integration work.
That work runs at real scale. NonStop’s published genomic data work covers 12.4 million variants across 8,320 samples spanning WGS, RNA-Seq, and proteomics, and 4,218 VUS across 3,102 patients re-evaluated at cohort scale.
For an HPO layer, the scope needs to name the source adapters, patient and relative context, assertion records, terminology versions, review interfaces, and analysis snapshots. Storing HPO identifiers does not establish that those behaviors are already implemented.
NonStop’s genomic analytics platform describes HPO integration for phenotype-driven prioritization. The layer discussed here provides the contextualized input for that analysis. Phenotype similarity supports review; it does not, on its own, establish a diagnosis or a final variant classification.
The interpretation decision has a further evidence and approval history. NonStop’s discussion of variant knowledge management covers that responsibility separately. The phenotype service should supply the input without quietly taking on classification decisions.
NonStop’s forward-deployed engineering model supports implementation and handover within the client’s environment. For phenotype data, the working relationship between data engineers, clinical-data owners, and downstream analysts is essential: they need the same understanding of what the output means before production use.
That is the useful starting point for the project. Agree which evidence the input represents, which uncertainty it keeps, and which changes require a new snapshot. The implementation can make that agreement executable while clinical assessment and the decisions based on it stay with the qualified professionals responsible for them.
Questions precision-medicine data teams ask
How do you build an HPO layer for clinical phenotype data?
Retain the source assertion and its context, map supported concepts against a controlled HPO release, and produce versioned outputs for defined consumers. The record needs the subject, polarity, uncertainty, timing, evidence, and review history, not only a list of identifiers.
Should every diagnosis or lab code be converted to an HPO term?
No. Use HPO for supported phenotypic concepts while preserving the original diagnoses, measurements, units, and terminology. Where the mapping requires context or qualified interpretation, make that dependency explicit rather than forcing every code or sentence into an HPO term.
What does excluded mean in a phenopacket?
In Phenopacket Schema 2.0, excluded set to true means the feature was looked for and found to be absent. The field defaults to false, so a feature with excluded left unset is read as observed. An uncertain or unassessed finding should not be exported either way.
How accurate are LLMs at assigning HPO terms?
Accuracy depends heavily on the setting. A 2025 Genome Medicine study of retrieval-augmented mapping on published case reports still found that 19.1% of returned terms did not match the manual annotation. Local evaluation on your own document types is the only reliable guide.
How do you map FHIR data to HPO terms?
Map each resource type on its own terms. Preserve Condition verification and clinical status, and interpret Observation codes and values together. Check timing and the actual person or focus described so the shared output keeps the distinctions that matter clinically.
What should buyers expect from an HPO data platform?
Ask how it handles explicit negatives, uncertainty, family history, resolved findings, copied text, terminology changes, and reviewer corrections. Establish what the phenotype snapshot supplied to genomic analysis represents and whether its provenance explains why each feature was included.

Mahendra works as a Sr. Bioinformatics Engineer at NonStop. He builds genomic pipelines, agentic AI systems, and AI-powered products for genomics and life sciences. He has 10+ years of experience in bioinformatics and genomics software. He studied Biotechnology at Mumbai University.

