CAT, BAT, and RAT

• Introduction
• Dependencies and where to get them
• Installation
• Getting started
  • Downloading preconstructed database files
  • Creating a fresh NCBI nr or GTDB database yourself
  • Creating a custom database
  • Running CAT/BAT/RAT
  • MMseqs2 GPU searches
  • Getting help
• Taxonomic annotation of contigs or MAGs with CAT and BAT
  • Interpreting the output files
  • Marking suggestive taxonomic assignments with an asterisk
  • Optimising running time, RAM, and disk usage
  • Examples
• Estimating the microbial composition with RAT
  • Output files

Introduction

Contig Annotation Tool (CAT) and Bin Annotation Tool (BAT) are pipelines for the taxonomic classification of long DNA sequences and metagenome assembled genomes (MAGs / bins) of both known and (highly) unknown microorganisms, as generated by contemporary metagenomics studies. The core algorithm of both programs involves gene calling, mapping of predicted ORFs against a protein database, and voting-based classification of the entire contig / MAG based on classification of the individual ORFs. CAT and BAT can be run from intermediate steps if files are formatted appropriately.

A paper describing the algorithm together with extensive benchmarks can be found at https://doi.org/10.1186/s13059-019-1817-x. If you use CAT or BAT in your research, it would be great if you could cite us:

• von Meijenfeldt F.A.B., Arkhipova K., Cambuy D.D., Coutinho F.H., Dutilh B.E. Robust taxonomic classification of uncharted microbial sequences and bins with CAT and BAT. Genome Biology. 2019;20:217.

Read Annotation Tool (RAT) estimates the taxonomic composition of metagenomes using CAT and BAT output. A manuscript describing RAT with benchmarks can be found at https://doi.org/10.1038/s41467-024-47155-1. If you use RAT in your research, it would be great if you could cite:

• Hauptfeld, E., Pappas, N., van Iwaarden, S., Snoek B.L., Aldas-Vargas A., Dutilh B.E., von Meijenfeldt F.A.B. Integrating taxonomic signals from MAGs and contigs improves read annotation and taxonomic profiling of metagenomes. Nature Communications 15, 3373 (2024).
• von Meijenfeldt F.A.B., Arkhipova K., Cambuy D.D., Coutinho F.H., Dutilh B.E. Robust taxonomic classification of uncharted microbial sequences and bins with CAT and BAT. Genome Biology. 2019;20:217.

To cite the code itself:

Dependencies and where to get them

• Python >=3.11, https://www.python.org/.

• DIAMOND (default aligner), https://github.com/bbuchfink/diamond.

• MMseqs2 (alternative aligner), https://github.com/soedinglab/MMseqs2.

• Pyrodigal (installed automatically with CAT pack), https://github.com/althonos/pyrodigal.

RAT further requires (not needed for CAT and BAT):

Use either BWA or BWA-MEM2 when mapping reads. BWA-MEM2 is recommended due to its speed increase. No mapper is required when supplying existing mappings.

• BWA, https://github.com/lh3/bwa.

• BWA-MEM2, https://github.com/bwa-mem2/bwa-mem2

• SAMtools, http://www.htslib.org/download/.

For MMseqs2 GPU searches, install the optional Python dependency:

python -m pip install 'cat-pack[gpu]'

CAT, BAT, and RAT have been thoroughly tested on Linux systems, and should run on macOS as well.

Installation

Install CAT pack from PyPI:

$ python -m pip install cat-pack

Alternatively, install from the project root of a source checkout:

$ python -m pip install .

After following these steps you can run CAT, BAT, and RAT from anywhere:

$ CAT_pack --version

Getting started

To get started with CAT/BAT/RAT, you will have to get the database files on your system. You can either download preconstructed database files, or generate them yourself.

Downloading preconstructed database files

To download the database files, find the most recent version on tbb.bio.uu.nl/tina/CAT_pack_prepare/, download and extract, and you are ready to go!

For NCBI nr:

$ wget tbb.bio.uu.nl/tina/CAT_pack_prepare/20240422_CAT_nr.tar.gz

