Runuran-package: Runuran - R interface to Universal Non-Uniform RANdom variate...

In Runuran: R Interface to the 'UNU.RAN' Random Variate Generators

Runuran – R interface to Universal Non-Uniform RANdom variate generators library

Description

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

Details

Package:	Runuran
Type:	Package
Version:	0.38
Date:	2023-01-17
License:	GPL 2 or later

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:

Function		Method
arou.new	...	Automatic Ratio-of-Uniforms method
ars.new	...	Adaptive Rejection Sampling
itdr.new	...	Inverse Transformed Density Rejection
pinv.new	...	Polynomial interpolation of INVerse CDF
srou.new	...	Simple Ratio-Of-Uniforms method
tabl.new	...	TABLe based rejection
tdr.new	...	Transformed Density Rejection

Discrete Distributions:

Function		Method
dari.new	...	Discrete Automatic Rejection Inversion
dau.new	...	Alias-Urn Method
dgt.new	...	Guide-Table Method for discrete inversion

Multivariate Distributions:

Function		Method
hitro.new	...	Hit-and-Run with Ratio-of-Uniforms method
vnrou.new	...	Multivariate Naive Ratio-Of-Uniforms method

[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 [e-mail].

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.

Runuran documentation built on Jan. 17, 2023, 5:17 p.m.