@menu
* Overview::
* MetaDB::
@end menu

@node Overview
@section Overview

The first phase in using @b{MetaQTL} is to create the database to store the QTL mapping experiments. The database here relies on a simple multiple file framework. All the tables of the database are plain text file where the first line contains the labels of the columns and the following lines represents the records. For both the header and the records the fields are separated by a @b{@sc{tabulation}}. The global database (METAdb) consists of 3 tables, the experiment table, the trait ontology table and the marker dictionary table, plus 2 sub databases, the genetic linkage map database (GLMdb) and the QTL database (QTLdb). In the next sections we provide a full description of the tables of the database. We have adopted the following convention to specify each field of the tables: the fields in bold are required, i.e they must be specified in the header of the file while the other can be ignored. For each field we have indicated the type of the value between brackets (e.g @sc{string}, @sc{integer}, @sc{boolean},...).

@menu
* Experiment Table::
* Trait Ontology Table::
* GLMdb::
* QTLdb::
@end menu

@node Experiment Table
@subsection Experiment Table

The experiment table summarizes the parameters of each mapping experiment. This table contains the following fields:

@itemize @bullet
@item @b{map} (@sc{string}) : the name of the mapping experiment which must be unique.
@item @b{mapping.function} (@sc{string}) : the name of the mapping function used to build the genetic map for this mapping experiment. Presently the possible values are:
@itemize @minus
@item haldane
@item kosambi
@end itemize
@item @b{mapping.unit} (@sc{string}) : the unit of the genetic distances of the genetic linkage map. Possible values are M for Morgan or cM for centiMorgan.
@item mapping expansion (@sc{boolean}) : 1 if the genetic linkage map of this mapping experiment must be rescaled.
@item mapping.cross : the cross design used to build the map (may differ from the cross.type).
@item @b{cross.type} (@sc{string}) : the cross design used to build the genetic linkage map. @b{MetaQTL} is able to deal with various types of experimental designs. The design is encoded by a string of characters. For example BC stands for backcross, SF@i{i} stands for selfed intercross lines and the integer @i{i} indicates the generation (if @i{i}=2 then we have a classical F2). Experimental designs presently supported are listed in the table below (the cross type naming and labelling convention comes from QTLCartographer).

@multitable @columnfractions @columnfractions 0.80 0.1 0.1
@headitem Cross type @tab Code @tab Example
@item Backcross
@tab  BC
@tab  BC
@item Selfed generation @i{i} intercross
@tab SF@i{i}
@tab SF2
@item Randomly mated generation @i{i} intercross
@tab RF@i{i}
@tab RF3
@item Recombined Inbred via selfing
@tab RI0
@tab RI0
@item Recombined Inbred via sib mating
@tab RI1
@tab RI1
@item Intermated (@i{i} generations) Recombined Inbred via selfing
@tab IRI0i
@tab IRI04
@item Intermated (@i{i} generations) Recombined Inbred via sib mating
@tab IRI1i
@tab IRI13
@end multitable

@item @b{cross.name} (@sc{string}) : the name of the cross.
@item @b{cross.size} (@sc{integer}): the number of individuals used to build the genetic linkage map.
@end itemize

For example, inserting 5 mapping experiments leads to the following file

@cartouche
@smallexample
@verbatim
map  mapping.function  mapping.unit  mapping.expansion  cross.type  cross.name  cross.size
exp1   haldane   cM   0   SF2   Mo17xB73   200
exp2   haldane   cM   1   RF4   F2xF252    300
exp3   kosambi   M    0   BC    H99xF2     150
exp4   haldane   cM   1   IRI04 F2xF252    400
exp5   haldane   cM   0   SF4   Mo17xF2    150
@end verbatim
@end smallexample
@end cartouche

@node Trait Ontology Table
@subsection Trait Ontology Table

@b{MetaQTL} can also use a trait ontology in order to group the QTL in trait categories. The ontology representation handled by @b{MetaQTL} is based on a simple hierarchy (such as a taxonomy) where each child has a unique parent. The table which stores the trait ontology is defined by the following fields:
@itemize
@item @b{term_id}(@sc{integer}): the unique identifier of the term.
@item @b{term_name}(@sc{string}): the name of the term, i.e the trait name.
@item @b{parent_id}(@sc{integer}): the identifier of the unique parent of this term (required except for the root of the ontology).
@item synonyms(@sc{string}): the synonyms of the trait name separated by a coma (then the synonyms must not contain any coma).
@item definition(@sc{string}): the definition of the trait.
@end itemize

