unuran.new {Runuran} | R Documentation |
Create a new UNU.RAN object in package Runuran that can be used
for sampling from the specified distribution.
The function unuran.sample
can then be used to draw a random
sample.
unuran.new(distr,method="auto")
distr |
a string or an S4 class describing the distribution. |
method |
a string describing the random variate generation method. |
The UNU.RAN package works in the following way:
unuran.new
call. Thus it is possible to choose a method
that corresponds best to ones application. However, not all methods
work in combination with all distribution. Thus the result of
unuran.new
can be empty and must be checked.
Both the distribution and the method are described by character
strings, see below.unuran.sample
.
The argument distr
describes the target distribution from which
wants to draw one (or more) random sample(s).
It is passed through to the UNU.RAN interface, see the UNU.RAN manual
for a detailed description at
http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#StringDistr.
Notice that the key-value pairs have to be separated by semicolons
;
.
"normal(1,2)"
for the normal distribution with mean 1 and
standard deviation 2. We remark, however, that we have prepared
wrapper functions with function names starting with ur
that
combine the initialization and sampling steps for theses
distributions. See the man pages and source of these functions for
further reference. It is possible to truncate standard
distributions with the domain
keyword, e.g. to sample from
the half-normal distribution one has to use
"normal(); domain=(0,Inf)"
.
"cont"
to indicate this type
of distribution. Then the probability density function
(pdf
) or cumulative distribution function (cdf
) must
be given. Moreover, the domain must be set as otherwise
(-Inf,Inf)
is assumed.
E.g., if the target distribution has a density proportional to
1/x^2 on x >= 1 we use
"cont; pdf='1/x^2'; domain=(1,Inf)"
.
Notice the single quotes '
that encapsulates the function
string. Note that the given PDF must be a non-negative function with
finite integral. It need not integrate to 1, i.e., it can be any
multiple of density function. The syntax of the function string
("1/x^2"
in our example) is very similar to the R syntax;
see the UNU.RAN manual for detailed description at
http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#StringFunct.
Notice, that there also exist an indicator function for densities.
For example, to get a triangular distribution on (-1,1) with
mode at 0 we write
"cont; pdf='(x<0)*(1+x) + (x<=0)*(1-x)'; domain=(-1,1)"
.
The CDF can be specified analogously:
"cont; cdf='exp(-x)'; domain=(0,Inf)"
.
"discr"
. Then one either can
provide a (multiple of a) probability mass function
(“density”) using the keyword pmf
or a (multiple of
a) probability vector using pv
.
Here is an example for a discrete distribution on (1,100)
with probability vector proportional to 1/x:
"discr; pmf='1/x'; domain=(1,100)"
.
A discrete distribution with a probability vector proportional to
(1,2,3,4,5,4,3,2,1) is given by
"discr; pv=(1,2,3,4,5,4,3,2,1)"
(there is no necessity for
providing a domain except it does not start at 0).
Notice that for the latter case there exist wrapper functions
urdgt
and urdau
for drawing a random
sample.
domain
keyword. E.g., when the domain should be set to
(-1,Inf)
we write domain=(-1,Inf)
.
If non-integer domains are given for discrete distribution, then
the given numbers are simply truncated to integers.
mode
keyword: "mode=1.5"
.
"unuran.cmv"
instead.
The package Runuran provides an alternative approach to describe distributions. Thus the following S4 classes can be used.
unuran.cont
.
unuran.discr
.
unuran.cmv
.
This interface allows to use R functions and object to define distributions.
The argument method
describes generation method for drawing
the random samples. UNU.RAN provides various such method for all
types of distributions. This is indentional as not all methods work
for all distributions. Morever, the choice of the generation method
also might depend on the particular application (stochastic
simulation problem) for which the sample has to be drawn.
We give her short list of methods that are most useful.
for a detailed description see the UNU.RAN manual at
http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#StringMethod.
"AUTO"
:method
string is
provided by the user.
All other methods only work for continuous univariate, discrete, or continuous multivariate distributions. (We remark, that UNU.RAN also provides methods for other types of distributions which are currently only partially supported by the Runuran interface.) All methods have optional parameters that allow to adjust the method for the target distribution. However, most of these are only useful in rare situations with distributions with extreme properties. See the UNU.RAN manual if you need a the full list of paramters.
For continuous univariate distributions the most important methods are:
"HINV"
:
The accuracy of the method can be controlled by the parameter
u_resolution
which gives the
maximal tolerated u-error (i.e., |U-CDF(X)|)
of the numeric inversion (Default is 1.e-10
).
Use "hinv; u_resolution=1.e-12"
to use this method with
increased accuracy.
"TDR"
:
It is possible to choose a piecewise exponential hat by means of
parameter c
: "TDR; c=0"
. It then only works for
log-concave distributions.
The acceptance probability can be changed using parameter
"max_sqhratio"
. For example if an acceptance probability
of 90% is acceptable (which results in a faster setup) use
"TDR; max_sqhratio=0.95"
.
The marginal generation speed can be increased using
parameter "variant_ia"
which cases TDR to use a techique
called “immediate acceptance”:
"TDR; variant_ia"
.
For discrete univariate distributions the most important methods are:
"DGT"
:"DAU"
:"DGT"
.
"DARI"
:For continuous multivariate distributions the most important methods are:
"HITRO"
:Notice that MCMC samplers do not produce a sequence of independent variates. The drawn sample follows the target distribution only appropriately.
Beware: MCMC sampling can be dangerous!
Method HITRO provides two parameters that increase the quality the
generated sample: "thinning"
and "burnin"
.
By the first parameter only a fraction of the generated sequence
is returned while the second one discards the first part of the
sequence (“burn-in phase”):
"HITRO; thinning=3; burnin=1000"
.
There are some more parameter to control the behavior of the
algorithm.
See the UNU.RAN manual and urhitro
for more
informations.
"VNROU"
:
unuran.new(distr,method)
is an alias for
new("unuran", distr, method)
.
Josef Leydold and Wolfgang H"ormann unuran@statmath.wu-wien.ac.at.
W. H"ormann, J. Leydold, and G. Derflinger (2004): Automatic Nonuniform Random Variate Generation. Springer-Verlag, Berlin Heidelberg.
runif
and .Random.seed
about random number
generation, unuran
for the UNU.RAN class,
unuran.sample
, urtdr
, urdgt
and urdau
.
For distribution objects see unuran.cont
,
unuran.discr
, and
unuran.cmv
.
## Make histograms for samples of size 10000 for some non-standard distributions unr <- new("unuran", "cont; pdf='log(x)*(x<1.3098)+(x>1.3098)*exp(-x)'; domain = (1, Inf)", "TDR"); x <- unuran.sample(unr,10000); hist(x) unr <- new("unuran", "distr=cont; pdf='1/x^3'; domain = (0.5, Inf)", "TDR"); x <- unuran.sample(unr,10000); hist(x) unr <- new("unuran", "distr=discr; pmf='1/(2+x)^3'; domain = (1, Inf);pmfsum=0.05","DARI"); x <- unuran.sample(unr,10000); hist(x)