Refactor of Documentation #182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

jenniferjiangkells merged 13 commits into main from improv/documentation_refactor_v2

Jan 27, 2026

docs/tutorials/interop/basic_conversion.md → docs/cookbook/format_conversion.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,37 +1,38 @@
  
    # Basic Format Conversion

    # Convert Between Healthcare Data Formats

    This tutorial demonstrates how to use the HealthChain interoperability module to convert between different healthcare data formats.

    Convert between CDA, HL7v2, and FHIR formats using HealthChain's interoperability engine. This recipe covers the most common conversion scenarios for integrating legacy healthcare systems with modern FHIR-based applications.

    ## Prerequisites

    - HealthChain installed (`pip install healthchain`)

    - Basic understanding of FHIR resources

    - Sample CDA or HL7v2 files (or you can use the examples below)

    The [InteropEngine](../reference/interop/engine.md) provides a unified interface for bidirectional format conversion, handling the complexity of mapping between different healthcare data standards.

    ## Setup

    First, let's import the required modules and create an interoperability engine:

    Install HealthChain:

    ```bash

    pip install healthchain

    ```

    Create an interoperability engine:

    ```python

    from healthchain.interop import create_interop, FormatType

    from pathlib import Path

    import json

    # Create an engine

    engine = create_interop()

    ```

    ## Converting CDA to FHIR

    Let's convert a CDA document to FHIR resources:

    Parse a CDA document and extract FHIR resources:

    ```python

    # Sample CDA document

    cda_xml = """

    <ClinicalDocument xmlns="urn:hl7-org:v3">

      <templateId root="2.16.840.1.113883.10.20.22.1.2"/>

      <id root="2.16.840.1.113883.19.5.99999.1"/>

      <code code="34133-9" displayName="Summarization of Episode Note" codeSystem="2.16.840.1.113883.6.1" codeSystemName="LOINC"/>

      <code code="34133-9" displayName="Summarization of Episode Note"

            codeSystem="2.16.840.1.113883.6.1" codeSystemName="LOINC"/>

      <title>Example CDA Document</title>

      <effectiveTime value="20150519"/>

      <confidentialityCode code="N" codeSystem="2.16.840.1.113883.5.25"/>

    @@ -54,18 +55,22 @@ cda_xml = """
  
          <component>

            <section>

              <templateId root="2.16.840.1.113883.10.20.1.11"/>

              <code code="11450-4" codeSystem="2.16.840.1.113883.6.1" displayName="Problem List"/>

              <code code="11450-4" codeSystem="2.16.840.1.113883.6.1"

                    displayName="Problem List"/>

              <title>Problems</title>

              <text>Hypertension</text>

              <entry>

                <observation classCode="OBS" moodCode="EVN">

                  <templateId root="2.16.840.1.113883.10.20.1.28"/>

                  <templateId root="2.16.840.1.113883.10.20.1.54"/>

                  <id root="2.16.840.1.113883.19.5.99999.3"/>

                  <code code="64572001" displayName="Hypertension" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SNOMED CT"/>

                  <code code="64572001" displayName="Hypertension"

                        codeSystem="2.16.840.1.113883.6.96" codeSystemName="SNOMED CT"/>

                  <statusCode code="completed"/>

                  <effectiveTime value="20180101"/>

                  <value xsi:type="CD" code="64572001" displayName="Hypertension" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SNOMED CT" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

                  <value xsi:type="CD" code="64572001" displayName="Hypertension"

                         codeSystem="2.16.840.1.113883.6.96" codeSystemName="SNOMED CT"

                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

                </observation>

              </entry>

            </section>

    @@ -78,22 +83,21 @@ cda_xml = """
  
    # Convert CDA to FHIR resources

    fhir_resources = engine.to_fhir(cda_xml, src_format=FormatType.CDA)

    # Print the resulting FHIR resources

    # Inspect the results

    for resource in fhir_resources:

        print(f"Resource Type: {resource.resource_type}")

        print(json.dumps(resource.dict(), indent=2))

        print("-" * 40)

    ```

    ## Converting FHIR to CDA

    You can also convert FHIR resources to a CDA document:

    Generate a CDA document from FHIR resources:

    ```python

    from fhir.resources.condition import Condition

    from fhir.resources.patient import Patient

    # Create some FHIR resources

    # Create FHIR resources

    patient = Patient(

        resourceType="Patient",

        id="patient-1",

    @@ -135,20 +139,18 @@ condition = Condition(
  
        onsetDateTime="2018-01-01"

    )

    # Convert FHIR resources to CDA

    # Convert to CDA

    resources = [patient, condition]

    cda_document = engine.from_fhir(resources, dest_format=FormatType.CDA)

    # Print the resulting CDA document

    print(cda_document)

    ```

    ## Converting HL7v2 to FHIR

    Let's convert an HL7v2 message to FHIR resources:

    Parse an HL7v2 message and extract FHIR resources:

    ```python

    # Sample HL7v2 message

    hl7v2_message = """

    MSH|^~\&|EPIC|EPICADT|SMS|SMSADT|199912271408|CHARRIS|ADT^A01|1817457|D|2.5|

    PID|1||PATID1234^5^M11^ADT1^MR^GOOD HEALTH HOSPITAL~123456789^^^USSSA^SS||EVERYMAN^ADAM^A^III||19610615|M||C|2222 HOME STREET^^GREENSBORO^NC^27401-1020|GL|(555) 555-2004|(555)555-2004||S||PATID12345001^2^M10^ADT1^AN^A|444333333|987654^NC|

    @@ -159,22 +161,19 @@ PV1|1|I|2000^2012^01||||004777^ATTEND^AARON^A|||SUR||||ADM|A0|
  
    # Convert HL7v2 to FHIR resources

    fhir_resources = engine.to_fhir(hl7v2_message, src_format=FormatType.HL7V2)

    # Print the resulting FHIR resources

    for resource in fhir_resources:

        print(f"Resource Type: {resource.resource_type}")

        print(json.dumps(resource.dict(), indent=2))

        print("-" * 40)

    ```

    ## Converting FHIR to HL7v2

    You can also convert FHIR resources to an HL7v2 message:

    Generate an HL7v2 message from FHIR resources:

    ```python

    from fhir.resources.patient import Patient

    from fhir.resources.encounter import Encounter

    # Create some FHIR resources

    patient = Patient(

        resourceType="Patient",

        id="patient-1",

    @@ -218,45 +217,38 @@ encounter = Encounter(
  
        }

    )

    # Convert FHIR resources to HL7v2

    # Convert to HL7v2

    resources = [patient, encounter]

    hl7v2_message = engine.from_fhir(resources, dest_format=FormatType.HL7V2)

    # Print the resulting HL7v2 message

    print(hl7v2_message)

    ```

    ## Saving Conversion Results

    ## Saving Results

    Let's save our conversion results to files:

    Save converted data to files:

    ```python

    # Save FHIR resources to JSON files

    output_dir = Path("./output")

    output_dir.mkdir(exist_ok=True)

    # Save FHIR resources as JSON

    for resource in fhir_resources:

        filename = f"{resource.resource_type.lower()}_{resource.id}.json"

        with open(output_dir / filename, "w") as f:

            json.dump(resource.dict(), f, indent=2)

    # Save CDA document to XML file

    # Save CDA document as XML

    with open(output_dir / "document.xml", "w") as f:

        f.write(cda_document)

    # Save HL7v2 message to file

    # Save HL7v2 message

    with open(output_dir / "message.hl7", "w") as f:

        f.write(hl7v2_message)

    ```

    ## Conclusion

    In this tutorial, you learned how to:

    - Convert CDA documents to FHIR resources

    - Convert FHIR resources to CDA documents

    - Convert HL7v2 messages to FHIR resources

    - Convert FHIR resources to HL7v2 messages

    - Save conversion results to files

    ## Next Steps

    For more advanced interoperability features, see the [InteropEngine documentation](../../reference/interop/engine.md) and other cookbook examples.

    - [InteropEngine documentation](../reference/interop/engine.md) - Advanced configuration and customization

    - [Configuration guide](../reference/interop/configuration.md) - Custom templates and mappings

    - [CDA Adapter](../reference/io/adapters/cdaadapter.md) - Higher-level CDA integration with Document containers

