Metadata-Version: 2.4
Name: nhs-dmd
Version: 0.3.0b0
Summary: For handling data from the NHS DM+D, along with general prescription parsing
Author-email: Chris Finan <c.finan@ucl.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://cfinan.gitlab.io/dmd
Project-URL: Repository, https://gitlab.com/cfinan/dmd
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: multi-join
Requires-Dist: pint
Requires-Dist: pymysql
Requires-Dist: sqlalchemy>2
Requires-Dist: sqlalchemy-config
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Requires-Dist: requests; extra == "dev"
Requires-Dist: umls-tools; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: nbsphinx-link; extra == "docs"
Requires-Dist: sphinx-argparse; extra == "docs"
Requires-Dist: cfin-pyaddons; extra == "docs"
Dynamic: license-file

# DMD database

[![version](https://img.shields.io/badge/version-0.3.0b0-blue)](https://gitlab.com/cfinan/dmd)
[![python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org)
[![license](https://img.shields.io/badge/license-GPL--3.0-green)](LICENSE.txt)

A Python toolkit for building the NHS Dictionary of Medicines and Devices
(DM+D) XML distribution files into a relational database. It provides an
SQLAlchemy 2 ORM, CLI scripts for building single-version and multi-version
warehouse databases, and a query API for looking up medicines by name, ID, or
ingredient.

There is [online documentation](https://cfinan.gitlab.io/dmd/index.html) for
dmd.

Please note, this is for research purposes only and was built to map
prescriptions from sources such as CPRD and the UK BioBank. Please do not use
for any healthcare related implementation.

## Installation

### Using pip

Install from a local clone for development:

```bash
git clone git@gitlab.com:cfinan/dmd.git
cd dmd
pip install -e ".[dev]"
```

### Using conda

A conda package is available in the `cfin` channel for Python 3.11--3.13
(Linux-64):

```bash
conda install -c cfin -c conda-forge dmd
```

## Usage

### Command line

Build one weekly SQLite database from a TRUD zip pair:

```bash
dmd-build -v -B nhsbsa_dmdbonus_<version>.zip nhsbsa_dmd_<version>.zip ~/dmd.db
```

Walk a year-folder archive tree and write one weekly file per dump
(existing destinations are skipped):

```bash
resources/bin/dmd-bulk-build.sh /data/Dmd/DmdArchive /data/Dmd/DmdDbs
```

Load those weeklies into the current warehouse file. Use `--create`
(not `-c`; `-c` is the config-file flag). The default destination is
`/data/Dmd/Warehouse/dmd_warehouse_v2.db`. The old file
`dmd_warehouse.db` is refused.

```bash
dmd-warehouse-build -v list --create \
  /data/Dmd/Warehouse/weeklies.list \
  /data/Dmd/Warehouse/dmd_warehouse_v2.db
```

`dmd-warehouse-build corpus` discovers remaining zips and records each
dump as loaded, set-aside, or skipped. Use it when weeklies are not
already built under year folders.

More information on DM+D can be found on the NHS digital
[TRUD](https://isd.digital.nhs.uk/trud/user/guest/group/0/home) site. You will
need an account to subscribe and download.

For full CLI help:

```bash
dmd-build --help
dmd-warehouse-build --help
```

### Python API

```python
import sqlalchemy
from dmd.build import build_dmd

engine = sqlalchemy.create_engine("sqlite:///dmd.db")
sm = sqlalchemy.orm.sessionmaker(bind=engine)

build_dmd(
    sm,
    "nhsbsa_dmd_<version>.zip",
    bonus_zip="nhsbsa_dmdbonus_<version>.zip",
)
```

## Schema

The final database will have the following schema (including bonus file). Open
in a separate browser tab to make it larger.

<div>
<img style="float: right;" width="100%" height="100%" src="./resources/images/dmd_schema.png">
</div>
