% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gpb.Booster.R
\name{predict.gpb.Booster}
\alias{predict.gpb.Booster}
\title{Prediction function for \code{gpb.Booster} objects}
\usage{
\method{predict}{gpb.Booster}(object, data, start_iteration = NULL,
  num_iteration = NULL, pred_latent = FALSE, predleaf = FALSE,
  predcontrib = FALSE, header = FALSE, reshape = FALSE,
  group_data_pred = NULL, group_rand_coef_data_pred = NULL,
  gp_coords_pred = NULL, gp_rand_coef_data_pred = NULL,
  cluster_ids_pred = NULL, predict_cov_mat = FALSE, predict_var = FALSE,
  sample_posterior = FALSE, sample_prior = FALSE, num_post_samples = 100,
  num_prior_samples = 100, cov_pars = NULL, offset_pred = NULL,
  ignore_gp_model = FALSE, rawscore = NULL, vecchia_pred_type = NULL,
  num_neighbors_pred = NULL, ...)
}
\arguments{
\item{object}{Object of class \code{gpb.Booster}}

\item{data}{a \code{matrix} object, a \code{dgCMatrix} object or a character representing a filename}

\item{start_iteration}{int or NULL, optional (default=NULL)
Start index of the iteration to predict.
If NULL or <= 0, starts from the first iteration.}

\item{num_iteration}{int or NULL, optional (default=NULL)
Limit number of iterations in the prediction.
If NULL, if the best iteration exists and start_iteration is NULL or <= 0, the
best iteration is used; otherwise, all iterations from start_iteration are used.
If <= 0, all iterations from start_iteration are used (no limits).}

\item{pred_latent}{If TRUE latent variables, both fixed effects (tree-ensemble) 
and random effects (\code{gp_model}) are predicted. Otherwise, the response variable 
(label) is predicted. Depending on how the argument 'pred_latent' is set,
different values are returned from this function; see the 'Value' section for more details. 
If there is no \code{gp_model}, this argument corresponds to 'raw_score' in LightGBM.}

\item{predleaf}{whether predict leaf index instead.}

\item{predcontrib}{return per-feature contributions for each record.}

\item{header}{only used for prediction for text file. True if text file has header}

\item{reshape}{whether to reshape the vector of predictions to a matrix form when there are several
prediction outputs per case.}

\item{group_data_pred}{A \code{vector} or \code{matrix} with elements being group levels 
for which predictions are made (if there are grouped random effects in the \code{GPModel})}

\item{group_rand_coef_data_pred}{A \code{vector} or \code{matrix} with covariate data 
for grouped random coefficients (if there are some in the \code{GPModel})}

\item{gp_coords_pred}{A \code{matrix} with prediction coordinates (=features) for 
Gaussian process (if there is a GP in the \code{GPModel})}

\item{gp_rand_coef_data_pred}{A \code{vector} or \code{matrix} with covariate data for 
Gaussian process random coefficients (if there are some in the \code{GPModel})}

\item{cluster_ids_pred}{A \code{vector} with elements indicating the realizations of 
random effects / Gaussian processes for which predictions are made 
(set to NULL if you have not specified this when creating the \code{GPModel})}

\item{predict_cov_mat}{A \code{boolean}. If TRUE, the (posterior) 
predictive covariance is calculated in addition to the (posterior) predictive mean}

\item{predict_var}{A \code{boolean}. If TRUE, the (posterior) 
predictive variances are calculated}

\item{sample_posterior}{A \code{boolean}. If TRUE, samples from the posterior are drawn (currently very limited support)}

\item{sample_prior}{A \code{boolean}. If TRUE, samples from the prior are drawn (currently very limited support)}

\item{num_post_samples}{A \code{numeric} with the number of posterior samples to draw if 'sample_posterior=TRUE'}

\item{num_prior_samples}{A \code{numeric} with the number of prior samples to draw if 'sample_prior=TRUE'}

\item{cov_pars}{A \code{vector} containing covariance parameters which are used if the 
\code{gp_model} has not been trained or if predictions should be made for other 
parameters than the trained ones}

\item{offset_pred}{A \code{numeric} \code{vector}. 
Offsets for prediction: additional fixed effects contributions that are added to the predictor for the prediction points. 
The length of this vector needs to equal the number of prediction points.}

\item{ignore_gp_model}{A \code{boolean}. If TRUE, predictions are only made for the tree ensemble part
and the \code{gp_model} is ignored}

\item{rawscore}{This is discontinued. Use the renamed equivalent argument 
\code{pred_latent} instead}

\item{vecchia_pred_type}{A \code{string} specifying the type of Vecchia approximation used for making predictions.
This is discontinued here. Use the function 'set_prediction_data' to specify this}

\item{num_neighbors_pred}{an \code{integer} specifying the number of neighbors for making predictions.
This is discontinued here. Use the function 'set_prediction_data' to specify this}

\item{...}{Additional named arguments passed to the \code{predict()} method of
the \code{gpb.Booster} object passed to \code{object}.}
}
\value{
either a list with vectors or a single vector / matrix depending on 
whether there is a \code{gp_model} or not
\itemize{
  \item {If there is a \code{gp_model}, the result dict contains the following entries.
\itemize{
  \item { 1. If \code{pred_latent} is FALSE (=default), the dict contains the following 2 entries:
\itemize{
     \item { result["response_mean"] are the predictive means of the response variable (Label) taking into account
    both the fixed effects (tree-ensemble) and the random effects (\code{gp_model}) }
      \item { result["response_var"] are the predictive  covariances or variances of the response variable
  (only if 'predict_var' or 'predict_cov' is TRUE) }
  \item { result["posterior_samples"] samples of the posterior of the response variable (if 'sample_posterior' is TRUE) }
  \item { result["prior_samples"] samples of the prior (if 'sample_prior' is TRUE) }
  }
  }
   \item { 2. If \code{pred_latent} is TRUE, the dict contains the following 3 entries:
\itemize{
      \item { result["fixed_effect"] are the predictions from the tree-ensemble }
      \item { result["random_effect_mean"] are the predictive means of the \code{gp_model} excluding the 'fixed_effect' }
      \item { result["random_effect_cov"] are the predictive covariances or variances of the \code{gp_model}
  (only if 'predict_var' or 'predict_cov' is TRUE) }
     \item { result["posterior_samples"] samples of the posterior of the \code{gp_model} (if 'sample_posterior' is TRUE) excluding the 'fixed_effect' }
     \item { result["prior_samples"] samples of the prior of the \code{gp_model} (if 'sample_prior' is TRUE) }
  }
  }
  }
  }
  \item { If there is no \code{gp_model} or \code{predcontrib} or \code{ignore_gp_model} 
    are TRUE, the result contains predictions from the tree-booster only. }
}
}
\description{
Prediction function for \code{gpb.Booster} objects
}
\examples{

# See https://github.com/fabsig/GPBoost/tree/master/R-package for more examples

\donttest{
library(gpboost)
data(GPBoost_data, package = "gpboost")

#--------------------Combine tree-boosting and grouped random effects model----------------
# Create random effects model
gp_model <- GPModel(group_data = group_data[,1], likelihood = "gaussian")
# The default optimizer for covariance parameters (hyperparameters) is 
# Nesterov-accelerated gradient descent.
# This can be changed to, e.g., Nelder-Mead as follows:
# re_params <- list(optimizer_cov = "nelder_mead")
# gp_model$set_optim_params(params=re_params)
# Use trace = TRUE to monitor convergence:
# re_params <- list(trace = TRUE)
# gp_model$set_optim_params(params=re_params)

# Train model
bst <- gpboost(data = X, label = y, gp_model = gp_model, nrounds = 16,
               learning_rate = 0.05, max_depth = 6, min_data_in_leaf = 5,
               verbose = 0)
# Estimated random effects model
summary(gp_model)

# Make predictions
# Predict latent variables
pred <- predict(bst, data = X_test, group_data_pred = group_data_test[,1],
                predict_var = TRUE, pred_latent = TRUE)
pred$random_effect_mean # Predicted latent random effects mean
pred$random_effect_cov # Predicted random effects variances
pred$fixed_effect # Predicted fixed effects from tree ensemble
# Predict response variable
pred_resp <- predict(bst, data = X_test, group_data_pred = group_data_test[,1],
                     predict_var = TRUE, pred_latent = FALSE)
pred_resp$response_mean # Predicted response mean
# For Gaussian data: pred$random_effect_mean + pred$fixed_effect = pred_resp$response_mean
pred$random_effect_mean + pred$fixed_effect - pred_resp$response_mean

#--------------------Combine tree-boosting and Gaussian process model----------------
# Create Gaussian process model
gp_model <- GPModel(gp_coords = coords, cov_function = "exponential",
                    likelihood = "gaussian")
# Train model
bst <- gpboost(data = X, label = y, gp_model = gp_model, nrounds = 8,
               learning_rate = 0.1, max_depth = 6, min_data_in_leaf = 5,
               verbose = 0)
# Estimated random effects model
summary(gp_model)
# Make predictions
pred <- predict(bst, data = X_test, gp_coords_pred = coords_test,
                predict_var = TRUE, pred_latent = TRUE)
pred$random_effect_mean # Predicted latent random effects mean
pred$random_effect_cov # Predicted random effects variances
pred$fixed_effect # Predicted fixed effects from tree ensemble
# Predict response variable
pred_resp <- predict(bst, data = X_test, gp_coords_pred = coords_test,
                     predict_var = TRUE, pred_latent = FALSE)
pred_resp$response_mean # Predicted response mean
}
}
\author{
Fabio Sigrist, authors of the LightGBM R package
}
