anvi-estimate-scg-taxonomy

Estimates taxonomy at genome and metagenome level. This program is the entry point to estimate taxonomy for a given set of contigs (i.e., all contigs in a contigs database, or contigs described in collections as bins). For this, it uses single-copy core gene sequences and the GTDB database.

🔙 To the main page of anvi’o programs and artifacts.

Authors

A. Murat Eren (Meren)
WebEmailTwitterGithub
Quentin Clayssen
EmailTwitterGithub

Requires

contigs-db scgs-taxonomy

Can use

profile-db collection bin metagenomes

Provides

genome-taxonomy

Can provide

genome-taxonomy-txt

Usage

This program makes quick taxonomy estimates for genomes, metagenomes, or bins stored in your contigs-db using single-copy core genes.

You can run this program on an anvi’o contigs database only if you already have setup the necessary databases to assign taxonomy on your computer by running anvi-setup-scg-taxonomy and annotated the contigs-db you are working with using anvi-run-scg-taxonomy, which are described in greater detail in this document), which also offers a comprehensive overview of what anvi-estimate-scg-taxonomy can do.

Keep in mind that the scg-taxonomy framework currently uses single-copy core genes found in GTDB genomes, thus it will not work well for low-completion, viral, or eukaryotic genomes.

This same functionality anvi-estimate-scg-taxonomy is implicitly accessed thorugh the anvi’o interactive interface, when you turn on real-time taxonomy estimation for bins. So, if you’ve ever wondered where those estimates were coming from, now you know.

So, what can this program do?

1. Estimate the taxonomy of a single genome

By default, this program wll assume your contigs-db contains only one genome, and will try to use the single-copy core genes (that were associated with taxonomy when you ran anvi-run-scg-taxonomy) to try to identify the taxonomy of your genome.

When you run

anvi-estimate-scg-taxonomy -c contigs-db

It will give you the best taxonomy hit for your genome. If you would like to see how it got there (by looking at the hits for each of the single-copy core genes), just use the --debug flag to see more information, as so:

anvi-estimate-scg-taxonomy -c contigs-db \ --debug

2. Estimate the taxa within a metagenome

By running this program in metagenome mode, it will assume that your contigs-db contains multiple genomes and will try to give you an overview of the taxa within it. To do this, it will determine which single-copy core gene has the most hits in your contigs (for example Ribosomal_S6), and then will look at the taxnomy hits for that gene across your contigs. The output will be this list of taxonomy results.

anvi-estimate-scg-taxonomy -c contigs-db \ --metagenome-mode

If you want to look at a specific gene (instead of the one with the most hits), you can also tell it to do that. For example, to tell it to look at Ribosomal_S9, run

anvi-estimate-scg-taxonomy -c contigs-db \ --metagenome-mode \ --scg-name Ribosomal_S9

Without a profile-db, the output will report the frequency of each taxon — i.e., how many times that taxon was detected across the SCG hits in your contigs database. If you only care whether a taxon is present or absent rather than how many times it was detected, you can use the --presence-absence-only flag to get a binary report instead:

anvi-estimate-scg-taxonomy -c contigs-db \ --metagenome-mode \ --presence-absence-only

3. Look at the taxonomic composition as a tree

The table above answers the question “what is the taxonomy of each of these hits?”, which is not the same question as “what is in here?”. Since each row spells out an entire lineage, a taxon that occurs 30 times occupies 30 nearly identical rows, and the shape of the community is nowhere to be seen. If that is what you are after, add the flag --tree-output:

anvi-estimate-scg-taxonomy -c contigs-db \ --metagenome-mode \ --tree-output

which will show you the very same results as a hierarchical tree instead (please remember that the tree here has no phylogenetic order or meaning in its current implementation):

All Ribosomal_S11 copies (96)
├── Bacteria (94)
│   ├── Campylobacterota (36)
│   │   └── Campylobacteria (36)
│   │       └── Campylobacterales (36)
│   ├── Desulfobacterota (16)
│   │   ├── Desulfobulbia (9)
│   │   │   └── Desulfobulbales (9)
│   │   ├── Desulfobacteria (3)
│   │   │   └── Desulfobacterales (3)
(...)
└── Archaea (2)
    └── Halobacteriota (2)
        └── Methanosarcinia (2)
            └── Methanosarcinales (2)

The number next to each taxon is the number of things that were assigned to it or to anything under it, which is why the numbers of a node’s children always add up to the number of the node itself. What is being counted depends on how you ran the program: copies of the single-copy core gene anvi’o surveyed in metagenome mode (Ribosomal_S11 in the example above), bins if you gave anvi’o a collection, and genomes otherwise. The root of the tree spells out which one it is, so you never have to guess.

