\documentclass{article}
% sweave commands for vignette
%\VignetteIndexEntry{Fit parametric distributions on non-censored or censored data}
%\VignettePackage{fitdistrplus}
%\VignetteKeyword{distribution}

%%%
%%% TITLE:       fitdistrplus: an R Package for Fitting Distributions 
%%% AUTHORS:     Marie Laure Delignette Muller*, Christophe Dutang
%%%              * Corresponding author
%%% AFFILIATION: LBBE, Université Claude Bernard Lyon 1, Lyon, France
%%% ADDRESS:     VetAgro Sup Campus Vétérinaire de Lyon
%%%              1, avenue Bourgelat
%%%              69820 MARCY L'ETOILE, France
%%% PHONE:       +33 4 78 87 27 40
%%% FAX:         +33 4 78 87 27 12
%%% EMAIL:       marielaure.delignettemuller@vetagro-sup.fr
%%%



\usepackage{amsmath,amsthm,amssymb}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
%\usepackage[english]{babel}
%% need no 
\usepackage{Sweave}

\usepackage{color, graphics}
\usepackage[a4paper, textwidth=18cm, textheight=27cm]{geometry}

\newcommand{\sigle}{\textsc}
\newcommand{\pkg}{\textbf} %defined in jss.cls
\newcommand{\code}{\texttt} %defined in jss.cls
\newcommand{\proglang}{\textsf} %defined in jss.cls

%layout
\newcommand{\HRuleTop}{\noindent\rule{\linewidth}{.5pt}}
\newcommand{\HRuleBottom}{\rule{\linewidth}{.5pt}}


\usepackage{natbib,url}
%\usepackage[hyperfootnotes=false]{hyperref}

  
\author{ Marie Laure Delignette-Muller \\ Universit\'e de Lyon\\
    Christophe Dutang \\ Universit\'e de Strasbourg}
%\Plainauthor{Marie Laure Delignette-Muller}

\title{\pkg{fitdistrplus}: An \proglang{R} Package for Fitting Distributions}
%\Plaintitle{fitdistrplus: an R Package for Fitting Distributions}

\date{October 2014\footnote{Paper accepted in the Journal of Statistical Software}}

%quantile matching, maximum goodness-of-fit, distributions, R}

%% publication information
%% NOTE: Typically, this can be left commented and will be filled out by the technical editor
%% \Volume{50}
%% \Issue{9}
%% \Month{June}
%% \Year{2012}
%% \Submitdate{2012-09-04}
%% \Acceptdate{2012-09-04}

