alartin / bracken Goto Github PK

BRACKEN ABUNDANCE ESTIMATION
=============================

Step 1: Classify all reads using Kraken (http://ccb.jhu.edu/software/kraken/) and Generate a Kraken report file.   

Three steps are necessary to set up Kraken abundance estimation. It is assumed that
${KRAKEN_DB} is the path to a built Kraken database, and all sequences are as '.fna' files in the
${KRAKEN_DB}/library directory.

Step 2a: Search all library input sequences against the database

    kraken --db=${KRAKEN_DB} --fasta-input --threads=10 <( find -L library -name "*.fna" -o -name "*.fa" -o -name "*.fasta" -exec cat {} + )  > database.kraken

Step 2b: Compute the classifications for each perfect read of ${READ_LENGTH} base pairs from one of the input sequences.
With ${READ_LENGTH} = 75:

    perl count-kmer-abundances.pl --db=${KRAKEN_DB} --read-length=75 database.kraken  > database75mers.kraken_cnts

Step 3: Generate the kmer distribution file using the following command line:
    
    python generate_kmer_distribution.py -i database75mers.kraken_cnts -o KMER_DISTR.TXT

Step 4: 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 estimate_abundance.py -i KRAKEN.REPORT -k KMER_DISTR.TXT -l
      CLASSIFICATON_LEVEL -t THRESHOLD -o OUTPUT_FILE.TXT

The following required parameters must be specified:
- KRAKEN.REPORT     :: the kraken report generated for a given dataset 
- KMER_DISTR.TXT    :: the file generated by generate_kmer_distribution.py 
- OUTPUT_FILE.TXT   :: the desired name of the output file to be generated by the code

The following optional parameters may be specified:
- CLASSIFICATION_LEVEL  :: [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.  

============================
EXAMPLE ABUNDANCE ESTIMATION
============================
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: 

Step 1:
    kraken --db${KRAKEN_DB} --threads=10 sample.fa > sample_test.kraken
    kraken-report --db=${KRAKEN_DB} sample_test.kraken > sample_test.report 

Step 2:
    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

Step 3:
    python generate_kmer_distribution.py -i database75mers.kraken_cnts -o sample_kmer_distr_75mers.txt

Step 4: 
    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 AND LICENSING
=======================
Copyright (C) 2016 Jennifer Lu, [email protected]

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/>.
    
==================
AUTHOR INFORMATION
==================
Jennifer Lu ([email protected])
Florian Breitwieser ([email protected])
Last Updated On: 08/17/2016