A Basic DAG

The usual syntax for specifying a DAG in the dagitty R-package is something like:

library(dagitty)
dagitty("dag {
  X -> Y
  Z -> X
  Z -> Y
}")

There are several tags that can be used in dagitty. Note that quotation marks used in tags must be double quotes ", so it makes sense to wrap the whole DAG syntax in single quotes ':

library(dagitty)
dagitty('dag {
  X [exposure, pos="0,1"]
  Y [outcome, pos="1,1"]
  Z [unobserved, pos="1,0"]
  X -> Y
  Z -> X
  Z -> Y
}')

Augmented DAGs (aDAGs)

In our augmented specification, we add additional properties as metadata fields.

Below, we detail each new property:

library(tidySEM)
g <- dagitty('dag {
  X [label="Predictor", pos="0,0"]
  Y [label="Outcome", pos="1,0"]
  X -> Y [label="effect"]
}')
graph_sem(g, text_size = 2)

2. distribution (Nodes)

• Usage: References a function that generates data for exogenous variables, or that describes the residual distribution for endogenous variables. The function can reference the argument n to determine sample size. For example, to specify a node comprising five groups with total sample size n, one could use sample.int(n = 5, size = n, replace=TRUE). If the argument n is not explicitly provided, theorytools checks if n is a formal argument of the function, and assigns it.

• Examples:

  • X [distribution="rnorm()"]: Node X is an exogenous variable drawn from a normal distribution with default arguments.
  • Y [distribution="rnorm()"]: Node Y has residuals assumed to be normally distributed with default arguments.

g <- dagitty('dag {
  X [distribution="rbinom(size = 2, prob = .5)"]
  Y [distribution="rnorm()"]
  X -> Y [form=".2*X"]
}')

3. form (Edges)

• Usage: Provides a formula-like specification for how a child node depends on its parent node(s). It should be something that as.formula() can parse.

• Examples:

• X -> Y [form=".2*X"] indicates that Y is a linear function of .2 times X

• X -> Y [form="X:Z"] indicates that Y depends on an interaction between X and Z

• X -> Y [form="X^2"] indicates that Y depends on a quadratic function of X

g <- dagitty('dag {
  X [distribution="rbinom(size = 2, prob = .5)"]
  Y [distribution="rnorm()"]
  X -> Y [form=".2*X"]
}')

Example: Augmented DAG Specification

Below is a simple, hypothetical DAG showing how to combine these ideas. This DAG posits:

• X: Number of study hours, an exposure. Values are randomly sampled from 1-20 hours.
• Z: Stress level, an exogenous covariate, exponentially distributed (i.e., right-skewed, most people are not very stressed).
• Y: Exam performance an outcome depending on X and Z, with normally distributed residuals.s

g <- dagitty('dag {
  X [exposure,
     pos="0,0",
     label="Study Hours",
     distribution="sample.int(n = 20, size = n, replace = TRUE)"]
  Z [label="Stress Level",
     pos=".5,1",
     distribution="rexp()"]
  Y [outcome,
     pos="1,.2",
     label="Exam Performance", distribution="rnorm()"]
  X -> Y [label="direct", form="0.5+X"]
  X -> Z
  Z -> Y [label="indirect", form="2*Z"]
}')
graph_sem(g, text_size = 3)

get_nodes(g)
#>   name exposure   x   y            label
#> 1    X     TRUE 0.0 0.0      Study Hours
#> 2    Y       NA 1.0 0.2 Exam Performance
#> 3    Z       NA 0.5 1.0     Stress Level
#>                                   distribution outcome shape
#> 1 sample.int(n = 20, size = n, replace = TRUE)      NA  none
#> 2                                      rnorm()    TRUE  none
#> 3                                       rexp()      NA  none
get_edges(g)
#>   from to  e    label     form arrow  color
#> 1    X  Y ->   direct -X^2+4*X  last gray80
#> 2    X  Z ->     <NA>     <NA>  last gray80
#> 3    Z  Y -> indirect      2*Z  last gray80

Interpreting distribution and form in Simulation

A primary motivation for these augmented properties is simulation. For example, you might simulate data by:

1. Generating X from sample.int(n).
2. Generating Z from rexp(n).
3. Generating Y using a formula that includes X and Z plus a residual from rnorm(n).

Code to simulate data in line with these metadata can be automatically generated:

set.seed(1)
cat(simulate_data(g, run = FALSE), sep = "\n")
#> # Set random seed
#> set.seed(1140350788)
#> # Set simulation parameters
#> n <- 500
#> # Simulate exogenous nodes
#> X <- sample.int(n = 20, size = n, replace = TRUE)
#> # Simulate endogenous nodes
#> Z <- 0.09 * X + rexp(n = n)
#> Y <- 2 * Z + X * (4 - 0.49 * X) + rnorm(n = n)
#> df <- data.frame(
#> X = X,
#> Y = Y,
#> Z = Z
#> )

To illustrate, we show a scatter plot of data simulated using this code:

df <- simulate_data(g, run = TRUE)
ggplot2::ggplot(df, aes(x=X,y=Y,color=Z))+geom_point()

You can use this script, for example, to generate synthetic data and build a reproducible analysis pipeline for a Preregistration-As-Code (Peikert, Van Lissa, and Brandmaier 2021; Van Lissa 2022).