Commit 3a6d24f3 authored by Damien Leroux's avatar Damien Leroux
Browse files

Tweaked the user manual a bit.

parent 0837fa5b
......@@ -176,7 +176,7 @@ add_manpage(spell-qtl.1)
add_manpage(spell-qtl-examples.1)
add_custom_target(user_manual.pdf ALL COMMAND ./build_manual.sh ${CMAKE_BINARY_DIR} ${CMAKE_SOURCE_DIR} WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/deploy)
add_dependencies(user_manual.pdf spell-pedigree spell-marker spell-qtl)
add_dependencies(user_manual.pdf spell-pedigree spell-marker spell-qtl manpages)
#add_custom_command(OUTPUT spell-marker.1
# COMMAND pandoc -t man ${CMAKE_SOURCE_DIR}/doc/man/spell-marker.1.md -o spell-marker.1
......
......@@ -69,20 +69,20 @@ General output directory organization is :
\begin{itemize}
\item A common working directory must be set for all 3 executables using command line option \texttt{-wd my\_directory} or \texttt{--work-directory my\_directory}. Every result produced during analysis will be directed to this directory.
\item A configuration name using command line option \texttt{-n my\_name} or \texttt{--name my\_name} is used to name subdirectories.
\item Parental Origin Probabilities are output as CSV files
\item A common working directory must be set for all 3 executables using the commandline option \texttt{-wd my\_directory} or \texttt{-{}-work-directory my\_directory}. Every result produced during analysis will be output into this directory.
\item A configuration name using commandline option \texttt{-n my\_name} or \texttt{-{}-name my\_name} is used to prefix the subdirectories and output files.
\item Parental Origin Probabilities are output as CSV files:
\begin{description}
\item [1-point] one file per marker (with pedigree like structure), use option \texttt{-O1} in command \texttt{spell-marker} to output these files
\item [n-point] one file per linkage group per generation per individual, use model option \texttt{output-nppop} in command \texttt{spell-qtl} to output these files.
\item [1-point] one file per marker (with pedigree-like structure). Use option \texttt{-O1} in command \texttt{spell-marker} to output these files.
\item [n-point] one file per linkage group per generation per individual. Use option \texttt{output-nppop} in command \texttt{spell-qtl} to output these files.
\end{description}
\item a report containing
\item A report containing:
\begin{itemize}
\item A text-mode file rendering of the genetic map with the detected QTLs and their confidence interval
\item The model matrix ans the variance-covariance matrix for each selection the detection algorithm used
\item The detailed final model including variance-covariance matrix, coefficients, contrasts and contrasts significance
\item A text-mode rendering of the genetic map with the detected QTLs and their respective confidence intervals,
\item The model matrix and the variance-covariance matrix for each selected set of loci used by the detection algorithm,
\item The detailed final model including variance-covariance matrix, coefficients, contrasts, and contrasts significance.
\end{itemize}
\item some hidden files with cached computation results.
\item A cache of intermediate computation results.
\end{itemize}
\section{Output files samples}
......@@ -93,7 +93,7 @@ General output directory organization is :
linerange={1-12,107-112}
]{my_directory/my_name.1-point/my_name.pedigree-and-probabilities.M_1_1.csv}
Note that you must use \texttt{-01} command line option in \texttt{spell-marker} in order to generate these files (see \vref{spell-marker:output-modes}.)
Note that you must use the \texttt{-O1} commandline option in \texttt{spell-marker} in order to generate these files (see \vref{spell-marker:output-modes}.)
\subsection{n-point POP}
\lstinputlisting[numbers=left,
......@@ -102,29 +102,29 @@ Note that you must use \texttt{-01} command line option in \texttt{spell-marker}
]
{output_files/my_name.ch1.F2.0.csv}
Note that you must use \texttt{output-nppop} processing option in \texttt{spell-qtl} in order to generate these files (see \vref{spell-qtl:processing-options}.)
Note that you must use the \texttt{output-nppop} processing option in \texttt{spell-qtl} in order to generate these files (see \vref{spell-qtl:processing-options}.)
\subsection{full map}
The special text file named \texttt{full\_map.txt} is produced at the root of \texttt{my name.report} directory. The full genetic map is drawn using text characters. Any detected QTL (for any trait under study) is inserted in this map with its confidence interval (figure \vref{fig:full-map}).
The special text file named \texttt{full\_map.txt} is produced at the root of the \texttt{my name.report} directory. The full genetic map is drawn using text characters. Any detected QTL (for any trait under study) is inserted in this map with its confidence interval (figure \vref{fig:full-map}).
\begin{figure}[h]
\includegraphics[width=1.0\textwidth]{full_map.png}
\caption{screen capture of \texttt{less -RS full\_map.txt} in a \textit{ad hoc} resized terminal. Chromosome names are printed light blue. The chromosome and markers names are white. The found QTL and its confidence interval are added in green labeled with trait name (\texttt{t1}), \texttt{@}, QTL position (\texttt{135.34}) and confidence interval (\texttt{[129.246:140.84]})}
\caption{screen capture of \texttt{less -RS full\_map.txt} in an \textit{ad hoc} resized terminal. Chromosome names are printed in light blue. The chromosome and the marker names are in white. The detected QTL and its confidence interval are added in green, labeled with trait name (\texttt{t1}), \texttt{@}, QTL position (\texttt{135.34}) and confidence interval (\texttt{[129.246:140.84]})}
\label{fig:full-map}
\end{figure}
Note that you must use \texttt{cat} or \texttt{less -RS} command in ordrer to see it properly. \texttt{more} command, \texttt{less} command or your favorite text editor may fail to read special characters.
Note that you must use the \texttt{cat} or \texttt{less -RS} command in order to see it properly. \texttt{more} command, \texttt{less} command or your favorite text editor may fail to read special characters.
\subsection{Trait by trait reports}
For every trait under analysis, a report directory is generated (this directory name is the trait name). Whithin this directoty the report file itself is named after the trait name followed by \texttt{\_report.txt}
For every trait under analysis, a report directory is generated (this directory name is the trait name). Within this directory the report file itself is named after the trait name followed by \texttt{\_report.txt}
This file is divided in several parts. For the sample file \vref{sample:report} they are :
\begin{description}
\item[General information (lines 1-7)] Trait name and what was detected (QTLs positions and confidence intervals)
\item[R2 (lines 12-20)] Part of the variance explained by each QTL
\item[Coefficients (lines 22-54)] Cross effects and QTLs allele effects are displayed with their estimated vairiance-covariance matrix
\item[Contrasts (lines 57-79 and 81-103)] Any tractable contrast is computed and its significance tested. \texttt{spell-qtl} displays a contrasts section for every comparable effects group.
\item[Contrasts (lines 57-79 and 81-103)] Spell-QTL computes all tractable contrasts and tests their significances. Spell-QTL displays a contrasts section for each comparable effect group.
\item[Final Model (lines 105-325)] The final linear model for this detection is then displayed in human readable form. (It is available in computer readable form in files \texttt{trait\_values.txt} and \texttt{Model\_*X.txt})
\item[Final Model inversion (lines 328-351)] $(X^tX)^{-1}$ matrix from linear model solving in human readable form. (It is available in computer readable form in file \texttt{Model\_*\_XtX\_inv.txt}).
\end{description}
......
......@@ -18,19 +18,19 @@ A minimal session for Spell-QTL analysis is 3 commands long. For an example to r
\item \texttt{spell-qtl -wd my\_directory -n my\_name -P auto -p F2 example1\_F2.phen -p F2C example1\_F2C.phen -gm example1.map}
\end{itemize}
If you want to duplicate these commands, you must check that the input files are available to the programs. You may want to copy them in your test directory, or use an absolute or relative path in you command line.
If you want to duplicate these commands, you must check that the input files are available to the programs. You may want to copy them into your test directory, or use an absolute or relative path in your command lines.
\section{Software suite details}
\subsection{\texttt{spell-pedigree}}
\begin{itemize}
\item Computes the transition matrices for the Continuous Time Hidden Markov Models (CTHMM). They are the $T_d$ matrices in formula \vref{eq:pop}. The number of hidden states is of course the order of the matrix.
\item Computes the transition matrices for the Continuous Time Hidden Markov Models (CTHMM). They are the $T_d$ matrices in formula \vref{eq:pop}. %The number of hidden states is of course the order of the matrix.
\item These computations are inherently dependent, so it can only run sequentially.
\item Outputs a data file that can be fed to \texttt{spell-marker}.
\end{itemize}
\subsection{\texttt{spell-marker}}
\begin{itemize}
\item Computes the 1-point Parental Origins Probabilities by Bayesian inference for all markers.
\item Computes the 1-point Parental Origins Probabilities using Bayesian Inference at each marker.
\item Each marker is independent, so it can run in various ways:
\begin{itemize}
\item Sequentially,
......@@ -39,7 +39,7 @@ If you want to duplicate these commands, you must check that the input files are
\item Sending jobs to remote machines via \texttt{ssh}
\end{itemize}
\item Outputs a data file that can be fed to \texttt{spell-qtl}.
\item Can also output the raw Parental Origin Probabilities.
\item Can also output the raw (1-point) Parental Origin Probabilities.
\end{itemize}
\subsection{\texttt{spell-qtl}}
\begin{itemize}
......@@ -82,7 +82,7 @@ Note that: \begin{itemize}
Build in allele code are :
\begin{description}
\item[02] SNP observations, where 0 and 2 are homozygous and 1 is heterozygous. These observations type are relevant for any individual in the pedigree, including parents. \texttt{spell-marker} will then perform inference of possible genotypes and inference of possible states in the CTHMM.
\item[ABHCD] MapMaker like Parental Origin inferred observations. These are relevant for inbred lines crosses products. Let's consider the cross $A|A \times B|B$:
\item[ABHCD] MapMaker-like Parental Origin inferred observations. These are relevant for inbred lines crosses products. Let's consider the cross $A|A \times B|B$:
\begin{itemize}
\item The child is typed A and the allele A is not dominant. The only possible genotype is $A|A$. This is encoded by the character \texttt{ A} in MapMaker.
\item The child is typed A and the allele A is dominant. The possible genotype are $A|A$, $A|B$ and $B|A$. This is encoded by the character \texttt{ D} in MapMaker.
......
......@@ -74,21 +74,20 @@ basicstyle=\ttfamily
\chapter*{Foreword}
\paragraph{} Spell-QTL
is a software suite allowing to detect QTLs in any crossing design. Spell acronym is for {\em Species Perscrutandis Enixe Locis Locabutur}. This means {\em The characters will be localized using an zealous loci inspection}, the very purpose of the software. If you read this manual, you already know what QTL stands for.
\paragraph{} Spell-QTL is a software suite allowing to detect QTLs in any crossing design. Spell is an acronym that stands for {\em Species Perscrutandis Enixe Locis Locabutur}. This means {\em The characters will be localized by zealously inspecting the loci}, the very purpose of the software. If you are reading this manual, you already know what QTL stands for.
We - Damien Leroux and Sylvain Jasson - are developping Spell-QTL at MIAT, a research lab from INRA French National Institute for Agricultural Research. We are located near Toulouse, in the French Occitanie region.
We---Damien Leroux and Sylvain Jasson---are developping Spell-QTL at MIAT, a research lab from INRA French National Institute for Agricultural Research. We are located near Toulouse, in the French Occitanie region.
\paragraph{} When the project started, we were just planning to rewrite our legacy code MCQTL, using modern C++. After decades of development and many contributors - most of them not even reachable - MCQTL had reached the stage of "Hydra code": every bug correction, every improvement was made at very high cost.
\paragraph{} When the project started, we were just planning to rewrite our legacy code MCQTL, using modern C++. After decades of development and many temporary contributors---most of them not even reachable---MCQTL was in a stage of ``Hydra code'': every bug correction, every improvement had a very high cost.
As the project was moving forward, and as we were thinking it would be a quick and easy release, we discover that some hypothesis that were made in MCQTL, were no mode valid with dealing with modern crosses (MAGIC, AIC...)
As the project was moving forward, and as we were thinking it would be a quick and easy release, we discovered that some hypotheses that were made in MCQTL, were no more valid when dealing with modern crosses (MAGIC, AIC...)
This work switched from engineering project to research project inadvertently, and we are very happy about that !
This work switched inadvertently from an engineering project to a research project, and we are very happy about that!
\paragraph{} Both the software and this manual are work under progress: feed-back is welcome and appreciated.
\paragraph{} Both the software and this manual are works in progress: feedback is welcome and appreciated.
\vspace*{\fill}
\noindent Spell-QTL is available at \url{https://mulcyber.toulouse.inra.fr/frs/?group_id=204} under Gnu Public License.
\noindent Spell-QTL is available at \url{https://mulcyber.toulouse.inra.fr/frs/?group_id=204} under the Gnu Public License.
\begin{center}
\includegraphics[clip, trim=0.5cm 7.9cm 0.5cm 14cm,width=0.25\columnwidth]{pdfs/gpl-v3-logo}
\end{center}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment