R/parameter_NBKP.R

In NBKP: Beta Kernel Process Modeling with Negative Binomial Response

#' @title Extract Model Parameters from a Fitted NBKP Model
#'
#' @description Retrieve the key model parameters from a fitted \code{NBKP} object.
#' This includes the optimized kernel hyperparameters, posterior Gamma parameters,
#' and the negative‑binomial dispersion parameter.
#'
#' @param object An object of class \code{NBKP}, typically the result of a call to \code{\link{fit_NBKP}}.
#' @param ... Additional arguments (currently unused).
#'
#' @return A named list containing:
#' \itemize{
#'   \item{\code{theta}: Estimated kernel hyperparameters.}
#'   \item{\code{phi}: Negative‑binomial dispersion parameter.}
#'   \item{\code{alpha_n}: Posterior Gamma \eqn{\alpha} parameters.}
#'   \item{\code{beta_n}: Posterior Gamma \eqn{\beta} parameters.}
#' }
#'
#' @keywords NBKP
#'
#' @seealso \code{\link{fit_NBKP}} for fitting NBKP models.
#'
#' @references Zhao J, Qing K, Xu J (2025). \emph{BKP: An R Package for Beta
#' Kernel Process Modeling}. arXiv. https://doi.org/10.48550/arxiv.2508.10447.
#'
#' @examples
#' \donttest{
#' set.seed(123)
#'
#' # Define true mean function
#' true_mu_fun <- function(x) {
#'   exp(sin(x) + 0.5)
#' }
#'
#' n <- 30
#' Xbounds <- matrix(c(-2, 2), nrow = 1)
#' X <- tgp::lhs(n = n, rect = Xbounds)
#' true_mu <- true_mu_fun(X)
#' y <- rnbinom(n, size = 1, mu = true_mu)
#'
#' # Fit NBKP model
#' model <- fit_NBKP(X, y, Xbounds = Xbounds)
#'
#' # Extract posterior and kernel parameters
#' parameter(model)
#' }
#'
#' @export
parameter <- function(object, ...) {
  UseMethod("parameter")
}

#' @rdname parameter
#' @export
#' @method parameter NBKP
parameter.NBKP <- function(object, ...) {
  list(
    theta    = object$theta_opt,
    phi      = object$phi,
    alpha_n  = object$alpha_n,
    beta_n   = object$beta_n
  )
}