ultimagenomics/alignment repository overview

⁠UA

UA is a tool for aligning reads to a reference genome.

⁠Get UA Docker Image

⁠Get the Image

The docker image for UA can be downloaded with

$ docker pull ultimagenomics/alignment

and given a shorter name with

$ docker tag ultimagenomics/alignment ua

This shorter name is used in the following section.

⁠Run the Container

The ua executable is in the PATH of the docker image, so the simplest invocation of ua would be

$ docker run --rm ua ua --version
ua: 5.2.0 9e6d218+ 2024-02-07 22:52:14+0000

The --rm argument causes the container to be removed after UA exits.

The complete README.md file can be found at README.md in the working directory of the container and can be viewed with a command-line markdown viewer such as mdless.

$ docker run --rm ua cat README.md | mdless

To run by specifying a bind mount that provides the index file and data files and to read and write files as the current user

$ docker run --rm -v /data:/data --user $(id -u):$(id -g) ua ua --index /data/HG38.uai --input /data/input.sam --output /data/output.sam

To use stdin and stdout for input and output, pass the -i flag to run.

$ docker run --rm -i -v /data:/data --user $(id -u):$(id -g) ua ua --index /data/HG38.uai < /data/input.sam > /data/output.sam

One method to cache the index file across runs is to use the --ipc host option to docker run along with the --cache option to UA

$ docker run --rm --ipc host -v /data:/data --user $(id -u):$(id -g) ua ua --cache --index /data/HG38.uai --input /data/input.sam --output /data/output.sam

To work inside the container with a mounted directory as the current user

$ docker run -it --rm -v /data:/data --user $(id -u):$(id -g) ua bash

# ua --version
ua: 5.2.0 9e6d218+ 2024-02-07 22:52:14+0000

# ua --index /data/HG38.uai --input /data/input.sam --output /data/output.sam

When running inside the container, one can cache the index file by passing the --cache option.

# ua --cache --index /data/HG38.uai --input /data/input.sam --output /data/output.sam
# ua --cache --index /data/HG38.uai --input /data/input.sam --output /data/output.sam

To use huge pages, enter the container as root to create a group with the same group ID that is permitted in the host system to allocate huge pages via shared memory. Then create a user with the target user's id and gid and membership in that group, and then change to that user. Then use the --huge1G option to UA.

$ docker run -it --rm -v /data:/data ua bash
# groupadd -g 1004 hugetlb
# useradd -u 1003 -G 1004 myuser
# su myuser
$ ua --huge1G --cache --index /data/HG38.uai --input /data/input.sam --output /data/output.sam

All of the examples in this document show running a UA executable directly from the command line and not using the docker image. The commands must be modified as described above to work with the docker image.