For Bracken news, updates, and instructions: https://ccb.jhu.edu/software/bracken/
Bracken's peer-reviewed paper (published Jan 2, 2017): "Bracken: estimating species abundance in metagenomics data" https://peerj.com/articles/cs-104/
Protocol paper for Kraken 2, Bracken, KrakenUniq, and KrakenTools (published Sept 28, 2022): "Metagenome analysis using the Kraken software suite" https://www.nature.com/articles/s41596-022-00738-y
Bracken is a companion program to Kraken 1, KrakenUniq, or Kraken 2 While Kraken classifies reads to multiple levels in the taxonomic tree, Bracken allows estimation of abundance at a single level using those classifications (e.g. Bracken can estimate abundance of species within a sample).
Prior to installing Bracken, please install Kraken/KrakenUniq/Kraken 2: Kraken can be downloaded from here: http://ccb.jhu.edu/software/kraken/ KrakenUniq can be downloaded from here: https://github.com/fbreitwieser/krakenuniq Kraken 2 can be downloaded from here: https://github.com/DerrickWood/kraken2/
bash install_bracken.sh
cd src/ && make
Add bracken/bracken-build and scripts in src/ to your PATH
IMPORTANT: Bracken is not compatible with mpa-style reports. Bracken requires the default report format from kraken/kraken2.
Bracken 2.9 fixes compatibility for KrakenUniq building of the Bracken database. Input files to be concatenated prior to classification against the full database. NOTE: Multiple Bracken databases cannot exist in the same folder. Files will rewrite. User must use the individual command lines to generate different file extensions per bracken file per kraken version.
Bracken 2.8 provides compatibility for KrakenUniq
Bracken 2.7 addresses a bug in which non-specific genomes previously caused clades to be removed. In a small edit, all reads (including those at abundance level/below) were all redistributed to the genome level prior to being added to the abundance level. This caused any species (for example) to be removed if no genome-specific reads were found. In order to fix this problem, reads will no longer be redistributed if at the abundance level/below. Only higher taxonomy reads will be distributed down.
Bracken 2.5.3 has small changes in options to allow for non-traditional abundance estimation (e.g. S1, G1, K7) and allows specification for naming the kraken-style report with bracken read counts.
Bracken 2.5 has a 30x faster build-time. Previously, 1 million database sequences would take hours to process by Bracken. Now, the same process requires less than 10 minutes (with 16 threads). All output is identical to previous output.
Bracken 2.0 does not introduce any changes in the main algorithm. [Output from Bracken 1.0 is identical to output from Bracken 2.0] However, additional scripts are provided to allow easier/faster installation and execution of the Bracken code.
Users can either run the higher-level scripts now provided, OR follow the individual steps described.
Steps 0/1 are run once per database. If you would like to generate Bracken files for multiple read lengths, repeat Step 1 specifying the same database but different read lengths. The script will skip any step already complete.
If you run Kraken using one of the pre-built databases, bracken-build must also be run using pre-built databases.
Run one of the following depending on your kraken installation:
kraken-build --db ${KRAKEN_DB} --threads ${THREADS}
krakenuniq-build --db ${KRAKEN_DB} --threads ${THREADS}
kraken2-build --db ${KRAKEN_DB} --threads ${THREADS}
${KRAKEN_DB}is the path to a built Kraken database which also must contain:- the taxonomy/nodes.dmp file
- and library sequences
*.fna,*.fa, or*.fastain thelibrarydirectory.
It is highly encouraged for users to run the following scripts with 10-20 threads. [if run single-threaded, kraken/kraken2 and kmer2read_distr will take hours-days] Please note that the flags for this script are single lettered
If Kraken 2 is included in your PATH, run the following
bracken-build -d ${KRAKEN_DB} -t ${THREADS} -k ${KMER_LEN} -l ${READ_LEN}
Otherwise, direct the program using "-x" to the installation/location of the ./kraken or ./kraken2 scripts OR specify the version of kraken being used with the "-y" flag.
bracken-build -d ${KRAKEN_DB} -t ${THREADS} -k ${KMER_LEN} -l ${READ_LEN} -x ${KRAKEN_INSTALLATION} -y ${KRAKEN_TYPE}
`${KRAKEN_DB}` = location of the built Kraken 1/Kraken 2/KrakenUniq database
`${THREADS}` = number of threads to use with Kraken and the Bracken scripts
`${KMER_LEN}` = length of kmer used to build the Kraken database
Kraken 1/KrakenUniq default kmer length = 31
Kraken 2 default kmer length = 35
Default set in the script is 35.
`${READ_LEN}` = the read length of your data
e.g., if you are using 100 bp reads, set it to `100`.
`${KRAKEN_INSTALLATION}` = location of kraken/kraken2/krakenuniq executables
`${KRAKEN_TYPE}` = type of Kraken: kraken, krakenuniq, or kraken2 [default: kraken2]
Kraken 1 requires a 2-step process to generate the report file needed by Bracken
kraken --db ${KRAKEN_DB} --threads ${THREADS} ${SAMPLE}.fq > ${SAMPLE}.kraken
kraken-report --db ${KRAKEN_DB} ${SAMPLE}.kraken > ${SAMPLE}.kreport
Kraken 2 and KrakenUniq requires the addition of the --report flag
krakenuniq --db ${KRAKEN_DB} --threads ${THREADS} --report ${SAMPLE}.kreport ${SAMPLE}.fq > ${SAMPLE}.kraken
kraken2 --db ${KRAKEN_DB} --threads ${THREADS} --report ${SAMPLE}.kreport ${SAMPLE}.fq > ${SAMPLE}.kraken
bracken -d ${KRAKEN_DB} -i ${SAMPLE}.kreport -o ${SAMPLE}.bracken -r ${READ_LEN} -l ${LEVEL} -t ${THRESHOLD}
Run one of the following depending on your kraken installation:
kraken-build --db ${KRAKEN_DB} --threads ${THREADS}
krakenuniq-build --db ${KRAKEN_DB} --threads ${THREADS}
kraken2-build --db ${KRAKEN_DB} --threads ${THREADS}
${KRAKEN_DB}is the path to a built Kraken database which also must contain:- the taxonomy/nodes.dmp file
- and library sequences
*.fna,*.fa, or*.fastain thelibrarydirectory.
- It is highly encouraged for users to run the following scripts with 20 threads.
Run the following scripts WITHIN the Kraken database folder:
find -L library \(-name "*.fna" -o -name "*.fa" -o -name "*.fasta" \) -exec cat {} + > input.fasta
#Run one of the following three commands, depending on your kraken installation/project:
kraken --db=${KRAKEN_DB} --threads=10 input.fasta > database.kraken
krakenuniq --db=${KRAKEN_DB} --threads=10 input.fasta > database.kraken
kraken2 --db=${KRAKEN_DB} --threads=10 input.fasta > database.kraken
rm input.fasta
If users would like Bracken files for krakenuniq AND kraken2 in the same folder, please specify a unique extension for each database.kraken file (e.g. database.kuniq, database.k2)
/src/kmer2read_distr --seqid2taxid ${KRAKEN_DB}/seqid2taxid.map --taxonomy ${KRAKEN_DB}/taxonomy --kraken database.kraken --output database${READ_LEN}mers.kraken
-k ${KMER_LEN} -l ${READ_LEN} -t ${THREADS}
`${KRAKEN_DB}` = location of the built Kraken 1.0 or Kraken 2.0 database
`${THREADS}` = number of threads to use [recommended: 20]
`${KMER_LEN}` = length of kmer used to build the Kraken database
Kraken 1.0 default kmer length = 31
Kraken 2.0 default kmer length = 35
[default: 35]
`${READ_LEN}` = the read length of your data
e.g., if you are using 100 bp reads, set it to `100`.
The kmer distribution file is generated using the following command line:
python generate_kmer_distribution.py -i database${READ_LEN}mers.kraken -o database${READ_LEN}mers.kmer_distrib
Kraken 1 requires a 2-step process to generate the report file needed by Bracken
kraken --db ${KRAKEN_DB} --threads ${THREADS} ${SAMPLE}.fq > ${SAMPLE}.kraken
kraken-report --db ${KRAKEN_DB} ${SAMPLE}.kraken > ${SAMPLE}.kreport
Kraken 2 and KrakenUniq requires the addition of the --report flag
krakenuniq --db ${KRAKEN_DB} --threads ${THREADS} --report ${SAMPLE}.kreport ${SAMPLE}.fq > ${SAMPLE}.kraken
kraken2 --db ${KRAKEN_DB} --threads ${THREADS} --report ${SAMPLE}.kreport ${SAMPLE}.fq > ${SAMPLE}.kraken
Given the expected kmer distribution for genomes in a kraken database along with a kraken report file, the number of reads belonging to each species (or genus) is estimated using the estimate_abundance.py file, run with the following command line:
python est_abundance.py -i ${SAMPLE}.kreport -k database${READ_LEN}mers.kmer_distrib -l ${CLASSIFICATION_LVL} -t ${THRESHOLD} -o ${BRACKEN_OUTPUT_FILE}.bracken
The following required parameters must be specified:
${SAMPLE}.kreport - the kraken report generated for a given dataset- database
${READ_LEN}mers.kmer_distrib - the file generated by generate_kmer_distribution.py {BRACKEN_OUTPUT_FILE}.bracken - the desired name of the output file to be generated by the code
The following optional parameters may be specified:
${CLASSIFICATION_LVL}- Default ='S'. This specifies that abundance estimation will calculate estimated reads for each species. Other possible options are K (kingdom level), P (phylum), C (class), O (order), F (family), and G (genus).${THRESHOLD}- Default =10. For species classification, any species with <= 10 (or otherwise specified) reads will not receive any additional reads from higher taxonomy levels when distributing reads for abundance estimation. If another classification level is specified, thresholding will occur at that level.
By default, this script will also recreate the report file using the new Bracken numbers.
- The new report file will be found in the same folder as the original report file, with "bracken" included in the name.
- Levels below the estimate-level will not be printed.
- Any levels whose reads were below the threshold will not be included
- Percentages will be re-calculated for the remaining levels
- Unclassified reads will not be included in the report.
The following sample input and output files are included in the sample_data/ folder:
sample_test.report - Kraken report file generated from the kraken-report command.
sample_kmer_distr_75mers.txt - example kmer distribution file generated by generate_kmer_distribution.py
sample_output_species_abundance.txt - Bracken species abundance estimation for sample_test.report
sample_output_bracken.report - Kraken report style file with all reads redistributed to the species level
Due to size constraints, the following files are not included in the sample_data/ folder:
sample_test.kraken - Kraken output file used to generate the Kraken report file
database.kraken - Initial Kraken classification of every genome
database75mers.kraken_cnts - Counting of kmer abundances
The following commands were used to generate each individual file:
-
kraken --db${KRAKEN_DB} --threads=10 sample.fa > sample_test.kraken kraken-report --db=${KRAKEN_DB} sample_test.kraken > sample_test.report -
kraken --db=${KRAKEN_DB} --fasta_input --threads=10 <( find -L library -name "*.fna" -o -name "*.fa" -o -name "*.fasta" -exec cat {} + ) > database.kraken perl count-kmer-abubndances.pl --db=${KRAKEN_DB} --read-length=75 database.kraken > database75mers.kraken_cnts -
python generate_kmer_distribution.py -i database75mers.kraken_cnts -o sample_kmer_distr_75mers.txt -
python estimate_abundance.py -i sample_test.report -k sample_kmer_distr_75mers.txt -l S -t 10 -o sample_output_species_abundance.txt
Copyright (C) 2023 Jennifer Lu, jlu26@jhmi.edu
Bracken is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the license, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses/.
Jennifer Lu (jlu26@jhmi.edu, ccb.jhu.edu/people/jennifer.lu)
Florian Breitwieser (fbreitw1@jhu.edu, ccb.jhu.edu/people/florian)
Last Updated On: 10/11/2022
