A pathogenic variant does not automatically explain the patient.
That distinction is easy to state and easy to lose in a genomic analysis workflow. Once a case contains thousands of variants, several kinds of evidence compete for attention: population frequency, predicted consequence, database assertions, inheritance, classification criteria and phenotype relevance.
A phenotype-matching service should answer one question:
How well does a gene represented in this case fit the patient’s recorded clinical features?
It should not silently answer a second question about whether the variant itself is pathogenic.
At Helena Bioinformatics, we implemented phenotype matching as a separate service within Folklore. The service accepts a reviewed set of Human Phenotype Ontology terms, compares them with phenotype annotations associated with genes in the case and returns results that remain open to inspection.
This article describes the architecture and the engineering decisions behind that separation. It does not disclose Folklore’s thresholds, scoring weights, prioritization rules or other proprietary decision logic.
Keep classification and phenotype relevance separate
Variant classification and phenotype matching operate on different evidence.
Classification evaluates evidence attached to the variant and assigns a class. Phenotype matching evaluates the relationship between the patient’s features and phenotypes associated with the gene.
The same finding can therefore have two different properties:
- strong evidence for pathogenicity;
- weak relevance to the referral phenotype.
The reverse can also occur. A variant of uncertain significance may be located in a gene that fits several specific patient features. That fit can justify closer review without changing the variant’s class.
Our service does not modify the classification produced by the variant-analysis layer. It adds phenotype relevance as a separate result.
This boundary is carried through the data model and the interface. The reviewer can inspect the variant class, the phenotype match, the contributing patient terms and the other evidence attached to the finding.
A phenotype result changes review order. It does not reclassify the variant.
The clinician owns the phenotype
Phenotype matching depends on the quality of the patient description.
A service can help search HPO terms by identifier, name or synonym. It can also extract possible findings from clinical text. Neither operation should silently define the patient.
Text extraction can fail in ordinary ways. A phrase may be negated. A historical feature may not describe the current presentation. A broad expression may map to a term that is too specific. A relevant feature may not be mentioned in the supplied text.
For this reason, Folklore treats extracted terms as proposals. The geneticist reviews the proposed terms and decides which ones belong in the case.
The workflow has a clear sequence:
- Search or extract possible HPO terms.
- Review, remove or add terms.
- Save the accepted phenotype for the case.
- Run matching against that accepted set.
The service stores the reviewed HPO terms and the clinical notes associated with the case. The phenotype can be updated later as the presentation becomes clearer.
A rerun uses the revised phenotype without altering the underlying variant annotation or classification. This makes it possible to refine the clinical question without rebuilding the entire case.
Literal matching is not enough
Exact HPO identifier overlap would miss many clinically related concepts.
A patient may have a broad recorded feature while a gene-disease annotation contains a more specific term. Two sources may describe related manifestations using different points in the ontology. Treating HPO terms as unrelated strings would discard that structure.
The service therefore resolves terms inside the ontology and compares their relationships.
The implementation uses information-content-based semantic similarity. The exact aggregation method used by Folklore is proprietary, but the general mechanism is established: terms that share a more informative common ancestor are treated as more closely related than terms connected only through a broad ancestor.
The practical work around the similarity measure matters as much as the measure itself.
The service must resolve valid HPO identifiers, handle missing terms, keep ontology-dependent calculations consistent and return a bounded result that the rest of the platform can consume. It must also retain enough detail for a reviewer to understand how the aggregate result was formed.
A number without that supporting detail is useful for sorting and weak for interpretation.
Retain the comparison beneath the score
For each patient HPO term, the service records the closest supported relationship found in the gene-associated phenotype set.
The result can therefore contain:
- the patient term;
- the closest gene-associated term;
- the semantic relationship expressed as a similarity value;
- the number of patient terms represented in the result;
- the number of phenotype annotations available for the gene.
This term-level representation is kept alongside the aggregate phenotype score.
That decision serves both clinical review and engineering diagnosis.
A geneticist can see whether several specific features support the gene or whether the result depends mainly on one broad term. An engineer can trace an unexpected result to the patient input, the gene annotations, ontology resolution or result aggregation.
Without the individual comparisons, those failure modes collapse into one unexplained rank.
The score should point to evidence. It should not replace it.
Compute at the level where the biological information changes
A whole-genome case may contain many variant rows associated with the same gene-level phenotype annotations.
Running the same ontology comparison for every such row repeats work without introducing new phenotype information.
The service therefore identifies repeated phenotype annotation sets, computes the semantic comparison once for each distinct set and associates the result with the relevant variants afterwards.
The public engineering principle is broader than this implementation:
Storage rows are not always the correct computational unit.
A variant table is organised around variants. Phenotype knowledge may be organised around genes and diseases. An efficient service should recognise that difference instead of assuming that every row requires an independent semantic calculation.
This reduction happens before parallel execution. The remaining distinct comparisons can then be distributed across long-lived worker processes.
Each worker loads the ontology once and reuses it across requests. Term resolution and repeated ontology operations are cached inside the worker process.
The number of workers, batching rules and internal cache structure are deployment details and are not part of this public description. The architectural decision is to avoid repeated ontology loading and repeated calculation for identical semantic inputs.
Keep the analytical result with the case
The service uses two storage paths because patient input and analytical output have different lifecycles.
The reviewed phenotype is case metadata. It consists of HPO terms and clinical notes selected by the user. That information is stored through the service’s persistence layer and is addressed by the case session identifier.
The calculated phenotype matches belong with the processed variant data. Folklore stores those results in the session’s analytical database alongside the classified variants.
This co-location supports direct access to both the phenotype result and the underlying variant record without transferring a complete variant dataset between services.
The matching workflow follows a fixed sequence:
- Resolve the analytical file for the case.
- Read variants that have gene-associated phenotype annotations.
- Compare the patient phenotype with the distinct annotation sets.
- attach the match result to the relevant findings;
- store the calculated results in the case database;
- prepare gene-level summaries for the user interface.
The variant-analysis service remains responsible for annotation and classification. The phenotype service reads the resulting evidence and adds a separate relevance layer.
The services communicate through explicit case artifacts rather than by duplicating the complete variant dataset over an HTTP response.
Separate initial loading from detailed review
A genome-scale result should not require the browser to download every matched variant before showing the first useful information.
The user interface initially needs a smaller view:
- which genes have phenotype-relevant findings;
- the best available match for each gene;
- the number of associated variants;
- the distribution of result categories;
- the patient terms represented in each gene summary.
Folklore generates these gene-level summaries after matching and stores them as a compressed newline-delimited JSON artifact.
The summary stream contains metadata followed by one record per gene. It does not include every variant attached to each gene.
When the user expands a gene, the frontend requests the detailed variants for that gene from the analytical database. The detailed response can then include the variant classification, consequence, frequency, inheritance information and the individual HPO comparisons.
This split keeps the first payload tied to what the screen initially renders. Variant detail is retrieved when the reviewer asks for it.
The pattern is useful beyond phenotype matching. Large analytical applications often benefit from preparing a small summary artifact and leaving row-level detail in the queryable case store.
Free text is an input aid, not the matching authority
The service also supports conversion of clinical text into candidate HPO terms.
The primary extraction path and the ontology mapping path remain separate.
A language-processing component identifies clinical findings as text. The phenotype service then maps those findings to HPO terms using its ontology index. The model does not assign the final HPO identifier directly into the accepted patient phenotype.
If the external extraction path is unavailable, the service can fall back to local ontology-based matching with word-boundary checks and basic negation handling.
This fallback has narrower linguistic coverage. It exists to preserve a usable term-proposal path, not to claim equivalent extraction quality.
In both cases, the user sees candidate terms and retains control over the saved phenotype.
The matching calculation runs only after that review.
Make failure boundaries explicit
Phenotype matching is an optional clinical-analysis stage in the wider case pipeline.
The orchestration layer calls the service only when phenotype matching is enabled and the case contains HPO terms. A failure in this stage is recorded and surfaced, but it does not erase the completed variant analysis.
That boundary reflects the dependency structure of the workflow. Variant processing can complete without phenotype matching. Phenotype matching cannot run until the variant data and gene-associated phenotype annotations are available.
Inside the service, the matching run distinguishes between several conditions:
- the case artifact cannot be found;
- the patient phenotype is empty;
- no variants contain phenotype annotations;
- the calculation fails;
- the summary export fails after the calculated results have already been stored.
These conditions should not all produce the same response.
For example, failure to create the lightweight summary artifact does not invalidate phenotype results already written to the analytical database. The service logs that export failure separately instead of discarding the completed calculation.
Operational health is also separated from readiness. The process can report its own health while readiness reflects required dependencies such as the configured database connection.
Audit the operation, not the patient text
When a matching run completes, the platform records an audit event describing the operation.
The event identifies the case and includes limited execution metadata such as the number of analysed findings and summary counts. It does not need to copy the patient’s clinical notes or the complete phenotype into the audit payload.
The detailed case evidence remains in the case stores where access controls and retention rules apply. The audit record answers a different question: what operation occurred, for which case and with what high-level outcome.
This separation reduces unnecessary duplication of clinical content while preserving an operational trail.
Where we deliberately stop
This architecture does not establish clinical validity by itself.
Ontology-aware matching can still produce an unhelpful ranking when the phenotype is incomplete, the gene-disease annotations are sparse or the recorded features are too broad. New knowledge can change the relationships available to the service. A technically reproducible score can still be clinically wrong.
The service also has a cost. Keeping term-level comparisons, analytical artifacts and separate presentation summaries introduces more data structures than returning one sorted list. Maintaining distinct services for annotation, matching and orchestration introduces explicit interfaces that must remain compatible.
We accept that cost because the boundaries remain visible.
The geneticist can inspect why a gene received attention. The classifier retains ownership of the variant class. The phenotype can change without rewriting the variant evidence. The frontend can load summaries without hiding the records beneath them.
Phenotype matching as part of the case
The useful output of phenotype matching is not a universal list of disease genes. It is a case-specific ordering grounded in the patient phenotype and linked back to the findings already present in the analysis.
Folklore places that result beside variant classification, inheritance, frequency, family analysis and reporting. The reviewer does not have to move the phenotype into a separate research tool and later reconcile the output by hand.
The design leaves three responsibilities in their proper places:
- the variant-analysis layer computes and records variant evidence;
- the phenotype service compares the accepted clinical presentation with gene-associated phenotype knowledge;
- the geneticist decides what the combined evidence means for the patient.
That final decision remains outside the score.
Helena Bioinformatics develops software infrastructure for genomic analysis and interpretation.
Folklore brings variant annotation, classification, phenotype matching, family analysis, structural variants and reporting into one case workflow.
Top comments (0)