anvi-script-gen-antismash-matrix
Table of Contents
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
Can use
Provides
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.
anvi-script-gen-antismash-matrix -e external-genomes \ --regions \ -O BGC_TYPES
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.
anvi-script-gen-antismash-matrix -e external-genomes \ --genes \ -O BGC_GENES
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_idpoints 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_idgroups 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).productand the signature columns line up with the--genesand--regionsmatrices, so you can go from any matrix cell down to the individual genes behind it.
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-script-gen-antismash-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
-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.
-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.
--genes- Build a per-gene matrix: rows are distinct gene signatures (role, function, smCOG and domains as separate columns), columns are genomes, and each cell is how many genes in that genome match the signature.
--regions- Build a per-cluster matrix: rows are BGC product types (terpene, NRPS, ...), columns are genomes, and each cell is how many regions (clusters) of that type the genome has.
-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.