Codon Optimal Likelihood Discoverer

Cold requires a number of files for input. The formats and uses of these files are as described below, as well as the example files included in the package. The example files can be found in either the "Data", or the "Models" directory, depending on the use of the file:

Trees:

Generally Newick formatted trees should work. The semicolon at the end is optional. Multiple trees can be given in a single file, each on a separate line; no more than one tree should be listed on a single line. It is not necessary to include blank lines between different trees, but it will improve readability.

Clades should be placed in brackets, with the length of the branch joining the clade to the rest of the tree listed after the clade, separated by a colon. The species names can be anything not containining the characters '(', ',', ')', ':', or newline. However the space ' ' character should be avoided because it makes reading the data not work. An example of a valid tree is:

See the file testtrees for more examples.

Data:

The lengths of the sequences can either be listed on the first line of the file, as the second number on that line (the first number is usually used for the number of species, though cold does not require this number, it assumes that it is there for compatibility with other packages which do require it), or else, the length of each sequence can be listed on the line with that sequence. It is possible to input sequences of different lengths, aligned at the start of the first sequence, however, cold assumes that all sequences are at least as long as the first sequence, so the first species in the tree must be the one with the shortest sequence in this case.

The data should be listed as nucleotide sequences. Each line should consist of the name of the species, followed by a space (or multiple spaces), then the length of the sequence (if necessary), then the sequence. [Note that this format does not allow spaces in species names. It is possible that such a feature may be incorporated into later versions.] Any character other than ACGT or a space is treated as an unknown nucleotide. (This means there is limited error checking, for instance no error would be produced by the sequence ACTGTGTTTCSC - the program would simply interpret the S as an unknown nucleotide, instead of a typo, which is a more likely explanation.)

[Currently there is no way to specify partial information about a nucleotide. This feature may be added in later versions.]

Each sequence should be on a separate line. The program can search the tree for species names, so, as long as the sequences for all species in the tree are contained in the file, it will work - it doesn't matter if the file contains extra data. The program will give an error if it can't find the data for any of the species in the tree.

See the file testdata for examples.

Matrices:

Matrices should be listed in the usual format. Entries should be separated by the space character. Multiple spaces are OK. Lines are separated by newline characters. The size of the matrix is determined by the length of the first line, so it is important that the first line should be the right length. Other lines don't matter (though it will look better if all lines are the right length).

Separate matrices in the file do not [at least, should not - I haven't done a lot of testing of obscure input formats] need to be separated by newlines, but doing so will improve readability of the file.

InitialParameters:

The initial parameters file contains a list of the Pi values, followed by initial values for all the parameters that are to be estimated.

See the file M0_example_initpars for an example.

Variables:

Mixture:

Each row represents a parameter for the components. The row starts with the number of the parameter (starting with 0, which is the rate). Then it has a list of classes separated by colons if the parameters must have equal values, and commas if they can have separate values. A dot between two values indicates a comma-separated list of all values between them, that have not already been listed. A dash indicates a colon-seperated list. If there is no first value, zero is assumed. If there is no second value, the number of components minus one is assumed (so that all later components are included). If the parameter number in a row is a dot, this means that all rows between the one above and below that do not already have patterns should follow this pattern (or the pattern of the row above if there is no pattern). If the parameter number is a |, it indicates that the groups in the rows above and below should be merged. Rows can be separated with a semicolon instead of an end of line. This is useful for inputing the mixture as a string, rather than writing a separate file for very simple mixtures.

[Some aspects of this don't work quite as described yet. This shouldn't be a problem for usual mixture files, only if the mixture file is specified in a strange way. If you list the rows and entries in increasing order, there should be no problems. Things like 5 7-5,3.6,0:2;|;.;2, however, are not guarenteed to work correctly.]

For examples, see the file mixture. See also the mixture strings in the file models.

Models:

State file

This file should not be edited by the user. The reason for understanding the file layout is for debugging in the event of an error. The statefile is generated either in the event of a fatal error, or as a regular backup for long runs. It's purpose is to allow the program to resume running from the point at which it was interrupted. This is done using the --recover option.

File searching

Changing the search path

The -f option