snapKrig (version 0.0.2)

sk_pars_update: Convert covariance parameter list to/from vectorized form

Description

Converts parameter list pars to vector p and back again. A convenience function for numerical optimization where objective functions accept numeric vectors only.

Usage

sk_pars_update(
  pars,
  p = NULL,
  iso = FALSE,
  eps_scaled = FALSE,
  na_omit = FALSE
)

Value

numeric vector of parameters, or, if p is supplied, the updated pars list

Arguments

pars

list of kernel parameters (in form understood by sk_pars_make)

p

numeric vector (optional) kernel parameters to update in pars

iso

logical, indicating to treat y and x kernel parameters as equal (see details)

eps_scaled

logical, indicates to drop partial sill from input/output

na_omit

logical, toggles handling of NAs (see details)

Details

When p is not supplied, the function un-lists the numeric values of pars, returning them as a vector. When na_omit=TRUE, only the non-NA values are returned; and when iso=TRUE the x kernel parameters are also omitted from the output vector.

When p is supplied, the function copies its values to the corresponding entries in pars, returning the result as a list. In this case, when na_omit=TRUE, only the NA entries of pars are filled; and when iso=TRUE, parameters for the y kernel are recycled to fill entries for the x kernel.

The order returned (and expected in p, if supplied) is:

'eps', 'psill', 'y.rho', ('y.kap'), 'x.rho', ('x.kap')

where 'y.kap' and 'x.kap' are omitted in kernels without shape parameters (see sk_corr). Only the order matters here, as names are ignored in p.

With na_omit=FALSE, p should have length 3-6, the same as the vector returned by sk_pars_update(pars); NAs in p are copied over in this case, effectively inverting the vectorization.

With na_omit=TRUE, values in p are copied only to the NA entries of pars; ie the length of p should equal the number of NA entries in pars (less any redundant x kernel parameters when iso=TRUE). Note that this does NOT invert the vectorization p=sk_pars_update(pars, na_omit=TRUE), which returns non-NA entries of pars.

See Also

Other parameter managers: sk_bds(), sk_fit(), sk_kp(), sk_pars_make(), sk_pars(), sk_to_string()

Examples

# initialize a parameter list and pass to sk_pars_update
k = c('gau', 'mat')
pars_empty = sk_pars_make(k)
sk_pars_update(pars_empty)

# pars can be a character vector passed directly to sk_pars_update
sk_pars_update(k)

# single kernel definitions are duplicated
sk_pars_update('mat')

# example parameter vector to illustrate ordering
p_update = seq(5)

# (inverse) pass a modified vector back to the function to update pars
pars_filled = sk_pars_update(pars_empty, p_update)
print(pars_filled)

# p_update is unchanged by round trip
sk_pars_update(pars_filled)

# NAs in pars can be filtered out with na_omit=TRUE
pars_filled$eps = NA
pars_filled$x$kp[1] = NA
sk_pars_update(pars_filled)
sk_pars_update(pars_filled, na_omit=TRUE)

# when updating parameters, NAs in pars identify parameters to receive the new values
p_update = abs(stats::rnorm(2))
sk_pars_update(pars_filled, p_update, na_omit=TRUE)

# when na_omit=FALSE, all parameters in pars are updated
p_update = stats::rnorm(5)
sk_pars_update(pars_filled, p_update)

# iso=TRUE is for when x kernel parameters are assigned values from the y kernel
pars_empty = sk_pars_make('mat')
p_update = seq(length(sk_pars_update(pars_empty, iso=TRUE)))
pars_filled = sk_pars_update(pars_empty, p_update, iso=TRUE)
print(pars_filled)

# notice NA shape parameter in x ignored while NA in eps is copied
pars_filled$eps = NA
pars_filled$x$kp[2] = NA
sk_pars_update(pars_filled, iso=TRUE)

# update calls with iso=TRUE should omit the x kernel parameters (p is shorter)
sk_pars_update(pars_filled, seq(4), iso=TRUE)

# if eps_scaled=TRUE, psill is ignored (useful for when eps is scaled by psill)
sk_pars_update(pars_filled)
sk_pars_update(pars_filled, eps_scaled=TRUE)

# notice value of psill not updated
sk_pars_update(pars_filled, -seq(5), eps_scaled=TRUE)

# compare/combine with other modes
pars_filled$y$kp[2] = NA
sk_pars_update(pars_filled)
sk_pars_update(pars_filled, -seq(2), iso=TRUE, na_omit=TRUE)
sk_pars_update(pars_filled, -seq(4), iso=TRUE)
sk_pars_update(pars_filled, -seq(3), iso=TRUE, eps_scaled=TRUE)
sk_pars_update(pars_filled, -seq(3), na_omit=TRUE)