\documentclass[10pt,twoside,a4paper]{article}
\usepackage{pslatex,palatino,avant,graphicx}
\usepackage[usenames,dvipsnames]{color}
\usepackage[margin=2cm]{geometry}
\usepackage{url}
\usepackage[square,sort]{natbib}

\usepackage{listings}
\lstset{ %
  backgroundcolor=\color{white},   % choose the background color; you must add \usepackage{color} or \usepackage{xcolor}
  basicstyle=\footnotesize,        % the size of the fonts that are used for the code
  breakatwhitespace=false,         % sets if automatic breaks should only happen at whitespace
  breaklines=true,                 % sets automatic line breaking
  captionpos=b,                    % sets the caption-position to bottom
  commentstyle=\color{LimeGreen},  % comment style
  % deletekeywords={...},            % if you want to delete keywords from the given language
  escapeinside={\%*}{*)},          % if you want to add LaTeX within your code
  extendedchars=true,              % lets you use non-ASCII characters; for 8-bits encodings only, does not work with UTF-8
  frame=single,                    % adds a frame around the code
  keepspaces=true,                 % keeps spaces in text, useful for keeping indentation of code (possibly needs columns=flexible)
  keywordstyle=\color{BlueGreen},  % keyword style
  % language=Java,                   % the language of the code
  % numbers=left,                    % where to put the line-numbers; possible values are (none, left, right)
  % numbersep=5pt,                   % how far the line-numbers are from the code
  % numberstyle=\tiny\color{Gray},   % the style that is used for the line-numbers
  rulecolor=\color{black},         % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here))
  showspaces=false,                % show spaces everywhere adding particular underscores; it overrides 'showstringspaces'
  showstringspaces=false,          % underline spaces within strings only
  showtabs=false,                  % show tabs within strings adding particular underscores
  stepnumber=2,                    % the step between two line-numbers. If it's 1, each line will be numbered
  stringstyle=\color{RubineRed},   % string literal style
  tabsize=2,                       % sets default tabsize to 2 spaces
  title=\lstname,                  % show the filename of files included with \lstinputlisting; also try caption instead of title
  aboveskip=1em,
  belowcaptionskip=0em,
  belowskip=0em
}

\usepackage{hyperref}
\hypersetup{
    colorlinks,
    citecolor=Violet,
    filecolor=black,
    linkcolor=MidnightBlue,
    urlcolor=MidnightBlue
}

\begin{document}
\providecommand{\versionnumber}{0.1.10}
\title{jModelTest 2 Manual v\versionnumber}
\author{Diego Darriba, David Posada}
\date{}
\maketitle

\setcounter{tocdepth}{2}
\tableofcontents

\clearpage

\section{Overview}

jModelTest is a tool to carry out statistical selection of best-fit models of nucleotide substitution. It implements five different model selection strategies: hierarchical and dynamical likelihood ratio tests (hLRT and dLRT), Akaike and Bayesian information criteria (AIC and BIC), and a decision theory method (DT). It also provides estimates of model selection uncertainty, parameter importances and model-averaged parameter estimates, including model-averaged tree topologies. jModelTest 2 includes High Performance Computing (HPC) capabilities and additional features like new strategies for tree optimization, model-averaged phylogenetic trees (both topology and branch lenght), heuristic filtering and automatic logging of user activity.

\subsection{Download}

