anvi-pan-genome-graph
Table of Contents
An anvi'o program to compute a graph representation of pangenomes. It will do its magic, and store it into your pan-db, or report a JSON formatted graph file, for downstream visualization and analyses with anvi-display-pan-graph.
🔙 To the main page of anvi’o programs and artifacts.
Authors
Requires
Can use
genomes-storage-db 
external-genomes 
Provides
Usage
No one has described the usage of this program :/ If you would like to contribute, please see previous examples here, and feel free to add a Markdown formatted file in that directory named “anvi-pan-genome-graph.md”. For a template, you can use the markdown file for anvi-gen-contigs-database. THANK YOU!
Command line interface
The following is the list of parameters and their descriptions in the latest version of anvi-pan-genome-graph.
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-pan-genome-graph [-h] -p PAN_DB -g GENOMES_STORAGE -e FILE_PATH [-G GENOME_NAMES] [-d TSV] [--minbit-floor MINBIT_FLOOR] [--minbit-prefilter MINBIT_PREFILTER] [-o FILE_PATH] [--tables-dir DIR] [--min-contig-chain MIN_CONTIG_CHAIN] [--max-contigs-per-component MAX_CONTIGS_PER_COMPONENT] [--no-remerge] [--remerge-max-length REMERGE_MAX_LENGTH] [--no-include-non-coding-genes] [--locality-window LOCALITY_WINDOW] [--min-window-completeness MIN_WINDOW_COMPLETENESS] [--min-line-pair-hits MIN_LINE_PAIR_HITS] [--fusion-min-line-pair-hits FUSION_MIN_LINE_PAIR_HITS] [--orientation-tie-threshold ORIENTATION_TIE_THRESHOLD] [--min-orientation-score MIN_ORIENTATION_SCORE] [--orientation-demotion-strategy {slimmest-margin,fewest-edges}] [--ranking-components RANKING_COMPONENTS] [--ranking-mean {geometric,arithmetic}] [--decision-floor DECISION_FLOOR] [--support-floor SUPPORT_FLOOR] [--uniqueness-floor UNIQUENESS_FLOOR] [--decision-tie-score DECISION_TIE_SCORE] [--decision-boundary-score DECISION_BOUNDARY_SCORE] [--min-ranking-score MIN_RANKING_SCORE] [--fusion-top-bucket-k FUSION_TOP_BUCKET_K] [--fusion-seed FUSION_SEED] [--region-scope {global,component}] [--component COMPONENT] [--gene-cluster-grouping-threshold GENE_CLUSTER_GROUPING_THRESHOLD] [--grouping-compression GROUPING_COMPRESSION] [--max-edge-length-filter MAX_EDGE_LENGTH_FILTER] [--description TEXT_FILE] [-n PROJECT_NAME] [--load-state LOAD_STATE] [--import-values IMPORT_VALUES] [--just-do-it]
Parameters and their descriptions
-p, --pan-dbPAN_DBrequired- Anvi'o pan database
-g, --genomes-storageGENOMES_STORAGErequired- Anvi'o genomes storage file
-e, --external-genomesFILE_PATHrequired- 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, --genome-namesGENOME_NAMES- Genome names to 'focus'. You can use this parameter to limit the genomes included in your analysis. You can provide these names as a comma-separated list of names, or you can put them in a file, where you have a single genome name in each line, and provide the file path.
-d, --diamond-search-resultsTSV- A DIAMOND tabular (outfmt 6) search-results file used to SCORE and WEIGHT the gene-cluster-derived edges.Can be generated by running anvi-pan-genome with the --intermediate-data-dir option. Candidate edges are always defined by the pan-db gene clusters; if this file is provided, each cross-genome pair inside a gene cluster is weighted by its reciprocal-averaged minbit and edges without a DIAMOND score are dropped (reproducing the classic behavior exactly). If omitted, the tool runs on gene-cluster membership alone: every cross-genome pair within a gene cluster becomes an unweighted edge and the `minbit` ranking component is dropped.
--minbit-floorMINBIT_FLOOR- Edges with minbit below this value are dropped before ranking. Applied to the reciprocal-averaged minbit of each undirected cross-genome pair, this applies afterDIAMOND parsing has built the directed-pair dictionary. Use this for ranking quality control. This filter is analogousto support-, decision- and uniqueness-floor filters running in the engine. If you are concerned about your enormous listof DIAMOND hits, consider using the --minbit-prefilter parameter to reduce the dataset size before ranking. Default:
0.0 --minbit-prefilterMINBIT_PREFILTER- Row-level minbit prefilter. Rows whose directed minbit (bit_score / min(self_bit_u, self_bit_v)) is below this value are dropped before they enter the directed-pair dictionary. The dictionary holds all surviving cross-genome directed pairs and can be tens of GB for large pangenomes (e.g., 50+ genomes), which is the most common cause of OOM kills during the engine's parsing phase. Distinct from --minbit-floor, which gates after reciprocal-average and is for ranking quality. 0 disables the prefilter (default). Must be in [0.0, 1.0]. If you don't know which parameter is the correct one and you don't have OOM problemsuse --minbit-floor. Default:
0.0
-o, --output-fileFILE_PATH- Output file path for the pan-graph-db this program will generate.
--tables-dirDIR- Optional directory to dump intermediate tables (lines.txt, edges.tsv, genome_map.tsv, orientation.tsv, ranking.tsv) produced by the pan-graph engine. These artifacts are not required by anvi'o downstream consumers; they are for inspection only. If unset, no tables are written.
--min-contig-chainMIN_CONTIG_CHAIN- Skip contigs with fewer than this many genes (filters very short/fragmented contigs). Default:
5 --max-contigs-per-componentMAX_CONTIGS_PER_COMPONENT- Cap on how many contigs (lines) from a SINGLE genome are allowed to share one weakly-connected COMPONENT of the graph. During fusion, a fuse that would union two components in a way that puts more than this many contigs from any one genome into a single component is rejected (reason: `max-contigs-per-component`); the excess contig is not dropped -- it stays free to join a different component that lacks its genome, or ends up as its own component. -1 (default) disables the cap and preserves the classic behavior where a genome may thread arbitrarily many of its contigs through one component. Set it to 1 for CLOSED/complete genomes, where each genome should contribute at most one contig per replicon and a second one signals a spurious cross-replicon fusion. WARNING: a low cap will fragment DRAFT genomes, since a fragmented chromosome legitimately spreads many contigs across the same component; each excess contig then becomes a separate component. Must be -1 or a positive integer. Default:
1 --no-remerge- Skip the post-engine remerge pass. By default (no flag), anvi'o walks every parent gene cluster that produced multiple synteny clusters and merges pairs that look like engine over-splits: same weakly connected component, not in-series in the DAG, and disjoint genome coverage. Pass this flag to disable that pass and keep the engine's original splits intact.
--remerge-max-lengthREMERGE_MAX_LENGTH- Asymmetry cap (in DAG edges) for remerge candidates. For each candidate pair, the remerge pass measures shortest-path distances from BOTH the lowest common ancestor (LCA) and the lowest common descendant (LCD), where they exist, to each of the two nodes. If either |dist_a - dist_b| exceeds this value the merge is rejected. This blocks topologically lopsided merges where one candidate sits much deeper/shallower than the other relative to the shared ancestor or descendant. -1 disables the check.When only one of LCA or LCD exists, only that side's check applies; pairs with neither (extremely rare on a connected DAG) are not rejected by this guard. Default:
10 --no-include-non-coding-genes- Drop non-coding gene calls (rRNA, tRNA, etc.) from the graph. By default (no flag), non-coding gene calls are kept as singleton super-nodes typed `rna`. Non-coding genes are detected via each genome's CONTIGS.db `call_type` column (anything that is not CODING). They have no DIAMOND hits (DIAMOND runs on translated proteins) and therefore never merge across genomes -- each non-coding gene becomes its own node. Pass this flag to drop them before component-id and layout computation; flanking gene-order edges are re-stitched so line continuity is preserved.
--locality-windowLOCALITY_WINDOW- Flanking window size (in genes) on each side of a candidate line pair, used to decide whether two contigs are co-oriented or flipped. Default:
10 --min-window-completenessMIN_WINDOW_COMPLETENESS- Minimum number of genes that each of the four flanking windows (left/right of each endpoint) must contain for an edge to CONTRIBUTE TO ORIENTATION SCORING. Must be 0..--locality-window (0 disables the filter). SOFT gate -- it does NOT prevent fusion: an edge whose any flanking window is shorter than this is dropped from the orientation/locality scan only, NOT from the fusion pool. Its `decision` ranking component instead falls back to `--decision-boundary-score` (if its line pair still receives a same/flip label) or `--decision-tie-score` (if not), both 0.0 by default. Because the edge survives, the two lines can still fuse when `--decision-floor` is 0.0 and `--ranking-mean` is arithmetic (a zeroed component only lowers the arithmetic mean; under geometric mean it drives the whole score to 0). To hard-drop such edges, raise `--decision-floor` above 0. Default:
0 --min-line-pair-hitsMIN_LINE_PAIR_HITS- Orientation-side gate. Minimum number of edges (DIAMOND hits) between two contig lines required for the pair to receive a same/flip orientation label. SOFT gate -- it does NOT prevent fusion: a pair with fewer hits simply gets NO orientation label, which only makes its edges take `--decision-tie-score` (default 0.0) as their `decision` ranking component. The edges are NOT removed from the fusion pool, so such a pair can still fuse: with `--decision-floor 0.0` the zeroed decision passes the floor, and under `--ranking-mean arithmetic` the combined score can still clear `--min-ranking-score` on the strength of the other components (under geometric mean a zeroed component drives the whole score to 0, excluding the edge unless `--min-ranking-score` is also 0). To HARD-BLOCK under-supported line pairs from fusing use `--fusion-min-line-pair-hits`; to require a non-zero decision score raise `--decision-floor`. Default:
50 --fusion-min-line-pair-hitsFUSION_MIN_LINE_PAIR_HITS- Fusion-side hard cutoff. Line pairs with fewer than this many edges are dropped from the ranking pool entirely and NEVER fused (alongside the existing same-genome-conflict and transitive-cycle guards). Independent of --min-line-pair-hits, which only gates orientation labeling: set this above 0 if you want under-supported line pairs to be excluded from fusion regardless of how the ranking otherwise scores them. A potential usecase is plasmids in the dataset. 0 disables the cutoff. Default:
0 --orientation-tie-thresholdORIENTATION_TIE_THRESHOLD- Score margin under which a line-pair orientation call is treated as a tie and demoted (see --orientation-demotion-strategy). SOFT -- it does NOT prevent fusion: a tied/demoted pair simply loses its same/flip label, so its edges fall back to `--decision-tie-score` (default 0.0) for the `decision` ranking component instead of being removed from the fusion pool. As with `--min-line-pair-hits`, such edges can still fuse when `--decision-floor` is 0.0 and `--ranking-mean` is arithmetic. Default:
0.35 --min-orientation-scoreMIN_ORIENTATION_SCORE- Minimum orientation score for a line pair to receive a same/flip label. SOFT -- it does NOT prevent fusion: pairs below this are dropped from ORIENTATION LABELING only, not from the fusion pool. Their edges fall back to `--decision-tie-score` (default 0.0) for the `decision` ranking component, so with `--decision-floor 0.0` and `--ranking-mean arithmetic` they can still fuse on the strength of the other components. Use `--fusion-min-line-pair-hits`, or raise `--decision-floor`, for a hard cutoff. Default:
0.5 --orientation-demotion-strategyORIENTATION_DEMOTION_STRATEGY- How to break ties when committing line-pair orientations during the spanning-tree walk. Choices:
slimmest-marginfewest-edgesDefault:slimmest-margin --ranking-componentsRANKING_COMPONENTS- Comma-separated list of components used to rank edges before fusion (any subset of minbit, decision, support, uniqueness). 'uniqueness' (opt-in; not in the default) is min(uniqueness(u), uniqueness(v)) where uniqueness(g) = partner_genomes(g) / hit_count(g). The number of distinct genomes among g's cross-genome DIAMOND partners divided by the total partner count (gated by GC in panmode). Any single-copy gene scores 1.0 regardless of how core it is; multi-copy GCs score below 1.0; capped at 1.0 by construction. NOTE: `minbit` requires `--diamond-search-results`; when no DIAMOND file is provided it is silently dropped from this list (edges are unweighted) and the remaining components are used. Default:
minbit,decision,support,uniqueness --ranking-meanRANKING_MEAN- Mean used to combine ranking components into a single score per edge. Choices:
geometricarithmeticDefault:geometric --decision-floorDECISION_FLOOR- Edges whose per-edge decision_score (the locality-window top-n mean selected by the line-pair orientation label) is below this value are dropped before fusion. Applied at ranking time, as soon as the decision score is available; analogous to --minbit-floor for raw minbit. Must be in [0.0, 1.0]; all ranking-component scores are clamped to that range in the engine. Default:
0.0 --support-floorSUPPORT_FLOOR- Edges whose line-pair support (n_edges between the two lines divided by min(len(line_a), len(line_b))) is below this value are dropped before fusion. Applied at ranking time; analogous to --minbit-floor for raw minbit. Must be in [0.0, 1.0]; all ranking-component scores are clamped to that range in the engine, so a line pair with more edges than the shorter line has genes saturates at support=1.0. Default:
0.0 --uniqueness-floorUNIQUENESS_FLOOR- Edges whose per-edge uniqueness (min(uniqueness(u), uniqueness(v)) where uniqueness(g) = partner_genomes(g) / hit_count(g); gated by GC in panmode) is below this value are dropped before fusion. Applied at ranking time; analogous to --minbit-floor for raw minbit. Any single-copy gene edge scores 1.0, so a floor of e.g. 0.5 keeps edges only when both endpoints have at most ~2 partners per genome. Use this to exclude edges anchored on promiscuous genes (transposases, mobile elements, etc.) regardless of how uniqueness is weighted in --ranking-components. Default:
0.0 --decision-tie-scoreDECISION_TIE_SCORE- Decision score assigned to edges whose line pair has NO orientation label -- i.e. pairs that are tied (`--orientation-tie-threshold`), too weak (`--min-orientation-score`), under-supported (`--min-line-pair-hits`), or demoted by the odd-cycle resolver. Pair-level fallback: no fwd-vs-rev preference exists, so this value replaces the missing `decision` component in the ranking. It defaults to 0.0, which zeroes the decision component WITHOUT removing the edge -- so with `--decision-floor 0.0` and `--ranking-mean arithmetic` the pair can still fuse (under geometric mean a 0 here drives the whole score to 0). Set it above 0 to let unlabeled pairs contribute a non-zero decision score. Default:
0.0 --decision-boundary-scoreDECISION_BOUNDARY_SCORE- Decision score assigned to edges in confidently labeled pairs (same/flip) whose specific edge couldn't be scored by the locality scan, typically because one or both endpoint genes sit at contig boundaries (empty flanking window) or because --min-window-completeness dropped the edge from the orientation scan. Per-edge fallback on an otherwise good pair: it defaults to 0.0, which zeroes that edge's `decision` component WITHOUT removing the edge, so with `--decision-floor 0.0` and `--ranking-mean arithmetic` the edge can still fuse on the strength of the other components. Set it above 0.0 to keep such contig-end edges in well-oriented pairs from being zeroed out in the ranking. Default:
0.0 --min-ranking-scoreMIN_RANKING_SCORE- Edges whose combined ranking score (the mean of --ranking-components) is below this value are skipped during fusion. Independent of --minbit-floor, which gates on raw minbit; this gates on the aggregated score. Default:
0.1 --fusion-top-bucket-kFUSION_TOP_BUCKET_K- Number of top-ranked edges sampled per fusion step (Prim-style frontier growth with stochastic top-K bucketing). Default:
1 --fusion-seedFUSION_SEED- Random seed for the stochastic top-K fusion sampler. Default:
42 --region-scopeREGION_SCOPE- Scope of what is considered present in all genomes during region classification (backbone vs. variable) and the normalized region metrics. 'global' (default) counts genomes across the entire pangenome -- a region is BR only if every genome in the pangenome reaches it. 'component' counts only the genomes present in the current weakly-connected component -- a region is BR relative to the genomes that actually appear in its component, which treats each component as an independent sub-pangenome. With 'component' a 1-genome component is trivially classified as backbone; pick 'global' if that's not the intent. Choices:
globalcomponentDefault:component
--componentCOMPONENT- Which weakly connected component to lay out and summarize. Components are named largest-first as 'CP_0001', 'CP_0002', ...; the default ('CP_0001') selects the largest. All components are still persisted in the pan-graph-db. Default:
CP_0001 --gene-cluster-grouping-thresholdGENE_CLUSTER_GROUPING_THRESHOLD- Compress linear chains of nodes of this length or longer into groups (-1 disables grouping; useful to simplify long conserved runs). Default:
-1 --grouping-compressionGROUPING_COMPRESSION- Compression factor for grouped chains (1.0 = no compression; lower values squeeze grouped nodes closer in the layout). Default:
1.0 --max-edge-length-filterMAX_EDGE_LENGTH_FILTER- Remove edges longer than this length threshold after layout (-1 disables filtering; lower values prune long jumps/repeats). Default:
-1
--just-do-it- Bypass safety checks (e.g., over-splitting) and continue even when warnings would normally abort; use to diagnose tough datasets.
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.