ACMC Command Line Reference

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:

bash acmc trud install

OMOP Command

The omop command is used for installing OMOP vocabularies.

  • Install OMOP

Install vocabularies in a local OMOP database:

bash 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:

bash acmc omop clear

  • Delete OMOP

Delete the local OMOP database:

bash acmc omop delete

PHEN Command

The phen command is used phenotype-related operations.

  • Initialise Phenotype

Initialise a phenotype directory locally or with remote git repository:

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

  • -d, --phen-dir: (Optional) Directory to write phenotype configuration (the default is ./workspace/phen).

  • -r, --remote-url: (Optional) URL to a remote git repository where the phenotype will be published, only supports an empty repo without existing commits.

  • Fork Existing Phenotype

Initialise a phenotype an existing phenotype publish in a git repository:

bash acmc phen fork -d <PHENOTYPE_DIRECTORY> -r <REMOTE_URL>

  • -d, --phen-dir: (Optional) Local phenotype workspace directory (default is ./workspace/phen).
  • -r, --remote-url: (Optional) URL to a remote git repository where the phenotype will be published, only supports an empty repo without existing commits.
  • -u, --upstream-url: (Required) URL to the phenotype repository to fork.

  • -v, --upstream-version: (Required) Phenotype version to fork.

  • Validate Phenotype

Validate the phenotype configuration:

bash acmc phen validate -d <PHENOTYPE_DIRECTORY>

  • -d, --phen-dir: (Optional) Local phenotype workspace directory (default is ./workspace/phen).

  • Map Phenotype

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

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

  • -t, --target-coding: (Optional) Specify the target coding (e.g., read2, read3, icd10, snomed, opcs4).
  • -d, --phen-dir: (Optional) Local phenotype workspace directory (default is ./workspace/phen).
  • --not-translate: (Optional) Prevent any phenotype translation using NHS TRUD vocabularies. Therefore only concepts in already in the traget coding will be mapped.
  • --no-metadata: (Optional) Prevent copying of metadata columns to output.

  • --do-reverse-translate: (Optional) Enable reversing one directional mappings. WARNING goes against NHS TRUD guidelines.

  • 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:

bash acmc phen publish -d <PHENOTYPE_DIRECTORY>

  • -d, --phen-dir: (Optional) Local phenotype workspace directory (default is ./workspace/phen).
  • -i, --increment: (Optional) Version increment: major, minor, or patch, default is patch increment
  • -m, --msg: (Optional) Message to include with the published version

  • -r, --remote_url: (Optional) URL to a remote git repository where the phenotype will be published, only supports an empty repo without existing commits.

  • 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:

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

  • -d, --phen-dir: (Optional) Local phenotype workspace directory (default is ./workspace/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:

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

  • -d, --phen-dir: (Optional) Local phenotype workspace directory (default is ./workspace/phen).
  • -v, --version: (Optional) Directory of changed phenotype version, default is latest which is the current files in the changed phen directory.
  • -od, --old-phen-dir: (Optional) Directory of old phenotype, default is ./workspace/phen.
  • -ov, --old-version: (Required) Old phenotype version to compare with the chnaged version, default is latest which are the current files in the old phen directory.