% 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}
\alias{fitted.stable}
\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)

\method{fitted}{stable}(object, ...)
}
\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.}

\item{object}{the object of the default generic}

\item{...}{the usual R definition}
}
\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 of large x (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{Methods (by generic)}{
\itemize{
\item \code{fitted(stable)}: support functions

}}
\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
}
