anvi-compute-metabolic-enrichment

Authors
Requires
Can use
Provides
Usage
Module enrichment

How does it work?
Basic usage
Additional parameters

Command line interface

Command line usage
Parameters and their descriptions

Additional Resources

A program that computes metabolic enrichment across groups of genomes and metagenomes.

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

Authors

Iva Veseli

Amy D. Willis

Requires

groups-txt

Can use

kegg-metabolism user-metabolism external-genomes internal-genomes functions

Provides

functional-enrichment-txt

Usage

This program computes metabolic module enrichment across groups of genomes or metagenomes and returns a functional-enrichment-txt file (throughout this text, we will use the term genome to describe both for simplicity).

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

Module enrichment

To run this program, you must already have estimated the completeness of metabolic modules in your genomes using the program anvi-estimate-metabolism and obtained a “modules” mode output file (which is the default output mode of that program). In addition to that, 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?

Determine the presence of modules. Each module in the “modules” mode output has a completeness score associated with it in each genome, and any module with a completeness score over a given threshold (set by --module-completion-threshold) will be considered to be present in that genome.
Quantify the distribution of modules in each group of genomes. The distribution of a given module across genomes in each group will determine its enrichment. This is done by fitting a generalized linear model (GLM) with a logit linkage function in anvi-script-enrichment-stats, and it 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

See kegg-metabolism or user-metabolism for more information on how to generate a “modules” mode output format from anvi-estimate-metabolism. Please note that the genome names in the modules file must match those that you will mention in the groups-txt file.

anvi-compute-metabolic-enrichment -M MODULES.TXT \ -G groups-txt \ -o functional-enrichment-txt

Additional parameters

The default completeness threshold for a module to be considered ‘present’ in a genome is 0.75 (=75%). If you wish to change this, you can do so by providing a different threshold between (0, 1], using the --module-completion-threshold parameter:

anvi-compute-metabolic-enrichment -M MODULES.TXT \ -G groups-txt \ -o functional-enrichment-txt \ --module-completion-threshold 0.9

By default, this program uses the pathwise completeness score to determine which modules are ‘present’ in a genome, but you can ask it to use stepwise completeness instead by using the --use-stepwise-completeness flag.

anvi-compute-metabolic-enrichment -M MODULES.TXT \ -G groups-txt \ -o functional-enrichment-txt \ --use-stepwise-completeness

By default, the column containing genome names in your MODULES.TXT file will have the header db_name, but there are certain cases in which you might have them in a different column name for your genomes or metagenomes (such as those cases where you did not run anvi-estimate-metabolism in multi-mode). In those cases, you can tell this program to look for a different column name to find your genomes or metagenomes using the --sample-header. For example, if your metagenome names are listed under the metagenome_name column, you would do the following:

anvi-compute-metabolic-enrichment -M MODULES.TXT \ -G groups-txt \ -o functional-enrichment-txt \ --sample-header metagenome_name

If you ran anvi-estimate-metabolism on a bunch of extra genomes but only want to include a subset of them in the groups-txt, that is fine. By default, any samples from the MODULES.TXT file that are missing from the groups-txt will be ignored. However, there is also an option to include those missing samples in the analysis, as one big group called ‘UNGROUPED’. To do this, you can use the --include-samples-missing-from-groups-txt parameter.

anvi-compute-metabolic-enrichment -M MODULES.TXT \ -G groups-txt \ -o functional-enrichment-txt \ --include-samples-missing-from-groups-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-metabolic-enrichment.

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-metabolic-enrichment [-h] [-M TEXT_FILE] [-G TEXT_FILE] -o FILE_PATH [--sample-header SAMPLE_HEADER] [--module-completion-threshold NUM] [--use-stepwise-completeness] [--include-samples-missing-from-groups-txt] [--qlambda NUM] [--just-do-it]

Parameters and their descriptions

CRITICAL INPUTS This program requires TWO INPUT FILES: (1) an output file produced by the program `anvi-estimate-metabolism` as input and (2) a groups file (using the `--groups-txt` parameter) to specify which sample is in which group.

-M, --modules-txt TEXT_FILE: A tab-delimited text file specifying module completeness in every genome/MAG/sample that you are interested in. The best way to get this file is to run `anvi-estimate-metabolism --output-modes modules` on your samples of interest. Trust us.
-G, --groups-txt TEXT_FILE: 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.

OUTPUT OPTIONS What comes out the other end. (Please provide at least the output file name.)

-o, --output-file FILE_PATH required: File path to store results.

OPTIONAL OPTIONS If you want it, here it is, come and get it.

--sample-header SAMPLE_HEADER: The header of the column containing your sample names in the modules-txt input file. By default this is 'db_name' because we are assuming you got your modules mode output by running `anvi-estimate-metabolism` in multi mode (on multiple genomes or metagenomes), but just in case you got it a different way, this is how you can tell anvi'o which column to look at. The values in this column should correspond to those in the 'sample' column in the groups-txt input file. Default: db_name
--module-completion-threshold NUM: This threshold defines the percent completeness score at which we consider a KEGG module to be 'present'in a given sample. That is, if a module's completeness in a sample is less than this value, then we say the module is not present in that sample, and this will affect the module's enrichment score. By extension, if a module's completeness is less than this value in all samples, it will have a very very low enrichment score (ie, it will not be considered enriched at all, because it doesn't occur in any groups). Note that the closer this number is to 0, the more meaningless this whole enrichment analysis is... but hey, this is your show. This threshold CAN be different from the completeness threshold used in `anvi-estimate-metabolism` if you wish. The default threshold is 0.75. Default: 0.75
--use-stepwise-completeness: By default, this program will use pathwise completeness of a module to determine if it is present in a sample or not. To make it use stepwise completeness instead, provide this flag. Confused? Don't worry. Check out the online documentation for a discussion on pathwise vs stepwise completeness.
--include-samples-missing-from-groups-txt: Sometimes, you might have some sample names in your modules-txt file that you did not include in the groups-txt file. This is fine. By default, we will ignore those samples because they do not have a group. But if you use this flag, then instead those samples will be included in a group called 'UNGROUPED'.
--qlambda NUM: If you want to set the maximum lambda value for q-value estimation, provide a fraction between 0.05 and 1.
--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.