anvi-compute-functional-enrichment-across-genomes

A program that computes functional enrichment across groups of genomes..

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

Authors

Iva Veseli
EmailTwitterGithub
Amy D. Willis
WebEmailTwitterGithub

Requires

groups-txt external-genomes functions

Can use

internal-genomes genomes-storage-db

Provides

functional-enrichment-txt

Usage

This program computes functional enrichment across groups of genomes and returns a functional-enrichment-txt file.

For its sister programs, see anvi-compute-functional-enrichment-in-pan and anvi-compute-metabolic-enrichment.

Please also see anvi-display-functions which can both calculate functional enrichment, AND give you an interactive interface to display the distribution of functions.

Functional enrichment

You can use this program by combining genomes described through external-genomes, internal-genomes, and/or stored in a genomes-storage-db. In addition to sources for your genomes, you will need to provide a groups-txt file to declare which genome belongs to which group for enrichment analysis to consider.

How does it work?

  1. Aggregate functions from all sources. Gene calls in each genome are tallied according to their functional annotations from the given annotation source.

  2. Quantify the distribution of functions in each group of genomes. This information is then used by anvi-script-enrichment-stats to fit a GLM to determine (1) the level that a particular functional annotation is unique to a single group and (2) the percent of genomes it appears in in each group. This produces a functional-enrichment-txt file.

The script anvi-script-enrichment-stats was implemented by Amy Willis, and described first in this paper.

Basic usage

You can use it with a single source of genomes:

anvi-compute-functional-enrichment-across-genomes -i internal-genomes \ -o functional-enrichment-txt \ -G groups-txt \ --annotation-source FUNCTION_SOURCE

or many:

anvi-compute-functional-enrichment-across-genomes -i internal-genomes\ -e external-genomes \ -G groups-txt \ -g genomes-storage-db \ -o functional-enrichment-txt \ --annotation-source FUNCTION_SOURCE

Additional Parameters

You can get a tab-delimited matrix describing the occurrence (counts) of each function within each genome using the --functional-occurrence-table-output parameter:

anvi-compute-functional-enrichment-across-genomes -i internal-genomes \ -G groups-txt \ -o functional-enrichment-txt \ --annotation-source FUNCTION_SOURCE --functional-occurrence-table-output FUNC_OCCURRENCE.TXT

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-compute-functional-enrichment-across-genomes.

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-compute-functional-enrichment-across-genomes [-h] [-e FILE_PATH] [-i FILE_PATH] [-g GENOMES_STORAGE] -G TEXT_FILE [--annotation-source FUNCTION_ANNOTATION_SOURCE] [-l] -o FILE_PATH [--include-ungrouped] [-F FILE] [--qlambda NUM] [--skip-checking-genome-hashes] [--just-do-it]

Parameters and their descriptions

SOURCES OF GENOMES To estimate enriched functions across your geonomes, you can provide any combination of the following: an external genomes file, an internal genomes file, and/or a genomes storage file. Anvi'o will aggregate all functions in genomes found in any of these sources, and will do its magic.
-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.
-i, --internal-genomes FILE_PATH
A five-column TAB-delimited flat text file. The header line must contain these columns: 'name', 'bin_id', 'collection_id', 'profile_db_path', 'contigs_db_path'. Each line should list a single entry, where 'name' can be any name to describe the anvi'o bin identified as 'bin_id' that is stored in a collection.
-g, --genomes-storage GENOMES_STORAGE
Anvi'o genomes storage file
RELATIONSHIPS BETWEEN GENOMES Here you need to provide a groups file so anvi'o can understand which genome is in which group.
-G, --groups-txt TEXT_FILE required
A tab-delimited text file specifying which group each item belongs to. Depending on the context, items here may be individual samples or genomes. The first column must contain item names matching to those that are in your input data. A different column should have the header 'group' and contain the group name for each item. Each item should be associated with a single group. It is always a good idea to define groups using single words without any fancy characters. For instance, `HIGH_TEMPERATURE` or `LOW_FITNESS` are good group names. `my group #1` or `IS-THIS-OK?`, are not good group names.
FUNCTION ANNOTATION SOURCE Here you tell anvi'o which function annotation source to use. Obviously, any given function annotation source will have to be common to all genomes. You can see what you have in any of the contigs databases you can use the program `anvi-db-info`. YOU'RE ALMOST THERE.
--annotation-source FUNCTION_ANNOTATION_SOURCE
Get functional annotations for a specific annotation source. You can use the flag '--list-annotation-sources' to learn about what sources are available.
-l, --list-annotation-sources
List available functional annotation sources.
OUTPUT What comes out the other end. The only thing mandatory here is the output file.
-o, --output-file FILE_PATH required
File path to store results.
--include-ungrouped
Use this flag if you want anvi'o to include genomes with no group in the analysis. This means the genome has nothing in the 'group' column of the input file. By default all variables with no value will be ignored, but if you apply this flag, they will instead be considered as a single group (called 'UNGROUPED' when performing the statistical analysis.
-F, --functional-occurrence-table-output FILE
Saves the occurrence frequency information for functions in genomes in a TAB-delimited format. A file name must be provided. To learn more about how the functional occurrence is computed, please refer to the tutorial.
OPTIONAL THINGIES If you want it, here it is, come and get it.
--qlambda NUM
If you want to set the maximum lambda value for q-value estimation, provide a fraction between 0.05 and 1.
--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).
--just-do-it
Don't bother me with questions or warnings, just do it.

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