anvi-script-gen-antismash-matrix

With this script you can generate a matrix across many contig-dbs or bins in a collection to compare their biosynthetic capacity. You can choose between a per-gene matrix that resolves the smCOG annotations and domains within each gene and their role within the BGC and a cluster resolved matrix that summarizes the individual genes into BGC and their product. To generate these matrices your contig-dbs already need to be annotated with antiSMASH. Use the –genes flag to get the 'per-gene' output or the –regions flag to get the 'BGC-resolved' output..

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

Authors

Requires

functions external-genomes

Can use

internal-genomes

Provides

functions-across-genomes-txt

Usage

This program builds matrices that compare antiSMASH results across many genomes or metagenomes, reading the antiSMASH annotations straight from contigs databases that have already been processed with anvi-run-antismash.

It works like anvi-estimate-metabolism --matrix-format: point it at your genomes through an external-genomes file (-e), an internal-genomes file (-i), or both, and it reads the antiSMASH function sources (antiSMASH, antiSMASH_ROLE, antiSMASH_DOMAIN, antiSMASH_REGION) from each database and pivots them into matrices. An external genome is a whole contigs-db; an internal genome is a bin, so only that bin’s genes are counted, and two bins from the same assembly get their own separate profiles. Because a matrix is a comparison across genomes, there is no single contigs database (-c) mode. There is nothing to run per-genome first beyond the annotation itself, which you can do for a whole set in one command with anvi-run-antismash -e <span class="artifact-n">[external-genomes](/help/main/artifacts/external-genomes)</span>.

You choose one of two matrix types:

Per-cluster matrix (--regions)

Rows are BGC product types (terpene, NRPS, hserlactone, …), columns are your genomes, and each cell is the number of regions (clusters) of that type in that genome, a compact profile of biosynthetic potential across your dataset.

Per-gene matrix (--genes)

Rows are distinct gene signatures, described by five columns (product, role, function, smcog, and domains) that stay constant down each row; columns are your genomes, and each cell is how many genes match that signature. The leading product column names the BGC type the gene belongs to, so it lines up directly with the rows of the --regions matrix (a gene signature that occurs in more than one cluster type honestly appears as more than one row). Genes that sit inside a cluster but carry no functional annotation of their own are not shown here; they are in the per-gene file described below.

Output

Either mode writes two files of type functions-across-genomes-txt: a -FREQUENCY.txt matrix (counts) and a -PRESENCE-ABSENCE.txt matrix (0/1). In both, the descriptor columns come first, followed by one column per genome.

If any of the databases you provide were never annotated with anvi-run-antismash, the program still runs, but fills that genome’s column with NA (rather than 0) and warns you about it. The distinction matters: NA means “not annotated, unknown”, whereas 0 would wrongly imply “annotated, but no cluster of that kind”. Annotate all your databases first for a clean, all-numeric comparison.

Relating the matrices back to individual genes (--genes)

A matrix is a cross-genome summary: each cell is a count, so it cannot carry the identifiers that only make sense inside one database: the gene caller id and the region id. To bridge that gap, --genes additionally writes a comprehensive per-gene file, <prefix>-GENE-DETAILS.txt, with one row per antiSMASH-annotated gene across all your genomes and these columns:

genome, gene_callers_id, contig, region_id, product, role, function, smcog, domains

This one file is the join key for everything downstream:

• genome + gene_callers_id points back to that genome’s contigs-db, so you can relate an antiSMASH gene to its other annotations (KOfam, COGs, …), since every source shares the same gene caller id (see anvi-export-functions).
• region_id groups genes into their clusters, so you can list all the genes that make up a given BGC region (including accessory genes with no function of their own, which the matrix omits).
• product and the signature columns line up with the --genes and --regions matrices, so you can go from any matrix cell down to the individual genes behind it.

Edit this file to update this information.

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.