Skip to contents

Linked (D)GP emulator construction

Source: R/lgp.R
lgp.Rd

This function constructs a linked (D)GP emulator.

Usage

lgp(struc, emulators = NULL, B = 10, mode = "activate", verb = TRUE, id = NULL)

Arguments

struc

the structure of the linked emulator, which can take one of two forms:

  • [Deprecated] a list contains L (the number of layers in a systems of computer models) sub-lists, each of which represents a layer and contains (D)GP emulators (represented by instances of S3 class gp or dgp) of computer models. The sub-lists are placed in the list in the same order of the specified computer model system's hierarchy. This option is deprecated and will be removed in the next release.

  • [New] a data frame that defines the connection structure between emulators in the linked system, with the following columns:

    • From_Emulator: the ID of the emulator providing the output. This ID must match the id slot in the corresponding emulator object (produced by gp() or dgp()) within emulators (the next argument following struc). The id slot is either automatically generated by gp() or dgp(), or can be manually specified via the id argument in these functions or set with the set_id() function.

    • To_Emulator: the ID of the emulator receiving the input, also matching the id slot in the corresponding emulator object. The id slot is generated or set as described above for From_Emulator.

    • From_Output: a single integer specifying the output dimension from the From_Emulator that is being connected to the input dimension of the To_Emulator.

    • To_Input: a single integer specifying the input dimension of the To_Emulator that is receiving the output dimension from the From_Emulator.

    Each row represents a single one-to-one connection between a specified output dimension of From_Emulator and a corresponding input dimension of To_Emulator. If multiple connections are required between two emulators, each connection should be specified in a separate row.

    Additionally, the special value "Global" in From_Emulator can be used to represent global input data, linking a specified dimension of the global input directly to an input dimension of an emulator.

    Note: When using this data frame option, emulators argument must be provided.

emulators

[New] a list of emulator objects, each containing an id slot that uniquely identifies it within the linked system. The id slot in each emulator object must match the From_Emulator/To_Emulator columns in struc.

If the same emulator is used multiple times within the linked system, the list must contain distinct copies of that emulator, each with a unique ID stored in their id slot. Use the set_id() function to produce copies with different IDs to ensure each instance can be uniquely referenced.

B

the number of imputations to produce the predictions. Increase the value to account for more imputation uncertainties. Decrease the value for lower imputation uncertainties but faster predictions. If the system consists only GP emulators, B is set to 1 automatically. Defaults to 10.

mode

[New] a character string indicating the operational mode of the object returned by the function:

  • "validate": returns an object suitable for visual inspection of the linked emulator structure, which can be examined using summary().

  • "activate": returns an object ready for predictions, which can be used with predict().

Defaults to "activate". This argument is only applicable when struc is specified as a data frame.

verb

[New] a bool indicating if the trace information on linked (D)GP emulator construction will be printed during the function call. Defaults to TRUE. This argument is only applicable when struc is specified as a data frame.

id

an ID to be assigned to the linked (D)GP emulator. If an ID is not provided (i.e., id = NULL), a UUID (Universally Unique Identifier) will be automatically generated and assigned to the emulator. Default to NULL.

Value

An S3 class named lgp that contains three slots:

  • id: A number or character string assigned through the id argument.

  • constructor_obj: a list of 'python' objects that stores the information of the constructed linked emulator.

  • emulator_obj, a 'python' object that stores the information for predictions from the linked emulator.

  • specs: a list that contains

    1. seed: the random seed generated to produce the imputations. This information is stored for the reproducibility when the linked (D)GP emulator (that was saved by write() with the light option light = TRUE) is loaded back to R by read().

    2. B: the number of imputations used to generate the linked (D)GP emulator.

    [New] If struc is a data frame, specs also includes:

    1. metadata: a data frame providing configuration details for each emulator in the linked system, with following columns:

      • Emulator: the ID of an emulator.

      • Layer: the layer in the linked system where the emulator is positioned. A lower Layer number indicates a position closer to the input, with layer numbering increasing as you move away from the input.

      • Pos_in_Layer: the position of the emulator within its layer. A lower Pos_in_Layer number indicates a position higher up in that layer.

      • Total_Input_Dims: the total number of input dimensions of the emulator.

      • Total_Output_Dims: the total number of output dimensions of the emulator.

    2. struc: The linked system structure, as supplied by struc.

The returned lgp object can be used by

  • predict() for linked (D)GP predictions.

  • validate() for the OOS validation.

  • plot() for the validation plots.

  • summary() to summarize the constructed linked (D)GP emulator.

  • write() to save the linked (D)GP emulator to a .pkl file.

Details

See further examples and tutorials at https://mingdeyu.github.io/dgpsi-R/.

Examples

if (FALSE) { # \dontrun{

# load the package and the Python env
library(dgpsi)

# model 1
f1 <- function(x) {
  (sin(7.5*x)+1)/2
}
# model 2
f2 <- function(x) {
  2/3*sin(2*(2*x - 1))+4/3*exp(-30*(2*(2*x-1))^2)-1/3
}
# linked model
f12 <- function(x) {
  f2(f1(x))
}

# training data for Model 1
X1 <- seq(0, 1, length = 9)
Y1 <- sapply(X1, f1)
# training data for Model 2
X2 <- seq(0, 1, length = 13)
Y2 <- sapply(X2, f2)

# emulation of model 1
m1 <- gp(X1, Y1, name = "matern2.5", id = "emulator1")
# emulation of model 2
m2 <- dgp(X2, Y2, depth = 2, name = "matern2.5", id = "emulator2")

struc <- data.frame(From_Emulator = c("Global", "emulator1"),
                    To_Emulator = c("emulator1", "emulator2"),
                    From_Output = c(1, 1),
                    To_Input = c(1, 1))
emulators <- list(m1, m2)

# construct the linked emulator for visual inspection
m_link <- lgp(struc, emulators, mode = "validate")

# visual inspection
summary(m_link)

# build the linked emulator for prediction
m_link <- lgp(struc, emulators, mode = "activate")
test_x <- seq(0, 1, length = 300)
m_link <- predict(m_link, x = test_x)

# OOS validation
validate_x <- sample(test_x, 20)
validate_y <- sapply(validate_x, f12)
plot(m_link, validate_x, validate_y, style = 2)

# write and read the constructed linked emulator
write(m_link, 'linked_emulator')
m_link <- read('linked_emulator')
} # }