@b{MetaQTL} implements a serie of programs which can be combined to do a complete analysis. Here we give details on each program: how to use them and what they do. We classified the programs into 3 main categories which correspond to the main steps of a complete QTL meta-analysis.

@menu
* Consensus map::
* QTL Projection::
* QTL Clustering::
@end menu

@c
@c Consensus map
@c
@node Consensus map
@section Consensus map

The first step of the QTL meta-analysis is to intergate all the input genetic marker maps into a single one called the consensus marker map.

@subsection InfoMap

@subsubsection Method

Before performing the construction of the consensus map, it is important to evaluate how the input maps are connected together. For each linkage group, @b{InfoMap} displays some descriptive statistics about the marker maps and for each pair of mapping experiments the program looks for common marker sequences. A common marker sequence is a set of at least two common markers for which the order in the two linkage groups is consistent. The marker order is said to be consistent even if the sequence is completely inverted between the two linkage groups.

@image{fig1,5cm,10cm,,}

For example, in the above figure the number of common marker sequences is 2. The first one (in red) involved 2 markers (@i{umc116}, @i{umc5b}), which order is reversed between the two chromosome, and the second one (in blue) involved 3 markers (@i{umc110}, @i{bnl16.06}, @i{umc168}).

@subsubsection Command Line Options

@multitable @columnfractions 0.2 0.2 0.2 0.4
@headitem Option @tab Usage    @tab Type    @tab Explanation
@item @code{-m,--mapdir}     @tab required @tab @sc{string}  @tab The directory which contains the XML files.
@item @code{-o,--output}     @tab required @tab @sc{string}  @tab The output file name.
@item @code{-t,--mrkth}      @tab optional @tab @sc{integer} @tab The threshold on the occurence of the markers.
@end multitable

For example,
@example
@verbatim
%java org.metaqtl.main.InfoMap -m xmldb -t 2 -o info.txt
@end verbatim
@end example
gives information on the mapping experiments which XML files are included in the directory @code{xmldb} by keeping only markers which are defined in at least 2 mapping experiments.

@subsubsection Output

The output of @b{InfoMap} is a plain text file. For each linkage group, results are introduced by a '>CR' tag followed by the name of the linkage group as follows:
@cartouche
@smallexample
@verbatim
>CR 7 Connected=true
#
# Table of the chromosomes
#
1	Ribaut		12	9.67
2	Lubberstedt	9	10.34
3	Moreau		9	15.23
4	Rebai		9	13.26
5	Mechin		9	8.78
#
# Average number of marker per chrom m=9.60
# Average interval marker distance=11.45
#
@end verbatim
@end smallexample
@end cartouche
The term @samp{Connected=true} means that it exists a path in terms of common markers from any mapping experiment to any other mapping experiment. Otherwise, the value will be set to @samp{false}. This insures that for this linkage group the consensus map of the chromosome can be build. Then comes a table which summarizes the number of markers and the average interval marker distance per mapping experiment.
It is followed by the table of common markers which gives for each pair of mapping experiments the number of common markers which connects them. It can be viewed as the adjency matrix of the graph which connects the mapping experiments according to the number of common markers they share.
@cartouche
@smallexample
@verbatim
#
# Table of the number of common markers
#
# Total number of marker M=37
# Prop of common markers p=0.1650793650793651
#
Chrom		Index	1	2	3	4	5	Total
Ribaut		1				1.0		1.0
Lubberstedt	2			1.0	2.0	1.0	4.0
Moreau		3		1.0		5.0	2.0	8.0
Rebai		4	1.0	2.0	5.0		3.0	11.0
Mechin		5		1.0	2.0	3.0		6.0
@end verbatim
@end smallexample
@end cartouche
The two last tables are based on the common marker sequences found for each pair of mapping experiments.
@cartouche
@smallexample
@verbatim
#
# Table of the number of common sequences
#
Chrom		Index	1	2	3	4	5
Ribaut		1					
Lubberstedt	2				1.0	
Moreau		3				2.0	1.0
Rebai		4		1.0	2.0		1.0
Mechin		5			1.0	1.0	

