4. Installation

Note: We are working on a Conda build for Patchwork. In the future, the user will be able to install the programming by running conda install -c bioconda patchwork. These instructions describe how to do the installation manually, or alternatively with Docker.

Building Patchwork from Source

If you want to download Patchwork and build the program from source, you will need to ensure you have the following dependencies installed on your computer for the program to build and run correctly.

Dependencies

DIAMOND

The sequence aligner DIAMOND is required to run Patchwork. We recommend using Anaconda for installing this program. After installing Anaconda, install DIAMOND by entering:

conda install -c bioconda diamond

Julia

Patchwork is written in the programming language Julia and requires that you have julia installed to run. The instructions for installing Julia are available from their website but the program can also be obtained using Conda:

conda install -c conda-forge julia

Julia packages

The Julia packages that the program depends on are typically handled by Julia itself. If this is not the case, please notify us by opening an issue. Before doing so, however, please check to see if the issue already exists.

In the meantime, you can try installing the missing package yourself. Type julia followed by Enter to open up a Julia REPL. It should look something like this:

               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.6.2 (2021-07-14)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

julia>

Type ] to enter the Pkg mode (see this page for a description of the various modes in the Julia REPL). Once in the Pkg mode, type add NAME to add the package of your choice. For example, if Patchwork was complaining that ArgParse is missing, then type add ArgParse. You can use tab completion in this mode to make sure that your spelling is correct.

Obtaining the source code

Move into the directory where you want to install Patchwork and type this into your terminal:

$ git clone https://github.com/fethalen/patchwork

Go into the newly created directory by typing cd patchwork, then follow the instructions below to compile the program.

Compiling Patchwork

Note: At the moment of writing, the compiled binary is approximately 1 GB in size. Please ensure that you have enough space left on your device. This is because Julia and all the dependencies are installed alongside the program itself.

Please make sure to follow the instructions above for downloading the source code and moving into the source code's base directory. Once there, type the following to compile Patchwork:

$ julia src/compile.jl . src/precompiled.jl OUTPUT_DIR

Where OUTPUT_DIR is the path to the output directory where you wish to install Patchwork. The compilation process takes around 10 minutes, so please be patient.

The program's binary will be installed to OUTPUT_DIR/bin/patchwork. You may want to create a symbolic link between this file to a file that is in your path, so that you may use Patchwork from anywhere:

$ ln -s OUTPUT_DIR/bin/patchwork /usr/local/bin

Installing Patchwork with Docker

Patchwork is available in the Biocontainers repository on Docker Hub. To pull the Patchwork Image to your PC and run it inside a Docker Container, you must have Docker installed.

Installing Docker

Go to the Docker Docs, select your platform and follow the instructions to set up the Docker repositories and install Docker Engine or Docker Desktop. On Ubuntu, you can use the following commands to install Docker:

Install packages to allow apt access to repositories over HTTPS:

$ sudo apt-get update
$ sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release

Add Docker's official GPG key:

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Set up the stable repository:

$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Then you can install Docker Engine using the following command:

$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io

Verify the installation by running the hello-world image:

$ sudo docker run hello-world

Pulling the Patchwork Image from Docker Hub

To obtain the image from the Biocontainers repository, run:

$ sudo docker pull biocontainers/patchwork:v0.1.2_cv1

This image contains everything you need to run Patchwork inside a Docker Container, i.e. the Patchwork binary itself as well as its runtime dependency DIAMOND. You can have a look at the currently available version tags if you want to pull a specific version of the Patchwork Image. View your available images by running the following command:

$ sudo docker images

Running Patchwork inside a Docker Container

Now that you have the Patchwork Image on your local computer, you can run the program inside a Docker Container. To create a container from the image, modify the following command according to your preferences. The options and flags used in the command will be explained in more detail underneath.

$ sudo docker run -it --name NAME --user $(id -u) \
  --mount type=bind,src=SOURCE,dst=DESTINATION REPO/IMAGE:TAG COMMAND

• -it: The container will start in interactive mode with an open terminal window.
• --name NAME: The name you want to give your container, e.g. patchwork.
• --user $(id -u): This option is necessary if you want to run Patchwork inside the container and e.g. create an output directory that you can access from your local computer afterwards. On your local computer, the files and directories belong to you, and that allows you to modify them. Inside the Docker Container however, the pre- configured user might have a different ID that would prevent them from messing with your files on the host computer. The --user option overrides the pre-configured user; you enter the container with your local user ID. That means you are allowed to change files from your host system that you have access to from inside the container. The files you can access are determined by the next option --mount.
• --mount type=bind,src=SOURCE,dst=DESTINATION: Patchwork requires at least one contigs fasta file and one reference fasta file or database to run. These data are normally not available inside the Docker Container but you can make them accessible with a bind mount. src requires the absolute path to the directory on the host computer that contains your data. dst is the path inside the container that you want to access the data from. So, say your contigs and reference are in src=/home/yourname/data and you set dst=/home/patchwork/data. Then you can access all the files and subdirectories in /home/yourname/data via /home/patchwork/data. To learn more about on bind mounts, see the Docker Docs.Thus, you would call the program like

$ patchwork --contigs /home/patchwork/data/contigs.fa --reference /home/patchwork/data/reference.fa \
  --output-dir /home/patchwork/data/out

• REPO/IMAGE:TAG: The image you would like to use, e.g. biocontainers/patchwork:v0.1.2_cv1. The tag is optional, when omitted the default tag latest will be used.
• COMMAND: The command you want to run whenever the container starts. After executing this command, the container will stop automatically. For example, using bash as a command will keep the container's terminal open and the container running until you type exit. While the container is running, you can enter other commands, e.g. call Patchwork, in the terminal.

The docker run command above will create and start the new Docker Container. If you want to restart the container called patchwork, run

$ sudo docker start patchwork
$ sudo docker attach patchwork

More options for using Docker can be viewed in the help menu:

$ docker --help