anvi-estimate-trna-taxonomy

Estimates taxonomy at genome and metagenome level using tRNA sequences..

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

Authors

A. Murat Eren (Meren)

Requires

contigs-db trna-taxonomy

Can use

profile-db collection bin metagenomes dna-sequence

Provides

genome-taxonomy

Can provide

genome-taxonomy-txt

Usage

This program uses the taxonomy associates of your tRNA sequences to estimate the taxonomy for genomes, metagenomes, or collection stored in your contigs-db.

This is the final step in the trna-taxonomy workflow. Before running this program, you’ll need to have run anvi-run-trna-taxonomy on the contigs-db that you’re inputting to this program.

Input options

1: Running on a single genome

By default, this program will assume that your contigs-db contains only a single genome and will determine the taxonomy of that single genome.

anvi-estimate-trna-taxonomy -c contigs-db

This will give you only the best taxonomy hit for your genome based on your tRNA data. If you want to look under the hood and see what results from anvi-run-trna-taxonomy it’s using to get there, add the --debug flag.

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

2: Running on a metagenome

In metagenome mode, this program 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, anvi’o will determine which anticodon has the most hits in your contigs (for example GGG), and then will look at the taxnomy hits for tRNA with that anticodon across your contigs.

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

If instead you want to look at a specific anticodon, you can specify that with the -S parameter. For example, to look at GGT, just run the following:

anvi-estimate-trna-taxonomy -c contigs-db \ --metagenome-mode \ -S GGT

Since each row of the resulting table spells out an entire lineage, it can be hard to tell what is actually in your metagenome when the same taxon shows up over and over again. If you would rather see the taxonomic composition itself, add the flag --tree-output:

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

which will show you the very same results as a hierarchical tree, where the number next to each taxon is the number of tRNA genes that were assigned to it or to anything under it. Since metagenome mode surveys a single anticodon, the root of the tree names the one anvi’o ended up using:

All GGG copies (28)
├── Bacteria (26)
│   ├── Bacillota (14)
│   │   └── Bacilli (14)
│   │       └── Staphylococcales (14)
│   └── Unknown_phyla (12)
└── Archaea (2)

By default the tree does not go deeper than genus names. Use --tree-output-level if you want a different cutoff (note that this parameter has nothing to do with --taxonomic-level, and only influences the tree in your terminal):

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

This flag only changes what is displayed – any output file you ask for will contain the usual TAB-delimited table. And since the tree is the only thing this flag produces, anvi’o will not let you use it together with --quiet or --as-markdown.

3: Running on multiple metagenomes

You can 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-trna-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, based on their tRNA.

4: Estimating the taxonomy of bins

You can use this program to estimate the taxonomy of all of the bins in a collection by providing the collection and the associated profile-db.

anvi-estimate-trna-taxonomy -c contigs-db \ --C collection \ --p profile-db

When doing this, you can also put the final results into your profile-db as a misc-data-layers with the flag --update-profile-db-with-taxonomy

5: I don’t even have a contigs-db. Just a fasta file.

This program can run the entire ad hoc sequence search without a contigs-db involved (just a fasta and number of target sequences as a percent of the total; default: 20 percent), but this is not recommended. However, if you provide other parameters, they will be ignored.

anvi-estimate-trna-taxonomy --dna-sequence fasta \ --max-num-target-sequences 10

The Output

Now that you’ve inputted your desired inputs, you think about whether you want an output and what it will look like. By default, this program won’t give you an output (just genome-taxonomy information in your contigs-db. However, if you add any of these output options, it will instead produce a genome-taxonomy-txt.

Anticodon Frequencies

If you want to look at the anticodon frequencies before getting taxonomy info at all (for example because you can’t decide which anticodon to use for input option 2), add the flag --report-anticodon-frequencies. This will report the anticodon frequencies to a tab-delimited file and quit the program.

A single output

To get a single output (a fancy table for your viewing pleasure), just add the output file path.

In this example, the input will be a single contigs-db (input option 1),

anvi-estimate-trna-taxonomy -c contigs-db \ -o path/to/output.txt

This will give you a tab-delimited matrix with all levels of taxonomic information for the genome stored in your contigs-db. Specifically, the output is a genome-taxonomy-txt.

If you want to focus on a single taxonomic level, use the parameter --taxonomic-level, like so:

anvi-estimate-trna-taxonomy -c contigs-db \ -o path/to/output.txt \ --taxonomic-level genus

You can also simplify the taxonomy names in the table with the flag --simplify-taxonomy-information

If you’re running on a profile-db, you can also choose to add the anticodon coverage to the output with --compute-anticodon-coverages.

Multiple outputs

If you have multiple outputs (i.e. you are looking at multiple metagenomes (input option number 3) or you are looking at each anticodon individually with --per-anticodon-output-file), you should instead provide a output filename prefix.

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

The rest of the options listed for the single output (i.e. focusing on a taxonomic level, simplifying taxonomy information, etc.) still apply.

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-trna-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-trna-taxonomy [-h] [-c CONTIGS_DB] [-m] [-p PROFILE_DB] [-C COLLECTION_NAME] [-M FILE_PATH] [--dna-sequence DNA SEQ] [--max-num-target-sequences NUMBER] [-o FILE_PATH] [--per-anticodon-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 ANTICODON] [--report-anticodon-frequencies FILE_PATH] [--just-do-it] [--simplify-taxonomy-information] [--compute-anticodon-coverages] [--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 metagenomes file, assuming that you have multiple metagenomes with or without associated mapping results, and anvi'o would generate a singe output file for all.

-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`.

INPUT #4 Ad hoc sequence search. No contigs databases, no profiles. The lazy stayla. Please note that if you use parameters defined under this optin, none of the other standard parameters for this program will be taken into consideration.

--dna-sequence DNA SEQ: Literally a DNA sequence. For the very lazy.
--max-num-target-sequences NUMBER: Maximum number of target sequences to request from BLAST or DIAMOND searches. The default is 20%. Default: 20

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-anticodon-output-file FILE_PATH: A more detailed output file that will describe taxonomy of each anticodon 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, --anticodon-for-metagenome-mode ANTICODON: When running in metagenome mode, anvi'o automatically chooses the most frequent anticodon to estimate the taxonomic composition within a contigs database. If you have a different preference you can use this parameter to communicate that.
--report-anticodon-frequencies FILE_PATH: Report anticodon frequencies in a TAB-delimited file and quit. This is a great way to decide which anticodon to use in metagenome mode (we often wish to use the most frequent anticodon 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.

--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-anticodon-coverages: When this flag is declared, anvi'o will go back to the profile database to learn coverage statistics of tRNA genes used for taxonomy.
--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.