Hits that could not be resolved all the way down show up in an explicit Unknown_* node at the level where they ran out of names (as in Unknown_genera) rather than being quietly dropped, so nothing goes missing from the tree.

By default the tree does not go deeper than genus names, since species-level assignments from single-copy core genes are often absent or not particularly trustworthy. If you want a different cutoff, use --tree-output-level:

anvi-estimate-scg-taxonomy -c contigs-db \ --metagenome-mode \ --tree-output \ --tree-output-level t_family

Please note that --tree-output-level has nothing to do with the --taxonomic-level parameter, and only influences the tree that is displayed in your terminal.

Two small things to know about this flag. First, it only changes what is displayed: if you also ask for an output file with -o, that file will contain the usual TAB-delimited table, exactly as it would have without --tree-output. Second, since a tree is the only thing this flag produces, anvi’o will refuse to run it together with --quiet (which would show you nothing) or --as-markdown (which would mangle the characters anvi’o uses to draw the tree).

If you are working with a metagenomes or external-genomes file, --tree-output will give you a single tree in which the results from every one of your inputs are merged together. This is not really the appropriate display for many (meta)genomes at once, since a tree gives you no way to tell which input a taxon came from, and anvi’o will warn you about that – but if a bird’s eye view of everything at once is what you want, there it is.

4. Look at relative abundance of taxa across samples

If you provide a merged profile-db or single-profile-db, then you’ll be able to look at the relative abundance of your taxonomy hits (through a single-copy core gene) across your samples. Essentially, this adds additional columns to your output (one per sample) that descrbe the relative abundance of each hit in each sample.

Running this will look something like this,

anvi-estimate-scg-taxonomy -c contigs-db \ --metagenome-mode \ -p profile-db \ --compute-scg-coverages

For an example output, take a look at this page.

If you add --tree-output to a command like the one above, each node of the tree will report a coverage value in addition to its count. That value is the total coverage of everything under that node, summed across all of your samples. A tree has no room for one column per sample, so if you need per-sample numbers, ask for an output file with -o.

5. Estimate the taxonomy of your bins

This program basically looks at each of the bins in your collection as a single genome and tries to assign it taxonomy information. To do this, simply provide a collection, like this:

anvi-estimate-scg-taxonomy -c contigs-db \ -C collection

You can also look at the relative abundances across your samples at the same time, by running something like this:

anvi-estimate-scg-taxonomy -c contigs-db \ -C collection \ -p profile-db \ --compute-scg-coverages

Pro tip: you can use the output that emerges from the following output,

anvi-estimate-scg-taxonomy -c contigs-db \ -p profile-db \ -C collection \ -o TAXONOMY.txt

to display the taxonomy of your bins in the anvi’o interactive interface in collection mode:

anvi-interactive -c contigs-db \ -p profile-db \ -C collection \ --additional-layers TAXONOMY.txt

That simple.

6. Look at multiple metagenomes at the same time

You can even use this program to look at multiple metagenomes by providing a metagenomes artifact. This is useful to get an overview of what kinds of taxa might be in your metagenomes, and what kinds of taxa they share.

Running this

anvi-estimate-scg-taxonomy --metagenomes metagenomes \ --output-file-prefix EXAMPLE

will give you an output file containing all taxonomic levels found and their coverages in each of your metagenomes.

For a concrete example, check out this page.

7. Estimate taxonomy across multiple genomes using an external genomes file

You can also run this program on a set of genomes described in an external-genomes file:

anvi-estimate-scg-taxonomy --external-genomes external-genomes \ --output-file-prefix EXAMPLE

If you want to treat each genome as a metagenome (i.e., report the taxonomic composition within each genome rather than a single consensus taxonomy for it), add the --metagenome-mode flag:

anvi-estimate-scg-taxonomy --external-genomes external-genomes \ --metagenome-mode \ --output-file-prefix EXAMPLE

A note on SCG selection when working with multiple contigs databases

When you use --external-genomes or --metagenomes together with --metagenome-mode, anvi’o must pick a single SCG to use consistently across all contigs databases. This is critical for result comparability: using different SCGs for different databases would make the outputs impossible to compare.

If you do not explicitly name an SCG with --scg-name-for-metagenome-mode, anvi’o will automatically select the SCG that is most frequent across all your contigs databases combined, and will report which one it chose. You can inspect per-SCG frequencies beforehand with --report-scg-frequencies to make an informed choice.

If instead you want to use the most frequent SCG independently for each contigs database (which would make results incomparable across databases), you should run anvi-estimate-scg-taxonomy on each contigs database separately in --metagenome-mode.

