\name{RFgetModelNames}
\alias{RFgetModelNames}
%\alias{PrintModelList}
\title{Names of implemented covariance and variogram models}
\description{Displays the names of covariance and
  variogram models (see \command{\link{RMmodel}}) and returns them as a
  list. The user may
  specify and group the models according to the following properties:
  \itemize{
    \item type of function (\code{"positive definite"},
    \code{"variogram"}, etc.)
    \item whether the function depends on two arguments
    (\code{"kernel"}) or on one argument only (\code{"single variable"}) 
    \item types of isotropy
    \item whether the model is an operator
    \item whether the model is a normal scale mixture
    \item whether the model has a finite range covariance
    \item validity in certain dimensions of the coordinate space 
    \item maximal possible dimension of the coordinate space
    \item uni- or multivariety
  }
  See \command{Details} for an explanation and
  \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}
  for possible states (values) of these properties.
}

\usage{

RFgetModelNames(type = RC_TYPE_NAMES, domain = RC_DOMAIN_NAMES,
                isotropy = RC_ISO_NAMES, operator = c(TRUE, FALSE),
                monotone = RC_MONOTONE_NAMES,
                implied_monotonicities = length(monotone) == 1,
                finiterange = c(TRUE, FALSE, NA),
                valid.in.dim = c(1, Inf), 
                vdim = c(1, 5),
                group.by,
                exact.match = !missing(group.by),
                simpleArguments = FALSE,
                internal, newnames)
}

\arguments{
  \item{type, domain, isotropy, operator, monotone, finiterange, vdim}{
    see \link{constants} for the definition of \code{RC_TYPE_NAMES},
    \code{RC_DOMAIN_NAMES}, etc.
    See also \code{\link[=RMmodelgenerator-class]{RMmodelgenerator}}.
  }
  \item{implied_monotonicities}{logical. If \code{TRUE} then 
    all the models with a stronger monotonocity than the required one
    are also shown.
  }
  \item{valid.in.dim}{an optional integer indicating the dimension of
  the space where the model is valid}
\item{group.by}{an optional character string or \code{NULL}; must be one of
  \code{'type'},
    \code{'domain'}, \code{'isotropy'}, \code{'operator'},
    \code{'monotone'},
    \code{'finiterange'},\code{'maxdim'},\code{'vdim'}.
    If \code{group.by} is not given, the result is grouped by
    \code{'type'} if more than one type is given.    
  }
  \item{exact.match}{logical. If not \code{TRUE}, then
    all categories that are subclasses or might match are
    show as well.
  }
  \item{simpleArguments}{logical. If \code{TRUE}, only models
    are considered whose arguments are all integer or real valued.
    }
  \item{internal, newnames}{both logical;
    \code{internal} might be also integer valued.
    If any of them are given,
    \command{\link{RFgetModelNames}} behaves very differently.
    See the Notes below.
  }
}

\note{
  In case \code{internal} or \code{newnames} is given,
  only the values of \code{internal},
  \code{newnames} and \code{operator} are considered.
  All the other arguments are ignored and
  \command{\link{RFgetModelNames}} prints a table of the currently
  implemented covariance functions and the matching methods:
  \itemize{
    \item \code{internal}:\cr
    if \code{TRUE} also \code{\link{RMmodels}} are listed that are
    internal, hence invisible to the user. Default: \code{FALSE}.
    \item \code{newnames}:\cr
    The model names of version 2 of \pkg{RandomFields} and earlier
    can still be used in the model definitions. Namely when the
    list notation is chosen; see  \link{Advanced RMmodels} for the
    latter. If \code{internal} or \code{newnames} is given, then
    these old names are shown; if \code{newnames=TRUE} then also the
    usual names are shown.
    Default: \code{FALSE}.

    In fact, both internal and public
    models can have different variants implemented.
    These variants are also shown if
    \code{internal} has a value greater than or equal to \code{2},
    \item \code{operator}:\cr
    see above.
  }
  Here, also an indication is given, which method for simulating
  Gaussian random fields matches the model.
}

