[meta]
name = "bracken"
category = "metagenomics"
description = "Bayesian re-estimation of abundance from Kraken2 reports for accurate species-level quantification"
tags = ["metagenomics", "taxonomy", "abundance", "bracken", "microbiome", "species", "kraken2"]
author = "oxo-call built-in"
source_url = "https://github.com/jenniferlu717/Bracken"

[context]
concepts = [
    "Bracken re-estimates species-level abundances from Kraken2 output using a Bayesian framework for better accuracy.",
    "Bracken requires the same database used for Kraken2 AND a Bracken distribution file (databaseXmers.kmer_distrib).",
    "Key parameters: -l SPECIES (taxonomic level: S=species, G=genus, F=family, O=order, C=class, P=phylum).",
    "Use -r to specify the read length used for the Bracken database (must match kmer_distrib file).",
    "Use -t to set minimum reads threshold — taxa with fewer reads are excluded from re-estimation.",
    "Output: Bracken report (.bracken) with adjusted read counts and new fractions.",
    "combine_bracken_outputs.py merges Bracken results from multiple samples into one table.",
]

pitfalls = [
    "The Bracken distribution file must match the read length and database used for Kraken2 classification.",
    "Bracken requires the Kraken2 report file (--report from Kraken2), not the per-read output.",
    "Using wrong -l (taxonomic level) collapses counts at wrong level — use S for species-level microbiome analysis.",
    "Bracken may give incorrect results if the Kraken2 database was built differently than the Bracken kmer_distrib.",
    "Low -t (minimum threshold) includes many low-confidence taxa; too high -t excludes rare species.",
    "Bracken is a post-processing step — it requires Kraken2 classification first.",
]

[[examples]]
task = "run Bracken on a Kraken2 report for species-level abundance estimation"
args = "-d /path/to/kraken2_db -i kraken_report.txt -o bracken_output.bracken -l S -r 150 -t 10"
explanation = "-d database path; -i Kraken2 report; -o output; -l S species level; -r 150 bp read length; -t 10 minimum reads"

[[examples]]
task = "run Bracken for genus-level abundance estimation"
args = "-d /path/to/kraken2_db -i kraken_report.txt -o bracken_genus.bracken -l G -r 150 -t 5"
explanation = "-l G genus level; lower -t 5 to include more genera"

[[examples]]
task = "combine Bracken results from multiple samples into one table"
args = "--files sample1.bracken sample2.bracken sample3.bracken --output combined_abundance.txt"
explanation = "combine_bracken_outputs.py merges multiple Bracken outputs; requires Bracken utility scripts"

[[examples]]
task = "run Bracken on short reads (75 bp)"
args = "-d /path/to/kraken2_db -i kraken_report.txt -o bracken_75bp.bracken -l S -r 75 -t 10"
explanation = "-r 75 specifies 75 bp read length; must match the kmer_distrib file in the database"
