omop-semantics 0.2.1

Define, validate, and use schema-backed semantic conventions for OMOP CDM

omop_semantics

omop_semantics is a Python library for defining and managing semantic conventions on top of OMOP CDM.

It lets you describe conventions in code

• which OMOP concepts you want to have on hand as named key concepts to improve ergonomics in analytic code,
• how they are grouped,
• what roles they play
• and provide profiles to render these targets uniformly into CDM tables.

The goal is to make these conventions explicit, versioned, and reusable, instead of being buried in code, SQL, or documentation. They are also extensible so that you can add opinionated layers on top of default specifications that may be relevant in a domain-specific context only.

---

Current structure

The library has three user-facing surfaces:

• Value-set runtime For stable named ids and ergonomic downstream access such as from omop_semantics.runtime.default_valuesets import runtime.

• Template/profile runtime For working with semantic templates, compiled template views, and CDM row shapes via OmopSemanticEngine.

• Fallback concepts For canonical "unknown", "not recorded", and default concepts via from omop_semantics.unknowns import UNKNOWN.

If you are starting new downstream code today:

1. use runtime.default_valuesets when you need stable named concept ids,
2. use OmopSemanticEngine when you need templates, profiles, or profile groups,
3. use omop_semantics.unknowns when you need standard fallback concepts and their reason codes.

---

Key ideas

• Human-authored
  Semantic rules and concept groups are written in YAML and validated with schemas.

• Portable
  No database or graph store required.

• Versionable
  Conventions can evolve over time and be tracked in git.

• Integrates with pipelines
  Can drive ETL logic, validation, and documentation so they stay in sync.

---

Typical workflow

1. Define a schema
   Describes what kinds of semantic objects and roles exist (e.g. staging, modifiers).

2. Write YAML instances
   Lists actual OMOP concepts, profiles, and templates used in your project.

3. Load the runtime surface you need
   Use value sets for named ids, or the semantic engine for template/profile work.

4. Use it in code
   For validation, cohort logic, ETL constraints, or documentation.

---

When should you use this?

Use omop_semantics if you:

• have project-specific rules about which OMOP concepts are valid,
• need consistent concept groupings across ETL and analytics,
• want semantic conventions to be explicit, testable, and versioned,
• are working in domains like oncology where OMOP alone is too permissive.

---

Docs map

• docs/usage.md Recommended loading paths for value sets, templates/profiles, fallback concepts, and lower-level helpers.

• docs/data-model.md The conceptual distinction between profiles, profile groups, templates, and semantic objects.

• docs/schema-and-instances.md Canonical authoring assets and how the shipped schema/instance files are organized.

• docs/internals.md Repo structure, public runtime surfaces, and load-time behavior.

• docs/unknowns.md Canonical fallback concepts and how to use their reason codes.