For example:
@cartouche
@smallexample
@verbatim
term_id   term_name   parent_id   synonyms   definition
1       my_ontology
2       flowering_time          1
3       days_to_pollon_shed     2
4       plant_height            2
5       leaf_number             2
6       silking_date            2
@end verbatim
@end smallexample
@end cartouche

@b{REMARK:} The trait ontology must always be rooted (in the previous example the root was @code{my_ontology}). Generally, The root is not itself a trait but the name of the ontology.

@comment @node Marker Dictionary Table
@comment @subsection Marker Dictionary Table

@comment The marker dictionary table allows user to specify correspondances between marker names. It is not uncommon in mapping experiments that a same marker is reported with different names. Thus this table makes it possible to specify a standard marker name for which a list of synonyms can be attached. To do so, the table consists in two columns, the first one gives the standard name and the second one a possible synonym. For a given standard name there are as many records in the table as the number of synonyms.
@comment @itemize
@comment @item @b{standard}(@sc{string}): the standard name of the marker.
@comment @item @b{synonym}(@sc{string}): a synonym.
@comment @end itemize

@comment For example,
@comment @cartouche
@comment @smallexample
@comment @verbatim
@comment glb1    umc184a(glb1)
@comment umc236  php4015
@comment dhn1    umc170(dhn)
@comment dhn1    umc170(rab17)
@comment rop7    umc1950
@comment umc243a php4227a
@comment mmp121  umc2163
@comment adh1    umc1726
@comment adh1    umc(adh1)
@comment umc171b(oec23)  npi473(oec)
@comment umc171b(oec23)  oec1
@comment umc171b(oec23)  umc171b
@comment umc171b(oec23)  umc171b(oec)
@comment his1a   umc1577
@comment his1a   umc312
@comment his1a   umc312(gfu)
@comment ...
@comment @end verbatim
@comment @end smallexample
@comment @end cartouche

@node GLMdb
@subsection GLMdb

The genetic linkage map database is simply organized as a set of plain text files each corresponding to a single genetic linkage map. The link between the experiment table and the genetic map files is done by using the same stem file name than the name of the mapping experiment declared in the column @b{map} of the experiment table. For example the genetic linkage map related to the mapping experiments @samp{exp1} will be stored in a file named @file{exp1.txt}. Here a genetic linkage map is represented by a table with the following fields:
@itemize @bullet
@item @b{group} (@sc{string}) : the linkage group name.
@item @b{marker} (@sc{string}) : the name of the marker.
@item @b{position} (@sc{numeric}) : the position of the marker on the linkage group the unit of which is declared in the experiment table.
@end itemize

For example, the genetic linkage map file for the mapping experiments @verb{|exp1|} would be
@cartouche
@smallexample
@verbatim
group	marker	position
1    	lgm0392	0
1    	bnlg1178	47.7
1    	ts2	102.7
1    	bnlg1884	137.5
1    	lgm1234	179.3
1    	lgm1465	293.2
2    	bnlg1092	0
2    	bnlg1017	26.8
2    	lgm0701	37.4
2    	lgm0653	165
2    	bnlg1520	190.8
2    	dupssr32	218.1
3    	bnlg1904	0
3    	bnlg1035	36.6
3    	bnlg1063	63.1
3    	bnlg1182	140.2
3    	dupssr8b	161.2
@end verbatim
@end smallexample
@end cartouche

@node QTLdb
@subsection QTLdb

As for GLMdb the QTL database consists in as many plain text files as the number of mapping experiments described in the experiment table. Each file must respect the same naming convention as for GLMdb, i.e the stem name of the file must be the name of the corresponding mapping experiment as defined in the @b{map} field of the experiment table. Thus if a QTL detection result has been reported for the mapping experiment @samp{exp1} we will have a file @file{exp1.txt}. Each file of QTLdb are organized as follows:
@itemize @bullet
@item @b{group} (@sc{string}) : the linkage group name.
@item @b{qtl} (@sc{string}) : the name of the QTL.
@item @b{position} (@sc{numeric}) : the most probable position of the QTL on the linkage group.
@item @b{qtl.trait.name}(@sc{string}): the name of the trait to which this QTL is related.
@item qtl.ci.from(@sc{numeric}) : the lower bound of the CI of the QTL position.
@item qtl.ci.to(@sc{numeric}) : the upper bound of the CI of the QTL position.
@item qtl.ci.lod.decrease(@sc{numeric}): if the CI is based on a LOD support, use this field to define the decrease of LOD which was used to build the CI.
@item qtl.rsquare(@sc{numeric}): the estimated r-square of the QTL.
@item qtl.cross.name(@sc{string}): the name of the cross used to carry out the QTL mapping.
@item qtl.cross.type(@sc{string}): the type of the cross used to carry out the QTL mapping.
@item qtl.cross.size(@sc{integer}): the size of the cross used to carry out the QTL mapping.
@end itemize

