% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/kernel.R
\name{ForestKernelComputation}
\alias{ForestKernelComputation}
\alias{computeForestLeafIndices}
\alias{computeForestLeafVariances}
\alias{computeForestMaxLeafIndex}
\title{Forest Kernel Computation Routines}
\usage{
computeForestLeafIndices(
  model_object,
  covariates,
  forest_type = NULL,
  propensity = NULL,
  forest_inds = NULL
)

computeForestLeafVariances(model_object, forest_type, forest_inds = NULL)

computeForestMaxLeafIndex(model_object, forest_type = NULL, forest_inds = NULL)
}
\arguments{
\item{model_object}{Object of type \code{bartmodel}, \code{bcfmodel}, or \code{ForestSamples} corresponding to a BART / BCF model with at least one forest sample, or a low-level \code{ForestSamples} object.}

\item{covariates}{Covariates to use for prediction. Must have the same dimensions / column types as the data used to train a forest.}

\item{forest_type}{Which forest to use from \code{model_object}.
Valid inputs depend on the model type, and whether or not a

\strong{1. BART}
\itemize{
\item \code{'mean'}: Extracts leaf indices for the mean forest
\item \code{'variance'}: Extracts leaf indices for the variance forest
}

\strong{2. BCF}
\itemize{
\item \code{'prognostic'}: Extracts leaf indices for the prognostic forest
\item \code{'treatment'}: Extracts leaf indices for the treatment effect forest
\item \code{'variance'}: Extracts leaf indices for the variance forest
}

\strong{3. ForestSamples}
\itemize{
\item \code{NULL}: It is not necessary to disambiguate when this function is called directly on a \code{ForestSamples} object. This is the default value of this
}}

\item{propensity}{(Optional) Propensities used for prediction (BCF-only).}

\item{forest_inds}{(Optional) Indices of the forest sample(s) for which to compute max leaf indices. If not provided,
this function will return max leaf indices for every sample of a forest.
This function uses 0-indexing, so the first forest sample corresponds to \code{forest_num = 0}, and so on.}
}
\value{
\code{computeForestLeafIndices} returns a vector of size \code{num_obs * num_trees}, where \code{num_obs = nrow(covariates)}
and \code{num_trees} is the number of trees in the relevant forest of \code{model_object}.

\code{computeForestLeafVariances} returns a vector of size \code{length(forest_inds)} with the leaf scale parameter for each requested forest.

\code{computeForestMaxLeafIndex} returns a vector containing the largest possible leaf index computable by \code{computeForestLeafIndices} for the forests in a designated forest sample container.
}
\description{
Decision tree ensembles can be represented in part by a "kernel" function whose distance metric
is based on the extent to which two observations are mapped to the same leaf nodes.
This function group offers utilities for evaluating this kernel.

\code{computeForestLeafIndices} computes and return a vector representation of a forest's
leaf predictions for every observation in a dataset.
The resulting vector has a "row-major" format that can be easily re-represented as
as a CSR sparse matrix: elements are organized so that the first \code{n} elements
correspond to leaf predictions for all \code{n} observations in a dataset for the
first tree in an ensemble, the next \code{n} elements correspond to predictions for
the second tree and so on. The "data" for each element corresponds to a uniquely
mapped column index that corresponds to a single leaf of a single tree (i.e.
if tree 1 has 3 leaves, its column indices range from 0 to 2, and then tree 2's
leaf indices begin at 3, etc...).

\code{computeForestLeafVariances} returns each forest's leaf node scale parameters.
If leaf scale is not sampled for the forest in question, the function throws an error that the
leaf model does not have a stochastic scale parameter.

\code{computeForestMaxLeafIndex} computes and returns the largest possible leaf index computable by \code{computeForestLeafIndices} for the forests in a designated forest sample container.

These functions are intended for advanced use cases in which users require detailed control of sampling algorithms and data structures.
Minimal input validation and error checks are performed -- users are responsible for providing the correct inputs.
For tutorials on the "proper" usage of the stochtree's advanced workflow, we provide several vignettes at \url{https://stochtree.ai/}
}
\examples{
X <- matrix(runif(10*100), ncol = 10)
y <- -5 + 10*(X[,1] > 0.5) + rnorm(100)
bart_model <- bart(X, y, num_gfr=0, num_mcmc=10)
leaf_indices <- computeForestLeafIndices(bart_model, X, "mean")
leaf_indices <- computeForestLeafIndices(bart_model, X, "mean", 0)
leaf_indices <- computeForestLeafIndices(bart_model, X, "mean", c(1,3,9))
leaf_variances <- computeForestLeafVariances(bart_model, "mean")
leaf_variances <- computeForestLeafVariances(bart_model, "mean", 0)
leaf_variances <- computeForestLeafVariances(bart_model, "mean", c(1,3,5))
max_leaf_index <- computeForestMaxLeafIndex(bart_model, "mean")
max_leaf_index <- computeForestMaxLeafIndex(bart_model, "mean", 0)
max_leaf_index <- computeForestMaxLeafIndex(bart_model, "mean", c(1,3,9))

}
