% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stable.r
\name{dstable}
\alias{dstable}
\alias{pstable}
\alias{qstable}
\alias{rstable}
\alias{hstable}
\title{Stable Distribution}
\usage{
dstable(
  x,
  loc = 0,
  disp = 1/sqrt(2),
  skew = 0,
  tail = 2,
  npt = 501,
  up = 10,
  eps = 1e-06,
  integration = "Romberg"
)

pstable(q, loc = 0, disp = 1/sqrt(2), skew = 0, tail = 2, eps = 1e-06)

qstable(p, loc = 0, disp = 1/sqrt(2), skew = 0, tail = 2, eps = 1e-06)

rstable(n = 1, loc = 0, disp = 1/sqrt(2), skew = 0, tail = 2, eps = 1e-06)

hstable(x, loc = 0, disp = 1/sqrt(2), skew = 0, tail = 2, eps = 1e-06)
}
\arguments{
\item{x, q}{vector of quantiles.}

\item{loc}{vector of (real) location parameters.}

\item{disp}{vector of (positive) dispersion parameters.}

\item{skew}{vector of skewness parameters (in [-1,1]).}

\item{tail}{vector of parameters (in [0,2]) related to the tail thickness.}

\item{npt, up, integration}{As detailed herein -- only available when using \code{dstable}.}

\item{eps}{scalar giving the required precision in computation.}

\item{p}{vector of probabilites.}

\item{n}{number of observations.}
}
\description{
These functions provide information about the stable distribution
with the location, the dispersion, the skewness and the tail thickness
respectively modelled by the parameters \code{loc}, \code{disp},
\code{skew} and  \code{tail}. These differ from those of 'stabledist' (i.e., Nolan's 0-parameterization and 
1-parameterization as detailed in Nolan (2020)). See the README for how to make equivalent calls
to those of 'stabledist' (i.e., Nolan's 0-parameterization and 
1-parameterization as detailed in Nolan (2020)).
}
\details{
\code{dstable}, \code{pstable}, \code{qstable} and \code{hstable}
compute the density, the distribution, the quantile and the hazard functions
of a stable variate. \code{rstable} generates random deviates with
the prescribed stable distribution.

\code{loc} is a location parameter in the same way as the mean
in the normal distribution: it can take any real value.

\code{disp} is a dispersion parameter in the same way as the standard
deviation in the normal distribution: it can take any positive value.

\code{skew} is a skewness parameter: it can take any value in \eqn{(-1,1)}.
The distribution is right-skewed, symmetric and left-skewed
when \code{skew} is negative, null or positive respectively.

\code{tail} is a tail parameter (often named the characteristic exponent):
 it can take any value in \eqn{(0,2)} (with \code{tail=1} and \code{tail=2}
                                       yielding the Cauchy and the normal distributions respectively
                                       when symmetry holds).

If \code{loc}, \code{disp}, \code{skew}, or \code{tail} are not
specified they assume the default values of \eqn{0}, \eqn{1/sqrt(2)},
\eqn{0} and \eqn{2} respectively. This corresponds to a normal
variate with mean\eqn{=0} and variance\eqn{=1/2 disp^2}.

The stable characteristic function is given by
\deqn{greekphi(t) = i loca t - disp {|t|}^{tail}  [1+i skew sign(t) greekomega(t,tail)]}{phi(t) = i loc t - disp |t|^tail [1+i skew sign(t) omega(t,tail)]}
where
\deqn{greekomega(t,tail) = \frac{2}{\pi} LOG(ABS(t))}{omega(t,tail) = (2/pi) log|t|}
when \code{tail=1}, and
\deqn{greekomega(t,tail) = tan(\frac{\pi tail}{2})}{omega(t,tail) = tan(pi alpha / 2)}
otherwise.

The characteristic function is inverted using Fourier's transform
to obtain the corresponding stable density. This inversion requires the
numerical evaluation of an integral from \eqn{0} to \eqn{\infty}{infinity}.
Two algorithms
are proposed for this. The default is Romberg's method
(\code{integration}="Romberg") which is used to evaluate the integral
with an error bounded by \code{eps}.
The alternative method is Simpson's integration
(\code{integration}="Simpson"): it approximates the
integral from \eqn{0} to \eqn{\infty}{infinity} by an integral
from \eqn{0} to \code{up}
with \code{npt} points subdividing \eqn{(O, up)}.
These three extra arguments -- \code{integration}, \code{up} and
\code{npt} -- are only available when using \code{dstable}.
The other functions are all based on Romberg's algorithm.

[Swihart 2022 update:] 


See the README for how to make equivalent calls
to those of 'stabledist' (i.e., Nolan's 0-parameterization and 1-parameterization 
as detailed in Nolan (2020)). 
See github for Lambert and Lindsey 1999 JRSS-C journal article, 
which details the parameterization of the Buck (1995) stable distribution which allowed
a Fourier inversion to arrive at a form similar to but not exactly the $g_d$ 
function as detailed in Nolan (2020),
Abdul-Hamid and Nolan (1998) and Nolan (1997).  
The Nolan (2020) reference is a textbook that provides
an accessible and comprehensive summary of stable distributions in the 25 years or so
since the core of this R package was made and put on CRAN.  
The Buck (1995) parameterization most closely resembles the Zolotarev B parameterization
outlined in Definition 3.6 on page 93 of Nolan (2020) -- except that Buck (1995) did
not allow the scale parameter to multiply with the location parameter.  
This explains why the `Zolotarev B` entry in Table 3.1 on page 97 of Nolan (2020) has
the location parameter being multiplied by the scale parameter whereas in converting the Lindsey and Lambert (1999)
to Nolan 1-parameterization the location parameter stays the same.  

To be clear, \code{stable::dstable} and \code{stable::pstable} are evaluated 
by numerically integrating the inverse Fourier transform.  The code works 
reasonably for small and moderate values of x, but will have numerical issues 
in some cases (such as values from \code{stable::pstable} being greater than 
1 or or not being monotonic).  The arguments \code{npt}, \code{up}, 
\code{integration}, and \code{eps} can be adjusted 
to improve accuracy at the cost of speed, but will still have limitations.
Functions that better handle these problems are available in other packages
(such as \code{stabledist} and \code{stable}) that use an alternative method
(as detailed in Nolan 1997)  
distinct from directly numerically integrating the Fourier inverse transform. 
See last example in the README.
}
\section{Functions}{
\itemize{
\item \code{dstable}: density

\item \code{pstable}: cdf

\item \code{qstable}: quantiles

\item \code{rstable}: random deviates

\item \code{hstable}: hazard
}}