$ tar -xvzf 20240422_CAT_nr.tar.gz

For GTDB:

$ wget tbb.bio.uu.nl/tina/CAT_pack_prepare/20231120_CAT_gtdb.tar.gz     # release 214

$ tar -xvzf 20231120_CAT_gtdb.tar.gz

Creating a fresh NCBI nr or GTDB database yourself

Instead of using the preconstructed database, you can construct a fresh database yourself. The download module can be used to download and process raw data, in preparation for building a new CAT pack database. This will ensure that all input dependencies are met and correctly formatted for CAT_pack prepare.

Currently, two databases are supported, NCBI's nr and the Genome Taxonomy Database (GTDB) proteins.

NCBI non-redundant protein database (nr)

$ CAT_pack download --db nr --out_dir path/to/nr_data_dir

Will download the fasta file with the protein sequences, their mapping to a taxid, and the taxonomy information from NCBI over HTTPS.

Genome Taxonomy Database (GTDB) proteins

$ CAT_pack download --db gtdb --out_dir path/to/gtdb_data_dir

The files required to build a CAT pack database are provided by the GTDB downloads page.

CAT_pack download fetches the necessary files and does some additional processing to get them ready for CAT_pack prepare:

• The taxonomy information from GTDB is transformed into NCBI style nodes.dmp and names.dmp files.
• Protein sequences are extracted from gtdb_proteins_aa_reps.tar.gz and are subjected to a round of deduplication. The deduplication reduces the redundancy in the DIAMOND database, thus simplifying the alignment process. Exact duplicate sequences are identified based on a combination of the MD5sum of the protein sequences and their length. Only one representative sequence is kept, with all duplicates encoded in the fasta header. This information is later used by CAT_pack prepare to assign the LCA of the protein sequence appropriately in the .fastaid2LCAtaxid file.
• The mapping of all protein sequences to their respective taxonomy is created.
• In addition, the newick formatted trees of Bacteria and Archaea are downloaded and - artificially - concatenated under a single root node, to produce a <YYYY-MM-DD>.gtdb.tree file. This file is not used by the CAT pack but may come in handy for downstream analyses.

When the download and processing of the files is finished successfully you can build a CAT pack database with CAT_pack prepare.

For all command line options available see

$ CAT_pack download -h

and

$ CAT_pack prepare -h

Creating a custom database

For a custom CAT pack database, you must have the following input ready before you launch a CAT_pack prepare run.

1. A fasta file containing all protein sequences you want to include in your database.

2. A names.dmp file that contains mappings of taxids to their ranks and scientific names. The format must be the same as the NCBI standard names.dmp (uses \t|\t as field separator).

An example looks like this:

1	|	root	|	scientific name	|
2	|	Bacteria	|	scientific name	|
562	|	Escherichia	coli	|	scientific name	|

3. A nodes.dmp file that describes the child-parent relationship of the nodes in the taxonomy tree and their (official) rank. The format must be the same as the NCBI standard nodes.dmp (uses \t|\t as the field separator).

An example looks like this:

1	|	1	|	no rank	|
2	|	1	|	superkingdom	|
1224	|	2	|	phylum	|
1236	| 1224	|	class	|
91437	|	1236	|	order	|
543	|	91347	|	family	|
561	|	543	|	genus	|
562	|	561	|	species	|

For more information on the nodes.dmp and names.dmp files, see the NCBI taxdump_readme.txt.

4. A 2-column, tab-separated file containing the mapping of each sequence in the fasta file to a taxid in the taxonomy. This file must contain the header accession.version taxid.

An example looks like this

accession.version	taxid
protein_1	562
protein_2	123456

Once all of the above requirements are met you can run CAT_pack prepare. All the input needs to be explicitly specified for CAT_pack prepare to work, for example:

$ CAT_pack prepare \
--db_fasta path/to/fasta \
--names path/to/names.dmp \
--nodes path/to/nodes.dmp \
--acc2tax path/to/acc2taxid.txt.gz \
--db_dir path/to/output_dir

