ARGifier

ARGifier is a Snakemake workflow for assembly-based detection and quantification of antibiotic resistance genes (ARGs) from paired-end metagenomic reads.

What ARGifier does

For each sample, ARGifier can:

1. Trim paired-end reads with Trim Galore.
2. Optionally remove host-derived reads with either Kraken 2 or BWA plus samtools.
3. Assemble decontaminated reads with MEGAHIT or SPAdes.
4. Optionally annotate assembled contigs with Prokka.
5. Detect ARGs with Meta-MARC / mmarc.
6. Extract non-overlapping ARG sequences from Meta-MARC hits.
7. Quantify ARG abundance with either CoverM or Salmon.
8. Add ARG ontology annotations and merge per-sample tables into a final summary table.

Workflow overview

The pipeline implemented in snakefile can be summarized as follows:

Scope and limitations

ARGifier is an assembly-based workflow designed for shotgun metagenomic paired-end reads.

This point is important for manuscript interpretation:

• ARGifier is appropriate when reads can be assembled into contigs and ARG detection is followed by sequence extraction and abundance estimation.
• ARGifier is not a dedicated workflow for hybridization-capture datasets such as myBaits when the experimental design does not support contig assembly and downstream contig-based ARG context analysis.
• If your dataset is capture-enriched and you want read-level target recovery without assembly, the present workflow should be considered outside its intended scope unless you adapt the methodology accordingly.

Repository structure

