aomlomics/tourmaline repository overview

⁠About Tourmaline

Tourmaline is an amplicon sequence processing workflow for Illumina sequence data that uses QIIME 2⁠ and the software packages it wraps. Tourmaline manages commands, inputs, and outputs using the Snakemake⁠ workflow management system.

Full instructions for using Tourmaline are at github.com/aomlomics/tourmaline⁠.

⁠Running Tourmaline using Docker

⁠Docker Desktop

Make sure Docker is installed on your system. If you are using a laptop or desktop machine, you can install⁠ Docker Desktop (Mac or Windows) or Docker (Linux). If you are on a compute cluster, you may need to contact your system administrator. This command will list your Docker images and make sure the Docker daemon is running:

docker images

Make sure Docker has enough memory. On Docker for Mac, the default memory is 2 GB. Go to Preferences -> Resources -> Advanced -> Memory and increase the maximum memory to 8 GB or more if possible.

⁠Docker image

Download the Docker image from DockerHub:

docker pull aomlomics/tourmaline

List your Docker images again to make sure the tourmaline image is there:

docker images

⁠Docker container

Now create and run a container:

docker run -v $HOME:/data -it aomlomics/tourmaline

Note that symbolic links in a mounted volume will not work.

⁠External files

The -v (volume) flag above allows you to mount a local file system volume (in this case your home directory) to read/write from your container. Note that symbolic links in a mounted volume will not work.

Use mounted volumes to:

• copy metadata and manifest files to your container;
• create symbolic links from your container to your FASTQ files and reference database;
• copy your whole Tourmaline directory out of the container when the run is completed (alternatively, you can clone the Tourmaline directory inside the mounted volume).

To access files that aren't on a mounted volume, from outside the container (running or not), use these commands:

docker cp container:source_path destination_path # container to file system
docker cp source_path container:destination_path # file system to container

⁠Common errors

If you get an error "Plugin error from feature-classifier: Command ... died with <Signals.SIGKILL: 9>.", this means your Docker container ran out of memory. Go to Preferences -> Resources -> Advanced -> Memory and increase the maximum memory to 8 GB or more if possible.

⁠Restart a container

You can stop a container by typing exit. The container will still be running.

See all your containers with this command:

docker ps -a

Start a container using its container ID or name with this command:

docker start -ia CONTAINER

⁠Remove containers and images

Remove a Docker container:

docker container rm CONTAINER

Remove a Docker image:

docker rmi IMAGE

Remove all stopped containers, all networks not used by at least one container, all images without at least one container associated to them, and all build cache:

docker system prune -a

⁠License

This docker image is based on a QIIME 2 Docker image hosted at https://quay.io/repository/qiime2/core?tag=2021.2⁠. The QIIME 2 license can be found at https://github.com/qiime2/qiime2/blob/master/LICENSE⁠.