#
# Table of proportion of marker involved in common sequences
# The value can be negative depending on the frame of the  
# common sequences
#
Chrom		Index	1	2	3	4	5
Ribaut		1					
Lubberstedt	2				1.0	
Moreau		3				0.2	1.0
Rebai		4		1.0	0.2		1.0
Mechin		5			1.0	1.0	
@end verbatim
@end smallexample
@end cartouche
In this example, the first table reveals that the mapping experiment ``Moreau'' and ``Rebai'' show marker order inconsistency since there are 2 common marker sequences between them. In the second table the proportion of common markers involved in the common marker sequences are reported. This proportion is obtained by summing the number of markers of the common sequences weighted by 1 if the order is the same, -1 otherwise, and dividing this quantity by the total number of common markers. This value lies between -1 and 1. A value of 1 indicates that all the common markers are correclty ordered between the mapping experiments meanwhile a value of -1 indicates that the common marker order is completely reversed between the two mapping experiments. For example, in the above figure the two maps share 5 common markers: 2 are involved in a common sequence which is inverted, and 3 in a common sequence in the same way. Then the proportion of markers involved in common sequences is (3 x 1 + 2 x (-1))/5 = 0.2.

@subsection ConsMap

@b{ConsMap} is dedicated to the construction of consensus marker map.

@subsubsection Method

The method implemented in @b{MetaQTL} is based on a Weigthed Least Square (WLS) strategy. Contrary to iterative projection procedure, this method makes it possible to integrate all maps in a single step. It is also possible to fix a genetic map as reference.

@subsubsection Command Line Options

@multitable @columnfractions 0.2 0.2 0.2 0.4
@headitem Option  @tab Usage    @tab Type        @tab Explanation
@item @code{-m,--mapdir}    @tab required  @tab @sc{string} @tab The directory which contains the XML files.
@item @code{-o,--outstem}   @tab required  @tab @sc{string} @tab The output file stem.
@item @code{-r,--refmap}    @tab optional  @tab @sc{string} @tab The XML file of the reference map.
@item @code{-t,--mrkthresh} @tab optional  @tab @sc{integer} @tab The threshold on the occurence of the markers.
@item @code{-d,--dubfile}   @tab optional  @tab @sc{string} @tab The file containg a list of markers to ignore.
@item @code{--mrkdico}      @tab optional  @tab @sc{string} @tab The marker dictionary.
@end multitable

For example,
@cartouche
@example
@verbatim
%java org.metaqtl.main.ConsMap \
>     -m xmldb -r xmldb/IBM.xml -o consmap
@end verbatim
@end example
@end cartouche
builds a consensus linkage map using all the maps in the directory @file{xmldb} fixing the map defined in @file{xmldb/IBM.xml} as the reference.

@subsection Output

The result of @b{ConsMap} consists in two files:
@itemize @bullet
@item @file{<output_stem>_map.xml} : a XML file which represents the consensus map.
@item @file{<output_stem>_fit.txt} : a plain text file which gives for each chromosome the goodness-of-fit and the standardized residuals between the input maps and the consensus one. Each line begins with an identifier composed by 2 characters followed by its corresponding value.
@multitable @columnfractions 0.1 0.9
@headitem Identifier @tab  Value
@item CR @tab The name of the linkage group.
@item NM @tab The number of distinct markers positioned on the consensus linkage group.
@item GF @tab The goodness-of-fit of the consensus linkage group.
@item PV @tab The p-value associated to the goodness-of-fit.
@item DF @tab The number of degree of freedoms of the residual.
@item SR @tab The standardized residuals: first comes the name of the mapping experiment followed by the value of the residual. These values are ordered according to the order of the marker intervals in the linkage group of the mapping experiment.
@end multitable
For example, this file can look like this:
@cartouche
@smallexample
@verbatim
CR 7
NM 37
GF 182.0738940381568
PV 1.0
DF 7
SR Lubberstedt 1.6308530669014496E-13
SR Lubberstedt -9.205700855506115E-14
SR Lubberstedt -3.401706740747478E-14
SR Lubberstedt -1.049889614734477E-13
SR Lubberstedt 1.2471027908772377E-13
SR Lubberstedt -2.9725343354129593E-13
SR Mechin -4.797069139413729E-15
SR Mechin 5.484351947823543E-14
SR Mechin 6.830428378396427E-15
SR Mechin 0.7995364207820779
SR Mechin 0.3047608429054208
SR Mechin -6.98290111003849E-14
SR Moreau 9.661620158868837E-15
SR Moreau 10.85507243048007
SR Moreau -2.1096760232982783
SR Moreau -0.002216097065843051
...
@end verbatim
@end smallexample
@end cartouche
@end itemize

