Using docker

Installing docker

First, you need to install docker on your computing system. Here are some guides to install it:

• Ubuntu: https://www.hostinger.com/tutorials/install-docker-on-ubuntu/
• Mac OSX: https://docs.docker.com/docker-for-mac/install/

Obtaining Regenie image

Building image using DockerFile

Once you have docker installed and running, you can easily build the image using the script in the Github repository scripts/regenie_docker.sh.

chmod u+x scripts/regenie_docker.sh # this may be needed first
scripts/regenie_docker.sh --help # to see all the options

scripts/regenie_docker.sh --build # generate docker image
scripts/regenie_docker.sh --build --with-mkl # generate image compiling with Intel MKL

You can check the list of available images using

docker image ls

Pulling image from Github

Alternatively, you can pull the image from the Github repository. You will first need to authenticate to GitHub Container Registry using your Github personal access token, which can be obtained following these instructions.

Once you have the token which we assume is saved in the file 'GH_TOKEN.txt', you can authenticate using

cat GH_TOKEN.txt | docker login docker.pkg.github.com -u USERNAME --password-stdin

where USERNAME corresponds to your GitHub username.

Finally, you can pull the image (located here) using for example

docker pull ghcr.io/rgcgithub/regenie/regenie:v3.0.1.gz

Running example commands

Sample commands are included in the script 'test/test_docker.sh' in the Regenie source directory. To run these, you can use

scripts/regenie_docker.sh --test ## Add --with-bio if the image was compiled with Boost Iostream library

If no issues are encountered, you should see a template command for running Regenie with docker at the end

docker run -v <host_path>:<mount_path> regenie:v3.0.1.gz regenie <command_options>

where <host_path> is the folder (use absolute path) on the machine which is mounted to the docker container (multiple mount points can be used) and <mount_path> is the folder where it is mounted in the container.

For example, a command running Regenie step 1 is:

docker run -v /src/regenie/:/docker/ regenie:v3.0.1.gz regenie \
  --step 1 \
  --bed /docker/example/example \
  --exclude /docker/example/snplist_rm.txt \
  --covarFile /docker/example/covariates.txt \
  --phenoFile /docker/example/phenotype_bin.txt \
  --remove /docker/example/fid_iid_to_remove.txt \
  --bsize 100 \
  --bt \
  --lowmem \
  --out /docker/test/fit_bin_out

This will output files from Step 1 of Regenie with prefix /src/regenie/test/fit_bin_out*