\examples{
par(mfrow=c(2,2))
x <- seq(-5,5,by=0.1)

# Influence of loc (location)
plot(x,dstable(x,loc=-2,disp=1/sqrt(2),skew=-0.8,tail=1.5),
  type="l",ylab="",main="Varying LOCation")
lines(x,dstable(x,loc=0,disp=1/sqrt(2),skew=-0.8,tail=1.5))
lines(x,dstable(x,loc=2,disp=1/sqrt(2),skew=-0.8,tail=1.5))

# Influence of disp (dispersion)
plot(x,dstable(x,loc=0,disp=0.5,skew=0,tail=1.5),
  type="l",ylab="",main="Varying DISPersion")
lines(x,dstable(x,loc=0,disp=1/sqrt(2),skew=0,tail=1.5))
lines(x,dstable(x,loc=0,disp=0.9,skew=0,tail=1.5))

# Influence of skew (skewness)
plot(x,dstable(x,loc=0,disp=1/sqrt(2),skew=-0.8,tail=1.5),
  type="l",ylab="",main="Varying SKEWness")
lines(x,dstable(x,loc=0,disp=1/sqrt(2),skew=0,tail=1.5))
lines(x,dstable(x,loc=0,disp=1/sqrt(2),skew=0.8,tail=1.5))

# Influence of tail (tail)
plot(x,dstable(x,loc=0,disp=1/sqrt(2),skew=0,tail=0.8),
  type="l",ylab="",main="Varying TAIL thickness")
lines(x,dstable(x,loc=0,disp=1/sqrt(2),skew=0,tail=1.5))
lines(x,dstable(x,loc=0,disp=1/sqrt(2),skew=0,tail=2))

}
\references{
Lambert, P. and Lindsey, J.K. (1999) Analysing financial returns using
regression models based on non-symmetric stable distributions. Applied
Statistics, 48, 409-424.

Nolan, John P. Univariate stable distributions. Berlin/Heidelberg, Germany: Springer, 2020.

Nolan, John P. "Numerical calculation of stable densities and distribution functions." Communications in statistics. Stochastic models 13.4 (1997): 759-774.

Abdul-Hamid, Husein, and John P. Nolan. "Multivariate stable densities as functions of one dimensional projections." Journal of multivariate analysis 67.1 (1998): 80-89.
}
\seealso{
\code{\link[stable]{stablereg}} to fit generalized nonlinear regression models
for the stable distribution parameters. 
R packages \code{stabledist} and \code{libstableR} provide [dpqr] functions.
}
\author{
Philippe Lambert (Catholic University of Louvain, Belgium, \email{phlambert@stat.ucl.ac.be})

Jim Lindsey
}