pkern_pars_update: Convert covariance parameter list to/from vectorized form

In deankoch/pkern: Fast Kriging with Product Kernels

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

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

Arguments

pars	list of kernel parameters (in form understood by pkern_pars_make)
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
p_vec	numeric vector (optional) kernel parameters to update in pars

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 pkern_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 pkern_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=pkern_pars_update(pars, na_omit=TRUE), which returns non-NA entries of pars.

Value

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

Examples

# initialize a parameter list and pass to pkern_pars_update
k = c('gau', 'mat')
pars_empty = pkern_pars_make(k)
pars_empty |> pkern_pars_update()
# pars can be a character vector passed directly to pkern_pars_update
pkern_pars_update(k)
# single kernel definitions are duplicated
pkern_pars_update('mat')

# example parameter vector to illustrate ordering
p_update = 1:5
# (inverse) pass a modified vector back to the function to update pars
pars_filled = pars_empty |> pkern_pars_update(p_update)
pars_filled |> print()
# p_update is unchanged by round trip
pkern_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
pars_filled |> pkern_pars_update()
pars_filled |> pkern_pars_update(na_omit=TRUE)
# when updating parameters, NAs in pars identify parameters to receive the new values
p_update = rnorm(2) |> abs()
pars_filled |> pkern_pars_update(p_update, na_omit=TRUE)
# when na_omit=FALSE, all parameters in pars are updated
p_update = rnorm(5)
pars_filled |> pkern_pars_update(p_update)

# iso=TRUE is for when x kernel parameters are assigned values from the y kernel
pars_empty = pkern_pars_make('mat')
p_update = pars_empty |> pkern_pars_update(iso=TRUE) |> length() |> seq()
pars_filled = pars_empty |> pkern_pars_update(p_update, iso=TRUE)
pars_filled$eps = NA
pars_filled$x$kp[2] = NA
pars_filled |> pkern_pars_update(iso=TRUE) # NA shape parameter in x ignored
# update calls should omit the x kernel parameters
pars_filled |> pkern_pars_update(seq(4), iso=TRUE)

# if eps_scaled=TRUE, psill is dropped from input/output (for when eps is scaled by psill)
pars_filled |> pkern_pars_update()
pars_filled |> pkern_pars_update(eps_scaled=TRUE)
pars_filled |> pkern_pars_update(-seq(5), eps_scaled=TRUE)

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

deankoch/pkern documentation built on Oct. 26, 2023, 8:54 p.m.