codoff: A program to measure the irregularity of the codon usage for a focal genomic region (e.g. a BGC, prophage, etc.) relative to the full genome. It was primarily designed to work off the output of antiSMASH biosynthetic gene cluster (BGC) predictions - but can be more broadly applied as well, with options allowing users to provide a genome in FASTA format and simply specify the coordinates of the focal region of interest. It uses sequential contiguous-window sampling (v1.2.3+) to compare the focal region against randomly positioned genomic windows of the same size, reporting a discordance percentile that indicates how unusual the codon usage is compared to the rest of the genome.

If you have suggestions or feedback, please let us know in the GitHub issues.

Note, (for some setups at least) it is critical to specify the conda-forge channel before the bioconda channel to properly configure priority and lead to a successful installation.

Recommended: For a significantly faster installation process, use mamba in place of conda in the below commands, by installing mamba in your base conda environment.

Uncompress the example inputs (trimmed down to save space). The input includes: (1) BGC predictions and (2) the genome of a Corynebacterium simulans isolate that we previously reported to feature a non-ribosomal peptide synthase that synthesizes a metallophore in the lsaBGC manuscript. Expected results from using v1.2.3 of codoff are also included.

A demo can be run automatically via the bash script:

This should take around half a minute:

You can explore the results and also compare the results you produced in the Csimulans_Data/ folder with the expected results in Csimulans_Data/expected_results_v1.2.3/ folder.

Let's break down what this test is doing, but first remove the directory: rm -r Csimulans_Data/ and then uncompress it again: tar -zxvf Csimulans_Data.tar.gz.

(WORKS FOR BOTH EUKARYOTES & BACTERIA) Focal region and full-genome provided as GenBank files with CDS features (compatible with antiSMASH outputs). Multiple focal region GenBank files can be provided, e.g. consider a biosynthetic gene cluster split across multiple scaffolds due to assembly fragmentation.

(WORKS ONLY FOR BACTERIA) Full genome is provided as a FASTA or GenBank file. If CDS features are missing, gene calling is performed using pyrodigal. Afterwards, the focal region is determined through user speciefied coordinates.

Here, we also requested the -p argument to generate a plot of the simulated distribution of cosine distances for regions of similar size to the focal region and the actual cosine distance for the focal region/cluster (blue vertical line):

codoff uses a Monte Carlo simulation approach to calculate a discordance percentile to assess codon usage differences between the focal region(s) of interest and the background genome. The algorithm works as follows:

• Extract all CDS features from the genome (genes with lengths divisible by 3)
• Skip CDS features with fuzzy/partial boundaries (indicated by < or > in GenBank notation, e.g., <1..500 or 1000..>1500)
• Calculate codon frequency distributions for:
  • Focal region: Codons from genes in the BGC/focal region
  • Background genome: All remaining genes in the genome

• Compute cosine distance between focal and background codon frequency distributions
• Calculate Spearman correlation coefficient between the two distributions

As of v1.2.3, codoff uses sequential contiguous-window sampling, which better preserves the spatial structure of the genome.

For each of N simulations (default: 10,000, configurable with --num-sims):

1. Randomly select a scaffold from those large enough to contain the focal region size
2. Randomly select a starting coordinate on that scaffold
3. Extract all genes fully contained within a contiguous genomic window of the same size as the focal region
4. Calculate codon frequencies for genes in this simulated window
5. Skip windows with no genes or with >=5% of total genome CDS (to match filtering applied to real data)
6. Calculate background frequencies as: total_genome_counts - simulated_focal_counts
7. Compute cosine distance between simulated focal and background frequencies
8. Count how many simulated distances >= observed distance

This approach tests whether the observed focal region's codon usage is significantly different from what would be expected for a randomly positioned contiguous genomic region of the same size.

codoff reports a Discordance Percentile that indicates where the focal region ranks among all similarly sized genomic windows:

For example, a percentile of 5.0 means the focal region is within the top 5% most discordant regions in terms of codon usage compared to the rest of the genome. Lower percentiles indicate more unusual/discordant codon usage, which may be evidence of horizontal gene transfer or unusual regulatory or evolutionary processes.

Results can be reproduced exactly using the --seed/-x parameter (default: 42). Using the same seed value will produce identical results across multiple runs.

Beginning in v1.2.0, codoff can also be used as a function in your Python code. Check out this wiki page for info on how to do this and details on the API.