docs/cookbook/index.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,31 +1,109 @@
  
    # 🍳 Cookbook: Hands-On Examples

    # Cookbook

    Dive into real-world, production-ready examples to learn how to build interoperable healthcare AI apps with **HealthChain**.

    Hands-on, production-ready examples for building healthcare AI applications with HealthChain.

    ---

    <div class="tag-legend">

      <span class="tag-legend-title">Filter:</span>

      <span class="tag tag-filter tag-healthtech" data-tag="healthtech">HealthTech</span>

      <span class="tag tag-filter tag-genai" data-tag="genai">GenAI</span>

      <span class="tag tag-filter tag-ml" data-tag="ml">ML Research</span>

      <span class="tag tag-filter tag-gateway" data-tag="gateway">Gateway</span>

      <span class="tag tag-filter tag-pipeline" data-tag="pipeline">Pipeline</span>

      <span class="tag tag-filter tag-interop" data-tag="interop">Interop</span>

      <span class="tag tag-filter tag-fhir" data-tag="fhir">FHIR</span>

      <span class="tag tag-filter tag-cdshooks" data-tag="cdshooks">CDS Hooks</span>

      <span class="tag tag-filter tag-sandbox" data-tag="sandbox">Sandbox</span>

      <span class="tag-clear hidden" id="clearFilters">Clear</span>

    </div>

    ## 🚦 Getting Started

    <div class="cookbook-wrapper">

    <div class="cookbook-grid" id="cookbookGrid">

    - [**Working with FHIR Sandboxes**](./setup_fhir_sandboxes.md)

      *Spin up and access free Epic, Medplum, and other FHIR sandboxes for safe experimentation. This is the recommended first step before doing the detailed tutorials below.*

    <a href="setup_fhir_sandboxes/" class="cookbook-card" data-tags="fhir sandbox">

      <div class="cookbook-card-icon">🚦</div>

      <div class="cookbook-card-title">Working with FHIR Sandboxes</div>

      <div class="cookbook-card-description">

        Spin up and access free Epic, Medplum, and other FHIR sandboxes for safe experimentation. Recommended first step before the other tutorials.

      </div>

      <div class="cookbook-tags">

        <span class="tag tag-fhir">FHIR</span>

        <span class="tag tag-sandbox">Sandbox</span>

      </div>

    </a>

    ---

    <a href="ml_model_deployment/" class="cookbook-card" data-tags="ml gateway cdshooks">

      <div class="cookbook-card-icon">🔬</div>

      <div class="cookbook-card-title">Deploy ML Models: Real-Time Alerts & Batch Screening</div>

      <div class="cookbook-card-description">

        Deploy the same ML model two ways: CDS Hooks for point-of-care sepsis alerts, and FHIR Gateway for population-level batch screening with RiskAssessment resources.

      </div>

      <div class="cookbook-tags">

        <span class="tag tag-ml">ML Research</span>

        <span class="tag tag-gateway">Gateway</span>

        <span class="tag tag-cdshooks">CDS Hooks</span>

      </div>

    </a>

    <a href="multi_ehr_aggregation/" class="cookbook-card" data-tags="genai gateway fhir">

      <div class="cookbook-card-icon">🔗</div>

      <div class="cookbook-card-title">Multi-Source Patient Data Aggregation</div>

      <div class="cookbook-card-description">

        Merge patient data from multiple FHIR sources (Epic, Cerner, etc.), deduplicate conditions, prove provenance, and handle cross-vendor errors. Foundation for RAG and analytics workflows.

      </div>

      <div class="cookbook-tags">

        <span class="tag tag-genai">GenAI</span>

        <span class="tag tag-gateway">Gateway</span>

        <span class="tag tag-fhir">FHIR</span>

      </div>

    </a>

    ## 📚 How-To Guides

    <a href="clinical_coding/" class="cookbook-card" data-tags="healthtech pipeline interop">

      <div class="cookbook-card-icon">🧾</div>

      <div class="cookbook-card-title">Automate Clinical Coding & FHIR Integration</div>

      <div class="cookbook-card-description">

        Extract medical conditions from clinical documentation using AI, map to SNOMED CT codes, and sync as FHIR Condition resources for billing, analytics, and interoperability.

      </div>

      <div class="cookbook-tags">

        <span class="tag tag-healthtech">HealthTech</span>

        <span class="tag tag-pipeline">Pipeline</span>

        <span class="tag tag-interop">Interop</span>

      </div>

    </a>

    - 🔬 **[Deploy ML Models: Real-Time Alerts & Batch Screening](./ml_model_deployment.md)**

      *Deploy the same ML model two ways: CDS Hooks for point-of-care sepsis alerts, and FHIR Gateway for population-level batch screening with RiskAssessment resources.*

    <a href="discharge_summarizer/" class="cookbook-card" data-tags="healthtech gateway cdshooks">

      <div class="cookbook-card-icon">📝</div>

      <div class="cookbook-card-title">Summarize Discharge Notes with CDS Hooks</div>

      <div class="cookbook-card-description">

        Deploy a CDS Hooks-compliant service that listens for discharge events, auto-generates concise plain-language summaries, and delivers actionable clinical cards directly into the EHR workflow.

      </div>

      <div class="cookbook-tags">

        <span class="tag tag-healthtech">HealthTech</span>

        <span class="tag tag-gateway">Gateway</span>

        <span class="tag tag-cdshooks">CDS Hooks</span>

      </div>

    </a>

    - 🚦 **[Multi-Source Patient Data Aggregation](./multi_ehr_aggregation.md)**

      *Merge patient data from multiple FHIR sources (Epic, Cerner, etc.), deduplicate conditions, prove provenance, and robustly handle cross-vendor errors. Foundation for retrieval-augmented generation (RAG) and analytics workflows.*

    <a href="format_conversion/" class="cookbook-card" data-tags="healthtech interop fhir">

      <div class="cookbook-card-icon">🔄</div>

      <div class="cookbook-card-title">Convert Between Healthcare Data Formats</div>

      <div class="cookbook-card-description">

        Convert between CDA, HL7v2, and FHIR formats using the interoperability engine. Handle bidirectional conversion for integrating legacy systems with modern FHIR applications.

      </div>

      <div class="cookbook-tags">

        <span class="tag tag-healthtech">HealthTech</span>

        <span class="tag tag-interop">Interop</span>

        <span class="tag tag-fhir">FHIR</span>

      </div>

    </a>

    - 🧾 **[Automate Clinical Coding & FHIR Integration](./clinical_coding.md)**

      *Extract medical conditions from clinical documentation using AI, map to SNOMED CT codes, and sync as FHIR Condition resources to systems like Medplum—enabling downstream billing, analytics, and interoperability.*

    <div class="no-results hidden" id="noResults">

      No cookbooks match the selected filters. <a href="#" onclick="clearAllFilters(); return false;">Clear filters</a>

    </div>

    - 📝 **[Summarize Discharge Notes with CDS Hooks](./discharge_summarizer.md)**

      *Deploy a CDS Hooks-compliant service that listens for discharge events, auto-generates concise plain-language summaries, and delivers actionable clinical cards directly into the EHR workflow.*

    </div>

    </div>

    ---

    !!! info "What next?"

    !!! tip "What next?"

        See the source code for each recipe, experiment with the sandboxes, and adapt the patterns for your projects!

docs/index.md

-Original file line number
+Diff line change
@@ -1,4 +1,11 @@
-    # Welcome to HealthChain 💫 🏥
+    ---
+    template: welcome.html
+    hide:
+      - navigation
+      - toc
+    ---
+    # Welcome to HealthChain
     HealthChain is an open-source Python toolkit that streamlines productionizing healthcare AI. Built for AI/ML practitioners, it simplifies the complexity of real-time EHR integrations by providing seamless FHIR integration, unified data pipelines, and production-ready deployment.
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor of Documentation #182

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!