Extract Clinical Entities To Fhir

Extract clinical entities to FHIR

Separate extraction from clinical coding. OpenMed finds spans and supplies the mechanical FHIR builders; the application decides which resource type and status are clinically appropriate.

Procedure

1. Keep the source synthetic, or de-identify it inside the trusted boundary before extraction.
2. Run openmed.analyze_text with the task-appropriate clinical model.
3. Filter predictions by label and confidence; preserve offsets in a PHI-safe audit record.
4. Map each accepted span to the correct FHIR resource type.
5. Add terminology codes only from a user-approved mapping or terminology service. Never invent a code.
6. Assemble resources with to_bundle and validate against the target profile.

Runnable synthetic example

Install the model runtime first with python -m pip install "openmed[hf]".

import json

from openmed import analyze_text
from openmed.clinical.exporters.fhir import to_bundle

note = "Assessment: type 2 diabetes mellitus is stable on metformin."
result = analyze_text(
    note,
    model_name="disease_detection_superclinical",
    confidence_threshold=0.5,
)

resources = [{"resourceType": "Patient", "id": "synthetic-patient"}]
for index, entity in enumerate(result.entities, start=1):
    if entity.label.upper() not in {"CONDITION", "DIAGNOSIS", "DISEASE"}:
        continue
    resources.append(
        {
            "resourceType": "Condition",
            "id": f"condition-{index}",
            "clinicalStatus": {
                "coding": [
                    {
                        "system": (
                            "http://terminology.hl7.org/CodeSystem/"
                            "condition-clinical"
                        ),
                        "code": "active",
                    }
                ]
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": (
                            "http://terminology.hl7.org/CodeSystem/"
                            "condition-ver-status"
                        ),
                        "code": "confirmed",
                    }
                ]
            },
            # A text-only CodeableConcept is preferable to an invented code.
            "code": {"text": entity.text},
            "subject": {"reference": "Patient/synthetic-patient"},
        }
    )

if len(resources) == 1:
    raise RuntimeError("No condition spans met the label and confidence rules")

bundle = to_bundle(resources, doc_id="synthetic-note-001")
print(json.dumps(bundle, indent=2))

Safety checks

• Do not put raw identifiers, source text, or reversible mappings in logs, OperationOutcome.diagnostics, or trace metadata.
• Keep a patient identity service separate from extracted clinical facts.
• Preserve negation, temporality, and experiencer context before asserting a resource as active or confirmed.
• Use a text-only CodeableConcept when no approved code is available.
• Validate the Bundle against the receiver's FHIR and profile requirements.
• Do not bundle restricted terminologies; use the user's licensed service.

Repository example

Read and run the redaction-to-FHIR walkthrough for an offline-friendly pipeline with deterministic extraction.