Skip to content

Enhanced_CodeSystem_Documentation.md

Latest commit

 

History

History
183 lines (151 loc) · 6.65 KB

Enhanced_CodeSystem_Documentation.md

File metadata and controls

183 lines (151 loc) · 6.65 KB
Raw

Enhanced FHIR CodeSystem for Norwegian Laboratory Codebook (NLK)

Overview

Yes, FHIR CodeSystem codes can have extensive additional details! The enhanced NLK CodeSystem leverages all available metadata from the source data to create rich, comprehensive code definitions that go far beyond simple code/display pairs.

Enhanced Metadata Structure

Standard FHIR CodeSystem Elements

  • Code: The laboratory test identifier (e.g., NOR05003)
  • Display: Norwegian user-friendly name (e.g., Us-Osmolalitet)
  • Definition: Formal code definition when available (e.g., Syst(spec.)—Solute; molal.(proc.) = ? mosmol/kg)

Rich Property-Based Metadata

Each concept can include the following typed properties:

1. Lifecycle Properties

  • status: Current status (active, retired, draft)
  • effectiveDate: When the code became valid
  • expirationDate: When the code expires/expired
  • lastModified: Date of last modification
  • replacedBy: Code that replaces this concept (for retired codes)

2. Laboratory-Specific Properties

  • component: What is being measured (e.g., Osmotisk aktive partikler)
  • componentSpec: Component specification details
  • system: Biological system/specimen (e.g., System)
  • systemSpec: System specification (e.g., spesifikasjon)
  • property: Type of measurement (e.g., molalitet)
  • propertySpec: Property specification (e.g., prosedyreavhengig)
  • unit: Unit of measurement (e.g., mosmol/kg)

3. Classification Properties

  • primaryDomain: Primary medical domain (e.g., Medisinsk biokjemi)
  • secondaryDomain: Secondary medical domain if applicable
  • grouping: Test grouping category (e.g., Elektrolytter)

Example: Complete Concept Definition

* #NOR05003 "Us-Osmolalitet"
  * ^definition = "Syst(spec.)—Solute; molal.(proc.) = ? mosmol/kg"
  * ^property[+]
    * code = #status
    * valueCode = #active
  * ^property[+]
    * code = #effectiveDate
    * valueDateTime = "2013-01-25T00:00:00+00:00"
  * ^property[+]
    * code = #lastModified
    * valueDateTime = "2022-01-24T00:00:00+00:00"
  * ^property[+]
    * code = #component
    * valueString = "Osmotisk aktive partikler"
  * ^property[+]
    * code = #system
    * valueString = "System"
  * ^property[+]
    * code = #systemSpec
    * valueString = "spesifikasjon"
  * ^property[+]
    * code = #property
    * valueString = "molalitet"
  * ^property[+]
    * code = #propertySpec
    * valueString = "prosedyreavhengig"
  * ^property[+]
    * code = #unit
    * valueString = "mosmol/kg"
  * ^property[+]
    * code = #primaryDomain
    * valueString = "Medisinsk biokjemi"
  * ^property[+]
    * code = #grouping
    * valueString = "Elektrolytter"

Data Quality and Completeness

From the 11,395 concepts in the enhanced CodeSystem:

Concept Status Distribution

  • Active concepts: 9,686 (85.0%)
  • Retired concepts: 1,709 (15.0%)

Primary Domain Distribution

  • Immunologi og transfusjonsmedisin: 3,231 concepts (28.4%)
  • Medisinsk biokjemi: 2,881 concepts (25.3%)
  • Klinisk farmakologi: 2,642 concepts (23.2%)
  • Medisinsk mikrobiologi: 2,547 concepts (22.4%)
  • Medisinsk genetikk: 67 concepts (0.6%)
  • Patologi: 27 concepts (0.2%)

Metadata Completeness

  • Definition: 93.1% of concepts have formal definitions
  • Component: 93.1% have component information
  • System: 93.1% have system information
  • Property type: 92.9% have property type information
  • Units: 51.7% have unit information (as expected, some tests are qualitative)
  • Grouping: 86.0% have grouping classifications

Benefits of Enhanced Metadata

1. Semantic Interoperability

  • Rich context enables better automated mapping and translation
  • Component/system/property structure aligns with LOINC methodology
  • Domain classifications support filtering and organization

2. Clinical Decision Support

  • Units and ranges support automated validation
  • Component information enables laboratory result interpretation
  • Domain classifications help with clinical context

3. Lifecycle Management

  • Status tracking shows which codes are currently valid
  • Effective dates support temporal queries
  • Replacement relationships maintain historical continuity

4. Advanced Querying

  • Filter by medical domain or test grouping
  • Search by component or measurement type
  • Find tests by specific units or properties

Usage Examples

Finding All Active Biochemistry Tests

SELECT ?code ?display WHERE {
  ?concept a fhir:CodeSystem.concept ;
    fhir:CodeSystem.concept.code ?code ;
    fhir:CodeSystem.concept.display ?display ;
    fhir:CodeSystem.concept.property [
      fhir:CodeSystem.concept.property.code [fhir:value "status"] ;
      fhir:CodeSystem.concept.property.valueCode [fhir:value "active"]
    ] ;
    fhir:CodeSystem.concept.property [
      fhir:CodeSystem.concept.property.code [fhir:value "primaryDomain"] ;
      fhir:CodeSystem.concept.property.valueString [fhir:value "Medisinsk biokjemi"]
    ] .
}

Finding Tests by Unit

SELECT ?code ?display WHERE {
  ?concept a fhir:CodeSystem.concept ;
    fhir:CodeSystem.concept.code ?code ;
    fhir:CodeSystem.concept.display ?display ;
    fhir:CodeSystem.concept.property [
      fhir:CodeSystem.concept.property.code [fhir:value "unit"] ;
      fhir:CodeSystem.concept.property.valueString [fhir:value "mmol/L"]
    ] .
}

Implementation Notes

Performance Considerations

  • Large file size (~355K lines for 11,395 concepts)
  • Consider splitting into smaller CodeSystems by domain if needed
  • Properties enable efficient filtering without loading all concepts

FHIR Compliance

  • Fully compliant with FHIR R4 CodeSystem resource structure
  • Uses standard property types (code, string, dateTime)
  • Follows FSH (FHIR Shorthand) syntax conventions

Extensibility

  • Property-based approach allows adding new metadata without structural changes
  • Can easily incorporate additional CSV columns as new properties
  • Supports both administrative and clinical metadata

Conclusion

The enhanced FHIR CodeSystem demonstrates that codes can indeed have rich, detailed metadata that provides comprehensive context for laboratory testing. By leveraging the complete source data and FHIR's property-based extension mechanism, we created a CodeSystem that supports:

  • Complete lifecycle management (active/retired status, temporal validity)
  • Rich semantic context (components, systems, properties, units)
  • Clinical organization (domains, groupings)
  • Historical continuity (replacement relationships)

This approach transforms a simple code list into a comprehensive, interoperable, and clinically useful terminology resource.