Metadata-Version: 2.3
Name: omop-semantics
Version: 0.2.2
Summary: Define, validate, and use schema-backed semantic conventions for OMOP CDM
Author: gkennos
Author-email: gkennos <georgina.kennedy@unsw.edu.au>
Requires-Dist: ipykernel>=7.2.0
Requires-Dist: linkml>=1.11.1
Requires-Dist: linkml-runtime>=1.11.1
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: ruamel-yaml>=0.18.17
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: urllib3>=2.7.0
Requires-Dist: ipython>=8.0 ; extra == 'dev'
Requires-Dist: pytest>=9.0.3 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: mypy>=1.8 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: rich>=13.0 ; extra == 'dev'
Requires-Dist: tornado>=6.5.5 ; extra == 'dev'
Requires-Dist: pygments>=2.20.0 ; extra == 'dev'
Requires-Dist: mkdocs-material>=9.7.6 ; extra == 'docs'
Requires-Dist: mkdocstrings-python>=2.0.1 ; extra == 'docs'
Requires-Dist: mkdocs>=1.6.1 ; extra == 'docs'
Requires-Dist: mkdocs-mermaid2-plugin>=1.2.3 ; extra == 'docs'
Requires-Dist: pygments>=2.20.0 ; extra == 'docs'
Requires-Python: >=3.12
Project-URL: Homepage, https://australiancancerdatanetwork.github.io/omop-semantics/
Project-URL: Repository, https://github.com/AustralianCancerDataNetwork/omop-semantics
Project-URL: Issues, https://github.com/AustralianCancerDataNetwork/omop-semantics/issues
Provides-Extra: dev
Provides-Extra: docs
Description-Content-Type: text/markdown

# omop-semantics

**omop-semantics** is a Python library for defining and managing **semantic conventions on top of OMOP CDM**.

It gives you a structured, versioned, portable layer for describing which OMOP concepts are valid in a given context, how they map to CDM row shapes, and what fallback concepts to use when a mapping cannot be completed. Conventions are authored in YAML, validated against schemas, and exposed as typed Python objects — not scattered across ETL code, SQL, or documentation.

---

## Three runtime surfaces

- **Value-set runtime**  
  Stable named concept ids for application logic:  
  `from omop_semantics.runtime.default_valuesets import runtime`

- **Template/profile runtime**  
  Compiled semantic templates and CDM profiles via `OmopSemanticEngine`.

- **Fallback concepts**  
  Canonical unknown and default concepts with reason codes:  
  `from omop_semantics.unknowns import UNKNOWN`

---

## Key properties

- **Portable** — no database or vocabulary graph required
- **Versionable** — conventions are tracked in git alongside code
- **Extensible** — add project-specific definitions on top of the shipped ones
- **Integrates with pipelines** — drives ETL logic, validation, and documentation from a single source

---

## When to 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

- [Usage](docs/usage.md) — loading paths and code patterns
- [Data Model](docs/data-model.md) — profiles, templates, and semantic objects
- [Schema & Instances](docs/schema-and-instances.md) — authoring assets and file organisation
- [Fallback Concepts](docs/unknowns.md) — the shipped unknown and default concepts
- [Internals](docs/internals.md) — package structure and load-time behaviour