@c
@c
@c QTL Projection
@c
@c

@node QTL Projection
@section QTL Projection

@subsection Method

QTL projection consists in positioning the QTL located on a given map (the original map) onto another one (the reference map). To illustrate the basic principle of QTL projection, let's assume that the flanking markers of a given QTL location in the original map are also included in the reference. Then the QTL can be projected into the flanking marker interval of the reference map by using a simple homothetic rule. If the QTL have a confidence interval (CI) defined on the orignal map then it is resized on the reference map according to a scaling factor which takes into account the marker interval distance variations between the original and the reference map. This factor is computed by summing, over all the common marker sequences, the ratio of the marker interval distances between the reference and the original map weighted by the probability that the QTL lies in these intervals. 

@subsection QTLProj

@b{QTLProj} implements a dynamic algorithm in order to find the optimal context to do the projection. An optimal context consists in a pair of common marker which flanks the QTL in the original map and for which the distance estimate is consistent between the maps. Two parameters control the behaviour of the algorithm to find such a configuration: the minimal value of the ratio of the flanking marker interval distances and the minimal p-value obtained by testing the homogeneity of the flanking marker interval distances between the original and the reference map. 

@subsubsection Command Line Options

@multitable @columnfractions 0.2 0.2 0.2 0.4
@headitem Option @tab Usage    @tab Type @tab Explanation
@item @code{-m,--map}        @tab required @tab @sc{string} @tab The reference map (XML format).
@item @code{-q,--qtl}        @tab required @tab @sc{string} @tab The directory containing the original maps (XML format).
@item @code{-o,--output}     @tab required @tab @sc{string} @tab The output file stem.
@item @code{-r,--ratio}      @tab optional @tab @sc{double} @tab The minimal ratio between 0 and 1 (default is 0.5)
@item @code{-p,--pval}       @tab optional @tab @sc{double} @tab The minimal p-value between 0 and 1 (default is 0.01).
@item @code{--rmrk}    @tab optional @tab @sc{string} @tab A list of marker to ignore during the projection
@item @code{--rqtl}    @tab optional @tab @sc{string} @tab A list of QTL to be excluded from the projection
@end multitable

For example,
@cartouche
@example
@verbatim
%java org.metaqtl.main.QTLProj \
>     -m reference.xml -q xmldb -o projection -r 0.25 -p 0.05
@end verbatim
@end example
@end cartouche
projects the QTL located onto the maps included in the directory @file{xmldb} on the reference map @file{reference.xml}. Only the QTL for which it is possible to find a pair of flanking markers for which the interval distance is not reduced by more than a factor of 0.25 or for which the p-value of the homogeneity test of equal distances is greater than 0.05 will be projected. If the @code{-v} option is activated, the programs will return as many WARNING outputs as the number of QTL for which the projection is not possible.

@subsubsection Output files

@b{QTLProj} output consists in two XML files:
@itemize @bullet
@item @file{<output_stem>_map.xml} : This file contains both the markers and the projected QTL locations on the reference map (plus eventually the QTL previously defined on the reference).
@item @file{<output_stem>_qtl.xml} : This file contains only the QTL which have been projected on the reference map (plus eventually the QTL previously defined on the reference).
@end itemize

@node QTL Clustering
@section QTL Clustering

Here we want to address the following question: How many ``real'' QTL do the QTL detected in the different mapping experiments represent - one, two, three, four,... or as many as the number detected throughout the studies ? The meta-analysis of QTL can be viewed as a clustering procedure. To do so, @b{MetaQTL} implements tow kinds of clustering algorithm. Whatever the procedure used to perform the clustering, the QTL locations are assumed to be normally distributed around their true locations with variances which can be derived from the reported CI or r-square values. This Gaussian and unbiased approximation comes from the classical asymptotic Gaussian distribution of the maximum-likelihood estimation of the parameters. 

