Metadata-Version: 2.3
Name: omop-semantics
Version: 0.2.0
Summary: Add your description here
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>=7.0 ; 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 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 currently has two main runtime surfaces and one older compatibility
surface:

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

- **ConceptRegistry compatibility API**
  The older `load()` / `ConceptRegistry` path is still exported for workflows
  that rely on it, but it should be treated as a compatibility surface rather
  than the only mental model for the package.

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 `load()` / `ConceptRegistry` when you specifically need the older
   registry behavior.

---

## 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, and older
  registry workflows.

- `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 compatibility notes.
