Docker Installation

Containerized usage is recommended when you want a reproducible environment with Perl dependencies preinstalled.

Windows

Windows users can run the published Linux image with Docker Desktop configured for Linux containers, normally through its WSL2 backend. This is the simplest Windows setup and avoids installing Perl dependencies on the host.

The following PowerShell command mounts the current directory and runs a conversion:

docker run --rm `
  --volume "${PWD}:/data" `
  --workdir /data `
  manuelrueda/convert-pheno:latest `
  /usr/share/convert-pheno/bin/convert-pheno `
  -ipxf pxf.json -obff individuals.json

Input files and generated output remain in the mounted Windows directory.

Method 1: From Docker Hub

Download the latest image from Docker Hub:

docker pull manuelrueda/convert-pheno:latest
docker image tag manuelrueda/convert-pheno:latest cnag/convert-pheno:latest

Method 2: Build From Dockerfile

The repository includes a docker/Dockerfile.

Build the image locally with:

docker buildx build --load \
  --file docker/Dockerfile \
  --build-arg BUILD_VERSION="$(cat VERSION)" \
  --build-arg VCS_REF="$(git rev-parse HEAD)" \
  --tag cnag/convert-pheno:latest \
  .

The Dockerfile packages the current repository checkout; it does not clone the moving main branch. Uncommitted files are also part of a local build unless they are excluded by .dockerignore. Check out a release tag before building if you need an image that exactly matches that release.

Maintainer release builds

After committing the version and changelog, create and push a tag matching the value in VERSION:

VERSION="$(cat VERSION)"
git tag -a "$VERSION" -m "Tagging version $VERSION"
git push origin "$VERSION"

Pushing the tag automatically launches the Docker build (multi-arch) GitHub workflow. The workflow builds the tagged checkout and records its Git SHA and Convert-Pheno version in the image labels. It refuses lightweight tags, tags that do not point to the checked-out commit, and tags that do not match VERSION.

Run Convert-Pheno

Run each conversion in the foreground and mount the current directory so Convert-Pheno can read local inputs and write its results back to the host:

docker run --rm \
  --volume "$PWD:/data" \
  --workdir /data \
  cnag/convert-pheno:latest \
  /usr/share/convert-pheno/bin/convert-pheno \
  -ipxf pxf.json -obff individuals.json

The command displays progress and errors in the terminal, then removes the container when it finishes. A successful run creates individuals.json in the current directory. Replace the final line with the Convert-Pheno arguments required for your conversion.

The image runs as root by default. On Linux, add --user "$(id -u):$(id -g)" to keep output files owned by your current user:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --volume "$PWD:/data" \
  --workdir /data \
  cnag/convert-pheno:latest \
  /usr/share/convert-pheno/bin/convert-pheno \
  -ipxf pxf.json -obff individuals.json

Reproduce Tested Examples

Release images include the regression fixtures under /usr/share/convert-pheno/t. The following commands read those inputs directly from the published 0.34 image and write only the converted file to the mounted host directory.

PXF to BFF:

docker run --rm \
  --volume "$PWD:/data" \
  manuelrueda/convert-pheno:0.34 \
  /usr/share/convert-pheno/bin/convert-pheno \
  -ipxf /usr/share/convert-pheno/t/pxf2bff/in/pxf.json \
  -obff /data/individuals.json \
  --test -O

BFF to PXF:

docker run --rm \
  --volume "$PWD:/data" \
  manuelrueda/convert-pheno:0.34 \
  /usr/share/convert-pheno/bin/convert-pheno \
  -ibff /usr/share/convert-pheno/t/bff2pxf/in/individuals.json \
  -opxf /data/pxf.json \
  --test -O

OMOP CSV tables to BFF:

docker run --rm \
  --volume "$PWD:/data" \
  manuelrueda/convert-pheno:0.34 \
  /usr/share/convert-pheno/bin/convert-pheno \
  -iomop \
  /usr/share/convert-pheno/t/omop2bff/in/PERSON.csv \
  /usr/share/convert-pheno/t/omop2bff/in/CONCEPT.csv \
  /usr/share/convert-pheno/t/omop2bff/in/DRUG_EXPOSURE.csv \
  -obff /data/individuals-omop.json \
  --test -O

The corresponding reference outputs and native commands are indexed in the repository's t/ fixture guide.

Interactive Container (Optional)

Use a named, detached container when you want to inspect the image or run several commands in the same environment:

docker run -tid \
  --volume "$PWD:/data" \
  --workdir /data \
  --name convert-pheno \
  cnag/convert-pheno:latest
docker exec -ti convert-pheno bash

The command-line executable is available at /usr/share/convert-pheno/bin/convert-pheno. Images built from the current source also add that directory to PATH. Remove the named container when it is no longer needed:

docker rm -f convert-pheno

The image also includes dockeruser with UID=1000. To use it, add --user 1000:1000 to the initial docker run command.

Use make

If you prefer, use the included makefile.docker:

make -f makefile.docker install
make -f makefile.docker run
make -f makefile.docker enter

Mount Volumes

Containers are isolated: files on your computer are not visible inside the container unless you mount them. The easiest approach is to put the input files, mapping files, dictionaries, optional databases, and output directory under one project directory and mount that directory as /data.

Recommended layout on the host:

my_convert_pheno_run/
|-- input/
|   |-- clinical.csv
|   |-- redcap.csv
|   `-- redcap-dictionary.csv
|-- mapping/
|   `-- mapping.yaml
|-- db/
|   `-- ohdsi.db
`-- output/

Run a conversion with that directory mounted:

docker run --rm \
  --volume "$PWD/my_convert_pheno_run:/data" \
  --workdir /data \
  cnag/convert-pheno:latest \
  /usr/share/convert-pheno/bin/convert-pheno \
  -icsv /data/input/clinical.csv \
  --mapping-file /data/mapping/mapping.yaml \
  --term-audit /data/output/terminology.tsv \
  -obff /data/output/individuals.json

For REDCap input, keep both the export and dictionary under the mounted directory:

docker run --rm \
  --volume "$PWD/my_convert_pheno_run:/data" \
  --workdir /data \
  cnag/convert-pheno:latest \
  /usr/share/convert-pheno/bin/convert-pheno \
  -iredcap /data/input/redcap.csv \
  --redcap-dictionary /data/input/redcap-dictionary.csv \
  --mapping-file /data/mapping/mapping.yaml \
  -obff /data/output/individuals.json

If your files are already in different host directories, you do not need to copy them. Mount each directory explicitly and use the container paths in the command:

docker run --rm \
  --volume /path/to/input:/input:ro \
  --volume /path/to/mapping:/mapping:ro \
  --volume /path/to/output:/output \
  --volume /path/to/db:/db:ro \
  cnag/convert-pheno:latest \
  /usr/share/convert-pheno/bin/convert-pheno \
  -icsv /input/clinical.csv \
  --mapping-file /mapping/mapping.yaml \
  --path-to-ohdsi-db /db \
  -obff /output/individuals.json

Use read-only mounts (:ro) for inputs, mappings, and databases when you do not want the container to modify those files. Do not use :ro for output directories.

System Requirements

• Supported targets: linux/amd64 and linux/arm64
• Perl 5.26+ inside the image
• At least 4 GB RAM
• At least 1 CPU core
• At least 16 GB disk space

Optional Athena-OHDSI Database

OMOP output requires the current ohdsi.db; OMOP input can also use it for concepts absent from the supplied CONCEPT table. This approximately 3.2 GB database includes concept domains, standard-concept status, and Maps to relationships. Older four-column copies are not compatible. Download it separately, mount it into the container, and point to its directory with --path-to-ohdsi-db.

You can either download it manually in a browser from this Google Drive directory:

• https://drive.google.com/drive/folders/1-5Ywf-hhwb8bX1sRNV2Tf3EjH4TCaC8P?usp=sharing

or download the file from the command line with gdown:

pip install gdown

import gdown

url = "https://drive.google.com/uc?export=download&id=1zQ26Q1qsqTBPDGrtZbhDP-85NhaOrfBP"
output = "./ohdsi.db"
gdown.download(url, output, quiet=False)