Introduction ============ What is Centrifuge? ----------------- [Centrifuge] is a novel microbial classification engine that enables rapid, accurate, and sensitive labeling of reads and quantification of species on desktop computers. The system uses a novel indexing scheme based on the Burrows-Wheeler transform (BWT) and the Ferragina-Manzini (FM) index, optimized specifically for the metagenomic classification problem. Centrifuge requires a relatively small index (5.8 GB for all complete bacterial and viral genomes plus the human genome) and classifies sequences at a very high speed, allowing it to process the millions of reads from a typical high-throughput DNA sequencing run within a few minutes. Together these advances enable timely and accurate analysis of large metagenomics data sets on conventional desktop computers. [Centrifuge]: http://www.ccb.jhu.edu/software/centrifuge [Burrows-Wheeler Transform]: http://en.wikipedia.org/wiki/Burrows-Wheeler_transform [FM Index]: http://en.wikipedia.org/wiki/FM-index [GPLv3 license]: http://www.gnu.org/licenses/gpl-3.0.html Obtaining Centrifuge ================== Download Centrifuge and binaries from the Releases sections on the right side. Binaries are available for Intel architectures (`x86_64`) running Linux, and Mac OS X. Building from source -------------------- Building Centrifuge from source requires a GNU-like environment with GCC, GNU Make and other basics. It should be possible to build Centrifuge on most vanilla Linux installations or on a Mac installation with [Xcode] installed. Centrifuge can also be built on Windows using [Cygwin] or [MinGW] (MinGW recommended). For a MinGW build the choice of what compiler is to be used is important since this will determine if a 32 or 64 bit code can be successfully compiled using it. If there is a need to generate both 32 and 64 bit on the same machine then a multilib MinGW has to be properly installed. [MSYS], the [zlib] library, and depending on architecture [pthreads] library are also required. We are recommending a 64 bit build since it has some clear advantages in real life research problems. In order to simplify the MinGW setup it might be worth investigating popular MinGW personal builds since these are coming already prepared with most of the toolchains needed. First, download the [source package] from the Releases secion on the right side. Unzip the file, change to the unzipped directory, and build the Centrifuge tools by running GNU `make` (usually with the command `make`, but sometimes with `gmake`) with no arguments. If building with MinGW, run `make` from the MSYS environment. Centrifuge is using the multithreading software model in order to speed up execution times on SMP architectures where this is possible. On POSIX platforms (like linux, Mac OS, etc) it needs the pthread library. Although it is possible to use pthread library on non-POSIX platform like Windows, due to performance reasons Centrifuge will try to use Windows native multithreading if possible. For the support of SRA data access in HISAT2, please download and install the [NCBI-NGS] toolkit. When running `make`, specify additional variables as follow. `make USE_SRA=1 NCBI_NGS_DIR=/path/to/NCBI-NGS-directory NCBI_VDB_DIR=/path/to/NCBI-NGS-directory`, where `NCBI_NGS_DIR` and `NCBI_VDB_DIR` will be used in Makefile for -I and -L compilation options. For example, $(NCBI_NGS_DIR)/include and $(NCBI_NGS_DIR)/lib64 will be used. [Cygwin]: http://www.cygwin.com/ [MinGW]: http://www.mingw.org/ [MSYS]: http://www.mingw.org/wiki/msys [zlib]: http://cygwin.com/packages/mingw-zlib/ [pthreads]: http://sourceware.org/pthreads-win32/ [GnuWin32]: http://gnuwin32.sf.net/packages/coreutils.htm [Xcode]: http://developer.apple.com/xcode/ [Github site]: https://github.com/infphilo/centrifuge [NCBI-NGS]: https://github.com/ncbi/ngs/wiki/Downloads Running Centrifuge ============= Adding to PATH -------------- By adding your new Centrifuge directory to your [PATH environment variable], you ensure that whenever you run `centrifuge`, `centrifuge-build`, `centrifuge-download` or `centrifuge-inspect` from the command line, you will get the version you just installed without having to specify the entire path. This is recommended for most users. To do this, follow your operating system's instructions for adding the directory to your [PATH]. If you would like to install Centrifuge by copying the Centrifuge executable files to an existing directory in your [PATH], make sure that you copy all the executables, including `centrifuge`, `centrifuge-class`, `centrifuge-build`, `centrifuge-build-bin`, `centrifuge-download` `centrifuge-inspect` and `centrifuge-inspect-bin`. Furthermore you need the programs in the scripts/ folder if you opt for genome compression in the database construction. [PATH environment variable]: http://en.wikipedia.org/wiki/PATH_(variable) [PATH]: http://en.wikipedia.org/wiki/PATH_(variable) Before running Centrifuge ----------------- Classification is considerably different from alignment in that classification is performed on a large set of genomes as opposed to on just one reference genome as in alignment. Currently, an enormous number of complete genomes are available at the GenBank (e.g. >4,000 bacterial genomes, >10,000 viral genomes, …). These genomes are organized in a taxonomic tree where each genome is located at the bottom of the tree, at the strain or subspecies level. On the taxonomic tree, genomes have ancestors usually situated at the species level, and those ancestors also have ancestors at the genus level and so on up the family level, the order level, class level, phylum, kingdom, and finally at the root level. Given the gigantic number of genomes available, which continues to expand at a rapid rate, and the development of the taxonomic tree, which continues to evolve with new advancements in research, we have designed Centrifuge to be flexible and general enough to reflect this huge database. We provide several standard indexes that will meet most of users’ needs (see the side panel - Indexes). In our approach our indexes not only include raw genome sequences, but also genome names/sizes and taxonomic trees. This enables users to perform additional analyses on Centrifuge’s classification output without the need to download extra database sources. This also eliminates the potential issue of discrepancy between the indexes we provide and the databases users may otherwise download. We plan to provide a couple of additional standard indexes in the near future, and update the indexes on a regular basis. We encourage first time users to take a look at and follow a `small example` that illustrates how to build an index, how to run Centrifuge using the index, how to interpret the classification results, and how to extract additional genomic information from the index. For those who choose to build customized indexes, please take a close look at the following description. Database download and index building ----------------- Centrifuge indexes can be built with arbritary sequences. Standard choices are all of the complete bacterial and viral genomes, or using the sequences that are part of the BLAST nt database. Centrifuge always needs the nodes.dmp file from the NCBI taxonomy dump to build the taxonomy tree, as well as a sequence ID to taxonomy ID map. The map is a tab-separated file with the sequence ID to taxonomy ID map. To download all of the complete archaeal, viral, and bacterial genomes from RefSeq, and build the index: Centrifuge indices can be build on arbritary sequences. Usually an ensemble of genomes is used - such as all complete microbial genomes in the RefSeq database, or all sequences in the BLAST nt database. To map sequence identifiers to taxonomy IDs, and taxonomy IDs to names and its parents, three files are necessary in addition to the sequence files: - taxonomy tree: typically nodes.dmp from the NCBI taxonomy dump. Links taxonomy IDs to their parents - names file: typically names.dmp from the NCBI taxonomy dump. Links taxonomy IDs to their scientific name - a tab-separated sequence ID to taxonomy ID mapping When using the provided scripts to download the genomes, these files are automatically downloaded or generated. When using a custom taxonomy or sequence files, please refer to the section `TODO` to learn more about their format. ### Building index on all complete bacterial and viral genomes Use `centrifuge-download` to download genomes from NCBI. The following two commands download the NCBI taxonomy to `taxonomy/` in the current directory, and all complete archaeal, bacterial and viral genomes to `library/`. Low-complexity regions in the genomes are masked after download (parameter `-m`) using blast+'s `dustmasker`. `centrifuge-download` outputs tab-separated sequence ID to taxonomy ID mappings to standard out, which are required by `centrifuge-build`. centrifuge-download -o taxonomy taxonomy centrifuge-download -o library -m -d "archaea,bacteria,viral" refseq > seqid2taxid.map To build the index, first concatenate all downloaded sequences into a single file, and then run `centrifuge-build`: cat library/*/*.fna > input-sequences.fna ## build centrifuge index with 4 threads centrifuge-build -p 4 --conversion-table seqid2taxid.map \ --taxonomy-tree taxonomy/nodes.dmp --name-table taxonomy/names.dmp \ input-sequences.fna abv After building the index, all files except the index *.[123].cf files may be removed. If you also want to include the human and/or the mouse genome, add their sequences to the library folder before building the index with one of the following commands: After the index building, all but the *.[123].cf index files may be removed. I.e. the files in the `library/` and `taxonomy/` directories are no longer needed. ### Adding human or mouse genome to the index The human and mouse genomes can also be downloaded using `centrifuge-download`. They are in the domain "vertebrate_mammalian" (argument `-d`), are assembled at the chromosome level (argument `-a`) and categorized as reference genomes by RefSeq (`-c`). The argument `-t` takes a comma-separated list of taxonomy IDs - e.g. `9606` for human and `10090` for mouse: # download mouse and human reference genomes centrifuge-download -o library -d "vertebrate_mammalian" -a "Chromosome" -t 9606,10090 -c 'reference genome' refseq >> seqid2taxid.map # only human centrifuge-download -o library -d "vertebrate_mammalian" -a "Chromosome" -t 9606 -c 'reference genome' refseq >> seqid2taxid.map # only mouse centrifuge-download -o library -d "vertebrate_mammalian" -a "Chromosome" -t 10090 -c 'reference genome' refseq >> seqid2taxid.map ### nt database NCBI BLAST's nt database contains all spliced non-redundant coding sequences from multiplpe databases, inferred from genommic sequences. Traditionally used with BLAST, a download of the FASTA is provided on the NCBI homepage. Building an index with any database requires the user to creates a sequence ID to taxonomy ID map that can be generated from a GI taxid dump: wget ftp://ftp.ncbi.nih.gov/blast/db/FASTA/nt.gz gunzip nt.gz && mv -v nt nt.fa # Get mapping file wget ftp://ftp.ncbi.nih.gov/pub/taxonomy/gi_taxid_nucl.dmp.gz gunzip -c gi_taxid_nucl.dmp.gz | sed 's/^/gi|/' > gi_taxid_nucl.map # build index using 16 cores and a small bucket size, which will require less memory centrifuge-build -p 16 --bmax 1342177280 --conversion-table gi_taxid_nucl.map \ --taxonomy-tree taxonomy/nodes.dmp --name-table taxonomy/names.dmp \ nt.fa nt ### Custom database To build a custom database, you need the provide the follwing four files to `centrifuge-build`: - `--conversion-table`: tab-separated file mapping sequence IDs to taxonomy IDs. Sequence IDs are the header up to the first space or second pipe (`|`). - `--taxonomy-tree`: `\t|\t`-separated file mapping taxonomy IDs to their parents and rank, up to the root of the tree. When using NCBI taxonomy IDs, this will be the `nodes.dmp` from `ftp://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz`. - `--name-table`: '\t|\t'-separated file mapping taxonomy IDs to a name. A further column (typically column 4) must specify `scientific name`. When using NCBI taxonomy IDs, `names.dmp` is the appropriate file. - reference sequences: The ID of the sequences are the header up to the first space or second pipe (`|`) When using custom taxonomy IDs, use only positive integers greater-equal to `1` and use `1` for the root of the tree. #### More info on `--taxonomy-tree` and `--name-table` The format of these files are based on `nodes.dmp` and `names.dmp` from the NCBI taxonomy database dump. - Field terminator is `\t|\t` - Row terminator is `\t|\n` The `taxonomy-tree` / nodes.dmp file consists of taxonomy nodes. The description for each node includes the following fields: tax_id -- node id in GenBank taxonomy database parent tax_id -- parent node id in GenBank taxonomy database rank -- rank of this node (superkingdom, kingdom, ..., no rank) Further fields are ignored. The `name-table` / names.dmp is the taxonomy names file: tax_id -- the id of node associated with this name name_txt -- name itself unique name -- the unique variant of this name if name not unique name class -- (scientific name, synonym, common name, ...) `name class` **has** to be `scientific name` to be included in the build. All other lines are ignored #### Example *Conversion table `ex.conv`*: Seq1 11 Seq2 12 Seq3 13 Seq4 11 *Taxonomy tree `ex.tree`*: 1 | 1 | root 10 | 1 | kingdom 11 | 10 | species 12 | 10 | species 13 | 1 | species *Name table `ex.name`*: 1 | root | | scientific name | 10 | Bacteria | | scientific name | 11 | Bacterium A | | scientific name | 12 | Bacterium B | | scientific name | 12 | Some other species | | scientific name | *Reference sequences `ex.fa`*: >Seq1 AAAACGTACGA..... >Seq2 AAAACGTACGA..... >Seq3 AAAACGTACGA..... >Seq4 AAAACGTACGA..... To build the database, call centrifuge-build --conversion-table ex.conv \ --taxonomy-tree ex.tree --name-table ex.name \ ex.fa ex which results in three index files named `ex.1.cf`, `ex.2.cf` and `ex.3.cf`. ### Centrifuge classification output The following example shows classification assignments for a read. The assignment output has 8 columns. readID seqID taxID score 2ndBestScore hitLength queryLength numMatches 1_1 gi|4 9646 4225 0 80 80 1 The first column is the read ID from a raw sequencing read (e.g., 1_1 in the example). The second column is the sequence ID of the genomic sequence, where the read is classified (e.g., gi|4). The third column is the taxonomic ID of the genomic sequence in the second column (e.g., 9646). The fourth column is the score for the classification, which is the weighted sum of hits (e.g., 4225) The fifth column is the score for the next best classification (e.g., 0). The sixth column is a pair of two numbers: (1) an approximate number of base pairs of the read that match the genomic sequence and (2) the length of a read or the combined length of mate pairs (e.g., 80 / 80). The seventh column is a pair of two numbers: (1) an approximate number of base pairs of the read that match the genomic sequence and (2) the length of a read or the combined length of mate pairs (e.g., 80 / 80). The eighth column is the number of classifications for this read, indicating how many assignments were made (e.g.,1). ### Centrifuge summary output (the default filename is centrifuge_report.tsv) The following example shows a classification summary for each genome or taxonomic unit. The assignment output has 7 columns. name taxID taxRank genomeSize numReads numUniqueReads abundance Wigglesworthia glossinidia endosymbiont of Glossina brevipalpis 36870 leaf 703004 5981 5964 0.0152317 The first column is the name of a genome, or the name corresponding to a taxonomic ID (the second column) at a rank higher than the strain (e.g., Wigglesworthia glossinidia endosymbiont of Glossina brevipalpis). The second column is the taxonomic ID (e.g., 36870). The third column is the taxonomic rank (e.g., leaf). The fourth column is the length of the genome sequence (e.g., 703004). The fifth column is the number of reads classified to this genomic sequence including multi-classified reads (e.g., 5981). The sixth column is the number of reads uniquely classified to this genomic sequence (e.g., 5964). The seventh column is the proportion of this genome normalized by its genomic length (e.g., 0.0152317). As the GenBank database is incomplete (i.e., many more genomes remain to be identified and added), and reads have sequencing errors, classification programs including Centrifuge often report many false assignments. In order to perform more conservative analyses, users may want to discard assignments for reads having a matching length (8th column in the output of Centrifuge) of 40% or lower. It may be also helpful to use a score (4th column) for filtering out some assignments. Our future research plans include working on developing methods that estimate confidence scores for assignments. ### Kraken-style report `centrifuge-kreport` can be used to make a Kraken-style report from the Centrifuge output including taxonomy information: `centrifuge-kreport -x ` Inspecting the Centrifuge index ----------------------- The index can be inspected with `centrifuge-inspect`. To extract raw sequences: centrifuge-inspect Extract the sequence ID to taxonomy ID conversion table from the index centrifuge-inspect --conversion-table Extract the taxonomy tree from the index: centrifuge-inspect --taxonomy-tree Extract the lengths of the sequences from the index (each row has two columns: taxonomic ID and length): centrifuge-inspect --size-table Extract the names from the index (each row has two columns: taxonomic ID and name): centrifuge-inspect --name-table Wrapper ------- The `centrifuge`, `centrifuge-build` and `centrifuge-inspect` executables are actually wrapper scripts that call binary programs as appropriate. Also, the `centrifuge` wrapper provides some key functionality, like the ability to handle compressed inputs, and the functionality for `--un`, `--al` and related options. It is recommended that you always run the centrifuge wrappers and not run the binaries directly. Performance tuning ------------------ 1. If your computer has multiple processors/cores, use `-p NTHREADS` The `-p` option causes Centrifuge to launch a specified number of parallel search threads. Each thread runs on a different processor/core and all threads find alignments in parallel, increasing alignment throughput by approximately a multiple of the number of threads (though in practice, speedup is somewhat worse than linear). Command Line ------------ ### Usage centrifuge [options]* -x {-1 -2 | -U | --sra-acc } [--report-file -S ] ### Main arguments -x The basename of the index for the reference genomes. The basename is the name of any of the index files up to but not including the final `.1.cf` / etc. `centrifuge` looks for the specified index first in the current directory, then in the directory specified in the `CENTRIFUGE_INDEXES` environment variable. -1 Comma-separated list of files containing mate 1s (filename usually includes `_1`), e.g. `-1 flyA_1.fq,flyB_1.fq`. Sequences specified with this option must correspond file-for-file and read-for-read with those specified in ``. Reads may be a mix of different lengths. If `-` is specified, `centrifuge` will read the mate 1s from the "standard in" or "stdin" filehandle. -2 Comma-separated list of files containing mate 2s (filename usually includes `_2`), e.g. `-2 flyA_2.fq,flyB_2.fq`. Sequences specified with this option must correspond file-for-file and read-for-read with those specified in ``. Reads may be a mix of different lengths. If `-` is specified, `centrifuge` will read the mate 2s from the "standard in" or "stdin" filehandle. -U Comma-separated list of files containing unpaired reads to be aligned, e.g. `lane1.fq,lane2.fq,lane3.fq,lane4.fq`. Reads may be a mix of different lengths. If `-` is specified, `centrifuge` gets the reads from the "standard in" or "stdin" filehandle. --sra-acc Comma-separated list of SRA accession numbers, e.g. `--sra-acc SRR353653,SRR353654`. Information about read types is available at http://trace.ncbi.nlm.nih.gov/Traces/sra/sra.cgi?sp=runinfo&acc=sra-acc&retmode=xml, where sra-acc is SRA accession number. If users run HISAT2 on a computer cluster, it is recommended to disable SRA-related caching (see the instruction at [SRA-MANUAL]). [SRA-MANUAL]: https://github.com/ncbi/sra-tools/wiki/Toolkit-Configuration -S File to write classification results to. By default, assignments are written to the "standard out" or "stdout" filehandle (i.e. the console). --report-file File to write a classification summary to (default: centrifuge_report.tsv). ### Options #### Input options -q Reads (specified with ``, ``, ``) are FASTQ files. FASTQ files usually have extension `.fq` or `.fastq`. FASTQ is the default format. See also: `--solexa-quals` and `--int-quals`. --qseq Reads (specified with ``, ``, ``) are QSEQ files. QSEQ files usually end in `_qseq.txt`. See also: `--solexa-quals` and `--int-quals`. -f Reads (specified with ``, ``, ``) are FASTA files. FASTA files usually have extension `.fa`, `.fasta`, `.mfa`, `.fna` or similar. FASTA files do not have a way of specifying quality values, so when `-f` is set, the result is as if `--ignore-quals` is also set. -r Reads (specified with ``, ``, ``) are files with one input sequence per line, without any other information (no read names, no qualities). When `-r` is set, the result is as if `--ignore-quals` is also set. -c The read sequences are given on command line. I.e. ``, `` and `` are comma-separated lists of reads rather than lists of read files. There is no way to specify read names or qualities, so `-c` also implies `--ignore-quals`. -s/--skip Skip (i.e. do not align) the first `` reads or pairs in the input. -u/--qupto Align the first `` reads or read pairs from the input (after the `-s`/`--skip` reads or pairs have been skipped), then stop. Default: no limit. -5/--trim5 Trim `` bases from 5' (left) end of each read before alignment (default: 0). -3/--trim3 Trim `` bases from 3' (right) end of each read before alignment (default: 0). --phred33 Input qualities are ASCII chars equal to the [Phred quality] plus 33. This is also called the "Phred+33" encoding, which is used by the very latest Illumina pipelines. [Phred quality]: http://en.wikipedia.org/wiki/Phred_quality_score --phred64 Input qualities are ASCII chars equal to the [Phred quality] plus 64. This is also called the "Phred+64" encoding. --solexa-quals Convert input qualities from [Solexa][Phred quality] (which can be negative) to [Phred][Phred quality] (which can't). This scheme was used in older Illumina GA Pipeline versions (prior to 1.3). Default: off. --int-quals Quality values are represented in the read input file as space-separated ASCII integers, e.g., `40 40 30 40`..., rather than ASCII characters, e.g., `II?I`.... Integers are treated as being on the [Phred quality] scale unless `--solexa-quals` is also specified. Default: off. #### Classification --min-hitlen Minimum length of partial hits, which must be greater than 15 (default: 22)" -k It searches for at most `` distinct, primary assignments for each read or pair. Primary assignments mean assignments whose assignment score is equal or higher than any other assignments. If there are more primary assignments than this value, the search will merge some of the assignments into a higher taxonomic rank. The assignment score for a paired-end assignment equals the sum of the assignment scores of the individual mates. Default: 5 --host-taxids A comma-separated list of taxonomic IDs that will be preferred in classification procedure. The descendants from these IDs will also be preferred. In case some of a read's assignments correspond to these taxonomic IDs, only those corresponding assignments will be reported. --exclude-taxids A comma-separated list of taxonomic IDs that will be excluded in classification procedure. The descendants from these IDs will also be exclude. #### Alignment options --n-ceil Sets a function governing the maximum number of ambiguous characters (usually `N`s and/or `.`s) allowed in a read as a function of read length. For instance, specifying `-L,0,0.15` sets the N-ceiling function `f` to `f(x) = 0 + 0.15 * x`, where x is the read length. See also: [setting function options]. Reads exceeding this ceiling are [filtered out]. Default: `L,0,0.15`. --ignore-quals When calculating a mismatch penalty, always consider the quality value at the mismatched position to be the highest possible, regardless of the actual value. I.e. input is treated as though all quality values are high. This is also the default behavior when the input doesn't specify quality values (e.g. in `-f`, `-r`, or `-c` modes). --nofw/--norc If `--nofw` is specified, `centrifuge` will not attempt to align unpaired reads to the forward (Watson) reference strand. If `--norc` is specified, `centrifuge` will not attempt to align unpaired reads against the reverse-complement (Crick) reference strand. In paired-end mode, `--nofw` and `--norc` pertain to the fragments; i.e. specifying `--nofw` causes `centrifuge` to explore only those paired-end configurations corresponding to fragments from the reverse-complement (Crick) strand. Default: both strands enabled. #### Paired-end options --fr/--rf/--ff The upstream/downstream mate orientations for a valid paired-end alignment against the forward reference strand. E.g., if `--fr` is specified and there is a candidate paired-end alignment where mate 1 appears upstream of the reverse complement of mate 2 and the fragment length constraints (`-I` and `-X`) are met, that alignment is valid. Also, if mate 2 appears upstream of the reverse complement of mate 1 and all other constraints are met, that too is valid. `--rf` likewise requires that an upstream mate1 be reverse-complemented and a downstream mate2 be forward-oriented. ` --ff` requires both an upstream mate 1 and a downstream mate 2 to be forward-oriented. Default: `--fr` (appropriate for Illumina's Paired-end Sequencing Assay). #### Output options -t/--time Print the wall-clock time required to load the index files and align the reads. This is printed to the "standard error" ("stderr") filehandle. Default: off. --un --un-gz --un-bz2 Write unpaired reads that fail to align to file at ``. These reads correspond to the SAM records with the FLAGS `0x4` bit set and neither the `0x40` nor `0x80` bits set. If `--un-gz` is specified, output will be gzip compressed. If `--un-bz2` is specified, output will be bzip2 compressed. Reads written in this way will appear exactly as they did in the input file, without any modification (same sequence, same name, same quality string, same quality encoding). Reads will not necessarily appear in the same order as they did in the input. --al --al-gz --al-bz2 Write unpaired reads that align at least once to file at ``. These reads correspond to the SAM records with the FLAGS `0x4`, `0x40`, and `0x80` bits unset. If `--al-gz` is specified, output will be gzip compressed. If `--al-bz2` is specified, output will be bzip2 compressed. Reads written in this way will appear exactly as they did in the input file, without any modification (same sequence, same name, same quality string, same quality encoding). Reads will not necessarily appear in the same order as they did in the input. --un-conc --un-conc-gz --un-conc-bz2 Write paired-end reads that fail to align concordantly to file(s) at ``. These reads correspond to the SAM records with the FLAGS `0x4` bit set and either the `0x40` or `0x80` bit set (depending on whether it's mate #1 or #2). `.1` and `.2` strings are added to the filename to distinguish which file contains mate #1 and mate #2. If a percent symbol, `%`, is used in ``, the percent symbol is replaced with `1` or `2` to make the per-mate filenames. Otherwise, `.1` or `.2` are added before the final dot in `` to make the per-mate filenames. Reads written in this way will appear exactly as they did in the input files, without any modification (same sequence, same name, same quality string, same quality encoding). Reads will not necessarily appear in the same order as they did in the inputs. --al-conc --al-conc-gz --al-conc-bz2 Write paired-end reads that align concordantly at least once to file(s) at ``. These reads correspond to the SAM records with the FLAGS `0x4` bit unset and either the `0x40` or `0x80` bit set (depending on whether it's mate #1 or #2). `.1` and `.2` strings are added to the filename to distinguish which file contains mate #1 and mate #2. If a percent symbol, `%`, is used in ``, the percent symbol is replaced with `1` or `2` to make the per-mate filenames. Otherwise, `.1` or `.2` are added before the final dot in `` to make the per-mate filenames. Reads written in this way will appear exactly as they did in the input files, without any modification (same sequence, same name, same quality string, same quality encoding). Reads will not necessarily appear in the same order as they did in the inputs. --quiet Print nothing besides alignments and serious errors. --met-file Write `centrifuge` metrics to file ``. Having alignment metric can be useful for debugging certain problems, especially performance issues. See also: `--met`. Default: metrics disabled. --met-stderr Write `centrifuge` metrics to the "standard error" ("stderr") filehandle. This is not mutually exclusive with `--met-file`. Having alignment metric can be useful for debugging certain problems, especially performance issues. See also: `--met`. Default: metrics disabled. --met Write a new `centrifuge` metrics record every `` seconds. Only matters if either `--met-stderr` or `--met-file` are specified. Default: 1. #### Performance options -o/--offrate Override the offrate of the index with ``. If `` is greater than the offrate used to build the index, then some row markings are discarded when the index is read into memory. This reduces the memory footprint of the aligner but requires more time to calculate text offsets. `` must be greater than the value used to build the index. -p/--threads NTHREADS Launch `NTHREADS` parallel search threads (default: 1). Threads will run on separate processors/cores and synchronize when parsing reads and outputting alignments. Searching for alignments is highly parallel, and speedup is close to linear. Increasing `-p` increases Centrifuge's memory footprint. E.g. when aligning to a human genome index, increasing `-p` from 1 to 8 increases the memory footprint by a few hundred megabytes. This option is only available if `bowtie` is linked with the `pthreads` library (i.e. if `BOWTIE_PTHREADS=0` is not specified at build time). --reorder Guarantees that output records are printed in an order corresponding to the order of the reads in the original input file, even when `-p` is set greater than 1. Specifying `--reorder` and setting `-p` greater than 1 causes Centrifuge to run somewhat slower and use somewhat more memory then if `--reorder` were not specified. Has no effect if `-p` is set to 1, since output order will naturally correspond to input order in that case. --mm Use memory-mapped I/O to load the index, rather than typical file I/O. Memory-mapping allows many concurrent `bowtie` processes on the same computer to share the same memory image of the index (i.e. you pay the memory overhead just once). This facilitates memory-efficient parallelization of `bowtie` in situations where using `-p` is not possible or not preferable. #### Other options --qc-filter Filter out reads for which the QSEQ filter field is non-zero. Only has an effect when read format is `--qseq`. Default: off. --seed Use `` as the seed for pseudo-random number generator. Default: 0. --non-deterministic Normally, Centrifuge re-initializes its pseudo-random generator for each read. It seeds the generator with a number derived from (a) the read name, (b) the nucleotide sequence, (c) the quality sequence, (d) the value of the `--seed` option. This means that if two reads are identical (same name, same nucleotides, same qualities) Centrifuge will find and report the same classification(s) for both, even if there was ambiguity. When `--non-deterministic` is specified, Centrifuge re-initializes its pseudo-random generator for each read using the current time. This means that Centrifuge will not necessarily report the same classification for two identical reads. This is counter-intuitive for some users, but might be more appropriate in situations where the input consists of many identical reads. --version Print version information and quit. -h/--help Print usage information and quit. The `centrifuge-build` indexer =========================== `centrifuge-build` builds a Centrifuge index from a set of DNA sequences. `centrifuge-build` outputs a set of 6 files with suffixes `.1.cf`, `.2.cf`, and `.3.cf`. These files together constitute the index: they are all that is needed to align reads to that reference. The original sequence FASTA files are no longer used by Centrifuge once the index is built. Use of Karkkainen's [blockwise algorithm] allows `centrifuge-build` to trade off between running time and memory usage. `centrifuge-build` has two options governing how it makes this trade: `--bmax`/`--bmaxdivn`, and `--dcv`. By default, `centrifuge-build` will automatically search for the settings that yield the best running time without exhausting memory. This behavior can be disabled using the `-a`/`--noauto` option. The indexer provides options pertaining to the "shape" of the index, e.g. `--offrate` governs the fraction of [Burrows-Wheeler] rows that are "marked" (i.e., the density of the suffix-array sample; see the original [FM Index] paper for details). All of these options are potentially profitable trade-offs depending on the application. They have been set to defaults that are reasonable for most cases according to our experiments. See [Performance tuning] for details. The Centrifuge index is based on the [FM Index] of Ferragina and Manzini, which in turn is based on the [Burrows-Wheeler] transform. The algorithm used to build the index is based on the [blockwise algorithm] of Karkkainen. [Blockwise algorithm]: http://portal.acm.org/citation.cfm?id=1314852 [Burrows-Wheeler]: http://en.wikipedia.org/wiki/Burrows-Wheeler_transform Command Line ------------ Usage: centrifuge-build [options]* --conversion-table --taxonomy-tree --name-table ### Main arguments A comma-separated list of FASTA files containing the reference sequences to be aligned to, or, if `-c` is specified, the sequences themselves. E.g., `` might be `chr1.fa,chr2.fa,chrX.fa,chrY.fa`, or, if `-c` is specified, this might be `GGTCATCCT,ACGGGTCGT,CCGTTCTATGCGGCTTA`. The basename of the index files to write. By default, `centrifuge-build` writes files named `NAME.1.cf`, `NAME.2.cf`, and `NAME.3.cf`, where `NAME` is ``. ### Options -f The reference input files (specified as ``) are FASTA files (usually having extension `.fa`, `.mfa`, `.fna` or similar). -c The reference sequences are given on the command line. I.e. `` is a comma-separated list of sequences rather than a list of FASTA files. -a/--noauto Disable the default behavior whereby `centrifuge-build` automatically selects values for the `--bmax`, `--dcv` and `--packed` parameters according to available memory. Instead, user may specify values for those parameters. If memory is exhausted during indexing, an error message will be printed; it is up to the user to try new parameters. -p/--threads Launch `NTHREADS` parallel search threads (default: 1). --conversion-table List of UIDs (unique ID) and corresponding taxonomic IDs. --taxonomy-tree Taxonomic tree (e.g. nodes.dmp). --name-table Name table (e.g. names.dmp). --size-table List of taxonomic IDs and lengths of the sequences belonging to the same taxonomic IDs. --bmax The maximum number of suffixes allowed in a block. Allowing more suffixes per block makes indexing faster, but increases peak memory usage. Setting this option overrides any previous setting for `--bmax`, or `--bmaxdivn`. Default (in terms of the `--bmaxdivn` parameter) is `--bmaxdivn` 4. This is configured automatically by default; use `-a`/`--noauto` to configure manually. --bmaxdivn The maximum number of suffixes allowed in a block, expressed as a fraction of the length of the reference. Setting this option overrides any previous setting for `--bmax`, or `--bmaxdivn`. Default: `--bmaxdivn` 4. This is configured automatically by default; use `-a`/`--noauto` to configure manually. --dcv Use `` as the period for the difference-cover sample. A larger period yields less memory overhead, but may make suffix sorting slower, especially if repeats are present. Must be a power of 2 no greater than 4096. Default: 1024. This is configured automatically by default; use `-a`/`--noauto` to configure manually. --nodc Disable use of the difference-cover sample. Suffix sorting becomes quadratic-time in the worst case (where the worst case is an extremely repetitive reference). Default: off. -o/--offrate To map alignments back to positions on the reference sequences, it's necessary to annotate ("mark") some or all of the [Burrows-Wheeler] rows with their corresponding location on the genome. `-o`/`--offrate` governs how many rows get marked: the indexer will mark every 2^`` rows. Marking more rows makes reference-position lookups faster, but requires more memory to hold the annotations at runtime. The default is 4 (every 16th row is marked; for human genome, annotations occupy about 680 megabytes). -t/--ftabchars The ftab is the lookup table used to calculate an initial [Burrows-Wheeler] range with respect to the first `` characters of the query. A larger `` yields a larger lookup table but faster query times. The ftab has size 4^(``+1) bytes. The default setting is 10 (ftab is 4MB). --seed Use `` as the seed for pseudo-random number generator. --kmer-count Use `` as kmer-size for counting the distinct number of k-mers in the input sequences. -q/--quiet `centrifuge-build` is verbose by default. With this option `centrifuge-build` will print only error messages. -h/--help Print usage information and quit. --version Print version information and quit. The `centrifuge-inspect` index inspector ===================================== `centrifuge-inspect` extracts information from a Centrifuge index about what kind of index it is and what reference sequences were used to build it. When run without any options, the tool will output a FASTA file containing the sequences of the original references (with all non-`A`/`C`/`G`/`T` characters converted to `N`s). It can also be used to extract just the reference sequence names using the `-n`/`--names` option or a more verbose summary using the `-s`/`--summary` option. Command Line ------------ Usage: centrifuge-inspect [options]* ### Main arguments The basename of the index to be inspected. The basename is name of any of the index files but with the `.X.cf` suffix omitted. `centrifuge-inspect` first looks in the current directory for the index files, then in the directory specified in the `Centrifuge_INDEXES` environment variable. ### Options -a/--across When printing FASTA output, output a newline character every `` bases (default: 60). -n/--names Print reference sequence names, one per line, and quit. -s/--summary Print a summary that includes information about index settings, as well as the names and lengths of the input sequences. The summary has this format: Colorspace <0 or 1> SA-Sample 1 in FTab-Chars Sequence-1 Sequence-2 ... Sequence-N Fields are separated by tabs. Colorspace is always set to 0 for Centrifuge. --conversion-table Print a list of UIDs (unique ID) and corresponding taxonomic IDs. --taxonomy-tree Print taxonomic tree. --name-table Print name table. --size-table Print a list of taxonomic IDs and lengths of the sequences belonging to the same taxonomic IDs. -v/--verbose Print verbose output (for debugging). --version Print version information and quit. -h/--help Print usage information and quit. Getting started with Centrifuge =================================================== Centrifuge comes with some example files to get you started. The example files are not scientifically significant; these files will simply let you start running Centrifuge and downstream tools right away. First follow the manual instructions to [obtain Centrifuge]. Set the `CENTRIFUGE_HOME` environment variable to point to the new Centrifuge directory containing the `centrifuge`, `centrifuge-build` and `centrifuge-inspect` binaries. This is important, as the `CENTRIFUGE_HOME` variable is used in the commands below to refer to that directory. Indexing a reference genome --------------------------- To create an index for two small sequences included with Centrifuge, create a new temporary directory (it doesn't matter where), change into that directory, and run: $CENTRIFUGE_HOME/centrifuge-build --conversion-table $CENTRIFUGE_HOME/example/reference/gi_to_tid.dmp --taxonomy-tree $CENTRIFUGE_HOME/example/reference/nodes.dmp --name-table $CENTRIFUGE_HOME/example/reference/names.dmp $CENTRIFUGE_HOME/example/reference/test.fa test The command should print many lines of output then quit. When the command completes, the current directory will contain ten new files that all start with `test` and end with `.1.cf`, `.2.cf`, `.3.cf`. These files constitute the index - you're done! You can use `centrifuge-build` to create an index for a set of FASTA files obtained from any source, including sites such as [UCSC], [NCBI], and [Ensembl]. When indexing multiple FASTA files, specify all the files using commas to separate file names. For more details on how to create an index with `centrifuge-build`, see the [manual section on index building]. You may also want to bypass this process by obtaining a pre-built index. [UCSC]: http://genome.ucsc.edu/cgi-bin/hgGateway [NCBI]: http://www.ncbi.nlm.nih.gov/sites/genome [Ensembl]: http://www.ensembl.org/ Classifying example reads ---------------------- Stay in the directory created in the previous step, which now contains the `test` index files. Next, run: $CENTRIFUGE_HOME/centrifuge -f -x test $CENTRIFUGE_HOME/example/reads/input.fa This runs the Centrifuge classifier, which classifies a set of unpaired reads to the the genomes using the index generated in the previous step. The classification results are reported to stdout, and a short classification summary is written to centrifuge-species_report.tsv. You will see something like this: readID seqID taxID score 2ndBestScore hitLength numMatches C_1 gi|7 9913 4225 4225 80 2 C_1 gi|4 9646 4225 4225 80 2 C_2 gi|4 9646 4225 4225 80 2 C_2 gi|7 9913 4225 4225 80 2 C_3 gi|7 9913 4225 4225 80 2 C_3 gi|4 9646 4225 4225 80 2 C_4 gi|4 9646 4225 4225 80 2 C_4 gi|7 9913 4225 4225 80 2 1_1 gi|4 9646 4225 0 80 1 1_2 gi|4 9646 4225 0 80 1 2_1 gi|7 9913 4225 0 80 1 2_2 gi|7 9913 4225 0 80 1 2_3 gi|7 9913 4225 0 80 1 2_4 gi|7 9913 4225 0 80 1 2_5 gi|7 9913 4225 0 80 1 2_6 gi|7 9913 4225 0 80 1