ARGifier/
|-- snakefile
|-- env.yaml
|-- config/
|   |-- config.yaml
|   |-- config.wp1.yaml
|   |-- config.poolseq.yaml
|   |-- sample.config
|   `-- sample.*.config
`-- scripts/
    |-- extractARGSequences.py
    |-- table_annotation.py
    |-- validate_decontamination_db.py
    |-- host_decontamination.kraken.sh
    |-- host_decontamination.bwa.sh
    `-- KrakenTools/

Requirements

ARGifier was written for a Linux environment with Conda available.

The repository includes env.yaml, but the full workflow also expects several external command-line tools to be installed and available in PATH.

Core tools used by the workflow:

• Snakemake
• Trim Galore
• FastQC
• Kraken 2 or BWA
• samtools when using BWA-based decontamination
• MEGAHIT or SPAdes
• Prokka if metamarc_target: prokka
• Meta-MARC / mmarc
• CoverM or Salmon
• Python packages required by the helper scripts, including pandas and biopython

Installation

Clone the repository:

git clone https://github.com/EBosi/ARGifier.git
cd ARGifier

Create and activate the Conda environment:

conda env create -f env.yaml
conda activate spargify

Install any workflow tools that are not already present in the environment on your system. A practical check is:

which snakemake trim_galore fastqc kraken2 bwa samtools megahit spades.py prokka mmarc coverm salmon

Not every tool is needed for every run. For example:

• bwa and samtools are only needed for BWA-based decontamination.
• kraken2 is only needed for Kraken-based decontamination.
• prokka is only needed when metamarc_target: prokka.
• coverm or salmon are alternatives, not both mandatory for a single run.

Input data

ARGifier expects paired-end FASTQ files and a sample sheet listing the files associated with each sample.

Sample sheet format

The sample sheet is a whitespace-delimited text file referenced by sample_config in the YAML configuration.

Minimal 3-column format:

Sample Index File
SAMPLE_A 1 /absolute/path/SAMPLE_A_R1.fastq.gz
SAMPLE_A 2 /absolute/path/SAMPLE_A_R2.fastq.gz
SAMPLE_B 1 /absolute/path/SAMPLE_B_R1.fastq.gz
SAMPLE_B 2 /absolute/path/SAMPLE_B_R2.fastq.gz

Example with a fourth column indicating samples to decontaminate:

#Sample Index File ToDeHost
SAMPLE_A 1 /absolute/path/SAMPLE_A_R1.fastq.gz 1
SAMPLE_A 2 /absolute/path/SAMPLE_A_R2.fastq.gz 1
SAMPLE_B 1 /absolute/path/SAMPLE_B_R1.fastq.gz 1
SAMPLE_B 2 /absolute/path/SAMPLE_B_R2.fastq.gz 1

Files in config/sample.wp1.config and config/sample.poolseq.config provide real examples.

Configuration

The main run parameters are stored in YAML files under config/.

Important fields used by the workflow include:

OUTDIR: /absolute/path/to/output
sample_config: config/sample.wp1.config
host_decontamination: kraken
decontamination_db: /absolute/path/to/decontamination_db
metamarc_target: prokka
quantification_method: coverm
ARG_ontology: /absolute/path/to/mmarc_model_annotations.tsv
assembler: megahit

Meaning of the main parameters

• OUTDIR: base output directory.
• sample_config: sample sheet listing paired-end FASTQ files.
• host_decontamination: decontamination strategy; expected values are kraken or bwa.
• decontamination_db: Kraken 2 database directory or BWA reference genome, depending on the selected method.
• metamarc_target: sequence set used as input to Meta-MARC; expected values are contigs or prokka.
• quantification_method: expected values are coverm or salmon.
• ARG_ontology: path to the Meta-MARC annotation table, typically mmarc_model_annotations.tsv.
• assembler: expected values are megahit or spades.

The repository contains example configuration files:

• config/config.yaml
• config/config.wp1.yaml
• config/config.poolseq.yaml

Running ARGifier

Basic run

Run the workflow with a chosen configuration file:

snakemake -s snakefile --configfile config/config.wp1.yaml --cores 8

If you prefer to preview the execution graph before starting:

snakemake -s snakefile --configfile config/config.wp1.yaml --cores 8 -n -p

Typical command template

snakemake \
  -s snakefile \
  --configfile config/config.wp1.yaml \
  --cores 8

Choosing major workflow branches

Example settings for a common assembly-based run:

host_decontamination: kraken
assembler: megahit
metamarc_target: prokka
quantification_method: coverm

Alternative settings are possible:

• host_decontamination: bwa
• assembler: spades
• metamarc_target: contigs
• quantification_method: salmon

Expected outputs

The main outputs generated for each sample are:

• OUTDIR/<sample>/trimmed/<sample>.trimmed.R1.fq.gz
• OUTDIR/<sample>/trimmed/<sample>.trimmed.R2.fq.gz
• OUTDIR/<sample>/trimmed/host_decontamination/<sample>.dehosted.R1.fq.gz
• OUTDIR/<sample>/trimmed/host_decontamination/<sample>.dehosted.R2.fq.gz
• OUTDIR/<sample>/assembly/<sample>.contigs.fa
• OUTDIR/<sample>/assembly/prokka/
• OUTDIR/<sample>/ARGs/<sample>.final.tblout.scan
• OUTDIR/<sample>/ARGs/<sample>.ARGs.fasta
• OUTDIR/<sample>/quantification/<sample>.annotated.abundance.tsv

The workflow also produces a merged results table:

• OUTDIR/results.table.tsv

Interpretation of key outputs

• *.contigs.fa: assembled contigs used for downstream ARG discovery.
• *.final.tblout.scan: merged Meta-MARC output across levels 1, 2, and 3.
• *.ARGs.fasta: extracted ARG sequences retained for quantification.
• *.annotated.abundance.tsv: abundance table with ARG ontology annotations added.
• results.table.tsv: concatenated table across samples.

External resources referenced by the workflow

The current implementation uses or expects the following external resources:

• A host-decontamination database for either Kraken 2 or BWA.
• A Meta-MARC ontology table, usually mmarc_model_annotations.tsv.
• Paired-end shotgun metagenomic FASTQ files for each sample.

Reproducibility notes

To make a run easier to reproduce in a manuscript or methods supplement, report at least:

1. The exact Git commit of ARGifier used.
2. The YAML configuration file used for the run.
3. The sample sheet used for the run.
4. The versions of Snakemake and all external tools selected in that run.
5. The decontamination database and Meta-MARC annotation table versions.

Current caveats

This README documents the workflow currently implemented in the repository. Users should be aware of the following:

• The pipeline assumes paired-end input reads.
• The workflow is assembly-based and therefore depends on successful contig generation.
• Several tools are called from PATH, so environment validation before launch is recommended.
• The repository currently ships example configuration files, but no bundled test dataset.

Suggested citation text for methods sections

If you need concise manuscript wording, the implemented workflow can be described as:

The resistome of European coastal environments revealed by high-resolution targeted metagenomics in Oysters

Contact

If you use or adapt ARGifier, please open an issue or fork the repository to document changes for downstream users.