Metadata-Version: 2.4
Name: lx-dtypes
Version: 0.5.5
Summary: Typed clinical data models, terminology, and interoperability contracts
Project-URL: Changelog, https://github.com/wg-lux/lx-data-models/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/wg-lux/lx-data-models
Project-URL: Issues, https://github.com/wg-lux/lx-data-models/issues
Project-URL: Repository, https://github.com/wg-lux/lx-data-models
Author-email: "Thomas J. Lux" <lux_t1@ukw.de>
Maintainer-email: "Thomas J. Lux" <lux_t1@ukw.de>
License: MIT License
        
        Copyright (c) 2025 AG-Lux
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: clinical-data,data-models,fhir,medical-research,pydantic,terminology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.12
Requires-Dist: bibtexparser>=1.4.0
Requires-Dist: django-ninja>=1.5.3
Requires-Dist: django-stubs-ext>=5.2.8
Requires-Dist: django-stubs[compatible-mypy]>=5.2.8
Requires-Dist: django>=6.0
Requires-Dist: icecream>=2.1.4
Requires-Dist: numpy>=2.2.3
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas-stubs>=2.3.3.251201
Requires-Dist: pandas>=2.2.3
Requires-Dist: pandera[io,mypy,pandas]>=0.27.0
Requires-Dist: pillow>=11.3.0
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic>=2.10.6
Requires-Dist: python-ffmpeg>=2.0.12
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.32.3
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: scipy>=1.16.1
Requires-Dist: types-pyyaml>=6.0.12.20250915
Provides-Extra: dev
Requires-Dist: build>=1.3.0; extra == 'dev'
Requires-Dist: flake8>=7.3.0; extra == 'dev'
Requires-Dist: furo>=2025.9.25; extra == 'dev'
Requires-Dist: linkify-it-py>=2.0.3; extra == 'dev'
Requires-Dist: mypy>=1.16.0; extra == 'dev'
Requires-Dist: myst-parser>=4.0.1; extra == 'dev'
Requires-Dist: opencv-python-headless>=4.12.0.88; extra == 'dev'
Requires-Dist: pip>=25.2; extra == 'dev'
Requires-Dist: pre-commit>=4.5.0; extra == 'dev'
Requires-Dist: pyright>=1.1.414; extra == 'dev'
Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
Requires-Dist: pytest-django>=4.11.1; extra == 'dev'
Requires-Dist: pytest-env>=1.1.5; extra == 'dev'
Requires-Dist: pytest-mypy-plugins>=3.2.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: radon>=6.0.1; extra == 'dev'
Requires-Dist: ruff>=0.14.8; extra == 'dev'
Requires-Dist: sphinx-autodoc-typehints>=3.5.2; extra == 'dev'
Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'dev'
Requires-Dist: sphinx<9.0,>=8.2.3; extra == 'dev'
Requires-Dist: twine<7,>=6.2.0; extra == 'dev'
Requires-Dist: vulture>=2.16; extra == 'dev'
Requires-Dist: xlrd==2.0.2; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2025.9.25; extra == 'docs'
Requires-Dist: linkify-it-py>=2.0.3; extra == 'docs'
Requires-Dist: myst-parser>=4.0.1; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=3.5.2; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
Requires-Dist: sphinx<9.0,>=8.2.3; extra == 'docs'
Description-Content-Type: text/markdown

# lx-data-models

[![PyPI](https://img.shields.io/pypi/v/lx-dtypes.svg)](https://pypi.org/project/lx-dtypes/)
[![Python](https://img.shields.io/pypi/pyversions/lx-dtypes.svg)](https://pypi.org/project/lx-dtypes/)
[![CI](https://github.com/wg-lux/lx-data-models/actions/workflows/ci.yml/badge.svg)](https://github.com/wg-lux/lx-data-models/actions/workflows/ci.yml)
[![Documentation](https://github.com/wg-lux/lx-data-models/actions/workflows/docs.yml/badge.svg)](https://github.com/wg-lux/lx-data-models/actions/workflows/docs.yml)
[![codecov](https://codecov.io/github/wg-lux/lx-data-models/graph/badge.svg?token=132HVE8KSF)](https://codecov.io/github/wg-lux/lx-data-models)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`lx-dtypes` provides typed models for clinical research data. It checks data
against study rules and versioned medical terminology. Applications can collect
validation findings during data capture and validate records before storage or
exchange. The package also supports FHIR conversion and Django integration.

> [!IMPORTANT]
> This project is research software. It is not a medical device and must not be
> used as the sole basis for clinical decisions.

## Highlights

- Reusable models for terminology, patient records, reports, and host integration.
- Versioned YAML knowledge bases with deterministic loading.
- Report-template checks for structure, coverage, and captured data.
- FHIR clinical data and terminology conversion.
- Type, test, and documentation checks in CI.

The package is in **alpha**. We aim to keep public imports stable. Releases
before `1.0` may include documented breaking changes.

## Installation

`lx-dtypes` supports Python 3.12.

```bash
python -m pip install lx-dtypes
```

## Quick start

Validate a study setup without raising for invalid input:

```python
from lx_dtypes.models.contracts.study_setup import StudySetupDefinition
from lx_dtypes.validation import validate_contract

result = validate_contract(StudySetupDefinition, {"schema_version": "1.0"})
for issue in result.report.issues:
    print(issue.code, issue.path, issue.message)

# result.value contains the typed model only when the contract is valid.
```

For ledger data, `assess_examination(knowledge_base, payload,
template_name="...")` checks terminology provenance and applies the selected
template's study rules. Findings are advisory; the host decides when to require
correction. See the [cross-layer validation guide](docs/guides/cross-layer-validation.md)
for error codes, evaluation status, and strict persistence boundaries.

Load a knowledge-base module shipped with the package:

```python
from lx_dtypes import load_knowledge_base

knowledge_base = load_knowledge_base("report_template_examples")

print(knowledge_base.config.knowledge_base_identity)
print(sorted(knowledge_base.report_template))
```

Registry-backed deployments require an exact module version. The
[knowledge-base authoring guide](docs/guides/knowledge-base-authoring.md)
explains versioning and deployment.

Provision the packaged catalog before starting a registry-backed host:

```bash
export LX_DTYPES_KB_REGISTRY=/var/lib/my-host/terminology/registry.json
lx-dtypes-kb-registry bootstrap
```

The command exits nonzero if the registry is invalid or a packaged identity
cannot load. Hosts must treat that failure as a startup blocker.

## Documentation

Follow the [reader roadmap](docs/index.md#reader-roadmap) from the model overview
to a working example, then choose terminology, reporting, or application
integration. You can start with the topic that fits your work.

Build the documentation locally with:

```bash
python -m pip install -e ".[docs]"
make -C docs html
```

## Development

Questions, documentation fixes, synthetic examples, and code changes are useful
ways to contribute. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
checks, and pull requests. See [CHANGELOG.md](CHANGELOG.md) for release notes
and [SECURITY.md](SECURITY.md) for vulnerability reporting.

For scoped repository navigation, start at [structure.yml](structure.yml) and
follow the [agent context guide](docs/agent_context.md).

## License and citation

Distributed under the [MIT License](LICENSE). If you use `lx-dtypes` in
published work, cite the project using [CITATION.cff](CITATION.cff).
