Revision 9df6a40adeba312e8827992d823c1fb051503cf5 authored by Martin Schlather on 08 August 1977, 00:00:00 UTC, committed by Gabor Csardi on 08 August 1977, 00:00:00 UTC
1 parent cfc74af
RFparameters.Rd
\name{RFparameters}
\alias{RFparameters}
\alias{RFparameters.default}
\title{Control Parameters}
\description{
\code{RFparameters} sets and returns control parameters for the simulation
of random fields
}
\usage{
RFparameters(...)
RFparameters.default(Storing=storing, PrintLevel=printlevel,
PracticalRange=practicalrange, CE.force=ce.force,
CE.mmin=ce.mmin, CE.tolRe=ce.tolRe,
CE.tolIm=ce.tolIm, CE.trials=ce.trials,
direct.checkprecision=directcheckprecision,
direct.maxvariables=directmaxvariables,
direct.method=directmethod,
direct.requiredprecision=directrequiredprecision,
spectral.lines=spectrallines,
spectral.grid=spectralgrid,
TBMCE.force=tbmceforce, TBMCE.mmin=tbmcemmin,
TBMCE.tolRe=tbmcetolre, TBMCE.tolIm=tbmcetolim,
TBMCE.trials=tbmcetrials, TBM2.lines=tbm2lines,
TBM2.linesimufactor=tbm2linesimufactor,
TBM2.linesimustep=tbm2linesimustep,
TBM3D2.lines=tbm3D2lines,
TBM3D2.linesimufactor=tbm3D2linesimufactor,
TBM3D2.linesimustep=tbm3D2linesimustep,
TBM3D3.lines=tbm3D3lines,
TBM3D3.linesimufactor=tbm3D3linesimufactor,
TBM3D3.linesimustep=tbm3D3linesimustep,
MPP.approxzero=mppapproxzero,
add.MPP.realisations=addmpprealisations,
MPP.radius=mppradius,
maxstable.maxGauss=maxstablemaxGauss, pch=pchx)
}
\arguments{
\item{...}{arguments as given in \code{RFparameters.default} and
listed in the following.}
\item{Storing}{logical. If \code{TRUE} then intermediate results are kept
after each simulation; if several simulation are made with the same
parameters (e.g., by \code{n}\eqn{>1}{>1} in \link{GaussRF} or
several calls of \link{GaussRF}) then
\code{Storing=TRUE} accelerates the simulations, but needs additional
memory. Default: \code{TRUE} [init, do].}
\item{PrintLevel}{If \code{PrintLevel}\eqn{\le0}{<=0}
there is not any output on the screen. The
higher the number the more tracing information.
Default: 1 [init, do].\cr
1 : messages about errors occurred\cr
2 : messages about partial failures of the algorithm
}
\item{PracticalRange}{The range of the covariance functions can be
adjusted so that cov(1) is about 0.05 (for \code{scale==1}).
Default: \code{FALSE} [init].}
\item{CE.force}{logical. Circulant embedding does not work if a
certain 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{CE.mmin}{Circulant embedding usually uses the smallest matrix
possible; by \code{CE.mmin} the minimum number of rows and columns
of the matrix are given. Default: \code{0} [init].}
\item{CE.tolRe}{Circulant embedding.
Threshold above which eigenvalues are considered as
non-negative. Default: \code{-1E-5} [init].}
\item{CE.tolIm}{Circulant embedding.
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{CE.trials}{Circulant embedding.
A larger embedding 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,
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{direct.checkprecision}{Gaussian
random vectors can be generated
by means of the square root of the covariance matrix.
By default Cholesky decomposition is used. If
\code{direct.checkprecision==TRUE} then the precision is checked.
Default: \code{FALSE} [init].}
\item{direct.maxvariables}{Decomposition of the covariance matrix.
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 if \code{method==NULL} in \link{GaussRF}.
Default: \code{1000} [init]}
\item{direct.method}{Decomposition of the covariance matrix.
If \code{direct.method==1}, Cholesky
decomposition will not be attempted, but singular value
decomposition
used instead.
Default: \code{0} [init].}
\item{direct.requiredprecision}{Decomposition of the covariance
matrix.
If \code{direct.checkprecision==TRUE} and
the \code{direct.requiredprecision} is not reached then Cholesky
decomposition fails, and singular value decomposition is used.
Default: \code{1e-11} [init].
}
\item{spectral.lines}{Spectral turning bands.
Number of lines used. Default: \code{500} [do].}
\item{spectral.grid}{Logical. Spectral turning bands is implemented
for 2 dimensions only. 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. Default: \code{TRUE} [do].}
%\item{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{TBMCE.force}{Ordinary TBM methods. At the moment only the
circulant embedding method on the line is implemented; this
parameter corresponds to \code{CE.force}.
Default: \code{FALSE} [init].}
\item{TBMCE.mmin}{Ordinary TBM methods. This parameter corresponds to
\code{CE.mmin}. Default: \code{0} [init].}
\item{TBMCE.tolRe}{Ordinary TBM methods. This parameter corresponds
to \code{CE.tolRe}. Default: \code{-1E-5} [init].}
\item{TBMCE.tolIm}{Ordinary TBM methods. This parameter corresponds
to \code{CE.tolIm}. Default: \code{1E-3} [init].}
\item{TBMCE.trials}{Ordinary TBM methods. This parameter corresponds
to \code{CE.trials}. Default: \code{3} [init].}
\item{TBM2.lines}{Ordinary 2-dimensional turning bands method.
Number of lines used.
Default: \code{60} [do].}
\item{TBM2.linesimufactor}{Either \code{TBM2.linesimufactor} or
\code{TBM2.linesimustep} must be greater than zero. The parameter
that is zero is ignored. The grid on the line is
\code{TBM2.linesimufactor}-times
smaller than the smallest distance.
See also \code{TBM2.lines}.
Default: \code{2.0} [init].}
\item{TBM2.linesimustep}{The grid on the line has lag
\code{TBM2.linesimustep}. See also \code{TBM2.linesimufactor}.
Default: \code{0.0} [init].}
\item{TBM3D2.lines}{Ordinary 3-dimensional turning bands method,
simulation of a \emph{2-dimensional} field.
Number of lines used.
Default: \code{500} [do].}
\item{TBM3D2.linesimufactor}{Either \code{TBM3D2.linesimufactor} or
\code{TBM2.linesimustep} must be greater than zero. The parameter
that is zero is ignored. The grid on the line is
\code{TBM3D2.linesimufactor}-times
smaller than the smallest distance. See also \code{TBM3D2.lines}.
Default: \code{2.0} [init].}
\item{TBM3D2.linesimustep}{The grid on the line has lag
\code{TBM3D2.linesimustep}. See also \code{TBM3D2.linesimufactor}.
Default: \code{0.0} [init].}
\item{TBM3D3.lines}{Ordinary 3-dimensional turning bands method,
simulation of a \emph{3-dimensional field}.
Number of lines used.
Default: \code{500} [do].}
\item{TBM3D3.linesimufactor}{Either \code{TBM3D3.linesimufactor} or
\code{TBM2.linesimustep} must be greater than zero. The parameter
that is zero is ignored. The grid on the line is
\code{TBM3D3.linesimufactor}-times smaller than the smallest
distance. See also \code{TBM3D3.lines}.
Default: \code{2.0} [init].}
\item{TBM3D3.linesimustep}{The grid on the line has lag
\code{TBM3D3.linesimustep}. See also \code{TBM3D3.linesimufactor}.
Default: \code{0.0} [init].}
\item{MPP.approxzero}{Marked point processes. Functions that do not have
compact support are set to zero outside the ball outside which the
function has absolute values less than \code{MPP.approxzero}.
Default: \code{0.001} [init].}
\item{add.MPP.realisations}{Random coins.
Number of superposed
realisations (to approximate the normal distribution).
Default: \code{100} [do].}
\item{MPP.radius}{Marked point processes.
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.radius>0} the true radius \eqn{r}{r} is replaced by
\code{MPP.radius}.
Default: \code{0.0} [init].}
\item{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 \code{\link{MaxStableRF}}, the upper endpoint is
approximated by \code{maxstable.maxGauss}.
Default: \code{3.0} [init].
}
\item{pch}{character. The character is printed after each
performed simulation if more than one simulation is performed at
once. Default: \code{"#"} [do].
}
}
\details{
The following refers to the simulation of Gaussian random fields
(\code{\link{InitGaussRF}}, \code{\link{GaussRF}}), but most
parts also apply
for the simulation of max-stable random fields
(\code{\link{InitMaxStableRF}}, \code{\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
\code{\link{InitGaussRF}} and stored in an internal register.
Changing
such a parameter between calling \code{\link{InitGaussRF}} and calling
\code{\link{DoSimulateRF}} will not have any effect. These parameters have
the flag "[init]".
Parameters like \code{TBM2.lines} (which determines the number of
i.i.d. proceses to be simulated on the line)
are only relevant when generating
random numbers. These parameters are read by \code{DoSimulateRF}, and
are marked by "[do]".
\code{Storing} has an influence on both, \code{\link{InitGaussRF}} and
\code{\link{DoSimulateRF}}. \code{\link{InitGaussRF}} may reserve
more memory if \code{Storing==TRUE}. \code{\link{DoSimulateRF}} will
free the register
if \code{Storing==FALSE}, whatever the value of \code{Storing} was
when \code{\link{InitGaussRF}} was called.
The distinction between [init] and [do] is relevant even if
\code{\link{GaussRF}} is used, but called a second time
with the same parameters for the random field and if
\code{RFparameters()$Storing==TRUE}.
Then \code{\link{GaussRF}} realises that the second call has the
same parameters, and
takes over the stored intermediate results (that have been calculated
with the \code{RFparameters()} at that time). To prevent this
put \code{RFparameters(Storing==FALSE)} or use
\code{\link{DeleteRegister}()}.
A programme that checks whether the parameters are well
adapted to a specific simulation problem is given as an example of
\code{\link{EmpiricalVariogram}()}.
For further details on the implemented methods, see \link{RFMethods}.
}
\value{
returns \code{NULL} if any parameter has been given,
and the list of all parameter values otherwise.
}
\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@uni-bayreuth.de}
\url{http://www.geo.uni-bayreuth.de/~martin}}
\seealso{\code{\link{GaussRF}},
\code{\link{GetPracticalRange}},
\code{\link{MaxStableRF}},
\code{\link{RandomFields}},
and \code{\link{RFMethods}}.}
\examples{
RFparameters(Storing=TRUE)
str(RFparameters())
}
\keyword{spatial}
Computing file changes ...