% \Address{
%     Marie Laure Delignette-Muller \\
%     Universit\'e de Lyon\\
%     Universit\'e Lyon 1, CNRS, UMR5558, Laboratoire de Biom\'etrie et Biologie \'evolutive\\
%     VetAgro Sup, Campus V\'et\'erinaire de Lyon \\
%     1, avenue Bourgelat \\
%     69820 MARCY L'ETOILE\\
%     France \\
%     E-mail: \email{marielaure.delignettemuller@vetagro-sup.fr} \\
%     URL: \url{http://lbbe.univ-lyon1.fr/-Delignette-Muller-Marie-Laure-.html}
% }


% \newcommand{\Sconcordance}[1]{%
%   \ifx\pdfoutput\undefined%
%   \csname newcount\endcsname\pdfoutput\fi%
%   \ifcase\pdfoutput\special{#1}%
%   \else%
%    \begingroup%
%      \pdfcompresslevel=0%
%      \immediate\pdfobj stream{#1}%
%      \pdfcatalog{/SweaveConcordance \the\pdflastobj\space 0 R}%
%    \endgroup%
%   \fi}


\begin{document}
\SweaveOpts{concordance=TRUE}

\maketitle

\begin{abstract}%
    \HRuleTop\\
    The package \pkg{fitdistrplus} provides functions for fitting univariate distributions
to different types of data (continuous censored or non-censored data and discrete data) and allowing
different estimation methods (maximum likelihood, moment matching, quantile matching
and maximum goodness-of-fit estimation).
Outputs of \code{fitdist} and \code{fitdistcens} functions are S3 objects, for
which kind generic methods are provided, including \code{summary}, \code{plot} and
\code{quantile}. 
This package also provides various functions to compare the fit of several distributions to a same data set 
and can handle bootstrap of parameter estimates.
Detailed examples are given in food risk assessment, ecotoxicology and insurance contexts.\\
\HRuleBottom
\end{abstract}

\textit{Keywords}: {probability distribution fitting, bootstrap, censored data, maximum likelihood, moment matching, 
quantile matching, maximum goodness-of-fit, distributions, \proglang{R}}
%\Plainkeywords{probability distribution fitting, bootstrap, censored data, maximum likelihood, moment matching, 




%, prefix.string=figs/jss

%% include your article here, just as usual
%% Note that you should use the \pkg{}, \proglang{} and \code{} commands.



\section{Introduction}
\label{Introduction}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



Fitting distributions to data is a very common task in statistics and consists in choosing
a probability distribution modelling the random
variable, as well as finding parameter estimates for that distribution. 
This requires judgment and expertise and generally needs an iterative process of
distribution choice, parameter estimation, and quality of fit assessment.
In the \proglang{R} \citep{R13} package \pkg{MASS} \citep{MASS}, maximum likelihood estimation 
is available via the \code{fitdistr} function; other steps of the
fitting process can be done using other \proglang{R} functions \citep{Ricci05}. 
In this paper, we present the \proglang{R} package \pkg{fitdistrplus} \citep{fitdistrplus}
implementing several methods for fitting univariate parametric distribution.
A first objective in developing this package was to provide \proglang{R} 
users a set of functions dedicated to help this overall process.


The \code{fitdistr} function estimates distribution parameters by maximizing the likelihood
function using the \code{optim} function. 
No distinction between parameters with different roles (e.g., main parameter and nuisance parameter)
is made, as this paper focuses 
on parameter estimation from a general point-of-view. 
In some cases, other estimation methods could be prefered, 
such as maximum goodness-of-fit estimation (also called minimum distance estimation), as
proposed in the \proglang{R} package \pkg{actuar} with three different goodness-of-fit distances
\citep{actuarJSS}. 
While developping  the \pkg{fitdistrplus} package, a second objective  was to consider 
various estimation methods in addition to maximum likelihood estimation (MLE). Functions
were developped to enable moment matching estimation (MME), quantile matching estimation (QME), and 
maximum goodness-of-fit estimation (MGE) using eight different distances.
Moreover, the \pkg{fitdistrplus} package offers the possibility to specify a user-supplied function
for optimization, 
useful in cases where classical optimization techniques, not included in \code{optim}, are more adequate.

In applied statistics, it is frequent to have to fit distributions to censored data \citep{kleinmoeschberger03,
helsel05,busschaertetal10,lehaetal11,commeauetal12}. 
The \pkg{MASS} \code{fitdistr} function 
does not enable maximum likelihood estimation with this type of data. Some packages 
can be used to work with censored data, especially survival data \citep{survival,hiranoetal94,jordan05},
but those packages generally focus on specific models, enabling the fit of  a 
restricted set of distributions. 
A third objective is thus to provide \proglang{R} users a function 
to estimate univariate distribution parameters from right-, left- and interval-censored data. 

Few packages on \sigle{CRAN} provide estimation procedures for any user-supplied parametric distribution 
and support different types of data. 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The \pkg{distrMod} package \citep{distrModJSS} provides an object-oriented (S4)  
implementation of probability models and includes distribution fitting procedures  
for a given minimization criterion. 
This criterion is a user-supplied function 
which is sufficiently flexible to handle censored data, yet not in a trivial way,
see Example M4 of the \pkg{distrMod} vignette.
The fitting functions \code{MLEstimator} and \code{MDEstimator} return an S4 class 
for which a coercion method to class mle is provided so that the respective 
functionalities (e.g., \code{confint} and \code{logLik}) from package \pkg{stats4} 
are available, too.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
In \pkg{fitdistrplus}, we chose to use the standard S3 class system for its understanding by most \proglang{R} users.
When designing the \pkg{fitdistrplus} package, we did not forget to implement
generic functions also available for S3 classes.
Finally, various other packages provide functions to estimate the mode, the moments or the L-moments of a distribution, see the reference manuals of  \pkg{modeest}, \pkg{lmomco} and \pkg{Lmoments} packages.

This manuscript reviews the various features of version 1.0-2 of \pkg{fitdistrplus}. The package
is available from the Comprehensive \proglang{R} Archive Network at \url{http://cran.r-project.org/package=fitdistrplus}.
The development version of the package is located at \proglang{R}-forge as one package of the 
project ``Risk Assessment with \proglang{R}''
(\url{http://r-forge.r-project.org/projects/riskassessment/}).
The paper is organized as follows: Section \ref{fitnoncenscont} presents tools for fitting continuous
distributions to classic non-censored data. Section \ref{advtopic} deals with other
estimation methods and other types of data, before Section \ref{ccl} concludes.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section[Fitting distributions]{Fitting distributions to continuous non-censored data}\label{fitnoncenscont}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Choice of candidate distributions}
\label{Choice}
For illustrating the use of various functions of the \pkg{fitdistrplus} package 
with continuous non-censored data, we will  first use
a data set named \code{groundbeef} which is included in our package.
This data set contains pointwise values of
serving sizes in grams, collected in a French survey, for ground beef patties consumed by 
children under 5 years old. It was used in a quantitative risk assessment 
published by \cite{Delignette08}.
%%% R code set default options for all R schunks
<<par4vignette, echo=FALSE, results=hide>>=
options(digits = 4, prompt="R> ", 
        SweaveHooks=list(fig=function() par(mar=c(5.1, 4.1, 1.1, 2.1))))
set.seed(1234)
@
%%% R code
<<datgroundbeef, echo=TRUE>>=
library("fitdistrplus")
data("groundbeef")
str(groundbeef)
@


Before fitting one or more distributions to a data set, it is generally
necessary to choose good candidates among a predefined set of distributions.
This choice may be guided by the knowledge of stochastic processes governing
the modelled variable, or, in the absence of knowledge regarding the underlying process, 
by the observation of its empirical distribution.
To help the user in this choice, we developed functions to plot and
characterize the empirical distribution.

First of all, it is common to start with plots of the empirical distribution 
function and the histogram (or density plot), which can be obtained with the \code{plotdist} function of the \pkg{fitdistrplus} package.
This function provides two plots (see Figure~\ref{plotdistcont}): the left-hand plot is by default the histogram 
on a density scale
(or density plot of both, according to values of arguments \code{histo} and \code{demp})
and the right-hand  plot the empirical cumulative distribution function (CDF).
%%% R code
<<figgroundbeef.echo, echo=TRUE, fig=FALSE, eval=FALSE>>=
plotdist(groundbeef$serving, histo = TRUE, demp = TRUE)
@

\setkeys{Gin}{width=0.8\textwidth}

\begin{figure}[htb!]
  \centering
  %%% R code
<<figgroundbeefplot, echo=FALSE, fig=TRUE, width=10, height=5, eps=FALSE>>=
plotdist(groundbeef$serving, histo = TRUE, demp = TRUE)
@
  \caption{Histogram and CDF plots of an empirical distribution for a continuous variable 
  (serving size from the \code{groundbeef} data set) as provided by the \code{plotdist} function.}
  \label{plotdistcont}
\end{figure}



In addition to empirical plots, descriptive statistics may help to choose candidates to describe a distribution
among a set of parametric distributions. Especially the skewness and kurtosis, linked to the third and fourth moments, 
are useful for this purpose. A non-zero skewness reveals a lack of symmetry of the empirical distribution,
while the kurtosis value quantifies the weight of tails in comparison to the normal distribution for which
the kurtosis equals 3.
The skewness and kurtosis and their corresponding unbiased estimator \citep{casellaberger02} from a sample 
$(X_i)_i \stackrel{\text{i.i.d.}}{\sim} X$ with observations $(x_i)_i$ are given by
  \begin{equation}
    \label{skewness}
    sk(X) = \frac{E[(X-E(X))^3]}{Var(X)^{\frac{3}{2}}}~,~
    \widehat{sk}=\frac{\sqrt{n(n-1)}}{n-2}\times\frac{m_{3}}{m_{2}^{\frac{3}{2}}},
  \end{equation}

  \begin{equation}
    \label{kurtosis}
    kr(X) = \frac{E[(X-E(X))^4]}{Var(X)^{2}}~,~
    \widehat{kr}=\frac{n-1}{(n-2)(n-3)}((n+1) \times \frac{m_{4}}{m_{2}^{2}}-3(n-1)) + 3,
  \end{equation}
where $m_{2}$, $m_{3}$, $m_{4}$ denote empirical moments defined by
$m_{k}=\frac{1}{n}\sum_{i=1}^n(x_{i}-\overline{x})^{k}$, with
$x_{i}$ the $n$ observations of variable $x$ and $\overline{x}$ their mean value.

The  \code{descdist} function provides classical descriptive statistics
(minimum, maximum, median, mean, standard deviation), skewness and kurtosis. By default, 
unbiased estimations of the three last statistics are provided. Nevertheless,
the argument \code{method}
can be changed from \code{"unbiased"} (default) to \code{"sample"} to obtain  
them without correction for bias. 
A skewness-kurtosis plot such as the one proposed by \cite{Cullen99} is  provided by 
the \code{descdist} function for the empirical distribution 
(see Figure~\ref{Cullenplotcont} for the \code{groundbeef} data set). 
On this plot, values for common distributions are displayed in order 
to help the choice of distributions to fit to data. For some distributions (normal, uniform,
logistic, exponential), there is only one possible value for the skewness and the kurtosis.
 Thus, the distribution is represented by a single point on the plot. For other distributions, 
areas of possible values are represented, consisting in lines (as for gamma and lognormal distributions), 
or larger areas (as for beta distribution).
    
Skewness and kurtosis are known not to be robust. In order to take into account the uncertainty 
of the estimated values of kurtosis and skewness from data, a nonparametric bootstrap 
procedure \citep{efrontibshirani94} can be performed by using the argument \code{boot}. %to an integer above 10.
Values of skewness and kurtosis are computed on bootstrap samples (constructed by 
random sampling with replacement from the original data set) and reported on the 
skewness-kurtosis plot. 
Nevertheless, the user needs to know that skewness and kurtosis,  like all higher moments, have a very high variance. This is a problem which cannot be completely solved by the use of bootstrap. The skewness-kurtosis plot should then be regarded as indicative only.
The properties of the random variable should be considered, notably its expected value and its range,
as a complement to the use of the \code{plotdist} and \code{descdist} functions. 
Below is a call to the \code{descdist} function to describe the distribution 
of the serving size from the \code{groundbeef} data set and to draw the corresponding skewness-kurtosis
plot (see Figure~\ref{Cullenplotcont}). Looking at the results on this example
with a positive skewness and a kurtosis not far from 3,
the fit of three common right-skewed distributions could be considered, Weibull, gamma and 
lognormal distributions.
%%% R code
<<descgroundbeef.echo, echo=TRUE, fig=FALSE, eval=FALSE>>=
descdist(groundbeef$serving, boot = 1000)
@

\setkeys{Gin}{width=0.5\textwidth}

\begin{figure}[htb]
  \centering
 %%% R code
<<descgroundbeefplot, echo=FALSE, fig=TRUE, width=6, height=6, eps=FALSE>>=
descdist(groundbeef$serving, boot = 1000)
@
  \caption{Skewness-kurtosis plot for a continuous variable 
  (serving size from the \code{groundbeef} data set) as provided by the \code{descdist} function.}
  \label{Cullenplotcont}
\end{figure}

\newpage

\subsection[Maximum likelihood]{Fit of distributions by maximum likelihood estimation}
\label{FIT}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Once selected, one or more parametric distributions $f(.\vert \theta)$ 
(with parameter $\theta\in\mathbb{R}^d$) may be fitted to the data set, 
one at a time, using the \code{fitdist} function. 
Under the i.i.d. sample assumption, distribution parameters $\theta$ are by default estimated by maximizing the
likelihood function defined as:
  \begin{equation}
    \label{likelihood}
    L(\theta)=\prod_{i=1}^n f(x_{i}\vert \theta)
  \end{equation}
with $x_{i}$ the $n$ observations of variable $X$ and $f(.\vert \theta)$ the density function of the 
parametric distribution.
The other proposed estimation methods are described in Section~\ref{Alternatives}. 

The \code{fitdist} function returns an S3 object of class \code{"fitdist"} 
for which \code{print}, \code{summary} and \code{plot} functions are provided.
The fit of a distribution using \code{fitdist} assumes that the corresponding 
\code{d}, \code{p}, \code{q} functions (standing respectively for the density, 
the distribution and the quantile functions) are defined.
Classical distributions are already defined in that way in the \pkg{stats} package,
e.g., \code{dnorm}, \code{pnorm} and \code{qnorm} for the normal distribution
(see \code{?Distributions}). Others
may be found in various packages (see the CRAN task view: Probability Distributions at \url{https://CRAN.R-project.org/view=Distributions}). 
Distributions not found in any package must be implemented by the user as
\code{d}, \code{p}, \code{q} functions.
In the call to \code{fitdist}, a distribution  has to be specified via
the argument \code{dist} either by the character string corresponding to its common root name
used in the names of \code{d}, \code{p}, \code{q} functions
(e.g., \code{"norm"} for the normal distribution) 
or by the density function itself, from which
the root name is extracted (e.g., \code{dnorm} for the normal distribution).
Numerical results returned by the \code{fitdist} function are 
(1) the parameter estimates, (2) the estimated standard errors (computed from the estimate
of the Hessian matrix at the maximum likelihood solution), (3) the loglikelihood, 
(4) Akaike and Bayesian information criteria (the so-called AIC and BIC), and (5) the correlation matrix
between parameter estimates.
Below is a call to the \code{fitdist} function to fit a Weibull distribution 
to the serving size from the \code{groundbeef} data set.
%%% R code
<<fitgroundbeef.weibull, echo = TRUE, fig = FALSE>>=
fw <- fitdist(groundbeef$serving, "weibull")
summary(fw)
@

The plot of an object of class \code{"fitdist"} provides 
four classical goodness-of-fit plots \citep{Cullen99} 
presented on Figure~\ref{groundbeef:comp}: 
\begin{itemize}
\item a density plot representing the density function of the fitted distribution 
along with the histogram of the empirical distribution, 
\item a CDF plot of both the empirical distribution and the fitted distribution, 
\item a Q-Q plot
representing the empirical quantiles (y-axis) against the theoretical quantiles (x-axis)
\item a P-P plot representing the empirical distribution function evaluated at each data point (y-axis)
against the fitted distribution function (x-axis).
\end{itemize}

For CDF, Q-Q and P-P plots, the probability plotting position is defined by default using Hazen's rule, with probability points of the empirical distribution calculated as
 \code{(1:n - 0.5)/n}, as recommended by \cite{Blom}.
This plotting position can be easily changed (see the reference 
manual for details \citep{fitdistrplus}).
% using the arguments 
%\code{use.ppoints} and \code{a.ppoints}. When \code{use.ppoints = TRUE}, 
%the argument \code{a.ppoints} is passed to the \code{ppoints} function from the \pkg{stats} package to %define the 
%probability points of the empirical distribution as \code{(1:n - a.ppoints)/(n - 2a.ppoints + 1)}. 
%When \code{use.ppoints = FALSE}, the probability points are simply defined as \code{1:n / n}.


Unlike the generic \code{plot} function, the \code{denscomp}, \code{cdfcomp},
\code{qqcomp} and \code{ppcomp} functions enable to draw separately each
of these four plots, in order to compare the empirical distribution 
and multiple parametric distributions fitted
on a same data set. These functions must be called with a first argument 
corresponding to a list of objects of class \code{fitdist}, and optionally
further arguments to customize the plot (see the reference 
manual for lists of arguments that may be specific to each plot \citep{fitdistrplus}). 
In the following example, we compare the fit of
a Weibull, a lognormal and a gamma distributions to the \code{groundbeef} data set (Figure~\ref{groundbeef:comp}).
%%% R code
<<fitgroundbeef.echo, echo=TRUE, fig=FALSE>>=
fg <- fitdist(groundbeef$serving, "gamma")
fln <- fitdist(groundbeef$serving, "lnorm")
par(mfrow = c(2, 2))
plot.legend <- c("Weibull", "lognormal", "gamma")
denscomp(list(fw, fln, fg), legendtext = plot.legend)
qqcomp(list(fw, fln, fg), legendtext = plot.legend)
cdfcomp(list(fw, fln, fg), legendtext = plot.legend)
ppcomp(list(fw, fln, fg), legendtext = plot.legend)
@


\setkeys{Gin}{width=0.8\textwidth}

\begin{figure}[htb!]
  \centering
<<fitgroundbeef, echo=FALSE, fig=TRUE, width=7, height=7, eps=FALSE>>=
par(mfrow=c(2, 2))
denscomp(list(fw, fln, fg), legendtext=c("Weibull", "lognormal", "gamma"))
qqcomp(list(fw, fln, fg), legendtext=c("Weibull", "lognormal", "gamma"))
cdfcomp(list(fw, fln, fg), legendtext=c("Weibull", "lognormal", "gamma"))
ppcomp(list(fw, fln, fg), legendtext=c("Weibull", "lognormal", "gamma"))
@ 
  \caption{Four Goodness-of-fit plots for various distributions fitted to continuous data
  (Weibull, gamma and lognormal
  distributions fitted to serving sizes from the \code{groundbeef} data set)  
  as provided by functions \code{denscomp}, \code{qqcomp}, \code{cdfcomp} and \code{ppcomp}.}
\label{groundbeef:comp}  
\end{figure}



The density plot and the CDF plot may be considered as the basic classical goodness-of-fit plots.
The two other plots are complementary and can be very informative in some cases.
The Q-Q plot emphasizes the lack-of-fit at the distribution tails while the P-P plot emphasizes
the lack-of-fit at the distribution center.
In the present example (in Figure~\ref{groundbeef:comp}), none of the three fitted distributions correctly describes
the center of the distribution, but the Weibull and gamma distributions 
could be prefered for their better description of the right tail of the empirical distribution, especially
if this tail is important in the use of the fitted distribution, as it is in the context of
food risk assessment.

The data set named  \code{endosulfan} will now be used to illustrate other features of 
the \pkg{fitdistrplus} package. This data set contains
acute toxicity values for the organochlorine pesticide endosulfan
(geometric mean of LC50 ou EC50 values in $\mu g.L^{-1}$),
tested on Australian and non-Australian laboratory-species 
\citep{Hose04}. 
In ecotoxicology, a
lognormal or a loglogistic distribution is often fitted to such a data set in order
to characterize the species sensitivity distribution (SSD) for a pollutant. A low percentile
of the fitted distribution, generally the 5$\%$ percentile, is then calculated and named 
the hazardous concentration 5$\%$ (HC5). It is interpreted as the value of the
pollutant concentration protecting 95$\%$ of the species \citep{Posthuma2010}.
But the fit of a lognormal or a loglogistic distribution to the whole \code{endosulfan} data set is rather bad (Figure~\ref{endo:comp}),
especially due to a minority of very high values. 
The two-parameter Pareto distribution and the three-parameter Burr distribution (which is an extension
of both the loglogistic and the Pareto distributions) have been fitted.
Pareto and Burr distributions are provided in the package \pkg{actuar}. 
Until here, we did not have to  define starting values (in the optimization process)
as reasonable starting values are implicity defined within the \code{fitdist} function 
for most of the distributions defined in \proglang{R} (see \code{?fitdist} for details).
For other distributions like the Pareto and the Burr distribution, initial 
values for the distribution parameters have to be supplied
in the argument \code{start}, as a named list  with initial values for each parameter 
(as they appear in the \code{d}, \code{p}, \code{q} functions). 
Having defined reasonable starting values\footnote{%----
The \code{plotdist} function can plot any 
parametric distribution with specified parameter values in argument \code{para}. It can thus help to find correct initial values for the distribution parameters in non trivial cases, by iterative calls if necessary (see the reference 
manual for examples \citep{fitdistrplus}).
}, %----
various distributions can be fitted and graphically
compared. On this example, the function \code{cdfcomp} can be used to report CDF values in a logscale so as to emphasize discrepancies on the tail of
interest while defining an HC5 value (Figure~\ref{endo:comp}).


%%% R code
<<fitendo.echo, echo=TRUE, fig=FALSE>>=
data("endosulfan")
ATV <-endosulfan$ATV
fendo.ln <- fitdist(ATV, "lnorm")
library("actuar")
fendo.ll <- fitdist(ATV, "llogis", start = list(shape = 1, scale = 500))
fendo.P <- fitdist(ATV, "pareto", start = list(shape = 1, scale = 500))
fendo.B <- fitdist(ATV, "burr", start = list(shape1 = 0.3, shape2 = 1, 
  rate = 1))
cdfcomp(list(fendo.ln, fendo.ll, fendo.P, fendo.B), 
  xlogscale = TRUE, ylogscale = TRUE, 
  legendtext = c("lognormal", "loglogistic", "Pareto", "Burr"))
@
% qqcomp(list(fendo.ln, fendo.ll, fendo.P, fendo.B), xlogscale=TRUE, ylogscale=TRUE,
%       legendtext = c("lognormal","loglogistic","Pareto","Burr"))

\setkeys{Gin}{width=0.5\textwidth}

\begin{figure}[htb!]
  \centering
<<fitendo, echo=FALSE, fig=TRUE, width=4, height=4, eps=FALSE>>=
cdfcomp(list(fendo.ln, fendo.ll, fendo.P, fendo.B), xlogscale = TRUE,
        ylogscale = TRUE,legendtext = c("lognormal","loglogistic","Pareto","Burr"))
@
%qqcomp(list(fendo.ln,fendo.ll,fendo.P,fendo.B),xlogscale=TRUE,ylogscale=TRUE,
%       legendtext = c("lognormal","loglogistic","Pareto","Burr"))

  \caption{CDF plot to compare the fit of four distributions to
  acute toxicity values of various organisms for the organochlorine pesticide endosulfan
  (\code{endosulfan} data set) as provided by the \code{cdfcomp} function, with CDF values
  in a logscale to emphasize discrepancies on the left tail.}
\label{endo:comp}  
\end{figure}

None of the fitted distribution correctly
describes the right tail observed in the data set, but as shown in Figure~\ref{endo:comp},
the left-tail seems to be better described by the Burr distribution. Its use could then be considered
to estimate the HC5 value as the $5\%$ quantile of the distribution. This can be 
easily done using the \code{quantile} generic function defined for an object 
of class \code{"fitdist"}. Below is this calculation together with the calculation of the 
empirical quantile for comparison.


%%% R code
<<quantilefitdist, echo=TRUE, fig=FALSE>>=
quantile(fendo.B, probs = 0.05)
quantile(ATV, probs = 0.05)
@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
In addition to the ecotoxicology context, the \code{quantile} generic function is also attractive in
the actuarial--financial context. In fact, the value-at-risk $VAR_\alpha$ is defined as the $1-\alpha$-quantile
of the loss distribution and can be computed with \code{quantile} on a \code{"fitdist"} object.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The computation of different goodness-of-fit statistics is proposed in the \pkg{fitdistrplus} package
in order to further compare fitted distributions.
The purpose of goodness-of-fit statistics aims to measure the distance between the
fitted parametric distribution and the empirical distribution: e.g., 
the distance between the fitted cumulative distribution function $F$ 
and the empirical distribution function $F_{n}$.
When fitting continuous distributions, three  goodness-of-fit statistics are classicaly considered: 
Cramer-von Mises, Kolmogorov-Smirnov and Anderson-Darling statistics \citep{Stephens86}.
Naming $x_{i}$ the $n$ observations of a continuous variable $X$ arranged in an ascending order,
Table \ref{tabKSCvMAD} gives the definition and the empirical estimate of the three considered 
goodness-of-fit statistics.
They can be computed using the function \code{gofstat}
as defined by Stephens \citep{Stephens86}.



<<fendo.gof.print, echo=TRUE, fig=FALSE>>=
gofstat(list(fendo.ln, fendo.ll, fendo.P, fendo.B),
  fitnames = c("lnorm", "llogis", "Pareto", "Burr"))
@

\begin{table}[htb!]
  \begin{center}
    \begin{tabular}{lll}
    \hline
      Statistic  & General formula & Computational formula\\
    \hline
      Kolmogorov-Smirnov   & $\sup|F_{n}(x) - F(x)|$ &
      $\max(D^{+},D^{-})$ with\\
      (KS) & &  $D^{+}=\max\limits_{i=1,\dots,n}\left(\frac{i}{n} - F_i\right)$ \\
           & &  $D^{-}=\max\limits_{i=1,\dots,n}\left(F_{i}-\frac{i-1}{n}\right)$ \\
    \hline
      Cramer-von Mises  & n $\int_{-\infty}^{\infty}(F_{n}(x) - F(x))^2 dx$ &
        $\frac{1}{12n} + \sum\limits_{i=1}^n \left(F_i-\frac{2i-1}{2n} \right)^{2}$\\
      (CvM)&&\\
% cvm <- 1/(12*n) + sum( ( theop - (2 * seq(1:n) - 1)/(2 * n) )^2 )
    \hline
      Anderson-Darling  & n $\int_{-\infty}^{\infty}\frac{(F_{n}(x) - F(x))^2}{F(x) (1 - F(x))} dx$
      & $-n -\frac{1}{n}\sum\limits_{i=1}^n (2i-1)\log(F_i(1-F_{n+1-i}))$ \\
      (AD) &    & \\
% ad <- - n - mean( (2 * seq(1:n) - 1) * (log(theop) + log(1 - rev(theop))) )
    \hline
     where $F_i\stackrel{\triangle}{=} F(x_i)$
    \end{tabular}
    \caption{Goodness-of-fit statistics as defined by Stephens \citep{Stephens86}.}
    \label{tabKSCvMAD}
  \end{center}
\end{table}

%\newpage
As giving  more weight to distribution tails, 
the Anderson-Darling statistic is of special interest when it matters to equally 
emphasize the tails as well as the main body of a distribution.
This is often the case in risk assessment \citep{Cullen99,Vose10}. For this reason, 
this statistics is often used to select the best distribution among those fitted.
Nevertheless, this statistics should be used cautiously when comparing fits of various distributions. 
Keeping in mind that the weighting of each CDF quadratic difference 
depends on the parametric distribution in its definition (see Table \ref{tabKSCvMAD}), 
Anderson-Darling statistics computed for several distributions fitted on a same data set
are theoretically difficult to compare. Moreover, such a statistic, as Cramer-von Mises and
Kolmogorov-Smirnov ones, does not take into account the complexity of 
the model (i.e., parameter number). It is not
a problem when compared distributions are characterized by the same number of parameters, but
it could systematically promote the selection of the more complex distributions in the other case. 
Looking at classical penalized criteria based on the loglikehood (AIC, BIC) seems thus also interesting, especially
to discourage overfitting. 

In the previous example, all the goodness-of-fit statistics based on the CDF distance are in favor of 
the Burr distribution, the only one characterized by three parameters, while AIC and BIC values
respectively give the preference to the Burr distribution or the Pareto distribution.
The choice between these two distributions seems thus less obvious and could be discussed. 
Even if specifically recommended for discrete distributions, the Chi-squared statistic may also be used for
continuous distributions (see Section~\ref{otherdata} and the reference 
manual for examples \citep{fitdistrplus}).

\subsection[Uncertainty]{Uncertainty in parameter estimates}
\label{Uncertainty}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The uncertainty in the parameters of the fitted distribution can be estimated by parametric or nonparametric
bootstraps using the \code{boodist} function for non-censored data \citep{efrontibshirani94}.
This function returns the bootstrapped values of parameters in an 
S3 class object which can be plotted to visualize the bootstrap region. 
The medians and the 95 percent confidence intervals of parameters (2.5 and 97.5 percentiles) are printed 
in the summary.
When inferior to the whole number of iterations (due to lack of convergence of the optimization
algorithm for some bootstrapped data sets), the number of iterations for which the estimation converges 
is also printed in the summary. 
    
The plot of an object of class \code{"bootdist"}  
consists in a scatterplot or a matrix of scatterplots
of the bootstrapped values of parameters providing
a representation of the joint uncertainty distribution of the fitted parameters.
Below is an example of the use of the \code{bootdist} function with the previous fit of the Burr distribution to the
\code{endosulfan} data set (Figure~\ref{fig:bootstrap}). 
%%% R code
<<fitBurr.boot.echo, echo=TRUE, results=hide, fig=FALSE>>=
bendo.B <- bootdist(fendo.B, niter = 1001)
@
<<fitBurr.boot.results, echo=TRUE, fig=FALSE>>=
summary(bendo.B)
plot(bendo.B)
@

\setkeys{Gin}{width=0.5\textwidth} 
\begin{figure}[htb!]
  \centering
<<fitBurrbootplot, echo=FALSE, fig=TRUE, width=6, height=6, eps=FALSE>>=
plot(bendo.B)
@
  \caption{Bootstrappped values of parameters for a fit of the Burr distribution
characterized by three parameters (example on the \code{endosulfan} data set) as provided 
by the plot of an object of class \code{"bootdist"}.}
  \label{fig:bootstrap}
\end{figure}

Bootstrap samples of parameter estimates are useful especially to calculate confidence intervals on each parameter
of the fitted distribution from the marginal distribution of the bootstraped values. It is also interesting to look at the joint distribution of the bootstraped
values in a scatterplot (or a matrix of scatterplots if the number of parameters exceeds two) in order
to understand the potential structural correlation between parameters (see Figure~\ref{fig:bootstrap}).

The use of the whole bootstrap sample is also of interest in the risk assessment field. Its use enables
the characterization of uncertainty in distribution parameters. 
It can be directly used within a second-order Monte Carlo
simulation framework, especially within the package \pkg{mc2d} \citep{mc2d}. One could refer to \cite{Pouillot10} for an introduction to the use of \pkg{mc2d} 
and \pkg{fitdistrplus} packages in the context of quantitative 
risk assessment.

The bootstrap method can also be used to calculate confidence intervals on quantiles 
of the fitted distribution.
For this purpose, a generic \code{quantile} function is provided for class \code{bootdist}. 
By default, $95\%$ percentiles bootstrap confidence intervals of quantiles are provided.
Going back to the previous example from ecotoxicolgy, this function can be used to 
estimate the uncertainty associated to the HC5 estimation, for example from the previously fitted
Burr distribution to the \code{endosulfan} data set.
 %%% R code
<<fitATV.lnorm.quantile, echo=TRUE,results=hide>>=
quantile(bendo.B, probs = 0.05)
@
\begin{small}
<<fitATV.lnorm.quantileb, echo=FALSE>>=
quantile(bendo.B, probs = 0.05)
@
\end{small}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Advanced topics}\label{advtopic}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection[Alternative estimation]{Alternative methods for parameter estimation}
\label{Alternatives}



This subsection focuses on alternative estimation methods.
One of the alternative for continuous distributions
is the maximum goodness-of-fit estimation method also called
minimum distance estimation method \citep{Stephens86,actuarJSS}. 
In this package this method is proposed with
eight different distances: the three classical distances defined
in Table~\ref{tabKSCvMAD},
or one of the variants of the Anderson-Darling distance proposed by \cite{Luceno06} and defined in 
Table~\ref{modifiedAD}.
The right-tail AD gives more weight to the right-tail, the left-tail AD
gives more weight only to the left tail. Either of the tails, or both of them,
can receive even larger
weights by using second order Anderson-Darling Statistics.

\begin{table}[htb!]
  \begin{center}
    \begin{tabular}{lll}
    \hline
      Statistic  & General formula & Computational formula\\
    \hline
      Right-tail AD  & $\int_{-\infty}^{\infty}\frac{(F_{n}(x) - F(x))^2 }{1 - F(x)}  dx$
      & $\frac{n}{2} -2\sum\limits_{i=1}^nF_i -\frac{1}{n}\sum\limits_{i=1}^n(2i-1)ln(\overline F_{n+1-i})$ \\
      (ADR) &  &\\
    \hline
      Left-tail AD  & $\int_{-\infty}^{\infty}\frac{(F_{n}(x) - F(x))^2 }{(F(x))}  dx$
      & $-\frac{3n}{2} +2\sum\limits_{i=1}^nF_i -\frac{1}{n}\sum\limits_{i=1}^n(2i-1)ln(F_i)$ \\
      (ADL) &  &\\
    \hline
      Right-tail AD  & $ad2r=\int_{-\infty}^{\infty}\frac{(F_{n}(x) - F(x))^2 }{(1 - F(x))^{2}}  dx$
      & $ad2r=2\sum\limits_{i=1}^nln(\overline F_i) +\frac{1}{n}\sum\limits_{i=1}^n \frac{2i-1}{\overline F_{n+1-i}}$ \\
      2nd order (AD2R) &  &\\
    \hline
      Left-tail AD  & $ad2l=\int_{-\infty}^{\infty}\frac{(F_{n}(x) - F(x))^2 }{(F(x))^{2}}  dx$
      & $ad2l=2\sum\limits_{i=1}^nln(F_i) +\frac{1}{n}\sum\limits_{i=1}^n\frac{2i-1}{F_i}$ \\
      2nd order (AD2L) &  &\\
    \hline
    AD 2nd order & $ad2r+ad2l$
      & $ad2r+ad2l$ \\
    (AD2) &  &\\
    \hline
    where $F_i\stackrel{\triangle}{=} F(x_{i})$; & $\overline F_i\stackrel{\triangle}{=}1-F(x_{i})$
    \end{tabular}
    \caption{Modified Anderson-Darling statistics as defined by \cite{Luceno06}.}
    \label{modifiedAD}
  \end{center}
\end{table}

To fit a distribution by maximum goodness-of-fit estimation, one
needs to fix the argument \code{method}
to \code{"mge"} in the call to \code{fitdist} and to specify the argument \code{gof}
coding for the chosen goodness-of-fit distance. 
This function is intended to be used only with continuous non-censored data.


Maximum goodness-of-fit estimation may be useful to give
more weight to data at one tail of the distribution.
In the previous example from ecotoxicology, 
we used a non classical distribution (the Burr distribution) to correctly
fit the empirical distribution especially on its left tail. 
In order to correctly estimate the 5$\%$ percentile, we could
also consider the fit of the classical lognormal distribution, but minimizing a
goodness-of-fit distance giving more weight to the left tail of the empirical distribution. 
In what follows, the left tail 
Anderson-Darling distances of first or second order are used to fit a lognormal
to \code{endosulfan} data set
(see Figure~\ref{plotfitMGE}).

%%% R code
<<mge.gofcomp.echo, echo=TRUE, fig=FALSE>>=
fendo.ln.ADL <- fitdist(ATV, "lnorm", method = "mge", gof = "ADL")
fendo.ln.AD2L <- fitdist(ATV, "lnorm", method = "mge", gof = "AD2L")
cdfcomp(list(fendo.ln, fendo.ln.ADL, fendo.ln.AD2L), 
  xlogscale = TRUE, ylogscale = TRUE,
  main = "Fitting a lognormal distribution",
  xlegend = "bottomright", 
  legendtext = c("MLE","Left-tail AD", "Left-tail AD 2nd order"))
@

\setkeys{Gin}{width=0.5\textwidth}

\begin{figure}[htb!]
  \centering
  %%% R code
<<mgegofcompplot, echo=FALSE, fig=TRUE, width=4, height=4, eps=FALSE>>=
cdfcomp(list(fendo.ln, fendo.ln.ADL, fendo.ln.AD2L),
  xlogscale = TRUE, ylogscale = TRUE,
  main = "Fitting a lognormal distribution",
  legendtext = c("MLE","Left-tail AD", "Left-tail AD 2nd order"),
xlegend = "bottomright")
@
  \caption{Comparison of a lognormal distribution fitted by MLE
  and by MGE using  two different goodness-of-fit distances : left-tail Anderson-Darling and left-tail Anderson Darling of second order (example with the \code{endosulfan} data set)
  as provided by the \code{cdfcomp} function, with CDF values
  in a logscale to emphasize discrepancies on the left tail.}
  \label{plotfitMGE}
\end{figure}

Comparing the $5\%$ percentiles (HC5) calculated using these three fits to the one calculated
from the MLE fit of the Burr distribution, we can observe, on this example,
that fitting the lognormal distribution by maximizing left tail 
Anderson-Darling distances of first or second order
enables to approach the value obtained by fitting the Burr distribution by MLE. 
%%% R code
<<quantilefitdist, echo=TRUE, fig=FALSE>>=
(HC5.estimates <- c(
  empirical = as.numeric(quantile(ATV, probs = 0.05)), 
  Burr = as.numeric(quantile(fendo.B, probs = 0.05)$quantiles), 
  lognormal_MLE = as.numeric(quantile(fendo.ln, probs = 0.05)$quantiles), 
  lognormal_AD2 = as.numeric(quantile(fendo.ln.ADL, 
    probs = 0.05)$quantiles), 
  lognormal_AD2L = as.numeric(quantile(fendo.ln.AD2L, 
    probs = 0.05)$quantiles)))
@

%\subsubsection{Moment matching estimation}
%\label{MME}
%%%%%%%%%%
The moment matching estimation (MME) is another method commonly used to fit parametric 
distributions \citep{Vose10}. 
MME consists in finding the value of the parameter $\theta$  that equalizes the first theoretical 
raw moments of the parametric distribution  to the corresponding empirical raw moments as in Equation~(\ref{moments}):
  \begin{equation}
    \label{moments}
    E(X^{k}|\theta)=\frac{1}{n}\sum_{i=1}^{n}x_{i}^{k} ,
  \end{equation}
for $k=1,\ldots,d$, with $d$ the number of parameters to estimate and
 $x_{i}$ the $n$ observations of variable $X$.
For moments of order greater than or equal to 2, it may  also be relevant to match centered moments.
Therefore, we match the moments given in Equation~(\ref{centmoments}):
  \begin{equation}
    \label{centmoments}
    E(X\vert \theta) = \overline{x} ~,~
    E\left((X-E(X))^{k}|\theta\right)=m_k, \text{ for }  k=2,\ldots,d,
  \end{equation}
where $m_k$ denotes the empirical centered moments.
This method can be performed by setting the argument \code{method} to \code{"mme"} in the call to \code{fitdist}.
The estimate is computed by a closed-form formula for the following distributions:
normal, lognormal, exponential, Poisson, gamma, logistic, negative binomial,
geometric, beta and uniform distributions.
In this case, for distributions characterized by one parameter (geometric, Poisson and exponential),
this parameter is simply estimated by matching theoretical and observed means, and for distributions 
characterized by two parameters, these parameters are estimated by matching theoretical and observed 
means and variances \citep{Vose10}.
For other distributions, the equation of moments is solved numerically using 
the \code{optim} function  by minimizing the
sum of squared differences between observed and theoretical moments (see the \pkg{fitdistrplus} reference
manual
for technical details \citep{fitdistrplus}).


A classical data set from the Danish insurance industry 
published in \cite{mcneil97} will be used to illustrate this method.
In \pkg{fitdistrplus}, the data set is stored in \code{danishuni} for the univariate version and contains
the loss amounts collected at Copenhagen Reinsurance between 1980 and 1990.
In actuarial science, it is standard to consider positive heavy-tailed distributions and have 
a special focus on the right-tail of the distributions.
In this numerical experiment, we choose classic actuarial 
distributions for loss modelling: the lognormal distribution and the Pareto type II 
distribution \citep{Klugmanetal09}. 

The lognormal distribution is 
fitted to \code{danishuni} data set by matching moments implemented as a closed-form formula.
On the left-hand graph of Figure~\ref{fig:danish:mme}, the fitted distribution functions obtained 
using the moment matching estimation (MME) and  maximum likelihood estimation (MLE) methods are compared.
The MME method provides a more cautious estimation of the insurance risk 
as the MME-fitted distribution function (resp. MLE-fitted) underestimates (overestimates) 
the empirical distribution function for large values of claim amounts.

%%% R code
<<danish.mme, echo=TRUE, fig=FALSE>>=
data("danishuni")
str(danishuni)
fdanish.ln.MLE <- fitdist(danishuni$Loss, "lnorm")
fdanish.ln.MME <- fitdist(danishuni$Loss, "lnorm", method = "mme", 
  order = 1:2)
cdfcomp(list(fdanish.ln.MLE, fdanish.ln.MME), 
  legend = c("lognormal MLE", "lognormal MME"), 
  main = "Fitting a lognormal distribution", 
  xlogscale = TRUE, datapch = 20)
@

\setkeys{Gin}{width=0.9\textwidth} %default
\begin{figure}[htb!]
  \centering
  %%% R code
<<danishmmeplot, echo=FALSE, fig=TRUE, width=7, height=3.5, eps=FALSE>>=
library("actuar")
fdanish.P.MLE <- fitdist(danishuni$Loss, "pareto", 
  start=list(shape=10, scale=10), lower = 2+1e-6, upper = Inf)
memp <- function(x, order) sum(x^order)/length(x)
fdanish.P.MME <- fitdist(danishuni$Loss, "pareto", 
    method="mme", order=1:2, 
memp="memp", start=c(shape=10, scale=10), lower=c(2+1e-6,2+1e-6), 
upper=c(Inf,Inf))
par(mfrow=c(1, 2))
cdfcomp(list(fdanish.ln.MLE, fdanish.ln.MME), 
        legend=c("lognormal MLE", "lognormal MME"), main="Fitting a lognormal distribution",
        xlogscale=TRUE, datapch=20)
cdfcomp(list(fdanish.P.MLE, fdanish.P.MME), 
        legend=c("Pareto MLE", "Pareto MME"), main="Fitting a Pareto distribution",
        xlogscale=TRUE, datapch=20)
@
\caption{Comparison between MME and MLE when fitting a lognormal or a Pareto distribution 
to loss data from the \code{danishuni} data set.}
\label{fig:danish:mme}
\end{figure}

% je trouve nos legendes de graph trop longues?
% 


In a second time, a Pareto distribution, which gives more weight to 
the right-tail of the distribution, is fitted.
As the lognormal distribution, the Pareto has two parameters, which
allows a fair comparison.
%The Burr distribution (with its three parameters) would lead to a better fit.


We use the implementation of the \pkg{actuar} package providing raw and centered moments
for that distribution (in addition to \code{d}, \code{p}, \code{q} and \code{r} functions \citep{actuar12}.
Fitting a heavy-tailed distribution for which the first and the second moments do not exist for
certain values of the shape parameter requires some cautiousness.
This is carried out by providing, for the optimization process, 
a lower and an upper bound for each parameter.
The code below calls the L-BFGS-B optimization method in \code{optim}, since this quasi-Newton
allows box constraints\footnote{That is what the B stands for.}.
We choose match moments defined in Equation~(\ref{moments}), and so 
a function for computing the empirical raw moment (called \code{memp} in our example) is passed to \code{fitdist}.
For two-parameter distributions (i.e., $d=2$),  
Equations~(\ref{moments}) and (\ref{centmoments}) are equivalent.

<<danish.mme.pareto, echo=TRUE, fig=FALSE>>=
library("actuar")
fdanish.P.MLE <- fitdist(danishuni$Loss, "pareto",  
  start = list(shape = 10, scale = 10), lower = 2+1e-6, upper = Inf)
memp <- function(x, order) sum(x^order)/length(x)
fdanish.P.MME <- fitdist(danishuni$Loss, "pareto", method = "mme", 
  order = 1:2, memp = "memp", start = list(shape = 10, scale = 10), 
  lower = c(2+1e-6, 2+1e-6), upper = c(Inf, Inf))
cdfcomp(list(fdanish.P.MLE, fdanish.P.MME), 
  legend = c("Pareto MLE", "Pareto MME"), 
  main = "Fitting a Pareto distribution", 
  xlogscale = TRUE, datapch = ".")
gofstat(list(fdanish.ln.MLE, fdanish.P.MLE, 
  fdanish.ln.MME, fdanish.P.MME),
  fitnames = c("lnorm.mle", "Pareto.mle", "lnorm.mme", "Pareto.mme"))
@

As shown on Figure~\ref{fig:danish:mme}, MME and MLE fits
are far less distant (when looking at the right-tail) for the Pareto distribution 
than for the lognormal distribution on this data set. 
Furthermore, for these two distributions, the MME method better fits the 
right-tail of the distribution from a visual point of view. 
This seems logical since empirical moments 
are influenced by large observed values.
In the previous traces, we gave the values of goodness-of-fit statistics.
Whatever the statistic considered, the MLE-fitted lognormal always provides the best fit 
to the observed data.

Maximum likelihood and moment matching 
%(the default on many softwares)
% si on ne trouve pas de references on l'enleve?
estimations are 
certainly the most commonly used method for fitting distributions \citep{Cullen99}. 
Keeping in mind that these two methods may produce very different results,
the user should be aware of its great sensitivity to outliers
when choosing the moment matching estimation. This may be seen as an advantage in our example if the
objective is to better describe the right tail of the distribution, but it may be seen as a
drawback if the objective is different.
% As-tu des references indiquant que le MLE est meilleurs dans certains cas, cf. commentaires de Regis ?



%\subsubsection{Quantile matching estimation}
%\label{QME}
%%%%%%%%%%
Fitting of a parametric distribution may also be done by matching theoretical quantiles
of the parametric distributions (for specified probabilities) against the empirical quantiles (\cite{Tse2009}). The equality of theoretical and empirical qunatiles
is expressed by
Equation~(\ref{quantiles}) below, which is very similar to Equations~(\ref{moments}) and (\ref{centmoments}):
  \begin{equation}
    \label{quantiles}
    F^{-1}(p_{k}|\theta)=Q_{n,p_{k}} 
  \end{equation}
for $k=1,\ldots,d$, with $d$ the number of parameters to estimate (dimension of $\theta$ if there is
no fixed parameters) and
 $Q_{n,p_{k}}$ the empirical quantiles calculated from data for specified probabilities $p_{k}$.

Quantile matching estimation (QME) is performed by setting the argument \code{method}
to \code{"qme"} in the call to \code{fitdist} and adding an argument \code{probs}
defining the probabilities for which the quantile matching is performed.
The length of this vector must be equal
to the number of parameters to estimate (as the vector of moment orders for MME).
Empirical quantiles are computed using the
\code{quantile} function of the \pkg{stats} package using  \code{type=7} 
by default (see \code{?quantile} and \cite{hyndmanfan96}).
But the type of quantile can be easily changed by using the \code{qty} 
argument in the call to the \code{qme} function.   
The quantile matching is carried out numerically, 
by minimizing the sum of squared differences between observed and theoretical quantiles.
%%% R code
<<danish.qme.echo, echo=TRUE, fig=FALSE>>=
fdanish.ln.QME1 <- fitdist(danishuni$Loss, "lnorm", method = "qme", 
  probs = c(1/3, 2/3))
fdanish.ln.QME2 <- fitdist(danishuni$Loss, "lnorm", method = "qme", 
  probs = c(8/10, 9/10))
cdfcomp(list(fdanish.ln.MLE, fdanish.ln.QME1, fdanish.ln.QME2), 
  legend = c("MLE", "QME(1/3, 2/3)", "QME(8/10, 9/10)"), 
  main = "Fitting a lognormal distribution", 
  xlogscale = TRUE, datapch = 20)
@
Above is an example of fitting of a lognormal distribution to \code{danishuni} data set 
by matching probabilities $(p_1= 1/3, p_2=2/3)$ and $(p_1= 8/10, p_2=9/10)$.
As expected, the second QME fit gives more weight to the right-tail of the distribution.
%, despite we do not choose the Pareto type-II distribution.
Compared to the maximum likelihood estimation, the second QME fit best suits the right-tail
of the distribution, whereas the first QME fit best models the body of the distribution.
The quantile matching estimation is of particular interest when we need to focus 
around particular quantiles, e.g., $p=99.5\%$ in the Solvency II insurance context or
$p=5\%$ for the HC5 estimation in the ecotoxicology context.


\setkeys{Gin}{width=0.5\textwidth} %default


\begin{figure}[htb!]
  \centering
  %%% R code
<<danishqmeplot, echo=FALSE, fig=TRUE, width=4, height=4, eps=FALSE>>=
cdfcomp(list(fdanish.ln.MLE, fdanish.ln.QME1, fdanish.ln.QME2), 
        legend=c("MLE", "QME(1/3, 2/3)", "QME(8/10, 9/10)"), main="Fitting a lognormal distribution",
        xlogscale=TRUE, datapch=20)
@
\caption{Comparison between QME and MLE when fitting a lognormal distribution to loss data from the \code{danishuni} data set.}
\label{fig:danish:qme}
\end{figure}

\clearpage

\subsection[Customizing optimization]{Customization of the optimization algorithm}
\label{Customization}
%%%%%%%%%%
Each time a numerical minimization is carried out in the \code{fitdistrplus} package, 
the \code{optim} function of the \pkg{stats} package  is used by default with the 
\code{"Nelder-Mead"} method for distributions characterized by more than one parameter and
the \code{"BFGS"} method for distributions characterized by only one parameter.
Sometimes the default algorithm fails to converge. It is then
interesting to change some options of the \code{optim} function or to use another optimization
function than \code{optim} to minimize the objective function.
The argument \code{optim.method} can be used in the call to \code{fitdist} or
\code{fitdistcens}. It will internally be passed to \code{mledist},
\code{mmedist}, \code{mgedist} or \code{qmedist}, and to \code{optim}
(see \code{?optim} for details about the different algorithms available).

Even if no error is raised when computing the optimization, changing the algorithm 
is of particular interest to enforce bounds on some parameters. For instance, a 
volatility parameter $\sigma$ is strictly positive $\sigma>0$ and a probability 
 parameter $p$ lies in $p\in [0,1]$. This is possible by using arguments \code{lower} 
 and/or \code{upper}, for which their use automatically forces 
 \code{optim.method="L-BFGS-B"}. 


Below are examples of fits of a gamma distribution $\mathcal{G}(\alpha, \lambda)$ to 
the \code{groundbeef} data set with various algorithms. Note that the conjugate gradient algorithm
(\code{"CG"}) needs far more 
iterations to converge (around 2500 iterations)
compared to other algorithms (converging in less than 100 iterations).
%%% R code
<<optimmethod.gamma, echo=TRUE>>=
data("groundbeef")
fNM <- fitdist(groundbeef$serving, "gamma", optim.method = "Nelder-Mead")
fBFGS <- fitdist(groundbeef$serving, "gamma", optim.method = "BFGS") 
fSANN <- fitdist(groundbeef$serving, "gamma", optim.method = "SANN")
fCG <- try(fitdist(groundbeef$serving, "gamma", optim.method = "CG", 
  control = list(maxit = 10000)))
if(class(fCG) == "try-error")
  fCG <- list(estimate = NA)
@


It is also possible to use another function than \code{optim} to minimize the objective function by
specifying by the argument \code{custom.optim} in the call to \code{fitdist}. 
It may be necessary to customize this optimization function to meet
the following requirements. (1) \code{custom.optim} function must have the following arguments:
\code{fn} for the function to be optimized and \code{par} for the initialized parameters. 
(2) \code{custom.optim} should carry out a MINIMIZATION and must return
 the following components: \code{par} for the estimate, \code{convergence} for the convergence
code, \code{value=fn(par)} and \code{hessian}.
Below is an example of code written to wrap the \code{genoud} function from the \pkg{rgenoud} package in
order to respect our optimization ``template''.
The \pkg{rgenoud} package implements the genetic (stochastic) algorithm.
%%% R code
<<optimmethod.customgenoud, echo=TRUE>>=
mygenoud <- function(fn, par, ...) 
{
   require(rgenoud)
   res <- genoud(fn, starting.values = par, ...)        
   standardres <- c(res, convergence = 0)
   return(standardres)
}
@

The customized optimization function can then be passed as the argument \code{custom.optim} 
in the call to \code{fitdist}
or \code{fitdistcens}. The following code can for example be used to fit a gamma distribution to the
\code{groundbeef} data set. Note that in this example various arguments are also passed from \code{fitdist} 
to \code{genoud} :
\code{nvars}, \code{Domains}, \code{boundary.enforcement}, 
\code{print.level} and \code{hessian}.
The code below compares all the parameter estimates ($\hat\alpha$, $\hat\lambda$) by the different algorithms:
shape $\alpha$ and rate $\lambda$ parameters are relatively similar on this 
example, roughly 4.00 and 0.05, respectively.
%%% R code
<<optimmethod.customgenoud.fitdist, echo=TRUE, eval=TRUE>>=
fgenoud <- mledist(groundbeef$serving, "gamma", custom.optim = mygenoud, 
  nvars = 2, max.generations = 10, Domains = cbind(c(0,0), c(10,10)), 
  boundary.enforcement = 1, hessian = TRUE, print.level = 0, P9 = 10)
cbind(NM = fNM$estimate,
  BFGS = fBFGS$estimate,
  SANN = fSANN$estimate,
  CG = fCG$estimate,
  fgenoud = fgenoud$estimate)
@

%\newpage

\subsection[Other types of data]{Fitting distributions to other types of data}
\label{otherdata}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Analytical methods often lead to semi-quantitative results which are referred to as
censored data. Observations only known to be under a limit of detection are 
left-censored data. Observations only known to be above a limit of quantification
are  right-censored data. Results known to lie between two bounds are 
interval-censored data. These two bounds may correspond to a limit of detection and 
a limit of quantification, or more generally to uncertainty bounds around the observation.
Right-censored data are also commonly encountered with survival data \citep{kleinmoeschberger03}.
A data set may thus contain right-, left-, or interval-censored data, or may be a mixture
of these categories, possibly with different upper and lower bounds.
Censored data are sometimes excluded from the data analysis or replaced by a fixed value, which
in both cases may lead to biased results. A more recommended approach to correctly model
such data is based upon maximum likelihood \citep{kleinmoeschberger03,helsel05}. 


Censored data may thus contain left-censored, right-censored and interval-censored values, 
with several lower and upper bounds. 
Before their use in package \pkg{fitdistrplus}, 
such data must be coded into a dataframe with two columns, 
respectively named \code{left} 
and \code{right}, describing each observed value as an interval.
The \code{left} column contains either \code{NA} for left censored observations,
the left bound of the interval for interval censored observations,
or the observed value for non-censored observations.
The \code{right} column contains either \code{NA} for right censored observations,
the right bound of the interval for interval censored observations,
or the observed value for non-censored observations.
To illustrate the use of package \pkg{fitdistrplus} to fit distributions
to censored continous data, we  will use another
data set from ecotoxicology, included in our package and named  \code{salinity}. 
This data set contains acute salinity tolerance (LC50 values in electrical conductivity, $mS$.$cm^{-1}$)
of riverine macro-invertebrates taxa from the southern Murray-Darling Basin in 
Central Victoria, Australia
\citep{kefford07}. 


%%% R code
<<datsalinity, echo=TRUE>>=
data("salinity")
str(salinity)
@
     
%\subsubsection{Graphical display of the observed distribution}
%\label{censored:graph}
%%%%%%%%%%

Using censored data such as those coded in the \code{salinity} data set,
the empirical distribution can be plotted using the \code{plotdistcens} function.
By default, this function uses the Expectation-Maximization approach of \cite{Turnbull74} to compute the overall
empirical cdf curve with optional confidence intervals, by calls to \code{survfit}
and \code{plot.survfit} functions from the \pkg{survival} package 
(Figure~\ref{cdfcompcens} shows the Turnbull plot of data together with two fitted distributions). 
A less rigorous
but sometimes more illustrative plot can be 
obtained by fixing the argument \code{Turnbull} to \code{FALSE} in the call to \code{plotdistcens}
(see Figure~\ref{plotdistcens} for an example and the help page of Function
\code{plotdistcens} for details). This plot enables to see the real nature of censored data, as
points and intervals. 

%%% R code
%<<plotsalinity.echo, echo=TRUE, fig=FALSE>>=
%plotdistcens(salinity)
%@



%%% R code
<<plotsalinity2.echo, echo=TRUE, fig=FALSE>>=
plotdistcens(salinity,Turnbull = FALSE)
@


% pourquoi ne pas travailler avec un exemple simulé?
%


\setkeys{Gin}{width=0.5\textwidth} 

\begin{figure}[htb!]
  \centering
  %%% R code
<<plotsalinity, echo=FALSE, fig=TRUE, width=6, height=6, eps=FALSE, result=hide>>=
plotdistcens(salinity,Turnbull = FALSE)
@
  \caption{Simple plot of censored raw data (72-hour acute salinity tolerance of riverine macro-invertebrates from 
   the \code{salinity} data set) as ordered points 
   and intervals.}
  \label{plotdistcens}
\end{figure}




%\subsubsection{Maximum likelihood estimation}
%\label{censored:MLE}
%%%%%%%%%%

As for non censored data, one or more parametric distributions can
be fitted to the censored data set, one at a time, but using in this case
the \code{fitdistcens} function. This function estimates the vector of distribution parameters $\theta$
by maximizing the likelihood for censored data defined as:
  \begin{equation}
    \label{likelihoodC}
    \begin{array}{lll}
    L(\theta)&=&\prod_{i=1}^{N_{nonC}} f(x_{i}|\theta)
    \times \prod_{j=1}^{N_{leftC}} F(x^{upper}_{j}|\theta) \\
    & & \times \prod_{k=1}^{N_{rightC}} (1- F(x^{lower}_{k}|\theta))
    \times \prod_{m=1}^{N_{intC}} (F(x^{upper}_{m}|\theta)- F(x^{lower}_{j}|\theta))
    \end{array}
  \end{equation}
with $x_{i}$ the $N_{nonC}$ non-censored observations,
$x^{upper}_{j}$ upper values defining the $N_{leftC}$ left-censored observations,
$x^{lower}_{k}$ lower values defining the $N_{rightC}$ right-censored observations,
$[x^{lower}_{m} ; x^{upper}_{m}]$ the intervals defining the $N_{intC}$ interval-censored observations,
and F the cumulative distribution function of the parametric distribution 
\citep{kleinmoeschberger03,helsel05}.

As \code{fitdist}, \code{fitdistcens} returns the results of the fit of any parametric distribution
to a data set as an S3 class object that can be easily printed,
summarized or plotted.
For the \code{salinity} data set, a lognormal distribution or a loglogistic can be fitted 
as commonly done in ecotoxicology for such data. 
As with \code{fitdist}, for some distributions (see \cite{fitdistrplus} for details), 
it is necessary to specify initial 
values for the distribution parameters in the argument \code{start}.
The \code{plotdistcens} function can help to find correct initial values for 
the distribution parameters in non trivial cases, by a manual iterative use if necessary.
%%% R code
<<fitsalinity.echo, echo=TRUE, fig=FALSE>>=
fsal.ln <- fitdistcens(salinity, "lnorm")
fsal.ll <- fitdistcens(salinity, "llogis",
  start = list(shape = 5, scale = 40))
summary(fsal.ln)
summary(fsal.ll)
@

Computations of goodness-of-fit statistics have not yet been 
developed for fits using censored data but the quality of fit 
can be judged using Akaike and Schwarz's Bayesian 
information criteria (AIC and BIC) and the goodness-of-fit CDF plot, 
respectively provided when summarizing or plotting an object of class \code{"fitdistcens"}. 
Function \code{cdfcompcens} can also be used to compare the fit of various
distributions to the same censored data set. Its call is similar to the one of \code{cdfcomp}. Below is
an example of comparison of the two fitted distributions to the \code{salinity} data set (see Figure~\ref{cdfcompcens}).

%%% R code
<<fitsalinity.cdfcomp.echo, echo=TRUE, fig=FALSE, eval=FALSE>>=
cdfcompcens(list(fsal.ln, fsal.ll), 
  legendtext = c("lognormal", "loglogistic "))
@


\setkeys{Gin}{width=0.5\textwidth} %default
\begin{figure}[htb!]
  \centering
  %%% R code
<<fitsalinitycdfcompplot, echo=FALSE, fig=TRUE, width=6, height=6, eps=FALSE>>=
cdfcompcens(list(fsal.ln, fsal.ll),
    legendtext=c("lognormal", "loglogistic "))
@
  \caption{Goodness-of-fit CDF plot for fits of a lognormal and a loglogistic distribution
  to censored data: LC50 values from 
   the \code{salinity} data set.}
  \label{cdfcompcens}
\end{figure}

Function \code{bootdistcens} is the equivalent of \code{bootdist} for censored data, except that it 
only proposes nonparametric bootstrap. Indeed, it is not obvious to simulate censoring within a parametric 
bootstrap resampling procedure. The generic function \code{quantile} can also be applied
to an object of class \code{"fitdistcens"} or \code{"bootdistcens"}, as for 
continuous non-censored data.


In addition to the fit of distributions to censored or non censored continuous data, our package
can also accomodate discrete variables, such as count numbers, using the functions 
developped for continuous non-censored data. 
These functions will provide somewhat different graphs
and statistics, taking into account the discrete nature of the modeled variable.
The discrete nature of the variable is automatically recognized when a classical distribution is fitted to data
(binomial, negative binomial, geometric, hypergeometric and Poisson distributions) but must 
be indicated by fixing argument \code{discrete} to \code{TRUE} in the call to functions in other cases.
The \code{toxocara} data set included in the package corresponds to the observation of such a discrete variable. 
Numbers of \emph{Toxocara cati} parasites present in digestive tract are reported
from a random sampling of feral cats living on Kerguelen island \citep{Fromont01}. We  will use it 
to illustrate the case of discrete data.
%%% R code
<<dattoxocara, echo=TRUE>>=
data("toxocara")
str(toxocara)
@



The fit of a discrete distribution to discrete data by maximum
likelihood estimation requires the same procedure as for continuous non-censored data. 
As an example, 
using the \code{toxocara} data set, Poisson and
negative binomial distributions can be easily fitted.
%%% R code
<<fittoxocara.poisnbinom, echo = TRUE, fig = FALSE>>=
(ftoxo.P <- fitdist(toxocara$number, "pois"))
(ftoxo.nb <- fitdist(toxocara$number, "nbinom"))
@

For discrete distributions, the plot of an object of class \code{"fitdist"} simply provides
two goodness-of-fit plots comparing empirical and theoretical distributions
in density and in  CDF (Figure~\ref{plotdiscfitP}). Function \code{cdfcomp} can also be used to compare several plots
to the same data set, as follows for the previous fits (Figure~\ref{plotdiscfit}). 
<<fittoxocara.pois.echo, echo=TRUE, fig=FALSE>>=
plot(ftoxo.P)
@

\setkeys{Gin}{width=0.9\textwidth} %default

\begin{figure}[htb]
  \centering
<<fittoxocarapois, echo=FALSE, results=hide, fig=TRUE, width=7, height=3.5, eps=FALSE>>=
plot(ftoxo.P)
@
  \caption{Plot of the fit of a discrete distribution (Poisson distribution
  fitted to numbers of \emph{Toxocara cati} parasites from the \code{toxocara} data set).}
  \label{plotdiscfitP}
\end{figure}


<<fittoxocara.poisnbinom.echo, echo=TRUE, fig=FALSE>>=
cdfcomp(list(ftoxo.P, ftoxo.nb), 
  legendtext = c("Poisson", "negative binomial"))
@

\setkeys{Gin}{width=0.5\textwidth} %default

\begin{figure}[htb]
  \centering
<<fittoxocarapoisnbinomplot, echo=FALSE, results=hide, fig=TRUE, width=4, height=4, eps=FALSE>>=
cdfcomp(list(ftoxo.P, ftoxo.nb), 
        legendtext = c("Poisson", "negative binomial"))
@
  \caption{Comparison of the fits of a negative binomial and a Poisson distribution
   to numbers of \emph{Toxocara cati} parasites from the \code{toxocara} data set.}
  \label{plotdiscfit}
\end{figure}


When fitting discrete distributions, the Chi-squared statistic is computed by 
the \code{gofstat} function using cells defined 
by the argument \code{chisqbreaks} or cells automatically defined from the data in order 
to reach roughly the same number of observations per cell. This number is roughly equal to the argument
\code{meancount}, or sligthly greater if there are some ties. 
The choice to define cells from the empirical distribution (data), and not from the
theoretical distribution, was done to enable the comparison of Chi-squared values obtained
with different distributions fitted on a same data set.
If arguments \code{chisqbreaks} and \code{meancount} 
are both omitted, \code{meancount} is fixed in order to obtain roughly $(4n)^{2/5}$ cells, 
with $n$ the length of the data set \citep{Vose10}. Using this default option the two previous fits are 
compared as follows, 
giving the preference
to the negative binomial distribution, from both Chi-squared statistics and information criteria:
%%% R code
<<fittoxocara.poisnbinom.gof, echo=TRUE, fig=FALSE>>=
gofstat(list(ftoxo.P, ftoxo.nb), 
  fitnames = c("Poisson", "negative binomial"))
@



\section{Conclusion}
\label{ccl}
%%%%%%%%%%


The \proglang{R}  package \pkg{fitdistrplus} allows to easily fit distributions. 
Our main objective while developing this package was to provide tools for helping 
\proglang{R} users to fit distributions to data. 
We have been encouraged to pursue our work by feedbacks 
from users of our package in various areas as food or environmental risk assessment, epidemiology, ecology, 
molecular biology, genomics, bioinformatics, hydraulics, mechanics, financial and actuarial mathematics 
or operations research. Indeed, this package is already used by a lot of practionners and academics 
for simple MLE fits \citep{jaloustreetal11,saketal11,kochetal12,marquetouxetal12,
scholletal12,suuronenetal12,varoetal12,mandletal13,mala2013publi,nadarajahbakar2013,simoetal13,
westphalfitch13,wayland13,vianaetal13,wu13,staggeetal13,fiorellietal13,tikoleetal13,
voigtetal14}, 
for MLE fits and goodness-of-fit statistics 
\citep{tarnczi11,bagariaetal12,benavidesetal12,breitbach12,Pouillot10,vaninsky13}, 
for MLE fits and bootstrap \citep{croucheretal12,meheustetal12,orellanoetal12,telloetal12,hoelzeretal12,
prosseretal13,Zhang2013,Rigaux2014}, 
for MLE fits, bootstrap and goodness-of-fit statistics \citep{larrasetal13}, 
for MME fit \citep{luangkesornetal12,callauetal13,satoetal13}, 
for censored MLE and bootstrap \citep{lehaetal11,poulliotetal12,jongenburgeretal12,
commeauetal12,contrerasetal2013}, 
for graphic analysing in \citep{anandetal12}, 
for grouped-data fitting methods \citep{fusteinercostafreda12} 
or more generally \citep{busschaertetal10,eling12,
sosaetal2013,srinivasanetal2013,meyeretal13,Guillier2013471,Daelmanetal13,
eiketal13,Wu2:2013,drakeetal2014}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The \pkg{fitdistrplus} package is complementary with the \pkg{distrMod} package \citep{distrModJSS}. 
\pkg{distrMod} provides an even more flexible way to estimate distribution parameters but its use requires
a greater initial investment to learn how to manipulate the \texttt{S4} classes and methods
developed in the \texttt{distr}-family packages.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Many extensions of the \pkg{fitdistrplus} package are planned in the future: 
we target to extend to censored data some methods for the moment only available for non-censored data, 
especially concerning goodness-of-fit evaluation and fitting methods. We will also enlarge the choice of 
fitting methods for non-censored data, by proposing new goodness-of-fit distances (e.g., distances 
based on quantiles) for maximum goodness-of-fit estimation 
and new types of moments (e.g., limited expected values) for moment matching estimation. At last, we will
consider the case of multivariate distribution fitting.

\section{Acknowledgments}
\label{merci}
%%%%%%%%%%
The package would not have been at this stage without the stimulating contribution of R\'egis Pouillot  and 
Jean-Baptiste Denis, especially for its conceptualization. We also want to thank R\'egis Pouillot for 
his very valuable comments on the first version of this paper.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The authors gratefully acknowledges the two anonymous referees and the Editor for useful and constructive
comments. The remaining errors, of course, should be attributed to the authors alone.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\bibliographystyle{apalike}
\bibliography{jssfitdistrplus}



 
\end{document}
