1 Introduction

CoMap performs two kinds of tasks:

(Weighted) Probabilistic substitution mapping

Compute all (weighted) number of substitutions occurring on each branch of a tree, for each site of an alignment.

Co-evolution analysis

Using the substitution mapping, look for significantly groups of sites departing the null hypothesis of independence. Two kind of analyzes are provided: a pairwise analysis, presented in Dutheil et al. (2005), and a clustering analysis in Dutheil and Galtier (2007). In both cases, a parametric bootstrap approach is used to evaluate the significance of groups. Simulation results are written to separate files, a statistics software like R is required to look for the significance. For the clustering analysis, we provide R script to perform theses computations. No preliminary knowledge of the R language is required, although it is recommended.

CoMap is a command line program, written in C++ using the Bio++ libraries. It uses the Bio++ syntax, so that arguments may be passed as parameter=value options, either directly to the command line or using an option file. For more information about this very general syntax, please read the Bio++ Program Suite manual, available online at http://home.gna.org/bppsuite. You can also download a PDF version here http://home.gna.org/bppsuite. Since it uses the Bio++ libraries, CoMap shares several options with the BppML program, to read sequences and specify models for instance. We will only report the difference between CoMap and BppML in this manual.

2 Data loading

CoMap inputs two kinds of data: a sequence alignment file and a phylogenetic tree. The corresponding options are fully described in the Bio++ Program Suite manual.

CoMap adds an option to remove conserved sites from the analysis. The removal will occur after parameter optimization, if relevent.

3 Model specification

CoMap support all substitution models available in Bio++, including non-homogeneous models. Options for specifying a model are described in full in the Bio++ Program Suite manual.

4 Numerical parameters estimation

CoMap can (re-)estimate numerical parameters for you before any analysis. These parameters include

• Branch lengths
• Entries of the substitution matrices, included base frequencies. values)
• Parameters of the rate distribution (shape parameter of the gamma law, proportion of invariant sites).

The corresponding options are described in the Bio++ Program Suite manual. Note however that CoMap do not perform topology estimation. The tree topology will is considered to be know prior to the analysis. The tree can however contain multifurcations (WARNING: not fully tested, please report any bug you may found!).

5 Substitution mapping

Options described in this part are specific to CoMap. Options in this chapter are for the computation of substitution vectors.

input.vectors.file = {{path}|none}

Restart an analysis by specifying the already computed vectors. Otherwise, compute vectors using the following options.

output.vectors.file = {{path}|none}

Where to write the substitution mapping.

nijt = {Naive|Laplace|Uniformization|Decomposition}

The kind of mapping to perform. Laplace(trunc={int>1}) option perform exact mapping, as in Dutheil et al. (2005). The trunc option set where to trunc the series (default to 10). Note that this substitution count is rather slow, the uniformization or decomposition methods are faster and more accurate. This option is only there for legacy purpose. Naive(weight=...) performs a naive mapping, as in Tuffery and Darlu (2000). Uniformization(weight=...) [default] performs exact mapping, with the uniformization method (See Tataru and Hobolth, 2011). Decomposition(weight=...) performs exact mapping, with the decomposition method (See Tataru and Hobolth, 2011). Currently available only for proteins.

The Naive, Uniformization and Decomposition methods all allow to perform weighted substitution mapping, by taking a weight argument. Only two options are available for now:

None

The default, no weighting is used, all substitution weight the same.

AAdist

Amino-acid distance. This option takes further arguments:

type = {grantham|miyata|grantham.volume|grantham.polarity|charge|klein.charge|user1|user2}

Specify the type of weight to use. The user1 option is for computing a simple distance from a AAIndex1 file, user2 uses a AAIndex2 distance file.

file = {path}

File path toward a AAIndex1 and AAIndex2 file, ignored otherwise.

sym = {boolean}

Tell if symmetric matrices must be used. This option should be set to "no" for testing compensation.

• Optional commands
• Site specific statistics
• Ancestral sequences reconstruction
• Output node ids

6 Pairwise analysis

analysis = pairwise

Use this option for performing a pairwise analysis. If another option or none is selected, no pairwise analysis is performed.

statistic = {Correlation|Compensation|Cosubstitutions}

The coevolution statistic to use. The Correlation option is to be used in order to perform the MBE 2005 analysis. Uses option Compensation to perform a pairwise analysis with the compensation statistics introduced in the BMC Evol Biol 2007 paper. You can also use the Cosubstitution option to perform Tuffery & Darlu’s MBE 2000 analysis.