The main project webpage is located at GitHub: \url{https://github.com/ddarriba/jmodeltest2}.

New distributions of jModelTest will be hosted in GitHub releases and google drive.
\begin{itemize}
  \item \url{https://github.com/ddarriba/jmodeltest2/releases}
  \item \url{https://drive.google.com/folderview?id=0ByrkKOPtF_n_OUs3d0dNcnJPYXM#list}
\end{itemize}

Please use the jModelTest discussion group for any question: 
\begin{itemize}
  \item \url{http://groups.google.com/group/jmodeltest}.
\end{itemize}

\subsection{Citation}

When using jModelTest you should cite all these:

\begin{itemize}
\item Darriba D, Taboada GL, Doallo R, Posada D. 2012. jModelTest 2: more models, new heuristics and parallel computing. Nature Methods 9(8), 772.
\item Guindon S and Gascuel O (2003). A simple, fast and accurate method to estimate large phylogenies by maximum-likelihood". Systematic Biology 52: 696-704. 
\end{itemize}

\subsection{Disclaimer}

{\footnotesize
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. The jModelTest distribution includes Phyml executables.

These programs are protected by their own license and conditions, and using jModelTest implies agreeing with those conditions as well. 
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

{\footnotesize
\include{changelog}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\include{sec-quickstart}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Graphical User Interface}
\label{sec:gui}

\subsection{Launching the Graphical User Interface}

The main distribution includes a script for launching the interface,  \emph{runjmodeltest-gui.sh}, located under the jModelTest home folder. Other possibility is running the following command line:

\begin{lstlisting}
$ java -jar jModelTest.jar
\end{lstlisting}

Moreover, in Windows and MacOS X, it is often possible to double-click the jModelTest.jar file to launch the graphical interface.

The following window will show on the screen:

\begin{center}
\includegraphics[width=.9\textwidth]{images/main-window}
\end{center}

\subsection{Menu description}

\begin{minipage}{1\textwidth}
\small
\begin{tabular}{l l l l}
\hline
{\bf Menu} & {\bf Submenu} & {\bf Description} & {\bf Enabled} \\
\hline
File \\
& Load alignment & Load an input alignment & \\
& Load checkpoint file & Load a previous snapshot \footnote{See Section~\ref{sec:ckp}} & (i) \\
& Quit & Exit the program & \\
\hline
Analysis \\
& Compute likelihood scores & Optimize the set of candidate models & (i) \\
& Do AIC calculations & Calculate Akaike Information Criterion & (ii) \\
& Do BIC calculations & Calculate Bayesian Information Criterion & (ii) \\
& Do DT calculations & Calculate Decision Theory & (ii) \\
& Do hLRT calculations & Calculate hierarchical likelihood ratio test & (ii) \footnote{This test is only available for 3,5,7 and 11 substitution schemes and for fixed topologies (fixed BIONJ-JC tree or user-defined topology)} \\
& Model-averaged phylogeny & Calculate the consensus tree & (iii \& iv)  \\
\hline
Results \\
& Show results table & Show a table with the selection results & (ii) \\
& Build HTML log & Create an html webpage with the results & (ii) \\
\hline
Tools \\
& LRT calculator & Likelihood Ratio Test for nexted models & \\
\hline
\end{tabular}

\vspace{1em}
(i) After loading an alignment (ii) After computing the likelihood scores (iii) If the base tree is not fixed (iv) After calculating an Information Criterion
\end{minipage}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\include{sec-arguments}
\include{sec-config}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Common Use Cases}

\subsection{Converting Alignment Files}

jModelTest accepts several input alignment file formats. However, it makes use of the ALTER library for converting them into PHYLIP format, accepted by PhyML. If you want to validate your alignment, you can convert it into PHYLIP format using the ``-getPhylip'' argument. It will generate a new file appending ``.phy'' to the input alignment filename, and exit afterwards.

\begin{lstlisting}
$ java -jar jModelTest -d example-data/aP6.fas -getPhylip
\end{lstlisting}

In case there is something wrong in the input file, it will exit with the description of the error.

\subsection{Basic Model Selection}

Although jModelTest have many options, most of the users would like to perform a model selection among the 11 substitution schemes, including models with unequal frequencies, gamma rate variation and a proportion of invariable sites. The following command produces this operation, shows the selection results under the 4 available criteria, computes the model-averaged phylogenies (``-a''), computes the parameters importance (``-v'' and ``-p'') and writes the PAUP* block for the best-fit models (``-w''):

\begin{lstlisting}
$ java -jar jModelTest -d example-data/aP6.fas -s 11 -f -i -g 4 -AIC -BIC -AICc -DT -p -a -w
\end{lstlisting}

Note that, by default, jModelTest uses Maximum-Likelihood topologies as the base trees for the model optimization, and checks both NNI and SPR algorithms for the topology search. This obtains the most accurate results, but it is also the most time consuming operation. According to the size of the input alignment, one can directly select one of the algorithms saving time in the computations. As a general rule, for a small number of taxa NNI algorithm would work better, as well as SPR is more suitable for a large number of taxa. The tree search operation can be set with ``-S'' argument (e.g., -t ML -S NNI).

\subsection{Loading Checkpointing Files}
\label{sec:ckp}

By default, jModelTest saves ``.ckp'' checkpointing files in the log directory. In case of an error occurs, the user can start again the process minimizing the loss of computation. The user is in charge of selecting the checkpointing file and running again jModelTest with the same parameters of the previous execution. Otherwise the results might be wrong.

For finding the correct checkpointing file, if the execution had a user-defined name ``-n argument'', the checkpoing file will have the following format: 

\begin{lstlisting}
log/[sequenceFileName].[executionName].ckp
\end{lstlisting}

For example, the following command:

\begin{lstlisting}
$ java -jar jModelTest -d example-data/aP6.fas -n myTest -s 11 -f -i -g 4 -BIC -AIC
\end{lstlisting}

Will generate the checkpointing file in \$JMODELTEST\_HOME/log/aP6.fas.myTest.ckp, and in case of a sudden error in the execution, it can be continued using:

\begin{lstlisting}
$ java -jar jModelTest -d example-data/aP6.fas -n myTest -s 11 -f -i -g 4 -BIC -AIC -ckp log/aP6.fas.myTest.ckp
\end{lstlisting}

If no execution name was provided, it is automatically generated according to the current date and time with the following format: yyyyMMddhhmmss (e.g., if current time is 17:05:00 August 3 2014, the execution name is 20140803170500, and the checkpointing generated file is:

\begin{lstlisting}
log/[sequenceFileName].20140803170500.ckp).
\end{lstlisting}

When using the GUI instead of the command console interface, the checkpointing file can be loaded using the menu item ``File/Load checkpoint file'', that becomes enabled right after loading the alignment.

% \subsection{Finding the Best-fit Model for MrBayes Analysis}

% One common question is how to set the best-fit model obtained with jModelTest into MrBayes. The 3 substitution schemes option covers those models implemented in MrBayes. From the command console, the 3 substitution schemes mode is selected by default, so just make sure you are not modifying it with the ``-s'' argument.

From the GUI, one can choose between the different number of the substituion schemes in the execution settings window.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\include{sec-theory}


%\bibliographystyle{natbib}
%\bibliographystyle{achemnat}
\bibliographystyle{plainnat}
%\bibliographystyle{abbrv}
%\bibliographystyle{bioinformatics}
%\bibliographystyle{plain}
\bibliography{biblio}

\end{document}