https://github.com/cran/RandomFields
Tip revision: 6b9dea4f9beb109f9d5a81129f5e5bbfd2e2bb7a authored by Martin Schlather on 12 November 2011, 00:00:00 UTC
version 2.0.53
version 2.0.53
Tip revision: 6b9dea4
RFparameters.Rd
% x <- read.table("RFparameters.Rd")
% y <- iconv(x, "", "utf-8", sub="byte")
% write(y, "xx.Rd")
\name{RFparameters}
\alias{RFparameters}
\title{Control Parameters}
\description{
\code{RFparameters} sets and returns control parameters for the simulation
of random fields
}
\usage{
RFparameters(..., no.readonly=FALSE)
}
\arguments{
\item{...}{arguments in \code{tag = value} form, or a list of tagged
values.}
\item{no.readonly}{If \command{RFparameters} is called without
parameter then all parameters are returned in a list. If
\code{no.readonly=TRUE} then only rewritable parameters are returned.
}
}
\details{
The possible parameters are
\bold{General options}\cr
\describe{
\item{\code{PracticalRange}}{logical or .
If not \code{FALSE} the range of the \strong{primitive}
covariance functions is
adjusted so that cov(1) is zero for models with finite range.
The value of
cov(1) is about 0.05 (for \code{scale=1})
for models without range.
See \command{\link{CovarianceFct}} or type
\command{PrintModelList()}
for the list of
primitive models.
\itemize{
\item \code{FALSE} : the practical range ajustment is not used.
\item \code{TRUE} : \code{PracticalRange} is applicable only if
the value is known exactly, or, at least, can be approximated by
a closed formula.
\item \code{2} : if the practical range is not known exactly it
is approximated numerically.
}
Default: \code{FALSE} [init].}
\item{\code{PrintLevel}}{If \code{PrintLevel}\eqn{\le0}{<=0}
there is not any output on the screen. The
higher the number the more tracing information is given.
Default: 1 [init, do].\cr
1 : error messages\cr
2 : messages about partial failures of the algorithm\cr
>2 : additional informations
Note that \code{PrintLevel} is also used in other packages
as a default, for example in SoPhy
(\command{risk.index} and \command{create.roots}). The changing of
\code{PrintLevel} here may cause some unexpected effects in these
functions. See the documentation there.
}
}
%
\bold{General options for simulating}\cr
\describe{
\item{\code{pch}}{Character or empty string.
The character is printed after each
performed simulation if more than one simulation is performed at
once. If \code{pch='!'} then an absolute
counter is shown instead of the character.
If \code{pch='\%'} then a
counter of percentages is shown instead of the character.
Note that also '\eqn{\mbox{\textasciicircum}}{^}H's are printed in
the last two cases,
which may have undesirable interactions with some few other R
functions, e.g. \command{\link[utils]{Sweave}}.
Default: \code{'*'} [do].
}
\item{\code{Storing}}{Logical.
If \code{FALSE} then the intermediate results are
destroyed after the simulation of the random field(s)
or if an error had occured.
On the other hand, if \code{Storing=TRUE}, then
several simulations performed with \code{DoSimulateRF} for the same
model parameters are performed faster.
See alse \code{CE.several}, \code{TBMCE.several} and
\code{local.several} for related parameters.
Default: \code{FALSE} [do].
}
\item{\code{skipchecks}}{logical.
If \code{TRUE}, the check whether the given parameter values
and the dimension are within the allowed range is skipped.
Do not change the value of this variable except you really
know what you do.
Default: \code{FALSE} [init].
}
\item{\code{stationary.only}}{Logical or NA. Used for the automatic
choice of methods. See also \link{RFMethods}.
\itemize{
\item \code{TRUE}: the simulation of non-stationary random
fields is refused. In particular, the intrinsic
embedding method is excluded and
the simulation of Brownian motion is rejected.
\item \code{FALSE}: intrinsic embedding is always allowed,
actually it's the first one considered in the automatic
selection algorithm.
\item \code{NA}: the simulation of the Brownian motion allowed,
but intrinsic embedding is not used for stationary random fields.
}
Default: \code{NA} [init].}
\item{\code{exactness}}{logical or NA.
\itemize{
\item \code{TRUE}: add.MPP, hyperplanes and
all turning bands methods are excluded.
If the circulant embedding method is considered as badly
behaved, then the matrix decomposition methods are preferred.
\item \code{FALSE}: if the circulant embedding method is
considered as badly behaved or the number of points to be
simulated is large, the turning bands methods are
rather preferred.
\item \code{NA}: approximative non-exact methods are excluded,
i.e. TBM2 if the Abel transform of the covariance function
cannot be given explicitely.
}
Default: \code{NA} [init].
}
\item{\code{every}}{integer.
if greater than zero, then every \code{every}th iteration is
printed if simulated by TBM or random coin method.
Default: \code{0} [do].
}
\item{\code{aniso}}{logical.
If \code{TRUE} missing anisotropy parameter
or scale parameter in model \code{$} are
intepreted as identity matrix. If \code{FALSE}
missing anisotropy or scale parameter is intepreted
as scale parameter of value 1.0. The latter coding tends to faster
simulation, but also to more error messages. The parameter should
be changed only by advanced users.
Default: \code{TRUE} [init].
}
}
%
\bold{Options for simulating with the standard circulant embedding method}\cr
\describe{
\item{\code{CE.force}}{Logical. Circulant embedding does not work if a
certain circulant
matrix has negative eigenvalues. Sometimes it is convenient
to replace all the negative eigenvalues by zero
(\code{CE.force=TRUE}) after \code{CE.trials} number of trials.
Default: \code{FALSE} [init].
}
\item{\code{CE.mmin}}{Scalar or vector, integer if positive.
\code{CE.mmin} determines the initial size of the circulant
matrix. If \code{CE.mmin=0} the minimal starting size is
determined automatically according to the
dimensions of the grid.
If \code{CE.mmin>0} then the absolute starting size is given.
If \code{CE.mmin<0} then the automatically determined
matrix size is multiplied
by \eqn{|\code{CE.mmin}|}; here \code{CE.mmin} must be smaller
than -1; the
value -1 takes over the minimal starting size.\cr
Note: in any cases, the initial size might be increased according
to \code{CE.useprimes}.\cr
Default: \code{0} [init].}
\item{\code{CE.strategy}}{0 : if the circulant
matrix has negative eigenvalues then the
size in each direction is doubled; \cr 1 : the size is enhanced only in
one direction, namely that one where the covariance function has the
largest value at the end point of the grid --- note that
the default value of \code{CE.trials} is probably too small
in that case.
In some cases \code{CE.strategy=0} works better, in other cases
\code{CE.strategy=1}. Just try.
Default: \code{0}
[init].}
\item{\code{CE.maxmem}}{
maximal total size of the circulant matrix.
The total amount of memory needed for the internal calculations
is about 16 (=2 * sizeof(double))
times as large as \code{CE.maxmem}
if \command{\link{RFparameters}}\code{()$Storing=FALSE}
and 32 (=4 * sizeof(double)) time as large if \code{Storing=TRUE}.
Note that \code{CE.maxmem} can be used to control the automatic
choice of the simulation algorithm. Namely, in case of huge
circulant matrices, other simulation
methods (TBM) are faster and might be preferred be the user.
Default: \code{4096^2 = 16777216} [init].
}
\item{\code{CE.tolIm}}{
If the modulus of the imaginary part is less than
\code{CE.tolIm} then the eigenvalue is considered as real.
Default: \code{1E-3} [init].}
\item{\code{CE.tolRe}}{
Eigenvalues between \code{CE.tolRe} and 0 are considered as
0 and set 0. Default: \code{-1E-7} [init].}
\item{\code{CE.trials}}{
A larger circulant matrix is likely to make more eigenvalues
non-negative. If at least one of the thresholds \code{CE.tolRe} and
\code{CE.tolIm} are missed then the matrix size is doubled
according to \code{CE.strategy},
and the matrix is checked again. This procedure is repeated
up to \code{CE.trials-1} times. If there are still negative
eigenvalues, the simulation method fails if \code{CE.force=FALSE}.
Default: \code{3} [init].
}
\item{\code{CE.several}}{logical.
If \code{FALSE} only half the memory is need, but
only a single independent realisation can created.
Default: \code{TRUE} [init].
}
\item{\code{CE.useprimes}}{Logical. If \code{FALSE}
the columns of the circulant matrix
have length \eqn{2^k} for some \eqn{k}. Otherwise the algorithm
tries to find a nicely factorizable number close to the size of the
given matrix. Default: \code{TRUE} [init].}
\item{\code{CE.dependent}}{Logical. If \code{FALSE}
then independent random fields are created. If \code{TRUE}
then at least 4 non-overlapping rectangles are taken out of the
the expanded grid defined by the circulant matrix.
These simulations are dependent.
See below for an example.
See \code{CE.trials} for some
more information on the circulant matrix.
Default: \code{FALSE} [init].}
\item{\code{CE.method}}{0 or 1. Decomposition of the covariance matrix.
This parameter
is only relevant if multivariate random fields are simulated.
Default (\code{CE.method=0}):
If \code{.Random.seed} is fixed, Cholesky decomposition allows for
fixing the random field of the first component whilst
parameters for the second field are changed.
If \code{CE.method=0} and approximate circulant embedding is
allowed, i.e. \code{CE.force=TRUE},
SVD is tried for the last failed attempt of Cholesky
decomposition. (SVD, in contrast to Cholesky decomposition, allows
for approximate circulant embedding.)
If \code{CE.method=1}, Cholesky
decomposition will not be attempted, but singular value
decomposition used instead in all attempts. (SVD is slower, but
more precise.)
Default: \code{0} [init].}
}
\bold{Options for simulating by simple matrix decomposition}\cr
\describe{
\item{\code{direct.bestvariables}}{integer.
When searching for an appropriate simuation method
the matrix decomposition method (see \sQuote{direct method} below)
is preferred if the number of variables is less than or equal to
\code{direct.bestvariables}.
Default: \code{800} [init]}
\item{\code{direct.maxvariables}}{
If the number of variables to generate is
greater than \code{direct.maxvariables}, then any matrix decomposition
method is rejected. It is important that this option is set
conveniently to avoid great losses of time during the automatic
search of a simulation method (\code{method=NULL} in
\command{\link{GaussRF}}).
Default: \code{4096} [init]}
\item{\code{direct.method}}{Decomposition of the covariance matrix.
If \code{direct.method=1}, Cholesky
decomposition will not be attempted, but singular value
decomposition
used instead if \code{direct.svdtolerance} positive.
In case of a multivariate random field, \code{direct.method = 2}
or 3 orders the covariance such that first all components are
considered for the first variable, then all components for the
second one, and so on. If \code{direct.method = 0} or 1
it starts with the first component of all locations, then the
second components follow, etc.
Default: \code{0} [init].}
\item{\code{direct.svdtolerance}}{
If SVD decomposition is used for calculating the square root of
the covariance matrix then the absolute componentwise difference between
the covariance matrix and square of the square root must be less
than \code{direct.svdtolerance}. No check is performed if
\code{direct.svdtolerance} is negative.
Default: \code{1e-12} [init].}
}
%
\bold{Options for simulating hyperplane tessellations}\cr
\describe{
\item{\code{hyper.superpos}}{integer.
number of superposed hyperplane tessellations.
Default: \code{300} [do].
}
\item{\code{hyper.maxlines}}{integer.
Maximum number of allowed lines.
Default: \code{1000} [init].
}
\item{\code{hyper.mar.distr}}{integer.
code for the marginal distribution used in the
simulation:
\describe{
\item{\code{0}}{uniform distribution}
\item{\code{1}}{Frechet distribution with form parameter
\code{hyper.mar.param}}
\item{\code{2}}{Bernoulli distribution (Binomial with \eqn{n=1}) with
parameter \code{hyper.mar.param}}
}
The parameter should not be changed yet.
Default: \code{0} [do].
}
\item{\code{hyper.mar.param}}{Parameter used for the marginal
distribution. The parameter should not be changed yet.
Default: \code{0} [do].
}
}
\bold{Options for simulating with the local ce
methods (cutoff, intrinsic)}\cr
\describe{
\item{\code{local.force}}{see CE.force above.
Default: \code{FALSE} [init].
}
\item{\code{local.mmin}}{see CE.mmin above.
Difference: if \code{local.mmin=0} the automatic determination
of the initial size of the circulant matrix takes into
account an expansion factor. This expansion factor is
intended to make the circulant matrix positive definite
and is either theoretically or numerically known, or guessed.
If the usual strategy of circulant embedding
(doubling the grid sizes) should be taken over then
\code{local.mmin} must
be set to \code{-1}.
Default: \code{0} [init].}
\item{\code{local.maxmem}}{see \code{CE.maxmem} above.
Default: \code{20000000} [init].}
\item{\code{local.tolIm}}{see \code{CE.tolIm} above.
Default: \code{1E-7} [init].}
\item{\code{local.tolRe}}{see \code{CE.tolRe} above.
Default: \code{-1E-9} [init].}
\item{\code{local.several}}{see \code{CE.several} above.
Default: \code{1} [init].}
\item{\code{local.useprimes}}{see \code{CE.useprimes} above.
Default: \code{TRUE} [init].}
\item{\code{local.dependent}}{see \code{CE.dependent} above.
Default: \code{FALSE} [init].}
}
%
\bold{Options for simulating a Gaussian Markov random fields}
\describe{
\item{\code{markov.neighbours}}{2 or 3.
Number of neighbours in each direction.
Default: \code{2} [init].
}
\item{\code{markov.precision}}{
See also the GMRF manual.
Default: \code{1.0} [init].
}
\item{\code{markov.cyclic}}{logical.
simulation on a torus; should not be changed
except the user knows what he/she does. (The covariance function
will be (slightly?!) changed then without further notice!)
Default: \code{FALSE} [init].
}
\item{\code{markov.maxmem}}{integer.
maximum numer of points of the grid.
Default: \code{250000} [init].
}
}
\bold{Options for simulating by random coins}\cr
\describe{
\item{\code{mpp.locations}}{
integer. Way of defining the point process.\cr
-1 : automatic choice\cr
0 : grid\cr
1 : Poisson point process\cr
2 : uniform distribution\cr
3 : single point follows d dimensional Gaussian distribution\cr
Default: \code{-1} [init].
}
\item{\code{mpp.intensity}}{real.
Number of superposed
realisations (to approximate the normal distribution; total number
for all (additive) components with same anisotropy);
if \code{mpp.intensity<=0.0} then only a single
value is simulated (for checking).
Default: \code{100} [do].}
\item{\code{mpp.plus}}{
In order avoid edge effects, the simulation area is enlarged by
a constant \eqn{r}{r} so that all marks have their
(supposed) support in the ball with radius \eqn{r}{r} centred at
the origin; see also \code{mpp.approxzero}.
If \code{mpp.plus>0} the true radius \eqn{r}{r} is replaced by
\code{mpp.radius}.
Default: \code{0.0} [init].}
\item{\code{mpp.relRadius}}{
\eqn{\code{mpp.relRadius} / V} is added to the effectiveRadius.
The latter gives the approximate radius for the support of the
grain.
Default: \code{2.5} [init].
}
\item{\code{mpp.approxzero}}{Functions that
do not have
compact support are set to zero outside the ball outside for which the
function has absolute values less than \code{MPP.approxzero}.
Default: \code{0.001} [init].}
\item{\code{mpp.samplingdist}}{
\code{mpp.samplingdist} gives the grid distance
to numerically approximate the volume of the grain.
\code{[-mpp.samplingr,mpp.sampling]^d } gives the
domain over which the approximation is calculated.
Default: \code{0.01} [init].
}
\item{\code{mpp.samplingr}}{
see \code{mpp.samplingdist}
Default: \code{5} [init].
}
}
\bold{Options for simulating nugget effects}\cr
Simulating a nugget effect seems trivial. It gets complicated
and best methods (including \code{direct} and \code{circulant
embedding}!) fail if zonal anisotropies are considered,
where sets of points have to be identified that belong to the
same subspace of eigenvalue 0 of the anisotropy matrix.
\describe{
\item{\code{nugget.tol}}{
points at a distance less than or equal to \code{nugget.tol}
are considered as being identical. This strategy applies to
the simulation method and the covariance function itself.
Hence, the covariance function is only positive definite
if \code{nugget.tol=0.0}. However, if the anisotropy matrix
does not have full rank and \code{nugget.tol=0.0} then,
the simulations are likely to be odd.
The value of \code{nugget.tol}
should be of order \eqn{10^{-15}}{1e-15}.
Default: \code{0.0} [init].
}
\item{\code{nugget.meth}}{
logical. If \code{TRUE} any method given the user for the
simulation of the nugget effect is replaced by the method
\sQuote{nugget} whenever appropriate (zonal nugget or a method
different form circulant embedding, direct and sequential).
}
}
\bold{Options for using the sequential method}\cr
The method works only for spatio-temporal settings (and
grids).
\describe{
\item{\code{sequ.max}}{integer.
maximum number of allowed variables on which
the conditional distribution is conditionned.
Default: \code{5000} [init].
}
\item{\code{sequ.back}}{integer.
number of previous instances on which
the algorithm should condition.
If less than one then the number of previous instances
equals \code{sequ.max} / (number of spatial points).
Default: \code{5} [init].
}
\item{\code{sequ.initial}}{
First, N=(number of spatial points) * \code{sequ.back}
number of points are simulated. Then, sequentially,
all spatial points for the next time instance
are simulated at once, based on the previous \code{sequ.back}
instances. The distribution of the first N points
is the correct distribution, but
differs, in general, from the distribution of the sequentially
simulated variables. We prefer here to have the same distribution
all over (although only approximatively the correct one),
hence do some initial sequential steps first.
If \code{sequ.initial} is non-negative, then \code{sequ.initial}
first steps are performed.
If \code{sequ.initial} is negative, then
\code{sequ.back} - \code{sequ.initial}
initial steps are performed. The latter ensures that
none of the very first N variables are returned.
Default: \code{-10} [init].
}
}
\bold{Options for special simulation methods}\cr
Special methods exist for the following covariance functions
\describe{
\item{spatialMA1}{
this covariance function is simulated by
a certain moving average of a spatially independent,
but temporally dependent random field \eqn{Y}.
\describe{
\item{\code{spec.MA.r}}{gives the radius beyond which the bivariate
standard normal density is considered as being zero
Default: \code{2.5} [init].
}
\item{\code{spec.MA.dist}}{the random field \eqn{Y} is
approximated by a grid; the grid length is given by
\code{spec.MA.dist}.
Default: \code{0.1} [init].
}
}
}
}
\bold{Options for simulating with a turning bands method}\cr
Currently, there are 3 variants of the turning bands method
implemented:
\describe{
\item{\code{spectral}}{The spectral turning bands method
is implemented for 2 (and 1)
dimensions only.}
\item{\code{TBM2}}{It is based on the two dimensional turning bands operator
and is applicable for 1 and 2 dimensions. As an additional dimension
the time dimension can be added.
}
\item{\code{TBM3}}{It is based on the three dimensional turning bands operator
and is applicable for 1,2,3 dimensions. As an additional dimension
the time dimension can be added.
}
}
The following parameters are used.
\describe{
\item{\code{spectral.grid}}{Logical.
The angle of the lines is random if
\code{spectral.grid=FALSE},
and \eqn{k\pi/}{k*pi/}\code{spectral.lines}
for \eqn{k}{k} in \code{1:spectral.lines},
otherwise. This parameter is only considered
if the spectral measure, not the density is used.
Default: \code{TRUE} [do].}
\item{\code{spectral.ergodic}}{
In case of an additive model and \code{spectral.ergodic=FALSE},
the additive component are chosen proportional to their
variance. In total \code{spectral.lines} are simulated. If
\code{spectral.ergodic=TRUE}, the components are simulated
separately and then added.
Default: \code{FALSE} [do].
}
\item{\code{spectral.lines}}{
Number of lines used (in total for all additive components of the
covariance function). Default: \code{500} [do].}
\item{\code{spectral.metro}}{
Logical. If \code{TRUE} then preference is given
to the (slower) metropolis sampling algorithm of the spectral
density.
Default: \code{FALSE} [init].
}
\item{\code{spectral.nmetro}}{integer. Considered if the Metropolis
algorithm is used. It gives the number of metropolis steps
before returning the next draw from the spectral density.
If \code{spectral.nmetro}
is not positive then\code{RandomFields} tries to find a good
choice for
\code{spectral.nmetro} by itself.
Default: \code{0} [init].
}
\item{\code{spectral.sigma}}{real. Considered if the Metropolis
algorithm is used. It gives the standard deviation of the
multivariate normal distribution of the proposing
distribution.
If \code{spectral.sigma}
is not positive then\code{RandomFields} tries to find a good
choice for
\code{spectral.sigma} itself.
Default: \code{0} [init].
}
%\item{\code{TBM.method}}{Set at init time; setting ignored and stored
%setting used if other parameters are identical to former parameters!
%-- use DeleteKey, to make sure that the current setting is used.
% [init]}
\item{\code{TBM.method}}{character.
The preferred method to simulate on the line for \code{TBM2} and
\code{TBM3};
If \sQuote{Nothing} then automatic choice.
Default: \code{"Nothing"} [init].
}
\item{\code{TBM.center}}{Scalar or vector.
If not \code{NA}, the \code{TBM.center} is used as the center of
the turning bands for \code{TBM2} and \code{TBM3}.
Otherwise the center is determined
automatically such that the line length is minimal.
See also \code{TBM.points} and the examples below.
Default: \code{NA} [init].
}
\item{\code{TBM.points}}{integer. If greater than 0,
\code{TBM.points} gives the number of points simulated on the TBM
line, hence
must be greater than the minimal number of points given by
the size of the simulated field and the two paramters
\code{TBMx.linesimufactor} and \code{TBMx.linesimustep}.
If \code{TBM.points} is not positive the number of points is
determined automatically.
The use of \code{TBM.center} and \code{TBM.points} is highlighted
in an example below.
Default: \code{0} [init].
}
\item{\code{TBM2.every}}{If \code{TBM2.every>0} then every
\code{TBM2.every}th iteration is announced.
Default: \code{0} [do].}
\item{\code{TBM2.lines}}{
Number of lines used.
Default: \code{60} [do].}
\item{\code{TBM2.linesimufactor}}{ \code{TBM2.linesimufactor} or
\code{TBM2.linesimustep} must be non-negative; if
\code{TBM2.linesimustep}
is positive then \code{TBM2.linesimufactor} is ignored.
If both
parameters are naught then \code{TBM.points} is used (and must be
positive).
The grid on the line is \code{TBM2.linesimufactor}-times
finer than the smallest distance.
See also \code{TBM2.linesimustep}.
Default: \code{2.0} [init].}
\item{\code{TBM2.linesimustep}}{
If \code{TBM2.linesimustep} is positive the grid on the line has lag
\code{TBM2.linesimustep}.
See also \code{TBM2.linesimufactor}.
Default: \code{0.0} [init].}
\item{\code{TBM2.layers}}{
Logical or integer. If \code{TRUE} then the turning layers are used whenever
a time component is given.
If \code{FALSE} the turning layers are used only when the
traditional TBM is not applicable.
If negative then turning layers may never be used.
If greater than 1 then only turning layers may be used.
Default: \code{FALSE} [init].}
% \item{\code{TBM2.num}}{
% Logical. If \code{TRUE} then the covariance function on the line
% is approximated numerically.
% If \code{FALSE} only those models are allowed
% that have an analytic representation on
% the line.
% Default: \code{TRUE} [init].}
\item{\code{TBM3.every}}{If \code{TBM3.every>0} then every
\code{TBM3.every}th iteration is announced.
Default: \code{0} [do].}
\item{\code{TBM3.lines}}{
Number of lines used.
Default: \code{500} [do].}
\item{\code{TBM3.linesimufactor}}{See \code{TBM2.linesimufactor} for
the meaning.
Default: \code{2.0} [init].}
\item{\code{TBM3.linesimustep}}{See
\code{TBM2.linesimustep} for the meaning.
Default: \code{0.0} [init].}
\item{\code{TBM3.layers}}{See
\code{TBM2.layers} for the meaning.
Default: \code{FALSE} [init].}
\item{\code{TBMCE.force}}{see \code{TBM.method} and \code{CE.force}
Default: \code{FALSE} [init].}
\item{\code{TBMCE.mmin}}{see \code{TBM.method} and
\code{CE.mmin}. Default: \code{0} [init].}
\item{\code{TBMCE.strategy}}{see \code{TBM.method} and
\code{CE.strategy}. Default: \code{0} [init].}
\item{\code{TBMCE.maxmem}}{see \code{TBM.method} and
\code{CE.maxmem}. Default: \code{10000000} [init].}
\item{\code{TBMCE.tolIm}}{see \code{TBM.method} and
\code{CE.tolIm}. Default: \code{1E-3} [init].}
\item{\code{TBMCE.tolRe}}{see \code{TBM.method} and
\code{CE.tolRe}. Default: \code{-1E-7} [init].}
\item{\code{TBMCE.trials}}{see \code{TBM.method} and
\code{CE.trials}. Default: \code{3} [init].}
\item{\code{TBMCE.useprimes}}{see \code{TBM.method} and
\code{CE.useprimes}. Default: \code{TRUE} [init].}
\item{\code{TBMCE.dependent}}{see \code{TBM.method} and \code{CE.dependent}.
Default: \code{FALSE} [init].}
}
%
\bold{Options specific to simulating max-stable random fields}
\describe{
\item{\code{maxstable.maxGauss}}{Max-stable random fields.
The simulation of the max-stable process based on random fields uses
a stopping rule that necessarily needs a finite upper endpoint
of the marginal distribution of the random field.
In the case of extremal Gaussian random fields,
see \command{\link{MaxStableRF}}, the upper endpoint is
approximated by \code{maxstable.maxGauss}.
Default: \code{3.0} [init].
}
}
\bold{General comments on the options}
\cr
The following refers to the simulation of Gaussian random fields
(\command{\link{InitGaussRF}}, \command{\link{GaussRF}}), but most
parts also apply
for the simulation of max-stable random fields
(\command{\link{InitMaxStableRF}}, \command{\link{MaxStableRF}}).
Some of the global parameters determine the basic settings of a
simulation, e.g. \code{direct.method} (which chooses a square
root of a positive definite matrix). The values of
such parameters are read by
\command{\link{InitGaussRF}} and stored in an internal register.
Changing
such a parameter between calling \command{\link{InitGaussRF}} and calling
\command{\link{DoSimulateRF}} or between subsequent calls of
\command{\link{GaussRF}} will not have any effect. These parameters have
the flag "[init]".
Parameters like \code{TBM2.lines} (which determines the number of
i.i.d. processes to be simulated on the line)
are only relevant when generating
random numbers. These parameters are read by \code{DoSimulateRF}
(or by the second part of \command{\link{GaussRF}}), and
are marked by "[do]".
\code{Storing} has an influence on both, \command{\link{InitGaussRF}} and
\command{\link{DoSimulateRF}}. \command{\link{InitGaussRF}} may reserve
more memory if \code{Storing=TRUE}. \command{\link{DoSimulateRF}} will
free the register
if \code{Storing=FALSE}, whatever the value of \code{Storing} was
when \command{\link{InitGaussRF}} was called.
The distinction between [init] and [do] is also relevant if
\command{\link{GaussRF}} is used and called a second time
with the same parameters for the random field and if
\code{RFparameters()$Storing=TRUE}.
Then \command{\link{GaussRF}} realises that the second call has the
same random field parameters, and
takes over the stored intermediate results (that have been calculated
with the \code{RFparameters()} at that time). To prevent the use of
stored intermediate results or to take into account intermediate
changes of RFparameters
set \code{RFparameters(Storing=FALSE)} or use
\command{\link{DeleteRegister}()} between calls of \code{GaussRF}.
A programme that checks whether the parameters are well
adapted to a specific simulation problem is given as an example of
\command{\link{EmpiricalVariogram}()}.
For further details on the implemented methods, see \link{RFMethods}.
}
\value{
If any parameter has been given
\code{RFparameters} returns an invisible list of
the given parameters in full name.
Otherwise the complete list of parameters is returned. Further the
values of the following internal readonly variables are returned:
\cr
* \code{covmaxchar}: max. name length for variogram/covariance
models
\cr
* \code{covnr}: number of currently implemented
variogram/covariance models
\cr
* \code{distrmaxchar}: max. name length for a distribution
\cr
* \code{distrnr}: number of currently implemented
distributions
\cr
* \code{maxdim}: maximum number of dimensions for a
random field
\cr
* \code{maxmodels}: maximum number of elementary models in
definition of a complex covariance model
\cr
* \code{methodmaxchar}: max. name length for methods
\cr
* \code{methodnr}: number of currently implemented simulation methods
}
\references{
Schlather, M. (1999) \emph{An introduction to positive definite
functions and to unconditional simulation of random fields.}
Technical report ST 99-10, Dept. of Maths and Statistics,
Lancaster University.
}
\author{Martin Schlather, \email{martin.schlather@math.uni-goettingen.de}
\url{http://www.stochastik.math.uni-goettingen.de/~schlather}}
\seealso{\command{\link{GaussRF}},
\command{\link{GetPracticalRange}},
\command{\link{MaxStableRF}},
\code{\link{RandomFields}},
and \command{\link{RFMethods}}.}
\examples{
RFparameters(Storing=TRUE)
str(RFparameters())
############################################################
## ##
## use of TBM.points and TBM.center ##
## ##
############################################################
## The following example shows that the same realisation
## can be obtained on different grid geometries (or point
## configurations, i.e. grid, non-grid) using TBM3 (or TBM2)
x1 <- seq(-150,150,1)
y1 <- seq(-15, 15, 1)
x2 <- seq(-50, 50, 1)
model <- "exponential"
param <- c(0, 1, 0, 10)
meth <- "TBM3"
###### simulation of a random field on long thing stripe
runif(1)
rs <- get(".Random.seed", envir=.GlobalEnv, inherits = FALSE)
z1 <- GaussRF(x1, y1, model=model, param=param, grid=TRUE,
method=meth, TBM.center=0, Storing=TRUE)
do.call(getOption("device"), list(height=1.55, width=12))
par(mar=c(2.2, 2.2, 0.1, 0.1))
image(x1, y1, z1, col=rainbow(100))
polygon(range(x2)[c(1,2,2,1)], range(y1)[c(1,1,2,2)], border="red", lwd=3)
###### definition of a random field on a square of shorter diagonal
assign(".Random.seed", rs, envir=.GlobalEnv)
tbm.points <- length(GetRegisterInfo(meth="TBM")$S$line)
z2 <- GaussRF(x2, x2, model=model, param=param, grid=TRUE, register=1,
method=meth, TBM.center=0, TBM.points=tbm.points)
do.call(getOption("device"), list(height=4.3, width=4.3))
par(mar=c(2.2, 2.2, 0.1, 0.1))
image(x2, x2, z2, zlim=range(z1), col=rainbow(100))
polygon(range(x2)[c(1,2,2,1)], range(y1)[c(1,1,2,2)], border="red", lwd=3)
############################################################
## ##
## use of exactness ##
## ##
############################################################
% library(RandomFields, lib="~/TMP")
x <- seq(0, 1, 1/30)
model <- list("+",
list("stable", alpha=1.0),
list(model="gencauchy", alpha=1.0, beta=2.0)
)
for (exactness in c(NA, FALSE, TRUE)) {
readline(paste("\n\nexactness: `", exactness, "'; press return"))
z <- GaussRF(x, x, grid=TRUE, gridtriple=FALSE,
model=model, exactness=exactness,
stationary.only=NA, Print=1, n=1,
TBM2.linesimustep=1, Storing=TRUE)
Print(GetRegisterInfo()$meth$name)
}
#############################################################
## The following gives a tiny example on the advantage of ##
## local.dependent=TRUE (and CE.dependent=TRUE) if in a ##
## study most of the time is spent with simulating the ##
## Gaussian random fields. Here, the covariance at a pair ##
## of points is estimated for n independentent repetitions ##
## and 2*n locally dependent dependent repetitions . ##
## To get the precision, the procedure is repeated m times.##
#############################################################
# In the example below, local.dependent speeds up the simulation
# by about factor 16 at the price of an increased variance of
# factor 1.5
x <- seq(0, 1, len=10)
y <- seq(0, 1, len=10)
grid.size <- c(length(x), length(y))
model <- list("$", var=1.1, aniso=matrix(nc=2, c(2,1,0.5,1)),
list(model="exp"))
(CovarianceFct(matrix(c(1, -1), ncol=2), model=model)) ## true value
m <- if (interactive()) 100 else 2
n <- if (interactive()) 100 else 10
# using local.dependent=FALSE (which is the default)
c1 <- numeric(m)
unix.time(
for (i in 1:m) {
cat("", i)
z <- GaussRF(x, y, model=model, grid=TRUE, method="cu", n=n,
local.dependent=FALSE, pch="")
c1[i] <- cov(z[1,length(y), ], z[length(x), 1, ])
}) # many times slower than with local.dependent=TRUE
mean(c1)
sd(c1)
# using local.dependent=TRUE...
c2 <- numeric(m)
unix.time(
for (i in 1:m) {
cat("", i)
z <- GaussRF(x, y, model=model, grid=TRUE, method="cu", n=2 * n,
local.dependent=TRUE, pch="")
c2[i] <- cov(z[1,length(y),], z[length(x), 1 , ])
})
mean(c2)
sd(c2) # the sd is samller (using more locally dependent realisations)
## but it is (much) faster! For n=n2 instead of n=2 * n, the
## value of sd(c2) would be larger due to the local dependencies
## in the realisations.
}
\keyword{spatial}
