anvi-get-codon-frequencies

Get codon or amino acid frequency statistics from genomes, genes, and functions.

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

Authors

Samuel Miller

A. Murat Eren (Meren)

Requires

contigs-db

Can use

profile-db collection bin internal-genomes external-genomes

Provides

codon-frequencies-txt aa-frequencies-txt

Usage

This program calculates codon or amino acid frequencies from genes or functions.

A range of options allows calculation of different frequency statistics. This program is “maximalist,” in that it has many options that do the equivalent of a couple extra commands in R or pandas – because we (not you) tend to be lazy and prone to mistakes.

Basic commands

Gene frequencies

This command produces a table of codon frequencies from coding sequences in the contigs database. The first column of the table contains gene caller IDs and subsequent columns contain frequency data. The decoded amino acid is included in each codon column name with the flag, --header-amino-acids.

anvi-get-codon-frequencies -c contigs-db \ -o path/to/output.txt \ --header-amino-acids

Function frequencies

This command produces a table of function frequencies rather than gene frequencies. By using --function-sources without any arguments, the output will include every functions source available in a given contigs-db, e.g., KOfam, KEGG_BRITE, Pfam (you can always see the complete list of functions in your contigs-db by running the program anvi-db-info on it). The first four columns of the table before frequency data contain, respectively, gene caller IDs, function sources, accessions, and names.

anvi-get-codon-frequencies -c contigs-db \ --function-sources \ --function-table-output path/to/function_output.txt

Gene frequencies with function information

In contrast to the previous example, this command produces a table of gene frequencies, but has an entry for every gene/function pair, allowing statistical interrogation of the gene components of functions. The function table output is derived from this table by grouping rows by function source, retaining only one row per gene caller ID, and summing frequencies across rows of the groups.

anvi-get-codon-frequencies -c contigs-db \ --function-sources \ --gene-table-output path/to/gene_output.txt

Codon frequencies from multiple internal and external genomes

This command produces a table of codon frequencies from coding sequences in multiple genomes. A column is added at the beginning of the table for genome name.

anvi-get-codon-frequencies -i internal-genomes \ -e external-genomes \ -o path/to/output.txt

Option examples

The following tables show the options to get the requested results.

Different frequency statistics

Get	Options
Codon absolute frequencies
Codon relative frequencies	`--relative`
Synonymous (per-amino acid) codon relative frequencies	`--synonymous`
Amino acid frequencies	`--amino-acid`
Amino acid relative frequencies	`--amino-acid --relative`
Summed frequencies across genes	`--sum`
Synonymous relative summed frequencies across genes	`--sum --synonymous`
Summed frequencies across genes annotated by each function source	`--sum --function-sources`
Relative summed frequencies across genes with KOfam annotations	`--sum --relative --function-sources KOfam`
Average frequencies across all genes	`--average`

Frequencies from sets of genes with shared functions

Get	Options
All function annotation sources	`--function-sources`
All KEGG BRITE categories	`--function-sources KEGG_BRITE`
All KEGG KOfams and all Pfams	`--function-sources KOfam Pfam`
Certain KEGG BRITE categories	`--function-sources KEGG_BRITE --function-names Ribosome Ribosome>>>Ribosomal proteins`
Certain KEGG KOfam accessions	`--function-sources KOfam --function-accessions K00001 K00002`
Certain BRITE categories and KOfam accessions	`--select-functions-txt path/to/select_functions.txt`

Frequencies from selections of genes

Get	Options
From contigs database	`--contigs-db path/to/contigs.db`
From collection of internal genomes	`--contigs-db path/to/contigs.db --profile-db path/to/profile.db --collection-name my_bins`
From internal genome	`--contigs-db path/to/contigs.db --profile-db path/to/profile.db --collection-name my_bins --bin-id my_bin`
From internal genomes listed in a file	`--internal-genomes path/to/genomes.txt`
From external genomes (contigs databases) listed in a file	`--external-genomes path/to/genomes.txt`
With certain gene IDs	`--gene-caller-ids 0 2 500`
With certain gene IDs or genes annotated with certain KOfams	`--gene-caller-ids 0 2 500 --function-sources KOfam --function-accessions K00001`

Filtering genes and codons that are analyzed and reported

