defineUM: Define an uncertainty model for a single variable
In spup: Spatial Uncertainty Propagation Analysis

Description Usage Arguments Details Value Author(s) Examples

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

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

`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.

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

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".

Kasia Sawicka, Gerard Heuvelink

# 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)