\details{ 
 The plain call \code{\link{RFgetModelNames}()} simply gives back a
 vector of
 the names of all implemented covariance and variogram models and operators,
 i.e. members of the class
 \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}.

 The following arguments can be specified.
 In general, only exact matches are returned. One exception exists:
 If the length of \code{type} equals 1 and if \code{group.by} is not
 given, then  types included in \code{type} are also returned.
 E.g. if \code{type="variogram"}  and  \code{group.by} is not given
 then only models are returned that are negative definite.
 However, also positive definite functions and tail correlaton
 functions are returned if \code{"type"} is included in \code{group.by}.
 
 \describe{
   \item{\code{type}}{specifies the class of functions; for
     the meaning of the possible values see
     \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}
   }
   
   \item{\code{stationarity}}{specifies the type of stationarity; for
     the meaning of the possible values see
     \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}
   }
   
   \item{\code{isotropy}}{specifies the type of isotropy; for
     the meaning of the possible values see
     \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}
   }
   
   \item{\code{operator}}{indicates whether the model is an operator, 
     i.e. it requires at least one submodel, 
     e.g. \command{\link[=RMplus]{+}} or
     \command{\link{RMdelay}} are operators; see
     \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}
   }
   
   \item{\code{monotone}}{indicates what kind of monotonicity is known,
     e.g., whether the model is a normal
     scale mixture, the latter including \command{\link{RMexp}} or
     \command{\link{RMcauchy}}; see
     \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}
   }
   
   \item{\code{finiterange}}{indicates whether the covariance of the
     model has finite range, e.g. \command{\link{RMcircular}} or
     \command{\link{RMnugget}} have covariances with finite range; see
     \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}.
     \code{NA} is used if the finiteness depends on the submodel. 
   }
   
   \item{\code{valid.in.dim}}{If \code{valid.in.dim=n} is
     passed, all models which are valid in dimension \eqn{n} are
     displayed. Otherwise \code{valid.in.dim} should be a bivariate vector
     giving the range of requested dimensions.
   }
   
   \item{\code{maxdim}}{if a positive integer, it specifies the maximal
     possible dimension of the coordinate space;
     note that a model which is valid in dimension
     \eqn{n} is also valid in dimension \eqn{n-1};
     \code{maxdim=-1} means that the maximal possible dimension depends
     on the parameters of the \command{\link{RMmodel}} object;
     \code{maxdim=-2} means that the maximal possible dimension is
     adopted from the called submodels;
     see also
     \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}
   }
 
   \item{\code{vdim}}{if a positive integer, vdim specifies, whether
     the model is \eqn{vdim}-variate; 
     \code{vdim=-1} means that being multivariate
     in a certain dimension depends on the parameters of the
     \command{\link{RMmodel}} object;
     \code{vdim=-2} means that being multivariate
     in a certain dimension is adopted from the called submodels;
     see also
     \command{\link[=RMmodelgenerator-class]{RMmodelgenerator}}

     If \code{vdim} is bivariate then a range is given.
   }
   
   \item{\code{group.by}}{If \code{group.by="propertyname"} is
     passed, the displayed models are grouped according to
     \code{propertyname}.
   }
 }

 All arguments allow also for vectors of values. In case of
 \code{valid.in.dim} the smallest value is taken.
 The interpretation is canonical.
 
 
 Note that the arguments \code{stationarity}, \code{isotropy},
 \code{operator}, \code{monotone}, \code{finiterange},
 \code{maxdim}, \code{vdim}
 are also slots (attributes) of the SP4-class
 \code{\link[=RMmodelgenerator-class]{RMmodelgenerator}}.
}

\value{
  Either a vector of model names if the argument
 \code{group.by} is not used;
 or a list of vectors of model names if the argument \code{group.by} is
 used
 (with list elements specified by the categories of the grouping
 argument).

 In case \code{internal} or \code{newnames} is given,
 \command{\link{RFgetModelNames}} prints a table of the currently
 implemented covariance functions and the matching methods.
 \command{\link{RFgetModelNames}} returns \code{NULL}.
}

%\references{
%}

\me

\seealso{
  \link{constants},
 \code{\link[=RMmodelgenerator-class]{RMmodelgenerator}},
 \code{\link{RMmodel}},
 \code{\link[=RandomFields-package]{RandomFields}},
 \link{RC_DOMAIN_NAMES}, \link{RC_ISO_NAMES}
}

\examples{\dontshow{StartExample()}
RFoptions(seed=0) ## *ANY* simulation will have the random seed 0; set
##                   RFoptions(seed=NA) to make them all random again

# get list of names of all functions
RFgetModelNames()

# any kind of positive definite functions
RFgetModelNames(type="positive definite", exact.match=TRUE)
\dontrun{RFgetModelNames(type="positive definite")}

# get a list of names of all stationary models
RFgetModelNames(type="positive definite", domain="single variable",
                 exact.match=TRUE)
\dontrun{RFgetModelNames(type="positive definite", domain="single variable")}

# get a vector of all model names
RFgetModelNames(group.by=NULL)


\dontshow{\dontrun{


# get list of all univariate stationary models
# additionally grouped by the isotropy attribute
str(RFgetModelNames(type="positive definite", domain="single variable",
                    vdim=1, group.by="isotropy"))

# get vector of all models which are operators
# and valid in the two-dimensional coordinate space
RFgetModelNames(type=c("tail correlation function",
                       "positive definite",
                       "variogram",
                       "undefined"),
                operator=TRUE, valid.in.dim=2)

# processes and covariance function grouped by the stationarity
# argument and subsequently grouped by the isotropy argument

str(RFgetModelNames(type=c("positive definite", "variogram", "process"),
                    group.by=c("type", "domain", "isotropy")))
}}

\dontshow{FinalizeExample()}}

\keyword{spatial}