%\VignetteIndexEntry{Add a new distribution to the GAS package}
%\VignetteKeywords{GAS}
%\VignettePackage{GAS}
\documentclass[12pt,english]{article}
\usepackage{mathptmx}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{geometry}
\geometry{verbose,tmargin=2.5cm,bmargin=2.5cm,lmargin=2.5cm,rmargin=2.5cm,headheight=2.5cm,headsep=2.5cm}
\synctex=-1
\usepackage{amsmath}
\usepackage{setspace}
\onehalfspacing

\makeatletter
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
\numberwithin{equation}{section}

\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
\newcommand\code{\bgroup\@makeother\_\@makeother\~\@makeother\$\@codex}
\def\@codex#1{{\normalfont\ttfamily\hyphenchar\font=-1 #1}\egroup}
\let\proglang=\textsf
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands. 
\usepackage{hyperref}
\date{}

\makeatother

\usepackage{babel}
\begin{document}

\section*{Add a new distribution to the GAS package}

This short note illustrates how to add a new distribution in the \pkg{GAS} package. Changes have to be made in the \code{.R} files inside the R folder and in the \code{.cpp} and \code{.h} files inside the src folder of the package tarball, respectively.\\
%
The following guidelines apply when:
%
\begin{itemize}
  \item[1] You want to add an univariate distribution.
  \item[2] Your distribution has maximum 5 parameters.
\end{itemize}
%
If you want to add a multivariate distribution, most of the following points apply as well. However, additional changes have to be included in order to have a proper implementation. You can email the package maintainer for possible inclusion of your multivariate distribution in the package. \\
%
Changes with regards to \proglang{R} files are:
\begin{itemize}
  \item[1] \code{Distribution.R} : \code{DistLabels()}, \code{DistName()}, \code{DistNote()}, \code{DistReference()}, \code{DistParameters()}, \code{DistType()}, \code{DistScalingType()}.
  
  \item[2] \code{ParameterConstraints.R}: include the possible constraints to the parameters dynamic. Look at the function \code{GetFixedPar\_Uni()} and \code{GetFixedPar\_Multi()} for univariate and multivariate distributions, respectively.
  
  \item[3] \code{ParNames.R} : \code{FullNamesUni()}. Choose the labels for the parameters of the distribution between : \code{"location"}, \code{"scale"}, \code{"skewness"}, \code{"shape"} and \code{"shape2"}. These are only names, \emph{i.e.}, the label \code{"location"} does not necessarily represent a location parameter.
      
  \item[4] \code{StartingValue.R} : \code{StaticStarting\_Uni()}. Use Method of Moments when possible. If you want to add a multivariate distribution, you need to create a new function \code{StartingValues_dist()} and link to the \code{MultiGAS_Starting()} function. Note that, in the multivariate case, the output of the new  \code{StartingValues_dist()}, needs to be consistent with that of, for example, of \code{StartingValues_mvt()}.
\end{itemize}
%
Assuming that the label of the new distribution is \code{"poi"}. Changes with regards to the \proglang{C++} files are:
\begin{itemize}
  \item[1] Create \code{poi.cpp} with the functions:
  \begin{itemize}
    \item \code{double dPOI()} , probability density function : it accepts the additional \code{boolean} argument: \code{bLog}, by default \code{bLog = false}. 
    \item \code{double pPOI()}, cumulative density function.
    \item \code{double qPOI()}, quantile function.
    \item \code{double rPOI()}, random generator.
    \item \code{arma::vec mPOI()}, it returns an \code{arma::vec} with 4 entries containing: the mean, the variance, the skewness coefficient, the kurtosis coefficient (not excess of kurtosis).
    \item \code{arma::vec poi\_Score()}, score function.
    \item \code{arma::mat poi\_IM()}, information matrix. If the information matrix is not available, then the output of \code{arma::mat poi\_IM()} is the identity matrix of dimension equal to the number of parameters.
  \end{itemize}
  
  All the function of poi.cpp accept \code{double} arguments, expect \code{poi\_Score()} and \code{poi\_IM()} that accept an \code{arma::vec} argument. See, for example, the file \code{std.cpp} .
  
  \item[2] Create the header \code{poi.h} with all the functions in \code{poi.cpp} .
  
  \item[3] Modify \code{DistWrap.cpp} to include \code{poi.h}, add \code{if (Dist == "poi")} to all the functions.
  
  \item[4] Modify \code{IMWrap.cpp} to include \code{poi.h}, add \code{if (Dist == "poi")} to \code{arma::mat IM\_univ()}.
  
  \item[5] Modify \code{Mapping.cpp}, the functions : \code{MapParameters\_univ()}/\code{MapParameters\_multi()}, \code{UnmapParameters\_univ()}/\code{UnmapParameters\_multi()},\code{MapParametersJacobian\_univ()}/ \code{MapParametersJacobian\_multi()}. Use the same structure of the other distributions. If necessary, create global variables as \code{const double dLowerShape} and \code{const double dUpperShape} to determine the numerical upper and lower bounds for your parameters. You can use the modified logistic mapping function transformation (\code{double Map()}), its inverse (\code{double Unmap()}) and its derivative (\code{double MapDeriv()}).
      
  \item[6] Modify \code{ScoreWrap.cpp} to include \code{poi.h} : add \code{if (Dist == "poi")} to \\\code{arma::vec Score\_univ()}/\code{arma::vec Score\_multi()}. 
  
  \item[7] Modify \code{Utils.cpp}, functions : \code{int NumberParameters()} which returns an integer indicating the number of parameters of your distribution.   
\end{itemize}

If everything have been done correctly you can now compile the package through \code{R CMD BUILD} and use all the package functionalities.
\end{document}