Edit this file to update this information.

Command line interface

The following is the list of parameters and their descriptions in the latest version of anvi-estimate-scg-taxonomy.

The code that generates this web page ensures that this information is the latest available in 9-dev (eunice). Which means, in some cases the information in this section (generated automatically) might be more comprehensive or up-to-date compared to the descriptions above (written by humans).

Command line usage

anvi-estimate-scg-taxonomy [-h] [-c CONTIGS_DB] [-m] [-p PROFILE_DB] [-C COLLECTION_NAME] [-e FILE_PATH] [-M FILE_PATH] [-o FILE_PATH] [--per-scg-output-file FILE_PATH] [-O FILENAME_PREFIX] [--taxonomic-level {t_domain,t_phylum,t_class,t_order,t_family,t_genus,t_species}] [--matrix-format] [--raw-output] [--tree-output] [--tree-output-level {t_domain,t_phylum,t_class,t_order,t_family,t_genus,t_species}] [-T NUM_THREADS] [-S SCG_NAME] [--report-scg-sequences-file-prefix FILE NAME PREFIX] [--report-scg-frequencies FILE_PATH] [--just-do-it] [--skip-checking-genome-hashes] [--simplify-taxonomy-information] [--compute-scg-coverages] [--presence-absence-only] [--update-profile-db-with-taxonomy] [-r PATH]

Parameters and their descriptions

