Installing SingleM

There are several ways to install SingleM. On the assumption that a standard internet connection speed is available, each of these methods should take substantially less than 1 hour, hopefully less than 15 minutes.

Installation via conda

SingleM can be installed through Bioconda. You can use the default conda if you prefer but we recommend mamba for faster installation and better error messages.

mamba create -c bioconda -c conda-forge --name singlem singlem'>='0.18.3

Test if it works by running

conda activate singlem
singlem -h

After this, you'll also need to procure the reference data (the "metapackage"). See singlem data.

Installation via DockerHub

A docker image generated from the conda package is available on DockerHub. After installing Docker, run the following:

docker pull wwood/singlem:0.18.3

Test if it works by running

docker run wwood/singlem:0.18.3 -h

If the sequence data to be analyzed is in the current working directory, SingleM pipe can be used like so:

docker run -v `pwd`:`pwd` wwood/singlem:0.18.3 pipe --sequences \
    `pwd`/my.fastq.gz -p `pwd`/my.profile.csv --threads 4

Two things to note:

1. The default SingleM reference data is included in the docker image, so running singlem data is not necessary for this installation method - you can jump straight to using pipe.
2. You should not specify singlem in the command line, as this is automatic. Simply use e.g. docker run wwood/singlem:0.18.3 pipe -h.

Installation via Singularity / Apptainer

SingleM can be installed via Singularity or Apptainer. After installing Singularity or Apptainer, run the following:

singularity pull docker://wwood/singlem:0.18.3

Test if it works by running

singularity run singlem_0.18.3.sif -h

If the sequence data to be analyzed is in the current working directory, SingleM pipe can be used like so:

singularity run -B `pwd`:`pwd` singlem_0.18.3.sif pipe --sequences \
    `pwd`/my.fastq.gz -p `pwd`/my.profile.csv --threads 4

Two things to note:

1. The default SingleM reference data is included in the docker image, so running singlem data is not necessary for this installation method - you can jump straight to using pipe.
2. You should not specify singlem in the command line, as this is automatic. Simply use e.g. singularity run singlem_0.18.3.sif pipe -h.

Installation via PyPI

To install the Python libraries required:

pip install singlem

You may need super-user privileges.

SingleM also has several non-Python dependencies, which are documented in the singlem.yml file in the base directory of the repository. You'll also need to procure the reference data (the "metapackage"). See singlem data.

Installation via Github, with conda environment dependencies

SingleM can be installed from source together with its conda dependencies as follows.

git clone https://github.com/wwood/singlem
cd singlem
conda env create -n singlem -f singlem.yml
conda activate singlem
pip install -e .
singlem -h

After this, you'll also need to procure the reference data (the "metapackage"). See singlem data.

Example data

To test the main subcommand of SingleM, pipe works, download a minimal dataset and generate a taxonomic profile like so:

wget 'https://github.com/wwood/singlem/raw/44e1f81404c12931742259088999290edbb271b3/test/data/methanobacteria/genomes/GCA_000309865.1_genomic.fna'
singlem pipe -1 GCA_000309865.1_genomic.fna -p /dev/stdout

This should output a profile similar to the below. When tested, the pipe took a little less than 2 minutes:

sample  coverage        taxonomy
GCA_000309865.1_genomic 0.39    Root; d__Archaea; p__Methanobacteriota; c__Methanobacteria; o__Methanobacteriales; f__Methanobacteriaceae; g__Methanobacterium
08/06/2024 04:50:25 PM INFO: Finished condense

Containerised SingleM installation examples

To ensure that the instructions here work, they have been tested in containerised environments. Logs of this procedure are available at https://github.com/wwood/singlem-installation.