defineUM {spup}

Define an uncertainty model for a single variable

Description

Function that allows to define marginal uncertainty distributions for model inputs and subsequent Monte Carlo analysis.

Usage

defineUM(
  uncertain = TRUE,
  distribution = NULL,
  distr_param = NULL,
  crm = NULL,
  categories = NULL,
  cat_prob = NULL,
  id = NULL,
  ...
)

Arguments

uncertain

"TRUE" or "FALSE", determines if specification of Uncertainty Model (UM) is needed. Currently not in use, but provided for furture implementation of contributions analysis.

distribution

a string that specifies which distribution to sample from. Only in use for continuos or discrete numerical variables. See Details for a list of supported distributions.

distr_param

a vector or a list with distribution parameters. For example, for the normal distribution in case of a spatial variable this must be a map of means and a map of standard deviations. Only in use for continuous or discrete numerical variables.

crm

a correlogram model, object of a class "SpatialCorrelogramModel", output of makecormodel(). Can only be specified for numerical variables.

categories

a vector of categories. Only in use for categorical (e.g. saved as character) or discrete numerical variables.

cat_prob

spatial data frame or raster stack; a list of probabilities for the vector of categories. Number of columns in the data frame cannot be smaller than number of categories. Only in use for categorical (e.g. saved as character) or discrete numerical variables.

id

identifier of the variable; only in use if the UM defined here is to be used in defineUM() to construct a joint UM for numerical variables.

...

additional parameters.

Details

If the uncertain object is a spatial object, the distribution parameters or the probabilities for categories must be provided by means of maps, for example if a spatial variable has a normal distribution, a map of means and standard deviations must be provided. If crm is provided and spatial correlation between the residuals is assumed only the normal distribution for residuals is allowed.

If no spatial correlations between residuals is assumed, allowed distributions for marginal uncertainty models are listed in Table 1.

Table 1 Parametric probability models allowed in defineUM(). For more details look up ?distribution.

	Distribution	Syntax	Parameters
	beta	"beta"	shape1, shape2, ncp
	binomial	"binom"	size, prob
	Cauchy	"cauchy"	location, scale
	chi-squared	"chisq"	df, ncp
	exponential	"exp"	rate
	gamma	"gamma"	shape, rate
	geometric	"geom"	prob
	hypergeometric	"hyper"	m, n, k
	log-normal	"lnorm"	meanlog, sdlog
	negative binomial	"nbinom"	size, prob, mu
	normal	"norm"	mean, sd
	Poisson	"pois"	lambda
	Student's	"t"	df, ncp
	uniform	"unif"	min, max
	Weibull	"weibull"	shape, scale

Value

Object of a class "MarginalXxx" that includes all necessary information for creating realizations of the uncertain variable. If provided arguments are: type of the distribution and corresponding parameters, and corresponding parameters are spatial objects - an object of class "MarginalNumericSpatial". If provided arguments are: type of the distribution and corresponding parameters, and corresponding parameters are non-spatial objects - an object of class "MarginalNumericSpatial". If provided arguments are: categories and probabilities, and probabilities are saved in a spatial object - an object of class "MarginalCategoricalSpatial". If provided arguments are: categories and probabilities, and probabilities are saved in a non-spatial object - an object of class "MarginalCategoricalDataFrame".

Author(s)

Kasia Sawicka, Gerard Heuvelink

Examples

# define uncertainty model for spatial numerical variable
data(dem30m, dem30m_sd)
dem_crm <- makeCRM(acf0 = 0.78, range = 321, model = "Exp")
demUM <- defineUM(uncertain = TRUE, distribution = "norm",
                   distr_param = c(dem30m, dem30m_sd), crm = dem_crm)
class(demUM)
                   
# define uncertainty model for spatial categorical variable
data(woon)
woonUM <- defineUM(TRUE, categories = c(1,2,3), cat_prob = woon[, c(4:6)])
class(woonUM)

# define uncertainty model for a variable desribed by a scalar
scalarUM <- defineUM(uncertain = TRUE, distribution = "gamma", distr_param = c(1,2))
class(scalarUM)

# define uncertainty model for two spatial cross-correlated variables
data(OC, OC_sd, TN, TN_sd)

OC_crm <- makeCRM(acf0 = 0.6, range = 1000, model = "Sph")
OC_UM <- defineUM(TRUE, distribution = "norm", distr_param = c(OC, OC_sd), crm = OC_crm, id = "OC")
class(OC_UM)

TN_crm <- makeCRM(acf0 = 0.4, range = 1000, model = "Sph")
TN_UM <- defineUM(TRUE, distribution = "norm", distr_param = c(TN, TN_sd), crm = TN_crm, id = "TN")
class(TN_UM)