Value Sets

The value-set runtime gives you stable named concept ids with attribute-style access. It is the right choice for application logic, ETL constants, and validation rules where you want a consistent named import rather than a hardcoded integer.

from omop_semantics.runtime.default_valuesets import runtime

runtime.types.disease_episode_types.episode_of_care  # → 32533
runtime.staging.t_stage_concepts.t3                  # → 1634376
runtime.genomic.genomic_value_group.genomic_positive  # → 9191

Object hierarchy

The runtime is a four-level namespace:

RuntimeValueSets (runtime)
  └── RuntimeValueSet (runtime.staging)
        └── RuntimeSemanticUnit (runtime.staging.t_stage_concepts)
              ├── RuntimeEnum    — fixed concept list
              └── RuntimeGroup   — anchor-concept-based group

Access works at any level. runtime.staging.t3 and runtime.staging.t_stage_concepts.t3 both return the same concept id — the lookup falls through from the value set to its units and their members.

RuntimeGroup singleton shortcut

A group with exactly one parent concept collapses to a plain int on attribute access. A group with multiple parents returns the RuntimeGroup object. Call .is_singleton to test this explicitly, or use .ids to always get a set[int] regardless.

Available methods

All labelled-concept types (RuntimeEnum, RuntimeGroup) expose:

Attribute / Method	Returns
.<label>	int concept_id
.ids	set[int] of all concept ids
.labels	sorted list[str] of labels
.mapper()	dict[str, int] label → concept_id

RuntimeSemanticUnit additionally exposes .enums, .groups, and .concepts as dictionaries for direct access to the underlying objects.

What value sets are available

The shipped value sets are defined in instances/valuesets.yaml. Current top-level names:

Name	Contents
genomic	Genomic result values and mapped gene types
modifiers	Modifier fields and tables
types	Episode types and source types
treatment_modifiers	Treatment intent, modality, and modifier values
condition_modifiers	Condition modifier values, tumour grade, numeric modifiers, condition status
nlp	Document type, encoding, and language
cancer_procedures	Consult types, provider specialties, procedure types, location
measurements_numeric	Body size units and measurements, lab values, smoking, PROMs, performance status
staging	T, N, M, and group stage concepts plus stage edition
visits	Visit modalities
observations	Demography and SACT concepts
unknowns	Canonical unknown/fallback concepts

Loading your own value sets

The default runtime object loads the shipped enumerators and value sets at import time. To load a custom set instead, use the compiler directly:

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 (
    index_semantic_units,
    interpolate_valuesets,
    compile_valuesets,
)
from omop_semantics import INSTANCE_DIR

enumerators = yaml_loader.load(
    str(INSTANCE_DIR / "enumerators.yaml"),
    target_class=CDMSemanticUnits,
)
idx = index_semantic_units(enumerators)
value_sets = yaml_loader.load_as_dict(str(INSTANCE_DIR / "valuesets.yaml"))
value_set_objects = interpolate_valuesets(value_sets, idx)
runtime = compile_valuesets(value_set_objects)

Substitute your own YAML file paths to load project-specific value sets or extend the shipped ones.

API reference

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.

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(...)

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

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.

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 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 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.

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.