Skip to content

1. Usage

Jump to bottom
Karla Vasco edited this page Jun 26, 2026 · 1 revision

🚀 Pipeline Usage

This page describes how to run BaSSeT and prepare the required input files.

1️⃣ Requirements

Install the following software:

Container cache setup

For Apptainer or Singularity, use a persistent shared cache directory so container images can be reused across runs and accessed by all compute nodes.

For Apptainer:

export NXF_APPTAINER_CACHEDIR=/path/to/shared/nextflow/apptainer/cache

For Singularity:

export NXF_SINGULARITY_CACHEDIR=/path/to/shared/nextflow/singularity/cache

You can also set these paths in your Nextflow configuration using apptainer.cacheDir or singularity.cacheDir.

Optional: prefetch containers

For Apptainer and Singularity users, we recommend pre-pulling all required BaSSeT container images before launching the workflow. This helps avoid issues caused by multiple Nextflow tasks pulling images concurrently, such as race conditions or incomplete cache files.

Helper scripts are provided:

For Apptainer:

export NXF_APPTAINER_CACHEDIR=/path/to/shared/nextflow/apptainer/cache
bash prefetch_basset_containers_apptainer.sh

For Singularity:

export NXF_SINGULARITY_CACHEDIR=/path/to/shared/nextflow/singularity/cache
bash prefetch_basset_containers_singularity.sh

Note

NXF_APPTAINER_CACHEDIR and NXF_SINGULARITY_CACHEDIR control where Nextflow stores SIF images. Apptainer and Singularity also have their own OCI/layer caches, such as APPTAINER_CACHEDIR and SINGULARITY_CACHEDIR, which are mainly used while pulling or converting OCI images.

2️⃣ Prepare the samplesheet

The pipeline requires a CSV samplesheet describing the samples to analyze.

Specify the file using:

--input samplesheet.csv

Each row corresponds to one isolate/sample.

📥 Samplesheet Specification

The samplesheet must contain 5 columns with the following headers.

Column Description
sample Unique sample identifier. Spaces in sample names are automatically converted to underscores (_). No symbols other than hyphens (-) or underscores (_) are allowed
fastq_1 Full path to FastQ file for Illumina or Nanopore QC trimmed reads 1. File has to be gzipped and have the extension .fastq.gz or .fq.gz. (leave empty if not available)
fastq_2 Full path to FastQ file for Illumina QC trimmed short reads 2. File has to be gzipped and have the extension .fastq.gz or .fq.gz. (leave empty for single-end, ONT or assemblies)
assembly Full path to assembled genome file. File can be gzipped and have the extension .fasta, .fa, .fas, .fna, .fasta.gz, .fa.gz, .fas.gz or .fna.gz
organism Supported organism name (can be Other if running ABRicate for any other species). Spaces in organism are automatically converted to underscores (_).

Supported input types

Important

All columns must still be present in the CSV file.

Important

  • Most analyses require assemblies as input. However, tools such as el_gato and SeqSero2 may provide more accurate results when reads are supplied.
  • Reads are required for ShigaTyper, SeroBA, and ARIBA. If reads are not provided for a sample, these analyses will be skipped for that sample.

Note

If the reads are from ONT, add the flag --ont when running your analyses. ONT reads are only supported for ECTyper, SeqSero2, and ShigaTyper

Example samplesheet

sample,fastq_1,fastq_2,assembly,organism
SAMPLE_1,/path/S1_R1.fastq.gz,/path/S1_R2.fastq.gz,/path/S1.fasta,Vibrio_cholerae
SAMPLE_2,/path/S2_R1.fastq.gz,/path/S2_R2.fastq.gz,/path/S2.fasta,Shigella
SAMPLE_3,/path/S3.fastq.gz,,/path/S3.fasta,Salmonella
SAMPLE_4,,,/path/S4.fasta,Escherichia_coli

An example samplesheet is available in assets/samplesheet.csv

Supported inputs per tool

