
                                  codcmp 



Function

   Codon usage table comparison

Description

   codcmp reads two codon usage table files and writes to file the
   differences in codon usage fractions between the two tables.

   The usage fraction of a codon is its proportion (0 to 1) of the total
   number of the codons in the sequences used to construct the usage
   table. For each codon that is used in both tables, it takes the
   difference between the usage fractions in the two tables. The sum of
   the differences and the sum of the differences squared is reported in
   the output file. It also counts the number of the 64 possible codons
   which are unused (i.e. has a usage fraction of 0) in either one or the
   other or both of the codon usage tables, and writes this to the output
   file.

  Statistical significance

   Question:

   How do you interpret the statistical significance of any difference
   between the tables?

   Answer:

   This is a very interesting question. I don't think that there is any
   way to say if it is statistically significant just from looking at it,
   as it is essentially a descriptive statistic about the difference
   between two 64-mer vectors. If you have a whole lot of sequences and
   codcmp results for all the possible pairwise comparisons, then the
   resulting distance matrix can be used to build a phylogenetic tree
   based on codon usage.

   However, if you generate a series of random sequences, measure their
   codon usage and then do codcmp between each of your test sequences and
   all the random sequences, you could then use a z-test to see if the
   result between the two test sequences was outside of the top or bottom
   5%.

   This would assume that the codcmp results were normally distributed,
   but you could test that too. The simplest way is just to plot them and
   look for a bell-curve. For more rigour, find the mean and standard
   deviation of your results from the random sequences, use the normal
   distribution equation to generate a theoretical distribution for that
   mean and standard deviation, and then perform a chi square between the
   random data and the theoretically generated normal distribution. If
   you generate two sets of random data, each based on your two test
   sequences, an F-test should be used to establish that they have equal
   variances. Then you can safely go ahead and perform the z-test.

   You could use shuffle to base your random sequences on the test
   sequences - so that would ensure the randomised background had the
   same nucleotide content.

   F-tests, z-tests and chi-tests can all be done in Excel, as well as
   being standard in most statistical analysis packages.

   Answered by Derek Gatherer <d.gatherer © vir.gla.ac.uk> 21 Nov 2003

Usage

   Here is a sample session with codcmp

   This compares the codon usage tables for Escherichia coli and
   Haemophilus influenzae.


% codcmp 
Codon usage table comparison
Codon usage file: Eecoli.cut
Second Codon usage file: Ehaein.cut
Output file [eecoli.codcmp]: 

   Go to the output files for this example

Command line arguments

   Standard (Mandatory) qualifiers:
  [-first]             codon      First codon usage file
  [-second]            codon      Second codon usage file for comparison
  [-outfile]           outfile    [*.codcmp] Output file name

   Additional (Optional) qualifiers: (none)
   Advanced (Unprompted) qualifiers: (none)
   Associated qualifiers:

   "-first" associated qualifiers
   -format1            string     Data format

   "-second" associated qualifiers
   -format2            string     Data format

   "-outfile" associated qualifiers
   -odirectory3        string     Output directory

   General qualifiers:
   -auto               boolean    Turn off prompts
   -stdout             boolean    Write first file to standard output
   -filter             boolean    Read first file from standard input, write
                                  first file to standard output
   -options            boolean    Prompt for standard and additional values
   -debug              boolean    Write debug output to program.dbg
   -verbose            boolean    Report some/full command line options
   -help               boolean    Report command line options. More
                                  information on associated and general
                                  qualifiers can be found with -help -verbose
   -warning            boolean    Report warnings
   -error              boolean    Report errors
   -fatal              boolean    Report fatal errors
   -die                boolean    Report dying program messages

Input file format

   It reads in the Codon Usage Tables - these are available as EMBOSS
   data files. See below for details.

Output file format

  Output files for usage example

  File: eecoli.codcmp

# CODCMP codon usage table comparison
# Eecoli.cut vs Ehaein.cut

Sum Squared Difference = 2.178
Mean Squared Difference = 0.034
Root Mean Squared Difference = 0.184
Sum Difference         = 9.504
Mean Difference         = 0.148
Codons not appearing   = 0

Data files

   codcmp requires two codon usage tables which are read by default from
   the EMBOSS data file from Ehum.cut in the data/CODONS directory of the
   EMBOSS distribution. If the name of a codon usage file is specified on
   the command line, then this file will first be searched for in the
   current directory and then in the data/CODONS directory of the EMBOSS
   distribution.

   EMBOSS data files are distributed with the application and stored in
   the standard EMBOSS data directory, which is defined by the EMBOSS
   environment variable EMBOSS_DATA.

   To see the available EMBOSS data files, run:

% embossdata -showall

   To fetch one of the data files (for example 'Exxx.dat') into your
   current directory for you to inspect or modify, run:

% embossdata -fetch -file Exxx.dat

   Users can provide their own data files in their own directories.
   Project specific files can be put in the current directory, or for
   tidier directory listings in a subdirectory called ".embossdata".
   Files for all EMBOSS runs can be put in the user's home directory, or
   again in a subdirectory called ".embossdata".

   The directories are searched in the following order:
     * . (your current directory)
     * .embossdata (under your current directory)
     * ~/ (your home directory)
     * ~/.embossdata

Notes

   The following notes based on Derek Gatherer's comments are useful for
   interpreting the significance of any difference between the tables.

   It's not normally possible to be certain a a difference is
   statistically significant just from looking at it, as it is
   essentially a descriptive statistic about the difference between two
   64-mer vectors. If you have a whole lot of sequences and codcmp
   results for all the possible pairwise comparisons, then the resulting
   distance matrix can be used to build a phylogenetic tree based on
   codon usage.

   However, if you generate a series of random sequences, measure their
   codon usage and then do codcmp between each of your test sequences and
   all the random sequences, you could then use a z-test to see if the
   result between the two test sequences was outside of the top or bottom
   5%.

   This would assume that the codcmp results were normally distributed,
   but you could test that too. The simplest way is just to plot them and
   look for a bell-curve. For more rigour, find the mean and standard
   deviation of your results from the random sequences, use the normal
   distribution equation to generate a theoretical distribution for that
   mean and standard deviation, and then perform a chi square between the
   random data and the theoretically generated normal distribution. If
   you generate two sets of random data, each based on your two test
   sequences, an F-test should be used to establish that they have equal
   variances. Then you can safely go ahead and perform the z-test.

   You could use the shuffle program to base your random sequences on the
   test sequences - so that would ensure the randomised background had
   the same nucleotide content. F-tests, z-tests and chi-tests can all be
   done in Excel, as well as being standard in most statistical analysis
   packages.

References

   None.

Warnings

   None.

Diagnostic Error Messages

   None.

Exit status

   This program always exits with a status of 0.

Known bugs

   None.

See also

   Program name Description
   cai Calculate codon adaptation index
   chips Calculates Nc codon usage statistic
   cusp Create a codon usage table from nucleotide sequence(s)
   syco Draw synonymous codon usage statictic plot for a nucleotide
   sequence

Author(s)

   Alan Bleasby (ajb © ebi.ac.uk)
   European Bioinformatics Institute, Wellcome Trust Genome Campus,
   Hinxton, Cambridge CB10 1SD, UK

   Some more statistics were added by David Martin
   (dmartin © rfcgr.mrc.ac.uk)

History

   Completed 9 Sept 1999
   20 Oct 2000 - David Martin added a couple more statistics to the
   output.

Target users

   This program is intended to be used by everyone and everything, from
   naive users to embedded scripts.

Comments

   None
