Skip to content

Value Sets Runtime

RuntimeValueSets

Top-level runtime namespace for all compiled value sets.

This is the primary entry point for interactive access to the semantic registry:

>>> runtime.genomic
>>> runtime.staging
>>> runtime.nlp

Each attribute corresponds to a named RuntimeValueSet.

RuntimeValueSet

Runtime representation of a named value set.

A value set groups multiple semantic units under a single namespace or conceptual module - no added functionality just for ease of access and use

(e.g. genomic, staging, modifiers).

Semantic units can be accessed via attribute lookup:

>>> runtime.genomic.genomic_value_group
RuntimeSemanticUnit(...)

RuntimeSemanticUnit

Runtime container for a single semantic unit.

A semantic unit may contain any combination of:

  • Named enums (RuntimeEnum)
  • Named groups (RuntimeGroup)
  • Named concepts (raw OmopConcept)

This class exposes:

  • Direct access to named enums/groups/concepts via attributes
  • Direct access to enum/group labels as attributes (flattened lookup)
  • Rich textual and HTML representations for introspection
Example 
>>> runtime.genomic.genomic_value_group.genomic_positive
9191

>>> runtime.staging.t_stage_concepts.t4
1634654

RuntimeEnum

Bases: _RuntimeLabelledConcepts

Runtime wrapper around an OmopEnum.

Exposes enum members as a label to concept_id mapping, accessible via attribute access:

>>> runtime.genomic.genomic_value_group.genomic_positive
9191

Attributes:

Name Type Description
labels list[str]

Sorted list of enum labels.
ids list[int]

Sorted list of concept IDs in the enum.

RuntimeGroup

Bases: _RuntimeLabelledConcepts

Runtime wrapper around an OmopGroup.

Exposes the group's parent concepts as an attribute-accessible namespace, mapping concept labels to OMOP concept IDs. This allows interactive access such as:

>>> runtime.staging.t_stage_concepts.t3
1634376

value property 

value: int

Return the sole concept_id if this group has exactly one parent.

__int__ 

__int__() -> int

Allow int(runtime.group) for singleton groups.

compile_valuesets

Compile declarative CDM value set definitions into runtime objects.

Parameters:

Name Type Description Default
defs CDMValueSets

Parsed value set definitions after interpolation.

 required

Returns:

Type Description
RuntimeValueSets

Runtime-accessible registry of all value sets and semantic units.
Notes

This step materialises the interactive runtime namespace used in notebooks and rule logic. It is intentionally pure and read-only.

interpolate_valuesets

Interpolate raw value set definitions by resolving string references.

This replaces string references in valuesets.yaml with concrete CDMSemanticUnits instances wrapping the corresponding OMOP semantic objects.

Parameters:

Name Type Description Default
raw dict

Raw parsed YAML dictionary from valuesets.yaml.

 required
semantic_index dict[str, OmopSemanticObject]

Lookup table mapping semantic unit names to OMOP semantic objects.

 required

Returns:

Type Description
CDMValueSets

Fully resolved value set definitions suitable for compilation into runtime objects.

Raises:

Type Description
KeyError

If a referenced semantic unit name does not exist.
TypeError

If an unsupported semantic object type is encountered.

index_semantic_units

Build a name → semantic object index from a CDMSemanticUnits container.

Parameters:

Name Type Description Default
units CDMSemanticUnits

Declarative semantic unit registry.

 required

Returns:

Type Description
dict[str, OmopSemanticObject]

Mapping from semantic unit name to underlying OMOP semantic object (enum, group, or concept).
This index is used during interpolation of value set definitions.

default_valuesets

Default Value Sets

This module provides a reference implementation for loading and compiling the default OMOP semantic value sets shipped with the library.

It demonstrates the full runtime loading pipeline:

  1. Loading semantic unit definitions (enums, groups, concepts) from YAML.
  2. Indexing semantic units by name.
  3. Loading high-level value set definitions.
  4. Interpolating string references into concrete semantic objects.
  5. Compiling the result into runtime-friendly accessors.

This file is intended primarily as: - a working exemplar of the loading pipeline, and
- a convenient import point for default registry semantics.

Loading Pipeline

The default value sets are constructed using the following steps:

from pathlib import Path
from linkml_runtime.loaders import yaml_loader

from omop_semantics.schema.generated_models.omop_named_sets import CDMSemanticUnits
from omop_semantics.runtime.value_sets import (
    compile_valuesets,
    index_semantic_units,
    interpolate_valuesets,
    RuntimeValueSets,
)
from omop_semantics import SCHEMA_DIR, INSTANCE_DIR

schema_path = SCHEMA_DIR / "core" / "omop_named_sets.yaml"
enumerator_instances = INSTANCE_DIR / "enumerators.yaml"
valueset_definitions = INSTANCE_DIR / "valuesets.yaml"

# Load semantic units (enums, groups, concepts)
enumerators = yaml_loader.load(
    str(enumerator_instances),
    target_class=CDMSemanticUnits,
)

# Build name → semantic object index
idx = index_semantic_units(enumerators)

# Load valueset definitions (string references)
value_sets = yaml_loader.load_as_dict(str(valueset_definitions))

# Interpolate string references into concrete semantic units
value_set_objects = interpolate_valuesets(value_sets, idx)

# Compile to runtime objects
runtime = compile_valuesets(value_set_objects)

Intended Usage

This module is designed to be imported directly by downstream code (etl, interactive analytics, auto-documentation and/or data validation)

from omop_semantics.runtime.default_valuesets import runtime

concept_id = runtime.genomic.genomic_value_group.genomic_positive

It can also be used as a template for loading:

  • site-specific value sets,
  • project-specific semantic registries, or
  • dynamically constructed semantic bundles.

Notes

  • This loader pipeline is intentionally explicit and decomposed for clarity.
  • The API surface may be wrapped in higher-level convenience functions in future versions.
  • The current design prioritises transparency and inspectability over terseness.