R/fitted_NBKP.R

In NBKP: Beta Kernel Process Modeling with Negative Binomial Response

#' @rdname fitted.NBKP
#' @title Extract NBKP Model Fitted Values
#'
#' @description Compute the posterior fitted values from a fitted \code{NBKP} object.
#' For a \code{NBKP} object, this returns the posterior mean count from the Gamma‑Negative Binomial conjugate posterior.
#'
#' @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 numeric vector containing posterior mean count estimates at the training inputs.
#'
#' @details For a \code{NBKP} model, the fitted values correspond to the posterior mean count,
#' computed from the Gamma Kernel Process posterior distribution.
#'
#' @keywords NBKP
#'
#' @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 fitted values
#' fitted(model)
#' }
#'
#' @export
#' @method fitted NBKP
fitted.NBKP <- function(object, ...) {
  # Posterior Gamma parameters
  alpha_n <- object$alpha_n
  beta_n  <- object$beta_n

  # Posterior mean count (Gamma mean: alpha / beta)
  fitted_value <- alpha_n / beta_n
  return(fitted_value)
}