will create an output_dir that will look like this

output_dir
├── 2023-11-05_CAT_pack.log
├── 2023-11-05_CAT_pack.dmnd
├── 2023-11-05_CAT_pack.fastaid2LCAtaxid
├── 2023-11-05_CAT_pack.taxids_with_multiple_offspring
├── names.dmp
└── nodes.dmp

Notes:

• All database and taxonomy files are stored together in output_dir. Use this directory with -d for CAT, BAT, RAT.
• The nodes.dmp and names.dmp files in the output_dir directory are copied from their original location.
• The default prefix is <YYYY-MM-DD>_CAT_pack. You can customize it with the --common_prefix option.

For all command line options available see

$ CAT_pack prepare -h

Running CAT/BAT/RAT.

The database files are needed in subsequent CAT/BAT/RAT runs. They only need to be generated/downloaded once or whenever you want to update the database.

To run CAT/BAT/RAT, respectively:

$ CAT_pack cat       # Runs CAT.

$ CAT_pack bat       # Runs BAT.

$ CAT_pack rat       # Runs RAT.

MMseqs2 GPU searches

CAT, BAT, and RAT accept --aligner mmseqs2 --gpu to run their MMseqs2 searches on a supported GPU on Linux. Run CAT_pack on the GPU machine, with a GPU-enabled MMseqs2 binary on PATH, or supply --path_to_mmseqs /path/to/gpu/mmseqs.

Prepare the database protein FASTA and taxonomy inputs:

CAT_pack prepare --db_fasta reference.faa --names names.dmp --nodes nodes.dmp \
  --acc2tax accession2taxid.tsv --db_dir prepared_db --common_prefix reference \
  --build_mmseqs2 --gpu

Then run classification on the GPU machine:

CAT_pack cat -c contigs.fna -d prepared_db -o gpu_run --aligner mmseqs2 --gpu

Use the same flags for bat or rat. RAT applies the selected backend to its contig/bin searches and its translated search of unclassified reads. The existing compact and --blast6_out output formats are supported. --gpu requires --aligner mmseqs2.

GPU search always uses maximum sensitivity, so --sensitivity applies only to CPU search. For more information see the MMseqs2 GPU guide

Getting help.

If you are unsure what options a program has, you can always add --help to a command. This is a great way to get you started with CAT, BAT, or RAT.

$ CAT_pack --help

$ CAT_pack cat --help

$ CAT_pack summarise --help

If you are unsure about what input files are required, you can just run CAT/BAT/RAT, as the appropriate error messages are generated if formatting is incorrect.

Taxonomic annotation of contigs or MAGs with CAT and BAT

After you have got the database files on your system, you can run CAT to annotate your contig set:

$ CAT_pack cat -c {contigs fasta} -d {database folder}

Multiple output files and a log file will be generated. The final classification files will be called out.CAT.ORF2LCA.txt and out.CAT.contig2classification.txt.

Alternatively, if you already have a predicted proteins fasta file and/or an alignment table for example from previous runs, you can supply them to CAT, which will then skip the steps that have already been done and start from there:

$ CAT_pack cat -c {contigs fasta} -d {database folder} -p {predicted proteins fasta} -a {alignment file}

The headers in the predicted proteins fasta file must look like this >{contig}_{ORFnumber}, so that CAT can couple contigs to ORFs. The alignment file must be tab-separated, with queried ORF in the first column, protein accession number in the second, and bit-score in the 12th.

To run BAT on a set of MAGs (the default file suffix is .fna. Use -s .fa or -s .fasta for other suffixes):

$ CAT_pack bat -b {bin folder} -d {database folder}

Alternatively, BAT can be run on a single MAG:

$ CAT_pack bat -b {bin fasta} -d {database folder}

Multiple output files and a log file will be generated. The final classification files will be called out.BAT.ORF2LCA.txt and out.BAT.bin2classification.txt.

Similarly to CAT, BAT can be run from intermediate steps if gene prediction and alignment have already been carried out once:

