Metric definitions and implementation notes

Reference-dependent adaptation

For each synonymous codon i, relative adaptiveness is w_i = f_i / max(f_j) within its amino-acid family. CodonAdaptPy computes CAI as exp(mean(log(w_i))). This is numerically stable for long sequences. RCDI compares observed global codon fractions with host fractions and is closest to 1 when usage is similar. tAI uses the same geometric-mean engine with user-supplied tRNA availability weights.

Simulated CAI samples synonymous codons while exactly preserving the query amino-acid composition. Its seed and simulation count are recorded. The returned interval is an empirical 2.5–97.5 percentile interval, not a parametric confidence interval for expression.

Intrinsic usage

RSCU is observed usage divided by equal synonymous expectation. ENC uses corrected within-family homozygosity and is bounded to 20–61. FOP is the fraction of eligible synonymous positions occupied by reference-optimal codons. CBI corrects optimal-codon observations for equal synonymous expectation. ICDI summarizes normalized deviation from equal synonymous usage within amino-acid families.

Composition and pairs

GC is calculated after removing ambiguous symbols; GC1/2/3 and AT1/2/3 use the selected reading frame. GC3s is the GC fraction at third positions of multi-codon amino-acid families; methionine, tryptophan, stops, and ambiguous codons are excluded. The package reports observed/expected ratios for all 16 dinucleotides, calculated as observed pair frequency divided by the product of marginal nucleotide frequencies. A ratio is marked undefined when either marginal frequency is zero. Default classification thresholds are greater than 1.25 for overrepresentation and less than 0.78 for underrepresentation. Codon-pair scores are natural-log observed/expected ratios under independent codon sampling.

For genome-wide CDS aggregation, mono-, dinucleotide-, trinucleotide-, and codon-pair counts are accumulated inside each CDS. Artificial words spanning two adjacent genes are never counted.

Host comparison

Host comparison reports multiple metrics because no single statistic fully characterizes similarity. The exact SiD calculation uses RSCU values for 59 degenerate sense codons, excluding stops, methionine, and tryptophan. It reports cosine similarity R and distance D(A,B) = (1 - R) / 2. The composite score is the bounded mean of CAI, global codon-frequency cosine similarity, rescaled Pearson correlation, and one minus Jensen-Shannon divergence. Raw components should always be inspected.

Evolutionary diagnostics

Expected ENC follows Wright’s GC3 mutation-only curve. Neutrality regression models GC12 against GC3. PR2 coordinates are A3/(A3+T3) and G3/(G3+C3). These descriptive diagnostics do not identify a causal evolutionary mechanism by themselves.