@cartouche
@smallexample
@verbatim
group  qtl  position qtl.ci.lod.decrease  qtl.ci.from  qtl.ci.to  qtl.rsquare qtl.trait.name
1  QTL1  208  1  182  236  0.044  days_to_pollen_shed
1  QTL2  152  1  128  174  0.045  silking_date
2  QTL3  74   1  58   88   0.051  silking_date
2  QTL4  126  1  110  140  0.048  days_to_pollen_shed
3  QTL6  36   1  18   46   0.093  leaf_number
8  QTL5  76   1  60   92   0.21   leaf_number
@end verbatim
@end smallexample
@end cartouche

@node MetaDB
@section MetaDB

This program is designed to reformat all the tables of the database into a set of XML files which will be used by the analysis programs.

@subsection Command Line Options

@multitable @columnfractions 0.2 0.15 0.15 0.5
@headitem Option @tab Usage @tab Type @tab Explanation
@item @code{-e,--exp}    @tab required @tab @sc{string} @tab Experiment file
@item @code{-o,--output} @tab required @tab @sc{string} @tab Output XML directory
@item @code{-m,--mapdb}  @tab required @tab @sc{string} @tab The GLMdb directory
@item @code{-q,--qtldb}  @tab optional @tab @sc{string} @tab The QTLdb directory
@item @code{-t,--tofile} @tab optional @tab @sc{string} @tab Trait Ontology file
@item @code{-d,--mrkdico}@tab optional @tab @sc{string} @tab Marker dictionary file
@item @code{--mrkup} @tab optional @tab @sc{string} @tab A file with the marker name to update
@item @code{--mrkrm} @tab optional @tab @sc{string} @tab A file with the marker to remove
@item @code{--chrm} @tab optional @tab @sc{string} @tab A file with the chromosome to remove
@end multitable

For example, suppose we have created a database which consists in the files @file{exp.txt} (experiment table), @file{onto.txt} (trait ontology), @file{dico.txt} (marker dictionary), and the directories @file{glmdb/} and @file{qtldb/} which contain the marker map and the QTL map tables relative to the mapping experiments specified in @file{exp.txt}. We assume that all the files and directories are included into the same directory, the database directory. Then we can create the XML repository, @file{xmldb/}, by invoking the command (in the database directory)
@cartouche
@smallexample
>java org.metaqtl.main.MetaDB \
        -e exp.txt -t onto.txt -d dico.txt -m glmdb -q qtldb -o xmldb
@end smallexample
@end cartouche
This creates as many XML files in the @file{xmldb/} directory as the number of mapping experiments. For a given mapping experiment all the information (parameters, markers, QTL, ...) are merged into a single XML file which stem name is the same than the mapping experiment name. The output directory @file{xmldb/} also contains a file named @file{ontology.xml} which represents the trait ontology table (if this last one is not valid, the file is not created). Finally, using the marker dictionary, @b{MetaDB} converts all the marker names which match a synonym in the marker dictionary to their standard name. If you want to export these XML files into another file format, @xref{Xml2A}.

For the option @code{--mrkup}, the input file format must be a table with 4 columns seperated by a tabulation as follows:
@example
Exp1	Chrom1	mrk3	mrk3a
Exp1	Chrom2	mrk4	mrk4b
Exp2	Chrom1	mrk1	mrk1c
...
@end example
@noindent
where the first column gives the name of the mapping experiment (must be the same than in the experiment table), the second the name of the chromosome, the third one the current name of the marker to update and the last one the new name of the marker.

For the option  @code{--mrkrm}, the input file is the same than the previous one except that it contains only the first three columns.

Finally, for the option @code{--chrm}, the input file is the same than the previous one except that it contains only the first two columns.

Note that these three last options have no effect on the raw data file: the rules they define are only applied to the ouput XML data base.