$ CAT_pack bat -b {bin folder} -d {database folder} -p {predicted proteins fasta} -a {alignment file}

If you have previously run CAT on the set of contigs from which the MAGs originate, you can use the previously predicted protein and alignment files to classify the MAGs.

$ CAT_pack cat -c {contigs fasta} -d {database folder}

$ CAT_pack bat -b {bin folder} -d {database folder} -p {predicted proteins fasta from contig run} -a {alignment file from contig run}

This is a great way to run both CAT and BAT on a set of MAGs without needing to do protein prediction and alignment twice!

Interpreting the output files

The ORF2LCA output looks like this:

ORF	number of hits (r: 10)	lineage	top bit-score
contig_1_ORF1	7	1;131567;2;1783272	574.7

Where the lineage is the full taxonomic lineage of the classification of the ORF, and the bit-score the top-hit bit-score that is assigned to the ORF for voting. The BAT ORF2LCA output file has an extra column where ORFs are linked to the MAG in which they are found.

The contig2classification and bin2classification output looks like this:

contig or bin	classification	reason	lineage	lineage scores (f: 0.3)
contig_1	taxid assigned	based on 14/15 ORFs	1;131567;2;1783272	1.00; 1.00; 1.00; 0.78
contig_2	taxid assigned (1/2)	based on 10/10 ORFs	1;131567;2;1783272;1798711;1117;307596;307595;1890422;33071;1416614;1183438*	1.00;1.00;1.00;1.00;1.00;1.00;1.00;1.00;1.00;1.00;0.23;0.23
contig_2	taxid assigned (2/2)	based on 10/10 ORFs	1;131567;2;1783272;1798711;1117;307596;307595;1890422;33071;33072	1.00;1.00;1.00;1.00;1.00;1.00;1.00;1.00;1.00;1.00;0.77
contig_3	no taxid assigned	no ORFs found

Where the lineage scores represent the fraction of bit-score support for each classification. contig_2 has two classifications. This can happen if the f parameter is chosen below 0.5. For an explanation of the starred classification, see Marking suggestive taxonomic assignments with an asterisk.

To add names to the taxids in either output file, run:

$ CAT_pack add_names -i {ORF2LCA / classification file} -o {output file} -d {database folder}

This will show you that for example contig_1 is classified as Terrabacteria group. To only get official rank (i.e. superkingdom, phylum, ...):

$ CAT_pack add_names -i {ORF2LCA / classification file} -o {output file} -d {database folder} --only_official

Or, alternatively:

$ CAT_pack add_names -i {ORF2LCA / classification file} -o {output file} -d {database folder} --only_official --exclude_scores

If you have named a CAT or BAT classification file with official names, you can get a summary of the classification, where total length and number of ORFs supporting a taxon are calculated for contigs, and the number of MAGs per encountered taxon for MAG classification:

$ CAT_pack summarise -c {contigs fasta} -i {named CAT classification file} -o {output file}

$ CAT_pack summarise -i {named BAT classification file} -o {output file}

CAT_pack summarise currently does not support classification files wherein some contigs / MAGs have multiple classifications (as contig_2 above).

Marking suggestive taxonomic assignments with an asterisk

When we want to confidently go down to the lowest taxonomic level possible for a classification, an important assumption is that on that level conflict between classifications could have arisen. Namely, if there were conflicting classifications, the algorithm would have made the classification more conservative by moving up a level. Since it did not, we can trust the low-level classification. However, it is not always possible for conflict to arise, because in some cases no other sequences from the clade are present in the database. This is true for example for the family Dehalococcoidaceae, which in our databases is the sole representative of the order Dehalococcoidales. Thus, here we cannot confidently state that an classification on the family level is more correct than an classification on the order level. For these cases, CAT and BAT mark the lineage with asterisks, starting from the lowest level classification up to the level where conflict could have arisen because the clade contains multiple taxa with database entries. The user is advised to examine starred taxa more carefully, for example by analysing sequence identity between predicted ORFs and hits, or move up the lineage to a confident classification (i.e. the first classification without an asterisk).