Organism Tool Aim fastq1 fastq2 Assembly
Acinetobacter baumannii Kaptive with Wyres et. al database Serotyping based on K and OC antigens - - ✔️
Escherichia coli ECTyper Serotyping based on O/H antigens; optional pathotyping (only when using --ecoli_pathotypes) Fallback ⚠️ (only when ONT) - Preferred ✔️
Haemophilus influenzae HICap Serotyping based on cap locus (a–f) - - ✔️
Klebsiella pneumoniae complex Kleborate Serotyping (K/O), MLST, virulence genes - - ✔️
Legionella pneumophila el_gato Sequence‑based typing (SBT) Preferred ✔️ Preferred ✔️ Fallback ⚠️
Legionella pneumophila ABRicate with ReporType databases O‑antigen serogrouping (wzm/wzt) and subsepcies - - ✔️
Listeria monocytogenes LisSero Serogrouping/serotyping (O/H) - - ✔️
Neisseria gonorrhoeae NGMASTER porB/tbpB typing; AMR typing - - ✔️
Neisseria meningitidis meningotype Serogrouping (capsule); MLST; BAST; MenDeVAR - - ✔️
Pseudomonas aeruginosa Pasty Serotyping based on O antigen - - ✔️
Salmonella SeqSero2 Serotyping and antigenic profile Preferred ✔️ (can be ONT) Preferred ✔️ (optional for single-end or ONT) Fallback ⚠️
Salmonella SISTR Serovar prediction via antigen genes + cgMLST - - ✔️
Shigella ShigaTyper Serotyping + ipaB ✔️ (can be ONT) ✔️ (optional for single-end or ONT) -
Shigella ShigEiFinder Shigella/EIEC diff.; serotyping; virulence plasmid Fallback ⚠️ Fallback ⚠️ Preferred ✔️
Staphylococcus aureus AgrVATE agr locus typing - - ✔️
Staphylococcus aureus sccmec SCCmec cassette typing - - ✔️
Staphylococcus aureus spaTyper spa repeat typing - - ✔️
Streptococcus dysgalactiae emmtyper emm type assignment - - ✔️
Streptococcus pneumoniae pbptyper PBP typing - - ✔️
Streptococcus pneumoniae SeroBA Serotyping via cps locus ✔️ ✔️ -
Streptococcus pyogenes emmtyper emm type assignment - - ✔️
Vibrio parahaemolyticus Kaptive with Zomer Lab databases K/O serotyping - - ✔️
Vibrio cholerae ARIBA Detect ctxA, ctxB, tcpA, rstR ✔️ ✔️ -
Vibrio cholerae Kaptive with VicPred OAGC database O‑antigen serotyping - - ✔️
All organisms / Other ABRicate Locus detection, any db via --abricate_db - - ✔️

ABRicate bundles multiple databases for the detection of resistance determinants and virulence factors. This tool is optional and available for any organism in the sample sheet when using --abricate_db <database>. Only one database can be used per run:

Database Description Gene Types
argannot Antibiotic resistance gene annotation AMR genes
bacmet2 Bacterial biocide & metal resistance genes Metal/biocide resistance
card Comprehensive Antibiotic Resistance Database AMR genes
ecoh E. coli virulence genes (subset) Virulence factors
ecoli_vf Expanded E. coli virulence gene set Virulence factors
megares Antibiotic resistance ontology AMR genes
ncbi NCBI AMRFinder+ gene set AMR genes
plasmidfinder Plasmid replicon typing Plasmid replicons
resfinder Resistance gene detection AMR genes
upec_expec_vf UPEC/ExPEC virulence markers Virulence factors
vfdb Virulence Factor Database Virulence genes
victors Bacterial virulence database Virulence genes

▶ Running the Pipeline

Basic run

nextflow run MDHHS-Bioinformatics/basset \
  -profile singularity \
  --input samplesheet.csv \
  --outdir basset_results

This will execute typing analysis for the supported organisms.

Note

This command downloads this pipeline to ~/.nextflow/assets/MDHHS-Bioinformatics/basset. You can download the pipeline in a different location using git clone https://github.com/MDHHS-Bioinformatics/basset.git. To run the pipeline, specify the path to the cloned repository (e.g. nextflow run /path/to/basset ...).

Advanced run

Example enabling optional analyses (ABRicate and E. coli pathotyping with ECTyper) and adjusting resources:

nextflow run MDHHS-Bioinformatics/basset \
  -profile apptainer \
  --input samplesheet.csv \
  --outdir basset_results \
  --abricate_db vfdb \
  --ecoli_pathotypes \
  --max_memory 50.GB \
  --max_cpus 8 \
  --max_time 4.h

📂 Pipeline Outputs

The pipeline produces the following directories:

work/          # Nextflow working directory
<outdir>/      # Final pipeline outputs
.nextflow.log  # Execution log

The work/ directory contains intermediate files and may be deleted after successful completion.

🧠 Best practices & caveats

  • Use high-quality sequences: Ideally, assemblies should have <500 contigs ≥500 bp, reads ≥30× Illumina coverage, and no contamination. Pipelines like PHoeNIX, Bactopia and TheiaProk provide quality checks.

  • Disk cleanup: After the pipeline completes, you may safely remove the Nextflow work/ directory to reclaim space.

  • HICap may fail when no cap is detected. Therefore, HICap errors are ignored. In these cases, you may see the following message:

    -[MDHHS-Bioinformatics/basset] Pipeline completed successfully, but with errored process(es)-
[xxxx/yyyyy] NOTE: Process `BASSET:HICAP (<sample>)` terminated with an error exit status (1) -- Error is ignored

    If this occurs, HICAP results cannot be reported.

🔁 Reproducibility

For reproducible analyses, run a specific pipeline release:

nextflow run MDHHS-Bioinformatics/basset \
  -r v1.0.0 \
  -profile singularity \
  --input samplesheet.csv \
  --outdir results

Using version tags ensures the same pipeline code and container versions are used.

🔄 Updating the Pipeline

Nextflow caches pipeline code locally.

To update to the latest version:

nextflow pull MDHHS-Bioinformatics/basset

Clone this wiki locally