Package 'Runuran'

Description

R interface to the UNU.RAN library for Universal Non-Uniform RANdom variate generators

Details

Runuran provides an interface to the UNU.RAN library for universal non-uniform random number generators. It provides a collection of so called automatic methods for non-uniform random variate generation. Thus it is possible to draw samples from uncommon distributions. Nevertheless, (some of) these algorithms are also well suited for standard distribution like the normal distribution. Moreover, sampling from distributions like the generalized hyperbolic distribution is very fast. Such distributions became recently popular in financial engineering.

Runuran compiles four sets of functions of increasing power (and thus complexity):

• [Special Generator] – Generators for particular distributions. Their syntax is similar to the corresponding R built-in functions.

• [Universal] – Functions that offer an interface to a carefully selected collection of UNU.RAN methods with their most important parameters.

• [Distribution] – Functions that create objects for important distributions. These objects can then be used in combination with one of the universal methods which is best suited for a particular application.

• [Advanced] – Wrapper to the UNU.RAN string API. This gives access to all UNU.RAN methods and their variants.

We have marked all functions in their corresponding help page by one these four tags.

An introduction to Runuran with examples together with a very short survey on non-uniform random variate generation can be found in the package vignette (which can be displayed using vignette("Runuran")).

[Special Generator]

These functions have similar syntax to the analogous R built-in generating functions (if these exist) but have optional domain arguments lb and ub, i.e., these calls also allow to draw samples from truncated distributions:

ur...(n, distribution parameters, lb , ub)

Compared to the corresponding R functions these ur... functions have a different behavior:

• ur... functions are often much faster for large samples (e.g., a factor of about 5 for the $t$ distribution). For small samples they are slow.

• All ur... functions allow to sample from truncated versions of the original distributions. Therefore the arguments lb (lower border) and ub (upper border) are available for all these functions.

• Almost all ur... functions are based on fast numerical inversion algorithms. This is important for example for generating order statistics, quasi-Monte Carlo methods or random vectors from copulas.

• All ur... functions do not allow vectors as arguments (to be more precise: they only use the first element of the vector).

However, we recommend to use the more flexible approach described in the next sections below.

A list of all available special generators can be found in Runuran.special.generators.

[Universal]

These functions allow access to a selected collection of UNU.RAN methods. They require some data about the target distribution as arguments and return an instance of a UNU.RAN generator object that is implemented as an S4 class unuran. These can then be used to draw samples from the desired distribution by means of function ur. Methods that implement an inversion method can also be used for quantile function uq.

Currently the following methods are available by such functions.

Continuous Univariate Distributions:

Discrete Distributions:

Multivariate Distributions:

[Distribution]

Coding the required functions for particular distributions can be tedious. Thus we have compiled a set of functions that create UNU.RAN distribution objects that can directly be used with the functions from section [Universal].

A list of all available distributions can be found in Runuran.distributions.

[Advanced]

This interface provides the most flexible access to UNU.RAN. It requires three steps:

1. Create a unuran.distr object that contains all required information about the target distribution. We have three types of distributions:

   Function		Type of distribution
   unuran.cont.new	...	continuous distributions
   unuran.discr.new	...	discrete distributions
   unuran.cmv.new	...	multivariate continuous distributions

   The functions from section [Distribution] creates such objects for particular distributions.

2. Choose a generation method and create a unuran object using function unuran.new. This function takes two argument: the distribution object created in Step 1, and a string that contains the chosen UNU.RAN method and (optional) some parameters to adjust this method to the given target distribution. We refer to the UNU.RAN for more details on this “method string”.

3. Use this object to draw samples from the target distribution using ur or uq.

   Function
   ur	...	draw sample
   uq	...	compute quantile (inverse CDF)
   unuran.details	...	show unuran object

Density and distribution function

UNU.RAN distribution objects and generator objects may also be used to compute density and distribution function for a given distribution by means of ud and up.

Uniform random numbers

All UNU.RAN methods use the R built-in random number generator as source of (pseudo-) random numbers. Thus the generated samples depend on the state .Random.seed and can be controlled by the R functions RNGkind and set.seed.

Warning

unuran objects cannot be saved and restored in later R sessions, nor is it possible to copy such objects to different nodes in a computer cluster.

However, unuran objects for some generation methods can be “packed”, see unuran.packed. Then these objects can be handled like any other R object (and thus saved and restored).

All other objects must be newly created in a new R session! (Using a restored object does not work as the "unuran" object is then broken.)

Note

The interface has been changed compared to the DSC 2003 paper.

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

J. Leydold and W. H\"ormann (2000-2008): UNU.RAN User Manual, see https://statmath.wu.ac.at/unuran/.

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg

G. Tirler and J. Leydold (2003): Automatic Nonuniform Random Variate Generation in R. In: K. Hornik and F. Leisch, Proceedings of the 3rd International Workshop on Distributed Statistical Computing (DSC 2003), March 20–22, Vienna, Austria.

See Also

All objects are implemented as respective S4 classes unuran, unuran.distr, unuran.cont, unuran.discr, unuran.

See Runuran.special.generators for an overview of special generators and Runuran.distributions for a list of ready-to-use distributions suitable for the automatic methods.

Description

UNU.RAN random variate generator for continuous distributions with given probability density function (PDF). It is based on the Automatic Ratio-Of-Uniforms method (‘AROU’).

[Universal] – Rejection Method.

Usage

arou.new(pdf, dpdf=NULL, lb, ub, islog=FALSE, ...)
aroud.new(distr)

Arguments

Details

This function creates an unuran object based on ‘AROU’ (Automatic Ratio-Of-Uniforms method). It can be used to draw samples of a continuous random variate with given probability density function using ur.

The density pdf must be positive but need not be normalized (i.e., it can be any multiple of a density function). The derivative dpdf of the (log-) density is optional. If omitted, numerical differentiation is used. Notice, however, that this might cause some round-off errors such that the algorithm fails. This is in particular the case when the density function is provided instead of the log-density.

The given pdf must be $T_{-0.5}$-concave (with implies unimodal densities with tails not higher than $(1/x^2)$; this includes all log-concave distributions).

It is recommended to use the log-density (instead of the density function) as this is numerically more stable.

Alternatively, one can use function aroud.new where the object distr of class "unuran.cont" must contain all required information about the distribution.

The setup time of this method depends on the given PDF, whereas its marginal generation times are almost independent of the target distribution.

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. See Section 4.8 (Automatic Ratio-Of-Uniforms).

See Also

ur, tdr.new, unuran.cont, unuran.new, unuran.

Examples

