% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tree_explainer.R
\name{rsq}
\alias{rsq}
\title{Calculate Feature-Specific R-Squared Values}
\usage{
rsq(
  explainer,
  x,
  y,
  feature_names = NULL,
  local = FALSE,
  nsample = NULL,
  sd_out = TRUE,
  ci_out = TRUE,
  level = 0.95,
  nfrac = NULL,
  random_state = 42,
  ncore = 1L
)
}
\arguments{
\item{explainer}{A qshap_tree_explainer object created by \code{gazer()}}

\item{x}{Feature matrix or data frame with n samples and p features}

\item{y}{Response vector of length n}

\item{feature_names}{Character vector of feature names. If NULL, uses column names from x.}

\item{local}{Logical; if TRUE, returns both R-squared values and loss matrix}

\item{nsample}{Optional integer; number of samples to use (random subsample if less than nrow(x))}

\item{sd_out}{Logical; if TRUE, returns standard deviations of R-squared estimates}

\item{ci_out}{Logical; if TRUE, returns Wald-style confidence intervals for each feature's R-squared (normal approximation using sd_rsq)}

\item{level}{Confidence level for the intervals (default 0.95)}

\item{nfrac}{Optional numeric in (0,1); fraction of samples to use (alternative to nsample)}

\item{random_state}{Integer seed for reproducible sampling}

\item{ncore}{Number of cores for parallel processing. Use -1 for all available cores, 
or a positive integer. Default is 1 (no parallelization)}
}
\value{
A \code{qshap_result} object containing:
  \itemize{
    \item \code{rsq}: Numeric vector of feature-specific R² values
    \item \code{feature_names}: Character vector of feature names
    \item \code{total_rsq}: Total R² (sum of feature-specific values)
    \item \code{n_samples}: Number of samples
    \item \code{n_features}: Number of features
    \item \code{loss}: Loss matrix (if local=TRUE)
  }
}
\description{
Computes feature-specific R-squared values using Q-SHAP decomposition,
returning a \code{qshap_result} object with better formatting and additional metadata.
The \code{qshap_result} object includes feature names, total R², sample counts,
and provides enhanced \code{print()}, \code{summary()}, and \code{as.data.frame()}
methods for easier analysis.
}
\details{
This function provides a user-friendly interface for Q-SHAP R² computation:
\itemize{
  \item Automatically extracts feature names from the input data
  \item Returns a structured object with metadata
  \item Provides enhanced printing with top features displayed by default
  \item Includes a comprehensive \code{summary()} method
  \item Can be easily converted to a data frame with \code{as.data.frame()}
}
}
\examples{
library(xgboost)
set.seed(42)
n <- 100
p <- 100
X <- matrix(rnorm(n * p), nrow = n, ncol = p)
y <- X[, 1] - X[, 2] + rnorm(n, sd = 0.2)
model <- xgboost(X, y, nrounds = 15, max_depth = 2, verbose = 0)
explainer <- gazer(model)
result <- rsq(explainer, X, y)
print(result)

}
\seealso{
\code{\link{qshap_result}}
}
