FindIt: FindIt for Estimating Heterogeneous Treatment Effects
In FindIt: Finding Heterogeneous Treatment Effects

Description Usage Arguments Details Value Author(s) References Examples

FindIt returns a model with the most predictive treatment-treatment interactions or treatment-covariate interactions.

FindIt(
  model.treat,
  model.main,
  model.int,
  data = NULL,
  type = "binary",
  treat.type = "multiple",
  nway,
  search.lambdas = TRUE,
  lambdas = NULL,
  make.twoway = TRUE,
  make.allway = TRUE,
  wts = 1,
  scale.c = 1,
  scale.int = 1,
  fit.glmnet = TRUE,
  make.reference = TRUE,
  reference.main = NULL,
  threshold = 0.999999
)

`model.treat`	A formula that specifies outcome and treatment variables.
`model.main`	An optional formula that specifies pre-treatment covariates to be adjusted.
`model.int`	A formula specifying pre-treatment covariates to be interacted with treatment assignments when `treat.type="single"`.
`data`	An optional data frame, list or environment (or object coercible by 'as.data.frame' to a data frame) containing the variables in the model. If not found in 'data', the variables are taken from 'environment(formula)', typically the environment from which 'FindIt' is called.
`type`	"binary" for a binary outcome variable, which needs to be `integer` class; "continuous" for a continuous outcome variable.
`treat.type`	"single" for interactions between a single treatment variable, which needs to be `integer` class, and multiple pre-treatment covariates specified with `model.int`; "multiple" is used when treatment-treatment interactions are of interest and `treat` is a matrix of multiple treatments.
`nway`	An argument passed to `makeallway` when `treat.type="multiple"`. `FindIt` generates treatment-treatment interactions up to the order specified with this argument. In general, it is recommended to use the number of factorial treatments. The current version covers up to four way interactions.
`search.lambdas`	Whether to search for the tuning parameters for the LASSO constraints. If `FALSE`, `lambdas` must be supplied.
`lambdas`	Tuning parameters to be given to `FindIt`; only used if `search.lambdas=FALSE`.
`make.twoway`	If `make.twoway=TRUE`, all possible two-way interactions for the pre-treatment covariates specified in `model.main` and `model.int` are generated within `FindIt`. The default is set to be `TRUE`.
`make.allway`	If `make.allway=TRUE`, all possible treatment-treatment interactions for multiple treatments are generated when `treat.type="multiple"`. Interactions of the order up to the value of `nway` is computed.
`wts`	An optional set of scaling weights. The default is 1.
`scale.c`	A set of weights for recaling the pre-treatment covariates; only used if `make.twoway=FALSE`. `maketwoway` is useful for generating these.
`scale.int`	A set of weights for recaling the covariates to be interacted with treatment variables ; only used if `make.twoway=FALSE`. `maketwoway` is useful for generating these.
`fit.glmnet`	Whether to fit using the coordinate descent method in glmnet (TRUE) or the regularization path method of LARS (FALSE).
`make.reference`	Whether to make a reference matrix to check which columns are dropped when `makeallway=TRUE`.
`reference.main`	If `make.allway=FALSE` and researchers generate a matrix of all possible interactions between factorial treatments, `reference` from `makeallway` function is better to be passed to `FindIt` through this argument.
`threshold`	An argument passed to `makeallway` when `treat.type="multiple"`. Threshold to drop correlated columns when `makeallway` is used.

Implements the alternating line search algorithm for estimating the tuning parameters, as described in Imai and Ratkovic (2013).

`coefs`	A named vector of scaled coefficients
`coefs.orig`	A vector of coefficients on the original scale, if scale.c and scale.t was used
`fit`	Fitted values on an SVM scale
`names.out`	Names of the coefficients
`y`	A vector of observed outcomes
`X.c`	A matrix of pre-treatment covariates to be adjusted
`X.t`	A matrix of treatments and treatment-treatment interactions, or treatment-covariate interactions
`GCV`	GCV statistic at the minimum
`ATE`	When `treat.type="single"`, the estimated ATE. When `treat.type="multiple"`, the estimated treatment effect of each unique treatment combination
`lambdas`	Tuning parameters used for the fit
`reference`	When `treat.type="multiple"`, after making all interaction terms, columns with no variation or columns perfectly correlated with one of other columns are automatically dropped. `reference` shows which columns are kept and dropped.

Naoki Egami, Marc Ratkovic and Kosuke Imai.

Imai, Kosuke and Marc Ratkovic. 2013. “Estimating Treatment Effect Heterogeneity in Randomized Program Evaluation.” Annals of Applied Statistics, Vol.7, No.1(March), pp. 443-470. http://imai.fas.harvard.edu/research/files/svm.pdf

Egami, Naoki and Kosuke Imai. 2019. Causal Interaction in Factorial Experiments: Application to Conjoint Analysis, Journal of the American Statistical Association. http://imai.fas.harvard.edu/research/files/int.pdf

################################################### 
## Example 1: Treatment-Covariate Interaction
################################################### 
data(LaLonde)

## The model includes a treatment variable, 
## nine covariates to be interacted with the treatment variable,
## and the same nine covariates to be adjusted.

## Not run: 

## Run to find the LASSO parameters
F1  <-FindIt(model.treat= outcome ~ treat,
             model.main= ~ age+educ+black+hisp+white+
             marr+nodegr+log.re75+u75,
             model.int= ~ age+educ+black+hisp+white+
             marr+nodegr+log.re75+u75,
             data = LaLonde,  
             type="binary",
             treat.type="single") 

## End(Not run)

## Fit with uncovered lambda parameters.
F1  <-FindIt(model.treat= outcome ~ treat,
             model.main= ~ age+educ+black+hisp+white+
             marr+nodegr+log.re75+u75,
             model.int= ~ age+educ+black+hisp+white+
             marr+nodegr+log.re75+u75,
             data = LaLonde, 
             type="binary",
             treat.type="single",
             search.lambdas=FALSE,
             lambdas = c(-3.8760,-4.0025) )

summary(F1)

## Returns all the estimated treatment effects. 
pred1 <- predict(F1)
## Top10
head(pred1$data, n=10)
## Bottom 10
tail(pred1$data ,n=10)

## Visualize all the estimated treatment effects.
## Not run: 
plot(pred1)

## End(Not run)

################################################### 
## Example 2: Treatment-Treatment Interaction
################################################### 

## Not run: 
data(GerberGreen)

## The model includes four factorial treatments and 
## all two, three, four-way interactions between them.
## Four pre-treatment covariates are adjusted.

## Run to search for lambdas.
F2<- FindIt(model.treat= voted98 ~ persngrp+phnscrpt+mailings+appeal,
             nway=4,
             model.main= ~ age+majorpty+vote96.1+vote96.0,
             data = GerberGreen,
             type="binary",
             treat.type="multiple")

## Fit, given selected lambdas.
F2<- FindIt(model.treat= voted98 ~ persngrp+phnscrpt+mailings+appeal,
             nway=4,
             model.main= ~ age+majorpty+vote96.1+vote96.0,
             data = GerberGreen,
             type="binary",
             treat.type="multiple",
             search.lambdas=FALSE,
             lambdas=c(-15.000,-6.237))

## Returns coefficient estimates.
summary(F2)

## Returns predicted values for unique treatment combinations.
pred2 <- predict(F2,unique=TRUE)
## Top 10
head(pred2$data, n=10)
## Bottom 10
tail(pred2$data, n=10)

## Visualize predicted values for each treatment combination.
plot(pred2)

## End(Not run)