% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/XRF.R, R/XBART.R
\name{X-Learner}
\alias{X-Learner}
\alias{X_RF}
\alias{X_BART}
\title{X-Learners}
\usage{
X_RF(feat, tr, yobs, predmode = "propmean", nthread = 0,
  verbose = FALSE, mu.forestry = list(relevant.Variable = 1:ncol(feat),
  ntree = 1000, replace = TRUE, sample.fraction = 0.8, mtry =
  round(ncol(feat) * 13/20), nodesizeSpl = 2, nodesizeAvg = 1, splitratio =
  1, middleSplit = TRUE), tau.forestry = list(relevant.Variable =
  1:ncol(feat), ntree = 1000, replace = TRUE, sample.fraction = 0.7, mtry =
  round(ncol(feat) * 17/20), nodesizeSpl = 5, nodesizeAvg = 6, splitratio =
  0.8, middleSplit = TRUE), e.forestry = list(relevant.Variable =
  1:ncol(feat), ntree = 500, replace = TRUE, sample.fraction = 0.5, mtry =
  ncol(feat), nodesizeSpl = 11, nodesizeAvg = 33, splitratio = 0.5,
  middleSplit = FALSE))

X_BART(feat, tr, yobs, predmode = "pscore", nthread = 1,
  ndpost = 1200, ntree = 200, mu.BART = list(sparse = FALSE, theta =
  0, omega = 1, a = 0.5, b = 1, augment = FALSE, rho = NULL, usequants =
  FALSE, cont = FALSE, sigest = NA, sigdf = 3, sigquant = 0.9, k = 2, power
  = 2, base = 0.95, sigmaf = NA, lambda = NA, numcut = 100L, nskip = 100L),
  tau.BART = list(sparse = FALSE, theta = 0, omega = 1, a = 0.5, b = 1,
  augment = FALSE, rho = NULL, usequants = FALSE, cont = FALSE, sigest =
  NA, sigdf = 3, sigquant = 0.9, k = 2, power = 2, base = 0.95, sigmaf =
  NA, lambda = NA, numcut = 100L, nskip = 100L), e.BART = list(sparse =
  FALSE, theta = 0, omega = 1, a = 0.5, b = 1, augment = FALSE, rho = NULL,
  usequants = FALSE, cont = FALSE, sigest = NA, sigdf = 3, sigquant = 0.9,
  k = 2, power = 2, base = 0.95, sigmaf = NA, lambda = NA, numcut = 100L,
  nskip = 100L))
}
\arguments{
\item{feat}{A data frame containing the features.}

\item{tr}{A numeric vector with 0 for control and 1 for treated variables.}

\item{yobs}{A numeric vector containing the observed outcomes.}

\item{predmode}{Specifies how the two estimators of the second stage should
be aggregated. Possible types are "propmean," "control," and "treated." The
default is "propmean," which refers to propensity score weighting.}

\item{nthread}{Number of threads which should be used to work in parallel.}

\item{verbose}{TRUE for detailed output, FALSE for no output.}

\item{mu.forestry, tau.forestry, e.forestry}{A list containing the
hyperparameters for the \code{forestry} package that are used for
estimating the response functions, the CATE, and the propensity score.
These hyperparameters are passed to the \code{forestry} package. (Please
refer to the \href{https://github.com/soerenkuenzel/forestry}{forestry}
package for a more detailed documentation of the hyperparamters.)
\itemize{
   \item \code{relevant.Variable} Variables that are only used in the first 
         stage.
   \item \code{ntree} Numbers of trees used in the first stage.
   \item \code{replace} Sample with or without replacement in the first 
         stage.
   \item \code{sample.fraction} The size of total samples to draw for the 
         training data in the first stage.
   \item \code{mtry} The number of variables randomly selected in each 
         splitting point.
   \item \code{nodesizeSpl} Minimum nodesize in the first stage for 
         the observations in the splitting set. (See the details of the 
         \code{forestry} package)
   \item \code{nodesizeAvg} Minimum nodesize in the first stage for 
         the observations in the averaging set.
   \item \code{splitratio} Proportion of the training data used as the 
         splitting dataset in the first stage.
   \item \code{middleSplit} If true, the split value will be exactly in the 
         middle of two observations. Otherwise, it will take a point 
         based on a uniform distribution between the two observations. 
}}

\item{ndpost}{Number of posterior draws.}

\item{ntree}{Number of trees.}

\item{mu.BART, tau.BART, e.BART}{hyperparameters of the BART functions for the
estimates of the first and second stage and the propensity score. Use
\code{?BART::mc.wbart} for a detailed explanation of their effects.}
}
\value{
An object from a class that contains the \code{CATEestimator}
  class. It should be used with one of the following functions:
  \code{EstimateCATE}, \code{CateCI}, and \code{CateBIAS}. The object has at least the
  following slots:
  \item{\code{feature_train}}{A copy of feat.}
  \item{\code{tr_train}}{A copy of tr.}
  \item{\code{yobs_train}}{A copy of yobs.}
  \item{\code{creator}}{Function call that creates the CATE estimator. This
  is used for different bootstrap procedures.}
}
\description{
X_RF is an implementation of the X-learner with Random Forests
  (Breiman 2001) in the first and second stage.

X_BART is an implementation of the X-learner with Bayesian
  Additive Regression Trees (Chipman et al. 2010) at the first and second stage
}
\details{
The X-Learner estimates the CATE in three steps:
\enumerate{
 \item
    Estimate the response functions 
    \deqn{\mu_0(x) = E[Y(0) | X = x]}
    \deqn{\mu_1(x) = E[Y(1) | X = x]} 
    using the base learner and denote the estimates as \eqn{\hat \mu_0} and
    \eqn{\hat \mu_1}.
 \item
    Impute the treatment effects for the individuals in the treated group,
    based on the control outcome estimator, and the treatment effects for the
    individuals in the control group, based on the treatment outcome
    estimator, that is,
    \deqn{D^1_i = Y_i(1) - \hat \mu_0(X_i)}
    \deqn{D^0_i = \hat \mu_1(X_i) - Y_i(0).}
    Now employ the base learner in two ways: using \eqn{D^1_i} as the
    dependent variable to obtain \eqn{\hat \tau_1(x)}, and using \eqn{D^0_i}
    as the dependent variable to obtain \eqn{\hat \tau_0(x)}.
 \item 
    Define the CATE estimate by a weighted average of the two estimates at
    Stage 2: 
    \deqn{\tau(x) = g(x) \hat \tau_0(x) + (1 - g(x)) \hat \tau_1(x).} 
    If \code{predmode = "propmean"}, then \eqn{g(x) = e(x)}, where
    \eqn{e(x)} is an estimate of the propensity score using the 
    \href{https://github.com/soerenkuenzel/forestry}{\code{forestry}} Random Forests
    version with the hyperparameters specified in \code{e.forestry}.
    If \code{predmode = "control"}, then \eqn{g(x) = 1}, and if 
    \code{predmode = "treated"}, then \eqn{g(x) = 0}.
}
}
\examples{
require(causalToolbox)

# create example data set
simulated_experiment <- simulate_causal_experiment(
  ntrain = 1000,
  ntest = 1000,
  dim = 10
)
feat <- simulated_experiment$feat_tr
tr <- simulated_experiment$W_tr
yobs <- simulated_experiment$Yobs_tr
feature_test <- simulated_experiment$feat_te

# create the CATE estimator using Random Forests (RF)
xl_rf <- X_RF(feat = feat, tr = tr, yobs = yobs)
tl_rf <- T_RF(feat = feat, tr = tr, yobs = yobs)
sl_rf <- S_RF(feat = feat, tr = tr, yobs = yobs)
ml_rf <- M_RF(feat = feat, tr = tr, yobs = yobs)
xl_bt <- X_BART(feat = feat, tr = tr, yobs = yobs)
tl_bt <- T_BART(feat = feat, tr = tr, yobs = yobs)
sl_bt <- S_BART(feat = feat, tr = tr, yobs = yobs)
ml_bt <- M_BART(feat = feat, tr = tr, yobs = yobs)
  
cate_esti_xrf <- EstimateCate(xl_rf, feature_test)

# evaluate the performance.
cate_true <- simulated_experiment$tau_te
mean((cate_esti_xrf - cate_true) ^ 2)
\dontrun{
# create confidence intervals via bootstrapping. 
xl_ci_rf <- CateCI(xl_rf, feature_test, B = 500)
}
}
\references{
\itemize{
  \item Sören Künzel, Jasjeet Sekhon, Peter Bickel, and Bin Yu (2017). 
    MetaLearners for Estimating Heterogeneous Treatment Effects using
    Machine Learning. 
    \url{https://www.pnas.org/content/116/10/4156}
  \item 
    Sören Künzel, Simon Walter, and Jasjeet Sekhon (2018).
    Causaltoolbox---Estimator Stability for Heterogeneous Treatment Effects.
    \url{https://arxiv.org/pdf/1811.02833.pdf}
  \item Sören Künzel, Bradly Stadie, Nikita Vemuri, Varsha Ramakrishnan, 
    Jasjeet Sekhon, and Pieter Abbeel (2018). 
    Transfer Learning for Estimating Causal Effects using Neural Networks. 
    \url{https://arxiv.org/pdf/1808.07804.pdf}
  }
}
\seealso{
Other metalearners: \code{\link{M-Learner}},
  \code{\link{S-Learner}}, \code{\link{T-Learner}}
}
\author{
Soeren R. Kuenzel
}
\concept{metalearners}
