Deprecation

Deprecation of the basic nodes and `struc` arguments in gp() and dgp() functions, as customization of GP and DGP specifications can be achieved using the other arguments in `gp()` and `dgp()`.

NAMESPACE

@@ -32,7 +32,6 @@ S3method(validate,lgp)
 S3method(vigf,bundle)
 S3method(vigf,dgp)
 S3method(vigf,gp)
-export(Categorical)
 export(Hetero)
 export(NegBin)
 export(Poisson)

NEWS.md

@@ -11,10 +11,11 @@
 - An issue related to the `LD_LIBRARY` environment variable on Linux systems has been resolved via the `init_py()` function.
 - The `lgp()` function has been enhanced to accept connection information among emulators in the form of a data frame, streamlining linked emulation setup.
 - A new function, `set_id()`, allows users to assign unique IDs to emulators.
-- A new function, `Categorical()`, enables the creation of categorical likelihood nodes for classification within a customized DGP hierarchy.
 - The `plot()` function has been updated to generate validation plots for DGP classifiers (i.e., DGP emulators with categorical likelihoods).
 - The `summary()` function has been redesigned to provide visualizations of structure and model specifications for (D)GP and linked (D)GP emulators.
 - A `sample_size` argument has been added to the `validate()` and `plot()` functions, allowing users to adjust the number of samples used for validation when the validation method is set to `sampling`.
+- The following functions are deprecated as of this version and will be removed in the next release: `combine()`, `set_linked_idx()`, `kernel()`, `Poisson()`, `Hetero()`, and `NegBin()`. These functions are no longer maintained. Please refer to the updated package documentation for alternative workflows.
+- The basic node functions `kernel()`, `Hetero()`, `Poisson()`, and `NegBin()`, along with the `struc` argument in the `gp()` and `dgp()` functions, have been deprecated as of this version and will be removed in the next release. Customization of (D)GP specifications can be achieved by modifying the other arguments in `gp()` and `dgp()`.
 - Additional vignettes are available, showcasing large-scale DGP emulation and DGP classification.
 
 # dgpsi 2.4.0

R/dgp.R

@@ -5,13 +5,15 @@
 #' @param X a matrix where each row is an input training data point and each column is an input dimension.
 #' @param Y a matrix containing observed training output data. The matrix has its rows being output data points and columns being
 #'     output dimensions. When `likelihood` (see below) is not `NULL`, `Y` must be a matrix with only one column.
-#' @param struc a list that specifies a user-defined DGP structure. It should contain *L* (the number of DGP layers) sub-lists,
+#' @param struc `r lifecycle::badge("deprecated")` a list that specifies a user-defined DGP structure. It should contain *L* (the number of DGP layers) sub-lists,
 #'     each of which represents a layer and contains a number of GP nodes (defined by [kernel()]) in the corresponding layer.
 #'     The final layer of the DGP structure (i.e., the final sub-list in `struc`) can be a likelihood
 #'     layer that contains a likelihood function (e.g., [Poisson()]). When `struc = NULL`,
 #'     the DGP structure is automatically generated and can be checked by applying [summary()] to the output from [dgp()] with `training = FALSE`.
 #'     If this argument is used (i.e., user provides a customized DGP structure), arguments `depth`, `node`, `name`, `lengthscale`, `bounds`, `prior`,
 #'     `share`, `nugget_est`, `nugget`, `scale_est`, `scale`, `connect`, `likelihood`, and `internal_input_idx` will NOT be used. Defaults to `NULL`.
+#'
+#' **The argument will be removed in the next release. To customize DGP specifications, please adjust the other arguments in the [dgp()] function.**
 #' @param depth number of layers (including the likelihood layer) for a DGP structure. `depth` must be at least `2`.
 #'     Defaults to `2`. This argument is only used when `struc = NULL`.
 #' @param node number of GP nodes in each layer (except for the final layer or the layer feeding the likelihood node) of the DGP. Defaults to
@@ -180,7 +182,6 @@
 #' * [summary()] to summarize the trained DGP emulator.
 #' * [write()] to save the DGP emulator to a `.pkl` file.
 #' * [set_imp()] to change the number of imputations.
-#' * [set_linked_idx()] to add the linking information to the DGP emulator for linked emulations.
 #' * [design()] for sequential designs.
 #' * [update()] to update the DGP emulator with new inputs and outputs.
 #' * [alm()], [mice()], [pei()], and [vigf()] to locate next design points.
