---
title: "DAGassist in 10 minutes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{quick-tour}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# What you'll learn
- How to go from a `dagitty` DAG + formula to a compact report
- How to interpret the report, and what the variable categories and comparison models mean
-	How to export to `LaTeX` / `Word` / `Excel` / `text`

## Load packages

```{r setup}
library(DAGassist)
# load helper libraries
library(modelsummary)
library(dagitty)
```

## Make your DAG and data

```{r sample}
n <- 500
Z <- rnorm(n)
A <- rnorm(n)
X <- 0.6*Z + rnorm(n)
M <- 0.5*X + 0.3*Z + rnorm(n)
Y <- 1.0*X + 0.0*M + 0.5*Z + rnorm(n)
df <- data.frame(Y, X, M, Z, A)

dag_model <- dagitty('
  dag {
    Z -> X
    Z -> Y
    A -> Y
    X -> M
    X -> Y
    M -> Y
    X [exposure]
    Y [outcome]
  }')
```

## Generate a console report with `DAGassist`

See the [Getting Started](https://grahamgoff.github.io/DAGassist/articles/get-started.html) vignette for a guide on using different parameters get the most out of DAGassist. For the purpose of this tutorial, we will keep it simple. 

See the [Supported Models](https://grahamgoff.github.io/DAGassist/articles/compatability.html) vignette for documentation on what engines `DAGassist` supports. Since `DAGassist` is model-agnostic, if an engine accepts a standard `formula + data` interface, it will usually work. 

**Interpreting the output:**

- **ROLES:** `DAGassist` classifies the variables in your formula by causal role, based on the relationships in your DAG. It classifies according to these categories.
  - **X** is the `treatment` / `independent variable` / `exposure`.
  - **Y** is the `outcome` / `dependent variable`.
  - **conf** stands for `confounder`, a common cause of X and Y. Confounders create a spurious association between X and Y, and must be adjusted for. 
  - **med** stands for `mediator`, a variable that lies on a path from X to Y, which transmit some of the effect from X to Y. One should not adjust for mediators if one wants to estimate the total effect of X on Y. 
  - **col** stands for `collider`, a direct common descendant of X and Y. Colliders already block paths, so adjusting for it opens a spurious association between X and Y. 
  - **IO** stands for `intermediate outcome`, a descendant of Y, which introduces bias if adjusted for.
  - **dMed / Dmediator** stands for `descendant of a mediator`, which should not be adjusted for when estimating total effect.
  - **dCol / Dcollider** stands for `descendant of a collider`. Adjusting for a descendant of a collider opens a spurious association between X and Y.
  - **other** variables, such as those that only affect the outcome, do not fit any of the previous definitions. They are included in the canonical model because they can be safely included as controls, but are omitted from the minimal model because their inclusion is not strictly necessary. Since `other` variables' effects are generally neutral, it is usually best to use the minimal adjustment set as your baseline model. 

- **MODEL COMPARISON:** 
- `Minimal` is the smallest adjustment set necessary to close all back-door paths from the independent to the dependent variable. The minimal set only includes `confounders` as controls.
- `Canonical` is the largest permissible adjustment set. Essentially, the `canonical` set contains all control variables that are not `confounders`, `mediators`, `intermediate outcomes`, `descendants of mediatiors`, or `descendants of colliders`. 

```{r console-report}

DAGassist(
  dag = dag_model,
  formula = lm(Y ~ X + M + Z + A, data = df)
)
```


## Exporting

See the [Making Reports](https://grahamgoff.github.io/DAGassist/articles/making-reports.html) vignette for more detailed information on producing publication-quality `DAGassist` reports in `LaTex`, `Word`, `Excel`, and `plaintext`.

Since `DAGassist` is designed to make appendix robustness checks, this is an example of how to output a report in `LaTeX`.

```{r report}
#initialize a temporary path
out_tex <- file.path(tempdir(), "dagassist_report.tex")

DAGassist(
  dag = dag_model,
  formula = lm(Y ~ X + M + Z + A, data = df),
  type = "latex", 
  out = out_tex) #put your output directory and file name here

cat(readLines(out_tex, n = 15), sep = "\n") # briefly show the output
```