@subsection ClustQTL

@subsubsection Method

@b{ClustQTL} implements a clustering procedure based on a Gaussian mixture model which parameter estimates are obtained by applying a EM-algorithm.

@subsubsection Command Line Options

@multitable @columnfractions 0.2 0.2 0.2 0.4
@headitem Option @tab Usage   @tab Type        @tab Explanation
@item @code{-q,--qtlmap}    @tab required @tab @sc{string} @tab The map with the QTL to clusterize (XML format).
@item @code{-o,--output}    @tab required @tab @sc{string} @tab The output file stem.
@item @code{-t,--tonto}     @tab optional @tab @sc{string} @tab The trait ontology.
@item @code{-k,--kmax}      @tab optional @tab @sc{integer} @tab The maximal number of clusters.
@item @code{-c,--chr}      @tab optional @tab @sc{string} @tab The name of the chromosome on which to perform the meta-analysis.
@item @code{--cimode}    @tab optional @tab @sc{integer} @tab The CI computation mode.
@item @code{--cimiss}    @tab optional @tab @sc{integer} @tab The imputation mode for missing CI.
@item @code{--emrs}    @tab optional @tab @sc{integer} @tab the number of random starting points for the EM algorithm
@item @code{--emeps}    @tab optional @tab @sc{double} @tab the convergence threshold for the EM algorithm
@end multitable

The option @code{--cimode} controls the mode of computation of the variances of the QTL. There are four modes:
@itemize @bullet
@item 1 : the variances are computed according to the avalaible information: from the CI if defined, otherwise from the r-square value.
@item 2 : the variances are only computed for the QTL locations for which a CI is reported.
@item 3 : the variances are computed using the r-square values.
@item 4 : the variances are obtained by taking the maximum value between the variance derived from the CI and/or from the r-square.
@end itemize
The @code{--cimiss} defines how to deal with QTL for which no variance can be computed. There are two possibilities:
@itemize @bullet
@item 1 : the mean of the estimated variances is attributed to QTL with no variance defined.
@item 2 : the QTL with no variance defined are ignored.
@end itemize

@subsubsection Output

The output of @b{ClustQTL} is divided into 3 plain text files:
@itemize @bullet
@item @file{<output_stem>_res.txt} : this files contains a summary of the results of the clustering for each linkage group. The file is organized as follows
@multitable @columnfractions 0.1 0.9
@headitem Identifier @tab  Value
@item CR @tab The name of the linkage group.
@item TR @tab The trait name following by the number of related QTL on the chromosome.
@item QT @tab A QTL with its identifier, its name, its position on the chromosome and its estimated standard deviation.
@item CL @tab Indicates the beginning of a clustering result. It is followed by the number of QTL involved in the clustering, the number of clusters, the log-likelihood and the complete log-likelihood of this clustering.
@item CC @tab The name of a model choice criterion followed by its value.
@item CP @tab This tag recovers four kinds of entry:
@itemize @bullet
@item PI : the weights of each cluster (i.e the mixing proportions in the mixture model).
@item MU : the QTL location estimates (i.e the centroids of each cluster).
@item CI : the 95% confidence intervals of the QTL location estimates.
@item Z  : the QTL cluster membership probabilities: first comes the identifier of the QTL and then the probabilities.
@end itemize
@end multitable
For example,
@cartouche
@smallexample
@verbatim
CR 3
TR FloweringTime 10
QT 0 Lubberstedt_1997_HT_7 106.35 7.9
QT 1 Cardinal_2001_HT_5 90.76 7.91
QT 2 qplht107 150.02 5.28
QT 3 Cardinal_2001_HT_6 51.03 7.26
QT 4 qplht106 107.46 1.3
QT 5 Groh_1998_HT_2 61.03 17.15
QT 6 Bohn_1996_HT_2 66.81 4.26
QT 7 Lubberstedt_1997_HT_6 80.67 3.04
QT 8 qplht105 75.45 4.61
QT 9 Blanc_SDflofch3 148.15 15.05
QT 10 Blanc_FXflofch3 135.27 21.68
CL 10 2 -462.46 -445.55
CC AIC 930.91
CC BIC 935.11
CP MU 88.87 148.91
CP PI 0.73 0.27
CP CI 3.82 3.76
CP Z 0 1 0
CP Z 1 1 0
CP Z 2 0 1
CP Z 3 1 0
CP Z 4 1 0
CP Z 5 1 0
CP Z 6 1 0
CP Z 7 1 0
CP Z 8 1 0
CP Z 9 0 1
CP Z 10 0.1 0.9
...
@end verbatim
@end smallexample
@end cartouche