statistic.output.file = {path}

Where to write the statistic value for each pair of sites.

statistic.null = {boolean}

Tell is the null distribution of the statistic must be computed, using parametric bootstrap. The number of simulations performed is the product of two numbers, adjusting the amount of CPU and RAM to use.

statistic.null.nb_rep_CPU = {int>0}

Increase this parameter to take less memory (slow the program)

statistic.null.nb_rep_RAM = {int>0}

Increase this parameter to speed the program (need more memory)

statistic.null.output_file = {path}

Where to write the null distribution

statistic.null.compute_pvalue = {bool} (statistic.null=yes)

Shall we use the null distribution to compute p-values? From version 1.4.0, CoMap can now compute built-in p-values, without relying on an external R-script.

statistic.null.nb_rate_classes = {int} (statistic.null.compute_pvalue = yes)

Specifies how many classes should be used when conditioning of pairs rate. A value of 0 or 1 implies no conditionning.

• Performing inter-gene comparisons
• Optional commands

7 Clustering analysis

analysis = clustering

Use this option for performing a clustering. If another option or none is selected, no pairwise analysis is performed.

clustering.distance = {cor|euclidian|comp|none}

Distance to use: cor (correlation), euclidean, comp (compensation) or none (no clustering).

clustering.method = {complete}

Clustering algorithm: complete linkage. Other linkage types are available, but the complete one gives the better results.

clustering.output.matrix.file = {{path}|none}

Where to write the distance matrix (in phylip format).

clustering.output.tree.file = {{path}|none}

Where to write the clustering tree (newick format).

clustering.output.groups.file = {{path}|none}

Where to write the clusters (CSV format).

clustering.null = {boolean}

Tell if the null distribution of clusters must be computed.

clustering.null.number = {int>0}

Number of data sets to simulate.

clustering.null.output.file = {path}

Where to write the simulated clusters (CSV format).

8 Candidate groups analysis

This method is used to test candidate groups of sites. It perform a more powerful test by taking into account the precise rate of each site, and no longer relies on the minimum rate of the group as in the pairwise or clustering method. As a consequence, it is much slower, and should therefore only be used when some candidate groups are to be tested. It can’t be used in an exhaustive manner.

Important note: This method does not require the R scripts to be used! It directly outputs p-values :)

candidates.input.file = {path}

The file to read. It must be in CSV-like format, with one group per line, and column names.

candidates.input.column_name = {string}

The name of the column that will contain groups. Groups should be described as [pos1;pos2;etc], refering to alignment positions, starting at 1.

candidates.input.column_sep = {char}

The character used to separate columns in the input file.

candidates.omega = {float}

The width of the window for telling whether two sites have similar rates or not. A value of 0.2 is usually good enough. The smaller the value, the more precise the computations, but the slower the execution time.

candidates.null.min = {int>0}

Minimum number of simulations to perform for each group.

candidates.null.nb_rep_RAM = {int>0}

Controles the number of sites to simulate at a time. The higher the value, the faster the execution, but at the expense of more memory usage.

candidates.null.verbose = {int>=0}

Controles the amount of output to terminal.

candidates.output.file = {path}

The file to write, identical to the input one but with extra columns, in CSV format.

candidates.output.column_sep = {char}

The column separator for output file.

9 Output format and P-value computation

CoMap computes built-in p-values for the pairwise and candidate group analyses. For group detections, p-value computation is performed by two R scripts, distributed along with the program. The reason for this is that there are different ways to compute p-values, depending on the null-hypothesis to test. Getting the simulation result being the most expensive in terms of computer resources, I preferred to store them in files, and then play with R to get the p-values. It also allows to visualize the null-distribution and get more “feeling” about the data.

• Output format
• Available R scripts

R --vanilla < computePValues.R

10 Mica: Mutual Information Coevolution Analysis

The Mica program performs several standard mutual information (MI) analyses. Basically, it computes the MI value for all pairs of sites in an alignment, and optionally compute the MI value on randomized data. The resulting values can be compared in R in order to get a simple p-value. Mica also computes various rate measures, so that the CoMap R scripts and algorithms can be used with Mica’s output. Mica can generate replicates using either parametric bootstrap, like CoMap, or non-parametric bootstrap like in Caporaso et al (2008). It can also compute corrected MI (MIp from Gloor et al), and the associated p-values using a Z-score approach.

• Input data.
• Output results.
• Assessing significance of the coevolution statistics.