Sunbeam Metagenomic Sequencing Pipeline

Sunbeam is a robust, extensible metagenomic sequencing pipeline built on snakemake. It automates various stages of metagenomic analysis, including quality control, taxonomic assignment, assembly, and mapping. It is designed to be modular, allowing users to extend its functionality using specialized modules (e.g., sbx_kraken, sbx_assembly).

Sunbeam automates the following core tasks:

• Quality control: Includes adapter trimming, host read removal, and quality filtering.
• Taxonomic assignment: Assigns reads to databases using Kraken (via sbx_kraken).
• Assembly: Assembles reads into contigs using Megahit (via sbx_assembly).
• Contig annotation: Uses BLAST[n/p/x] and Diamond (via sbx_assembly).
• Mapping: Maps to reference genomes (via sbx_mapping).
• ORF prediction: Predicts Open Reading Frames using Prodigal (via sbx_assembly).

Use sunbeam init to create a new project directory. You must provide the path to your sequencing reads using the --data_fp flag. Reads must be in .fastq.gz format.

Initialization Modes:

• Standard: Uses Conda for local compute.
• Slurm: Uses a Slurm cluster (requires snakemake-executor-plugin-slurm installed). Use --profile slurm.
• Apptainer/Singularity: Uses Apptainer/Singularity for local compute. Use --profile apptainer.
• Docker: Run inside a container. You must mount local data and output directories using -v flags. Paths in the command must correspond to the paths inside the container.

Project Output: Initialization creates a project folder containing:

• config.yaml: A Snakemake profile for running the project.
• sunbeam_config.yml: Configuration parameters for each pipeline step.
• samples.csv: A list of discovered samples and their absolute paths to FASTQ files.

### Standard (Conda, local)
sunbeam init my_project --data_fp /sequencing/project/reads

### Slurm
pip install snakemake-executor-plugin-slurm
sunbeam init my_project --data_fp /sequencing/project/reads --profile slurm

### Apptainer/Singularity
sunbeam init my_project --data_fp /sequencing/project/reads --profile apptainer

### Docker
docker run --rm -v /local/path/to/data/:/data/ -v /local/path/to/outputs/:/projects/ sunbeamlabs/sunbeam:latest sunbeam init --data_fp /data/reads/ /projects/my_project

Sunbeam can be installed via pip, conda, git, or Docker.

Requirements:

• Python 3.11+ for pip installation.
• Gzipped FASTQ format (.fastq.gz) for sequencing reads.

Installation Methods:

• pip: Install sunbeamlib from PyPI into a virtual environment.
• conda: Install sunbeamlib from the conda-forge and bioconda channels.
• git: Clone the repository and install in editable mode. Use .[dev] to include development dependencies.
• Docker: Pull the sunbeamlabs/sunbeam:latest image. There is also a slim version that requires manual conda environment management.

### pip
python -m venv --python=python3.13 sunbeam_env/
source sunbeam_env/bin/activate
pip install sunbeamlib

### conda
conda create --name sunbeam_env -c conda-forge -c bioconda sunbeamlib
conda activate sunbeam_env

### git
git clone https://github.com/sunbeam-labs/sunbeam.git
cd sunbeam
python -m venv --python=python3.13 sunbeam_env/
source sunbeam_env/bin/activate
pip install -e .[dev]

### docker
docker pull sunbeamlabs/sunbeam:latest
docker run --rm sunbeamlabs/sunbeam:latest sunbeam -h

Extensions use Snakemake format to define how files are processed. A complete extension usually requires three components:

1. Rules File (.smk): Defines the workflow logic, including target rules (the desired outputs) and runner rules (the actual execution steps).
2. Configuration (config.yml): Defines parameters required by your rules.
3. Environment (envs/*.yml): Specifies the Conda environment needed to run the tool.

Example: Adding a tool (AwesomeTool)

To add a tool that takes input FASTQ files and a database to produce an output, your .smk file would look like this:

AWESOME_FP = CLASSIFY_FP / 'awesome'

rule all_awesome_tool:
    input:
        expand(AWESOME_FP / "{sample}.awesome", sample=Samples.keys())

rule run_awesome_tool:
    input:
        r1 = QC_FP / "decontam" / "{sample}_1.fastq.gz",
        r2 = QC_FP / "decontam" / "{sample}_2.fastq.gz",
        db = Cfg['all']['awesome_db']
    output:
        AWESOME_FP / "{sample}.awesome"
    conda:
        "awesome_env.yaml"
    shell:
        """
        AwesomeTool -i {input.r1} -d {input.db} -o {output}
        """

Configuration and Environment

Update your config.yml to include the new parameters:

sbx_awesome_tool:
    awesome_db: /path/to/awesome_db

And define the Conda environment in envs/sbx_awesome_tool_env.yml:

name: awesome_env
channels:
    - bioconda
    - conda-forge
dependencies:
    - awesome_tool