If you do not want the asterisks in your output files, you can add the --no_stars flag to CAT or BAT.

Optimising running time, RAM, and disk usage

CAT and BAT may take a while to run, and may use quite a lot of RAM and disk space. Depending on what you value most, you can tune CAT and BAT to maximize one and minimize others. The classification algorithm itself is fast and is friendly on memory and disk space. The most expensive step is alignment with DIAMOND, hence tuning alignment parameters will have the highest impact:

• The -n / --threads argument allows you to choose the number of cores to deploy.
• You can choose to run DIAMOND in sensitive mode with the --diamond_mode sensitive flag. This will increase sensitivity but will make alignment considerably slower.
• Setting the --block_size parameter lower will decrease memory and temporary disk space usage. Setting it higher will increase performance.
• For high memory machines, it is advised to set --index_chunks to 1 (currently the default). This parameter has no effect on temporary disk space usage.
• You can specify the location of temporary DIAMOND files with the --tmpdir argument.

Examples

Getting help for running the prepare utility:

$ CAT_pack prepare --help

Run CAT on a contig set with default parameter settings deploying 16 cores for DIAMOND alignment. Name the contig classification output with official names, and create a summary:

$ CAT_pack cat -c contigs.fasta -d db/ -n 16 --output_prefix first_CAT_run

$ CAT_pack add_names -i first_CAT_run.contig2classification.txt -o first_CAT_run.contig2classification.official_names.txt -d db/ --only_official

$ CAT_pack summarise -c contigs.fasta -i first_CAT_run.contig2classification.official_names.txt -o CAT_first_run.summary.txt

Run BAT on the set of MAGs that was binned from these contigs, reusing the protein predictions and DIAMOND alignment file generated previously during the contig classification:

$ CAT_pack bat -b bins/ -d db/ -p first_CAT_run.predicted_proteins.faa -a first_CAT_run.alignment.diamond -o first_BAT_run

Run the contig classification algorithm again with custom parameter settings, and name the output with all names in the lineage, excluding the scores:

$ CAT_pack cat --range 5 --fraction 0.1 -c contigs.fasta -d db/ -p first_CAT_run.predicted_proteins.faa -a first_CAT_run.alignment.diamond -o second_CAT_run

$ CAT_pack add_names -i second_CAT_run.contig2classification.txt -o second_CAT_run.contig2classification.names.txt -d db/ --exclude_scores

Run BAT on the set of MAGs with custom parameter settings, suppressing terminal verbosity. Next, add names to the ORF2LCA output file:

$ CAT_pack bat -r 3 -f 0.1 -b bins/ -s .fa -d db/ -p first_CAT_run.predicted_proteins.faa -a first_CAT_run.alignment.diamond -o second_BAT_run --quiet

$ CAT_pack add_names -i second_BAT_run.ORF2LCA.txt -o second_BAT_run.ORF2LCA.names.txt -d db/

Identifying contamination/mis-binned contigs within a MAG

We often use the combination of CAT / BAT to explore possible contamination within a MAG.

$ CAT_pack cat -c ../bins/interesting_MAG.fasta -d db/ -o CAT.interesting_MAG

$ CAT_pack bat -b ../bins/interesting_MAG.fasta -d db/ -p CAT.interesting_MAG.predicted_proteins.faa -a CAT.interesting_MAG.alignment.diamond -o BAT.interesting_MAG

Contigs that have a different taxonomic signal than the MAG classification are probably contamination.

Alternatively, you can look at contamination from the MAG perspective, by setting the f parameter to a low value:

$ CAT_pack bat -f 0.01 -b ../bins/interesting_MAG.fasta -d db/ -o BAT.interesting_MAG.low_f

$ CAT_pack add_names -i BAT.interesting_MAG.low_f.bin2classification.txt -o BAT.interesting_MAG.low_f.bin2classification.names.txt -d db/

BAT will output any taxonomic signal with at least 1% support. Low scoring diverging signals are clear signs of contamination!

Estimating the microbial composition with RAT

