README.Rmd

---
output: github_document
bibliography: inst/references.bib 
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# R/`unihtee`

> Univariate Heterogeneous Treatment Effect Estimation

__Author:__ [Philippe Boileau](https://pboileau.ca/)

<!-- badges: start -->
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
<!-- badges: end -->

---

`unihtee` provides tools for uncovering treatment effect modifiers in
high-dimensional data. Treatment effect modification is defined using variable
importance parameters based on absolute and relative effects. Inference is
performed about these variable importance measures using nonparametric
estimators. Users may use one-step or targeted maximum likelihood estimators.
Under general conditions, these estimators are unbiased and efficient.

Additional details about this methodology is provided in @boileau2022
and in the package's
[vignette](https://insightsengineering.github.io/unihtee/main/articles/using-unihtee.html).

## Installation

The package may be installed from GitHub using
[`remotes`](https://CRAN.R-project.org/package=remotes):

```{r gh-master-installation, eval=FALSE}
remotes::install_github("insightsengineering/unihtee")
```

`unihtee` is under active development. Check back often for updates.

## Usage

`unihtee()` is the only user-facing function. It can be used to perform
inference about the treatment effect modification variable importance
parameters. These parameters are defined for data-generating processes with
continuous, binary and time-to-event outcomes with binary exposure variables.
Variable importance parameters based on absolute and relative effects are
available. Details are provided in the vignette.

## Example

We simulate some observational study data that contains ten pre-treatment
covariates, of which are two treatment effect modifiers. We then perform
inference about the absolute treatment effect modifier variable importance
parameter, which is inspired by the average treatment effect.

```{r example}
library(unihtee)
library(MASS)
library(data.table)
library(sl3)

set.seed(510)

## create the dataset
n_obs <- 500
w <- mvrnorm(n = n_obs, mu = rep(0, 10), Sigma = diag(10))
confounder_names <- paste0("w_", seq_len(10))
colnames(w) <- confounder_names
a <- rbinom(n = n_obs, size = 1, prob = plogis(w[, 1] + w[, 2]))
y <- rnorm(n = n_obs, mean = w[, 1] + w[, 2] + a * w[, 3] - a * w[, 4])
dt <- as.data.table(cbind(w, a, y))

## targeted maximum likelihood estimates and testing procedure
unihtee(
  data = dt,
  confounders = confounder_names,
  modifiers = confounder_names,
  exposure = "a",
  outcome = "y",
  outcome_type = "continuous",
  effect = "absolute",
  estimator = "tmle"
)
```

## Issues

If you encounter any bugs or have any specific feature requests, please [file
an issue](https://github.com/insightsengineering/unihtee/issues).

## Contributions

Contributions are very welcome. Interested contributors should consult our
[contribution
guidelines](https://github.com/insightsengineering/unihtee/blob/master/.github/CONTRIBUTING.md)
prior to submitting a pull request.

## Citation

To cite `unihtee` and the papers introducing the underlying framework, use the
following BibTeX entries:

```
@manual{unihtee,
  title = {unihtee: Univariate Heterogeneous Treatment Effect Estimation},
  author = {Philippe Boileau},
  note = {R package version 0.0.1}
}

@misc{boileau2023,
      title={A nonparametric framework for treatment effect modifier discovery in high dimensions}, 
      author={Philippe Boileau and Ning Leng and Nima S. Hejazi and Mark van der Laan and Sandrine Dudoit},
      year={2023},
      eprint={2304.05323},
      archivePrefix={arXiv},
      primaryClass={stat.ME}
}

@article{boileau2022,
    author = {Boileau, Philippe and Qi, Nina Ting and van der Laan, Mark J and Dudoit, Sandrine and Leng, Ning},
    title = {A flexible approach for predictive biomarker discovery},
    journal = {Biostatistics},
    year = {2022},
    month = {07},
    issn = {1465-4644},
    doi = {10.1093/biostatistics/kxac029},
    url = {https://doi.org/10.1093/biostatistics/kxac029}
}
```

## License

The contents of this repository are distributed under the Apache 2.0 license.
See the
[`LICENSE.md`](https://github.com/insightsengineering/unihtee/blob/main/LICENSE.md)
and
[`LICENSE`](https://github.com/insightsengineering/unihtee/blob/main/LICENSE)
files for details.

## References