@b{MetaQTL} provides some utilities that read the input or the output of the analysis programs and reformat it as images. These images can then be visualized using standard image viewer or editor.

@menu
* MapView ::
* MMapView ::
* MQTLView ::
@end menu

@node MapView
@section MapView

@b{MapView} is designed to draw markers and QTL for one or several linkage groups, depending on drawing parameters.
 
@subsection Command Line Options

@multitable @columnfractions 0.2 0.2 0.2 0.4
@headitem Option @tab Usage    @tab Type    @tab Explanation
@item @code{-m,--mapfile}    @tab required @tab @sc{string}  @tab The XML file for the genetic map.
@item @code{-c,--chrom}      @tab required @tab @sc{string}  @tab The name of the chromosome(s) to display.
@item @code{-o,--output}     @tab required @tab @sc{string}  @tab The output file stem.
@item @code{-q,--withqtl}    @tab optional @tab @sc{integer} @tab Draw also QTL.
@item @code{-t,--tonto}      @tab optional @tab @sc{string}  @tab The XML file for the trait ontology
@item @code{-p,--parfile}    @tab optional @tab @sc{string}  @tab The drawing parameter file.
@item @code{--qmode}            @tab optional @tab @sc{integer}  @tab QTL representation mode (0=bar,1=arrow)
@item @code{--tree}           @tab optional @tab @sc{string}  @tab a QTL tree (obtained with QTLTree);
@item @code{--img}           @tab optional @tab @sc{string}  @tab The format of the image (use --help for possible values).
@end multitable
For example,
@cartouche
@example
@verbatim
%java org.metaqtl.main.MapView \
>     -c 1,2 -m map.xml -q -o figure --img jpeg
@end verbatim
@end example
@end cartouche
draws the chromosome 1 and 2 with both markers and QTL of the given map @file{map.xml} and outputs the result in @file{figure.jpeg}. This also creates a file named @file{figure.par} which gives the values of the drawing paremeters. This file can be modified and reused to create another image by using the @code{-p} or @code{--par} option
@cartouche
@example
@verbatim
%java org.metatqtl.main.MapView \
>     -c 1,2 -m map.xml -q -o figure -p figure.par --img jpeg 
@end verbatim
@end example
@end cartouche
The next section gives more details on how to deal with the drawing parameters.

@subsection Drawing Parameters