Get	Options
Exclude genes shorter than 300 codons	`--gene-min-codons 300`
Exclude genes shorter than 300 codons from contributing to function codon frequencies	`--gene-min-codons 300 --function-sources`
Exclude functions with <300 codons	`--function-min-codons 300`
Exclude stop codons and single-codon amino acids	`--exclude-amino-acids STP Met Trp`
Only include certain codons	`--include-amino-acids Leu Ile`
Exclude codons for amino acids with <5 codons in >90% of genes	`--pansequence-min-amino-acids 5 0.9`
Replace codons for amino acids with <5 codons in the gene or function with NaN	`--sequence-min-amino-acids 5`

Option details

Synonymous codon relative frequencies

This flag returns the relative frequency of each codon among the codons encoding the same amino acid, e.g., 0.4 GCC and 0.6 GCT for Ala. By default, stop codons and single-codon amino acids (Met ATG and Trp TGG) in the standard translation table are excluded, equivalent to using --exclude-amino-acids STP Met Trp for other frequency statistics.

Frequencies across genes

--sum and --average produce a table with a single row of frequencies from across genes. For example, the following command sums the codon frequencies of each decoded amino acid (and STP) across all genes, and then calculates the relative frequencies of the amino acids.

anvi-get-codon-frequencies -c contigs-db \ -o path/to/output_table.txt \ --sum \ --amino-acid \ --relative

The first column of the output table has the header, ‘gene_caller_ids’, and the value, ‘all’, indicating that the data is aggregated across genes.

--sum and --average operate on genes. When used with a function option, the program subsets the genes annotated by the functions of interest. With --average, it calculates the average frequency across genes rather than functions (sums of genes with functional annotation). For example, the following command calculates the average synonymous relative frequency across genes annotated by KOfam.

anvi-get-codon-frequencies -c contigs-db \ -o path/to/output_table.txt \ --average \ --synonymous \ --function-sources KOfam

Functions

