anvi-summarize
Table of Contents
Summarizer for anvi'o pan, pan-graph, or profile databases. Depending on the input, the program produces a output directory that contaisn flat files for rigorous downstream analyses by humans 🧠or LLMs 🤖..
🔙 To the main page of anvi’o programs and artifacts.
Authors
Requires
Can use
contigs-db 
pan-db pan-graph-db genomes-storage-db
Provides
pan-summary 
pan-graph-summary profile-summary
Can provide
Usage
Anvi-summarize lets you export a comprehensive overview of your data from an anvi’o database. Depending on the input, it can summarize a collection of binned contigs (from a profile-db), a collection of binned gene clusters (from a pan-db), or the full contents of a pan-graph-db. The output is a directory of flat files and an HTML index that conveniently displays them for you. This makes the program useful for sharing information with collaborators, generating supplementary files for manuscripts, and exporting data for use in downstream analyses.
See also anvi-summarize-blitz.
Output files
What this program produces as output depends on its inputs:
- Running it on a profile-db will produce a profile-summary output.
- Running it on a pan-db and genomes-storage-db will produce a pan-summary output.
- Running it on a pan-graph-db and genomes-storage-db will produce a pan-graph-summary output.
Running anvi-summarize
Running on a profile database
anvi-summarize -c contigs-db \ -p profile-db \ -o MY_SUMMARY \ -C collection
When running on a profile database, you also have options to:
- output very accurate (but intensely processed) coverage and detection data for each gene (using
--init-gene-coverages) - edit your contig names so that they contain the name of the bin that the contig is in (using
--reformat-contig-names) - also display the amino acid sequences for your gene calls (using
--report-aa-seqs-for-gene-calls)
Running on a pan database
A collection is optional when summarizing a pan-db. Without one, anvi’o will still export the full gene clusters table with all functional annotations — the bin_name column will simply be empty. If you have organized your gene clusters into bins using anvi-interactive or anvi-import-collection, passing the collection name will populate bin_name with the bin each gene cluster belongs to, which makes downstream filtering by bin straightforward.
Run without a collection (exports everything):
anvi-summarize -g genomes-storage-db \ -p pan-db
Run with a collection (adds bin_name to the output):
anvi-summarize -g genomes-storage-db \ -p pan-db \ -C collection
You can display DNA sequences instead of amino acid sequences with --report-DNA-sequences.
Running on a pan-graph database
A collection is optional when summarizing a pan-graph-db. Without one, all output files are still produced in full — the bin_name column in SYNGCs.txt and GENESxSYNGCs.txt will simply be empty. If you have organized your SynGCs into bins, passing the collection name will populate bin_name in both files, making it easy to filter the output to any bin of interest with a single column filter.
Run without a collection (exports everything):
anvi-summarize -g genomes-storage-db \ --pan-graph-db pan-graph-db
Run with a collection (adds bin_name to SYNGCs.txt and GENESxSYNGCs.txt):
anvi-summarize -g genomes-storage-db \ --pan-graph-db pan-graph-db \ -C collection
Computing DisCov statistics
When summarizing a profile database, you can optionally compute the Distribution of Coverage (DisCov) score for each bin and each contig within each bin. See discov-stats for a full description of the metric and its parameters.
To enable DisCov computation, use the --report-discov flag:
anvi-summarize -c contigs-db \ -p profile-db \ -o MY_SUMMARY \ -C collection \ --report-discov
This requires access to the auxiliary data file (AUXILIARY-DATA.db) in the same directory as the profile database and produces two additional output files under bins_across_samples/:
discov_bins.txt— one row per bin × samplediscov_contigs.txt— one row per contig × sample
You can adjust how DisCov is computed using the following parameters. When neither --window-length nor --window-length-as-percentage is specified, anvi’o applies context-sensitive defaults: a fixed 1,000 bp window for bins, and a percentage-based window (1% of contig length, minimum 300 bp) for individual contigs.
Window sizing for S
--window-length INT— use a fixed window size in bp for all sequences (bins and contigs)--window-length-as-percentage FLOAT— set window length as a percentage of each sequence’s length--min-window-length INT— minimum window length floor for percentage mode
Fold-range for E
--foldrange-lower FLOAT— lower bound of the coverage fold-range (default: 0.5)--foldrange-upper FLOAT— upper bound of the coverage fold-range (default: 2.0)
Combining S and E
--alpha FLOAT— weight of S relative to E, in [0, 1] (default: 0.5)--discov-formula STRING—linear(DisCov = αS + (1-α)E) orgeometric(DisCov = S^α × E^(1-α)) (default:linear)
Other notes
If you are unsure what collections are in your database, you can run this program with the flag --list-collections or by running anvi-show-collections-and-bins.
You can also use the flag --quick-summary to get a less comprehensive summary with a much shorter processing time. For profile-db summaries it skips several heavier computations; for pan-db summaries it omits sequences and annotation text from the gene clusters file; for pan-graph-db summaries it omits sequences from GENESxSYNGCs.txt.
For cases where you want the aggregate bin statistics and per-sample coverage matrices from your profile-db but not per-bin sequence files, you can use the flag --light-summary instead.
Just for your reference, in the context of profile-db summaries, and for a dataset of ~2,000 MAGs described in a 42Gb profile-db and a 9.5G contigs-db files, anvi-summarize took over 240 minutes to run during a test in 2026. With --light-summary, the program took about 40 minutes, and with --quick-summary, it took about 10 minutes to run on the same dataset.
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-summarize.
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
-p, --pan-or-profile-dbPAN_OR_PROFILE_DBrequired- An anvi'o pan-db or profile-db (and even genes-db or pan-graph-db in appropriate contexts).
-c, --contigs-dbCONTIGS_DB- Anvi'o contigs database generated by 'anvi-gen-contigs-database'
-g, --genomes-storageGENOMES_STORAGE- Anvi'o genomes storage file
--init-gene-coverages- Initialize gene coverage and detection data. This is a very computationally expensive step, but it is necessary when you need gene level coverage data. The reason this is very computationally expensive is because anvi'o computes gene coverages by going back to actual coverage values of each gene to average them, instead of using contig average coverage values, for extreme accuracy.
--calculate-Q2Q3-carefully- By default, anvi'o summarizes collections by cutting corners. One of those corners is to take values for mean coverage Q2Q3 for each contig, and normalize that value by the size of the contig, and average those values to have a single value for the bin. While this strategy works quite well for regular mean coverage, the calculation of mean coverage Q2Q3 requires the ENTIRETY of the raw coverage values for each contig to be first concatenated so they can be sorted to calculate the most accurate Q2Q3 value for a given bin. This flag ensures anvi'o calculates mean coverage Q2Q3 values in that careful way at the expense of things taking much longer (but it really is worth it for your final summary of everything). Please see https://github.com/merenlab/anvio/pull/2366 for details.
--reformat-contig-names- Reformat contig names while generating the summary output so they look fancy. With this flag, anvi'o will replace the original names of contigs to those that include the bin name as a prefix in resulting summary output files per bin. Use this flag carefully as it may influence your downstream analyses due to the fact that your original contig names in your input FASTA file for the contigs database will not be in the summary output. Although, anvi'o will report a conversion map per bin so you can recover the original contig name if you have to.
--light-summary- Generate a lighter summary that skips per-bin FASTA files, gene-call tables, and per-gene coverage statistics, but still produces bins_summary.txt, bins_across_samples/ tables, and bins_per_recruitment.txt. Use this when you need aggregate bin statistics without the overhead of per-bin sequence or gene-level detail.
--report-aa-seqs-for-gene-calls- You can use this flag if you would like amino acid AND dna sequences for your gene calls in the genes output file. By default, only dna sequences are reported.
--report-DNA-sequences- By default, this program reports amino acid sequences. Use this flag to report DNA sequences instead. Also note, since gene clusters are aligned via amino acid sequences, using this flag removes alignment information manifesting in the form of gap characters (`-` characters) that would be present if amino acid sequences were reported. Read the warnings during runtime for more detailed information.
-C, --collection-nameCOLLECTION_NAME- Collection name.
-o, --output-dirDIR_PATH- Directory path for output files
--list-collections- Show available collections and exit.
--cog-data-dirCOG_DATA_DIR- The directory path for your COG setup. Anvi'o will try to use the default path if you do not specify anything.
--quick-summary- When declared the summary output will be generated as quickly as possible, with minimum amount of essential information about bins.
--just-do-it- Don't bother me with questions or warnings, just do it.
--report-discov- Compute the Distribution of Coverage (DisCov) metric for each bin and each contig within each bin. DisCov combines a spread score S (proportion of windows with at least some coverage) and an evenness score E (proportion of covered bases within a fold-range of the median nonzero coverage). Requires access to the auxiliary data file (AUXILIARY-DATA.db). Results are written to 'bins_across_samples/discov_bins.txt' (one row per bin x sample) and 'bins_across_samples/discov_contigs.txt' (one row per contig x sample).
--window-lengthINTEGER- How long to make the windows for computing the spread metric: S = # windows with coverage / # windows. Using this flag sets a fixed window length (in bp) for computing S at both bin and contig level. Important note: when neither this flag nor --window-length-as-percentage is provided, anvi'o uses context-sensitive defaults: `--window-length 1000` for bins and `--window-length-as-percentage 1 --min-window-length 300` for individual contigs (which can be smaller than the default fixed length).
--window-length-as-percentageINTEGER- With this option you can set the window length for the spread metric (S) dynamically as a percentage of a given input sequence length. This works well when your input sequences (contigs or genomes) have a wide size distribution and you don't have a one-size-fits-all window length to use. For instance, if you want the window size to be 5% of the contig length, you would use `--window-length-as-percentage 5`. You may want to consider also specifying a reasonable minimum window length with the --min-window-length parameter.
--min-window-lengthINTEGER- Use with --window-length-as-percentage to ensure that percentage-based window lengths never fall below this value.
--foldrange-lowerFLOAT- When computing evenness of coverage depth (E), count any bases with coverage OVER this value * the median nonzero coverage. In typical use-cases, this value will be the inverse of --foldrange-upper. The default is '0.5'. Default:
0.5 --foldrange-upperFLOAT- When computing evenness of coverage depth (E), count any bases with coverage UNDER this value * the median nonzero coverage. In typical use-cases, this value will be the inverse of --foldrange-lower. The default is '2.0'. Default:
2.0 --alphaFLOAT- How much to weight S over E in the DisCov score. Should be a value in the range [0,1]. The default is '0.5'. Default:
0.5 --discov-formulaSTRING- Which formula to use when combining S and E into the DisCov score. Options are 'linear' (DisCov = αS + (1-α)E) and 'geometric' (DisCov = S^α * E^(1-α)). The default is 'linear'. Default:
linear
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.