controller

Overview

Workflow

The high level steps to use the tools are outlined below:

1. Define concept sets: A domain expert defines a list of concept sets for each observable characteristic of the phenotype using CSV file format (e.g., PHEN_concept_sets.csv).

2. Define concept code lists for concept sets: A domain expert defines code lists for each concept set within the phenotype using supported coding list formats and stores them in the /src directory.

3. Define mapping from code lists to concept sets: A domain expert defines a phenotype mapping that maps code lists to concept sets.

4. Generate versioned phenotype coding lists and translations: A domain expert or data engineer processes the phenotype mappings using the command line tool to validate against NHS TRUD-registered codes and mapping and to generate versioned concept set code lists with translations between coding standards.

Supported Medical Coding Standards

The tool supports verification and mapping across diagnostic coding formats below:

• Read V2: NHS clinical terminology standard used in primary care and replaced by SNOMED-CT in 2018; Still supported by some data providers as widely used in primary care, e.g. SAIL Databank
• SNOMED-CT: international standard for clinical terminology for Electronic Healthcare Records adopted by the NHS in 2018; Mappings to Read codes are partially provided by Clinical Research Practice Database (CPRD) and NHS Technology Reference Update Distribution (TRUD).
• ICD-10: International Classification of Diseases (ICD) is a medical classification list from the World Health Organization (WHO) and widely used in hospital settings, e.g. Hospital Episode Statistics (HES).
• ATC Codes: Anatomical Therapeutic Chemical (ATC) Classification is a drug classification list from the World Health Organization (WHO)

Notes

Processed resources will be saved in the build/maps/processed/ directory.

Note: NHS TRUD provides one-way mappings. To reverse mappings, duplicate the .parquet file and reverse the filename (e.g., read2_code_to_snomed_code.parquet to snomed_code_to_read2_code.parquet).

Usage

The acmc command-line tool provides various commands to interact with TRUD, OMOP, and Phenotype data. Below are the usage details for each command.

General Syntax

acmc [OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS]

Where:

• [OPTIONS] are global options that apply to all commands (e.g., --debug, --version).
• [COMMAND] is the top-level command (e.g., trud, omop, phen).
• [SUBCOMMAND] refers to the specific operation within the command (e.g., install, validate).

Global Options

• --version: Display the acmc tool version number
• --debug: Enable debug mode for more verbose logging.

Commands

TRUD Command

The trud command is used for installing NHS TRUD vocabularies.

• Install TRUD

  Install clinically assurred TRUD medical code mappings:

  acmc trud install

OMOP Command

The omop command is used for installing OMOP vocabularies.

• Install OMOP

  Install vocabularies in a local OMOP database:

  acmc omop install -d <OMOP_DIRECTORY_PATH> -v <OMOP_VERSION>

  • -d, --omop-dir: (Optional) Directory path to extracted OMOP downloads, default is ./build/omop
  • -v, --version: OMOP vocabularies release version.

• Clear OMOP

  Clear data from the local OMOP database:

  acmc omop clear

• Delete OMOP

  Delete the local OMOP database:

  acmc omop delete

PHEN Command

The phen command is used phenotype-related operations.

• Initialize Phenotype

  Initialize a phenotype directory locally or from a remote git repository:

  acmc phen init -d <PHENOTYPE_DIRECTORY> -r <REMOTE_URL>

  • -d, --phen-dir: (Optional) Directory to write phenotype configuration (the default is ./build/phen).
  • -r, --remote_url: (Optional) URL to a remote git repository.

• Validate Phenotype

  Validate the phenotype configuration:

  acmc phen validate -d <PHENOTYPE_DIRECTORY>

  • -d, --phen-dir: (Optional) Directory of phenotype configuration (the default is ./build/phen).

• Map Phenotype

  Process phenotype mapping and specify the target coding and output format:

  acmc phen map -d <PHENOTYPE_DIRECTORY> -t <TARGET_CODING> -o <OUTPUT_FORMAT>

  • -t, --target-coding: Specify the target coding (e.g., read2, read3, icd10, snomed, opcs4).
  • -d, --phen-dir: (Optional) Directory of phenotype configuration (the default is ./build/phen).
  • -o, --output: Output format(s) (csv, omop, or both), default is 'csv'.

• Publish Phenotype Configuration

  Publish a phenotype configuration, committing all changes and tagging with a new version number. If the phenotype has been initialised from a remote git URL, then the commit and new version tag will be pushed to the remote repo:

  acmc phen publish -d <PHENOTYPE_DIRECTORY>

  • -d, --phen-dir: (Optional) Directory of phenotype configuration (the default is ./build/phen).

• Copy Phenotype Configuration

  Copy a phenotype configuration from a source directory to a target directory at a specific version. This is used when wanting to compare versions of phenotypes using the acmc phen diff command:

  acmc phen copy -d <PHENOTYPE_DIRECTORY> -td <TARGET_DIRECTORY> -v <PHENOTYPE_VERSION>

  • -d, --phen-dir: (Optional) Directory of phenotype configuration (the default is ./build/phen).
  • -td, --target-dir: (Optional) Directory to copy the phenotype configuration to, (the default is ./build).
  • -v, --version: The phenotype version to copy.

• Compare Phenotype Configurations

  Compare a a new phenotype version with pervious version of a phenotype:

  acmc phen diff -d <NEW_PHENOTYPE_DIRECTORY> -old <OLD_PHENOTYPE_DIRECTORY>

  • -d, --phen-dir: (Optional) Directory of current phenotype configuration (the default is ./build/phen).
  • -old, --phen-dir-old: (Required) Directory of old phenotype version)