Several parameters allow user to put in form the figure. The next figure illustrates the role of each parameter.
@float Figure,fig2:fig2
@image{fig2,15cm,25cm,,}
@caption{Details of formatting parameters for MapView.}
@end float
The paremeter file is organized as follows:
@cartouche
@smallexample
@verbatim
#
# Graphical Parameters
#
# CHROMOSOME
#
CHROM_DISTANCE_SCALE=5.0
CHROM_FLANKING_CEX=0.1
CHROM_NAME_FONT=Utopia Regular:BOLD:12
CHROM_NAME_HSPACE=20.0
CHROM_TICK_WIDTH_1=10.0
CHROM_TICK_WIDTH_2=20.0
CHROM_TICK_WIDTH_3=10.0
CHROM_WIDTH=30.0
MAKER_NAME_VSPACE=1.0
MARKER_NAME_FONT=Utopia Regular:PLAIN:10
MARKER_POSITION_FONT=Utopia Regular:PLAIN:10
#
# QTL
#
QTL_CI_WIDTH=10.0
QTL_CI_WIDTH_CEX=0.25
QTL_HSPACE=10.0
QTL_NAME_FONT=Courier:PLAIN:10
QTL_NAME_VSPACE_CEX=1.0
QTL_POS_HEIGHT_CEX=0.01
QTL_POS_WIDTH_CEX=1.5
QTL_VSPACE=20.0
#
# LEGEND
#
LEGEND_BOX_CEX=0.5
LEGEND_FONT=Verdana:PLAIN:10
LEGEND_HSPACE=5.0
LEGEND_PART_HEIGHT=20.0
LEGEND_PART_WIDTH=50.0
LEGEND_SCALE_UNIT=5
#
# OTHER
#
BACKGROUND_COLOR=ffffff
LAYER_HSPACE=20.0
LAYER_VSPACE=20.0
WITH_CHROM_NAME=true
WITH_LEGEND=true
WITH_MAP_NAME=true
WITH_MARKER_NAME=true
WITH_QTL_NAME=true
WITH_MARKER_POSITION=true
@end verbatim
@end smallexample
@end cartouche
A line which begins by the character @samp{@code{#}} is ignored by the program. Each drawing parameter is specified by its own name directly followed by a sign @samp{@code{=}} and its value. For the parameters which specify a color (those which end by @samp{@code{_COLOR}}) the value must be a RGB code in hexadecimal (e.g red is ff0000, green 00ff00, blue 0000ff, white ffffff, black 000000, and etc...). For the parameters which specify a font (those which end by @samp{@code{_FONT}}) the value must be a string composed by 3 tokens separated by a @samp{@code{:}}. The first token gives the name of the font, the second one the style of the font (among @samp{@code{PLAIN,BOLD}} and @samp{@code{ITALIC}}) and the last one indicates the size of the font. The parameter file generated by @b{MapView} ends by a list of the available fonts on your system. If you do not use a font name in this list, then @b{MapView} will use the default font.
The parameters which start by @samp{@code{WITH_}} allow the user to specify if the corresponding elements of the figure must be drawn. The possible values for these parameters are either @samp{@code{true}} (draw) and @samp{@code{false}} (not to draw). For example if you set @samp{@code{WITH_MARKER_POSITION=false}} the marker positions along the chromosome wont' be drawn.
When the QTL are added to the figure (option @code{-q} with @b{MapView}) they are colored according to their trait group. The colors used to display the QTL are also specified in the parameter file generated by the program. For example, let's assume that the QTL belongs to 3 trait groups. The parameter file will then contain the following lines:
@cartouche
@smallexample
@verbatim
#
# COLOR PALETTE
#
QTL_COLOR_1=ffff00
QTL_COLOR_2=00ff00
QTL_COLOR_3=0000ff
@end verbatim
@end smallexample
@end cartouche
where @code{QTL_COLOR_i} is the color of the group @code{i}. You can use these lines to modify the default colors.
@node MMapView
@section MMapView

@b{MMapView} is designed to draw markers and QTL for one linkage group for several genetic maps. It helps to visualize common markers between maps but also to display marker interval distance heterogeneities.
 
@subsection Command Line Options

@multitable @columnfractions 0.2 0.15 0.15 0.5
@headitem Option @tab Usage    @tab Type    @tab Explanation
@item @code{-m,--mapdir}     @tab required @tab @sc{string}  @tab The XML file/directory for the genetic map(s).
@item @code{-c,--chrom}      @tab required @tab @sc{string}  @tab The name of the chromosome to display.
@item @code{-o,--output}     @tab required @tab @sc{string}  @tab The output file stem.
@item @code{-r,--refmap}     @tab optional @tab @sc{string}  @tab The XML file for the reference map.
@item @code{-q,--withqtl}    @tab optional @tab @sc{integer} @tab The threshold on the occurence of the markers.
@item @code{-t,--tonto}      @tab optional @tab @sc{string}  @tab The XML file for the trait ontology
@item @code{--htest}      @tab optional @tab @sc{boolean} @tab Test distance homogeneity between the maps and the reference (only with -r).
@item  @code{--hth}       @tab optional @tab @sc{double}  @tab The threshold of the p-value of the homogeneity test between the maps and the reference (only with -r and -h). The value must be between ]0,1[. A value of 0 or 1 codes for a gradient view.
@item   @code{--mrkt}      @tab optional @tab @sc{integer} @tab Threshold on the occurence of the markers.
@item @code{-p,--parfile}    @tab optional @tab @sc{string}  @tab The drawing parameter file.
@item   @code{--img}       @tab optional @tab @sc{string}  @tab The format of the image (use --help for possible values).
@end multitable
Suppose we have a set of genetic maps in XML format in the directory @file{xml} and that all the maps have a chromosome called 1. Then we can use @b{MMapView} to display all the chromosomes in a single figure as follows:
@cartouche
@smallexample
@verbatim
%java org.metaqtl.main.MMapView \
>     -c 1 -m xml -o figure
@end verbatim
@end smallexample
@end cartouche
This dumps the image into a file @file{figure_1.jpeg} and the parameter file into @file{figure_1.par}. We can also represent the same chromosomes but with only the markers which have observed at least in two distinct chromosomes by using the option @code{--mrkt}:
@cartouche
@smallexample
@verbatim
%java org.metaqtl.main.MMapView \
>     -c 1 -m xml -o figure --mrkt 2
@end verbatim
@end smallexample
@end cartouche
Now, suppose we want to draw the same chromosomes but also to represent the eventual interval marker distance heterogenities relatively to a reference chromosome defined in file @file{reference.xml}. Then we use the command,
@cartouche
@smallexample
@verbatim
%java org.metaqtl.main.MMapView \
>     -c 1 -m xml -r reference.xml --htest -o figure
@end verbatim
@end smallexample
@end cartouche

@subsection Drawing parameters

@b{MMapView} use the same drawing parameters than @b{MapView} plus some extra parameters. If you want to display common marker links between adjacent chromosomes set @samp{@code{WITH_COMMON_MARKER}} to @samp{@code{true}}. The width of the lines which connect the common markers can be modified by using the parameter @samp{@code{COMMON_STROKE_WIDTH}}. This is illustrated in the next figure.

@image{fig3,10cm,15cm,,}
@c @caption{Comparive view of two chromosomes. The common marker sequences are displayed in color depending on their ways.}

The link between common markers can also be painted depending on the way of the common sequences in which they are involved. For example, in the above figure the common markers which are involved in common sequence correctly ordered between the two chromosomes have their links painted in blue, otherwise their links are painted in red. Note that one marker is not involved in a common sequence and its link is painted in gray. These colors can be changed by using the parameters @samp{@code{SINGLE_COMMON_COLOR}}, @samp{@code{POS_COMMON_COLOR}} and @samp{@code{NEG_COMMON_COLOR}}. For example, to create the previous figure we added the following lines to the parameter file:
@cartouche
@smallexample
@verbatim
#
# DRAW COMMON MARKER LINKS
#
WITH_COMMON_MARKER=true
COMMON_STROKE_WIDTH=2.0
SINGLE_COMMON_COLOR=808080
POS_COMMON_COLOR=0000ff
NEG_COMMON_COLOR=ff0000
@end verbatim
@end smallexample
@end cartouche
When @b{MMapView} is used to visualize the test of homogeneity between a reference chromosome and several other chromosomes, you can parametrize both the number of bin colors to represent the probabilities and the type of gradient. For example, to create the following figure

@image{fig4,10cm,15cm,,}
@c @caption{Comparive view of two chromosomes. The marker intervals of the rigth chromosome are colored according to the probability that the genetic distance of the marker interval is the same than the genetic distance of the same marker interval in the left chromosome (option @code{--htest} of @b{MMapView}).}

we added the extra parameters:
@cartouche
@smallexample
@verbatim
#
# PROBABILITY GRADIENT
#
PROBA_BIN=20
PROBA_FROM_COLOR=ffffff
PROBA_TO_COLOR=ff0000
@end verbatim
@end smallexample
@end cartouche

This means that the interval between 0 and 1 is divided into 20 intervals and the gradient starts in white (ffffff) and ends in red (ff0000). Note that the probability gradient is represented into the legend box.

@image{fig5,10cm,15cm,,}
@c @caption{Comparive view of two chromosomes. The marker intervals of the rigth chromosome are colored in red if its probability of having the same genetic distance than the marker interval of the left chromosome exceeds the 95% percentile of a chi-square (option @code{--htest} and @code{--hth 0.95} of @b{MMapView}).}

Finally the chromosomes displayed in the figure can be aligned either relatively to the first marker of each chromosome, @code{CHROM_ALIGN_MODE=1}, or relatively to the first common marker between the first chromosome (the left one) and the other ones, @code{CHROM_ALIGN_MODE=0}.

@node MQTLView
@section MQTLView

@b{MQTLView} is designed to depict the result of the QTL clustering for one or several chromosomes on a given map.

@subsection Command Line Options

@multitable @columnfractions 0.2 0.15 0.15 0.5
@headitem Option  @tab Usage    @tab Type    @tab Explanation
@item @code{-m,--map}        @tab required @tab @sc{string}  @tab The XML file for the genetic map.
@item @code{-c,--chrom}      @tab required @tab @sc{string}  @tab The name of the chromosome (or a list separated by comma) to display.
@item @code{-o,--output}    @tab required @tab @sc{string}  @tab The output file stem.
@item @code{-r,--clust}      @tab optional @tab @sc{string}  @tab The file of the clustering result.
@item @code{-b,--best}       @tab optional @tab @sc{string}  @tab The file of the best clustering (only with -c).
@item @code{-t,--tree}       @tab optional @tab @sc{string}  @tab The file of the hierarchical clustering result.
@item @code{--mode}      @tab optional @tab @sc{integer} @tab The mode of representation (0 or 1 and only with -c and -b)
@item @code{--trait}      @tab optional @tab @sc{string}  @tab The name of the trait.
@item @code{-p,--parfile}    @tab optional @tab @sc{string}  @tab The drawing parameter file.
@item @code{--img}        @tab optional @tab @sc{string}  @tab The format of the image (use --help for possible values).
@end multitable

@b{MQTLView} provides several ways to represent the results of the QTL clustering depending on the algorithm used to perform it. Suppose we have first done a clustering using @b{QTLClust} @xref{QTL Clustering, QTLClust}, which produced the result file @file{clust_res.txt}. From the output file @file{clust_model.txt} generated by @b{QTLClust} we have derived the file @file{clust_best.txt} which gives for a given trait the best clustering model for each chromosome (according to a given model choice criterion):
@cartouche
@smallexample
@verbatim
Chromosome      Trait   Model
3       FT      5
10      FT      4
5       FT      4
7       FT      5
2       FT      4
9       FT      2
4       FT      3
8       FT      5
6       FT      3
1       FT      2
@end verbatim
@end smallexample
@end cartouche
Then, we can run @b{MQTLView} to visualize the result, for example on chromosome 8 and 9 together, by invoking the command
@cartouche
@smallexample
@verbatim
%java org.metaqtl.main.MQTLView \
>     -c 8,9 -m map.xml -r clust_res.txt -b clust_best.txt -o figure --img jpeg
@end verbatim
@end smallexample
@end cartouche
By default the figure is created with the mode @code{--mode} 1 which leads to something like that

@image{fig6,15cm,10cm,,}

Now, if you set the option @code{--mode} to @samp{@code{0}}, i.e
@cartouche
@smallexample
@verbatim
%java org.metaqtl.main.MQTLView \
>     -c 8,9 -m map.xml -r clust_res.txt -b clust_best.txt -o figure --img jpeg --mode 0
@end verbatim
@end smallexample
@end cartouche
you will obtain the following representation

@image{fig7,15cm,15cm,,}

where the first bar which follows the name of the QTL corresponds to the relative CI of the QTL (i.e. that the more the bar is filled, the larger the CI is). The second bar gives the membership probabilities of the QTL according to the meta-QTL model.

If the clustering have been done via @b{QTLTree}, the result file obtained @file{tree.txt} can be passed to @b{MQTLView} as follows,
@cartouche
@smallexample
@verbatim
%java org.metaqtl.main.MQTLView \
>     -c 3 -m map.xml -t tree.txt -o figure --img jpeg
@end verbatim
@end smallexample
@end cartouche
In this case @b{MQTLView} draws the tree obtained by the hierarchical clustering procedure as illustrated in the next figure.

@image{fig8,15cm,15cm,,}

Finally the results from @b{QTLClust} and @b{QTLTree} can be visualized together as shown bellow.
@cartouche
@smallexample
@verbatim
%java org.metaqtl.main.MQTLView \
>     -c 3 -m map.xml -r clust_res.txt -b clust_best.txt -t tree.txt -o figure --img jpeg 
@end verbatim
@end smallexample
@end cartouche

@image{fig9,15cm,15cm,,}