@@ -250,6 +251,17 @@ dgp <- function(X, Y, struc = NULL, depth = 2, node = ncol(X), name = 'sexp', le
     if (pkg.env$restart) return(invisible(NULL))
   }
 
+  if (!is.null(struc)) {
+    # Display a combined warning message
+    lifecycle::deprecate_warn(
+      when = "3.0.0",
+      what = "dgp(struc)",
+      details = c(i = "The argument will be dropped in the next release.",
+                  i = "To customize DGP specifications, please adjust the other arguments in the `dgp()` function."
+      )
+    )
+  }
+
   if (!is.null(internal_input_idx)) {
     lifecycle::deprecate_warn(
       when = "3.0.0",

R/gp.R

@@ -4,9 +4,11 @@
 #'
 #' @param X a matrix where each row is an input data point and each column is an input dimension.
 #' @param Y a matrix with only one column and each row being an output data point.
-#' @param struc an object produced by [kernel()] that gives a user-defined GP specifications. When `struc = NULL`,
+#' @param struc `r lifecycle::badge("deprecated")` an object produced by [kernel()] that gives a user-defined GP specifications. When `struc = NULL`,
 #'     the GP specifications are automatically generated using information provided in `name`, `lengthscale`,
 #'     `nugget_est`, `nugget`, `scale_est`, `scale`,and `internal_input_idx`. Defaults to `NULL`.
+#'
+#' **The argument will be removed in the next release. To customize GP specifications, please adjust the other arguments in the [gp()] function.**
 #' @param name kernel function to be used. Either `"sexp"` for squared exponential kernel or
 #'     `"matern2.5"` for Matérn-2.5 kernel. Defaults to `"sexp"`. This argument is only used when `struc = NULL`.
 #' @param lengthscale initial values of lengthscales in the kernel function. It can be a single numeric value or a vector:
@@ -106,7 +108,6 @@
 #' * [lgp()] for linked (D)GP emulator constructions.
 #' * [summary()] to summarize the trained GP emulator.
 #' * [write()] to save the GP emulator to a `.pkl` file.
-#' * [set_linked_idx()] to add the linking information to the GP emulator for linked emulations.
 #' * [design()] for sequential designs.
 #' * [update()] to update the GP emulator with new inputs and outputs.
 #' * [alm()], [mice()], [pei()], and [vigf()] to locate next design points.
@@ -164,6 +165,17 @@ gp <- function(X, Y, struc = NULL, name = 'sexp', lengthscale = rep(0.1, ncol(X)
     if (pkg.env$restart) return(invisible(NULL))
   }
 
+  if (!is.null(struc)) {
+    # Display a combined warning message
+    lifecycle::deprecate_warn(
+      when = "3.0.0",
+      what = "gp(struc)",
+      details = c(i = "The argument will be dropped in the next release.",
+                  i = "To customize GP specifications, please adjust the other arguments in the `gp()` function."
+      )
+    )
+  }
+
   if (!is.null(internal_input_idx)) {
     # Display a combined warning message
     lifecycle::deprecate_warn(

R/kernel.R

@@ -1,7 +1,11 @@
 #' @title Initialize a Gaussian process node
 #'
-#' @description This function constructs a kernel object to represent properties of a
-#'     Gaussian process node.
+#' @description
+#'
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function is deprecated and will be removed in the next release. To customize
+#'     DGP specifications, adjust the other arguments in the `dgp()` function instead.
 #'
 #' @param length a vector of lengthscales. The length of the vector equals to:
 #' 1. either one if the lengthscales in the kernel function are assumed same across input dimensions; or
@@ -59,12 +63,23 @@
 #' # on how to customize DGP structures using kernel().
 #' }
 #' @md
+#' @keywords internal
 #' @export
 kernel <- function(length, scale = 1., nugget = 1e-6, name = 'sexp', prior_name = 'ga', prior_coef = NULL, bounds = NULL, nugget_est = FALSE, scale_est = FALSE, input_dim = NULL, connect = NULL) {
   if ( is.null(pkg.env$dgpsi) ) {
     init_py(verb = F)
     if (pkg.env$restart) return(invisible(NULL))
   }
+
+  lifecycle::deprecate_warn(
+    when = "3.0.0",
+    what = "kernel()",
+    details = c(i = "The function will be removed in the next release.",
+                i=  "It may not be compatible with other functions in this version.",
+                i = "Please adjust the other arguments in `dgp()` function to customize DGP specifications."
+    )
+  )
+
   if ( name!='sexp' & name!='matern2.5' ) stop("'name' can only be either 'sexp' or 'matern2.5'.", call. = FALSE)
   if ( !is.null(prior_name) & prior_name!='ga' & prior_name!='inv_ga' ) stop("The provided 'prior_name' is not supported.", call. = FALSE)
 

R/likelihood.R

@@ -1,6 +1,12 @@
 #' @title Initialize a Poisson likelihood node
 #'
-#' @description This function constructs a likelihood object to represent a Poisson likelihood node.
+#' @description
+#'
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function is deprecated and will be removed in the next release.
+#'     To incorporate a Poisson likelihood node into a DGP structure,
+#'     use the `likelihood` argument in the `dgp()` function instead.
 #'
 #' @param input_dim a vector of length one that contains the indices of one GP node in the feeding
 #'     layer whose outputs feed into this likelihood node. When set to `NULL`,
@@ -18,12 +24,23 @@
 #' # on how to customize DGP structures using Poisson().
 #' }
 #' @md
+#' @keywords internal
 #' @export
 Poisson <- function(input_dim = NULL) {
   if ( is.null(pkg.env$dgpsi) ) {
     init_py(verb = F)
     if (pkg.env$restart) return(invisible(NULL))
   }
+
+  lifecycle::deprecate_warn(
+    when = "3.0.0",
+    what = "kernel()",
+    details = c(i = "The function will be removed in the next release.",
+                i=  "It may not be compatible with other functions in this version.",
+                i = "Please use the `likelihood` argument in `dgp()` function to incorporate a Poisson likelihood node into a DGP structure."
+    )
+  )
+
   if(!is.null(input_dim)){
     input_dim <- reticulate::np_array(as.integer(input_dim - 1))
   }
@@ -34,7 +51,13 @@ Poisson <- function(input_dim = NULL) {
 
 #' @title Initialize a heteroskedastic Gaussian likelihood node
 #'
-#' @description This function constructs a likelihood object to represent a heteroskedastic Gaussian likelihood node.
+#' @description
+#'
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function is deprecated and will be removed in the next release.
+#'     To incorporate a heteroskedastic Gaussian likelihood node into a DGP structure,
+#'     use the `likelihood` argument in the `dgp()` function instead.
 #'
 #' @param input_dim a vector of length two that contains the indices of two GP nodes in the feeding
 #'     layer whose outputs feed into this likelihood node. When set to `NULL`,
@@ -52,12 +75,23 @@ Poisson <- function(input_dim = NULL) {
 #' # on how to customize DGP structures using Hetero().
 #' }
 #' @md
+#' @keywords internal
 #' @export
 Hetero <- function(input_dim = NULL) {
   if ( is.null(pkg.env$dgpsi) ) {
     init_py(verb = F)
     if (pkg.env$restart) return(invisible(NULL))
   }
+
+  lifecycle::deprecate_warn(
+    when = "3.0.0",
+    what = "kernel()",
+    details = c(i = "The function will be removed in the next release.",
+                i=  "It may not be compatible with other functions in this version.",
+                i = "Please use the `likelihood` argument in `dgp()` function to incorporate a heteroskedastic Gaussian likelihood node into a DGP structure."
+    )
+  )
+
   if(!is.null(input_dim)){
     input_dim <- reticulate::np_array(as.integer(input_dim - 1))
   }
@@ -67,7 +101,13 @@ Hetero <- function(input_dim = NULL) {
 
 #' @title Initialize a negative Binomial likelihood node
 #'
-#' @description This function constructs a likelihood object to represent a negative Binomial likelihood node.
+#' @description
+#'
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function is deprecated and will be removed in the next release.
+#'     To incorporate a negative Binomial likelihood node into a DGP structure,
+#'     use the `likelihood` argument in the `dgp()` function instead.
 #'
 #' @param input_dim a vector of length two that contains the indices of two GP nodes in the feeding
 #'     layer whose outputs feed into this likelihood node. When set to `NULL`,
@@ -85,58 +125,26 @@ Hetero <- function(input_dim = NULL) {
 #' # on how to customize DGP structures using NegBin().
 #' }
 #' @md
+#' @keywords internal
 #' @export
 NegBin <- function(input_dim = NULL) {
   if ( is.null(pkg.env$dgpsi) ) {
     init_py(verb = F)
     if (pkg.env$restart) return(invisible(NULL))
   }
-  if(!is.null(input_dim)){
-    input_dim <- reticulate::np_array(as.integer(input_dim - 1))
-  }
-  res <- pkg.env$dgpsi$NegBin(input_dim)
-  return(res)
-}
 
-#' @title Initialize a Categorical likelihood node
-#'
-#' @description
-#'
-#' `r new_badge("new")`
-#'
-#' This function constructs a likelihood object to represent a categorical likelihood node.
-#'
-#' @param K an integer specifying the number of classes in the training data. If `K` is set to `NULL` (the default),
-#' its value will be inferred from the training data when running [dgp()]. Defaults to `NULL`.
-#' @param input_dim a vector that specifies which GP node outputs feed into this likelihood node. It should be either:
-#' * A vector of length `1` (for binary output), or
-#' * A vector of length `K` (for `K`-class output), containing the indices of one or `K` GP nodes in the feeding layer.
-#'
-#' If `input_dim` is set to `NULL` (the default), all GP node outputs from the feeding layer feed into the likelihood node.
-#' In this case, you must ensure that the feeding layer contains exactly one or `K` GP nodes. Defaults to `NULL`.
-#'
-#' @return A 'python' object to represent a categorical likelihood node.
-#' @note The categorical likelihood node can only be linked to one or `K` feeding GP nodes.
-#' @details See further examples and tutorials at <https://mingdeyu.github.io/dgpsi-R/>.
-#' @examples
-#' \dontrun{
-#'
-#' # Check https://mingdeyu.github.io/dgpsi-R/ for examples
-#' # on how to customize DGP structures using Categorical().
-#' }
-#' @md
-#' @export
-Categorical <- function(K = NULL, input_dim = NULL) {
-  if ( is.null(pkg.env$dgpsi) ) {
-    init_py(verb = F)
-    if (pkg.env$restart) return(invisible(NULL))
-  }
+  lifecycle::deprecate_warn(
+    when = "3.0.0",
+    what = "kernel()",
+    details = c(i = "The function will be removed in the next release.",
+                i=  "It may not be compatible with other functions in this version.",
+                i = "Please use the `likelihood` argument in `dgp()` function to incorporate a negative Binomial likelihood node into a DGP structure."
+    )
+  )
+
   if(!is.null(input_dim)){
     input_dim <- reticulate::np_array(as.integer(input_dim - 1))
   }
-  if(!is.null(K)){
-    K <- reticulate::np_array(as.integer(K))
-  }
-  res <- pkg.env$dgpsi$Categorical(K, input_dim)
+  res <- pkg.env$dgpsi$NegBin(input_dim)
   return(res)
 }

R/utils.R

@@ -1,6 +1,7 @@
 #' @title Combine layers
 #'
 #' @description
+#'
 #' `r lifecycle::badge("deprecated")`
 #'
 #' This function is deprecated and will be removed in the next release, as it is
@@ -10,7 +11,7 @@
 #'
 #' @param ... a sequence of lists:
 #' 1. For DGP emulations, each list represents a DGP layer and contains GP nodes (produced by [kernel()]), or
-#'    likelihood nodes (produced by [Poisson()], [Hetero()], [NegBin()], or [Categorical()]).
+#'    likelihood nodes (produced by [Poisson()], [Hetero()], or [NegBin()].
 #' 2. For linked (D)GP emulations, each list represents a system layer and contains emulators (produced by [gp()] or
 #'    [dgp()]) in that layer.
 #'
@@ -1594,10 +1595,7 @@ window <- function(object, start, end = NULL, thin = 1) {
 #' @description This function computes the negative predicted log-likelihood from a
 #'     DGP emulator with a likelihood layer.
 #'
-#' @param object an instance of the `dgp` class and it should be produced by [dgp()] with one of the following two settings:
-#' 1. if `struc = NULL`, `likelihood` is not `NULL`;
-#' 2. if a customized structure is provided to `struc`, the final layer must be likelihood layer containing only one
-#'    likelihood node produced by [Poisson()], [Hetero()], [NegBin()] or [Categorical()].
+#' @param object an instance of the `dgp` class and it should be produced by [dgp()] with `likelihood` not being `NULL`;
 #' @param x a matrix where each row is an input testing data point and each column is an input dimension.
 #' @param y a matrix with only one column where each row is a scalar-valued testing output data point.
 #'

_pkgdown.yml

@@ -72,16 +72,6 @@ reference:
   contents:
   - init_py
 
-- title: "Basic Nodes"
-  desc: >
-    Functions to customize stuctures of GP and DGP emulators.
-  contents:
-  - kernel
-  - Hetero
-  - Poisson
-  - NegBin
-  - Categorical
-
 - title: "GP, DGP, and Linked (D)GP Emulations"
   desc: >
     Functions to train, validate, and make predictions from GP, DGP, and Linked (D)GP emulators.