% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bart_package_f_tests.R
\name{cov_importance_test}
\alias{cov_importance_test}
\title{Importance Test for Covariate(s) of Interest}
\usage{
cov_importance_test(
  bart_machine,
  covariates = NULL,
  num_permutation_samples = 100,
  plot = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{bart_machine}{An object of class ``bart_machine''.}

\item{covariates}{A vector of names of covariates of interest to be tested for having an effect on the response. A value of NULL
indicates an omnibus test for all covariates having an effect on the response. If the name of a covariate is a factor,
the entire factor will be permuted. We do not recommend entering the names of factor covariate dummies.}

\item{num_permutation_samples}{The number of times to permute the covariates of interest and create a corresponding new BART model (see details).}

\item{plot}{If \code{TRUE}, this produces a histogram of the Pseudo-Rsq's / total misclassification error rates from
the \code{num_permutations} BART models created with the \code{covariates} permuted. The plot also illustrates
the observed Pseudo-Rsq's / total misclassification error rate from the original training data and indicates
the test's p-value.}

\item{verbose}{If TRUE, prints progress and summary messages.}
}
\value{
\item{permutation_samples_of_error}{A vector which records the error metric of the BART models with the covariates permuted (see details).}
\item{observed_error_estimate}{For regression, this is the Pseudo-Rsq on the original
training data set. For classification, this is the observed total misclassification error
on the original training data set.}
\item{pval}{The approximate p-value for this test (see details).
}
}
\description{
This function tests the null hypothesis \eqn{H_0}: These covariates of interest
do not affect the response under the assumptions of the BART
model.
}
\details{
To test the importance of a covariate or a set of covariates of interest on the response, this function generates
\code{num_permutations} BART models with the covariate(s) of interest permuted (differently each time).
On each run, a measure of fit is recorded. For regression, the metric is Pseudo-Rsq; for classification, it is
total misclassification error.\cr A
p-value can then be generated as follows. For regression, the p-value is the number of
permutation-sampled Pseudo-Rsq's greater than the observed Pseudo-Rsq divided by
\code{num_permutations + 1}. For classification, the p-value is the number of permutation-sampled
total misclassification errors less than the observed total misclassification error divided by \code{num_permutations + 1}.
}
\note{
This function is parallelized by the number of cores set in \code{\link{set_bart_machine_num_cores}}.
}
\examples{
\dontrun{
##regression example

##generate Friedman data
set.seed(11)
n  = 200
p = 5
X = data.frame(matrix(runif(n * p), ncol = p))
y = 10 * sin(pi* X[ ,1] * X[,2]) +20 * (X[,3] -.5)^2 + 10 * X[ ,4] + 5 * X[,5] + rnorm(n)

##build BART regression model
bart_machine = bartMachine(X, y)

##now test if X[, 1] affects Y nonparametrically under the BART model assumptions
cov_importance_test(bart_machine, covariates = c(1))
## note the plot and the printed p-value

}
}
\references{
Adam Kapelner, Justin Bleich (2016). bartMachine: Machine Learning
with Bayesian Additive Regression Trees. Journal of Statistical
Software, 70(4), 1-40. \doi{10.18637/jss.v070.i04}
}
\author{
Adam Kapelner and Justin Bleich
}
