%\VignetteIndexEntry{How to use the mQTL.NMR package}
%\VignetteDepends{mQTL.NMR}
%\VignetteKeywords{normalization, alignment, mQTL mapping, GWAS}
%\VignettePackage{mQTL.NMR}
%\VignetteEngine{utils::Sweave}

\documentclass[12pt]{article}

<<style, eval=TRUE, echo=FALSE, results=tex>>=
BiocStyle::latex()
@

\usepackage{subfigure}
\usepackage{grffile}
\title{How to use mQTL.NMR}
\author{Lyamine Hedjazi}

\begin{document}

\section{How to use {\tt mQTL.NMR package}}

\subsection{Introduction}
mQTL.NMR provides a complete QTL analysis pipeline for 1H-NMR metabolomic data. 
Distinctive features include normalisation using various approaches, peak alignment  
using RSPA approach, dimensionality reduction and mQTL mapping for animal crosses and humans cohorts. We provide 
below an application example showing the use of mQTL.NMR package on 
real-world datasets.

\subsection{Data format}
Raw data files should be formatted according to the targeted type of analysis (mQTL or mGWA analysis). 
However, this step can be skipped if the data files are already 
formatted by the user. In order to format the datafiles into the supported format 
by the mQTL.NMR package (comma-delimited format {\tt csvs}), the format\_mQTL() function 
should be used with the input files in the following format:


\begin{figure}[h]
\centering
\includegraphics[width=15cm]{FilesFormat.png}
\caption{Format datafiles by using format\_mQTL()}
\end{figure}

It is preferable that the user create a new directory to load the demonstration dataset. 
Data files can be formatted as follows:

<<R>>=
# Download raw data files
library(mQTL.NMR)
load_datafiles()
format_mQTL(phenofile,genofile,physiodat,cleandat,cleangen)
@

An example of csvs resulted files are shown below:

\begin{figure}[h]
\centering
\includegraphics[width=15cm]{CSVSFilesFormat.png}
\caption{Datafiles formatted in csvs}
\end{figure} 
  
\subsection{Normalization of metabolomic data}
The mQTL.NMR package implements several approaches to perform the normalization
of metabolomic data. We show below an example of the use of normalisation approache 'constant sum' (CS) 

<<R>>=
# Constant Sum normalization
nmeth<-'CS'
normalise_mQTL(cleandat,CSnorm,nmeth)
@

\subsection{Alignment of metabolomic data}
The mQTL.NMR package uses the Recursive Segment-wise Peak Alignment (RSPA)
approach to align positions of NMR spectral peaks with respect to a 
reference spectrum picked up either automatically or manually.
<<R>>=
align_mQTL(CSnorm,aligdat)
@

\subsection{Dimentionality reduction}
The mQTL.NMR package offers mainly two approaches in order to reduce the number 
of traits considered for genetic mapping analysis: statitical recoupling of variables ("SRV") and binning ("bin") approaches .
An example of using SRV approach is given below:
<<R>>=
met="rectangle" # choose the statistical summarizing measure ("max","sum","trapez",...)
pre_mQTL(aligdat, reducedF, RedMet="SRV",met, corrT=0.9)
@

\subsection{Quantitative trait locus mapping}
The mQTL.NMR package enables association studies for different species, from 
animal crosses to human cohorts. Below an example of mQTL mapping on mouse crosse: 
<<R>>=
results<- list() # a list to stock the mQTL mapping results
nperm<- 0 # number of permutations if required
results<-process_mQTL(reducedF, cleangen, nperm)
@

\subsection{Visualization of results}
mQTL mapping results can be shown in several plots as follows (Figure 1):
<<R>>=
 post_mQTL(results)
@

\begin{figure}
\hfill
\subfigure[3D Profile]{\includegraphics[width=5cm]{3D Profile.png}}
\hfill
\subfigure[Lod for top locus]{\includegraphics[width=5cm]{Lod for top locus.png}}
\hfill
\subfigure[Lod for top shift]{\includegraphics[width=5cm]{Lod for top shift.png}}
\hfill
\subfigure[Zoom on the lod for top shift]{\includegraphics[width=5cm]{Lod for top shift2.png}}
\hfill
\subfigure[2D profile]{\includegraphics[width=5cm]{Full 2D Profile.png}}
\hfill
\subfigure[Lod distribution]{\includegraphics[width=5cm]{Lod distribution.png}}
\hfill
\caption{figures generated by post\_mQTL()}
\end{figure}

\subsection{Summary of results}
A summary of the results can be obtained in a table as follows:
<<R>>=
summary_mQTL(results,rectangle_SRV,T=8)
@

\subsection{Circular genome-metabolome plot}
mQTL.NMR package provides a functionality to visualize the obtained mQTL mapping results.
The user can start first by visualizing the plot of the whole results of mQTL 
mapping. For optimal visualization, the user can then plot the results for 
one or several chromosomes.
<<R>>=
circle_mQTL(results, T=8,spacing=0)
@
<<fig=TRUE ,echo=FALSE >>=
library("graphics")
circle_mQTL(results, T=8,spacing=0)
@

\subsection{Structural assignment and metabolite identification}

mQTL.NMR package provides several visualization tools to help the user
in peak annotation and metabolite identification. In particular, users 
can visualize identified SRV clusters on the chemical shift axe 
and automatically generates a plot showing the top ranked SRV 
cluster in the association study in order to identify the corresponding 
metabolite.

\subsubsection{Plot a region of NMR profiles}
Displays a region of the NMR profiles by specifying a starting 
and ending point
<<R>>=
simple.plot(file=aligdat,lo=3.02,hi=3.08,k=1:60,title="NMR profile")
@ 

<<fig=TRUE ,echo=FALSE >>=
simple.plot(file=aligdat,lo=3.02,hi=3.08,k=1:60,title="NMR profile")
@

\subsubsection{Visualization of SRV clusters}
Displays the NMR profile with the clusters identified by SRV defined 
by horizontal lines on the profile (green=min cluster border, red=max cluster border)
<<R>>=
SRV.plot(file1=aligdat,file2=rectangle_SRV,lo=3.02,hi=3.08,k=1:60,title="Clusters plot")
@
<<fig=TRUE ,echo=FALSE >>=
SRV.plot(file1=aligdat,file2=rectangle_SRV,lo=3.02,hi=3.08,k=1:60,title="Cluster plot")
@

\subsubsection{Top SRV clusters}
Generates the plot of SRV cluster corresponding to the top association score 
with the two right and left clusters to be used for metabolite identification
<<R>>=
Top_SRV.plot(file1=aligdat,file2=rectangle_SRV,results=results,met=met,intMeth="mean")
@

<<fig=TRUE ,echo=FALSE >>=
Top_SRV.plot(file1=aligdat,file2=rectangle_SRV,results=results,met=met,intMeth="mean")
@

<<R>>=
SRV_lod.plot(results,rectangle_SRV,T=1)
@
<<fig=TRUE ,echo=FALSE >>=
SRV_lod.plot(results,rectangle_SRV,T=1)
@

The manual page on \Rfunction{mQTL.NMR} has a number of
additional examples that show how applicable functions
can be used.

\section{Session Information}

The version number of R and packages loaded for generating the vignette were:

\begin{verbatim}
<<echo=FALSE,results=tex>>=
sessionInfo()
@
\end{verbatim}

\end{document}