anvi-gen-function-matrix
Table of Contents
A program to generate reports for the distribution of functions across genomes.
🔙 To the main page of anvi’o programs and artifacts.
Authors
Requires
Can use
internal-genomes 
genomes-storage-db 
groups-txt
Provides
Can provide
Usage
Generates TAB-delmited output files for functions from a single function annotation source across all contigs-db files it receives.
For a simlar program that reports HMM hits instead, see anvi-gen-hmm-hits-matrix.
The input genomes, metagenomes, or loci for this program can be provided through an external-genomes, internal-genomes, genomes-storage-db, or any combination of these sources.
This program is very similar to anvi-display-functions, and can also perform a functional enrichment analysis on-the-fly if you provide it with an optional groups-txt file. But unlike, anvi-display-functions, this program will report TAB-delmited output files for you to further analyze.
You can always learn about which functions are in a given contigs-db using the program anvi-db-info.
You can run the program on a set of contigs-db files with a specific source of function annotation:
anvi-gen-function-matrix -e external-genomes \ --annotation-source functions \ --output-file-prefix MY-GENOMES
The command above will result in two files in your work directory (MY-GENOMES-FREQUENCY.txt and MY-GENOMES-PRESENCE-ABSENCE.txt) of type functions-across-genomes-txt.
In each of these files, the first few columns will describe functions (with a unique key, the full function name, and optionally the function accession ID), and the remaining columns will hold one value per genome.
These files will report raw frequency and presence/absence of functions across contigs-db files that you can use for downstream analyses.
Per-population copy number normalization for metagenomic assemblies
If you want to get an idea of differences in functional capacity across different metagenomic assemblies, but if you do not have MAGs from these assemblies or if you wish to make use of a larger fraction of the sequence data and not only only those reads that are used to reconstruct genomes, looking at the raw frequencies or raw presence/absence data becomes less effective for any downstream analysis as almost all functions and metabolic modules known will likely occur in at least in one population in a given metagenome. Although, normalizing the raw frequencies based on the estimated number of populations in a given environment would make such comparisons across metagenomes much more effective.
Anvi’o includes a means to estimate the number of populations observed in a given assembly using single-copy core genes, which is used in anvi-display-contigs-stats, and Veseli et al. has previously demonstrated its utility by predicting per-population copy number of metabolic modules observed across samples.
anvi-gen-function-matrix makes the same principle accessible with for functions via the flag --add-per-population-copy-number, which produces an additional output file with normalized copy numbers of the frequency of functions across samples:
anvi-gen-function-matrix -e external-genomes \ --annotation-source functions \ --output-file-prefix MY-METAGENOMES \ --add-per-population-copy-number
Adding the flag generates an additional output file, MY-METAGENOMES-PER-POPULATION-COPY-NUMBER.txt, of type functions-across-genomes-txt.
By dividing the frequency of each function in a given metagenomic assembly by the number of populations estimated to be present in that same assembly based on counts of single-copy core genes (SCGs) in each contigs-db: for each domain-specific SCG set, anvi’o takes the mode of the number of hits across all SCGs, and sums these per-domain estimates across Bacteria, Archaea, and Eukarya.
The script relies on SCG annotations generated by anvi-run-hmms, and you need an external-genomes file to let it know which assemblies to compare.
A per-population copy number is an average number of copies of a function per population: a value near 1 means the function tends to occur once in every population, a value below 1 means it is present in only a fraction of the populations, and a value above 1 means it tends to occur in multiple copies per population (as is common for, e.g., transposases). If a given metagenome has single-copy core genes that are too sparse to yield a reliable estimate, anvi’o cannot compute its number of populations, and the per-population copy number values for that assembly will be reported as NA.
Alternatively, you can run it with a groups-txt that associates sets of genomes with distinct groups,
anvi-gen-function-matrix -i internal-genomes \ --annotation-source functions \ --output-file-prefix MY-GENOMES \ --groups-txt groups.txt
which would generate an additional file in your work directory, MY-GENOMES-FUNCTIONAL-ENRICHMENT.txt, of type functional-enrichment-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-gen-function-matrix.
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
Parameters and their descriptions
-i, --internal-genomesFILE_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.
-e, --external-genomesFILE_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.
-g, --genomes-storageGENOMES_STORAGE- Anvi'o genomes storage file
-G, --groups-txtTEXT_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.
--print-genome-names-and-quit- Sometimes, especially when you are interested in creating a groups file for your genomes you gather from multiple different sources, it may be difficult to know every single genome name that will go into your analysis. If you declare this flag, after initializing everything, anvi'o will print out every genome name it found and quit, so you can actually put together a groups file for them.
--annotation-sourceFUNCTION_ANNOTATION_SOURCErequired- Get functional annotations for a specific annotation source. You can use the flag '--list-annotation-sources' to learn about what sources are available.
--aggregate-based-on-accession- This is important. When anvi'o aggregates functions for functional enrichment analyses or to display them, it uses by default the 'function text' as keys. This is because multiple accession IDs in various databases may correspond to the same function, and when you are doing a functional enrichment analysis, you most likely would like to avoid over-splitting of functions due to this. But then how can we know if you are doing something that requires things to be aggregated based on accession ids for functions rather than actual functions? We can't. But we have this flag here so you can instruct anvi'o to listen to you and not to us.
--aggregate-using-all-hits- This program will aggregate functions based on best hits only, and this flag will change that behavior. In some cases a gene may be annotated with multiple functions. This is a decision often made at the level of function annotation tool. For instance, when you run `anvi-run-ncbi-cogs`, you may end up having two COG annotations for a single gene because the gene hit both of them with significance scores that were above the default noise cutoff. While this can be useful when one visualizes functions or works with an `anvi-summarize` output where things should be most comprehensive, having some genes annotated with multiple functions and others with one function may over-split them (since in this scenario a gene with COGXXX and COGXXX;COGYYY would end up in different bins). Thus, when working on functional enrichment analyses or displaying functions anvi'o will only use the best hit for any gene that has multiple hits by default. But you can turn that behavior off explicitly and show anvi'o who is the boss by using this flag.
--also-report-accession-ids- When used, this flag will instruct anvi'o to also report the function accession ids in a new column, in addition to function name in the output file.
--min-occurrenceNUM GENOMES- The minimum number of occurrence of any given function accross genomes. If you set a value, those functions that occur in less number of genomes will be excluded. Default:
1
--add-per-population-copy-number- Request an additional output matrix that reports the per-population copy number (PPCN) of each function in every metagenomic assembly (or long-read metagenome). anvi'o divides the frequency of a function in a given assembly by the number of populations estimated to be present in that same assembly (estimated from single-copy core genes: the mode of the number of hits to the single-copy core genes of each domain, summed across Bacteria, Archaea, and Eukarya, just like `anvi-display-contigs-stats` does). This normalization is useful for metagenomic assemblies, where the raw frequency of a function scales with the number of populations in the assembly and is therefore not comparable across samples of vastly different community sizes. It follows the per-population copy number normalization introduced by Iva Veseli (Veseli et al. 2025). It requires that your contigs databases have been annotated with single-copy core genes via `anvi-run-hmms`, and it works only with an external-genomes file (`-e`), since population normalization is meaningful for whole metagenomic assemblies but not for individual genomes or a genomes storage database.
--gene-callerGENE-CALLER- The gene caller to utilize. Anvi'o supports multiple gene callers, and some operations (including this one) may require an explicit mentioning of which one to use. The default gene caller is identified automatically in most cases (based on whether the most frequent gene calls match to a known gene caller in anvi'o), but if you have a contigs-db generated with `--external-gene-callers` or something, you may have to pay extra attention here. Also, some HMM collections may add new gene calls into a given contigs-db as an ad-hoc fashion, so if you want to see all the options available to you in a given contigs database, please run the program `anvi-db-info` and take a look at the output.
--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).
-O, --output-file-prefixFILENAME_PREFIXrequired- 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.
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.