Functions and function annotation sources can be provided to subset genes (as seen in the last section with --average) and to calculate statistics for functions in addition to genes (as seen in a previous example.

Using --output-file is equivalent to --gene-table-output rather than --function-table-output, producing rows containing frequencies for annotated genes rather than summed frequencies for functions.

Inputs

There are multiple options to define which functions and sources should be used. --function-sources without arguments uses all available sources that had been used to annotate genes.

--function-accessions and --function-names select functions from a single provided source. The following example uses both options to select COG functions.

anvi-get-codon-frequencies -c contigs-db \ -o path/to/output_table.txt \ --function-sources COG14_FUNCTION \ --function-accessions COG0004 COG0005 \ --function-names “Ammonia channel protein AmtB” “Purine nucleoside phosphorylase”

To use different functions from different sources, a tab-delimited file can be provided to functions-txt. This headerless file must have three columns, for source, accession, and name of functions, respectively, with an entry in each row for source.

By default, selected function accessions or names do not need to be present in the input genomes; the program will return data for any selected function accessions or names that annotated genes. This behavior can be changed using the flag, --expect-functions, so that the program will throw an error when any of the selected accessions or names are absent.

BRITE hierarchies

Genes are classified in KEGG BRITE functional hierarchies by anvi-run-kegg-kofams. For example, a bacterial SSU ribosomal protein is classified in a hierarchy of ribosomal genes, Ribosome>>>Ribosomal proteins>>>Bacteria>>>Small subunit. Codon frequencies can be calculated for genes classified at each level of the hierarchy, from the most general, those genes in the Ribosome, to the most specific – in the example, those genes in Ribosome>>>Ribosomal proteins>>>Bacteria>>>Small subunit. Therefore, the following command returns summed codon frequencies for each annotated hierarchy level – in the example, the output would include four rows for the genes in each level from Ribosome to Small subunit.

anvi-get-codon-frequencies -c contigs-db \ -o path/to/output_table.txt \ --function-sources KEGG_BRITE

Filter genes and codons

Codons

It may be useful to restrict codons in the analysis to those encoding certain amino acids. Stop codons and the single codons encoding Met and Trp are excluded by default from calculation of synonymous codon relative frequencies (--synonymous). Relative frequencies across codons in a gene (--relative) are calculated for the selected amino acids, so the following option would return a table of codon frequencies relative to the codons encoding the selected nonpolar amino acids: --include-amino-acids Gly Ala Val Leu Met Ile.

Dynamic exclusion of amino acids can be useful in the calculation of synonymous codon frequencies. For example, 0.5 AAT and 0.5 AAC for Asn may be statistically insignificant for a gene with 1 AAT and 1 AAC; even more meaningless would be 1.0 AAT and 0.0 AAC for a gene with 1 AAT and 0 AAC. --pansequence-min-amino-acids removes rarer amino acids across the dataset, setting a minimum number of codons in a minimum number of genes to retain the amino acid. For example, amino acids with <5 codons in >90% of genes will be excluded from the analysis with --pansequence-min-amino-acids 5 0.9.

Codons for rarer amino acids within each gene or function row can be excluded in the results table (replaced by NaN) with --sequence-min-amino-acids. This parameter only affects how the results are displayed. For example, amino acids with <5 codons in each row will be discarded in the results table with --sequence-min-amino-acids 5.

Gene length and codon count

Removal of genes with few codons can improve the statistical utility of relative frequencies. --gene-min-codons sets the minimum number of codons required in a gene, and this filter can be applied before and/or after the removal of rarer codons. Applied before, --gene-min-codons filters genes by length; applied after, it filters genes by codons remaining after removing rarer codons. --min-codon-filter can take three possible arguments: length, remaining, or, by default when codons are removed, both, which applies the --gene-min-codons filter both before and after codon removal.

It may seem redundant for remaining and both to both be possibilities, but this is due to the possibility of dynamic amino acid exclusion using --pansequence-min-amino-acids. Amino acids are removed based on their frequency in a proportion of genes, so removing shorter genes by length before removing amino acids can affect which amino acids are dynamically excluded.

Function codon count

--function-min-codons can be used to filter functions with a minimum number of codons. Function codon count filters occur after gene codon count filters: the set of genes contributing to function codon frequency can be restricted by applying --gene-min-codons.

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-get-codon-frequencies.

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-get-codon-frequencies [-h] [-c CONTIGS_DB] [-p PROFILE_DB] [-C COLLECTION_NAME] [-b BIN_NAME] [--gene-caller-ids GENE_CALLER_IDS [GENE_CALLER_IDS ...]] [-i FILE_PATH] [-e FILE_PATH] [-o FILE_PATH] [--gene-table-output GENE_TABLE_OUTPUT] [--function-table-output FUNCTION_TABLE_OUTPUT] [--header-amino-acids] [--infinity-to-zero] [--relative] [--synonymous] [--return-amino-acids] [--encodings-txt ENCODINGS_TXT] [--sum] [--average] [--function-sources [FUNCTION_SOURCES ...]] [--function-accessions FUNCTION_ACCESSIONS [FUNCTION_ACCESSIONS ...]] [--function-names FUNCTION_NAMES [FUNCTION_NAMES ...]] [--select-functions-txt SELECT_FUNCTIONS_TXT] [--expect-functions] [--shared-function-sources] [--gene-min-codons INTEGER] [--function-min-codons INTEGER] [--exclude-amino-acids AMINO ACID [AMINO ACID ...]] [--include-amino-acids AMINO ACID [AMINO ACID ...]] [--sequence-min-amino-acids INTEGER] [--pansequence-min-amino-acids PANSEQUENCE_MIN_AMINO_ACIDS PANSEQUENCE_MIN_AMINO_ACIDS] [--min-codon-filter {length,remaining,both}] [--ignore-start-codons] [--skip-checking-genome-hashes]

Parameters and their descriptions

SINGLE GENOME INPUTS Get CUB from genes or functions in a single genome. A contigs database can be provided alone as an 'external' genome. An 'internal' genome (bin) also requires a profile database, collection name, and bin ID.

-c, --contigs-db CONTIGS_DB: Anvi'o contigs database generated by 'anvi-gen-contigs-database'
-p, --profile-db PROFILE_DB: Anvi'o profile database
-C, --collection-name COLLECTION_NAME: Collection name.
-b, --bin-id BIN_NAME: Bin name you are interested in.
--gene-caller-ids GENE_CALLER_IDS: Select genes by ID, space-separated.

MULTIPLE GENOME INPUTS Get frequencies from genes or functions in multiple genomes by providing internal and/or external genome files listing the genomes to analyze.

-i, --internal-genomes FILE_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-genomes FILE_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.

OUTPUT FILES This program writes codon or amino acid frequency tables. When functions rather than genes are analyzed, one of two possible files can be produced: a table of frequencies per gene or per function, using `--gene-table-output` or `--function-table-output`, respectively. The per-function table can be derived from the per-gene table by summing genes with the same function annotation, which are found in columns 2-4.

-o, --output-file FILE_PATH: File path to store results.
--gene-table-output GENE_TABLE_OUTPUT: A tab-delimited file of genes x codons or amino acids. The index columns before frequency data contain genome names (optional, if multiple genomes are considered) and gene callers IDs.
--function-table-output FUNCTION_TABLE_OUTPUT: A tab-delimited file of functions x codons or amino acids. Index columns before the frequency data contain, respectively, genome names (optional, if multiple genomes are considered), function annotation sources, accessions, and names.
--header-amino-acids: Include the amino acid for each codon in the column header of codon output, i.e., LysAAA instead of AAA.
--infinity-to-zero: Replace NA (empty) values in output with 0.0. NA occurs with `--synonymous` when all codons for an amino acid are absent in a gene or function, resulting in 0/0, reported as NA. Use with caution, for NA and 0.0 mean different things and this will skew downstream analyses of synonymous relative frequencies, such as codon usage bias.

FREQUENCY STATISTICS Rather than absolute frequencies (default), relative frequencies or synonymous (per-amino acid) relative frequencies can be returned. Absolute and relative frequencies can be calculated for the sets of codons encoding the same amino acid rather than for individual codons. Frequencies can be summed or averaged across genes in a genome.

--relative: Return relative frequencies across codons or amino acids in each gene or function.
--synonymous: Return synonymous (per-amino acid) frequencies among the codons encoding each amino acid in each gene or function.
--return-amino-acids: Return frequencies of the sets of codons encoding the same amino acid.
--encodings-txt ENCODINGS_TXT: Changes to the standard genetic code can be provided in this tab-delimited file of two columns. Each entry in the first column is a codon and each entry in the second column is the three-letter code for the decoded amino acid. For example, to recode the stop codon, TGA, as Trp, 'TGA' would be placed in the first column and 'Trp' in the same row of the second. Stop/termination codons are abbreviated 'STP'. This option affects per-amino acid and synonymous codon output (when using `--return-amino-acids` or `--synonymous`).
--sum: Sum frequencies across genes, returning a single row for each genome. When functions or function sources are selected, genes are subsetted to those annotated with the requested functions or annotated by the requested sources.
--average: Average frequencies across genes in the genome, returning a single row for each genome. When functions or function sources are selected, genes are subsetted to those annotated with the requested functions or annotated by the requested sources.

FUNCTIONS Frequencies can be calculated for functions rather than genes, summing the frequencies of the genes annotated by each function. Genes can also be subsetted to those annotated with requested functions or annotated by requested function sources.

--function-sources FUNCTION_SOURCES: Return frequencies for functions annotated by these sources, e.g., 'KOfam', 'KEGG_BRITE', 'COG20_FUNCTION'. When used with certain other options, such as `--sum`, rather than returning statistics for each function, analyzed genes are subsetted to those annotated by the provided sources. If `--function-sources` is used as a flag without any arguments, then every source will be considered.
--function-accessions FUNCTION_ACCESSIONS: Return frequencies for functions with these accessions from the source provided in `--function-sources`. To get accessions from multiple sources, instead use `--select-functions-txt`.
--function-names FUNCTION_NAMES: Return frequencies for functions with these names from the source provided in `--function-sources`. To get function names from multiple sources, instead use `--select-functions-txt`.
--select-functions-txt SELECT_FUNCTIONS_TXT: Selected functions can be listed in this tab-delimited file of three columns. The first column should contain function annotation sources, the second column accessions, and the third function names. An entry in the source column is required in every row, and either an accession or name, or both, should also be in a row. The file should not have a header of column names.
--expect-functions: By default, functions provided by `--function-accessions`, `--function-names`, and `--select-functions-txt` need not be annotated in the input genomes. With this flag, an error will be raised if any of the functions are not present in an input genome.
--shared-function-sources: Use this flag to exclude function annotation sources that were not run on every input genome.

FILTER GENES, FUNCTIONS, CODONS Genes/functions can be filtered by the number of codons they contain, e.g., ignore genes shorter than 300 codons. Codons can be selected a priori, e.g., ignore Ala codons, or rarer codons can be excluded, e.g., ignore amino acids that are decoded by ≤3 codons in ≥90%% of genes. Filters can improve the statistical utility of codon relative frequency data.

--gene-min-codons INTEGER: Set the minimum number of codons required in a gene. When functions are returned rather than genes, this filter is applied to genes before grouping them as functions. Default: 0
--function-min-codons INTEGER: Set the minimum number of codons required in a function. Genes with fewer than `--gene-min-codons` are first removed, and then functional groups of the remaining genes with fewer than `--function-min-codons` are removed. This filter only applies when returning functions. Default: 0
--exclude-amino-acids AMINO ACID: Remove codons that decode the given amino acids (use three-letter codes, e.g., Ala, and STP for stop codons). If `--synonymous`, this argument defaults to 'STP Met Trp', and if other amino acids are excluded, for STP, Met, and Trp codons to still be excluded from the output table, they must also be explicitly provided in the argument.
--include-amino-acids AMINO ACID: This is the complement of `--exclude-amino-acids`. Only codons for the given amino acids are analyzed and reported.
--sequence-min-amino-acids INTEGER: Do not report codons for amino acids (and STP) that are less numerous than the given argument. For example, if the argument is 5, and a gene or function query has 4 codons encoding Asn, 2 AAT and 2 AAC, then a row for this gene in the output table will have missing values in Asn columns. This filter occurs at the end of the analysis before writing results and so does not affect prior calculations. Default: 0
--pansequence-min-amino-acids PANSEQUENCE_MIN_AMINO_ACIDS: The first value of the argument is a positive integer representing a minimum number of codons encoding an amino acid -- 'min_amino_acids' -- and the second is a number between 0 and 1 representing a fraction of genes -- 'min_gene_fraction'. Remove codons for amino acids (and STP) that are less numerous than 'min_amino_acids' in a 'min_gene_fraction' of genes. For example, if 'min_amino_acids' is 5 and 'min_gene_fraction' is 0.9, then if there are fewer than 5 codons for an amino acid/STP in ≥90% of genes, then the columns for these codons are dropped. Default: [0, 1.0]
--min-codon-filter MIN_CODON_FILTER: This argument arises from the ambiguity of filters that remove genes and functions by number of codons (`--gene-min-codons` and `--function-min-codons`) in relation to filters that drop codons (`--exclude/include-amino-acids` and `--pansequence-min-amino-acids`). Genes (and functions) can be filtered by their full length, e.g., genes shorter than 300 codons are ignored. They can also be filtered by the number of codons remaining after dropping codons. The codon length filter followed by dropping codons can result in genes and functions with fewer codons than the original codon threshold -- thus the option of both 'length' and 'remaining' filters to ensure that total codon frequencies in the output always meet the minimum codon threshold. 'both' is needed as an option in addition to 'remaining' so dynamic codon filtering by `--pansequence-min-amino-acids` operates on genes that passed the first length filter. Choices: length remaining both Default: both
--ignore-start-codons: Ignore start codons in the analysis. Besides ATG, GTG and TTG are notable minority start codons in bacteria and archaea. With start codons removed, frequencies only represent elongation codons. This makes codon usage bias calculations more accurate, because initiation GTG and TTG, like ATG, encode fMet in bacteria and Met in archaea and eukaryotes, but anvi'o treats them like elongation codons encoding Val and Leu, respectively, in the standard genetic code. ATG does not contribute to codon usage bias given the standard genetic code, because it lacks synonymous codons, being the only Met codon. Note that `--ignore-start-codons` removes start codons from genes in the earliest steps of the analysis, which influences `--gene-min-codons`: the number of codons in a gene never counts the start codon.
--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).

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.