INPUT #1 The minimum you must provide this program is a contigs database. In which case anvi'o will attempt to estimate taxonomy for all contigs in it, assuming that the contigs database represents a single genome. If the contigs database is actually a metagenome, you should use the `--metagenome` flag to explicitly declare that.
-c, --contigs-db CONTIGS_DB
Anvi'o contigs database generated by 'anvi-gen-contigs-database'
-m, --metagenome-mode
Treat a given contigs database as an unbinned metagenome rather than treating it as a single genome.
INPUT #2 In addition, you can also point out a profile database. In which case you also must provide a collection name. When you do that anvi'o will offer taxonomy estimates for each bin in your collection.
-p, --profile-db PROFILE_DB
Anvi'o profile database
-C, --collection-name COLLECTION_NAME
Collection name.
INPUT #3 You can also work with a external genomes or metagenomes file, assuming that you have multiple (meta)genomes with or without associated mapping results, and anvi'o would generate a single output file for all.
-e, --external-genomes FILE_PATH
A two-column TAB-delimited flat text file that lists anvi'o contigs databases. The first item in the header line should read 'name', and the second should read 'contigs_db_path'. Each line in the file should describe a single entry, where the first column is the name of the genome (or MAG), and the second column is the anvi'o contigs database generated for this genome.
-M, --metagenomes FILE_PATH
A two-column TAB-delimited flat text file. The header line must contain these columns: 'name', 'contigs_db_path', and 'profile_db_path'. Each line should list a single entry, where 'name' can be any name to describe the metagenome stored in the anvi'o contigs database. In this context, the anvi'o profiles associated with contigs database must be SINGLE PROFILES, as in generated by the program `anvi-profile` and not `anvi-merge`.
OUTPUT AND FORMATTING Anvi'o will do its best to offer you some fancy output tables for your viewing pleasure by default. But in addition to that, you can ask the resulting information to be stored in a TAB-delimited file (which is a much better way to include the results in your study as supplementary information, or work with these results using other analysis tools such as R). Depending on the mode you are running this program, anvi'o may ask you to use an 'output file prefix' rather than an 'output file path'.
-o, --output-file FILE_PATH
File path to store results.
--per-scg-output-file FILE_PATH
A more detailed output file that will describe taxonomy of each scg in a single bin. When consensus taxonomy is generated per bin or genome, taxonomy for each underlying item is not reported. This additional optional output file will elucidate things.
-O, --output-file-prefix FILENAME_PREFIX
A prefix to be used while naming the output files. No file type extensions please; just a prefix -- all ouptut file names and extensions will be appended to this prefix.
--taxonomic-level TAXONOMIC_LEVEL
The taxonomic level to use whenever relevant and/or available. The default taxonomic level is None, but if you choose something specific, anvi'o will focus on that whenever possible. Choices: t_domain t_phylum t_class t_order t_family t_genus t_species
--matrix-format
If you want the reports to look like sparse matrices whenever possible, declare this flag. Matrices are especially good to use when you are working with internal/external genomes since they can show you quickly the distribution of each taxon across all metagenomes in programs like EXCEL. WELL TRY IT AND SEE.
--raw-output
Just store the raw output without any processing of the primary data structure.
--tree-output
Rather than showing you a table where each row describes the entire lineage of a single item, display the results as a hierarchical tree in your terminal, where each node shows the number of items that were assigned to that taxon or to anything under it. This is a much better way to get a quick sense of the taxonomic make up of a metagenome (based on SCGs, anticodons, or who knows what else, since the items will depend on the program you use and your parameters). Declaring this flag will not influence any of the output files you may have asked for. While they will continue describing the very same results in their usual TAB-delimited fashion, this flag will add more fabulous to your terminal.
--tree-output-level TREE_OUTPUT_LEVEL
The deepest taxonomic level to show when you are asking for a tree with `--tree-output`. The default is 't_genus', which means the tree will not show you species names. Please note that this parameter has nothing to do with the parameter `--taxonomic-level`, and it will only influence the tree that is displayed in your terminal. Choices: t_domain t_phylum t_class t_order t_family t_genus t_species
PERFORMANCE We are not sure if allocating more threads for this operation will change anything. But hey. One can try.
-T, --num-threads NUM_THREADS
Maximum number of threads to use for multithreading whenever possible. Very conservatively, the default is 1, unless the environmental variable `ANVIO_THREADS` sets another positive integer. If you use this parameter, it will override `ANVIO_THREADS`. It is a good idea to not exceed the number of CPUs / cores on your system. Plus, please be careful with this option if you are running your commands on a SGE -- if you are clusterizing your runs, and asking for multiple threads to use, you may deplete your resources very fast. Default: 1
AUTHORITY Assert your dominance.
-S, --scg-name-for-metagenome-mode SCG_NAME
When running in metagenome mode, anvi'o automatically chooses the most frequent single-copy core gene to estimate the taxonomic composition within a contigs database. If you have a different preference you can use this parameter to communicate that.
--report-scg-sequences-file-prefix FILE NAME PREFIX
When running in metagenome mode, anvi'o has access to each SCG sequence. By providing a file prefix, you can instruct anvi'o to report amino acid and DNA sequences for each SCG it uses to estimate taxonomy. The deflines of the resulting FASTA files will match tot he unique entry IDs used to populate the output file that reports taxonomy. Please note that this parameter will only run if you set the parameter `--scg-name-for-metagenome-mode`.
--report-scg-frequencies FILE_PATH
Report SCG frequencies in a TAB-delimited file and quit. This is a great way to decide which SCG name to use in metagenome mode (we often wish to use the most frequent SCG to increase the detection of taxa).
--just-do-it
Don't bother me with questions or warnings, just do it.
ADVANCED Very pro-like stuff.
--skip-checking-genome-hashes
Use this flag if you would like anvi'o to skip checking genome hashes. This is only relevant if you may have genomes in your internal or external genomes files that have identical sequences with different names AND if you are OK with it. You may be OK with it, for instance, if you are using `anvi-dereplicate-genomes` program to dereplicate genomes desribed in multiple collections in an anvi'o profile database that may be describing the same genome multiple times (see https://github.com/merenlab/anvio/issues/1397 for a case).
--simplify-taxonomy-information
The taxonomy output may include a large number of names that contain clade-specific code for not-yet-characterized taxa. With this flag you can simplify taxon names. This will influence all output files and displays as the use of this flag will on-the-fly trim taxonomic levels with clade-specific code names.
--compute-scg-coverages
When this flag is declared, anvi'o will go back to the profile database to learn coverage statistics of single-copy core genes for which we have taxonomy information.
--presence-absence-only
When this flag is declared, anvi'o will report only binary presence/absence information for each taxon rather than the number of times each SCG was observed. This is particularly useful when working with external genomes files to generate matrix outputs, where raw SCG frequencies may be difficult to interpret. If you use this flag together with `--compute-scg-coverages` will make anvi'o disappoint.
--update-profile-db-with-taxonomy
When anvi'o knows all both taxonomic affiliations and coverages across samples for single-copy core genes, it can, in theory add this information to the profile database. With this flag you can instruct anvi'o to do that and find information on taxonomy in the `layers` tab of your interactive interface.
BORING Options that you will likely never need.
-r, --taxonomy-database PATH
Path to the directory that contains the BLAST databases for single-copy core genes. You will almost never need to use this parameter unless you are trying something very fancy. But when you do, you can tell anvi'o where to look for database files through this parameter.

Additional Resources

Are you aware of resources that may help users better understand the utility of this program? Please feel free to edit this file on GitHub. If you are not sure how to do that, find the __resources__ tag in this file to see an example.

Copyleft, The anvi'o Project