@item @file{<output_stem>_crit.txt} : this file summarizes the values of the model choice criteria.
For example,
@cartouche
@smallexample
@verbatim
Chromosome	Trait	K	Criterion	Value	Delta	Weight
3	FT	1	AIC	1969.57	1654.71	0
3	FT	2	AIC	930.91	616.05	0
3	FT	3	AIC	445.55	130.69	0
3	FT	4	AIC	364.46	49.6	0
3	FT	5	AIC	314.86	0	0.51
3	FT	6	AIC	315.54	0.68	0.36
3	FT	7	AIC	317.92	3.06	0.11
3	FT	8	AIC	322.44	7.58	0.01
3	FT	9	AIC	326.44	11.58	0
3	FT	10	AIC	330.44	15.58	0
3	FT	30	AIC	361.77	46.92	0
3	FT	1	BIC	1970.97	1643.5	0
3	FT	2	BIC	935.11	607.64	0
3	FT	3	BIC	452.55	125.08	0
3	FT	4	BIC	374.27	46.8	0
3	FT	5	BIC	327.47	0	0.84
3	FT	6	BIC	330.95	3.48	0.15
3	FT	7	BIC	336.14	8.67	0.01
3	FT	8	BIC	343.46	15.99	0
3	FT	9	BIC	350.26	22.79	0
3	FT	10	BIC	357.06	29.59	0
3	FT	30	BIC	403.81	76.34	0
@end verbatim
@end smallexample
@end cartouche
The first column indicates the name of the chromosome, the second one the name of the trait, the third the number of clusters, the fourth the name of the criterion and the three last ones give respectively the criterion value, its rescaled value and the ``weight of evidence''.

@item @file{<output_stem>_model.txt}: This file gives the optimal number of QTL location according to the model choice criteria. The file is organized as a table with 4 columns. The first column indicates the name of the criterion, the second one the name of the chromosome, the third one the name of the trait and the last one the optimal number of QTL. For example,
@cartouche
@smallexample
@verbatim
Criterion	Chromosome	Trait	Model
AIC	3	FT	2
AIC	10	FT	4
AIC	5	FT	4
AIC	7	FT	5
AIC	2	FT	4
AIC	9	FT	3
AIC	4	FT	3
AIC	8	FT	5
AIC	6	FT	3
AIC	1	FT	5
BIC	3	FT	2
BIC	10	FT	3
BIC	5	FT	4
BIC	7	FT	5
BIC	2	FT	4
BIC	9	FT	3
BIC	4	FT	3
BIC	8	FT	5
BIC	6	FT	3
BIC	1	FT	5
@end verbatim
@end smallexample
@end cartouche
@end itemize

@c
@c
@c TreeQTL
@c 
@c
@subsection QTLTree

@subsubsection Method