RAT estimates the taxonomic composition of metagenomes by integrating taxonomic signals from MAGs, contigs, and reads. RAT has been added to the CAT pack from version 6.0. To use RAT, you need the CAT pack database files (see Getting started for more information).

RAT makes an integrated profile using MAGs/bins, contigs, and reads. To specify which elements should be integrated, use the --mode argument. Possible letters for --mode are m (for MAGs), c (for contigs), and r (for reads). All combinations of the three letters are possible, except r alone. To run RAT's complete workflow, specify the mode, read files, contig files, bin folder, and database files:

$ CAT_pack rat --mode mcr -b bin_folder/ -c contigs.fasta -r forward_reads.fq.gz -r reverse_reads.fq.gz -d db/

Currently, RAT supports single read files as well as paired-end read files. Interlaced read files are currently not supported. RAT will run CAT and BAT on the contigs and MAGs, will map the reads back to the contigs, and then try to annotate any unmapped reads separately.

RAT defaults to a classification fraction (-f / --fraction) of 0.5 and allows you to change it for its CAT, BAT, and direct sequence classification steps. RAT requires one classification per sequence in tables supplied with --c2c, --b2c, or --u2c. If a lower fraction produces multiple assignments for the same sequence, RAT reports an error; regenerate those classifications with --fraction 0.5 to obtain a single assignment.

If you already have a sorted mapping file, you can supply it and RAT will skip the mapping step:

$ CAT_pack rat --mode mcr -b bin_folder/ -c contigs.fasta --bam_file mapping_file_sorted.bam -r forward_reads.fq.gz -r reverse_reads.fq.gz -d db/

If CAT and/or BAT have already been run on your data, you can supply the output files to RAT to skip the CAT and BAT runs:

$ CAT_pack rat --mode mcr -b bin_folder/ -c contigs.fasta -r forward_reads.fq.gz -r reverse_reads.fq.gz -d db/ --c2c CAT_contig2classification_file.txt --b2c BAT_bin2classification_file.txt

Similarly, if a previous RAT run crashed after the unmapped reads have already been aligned to the database with DIAMOND or MMseqs2, you can supply the intermediate files to continue the run:

$ CAT_pack rat --mode mcr -b bin_folder/ -c contigs.fasta -r forward_reads.fq.gz -r reverse_reads.fq.gz -d db/ --c2c CAT_contig2classification_file.txt --b2c BAT_bin2classification_file.txt --alignment_unmapped unmapped_alignment_file.diamond

After a RAT run is finished, you can run add_names on the abundance files (only for RAT runs with nr database):

$ CAT_pack add_names -i out.RAT.RAT.complete.abundance.txt -o out.RAT.RAT.complete.abundance.names.txt -d db/ 

Similar to CAT and BAT, the paths to all dependencies can be supplied via an argument:

$ CAT_pack rat --mode mcr -b bin_folder/ -c contigs.fasta --read_file forward_reads.fq.gz --read_file reverse_reads.fq.gz -d db/ --path_to_samtools /path/to/samtools

Output files

The RAT output consists of:

• A log file.
• CAT output files for the contig fasta (when the mode contains c).
• BAT output files for the MAGs (when the mode contains m. Protein predictions and alignments are reused from CAT when available).
• A table that contains the abundance of each MAG (<prefix>.RAT.bin.reads.txt, when the mode contains m).
• A table that contains all detected taxa and their abundance in the sample (<prefix>.RAT.complete.abundance.txt).
• A table that contains the lineage for each read, as well as which step the annotation was made in (<prefix>.RAT.read2classification.txt, only with --read2classification, in any mode).
• A table that contains the abundance of each contig in the contig fasta (<prefix>.RAT.contig.abundance.txt).
• A fasta containing the sequences of all unmapped reads and contigs that could not be annotated by CAT (when the mode contains r).
• The DIAMOND or MMseqs2 alignment of unmapped reads and unannotated contigs (when the mode contains r).
• A table that contains the annotations for unmapped reads and (previously) unannotated contigs (<prefix>.RAT.unmapped2classification.txt, when the mode contains r).