anvi-display-functions
Table of Contents
- Authors
- Requires
- Can use
- Provides
- Can provide
- Usage
- Quick & Simple Run
- Combining genomes from multiple sources
- Performing functional enrichment analysis for free
- Aggregating functions using accession IDs
- Aggregating functions using all function hits
- The min-occurrence limit
- A real-world example
- Command line interface
- Additional Resources
Start an anvi'o interactive display to see 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
For a given annotation source for functions, this program will display distribution patterns of unique function names (or accession numbers) across genomes stored in anvi’o databases.
It is a powerful way to analyze differentially occurring functions for any source of annotation that is shared across all genomes.
Currently, anvi-display-functions can work with any combination of genomes from external-genomes, internal-genomes, and genomes-storage-db.
If you are only interested in a text output, see the program anvi-gen-function-matrix that can report functions-across-genomes-txt files.
Quick & Simple Run
The simplest way to run this program is as follows:
anvi-display-functions -e external-genomes \ --annotation-source KOfam \ --profile-db KOFAM-PROFILE.db
You can replace the annotation source based on what is available across your genomes. You can use the program anvi-db-info to see all available function annotation sources in a given contigs-db or genomes-storage-db. You can also use the program anvi-import-functions to import ANY kind of functional grouping of your genes and use those ad hoc functional sources to display their distribution across genomes. Please see functions for more information on functions and how to obtain them.
Please note that a profile-db will be automatically generated for you. Once it is generated, the same profile database can be visualized over and over again using anvi-interactive in manual mode, without having to retain any other files.
Combining genomes from multiple sources
You can run this program by combining genomes from multiple sources:
anvi-display-functions -e external-genomes \ -i internal-genomes \ -g genomes-storage-db \ --annotation-source KOfam \ --profile-db KOFAM-PROFILE.db
This way, you can bring together functions in your metagenome-assembled genomes, the isolates you have acquired from external sources, and even genomes in an anvi’o pangenome into a single framework in a disturbingly easy fashion.
Performing functional enrichment analysis for free
This is an optional step, but may be very useful for some investigations. If your genomes are divided into meaningful groups, you can also perform a functional enrichment analysis while running this program. All you need to do for this to be included in your analysis is to provide a groups-txt file that describes which genome belongs to which group:
anvi-display-functions -e external-genomes \ --groups-txt groups-txt --annotation-source KOfam \ --profile-db KOFAM-PROFILE.db
If you are using multiple sources for your genomes, you may not immediately know which genomes to list in your groups-txt file. In that case, you can first run the program with this additional parameter,
anvi-display-functions -e external-genomes \ -i internal-genomes \ -g genomes-storage-db \ --annotation-source COG20_FUNCTION \ --profile-db COGS-PROFILE.db \ --print-genome-names-and-quit
In which case anvi’o would report all the functions once it recovers everything from all sources, and print them out for you to create a groups file before re-running the program with it.
This analysis will add the following additional layers in your interactive display: ‘enrichment_score’, ‘unadjusted_p_value’, ‘adjusted_q_value’, ‘associated_groups’. See functional-enrichment-txt to learn more about these columns.
Aggregating functions using accession IDs
Once it is run, this program essentially aggregates all function names that occur in one or more genomes among the set of genomes found in input sources. The user can ask the program to use accession IDs to aggregate functions rather than function names:
anvi-display-functions -e external-genomes \ --annotation-source KOfam \ --profile-db KOFAM-PROFILE.db \ --aggregate-based-on-accession
While the default setting, which is to use function names, will be appropriate for most applications, using accession IDs instead of function names may be important for specific purposes. There may be an actual difference between using functions or accession to aggregate data since multiple accession IDs in various databases may correspond to the same function. This may lead to misleading enrichment analyses downstream as identical function annotations may be over-split into multiple groups. Thus, the default aggregation method uses function names.
Aggregating functions using all function hits
This is a bit confusing, but actually it is not. In some cases a gene may be annotated with more than one function names. This is a decision often made at the function annotation tool level. For instance anvi-run-ncbi-cogs may yield two COG annotations for a single gene because the significance score for both hits may exceed the default cutoff. While this can be useful in 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, anvi-display-functions will will use the best hit for any gene that has multiple hits. But this behavior can be turned off the following way:
anvi-display-functions -e external-genomes \ --annotation-source KOfam \ --profile-db KOFAM-PROFILE.db \ --aggregate-using-all-hits
The min-occurrence limit
You can choose to limit the number of functions to be considered to those that occur in more than a minimum number of genomes:
anvi-display-functions -e external-genomes \ --annotation-source KOfam \ --profile-db KOFAM-PROFILE.db \ --min-occurrence 5
Here the --min-occurrence 5 parameter will exclude any function that appears to occur in less than 5 genomes in your collection.
A real-world example
Assume we have a list of external-genomes that include three different species of Bifidobacterium. Running the following command,
anvi-display-functions --external-genomes Bifidobacterium.txt \ --annotation-source COG20_FUNCTION \ --profile-db COG20-PROFILE.db \ --min-occurrence 3
Would produce the following display by default, where each layer is one of the genomes described in the external-genomes file, and each item is a unique function name that occur in COG20_FUNCTION (which was obtained by running anvi-run-ncbi-cogs on each contigs-db in the external genomes file) that were found in more than three genomes:
The outermost layer shows the function names:
After a quick prettification through the interactive interface, leads to a cleaner display of three distinct species in this group, and functions that are uniquely enriched in either of them:
Now the resulting profile-db can be used by anvi-interactive to re-visualize these data, or can be shared with the community without sharing the underlying contigs databases.
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-display-functions.
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 everyghing, 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.
--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
-p, --profile-dbPROFILE_DBrequired- Anvi'o profile 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.
--dry-run- Don't do anything real. Test everything, and stop right before wherever the developer said 'well, this is enough testing', and decided to print out results.
--skip-news- Don't try to read news content from upstream.
--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).
-I, --ip-addressIP_ADDR- IP address for the HTTP server. The default ip address (localhost) should work just fine for most. Default:
localhost -P, --port-numberINT- Port number to use for anvi'o services. If nothing is declared, anvi'o will try to find a suitable port number, starting from the default port number, 8080.
--browser-pathPATH- By default, anvi'o will use your default browser to launch the interactive interface. If you would like to use something else than your system default, you can provide a full path for an alternative browser using this parameter, and hope for the best. For instance we are using this parameter to call Google's experimental browser, Canary, which performs better with demanding visualizations.
--read-only- When the interactive interface is started with this flag, all 'database write' operations will be disabled.
--server-only- The default behavior is to start the local server, and fire up a browser that connects to the server. If you have other plans, and want to start the server without calling the browser, this is the flag you need.
--password-protected- If this flag is set, command line tool will ask you to enter a password and interactive interface will be only accessible after entering same password. This option is recommended for shared machines like clusters or shared networks where computers are not isolated.
--user-server-shutdown- Allow users to shutdown an anvi'server via web interface.
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.