Another way to clusterize the observed QTL is to use standard hierarchical clustering procedures. @b{QTLTree} implements two kinds of hierarchical clustering algorithm :
@itemize @bullet
@item Average group linkage : once cluster of QTL are formed, they are represented by their mean values, that is, their mean location, and inter-cluster distance is defined as the distance between two mean values. In the average group linkage method, the two clusters Q1 and Q2 are merged such that, after merging, the average pairwise distance within the newly formed cluster, is minimum. Suppose we label the new cluster formed by merging clusters Q1 and Q2, as Q3. Then D(Q1,Q2) , the distance between clusters Q1 and Q2 is computed as D(Q1,Q2) = Average @{d(QTLi,QTLj) : where QTL i and j are in cluster Q3, the cluster formed by merging clusters Q1 and Q2@}. At each stage of hierarchical clustering, the clusters Q1 and Q2 , for which D(Q1,Q2) is minimum, are merged. The distance used here is the mahalanobis distance.
@item Ward's method : Ward (1963) proposed a clustering procedure seeking to form the partitions Qn, Qn-1,........,Q1  in a manner that minimizes the loss of information associated with each grouping, and to quantify that loss in a form that is readily interpretable. At each step in the analysis, the union of every possible cluster pair is considered and the two clusters whose fusion results in minimum increase in 'information loss' are combined. Usually, information loss is defined in terms of a error sum-of-squares like criterion, called the target function. Here the target function is defined as the loglikelihood of being one ``actual'' QTL underlying the distribution of the observed QTL locations within the cluster.
@end itemize

@subsubsection Command Line Options

@multitable @columnfractions 0.2 0.2 0.2 0.4
@headitem Option @tab Usage    @tab Type         @tab Explanation
@item @code{-q,--qtlmap}     @tab required @tab @sc{string}  @tab The map with the QTL to clusterize (XML format).
@item @code{-o,--output}     @tab required @tab @sc{string}  @tab The output file.
@item @code{-m,--mode}       @tab optional @tab @sc{integer} @tab  The clustering mode (default is 2).
@item @code{-t,--tonto}      @tab optional @tab @sc{string}  @tab The trait ontology.
@item @code{--cimode}     @tab optional @tab @sc{integer} @tab The variance computation mode.
@item @code{--cimiss}     @tab optional @tab @sc{integer} @tab The imputation mode for missing variances.
@end multitable

The option @code{-m} (or @code{--mode}) allows user to switch between the two possible clustering algorithms:
@itemize @bullet
@item 1 : Average group linkage.
@item 2 : Ward's metod.
@end itemize
The options @code{--cimode} and @code{--cimiss} works as for @b{QTLClust}.

@subsubsection Output

The output of @b{QTLTree} consists in one plain text file. The file is organized as follows:
@multitable @columnfractions 0.1 0.9
@headitem Identifier @tab  Value
@item CR @tab The name of the linkage group.
@item TR @tab The name of the trait followed by the number of related QTL on the chromosome.
@item QT @tab A QTL involved in the clustering with its identifier, its name, its most probable position on the chromosome and its estimated standard deviation.
@item HC @tab The tree obtained by the clustering algorithm in Newick's format.
@end multitable
For example,
@cartouche
@smallexample
@verbatim
CR 10
TR FT 16
QT 0 Ribaut_1996_DPS_6 8.02 7
QT 1 Bohn_2000_DPS_12 51.68 4.87
QT 2 Poupard_2001_DPS_13 40.02 3.65
QT 3 Mechin_2001_HT_5 71 4.26
QT 4 Lubberstedt_1997_HT_20 59.14 3.65
QT 5 Groh_1998_HT_7 100.01 12.2
QT 6 qplht127 52.39 5.25
QT 7 Rebai_1997_SD_5 66.51 5.17
QT 8 Blanc_DFflofch10 61.57 2.55
QT 9 Rebai_1997_SD_25 54.5 12.46
QT 10 Rebai_1997_SD_19 62.14 10.64
QT 11 Blanc_FXflofch10 58.17 3.57
QT 12 Ribaut_1996_SD_6 6.78 10.83
QT 13 Rebai_1997_SD_33 59.96 9.73
QT 14 Rebai_1997_SD_12 49.04 14.59
QT 15 Blanc_SFflofch10 53.13 3.32
HC ((0:0.16,12:0.16):87.85,((((((1:0.24,((6:0.06,15:0.06):0.11,9:0.11):0.24):0.4,14:0.4)
HC :7.43,(((4:0.04,13:0.04):0.16,11:0.16):1.11,(8:0.01,10:0.01):1.11):7.43):15.64,
HC (3:2.43,7:2.43):15.64):24.56,5:24.56):40.9,2:40.9):87.85);
@end verbatim
@end smallexample
@end cartouche