## Create a sample of size 100 for a Gaussian distribution
pdf <- function (x) { exp(-0.5*x^2) }
gen <- arou.new(pdf=pdf, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Create a sample of size 100 for a 
## Gaussian distribution (use logPDF)
logpdf <- function (x) { -0.5*x^2 }
gen <- arou.new(pdf=logpdf, islog=TRUE, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Same example but additionally provide derivative of log-density
## to prevent possible round-off errors
logpdf <- function (x) { -0.5*x^2 }
dlogpdf <- function (x) { -x }
gen <- arou.new(pdf=logpdf, dpdf=dlogpdf, islog=TRUE, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Draw sample from Gaussian distribution with mean 1 and
## standard deviation 2. Use 'dnorm'.
gen <- arou.new(pdf=dnorm, lb=-Inf, ub=Inf, mean=1, sd=2)
x <- ur(gen,100)

## Draw a sample from a truncated Gaussian distribution
## on domain [5,Inf)
logpdf <- function (x) { -0.5*x^2 }
gen <- arou.new(pdf=logpdf, lb=5, ub=Inf, islog=TRUE)
x <- ur(gen,100)

## Alternative approach
distr <- udnorm()
gen <- aroud.new(distr)
x <- ur(gen,100)

Description

UNU.RAN random variate generator for continuous distributions with given probability density function (PDF). It is based on Adaptive Rejection Sampling (‘ARS’).

[Universal] – Rejection Method.

Usage

ars.new(logpdf, dlogpdf=NULL, lb, ub, ...)
arsd.new(distr)

Arguments

Details

This function creates a unuran object based on ‘ARS’ (Adaptive Rejection Sampling). It can be used to draw samples from continuous distributions with given probability density function using ur.

Function logpdf is the logarithm the density function of the target distribution. It must be a concave function (i.e., the distribution must be log-concave). However, it need not be normalized (i.e., it can be a log-density plus some arbitrary constant).

The derivative dlogpdf of the log-density is optional. If omitted, numerical differentiation is used. Notice, however, that this might cause some round-off errors such that the algorithm fails.

Alternatively, one can use function arsd.new where the object distr of class "unuran.cont" must contain all required information about the distribution.

The setup time of this method depends on the given PDF, whereas its marginal generation times are almost independent of the target distribution.

‘ARS’ is a special case of method ‘TDR’ (see tdr.new). It is a bit slower and less flexible but numerically more stable. In particular, it is useful if one wants to sample from truncated distributions with extreme truncation points; or when the integral of the given “density” function is only known to be extremely large or small. However, this assumes that the log-density is computed analytically and not by just using log(pdf(x)).

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. See Chapter 4 (Tranformed Density Rejection).

W. R. Gilks and P. Wild (1992): Adaptive rejection sampling for Gibbs sampling. Applied Statistics 41(2), pp. 337–348.

See Also

ur, tdr.new, unuran.cont, unuran.new, unuran.

Examples

## Create a sample of size 100 for a 
## Gaussian distribution (use logPDF)
lpdf <- function (x) { -0.5*x^2 }
gen <- ars.new(logpdf=lpdf, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Same example but additionally provide derivative of log-density
## to prevent possible round-off errors
lpdf <- function (x) { -0.5*x^2 }
dlpdf <- function (x) { -x }
gen <- ars.new(logpdf=lpdf, dlogpdf=dlpdf, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Draw a sample from a truncated Gaussian distribution
## on domain [100,Inf)
lpdf <- function (x) { -0.5*x^2 }
gen <- ars.new(logpdf=lpdf, lb=50, ub=Inf)
x <- ur(gen,100)

## Alternative approach
distr <- udnorm()
gen <- arsd.new(distr)
x <- ur(gen,100)

Description

UNU.RAN random variate generator for discrete distributions with given probability mass function (PMF). It is based on Discrete Automatic Rejection Inversion (‘DARI’).

[Universal] – Rejection Method.

Usage

dari.new(pmf, lb, ub, mode=NA, sum=1, ...)
darid.new(distr)

Arguments

Details

This function creates an unuran object based on ‘DARI’ (Discrete Automatic Rejection Inversion). It can be used to draw samples of a discrete random variate with given probability mass function using ur.

Function pmf must be postive but need not be normalized (i.e., it can be any multiple of a probability mass function).

The given function must be $T_{-0.5}$-concave; this includes all log-concave distributions.

In addition the algorithm requires the location of the mode. If omitted then it is computed by a slow numerical search.

If the sum over all probabilities is different from 1 then a rough estimate of this sum is required.

Alternatively, one can use function darid.new where the object distr of class "unuran.discr" must contain all required information about the distribution.

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. See Section 10.2 (Tranformed Probability Rejection).

See Also

ur, unuran.discr, unuran.new, unuran.

Examples

## Create a sample of size 100 for a Binomial distribution
## with 1000 number if observations and probability 0.2
gen <- dari.new(pmf=dbinom, lb=0, ub=1000, size=1000, prob=0.2)
x <- ur(gen,100)

## Create a sample from a distribution with PMF
##  p(x) = 1/x^3, x >= 1  (Zipf distribution)
zipf <- function (x) { 1/x^3 }
gen <- dari.new(pmf=zipf, lb=1, ub=Inf)
x <- ur(gen,100)

## Alternative approach
distr <- udbinom(size=100,prob=0.3)
gen <- darid.new(distr)
x <- ur(gen,100)

Description

UNU.RAN random variate generator for discrete distributions with given probability vector. It applies the Alias-Urn method (‘DAU’).

[Universal] – Patchwork Method.

Usage

dau.new(pv, from=1)
daud.new(distr)

Arguments

Details

This function creates a unuran object based on ‘DAU’ (Discrete Alias-Urn method). It can be used to draw samples of a discrete random variate with given probability vector using ur.

Vector pv must be postive but need not be normalized (i.e., it can be any multiple of a probability vector).

The method runs fast in constant time, i.e., marginal sampling times do not depend on the length of the given probability vector. Whereas their setup times grow linearly with this length.

Notice that the range of random variates is from:(from+length(pv)-1).

Alternatively, one can use function daud.new where the object distr of class "unuran.discr" must contain all required information about the distribution.

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. See Section 3.2 (The Alias Method).

A.J. Walker (1977): An efficient method for generating discrete random variables with general distributions. ACM Trans. Model. Comput. Simul. 3, pp.253–256.

See Also

ur, unuran.discr, unuran.new, unuran.

Examples

## Create a sample of size 100 for a 
## binomial distribution with size=115, prob=0.5
gen <- dau.new(pv=dbinom(0:115,115,0.5), from=0)
x <- ur(gen,100)

## Alternative approach
distr <- udbinom(size=100,prob=0.3)
gen <- daud.new(distr)
x <- ur(gen,100)

Description

UNU.RAN random variate generator for discrete distributions with given probability vector. It applies the Guide-Table Method for discrete inversion (‘DGT’).

[Universal] – Inversion Method.

Usage

dgt.new(pv, from=1)
dgtd.new(distr)

Arguments

Details

This function creates an unuran object based on ‘DGT’ (Discrete Guide-Table method). It can be used to draw samples of a discrete random variate with given probability vector using ur. It also allows to compute quantiles by means of uq.

Vector pv must be postive but need not be normalized (i.e., it can be any multiple of a probability vector).

The method runs fast in constant time, i.e., marginal sampling times do not depend on the length of the given probability vector. Whereas their setup times grow linearly with this length.

Notice that the range of random variates is from:(from+length(pv)-1).

Alternatively, one can use function dgtd.new where the object distr of class "unuran.discr" must contain all required information about the distribution.

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. See Section 3.1.2 (Indexed Search).

H.C. Chen and Y. Asau (1974): On generating random variates from an empirical distribution. AIIE Trans. 6, pp.163–166.

See Also

ur, uq, unuran.discr, unuran.new, unuran.

Examples

## Create a sample of size 100 for a 
## binomial distribution with size=115, prob=0.5
gen <- dgt.new(pv=dbinom(0:115,115,0.5),from=0)
x <- ur(gen,100)

## Alternative approach
distr <- udbinom(size=100,prob=0.3)
gen <- dgtd.new(distr)
x <- ur(gen,100)

Description

UNU.RAN random variate generator for continuous multivariate distributions with given probability density function (PDF). It is based on the Hit-and-Run algorithm in combinaton with the Ratio-of-Uniforms method (‘HITRO’).

[Universal] – MCMC (Markov chain sampler).

Usage

hitro.new(dim=1, pdf, ll=NULL, ur=NULL, mode=NULL, center=NULL,
          thinning=1, burnin=0, ...)

Arguments

Details

Beware: MCMC sampling can be dangerous!

This function creates a unuran object based on the Hit-and-Run algorithm in combinaton with the Ratio-of-Uniforms method (‘HITRO’). It can be used to draw samples of a continuous random vector with given probability density function using ur.

The algorithm works best with log-concave distributions. Other distributions work as well but convergence can be slower.

The density must be provided by a function pdf which must return non-negative numbers and but need not be normalized (i.e., it can be any multiple of a density function).

The center is used as starting point of the Hit-and-Run algorithm. It is thus important, that the center is contained in the (interior of the) domain. Alternatively, one could provide the location of the mode. However, this requires its exact position whereas center allows any point in the “typical” region of the distribution.

If the mode is given, then it is used to obtain an upper bound on the pdf and thus its location should be given sufficiently accurate.

The ‘HITRO’ algorithm is a MCMC samplers and thus it does not produce a sequence of independent variates. The drawn sample follows the target distribution only approximately. The dependence between consecutive vectors can be decreased when only a subsequence is returned (and the other elements are erased). This is called “thinning” of the Markov chain and can be controlled by the thinning factor. A thinning factor $k$ means that only every $k$-th element is returned.

Markov chains also depend on the chosen starting point (i.e., the center in this implementation of the algorithm). This dependence can be decreased by erasing the first part of the chain. This is called the “burn-in” of the Markov chain and its length is controlled by the argument burnin.

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

R. Karawatzki, J. Leydold, and K. P\"otzelberger (2005): Automatic Markov Chain Monte Carlo Procedures for Sampling from Multivariate Distributions. Research Report Series / Department of Statistics and Mathematics, Nr. 27, December 2005 Department of Statistics and Mathematics, Wien, Wirtschaftsuniv., 2005. doi:10.57938/168a5370-8110-4aaa-878a-8add2de7e245, https://research.wu.ac.at/en/publications/automatic-markov-chain-monte-carlo-procedures-for-sampling-from-m-7

See Also

ur, unuran.new, unuran.

Examples

## Create a sample of size 100 for a 
## Gaussian distribution
mvpdf <- function (x) { exp(-sum(x^2)) }
gen <- hitro.new(dim=2, pdf=mvpdf)
x <- ur(gen,100)

## Use mode of Gaussian distribution.
## Reduce auto-correlation by thinning and burn-in.
##  mode at (0,0)
##  thinning factor 3
##    (only every 3rd vector in the sequence is returned)
##  burn-in of length 1000
##    (the first 100 vectors in the sequence are discarded)
mvpdf <- function (x) { exp(-sum(x^2)) }
gen <- hitro.new(dim=2, pdf=mvpdf, mode=c(0,0), thinning=3, burnin=1000)
x <- ur(gen,100)

## Gaussian distribution restricted to the rectangle [1,2]x[1,2]
##  (don't forget to provide a starting point using 'center')
mvpdf <- function (x) { exp(-sum(x^2)) }
gen <- hitro.new(dim=2, pdf=mvpdf, center=c(1.1,1.1), ll=c(1,1), ur=c(2,2))
x <- ur(gen,100)

Description

UNU.RAN random variate generator for continuous distributions with given probability density function (PDF). It is based on the Inverse Transformed Density Rejection method (‘ITDR’).

[Universal] – Rejection Method.

Usage

itdr.new(pdf, dpdf, lb, ub, pole, islog=FALSE, ...)
itdrd.new(distr)

Arguments

Details

This function creates a unuran object based on “ITDR” (Inverse Transformed Density Rejection). It can be used to draw samples of a continuous random variate with given probability density function using ur.

The density pdf must be positive but need not be normalized (i.e., it can be any multiple of a density function). The algorithm is especially designed for distributions with unbounded densities. Thus the algorithm needs the position of the pole. Moreover, the given function must be monotone on its domain.

The derivative dpdf is essential. (Numerical derivation does not work as it results in serious round-off errors.)

Alternatively, one can use function itdrd.new where the object distr of class "unuran.cont" must contain all required information about the distribution.

The setup time of this method depends on the given PDF, whereas its marginal generation times are almost independent of the target distribution.

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2007): Inverse transformed density rejection for unbounded monotone densities. ACM Trans. Model. Comput. Simul. 17(4), Article 18, 16 pages. DOI: 10.1145/1276927.1276931

See Also

ur, unuran.cont, unuran.new, unuran.

Examples

## Create a sample of size 100 for a Gamma(0.5) distribution
pdf <- function (x) { x^(-0.5)*exp(-x) }
dpdf <- function (x) { (-x^(-0.5) - 0.5*x^(-1.5))*exp(-x) }
gen <- itdr.new(pdf=pdf, dpdf=dpdf, lb=0, ub=Inf, pole=0)
x <- ur(gen,100)

## Alternative approach
distr <- udgamma(shape=0.5)
gen <- itdrd.new(distr)
x <- ur(gen,100)

Description

UNU.RAN random variate generator for a finite mixture of continuous or discrete distributions. The components are given as unuran objects.

[Universal] – Composition Method.

Usage

mixt.new(prob, comp, inversion=FALSE)

Arguments

Details

Given a set of probability density functions $p_1(x),\dots,p_n(x)$ (called the mixture components) and weights $w_1,\dots,w_n$ such that $w_i \ge 0$ and $\sum w_i = 1$, the sum

$q(x) = \sum_{i=1}^n \, w_i \, p_i(x)$

is called the mixture density.

Function mixt.new creates an unuran object for a finite mixture of continuous or discrete univariate distributions. It can be used to draw samples of a continuous random variate using ur.

The weights prob must be a vector of non-negative numbers (not all equal to 0) but need not sum to 1.

comp is a list of "unuran" generator objects. Each of which must sample from a continuous or discrete univariate distribution.

If inversion is TRUE, then the inversion method is used for sampling from the mixture distribution. However, the following conditions must be satisfied:

• Each component (unuran object) must use implement an inversion method (i.e., the quantile funtion uq must work).

• The domains of the components must not overlapping.

• The components must be order with respect to their domains.

If one of these conditions is violated, then initialization of the mixture object fails.

The setup time is fast, whereas its marginal generation times strongly depend on the average generation times of its components.

Value

An object of class "unuran".

Note

Each component in comp must correspond to a continuous or discrete univariate distribution. In particular this also includes mixtures of distributions. Thus mixtures can also be defined recursively.

Moreover, none of these components must be packed (see unuran.packed).

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. See Section 2.3 (Composition).

See Also

ur, uq, unuran.new, unuran.

Examples

## Create a mixture of an Exponential and a Half-normal distribution
unr1 <- unuran.new(udnorm(lb=-Inf, ub=0))
unr2 <- unuran.new(udexp())
mix <- mixt.new( c(1,1), c(unr1, unr2) )
x <- ur(mix,100)

## Now use inversion method:
## It is important that
##  1. we use a inversion for each component
##  2. the domains to not overlap
##  3. the components are ordered with respect to their domains
unr1 <- pinvd.new(udnorm(lb=-Inf, ub=0))
unr2 <- pinvd.new(udexp())
mix <- mixt.new( c(1,1), c(unr1, unr2), inversion=TRUE )
x <- ur(mix,100)

## We also can compute the inverse distribution function
##x <- uq(mix,0.90)

## Create a mixture of Exponential and Geometric distrbutions
unr1 <- unuran.new(udexp())
unr2 <- unuran.new(udgeom(0.7))
mix <- mixt.new( c(0.6,0.4), c(unr1, unr2) )
x <- ur(mix,100)

Description

UNU.RAN random variate generator for continuous distributions with given probability density function (PDF) or cumulative distribution function (CDF). It is based on the Polynomial interpolation of INVerse CDF (‘PINV’).

[Universal] – Inversion Method.

Usage

pinv.new(pdf, cdf, lb, ub, islog=FALSE, center=0,
         uresolution=1.e-10, smooth=FALSE, ...)
pinvd.new(distr, uresolution=1.e-10, smooth=FALSE)

Arguments

Details

This function creates an unuran object based on ‘PINV’ (Polynomial interpolation of INVerse CDF). It can be used to draw samples of a continuous random variate with given probability density function pdf or cumulative distribution function cdf by means of ur. It also allows to compute quantiles by means of uq.

Function pdf must be positive but need not be normalized (i.e., it can be any multiple of a density function). The set of points where the pdf is strictly positive must be connected. The center is a point where the pdf is not too small, e.g., (a point near) the mode of the distribution.

If the density pdf is given, then the algorithm automatically computes the CDF using Gauss-Lobatto integration. If the cdf is given but not the pdf then the CDF is used instead of the PDF. However, we found in our experiments that using the PDF is numerically more stable.

Alternatively, one can use function pinvd.new where the object distr of class "unuran.cont" must contain all required information about the distribution.

The algorithm approximates the inverse of the CDF of the distribution by means of Newton interpolation between carefully selected nodes. The approxiating functing is thus continuous. Argument smooth controls whether this function is also differentiable(“smooth”) at the nodes. Using smooth=TRUE requires the pdf of the distribution. It results in a higher setup time and memory consumption. Thus using smooth=TRUE is not not recommended, unless differentiability is important.

The approximation error is estimated by means of the the u-error, i.e., $|CDF(G(U)) - U|$, where $G$ denotes the approximation of the inverse CDF. The error can be controlled by means of argument uresolution.

When sampling from truncated distributions with extreme truncation points, it is recommended to provide the log-density by setting islog=TRUE. Then the algorithm is numerically more stable.

The setup time of this method depends on the given PDF, whereas its marginal generation times are independent of the target distribution.

Value

An object of class "unuran".

Remark

Using function up generator objects that implement method ‘PINV’ may also be used to approximate the cumulative distribution function of the given distribution when only the density is given. The approximation error is about one tenth of the requested uresolution.

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

G. Derflinger, W. H\"ormann, and J. Leydold (2010): Random variate generation by numerical inversion when only the density is known. ACM Trans. Model. Comput. Simul., 20:4, #18

See Also

ur, uq, up, unuran.cont, unuran.new, unuran.

Examples

## Create a sample of size 100 for a Gaussian distribution
pdf <- function (x) { exp(-0.5*x^2) }
gen <- pinv.new(pdf=pdf, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Create a sample of size 100 for a 
## Gaussian distribution (use logPDF)
logpdf <- function (x) { -0.5*x^2 }
gen <- pinv.new(pdf=logpdf, islog=TRUE, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Draw sample from Gaussian distribution with mean 1 and
## standard deviation 2. Use 'dnorm'.
gen <- pinv.new(pdf=dnorm, lb=-Inf, ub=Inf, mean=1, sd=2)
x <- ur(gen,100)

## Draw a sample from a truncated Gaussian distribution
## on domain [2,Inf)
gen <- pinv.new(pdf=dnorm, lb=2, ub=Inf)
x <- ur(gen,100)

## Improve the accuracy of the approximation
gen <- pinv.new(pdf=dnorm, lb=-Inf, ub=Inf, uresolution=1e-15)
x <- ur(gen,100)

## We have to provide a 'center' when PDF (almost) vanishes at 0.
gen <- pinv.new(pdf=dgamma, lb=0, ub=Inf, center=4, shape=5)
x <- ur(gen,100)

## We also can force a smoother approximation
gen <- pinv.new(pdf=dnorm, lb=-Inf, ub=Inf, smooth=TRUE)
x <- ur(gen,100)

## Alternative approach
distr <- udnorm()
gen <- pinvd.new(distr)
x <- ur(gen,100)

Description

Create objects for particular distributions suitable for using with generation methods from the UNU.RAN library.

Details

Runuran provides an interface to the UNU.RAN library for universal non-uniform random number generators. This is a very flexible and powerful collection of sampling routines, where the user first has to specify the target distribution and then has to choose an appropriate sampling method.

Creating an object for a particular distribution can be a bit tedious especially if the target distribution has a more complex density function. Thus we have compiled a set of functions that provides ready-to-use distribution objects. Moreover, using these object often results in faster setup time than objects created with pure R code.

These functions share a similar syntax and naming scheme (only ud is prefixed) with analogous R built-in functions that provide density, distribution function and quantile:

ud...(distribution parameters, lb , ub)

Currently generators for the following distributions are implemented.

Continuous Univariate Distributions (26):

Discrete Distributions (6):

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

See Also

Runuran-package.

Examples

## Create an object for a gamma distribution with shape parameter 5.
distr <- udgamma(shape=5)
## Create the UNU.RAN generator object. use method PINV (inversion).
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen, 100)
## Compute some quantiles for Monte Carlo methods
x <- uq(gen, (1:9)/10)

## Analogous for half normal distribution
distr <- udnorm(lb=0, ub=Inf)
gen <- pinvd.new(distr)
x <- ur(gen, 100)
x <- uq(gen, (1:9)/10)

## Analogous for a generalized hyperbolic distribution
distr <- udghyp(lambda=-1.0024, alpha=39.6, beta=4.14, delta=0.0118, mu=-0.000158)
gen <- pinvd.new(distr)
x <- ur(gen, 100)
x <- uq(gen, (1:9)/10)

## It is also possible to compute density or distribution functions.
## However, this might not work for all generator objects.
##    Density
x <- ud(gen, 1.2)
##    Cumulative distribution function
x <- up(gen, 1.2)

Description

Library Runuran has some parameters which (usually) affect the behavior of its functions. These can be set for the whole session via Runuran.options.

Usage

Runuran.options(...)

Arguments

Details

The function provides a tool to control the behavior of library Runuran. A list may be given as the only argument, or any number of arguments may be in the name=value form. If no arguments are specified then the function returns the current settings of all parameters. If a single option name is given as character string, then its value is returned (or NULL if it does not exist). Option values may be abbreviated.

Currently used parameters in alphabetical order:

error.level

verbosity level of error messages and warnings from the underlying UNU.RAN library. It has no effect on messages from the routines in this package. Warnings are useful for analysing possible problems with the selected combinations of distribution and method. However, they can produce quite a lot of output if the conditions of the method is appropriate for a distribution or the distribution has properties like very heavy tails or very high peaks.

The following levels can be set:

"default":

same as "warning".

"none":

all error messages and warnings are suppressed.

"error":

only show error messages.

"warning":

show error messages and some of the warnings.

"all":

show all error messages and warnings.

Value

Runuran.options returns a list with the updated values of the parameters. If the argument list is not empty, the returned list is invisible. If a single character string is given, then the value of the corresponding parameter is returned (or NULL if the parameter is not used).

Author(s)

Josef Leydold [email protected]

Examples

## save current options
oldval <- Runuran.options()

## show current options
Runuran.options("error.level")

## suppress all UNU.RAN error messages and warnings
Runuran.options(error.level="none")

## restore Runuran options
Runuran.options(oldval)

Description

Generators for particular distributions. Their syntax is similar to the corresponding R built-in functions.

Details

Runuran provides an interface to the UNU.RAN library for universal non-uniform random number generators. This is a very flexible and powerful collection of sampling routines, where the user first has to specify the target distribution and then has to choose an appropriate sampling method. However, we found that this approach is a little bit confusing for the beginner.

Thus we have prepared easy-to-use sampling functions for standard distributions to facilitate the use of the package. All these functions share a similar syntax and naming scheme (only u is prefixed) with their analogous R built-in generating functions (if these exist) but have optional domain arguments lb and ub, i.e., these calls also allow to draw samples from truncated distributions:

ur...(n, distribution parameters, lb , ub)

These functions also show the interested user how we used the more powerful functions. We recommend to directly use these more flexible functions. Then one has faster marginal generation times and one may choose the best generation method for one's application.

Currently generators for the following distributions are implemented.

Continuous Univariate Distributions (24):

Discrete Distributions (6):

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

See Also

Runuran-package, Runuran.distributions.

Examples

## draw a sample of size 100 from a
## gamma distribution with shape parameter 5
x <- urgamma(n=100, shape=5)

## draw a sample of size 100 from a
## half normal distribution
x <- urnorm(n=100, lb=0, ub=Inf)

Description

UNU.RAN random variate generator for continuous distributions with given probability density function (PDF). It is based on the Simple Ratio-Of-Uniforms Method (‘SROU’).

[Universal] – Rejection Method.

Usage

srou.new(pdf, lb, ub, mode, area, islog=FALSE, r=1, ...)
sroud.new(distr, r=1)

Arguments

Details

This function creates a unuran object based on ‘SROU’ (Simple Ratio-Of-Uniforms Method). It can be used to draw samples of a continuous random variate with given probability density function using ur.

The density pdf must be positive but need not be normalized (i.e., it can be any multiple of a density function). It must be $T_c$-concave for $c = -r/(r+1)$; this includes all log-concave distributions.

The (exact) location of the mode and the area below the pdf are essential.

Alternatively, one can use function sroud.new where the object distr of class "unuran.cont" must contain all required information about the distribution.

The acceptance probability decreases with increasing parameter r. Thus it should be as small as possible. On the other hand it must be sufficiently large for heavy tailed distributions. If possible, use the default r=1.

Compared to tdr.new it has much slower marginal generation times but has a faster setup and is numerically more robust. Moreover, It also works for unimodal distributions with tails that are heavier than those of the Cauchy distribution.

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. Sections 6.3 and 6.4.

See Also

ur, unuran.cont, unuran.new, unuran.

Examples

## Create a sample of size 100 for a Gaussian distribution.
pdf <- function (x) { exp(-0.5*x^2) }
gen <- srou.new(pdf=pdf, lb=-Inf, ub=Inf, mode=0, area=2.506628275)
x <- ur(gen,100)

## Create a sample of size 100 for a Gaussian distribution.
## Use 'dnorm'.
gen <- srou.new(pdf=dnorm, lb=-Inf, ub=Inf, mode=0, area=1)
x <- ur(gen,100)

## Alternative approach
distr <- udnorm()
gen <- sroud.new(distr)
x <- ur(gen,100)

Description

UNU.RAN random variate generator for continuous distributions with given probability density function (PDF). It is based on the TABLe based rejection method (‘TABL’).

[Universal] – Rejection Method.

Usage

tabl.new(pdf, lb, ub, mode, islog=FALSE, ...)
tabld.new(distr)

Arguments

Details

This function creates an unuran object based on ‘TABL’ (TABLe based rejection). It can be used to draw samples of a continuous random variate with given probability density function using ur.

The density pdf must be positive but need not be normalized (i.e., it can be any multiple of a density function).

The given pdf must be unimodal.

Alternatively, one can use function tabld.new where the object distr of class "unuran.cont" must contain all required information about the distribution.

The setup time of this method depends on the given PDF, whereas its marginal generation times are almost independent of the target distribution.

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. See Section 5.1 (“Ahrens Method”).

See Also

ur, tdr.new, unuran.cont, unuran.new, unuran.

Examples

## Create a sample of size 100 for a Gaussian distribution
pdf <- function (x) { exp(-0.5*x^2) }
gen <- tabl.new(pdf=pdf, lb=-Inf, ub=Inf, mode=0)
x <- ur(gen,100)

## Create a sample of size 100 for a 
## Gaussian distribution (use logPDF)
logpdf <- function (x) { -0.5*x^2 }
gen <- tabl.new(pdf=logpdf, islog=TRUE, lb=-Inf, ub=Inf, mode=0)
x <- ur(gen,100)

## Draw sample from Gaussian distribution with mean 1 and
## standard deviation 2. Use 'dnorm'.
gen <- tabl.new(pdf=dnorm, lb=-Inf, ub=Inf, mode=1, mean=1, sd=2)
x <- ur(gen,100)

## Draw a sample from a truncated Gaussian distribution
## on domain [5,Inf)
logpdf <- function (x) { -0.5*x^2 }
gen <- tabl.new(pdf=logpdf, lb=5, ub=Inf, mode=5, islog=TRUE)
x <- ur(gen,100)

## Alternative approach
distr <- udnorm()
gen <- tabld.new(distr)
x <- ur(gen,100)

Description

UNU.RAN random variate generator for continuous distributions with given probability density function (PDF). It is based on the Transformed Density Rejection method (‘TDR’).

[Universal] – Rejection Method.

Usage

tdr.new(pdf, dpdf=NULL, lb, ub, islog=FALSE, ...)
tdrd.new(distr)

Arguments

Details

This function creates an unuran object based on ‘TDR’ (Transformed Density Rejection). It can be used to draw samples of a continuous random variate with given probability density function using ur.

The density pdf must be positive but need not be normalized (i.e., it can be any multiple of a density function). The derivative dpdf of the (log-) density is optional. If omitted, numerical differentiation is used. Notice, however, that this might cause some round-off errors such that the algorithm fails. This is in particular the case when the density function is provided instead of the log-density.

The given pdf must be $T_{-0.5}$-concave (with implies unimodal densities with tails not higher than $(1/x^2)$; this includes all log-concave distributions).

It is recommended to use the log-density (instead of the density function) as this is numerically more stable.

Alternatively, one can use function tdrd.new where the object distr of class "unuran.cont" must contain all required information about the distribution.

The setup time of this method depends on the given PDF, whereas its marginal generation times are almost independent of the target distribution.

There exists a variant of ‘TDR’ which is numerically more stable (albeit a bit slower and less flexible) which is avaible via the ars.new function.

Value

An object of class "unuran".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg. See Chapter 4 (Tranformed Density Rejection).

See Also

ur, ars.new, unuran.cont, unuran.new, unuran.

Examples

## Create a sample of size 100 for a Gaussian distribution
pdf <- function (x) { exp(-0.5*x^2) }
gen <- tdr.new(pdf=pdf, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Create a sample of size 100 for a 
## Gaussian distribution (use logPDF)
logpdf <- function (x) { -0.5*x^2 }
gen <- tdr.new(pdf=logpdf, islog=TRUE, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Same example but additionally provide derivative of log-density
## to prevent possible round-off errors
logpdf <- function (x) { -0.5*x^2 }
dlogpdf <- function (x) { -x }
gen <- tdr.new(pdf=logpdf, dpdf=dlogpdf, islog=TRUE, lb=-Inf, ub=Inf)
x <- ur(gen,100)

## Draw sample from Gaussian distribution with mean 1 and
## standard deviation 2. Use 'dnorm'.
gen <- tdr.new(pdf=dnorm, lb=-Inf, ub=Inf, mean=1, sd=2)
x <- ur(gen,100)

## Draw a sample from a truncated Gaussian distribution
## on domain [5,Inf)
logpdf <- function (x) { -0.5*x^2 }
gen <- tdr.new(pdf=logpdf, lb=5, ub=Inf, islog=TRUE)
x <- ur(gen,100)

## Alternative approach
distr <- udnorm()
gen <- tdrd.new(distr)
x <- ur(gen,100)

Description

Evaluates the probability density function (PDF) or probability mass function (PMF) for a "unuran" object for a continuous and discrete distribution, respectively.

Usage

ud(obj, x, islog = FALSE)

Arguments

Details

The routine evaluates the probability density function of a distribution stored in a UNU.RAN distribution object or UNU.RAN generator object. If islog is TRUE, then the logarithm of the density is returned.

If the PDF (or its respective logarithm) is not available in the object, then NA is returned and a warning is thrown.

Note: when the log-density is not given explicitly (by setting islog=TRUE in the corresponding routing like unuran.cont.new or in an Runuran built-in distribution), then NA is returned even if the density is given.

Important: Routine ud just evaluates the density function that is stored in obj. It ignores the boundaries of the domain of the distribution, i.e., it does not return 0 outside the domain unless the implementation of the PDF handles this case correctly. This behavior is in particular important when Runuran built-in distributions are truncated by explicitly setting the domain boundaries.

Note

The generator object must not be packed (see unuran.packed).

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

W. H\"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg.

See Also

unuran.cont, unuran.discr, unuran.

Examples

## Create an UNU.RAN distribution object (for standard Gaussian)
## and evaluate density for some points
distr <- udnorm()
ud(distr, 1.5)
ud(distr, -3:3)

## Create an UNU.RAN generator object (for standard Gaussian)
## and evaluate density of underyling distribution
gen <- tdrd.new(udnorm())
ud(gen, 1.5)
ud(gen, -3:3)

Description

Create UNU.RAN object for a Beta distribution with with parameters shape1 and shape2.

[Distribution] – Beta.

Usage

udbeta(shape1, shape2, lb=0, ub=1)

Arguments

Details

The Beta distribution with parameters shape1 $= a$ and shape2 $= b$ has density

$f(x) = \frac{\Gamma(a+b)}{\Gamma(a)\Gamma(b)}{x}^{a} {(1-x)}^{b}$

for $a > 0$, $b > 0$ and $0 \le x \le 1$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1995): Continuous Univariate Distributions, Volume 2. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 25, p. 210.

See Also

unuran.cont.

Examples

## Create distribution object for beta distribution
distr <- udbeta(shape1=3,shape2=7)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Binomial distribution with parameters size and prob.

[Distribution] – Binomial.

Usage

udbinom(size, prob, lb=0, ub=size)

Arguments

Details

The Binomial distribution with size $= n$ and prob $= p$ has probability mass function

$p(x) = {n \choose x} {p}^{x} {(1-p)}^{n-x}$

for $x = 0, \ldots, n$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.discr".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and A.W. Kemp (1992): Univariate Discrete Distributions. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 3, p. 105.

See Also

unuran.discr.

Examples

## Create distribution object for Binomial distribution
dist <- udbinom(size=100, prob=0.33)
## Generate generator object; use method DGT (inversion)
gen <- dgtd.new(dist)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Cauchy distribution with location parameter location and scale parameter scale.

[Distribution] – Cauchy.

Usage

udcauchy(location=0, scale=1, lb=-Inf, ub=Inf)

Arguments

Details

The Cauchy distribution with location $l$ and scale $s$ has density

$f(x) = \frac{1}{\pi s} \left( 1 + \left(\frac{x - l}{s}\right)^2 \right)^{-1}$

for all $x$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 16, p. 299.

See Also

unuran.cont.

Examples

## Create distribution object for Cauchy distribution
distr <- udcauchy()
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Chi distribution with df degrees of freedom.

[Distribution] – Chi.

Usage

udchi(df, lb=0, ub=Inf)

Arguments

Details

The Chi distribution with df$= n > 0$ degrees of freedom has density

$f(x) = x^{n-1} e^{-x^2/2}$

for $x > 0$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 18, p. 417.

See Also

unuran.cont.

Examples

## Create distribution object for chi-squared distribution
distr <- udchi(df=5)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Chi-squared ($\chi^2$) distribution with df degrees of freedom.

[Distribution] – Chi-squared.

Usage

udchisq(df, lb=0, ub=Inf)

Arguments

Details

The Chi-squared distribution with df$= n > 0$ degrees of freedom has density

$f_n(x) = \frac{1}{{2}^{n/2} \Gamma (n/2)} {x}^{n/2-1} {e}^{-x/2}$

for $x > 0$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 18, p. 416

See Also

unuran.cont.

Examples

## Create distribution object for chi-squared distribution
distr <- udchisq(df=5)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for an Exponential distribution with rate rate (i.e., mean 1/rate).

[Distribution] – Exponential.

Usage

udexp(rate=1, lb=0, ub=Inf)

Arguments

Details

The Exponential distribution with rate $\lambda$ has density

$f(x) = \lambda {e}^{- \lambda x}$

for $x \ge 0$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 19, p. 494.

See Also

unuran.cont.

Examples

## Create distribution object for standard exponential distribution
distr <- udexp()
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for an F distribution with mean with df1 and df2 degrees of freedom.

[Distribution] – F.

Usage

udf(df1, df2, lb=0, ub=Inf)

Arguments

Details

The F distribution with df1 = $n_1$ and df2 = $n_2$ degrees of freedom has density

$f(x) = \frac{\Gamma(n_1/2 + n_2/2)}{\Gamma(n_1/2)\Gamma(n_2/2)} \left(\frac{n_1}{n_2}\right)^{n_1/2} x^{n_1/2 -1} \left(1 + \frac{n_1 x}{n_2}\right)^{-(n_1 + n_2) / 2}$

for $x > 0$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1995): Continuous Univariate Distributions, Volume 2. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 27, p. 332

See Also

unuran.cont.

Examples

## Create distribution object for F distribution
distr <- udf(df1=3,df2=6)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Frechet (Extreme value type II) distribution with shape parameter shape, location parameter location and scale parameter scale.

[Distribution] – Frechet (Extreme value type II).

Usage

udfrechet(shape, location=0, scale=1, lb=location, ub=Inf)

Arguments

Details

The Frechet distribution function with shape $k$, location $l$ and scale $s$ is

$F(x) = \exp(-(\frac{x-l}{s})^{-k})$

for $x \ge l$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Note

This function is a wrapper for the UNU.RAN class in R.

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1995): Continuous Univariate Distributions, Volume 2. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 22, p. 2.

See Also

unuran.cont.

Examples

## Create distribution object for Frechet distribution
distr <- udfrechet(shape=2)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Gamma distribution with parameters shape and scale.

[Distribution] – Gamma.

Usage

udgamma(shape, scale=1, lb=0, ub=Inf)

Arguments

Details

The Gamma distribution with parameters shape $=\alpha$ and scale $=\sigma$ has density

$f(x) = \frac{1}{{\sigma}^{\alpha}\Gamma(\alpha)} {x}^{\alpha-1} e^{-x/\sigma}$

for $x \ge 0$, $\alpha > 0$ and $\sigma > 0$. (Here $\Gamma(\alpha)$ is the function implemented by R's gamma() and defined in its help.)

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 17, p. 337.

See Also

unuran.cont.

Examples

## Create distribution object for gamma distribution
distr <- udgamma(shape=4)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Geometric distribution with parameter prob.

[Distribution] – Geometric.

Usage

udgeom(prob, lb = 0, ub = Inf)

Arguments

Details

The Geometric distribution with prob $= p$ has density

$p(x) = p (1-p)^x$

for $x = 0, 1, 2, \ldots$, $0 < p \le 1$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.discr".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and A.W. Kemp (1992): Univariate Discrete Distributions. 2nd edition, John Wiley & Sons, Inc., New York. Sect. 5.2, p. 201

Examples

## Create distribution object for Geometric distribution
dist <- udgeom(prob=0.33)
## Generate generator object; use method DARI
gen <- darid.new(dist)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Generalized Hyperbolic distribution with shape parameter lambda, shape parameter alpha, asymmetry (shape) parameter beta, scale parameter delta, and location parameter mu.

[Distribution] – Generalized Hyperbolic.

Usage

udghyp(lambda, alpha, beta, delta, mu, lb=-Inf, ub=Inf)

Arguments

Details

The generalized hyperbolic distribution with parameters $\lambda$, $\alpha$, $\beta$, $\delta$, and $\mu$ has density

$f(x) = \kappa \; (\delta^2+(x-\mu)^2)^{1/2 (\lambda-1/2)} \cdot \exp(\beta(x-\mu)) \cdot K_{\lambda-1/2}\left(\alpha\sqrt{\delta^2+(x-\mu)^2}\right)$

where the normalization constant is given by

$\kappa = \frac{\left(\sqrt{\alpha^2 - \beta^2}/\delta\right)^{\lambda}}{ \sqrt{2\pi} \, \alpha^{\lambda-1/2} \, K_{\lambda}\left(\delta \sqrt{\alpha^2-\beta^2}\right)}$

$K_{\lambda}(t)$ is the modified Bessel function of the third kind with index $\lambda$.

Notice that $\alpha>|\beta|$ and $\delta>0$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

Barndorff-Nielsen, O., Blaesild, P., 1983. Hyperbolic distributions. In: Johnson, N. L., Kotz, S., Read, C. B. (Eds.), Encyclopedia of Statistical Sciences. Vol. 3. Wiley, New York, p. 700–707.

Prause, K., 1997. Modelling financial data using generalized hyperbolic distributions. FDM preprint 48, University of Freiburg.

Prause, K., 1999. The generalized hyperbolic model: Estimation, financial derivatives, and risk measures. Ph.D. thesis, University of Freiburg.

See Also

unuran.cont.

Examples

## Create distribution object for generalized hyperbolic distribution
distr <- udghyp(lambda=-1.0024, alpha=39.6, beta=4.14, delta=0.0118, mu=-0.000158)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Generalized Inverse Gaussian distribution. Two parametrizations are available.

[Distribution] – Generalized Inverse Gaussian.

Usage

udgig(theta, psi, chi, lb=0, ub=Inf)
udgiga(theta, omega, eta=1, lb=0, ub=Inf)

Arguments

Details

The generalized inverse Gaussian distribution with parameters $\theta$, $\psi$, and $\chi$ has density proportional to

$f(x) = x^{\theta-1} \exp\left( -\frac{1}{2} \left(\psi x + \frac{\chi}{x}\right)\right)$

where $\psi>0$ and $\chi>0$.

An alternative parametrization used parameters $\theta$, $\omega$, and $\eta$ and has density proportional to

$f(x) = x^{\theta-1} \exp\left( -\frac{\omega}{2} \left(\frac{x}{\eta}+\frac{\eta}{x}\right)\right)$

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Note

These two parametrizations can be converted into each other by means of the following transformations:

$\psi = \frac{\omega}{\eta},\;\;\; \chi = \omega\eta$

$\omega = \sqrt{\chi\psi},\;\;\; \eta = \sqrt{\frac{\chi}{\psi}}$

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 15, p. 284.

See Also

unuran.cont.

Examples

## Create distribution object for GIG distribution
distr <- udgig(theta=3, psi=1, chi=1)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Gumbel (Extreme value type I) distribution location parameter location and scale parameter scale.

[Distribution] – Gumbel (Extreme value type I).

Usage

udgumbel(location=0, scale=1, lb=-Inf, ub=Inf)

Arguments

Details

The Gumbel distribution function with location $l$ and scale $s$ is

$F(x) = \exp(-\exp(-\frac{x-l}{s}))$

for all $x$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1995): Continuous Univariate Distributions, Volume 2. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 22, p. 2.

See Also

unuran.cont.

Examples

## Create distribution object for Gumbel distribution
distr <- udgumbel()
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Hypergeometric distribution with parameters m, n, and k.

[Distribution] – Hypergeometric.

Usage

udhyper(m, n, k, lb=max(0,k-n), ub=min(k,m))

Arguments

Details

The Hypergeometric distribution is used for sampling without replacement. The density of this distribution with parameters m, n and k (named $Np$, $N-Np$, and $n$, respectively in the reference below) is given by

$p(x) = \left. {m \choose x}{n \choose k-x} \right/ {m+n \choose k}$

for $x = 0, \ldots, k$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.discr".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and A.W. Kemp (1992): Univariate Discrete Distributions. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 6, p. 237.

Examples

## Create distribution object for Hypergeometric distribution
dist <- udhyper(m=15,n=5,k=7)
## Generate generator object; use method DGT (inversion)
gen <- dgtd.new(dist)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Hyperbolic distribution with location parameter mu, tail (shape) parameter alpha, asymmetry (shape) parameter beta, and scale parameter delta.

[Distribution] – Hyperbolic.

Usage

udhyperbolic(alpha, beta, delta, mu, lb=-Inf, ub=Inf)

Arguments

Details

The hyperbolic distribution with parameters $\mu$,$\alpha$,$\beta$, and $\delta$ has density proportional to

$f(x) = \exp( -\alpha \sqrt(\delta^2 + (x - \mu)^2) + \beta*(x-\mu) )$

where $\alpha>|\beta|$ and $\delta>0$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

See Also

unuran.cont.

Examples

## Create distribution object for hyperbolic distribution
distr <- udhyperbolic(alpha=3,beta=2,delta=1,mu=0)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Inverse Gaussian (Wald) distribution with mean mu and shape parameter lambda.

[Distribution] – Inverse Gaussian (Wald).

Usage

udig(mu, lambda, lb=0, ub=Inf)

Arguments

Details

The inverse Gaussian distribution with mean $\mu$ and shape parameter $\lambda$ has density

$f(x) = \sqrt{\frac{\lambda}{2 \pi x^3} } \exp( -\frac{\lambda (x-\mu)^2}{2\mu^2 x} )$

where $\mu>0$ and $\lambda>0$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 15, p. 259.

See Also

unuran.cont.

Examples

## Create distribution object for inverse Gaussian distribution
distr <- udig(mu=3, lambda=2)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Laplace (double exponential) distribution with location parameter location and scale parameter scale.

[Distribution] – Laplace (double exponential).

Usage

udlaplace(location=0, scale=1, lb = -Inf, ub = Inf)

Arguments

Details

The Laplace distribution with location $l$ and scale $s$ has density

$f(x) = \exp( -\frac{|x-l|}{s} )$

for all $x$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1995): Continuous Univariate Distributions, Volume 2. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 24, p. 164.

See Also

unuran.cont.

Examples

## Create distribution object for standard Laplace distribution
distr <- udlaplace()
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Log Normal distribution whose logarithm has mean equal to meanlog and standard deviation equal to sdlog.

[Distribution] – Log Normal.

Usage

udlnorm(meanlog=0, sdlog=1, lb=0, ub=Inf)

Arguments

Details

The log normal distribution has density

$f(x) = \frac{1}{\sqrt{2 \pi} \sigma x} \exp{- (\log(x)-\mu)^2 / (2 sigma^2)}$

where $\mu$ is the mean and $\sigma$ the standard deviation of the logarithm.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 14, p. 207.

See Also

unuran.cont.

Examples

## Create distribution object for log normal distribution
distr <- udlnorm()
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Logarithmic distribution with shape parameter shape.

[Distribution] – Logarithmic.

Usage

udlogarithmic(shape, lb = 1, ub = Inf)

Arguments

Details

The Logarithmic distribution with parameters shape $= \theta$ has density

$f(x) = -\log(1-\theta) \theta^x / x$

for $x = 1, 2, \ldots$ and $0 < \theta < 1$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.discr".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and A.W. Kemp (1992): Univariate Discrete Distributions. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 7, p. 285.

See Also

unuran.discr.

Examples

## Create distribution object for Logarithmic distribution
dist <- udlogarithmic(shape=0.3)
## Generate generator object; use method DARI
gen <- darid.new(dist)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Logistic distribution with parameters location and scale.

[Distribution] – Logistic.

Usage

udlogis(location=0, scale=1, lb=-Inf, ub=Inf)

Arguments

Details

The Logistic distribution with location $= \mu$ and scale $= \sigma$ has distribution function

$F(x) = \frac{1}{1 + e^{-(x-\mu)/\sigma}}$

and density

$f(x) = \frac{1}{\sigma}\frac{e^{(x-\mu)/\sigma}}{(1 + e^{(x-\mu)/\sigma})^2}$

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1995): Continuous Univariate Distributions, Volume 2. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 23, p. 115.

See Also

unuran.cont.

Examples

## Create distribution object for standard logistic distribution
distr <- udlogis()
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Lomax distribution (Pareto distribution of second kind) with shape parameter shape and scale parameter scale.

[Distribution] – Lomax (Pareto of second kind).

Usage

udlomax(shape, scale=1, lb=0, ub=Inf)

Arguments

Details

The Lomax distribution with parameters shape $=\alpha$ and scale $=\sigma$ has density

$f(x) = \alpha \sigma^\alpha (x+\sigma)^{-(\alpha+1)}$

for $x \ge 0$, $\alpha > 0$ and $\sigma > 0$.

The domain of the distribution can be truncated to the interval (lb,ub).

Value

An object of class "unuran.cont".

Author(s)

Josef Leydold and Wolfgang H\"ormann [email protected].

References

N.L. Johnson, S. Kotz, and N. Balakrishnan (1994): Continuous Univariate Distributions, Volume 1. 2nd edition, John Wiley & Sons, Inc., New York. Chap. 20, p. 575.

See Also

unuran.cont.

Examples

## Create distribution object for Lomax distribution
distr <- udlomax(shape=2)
## Generate generator object; use method PINV (inversion)
gen <- pinvd.new(distr)
## Draw a sample of size 100
x <- ur(gen,100)

Description

Create UNU.RAN object for a Meixner distribution with scale parameter alpha, asymmetry (shape) parameter beta, shape parameter delta and location parameter mu.

[Distribution] – Meixner.

Usage

udmeixner(alpha, beta, delta, mu, lb=-Inf, ub=Inf)