Basic Usage

As covered in Quickstart, the basic CAI() function is fast and easy. Simply import it and get to your science. Note that it also plays nicely with Biopython Seq objects:

>>> from CAI import CAI
>>> from Bio.Seq import Seq
>>> CAI(Seq("AAT"), reference=[Seq("AAC")])

The CLI is equally easy to use. For example, to find the CAI of the native GFP gene with respect to the highly expressed genes in E. coli, only one command is required:

$ CAI -r example_seqs/ecol.heg.fasta -s example_seqs/gfp.fasta


Both CAI and cai are valid commands.

More example sequences can be found in the example_seqs directory on GitHub.

Advanced Usage

If you have already computed the weights or RSCU values of the reference set, you can supply CAI() with one or the other as arguments. They must be formatted as a dictionary and contain values for every codon.

To calculate RSCU without calculating CAI, you can use RSCU(). RSCU()’s only required argument is a list of sequences.

Similarly, to calculate the weights of reference sequences, you can use relative_adaptiveness(). relative_adaptiveness() takes either a list of sequences as the sequences parameter or a dictionary of RSCUs as the RSCUs parameter.


If you are computing large numbers of CAIs with the same reference sequences, first calculate their weights with relative_adaptiveness() and then pass that to CAI() to eliminate redundant computation.

So, to modify the example in Quickstart:

>>> from CAI import CAI, relative_adaptiveness
>>> sequences=["ATGTTT...", "ATGCGC...",...]
>>> weights = relative_adaptiveness(sequences=sequences)
>>> CAI("ATG...", weights=weights)

These are exactly equivalent:

>>> assert CAI("ATG...", weights=weights) == CAI("ATG...", reference=sequences)

except the former will be faster if you’re using the same weights repeatedly.

Other Genetic Codes

All functions in CAI support an optional genetic_code parameter, which is set by default to 11 (the standard genetic code).

In the CLI, there is an optional “-g” parameter that changes the genetic code:

$ CAI -s sequence.fasta -r reference_sequences.fasta -g 22