manual-3.x.tex

\documentclass[a4paper]{article} % for Science, Engineering and Humanities and Social Sciences articles
\usepackage[a4paper, margin=1.5cm]{geometry}
\usepackage{url,hyperref,microtype,subcaption}
\usepackage{graphicx,amsmath,pxfonts}
\usepackage[font={small,sf}]{caption}
\renewcommand{\captionlabelfont}{\bfseries}
\usepackage[onehalfspacing]{setspace}
\usepackage{fixltx2e}
\usepackage{xcolor}
\usepackage{xspace}
\hypersetup{
    colorlinks,
    linkcolor=red!70!black, citecolor=blue!80!black
}
\usepackage{doi}
\usepackage[numbers]{natbib}
\usepackage{tikz}
\usepackage{framed}
\usepackage{fancyvrb}
\definecolor{shadecolor}{rgb}{.97, .97, .97}

\newcommand{\pp}{{\sc DAG}itty\xspace}
\newcommand{\action}[1]{\emph{``#1''}}
\setlength{\columnsep}{1cm}

%opening
\title{Drawing and Analyzing Causal DAGs with \pp}
\author{Johannes Textor}
\date{\today}


\makeatletter
\newenvironment{kframe}{%
 \def\at@end@of@kframe{}%
 \ifinner\ifhmode%
  \def\at@end@of@kframe{\end{minipage}}%
  \begin{minipage}{\columnwidth}%
 \fi\fi%
 \def\FrameCommand##1{\hskip\@totalleftmargin \hskip-\fboxsep
 \colorbox{shadecolor}{##1}\hskip-\fboxsep
     % There is no \\@totalrightmargin, so:
     \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
 \MakeFramed {\advance\hsize-\width
   \@totalleftmargin\z@ \linewidth\hsize
   \@setminipage}}%
 {\par\unskip\endMakeFramed%
 \at@end@of@kframe}
\makeatother


\DefineVerbatimEnvironment% 
	{dagcode}{Verbatim} {frame=lines,framerule=0.1mm,fontsize=\small}

% \usepackage{natbib}



\newcommand{\typesetbiblink}[1]{#1}

\bibliographystyle{plain}

\begin{document}

\twocolumn[{%
  \begin{@twocolumnfalse}
    \maketitle
    \begin{quote}
\pp is a software for drawing and analyzing causal diagrams, also known as directed acyclic graphs (DAGs). Functions include identification of minimal sufficient adjustment sets for estimating causal effects, diagnosis of insufficient or invalid adjustment via the identification of biasing paths, identification of instrumental variables, and derivation of testable implications.

\pp is provided in the hope that it is useful for researchers and students in Epidemiology, Sociology, Psychology, and other empirical disciplines. The software should run in any modern web browser that supports JavaScript, HTML, and SVG.

This is the user manual for \pp version 3.0. The manual is updated with every release of
a new stable version. \pp is available at \href{http://dagitty.net}{dagitty.net}. An R package ‘dagitty’ implementing the same functionality is also available on CRAN and at 
\href{https://github.com/jtextor/dagitty}{github.com/jtextor/dagitty}.
\vspace{20pt}
    \end{quote}
  \end{@twocolumnfalse}
}]

\tableofcontents

\section{Introduction}

\pp is a web-based software for analyzing causal diagrams. It contains some of the 
fastest algorithms available for this purpose. 

This manual describes how causal diagrams can be created
(Section~\ref{sec:diagramcreation}) 
and manipulated (Section~\ref{sec:diagramediting}) using \pp. In 
Section~\ref{sec:diagramanalysis}, \pp's capabilities to analyze causal diagrams are
described. A brief introduction to causal diagrams is given
in Section~\ref{sec:dagintro}. Advanced users might also be interested in the R package ‘dagitty’ \cite{textor_robust_2016}, which implements all functionality of the web-based software and more.


\subsection{Citing \pp}

Developing and maintaining \pp takes time and effort.
If you publish research results obtained
with the help of \pp, please 
consider giving us credit by citing our work. 
The main reference
for \pp is our paper describing the accompanying R package \cite{textor_robust_2016}, 
which is based on the same software library, and therefore also serves as a reference for the web-based program.
 We have also published several research papers describing the specific algorithms used in DAGitty, such as for identification of biasing paths \cite{TextorL2011}, adjustment sets \cite{textor14_uai}, and instrumental variables
\cite{zander15_instrument}.




\subsection{Running \pp online}

There are two ways to run \pp: either from the internet or from your
own computer. To run \pp online, visit the URL
\href{http://www.dagitty.net}{\tt dagitty.net}.
\pp should run in every modern browser. Specifically, I expect it
to work well on recent versions of Firefox, Chrome, Opera, and Safari
as well as on Internet Explorer (IE) version 9.0 or later, which all
support scalable vector graphics (SVG). If you encounter any problems, please send
me an e-mail so I can fix them (my contact information is at the end of this manual). 
Keep in mind that \pp is used by hundreds of people per day from all over the world -- these people all benefit if the problem you found is fixed so please do consider investing the time to notify me if you encounter any bugs.

\subsection{Installing \pp on your own computer} 

\pp can be ``installed'' on your computer for use without an internet
connection. To do this, download the file 
\href{http://www.dagitty.net/dagitty.zip}{\tt dagitty.net/dagitty.zip}
which is a ZIP archive containing \pp's source. Unpack this ZIP file anywhere
in your file system. To run \pp, just open the file \verb|dags.html| in the
unpacked folder. 

Some features of \pp will not work in the offline version, because they
are actually implemented on the web server. Currently, these features are:
\begin{itemize}
\item Exporting model drawings as PDF, JPEG or PNG files.
\item Publishing models on-line.
\end{itemize}

\subsection{Migrating from earlier versions of \pp}

The following two issues are important for users of older \pp versions. New users
can skip this section.

\begin{itemize}
\item The model code syntax has been completely changed in DAGitty version 3.0; the old syntax
	based on the DAG program by Sven Kn\"uppel \cite{KnueppelS2010} was getting too limited to accommodate the new features that were being added. Therefore, I decided to switch to a very different, but much more extensible syntax closely based on the ``dot'' language used by graphviz.
\pp will still be able to open model code from older versions (with one small caveat
for very old code, see below) and will automatically convert this to the new syntax.
\item Early versions of DAGitty supported only one exposure and one outcome variable. It has
now been possible for quite some time to have more than one exposure and/or outcome
variable. This means that the old model code convention where the variable in the first line
is the exposure and the variable in the second line is the outcome no longer works. Hence,
if you open a model created with an earlier version in DAGitty 2.0 or higher,
exposure and outcome will appear like normal variables. To fix this, simply set exposure and outcome again 
and save the new model code.
\end{itemize}

\section{A brief introduction to causal diagrams}

\label{sec:dagintro}

In this section, we will briefly review what causal diagrams are and how they can be 
applied in empirical sciences. For a more detailed account, we recommend 
the book \emph{Causal Inference in Statistics: A Primer} by Pearl, Glymour and Jewell \cite{Pearl2016}, or the chapter \emph{Causal Diagrams} in the Epidemiology 
textbook of Rothman, Greenland, and Lash \cite{RothmanGL2008}. 
Also take a look at the web page \href{http://www.dagitty.net/learn/}{\tt dagitty.net/learn/}, where I am collecting several tutorials (some of them interactive) on specific DAG-related  topics.
 
In Epidemiology, causal diagrams are also frequently
called \emph{DAGs}.\footnote{The term ``DAG'' is
somewhat confusing to computer scientists and mathematicians, 
for whom a DAG is simply an abstract mathematical structure without specific semantics 
attached to it.} In a nutshell, a DAG is a graphic model that depicts a set of hypotheses
about the causal process that generates a set of variables of interest.
An arrow $X \to Y$ is drawn if there is a direct
causal effect of $X$ on $Y$. Intuitively, this means that
the natural process determining $Y$ is directly influenced by
the status of $X$, and that altering $X$ via external intervention 
would also alter $Y$. However, an arrow $X \to Y$ only represents that part
of the causal effect which is \emph{not} mediated by any of the other variables
in the diagram. If one is certain that $X$ does not
have a direct causal influence on $Y$, then the arrow is omitted.
This has two important implications: (1) arrows should follow time order,
 or else the diagram contradicts the basic principle that
causes must precede their effects; (2) the omission of an arrow is a stronger
claim than the inclusion of an arrow -- the presence of an arrow depicts
merely the ``causal null hypothesis'' that $X$ \emph{might} have an effect
on $Y$.

Mathematically, the semantics of an arrow $X \to Y$ can be defined as
follows. Given a DAG $G$ and a variable $Y$ in $G$, let $X_1,\ldots,X_n$
be all variables in $G$ that have direct arrows $X_i \to Y$ (also called the
\emph{parents} of $Y$). Then $G$ 
claims that the causal process determining the value of $Y$ can be
modelled as a mathematical function $Y := f(X_1,\ldots,X_n,\epsilon_Y)$,
where $\epsilon_Y$ (the ``causal residual'') is a random variable that
is jointly independent of all $X_i$.  

For example, the sentence ``smoking causes lung cancer'' could be translated
into the following simple causal diagram: 

\begin{center}
\begin{tikzpicture}
\node (sm) {smoking};
\node (c) [below of=sm] {lung cancer};

\draw [->] (sm) -- (c);
\end{tikzpicture}
\end{center}

We would interpret this diagram as
follows: (1) The variable ``smoking'' refers to a person's smoking habit
prior to a later cancer disease status in that same person;
(2) the natural process by which a person develops
cancer might be influenced by the smoking habits of that person; (3) there
exist no other variables that have a direct influence on both smoking 
habits and cancer. A slightly more complex version of this diagram might look as follows:

\begin{center}
\begin{tikzpicture}
\node (sm) {smoking};
\node [below of=sm] (t) {tar deposit in lungs};
\node (c) [below of=t] {lung cancer};

\draw [->] (sm) -- (t);
\draw [->] (t) -- (c);
\end{tikzpicture}
\end{center}

This diagram is about a person's smoking habits at a time $t_1$,
the tar deposit in her lungs at a later time $t_2$, and finally the
development of lung cancer at an even later time $t_3$. We claim that 
(1) the natural process which determines the amount of tar in the
lungs is affected by smoking; 
(2) the natural process by which lung cancer develops is affected by
the amount of tar in the lung; (3) the natural 
process by which lung cancer develops is not affected by the person's
smoking other than indirectly via the tar deposit; 
and finally (4) no variables having
relevant direct influence on more than one variable
of the diagram were omitted.

In an epidemiological context, we are often interested in the putative 
effect of a set of variables, called \emph{exposures}, on another set of variables
called \emph{outcomes}. A key question in Epidemiology (and many other empirical sciences)
is: how can we infer the causal effect of an exposure on an outcome of interest from
an observational study? Typically, a simple regression will not suffice due to the 
presence of \emph{confounding factors}, which may lead to an over- or underestimation
of the causal effect from the observed data. If the assumptions encoded in a given 
diagram hold, then it is sometimes possible to devise an \emph{identification strategy}
from that diagram, by which it would be possible to devise an unbiased estimate 
of a causal effect from observed data. One example identification strategy would
be \emph{covariate adjustment}. For example,
consider the following diagram: 

% \begin{figure}[h!]
\begin{center}
\begin{tikzpicture}
\node (sm) at (0,0)  {smoking};
\node [anchor=east] (m) at (-1,-1) {carry matches};
\node [anchor=west] (c) at (1,-1) {cancer};
\draw [->,very thick] (sm) -- (c);
\draw [->,very thick] (sm) -- (m);
\draw [->] (m) -- node[midway,above] {?} (c);
\end{tikzpicture}
\end{center}
% \caption{A classical confounding triangle.}
% \label{fig:dag2}
% \end{figure}

If we were to perform an association 
study on the relationship between carrying matches
in one's pocket and developing lung cancer, we would probably find a 
correlation between these two variables. However, as the above diagram
indicates, this correlation would not imply that carrying matches in 
your pocket causes lung cancer: Smokers are more likely to carry matches
in their pockets, and also more likely to develop lung cancer. This is an
example of a \emph{confounded} association between two variables,
which is mediated via the \emph{biasing path} (bold). 
Now let us assume (unrealistically, and solely for didactic purposes) 
that the simplistic diagram above is an accurate representation of the
process that generated our data. Under this assumption, would we adjust for smoking, 
e.g. by weighted averaging of separate effect estimates for 
smokers and non-smokers or by including smoking status as a covariate
in a regression model, we would  
no longer find a correlation between carrying matches and lung cancer.
In other words, adjustment for smoking would \emph{close the biasing path}.
In general, any set of covariates that closes all biasing paths (and does
not open new ones or closes causal paths in the process) is called an 
\emph{adjustment sets}.  Adjustment sets will be explained in more detail in 
Section~\ref{sec:adjustment}.

The purpose of \pp is to aid study design through devising identification
strategies in (possibly complex) causal diagrams and,
more generally, through the identification of causal and biasing paths as
well as testable implications in a given diagram. 

\section{Loading, saving  and sharing diagrams}

\label{sec:diagramcreation}

This section covers the three basic steps of working with \pp: 
(1) loading a diagram; (2) manipulating the graphical layout of the diagram; and
(3) saving the diagram. 
% The first step for working with \pp is to create a causal network.
First of all, any causal diagram consists of vertices (variables) and arrows 
(direct causal effects).
You can either create the diagram directly using \pp's graphical user
interface (explained in the next section),
or prepare a textual diagram description in a word processor 
and then import this
description into \pp. In addition, \pp
contains some pre-defined examples that you can use to become familiar
with the program and with DAGs in general. 
To do so, just select one of the pre-defined examples from
the \action{Examples} menu.

\subsection{\pp's textual syntax for causal diagrams} 

The textual syntax in DAGitty is based on the ‘dot’ language by graphviz. In fact, many dot graphs should work directly in dagitty without modifications, although most of the style attributes of the dot language are not supported by dagitty.
I believe it is best to introduce the syntax by a series of examples. Let us start by defining the example used in the introduction above.

\begin{dagcode}
dag{ 
  smoking
  "carry matches" [exposure]
  cancer [outcome]
  smoking -> "carry matches"
  smoking -> cancer
  "carry matches" -> cancer
}
\end{dagcode}

This example shows the three basic components of the syntax in action:
\begin{itemize}
\item The enclosing statement \verb'dag{ ... }', which is always there. The DAG can also be given a name like so: \verb'dag Smoking { ... }'

\item The variable (vertex) statements. These consist of a variable name and a list of options enclosed in square brackets. For instance, the options ``exposure'' and ``outcome'' set a variable to be an exposure or outcome, respectively. Other relevant options are ``latent'' (for unobserved variables) and ``adjusted'' (for variables that have been adjusted for in a statistical analysis). It is necessary to double-quote the variable names if they contain spaces or other special characters, like for the variable ``carry matches''.

\item The edge statements. These consist of a source variable, and edge type (which can be  \verb|->|, \verb|<-|, or \verb|<->|), and a target variable. Double-headed edges (\verb|x<->y|) are simply an equivalent shortand for typing \verb|x<-u->y; u[latent]|. Importantly, this means that double-headed edges are \emph{not} meant to represent reciprocal causation (which is impossible to represent in a DAG). Instead, they are commonly used to depict unknown or unobserved confounders without specifying explicitly what those confounders are. 
\end{itemize}

These three syntax components are in fact enough to define any DAG. We are now going to define the same DAG in various different ways to showcase various convenient features of the syntax that make DAG definitions more compact; it is not necessary to use any of these features, but they can save a lot of typing.

Variable statements can be omitted if the variable has no options, such as ``smoking'' in the above example. Every time a variable is used in an edge statement, that variable is automatically added as if there had been a corresponding node statement without an option.

\begin{dagcode}
dag{ 
  "carry matches" [exposure]
  cancer [outcome]
  smoking -> "carry matches"
  smoking -> cancer
  "carry matches" -> cancer
}
\end{dagcode}


White-space is optional and several statements can be combined on one line. For clarity, it is recommended to insert semi-colons between different statements on the same line; however, this is not necessary. The following two versions are equivalent:

\begin{dagcode}
dag{ 
  "carry matches" [exposure]; cancer [outcome]
  smoking -> "carry matches"; smoking -> cancer;
  "carry matches" -> cancer
}
\end{dagcode}

\begin{dagcode}
dag{ 
  "carry matches" [exposure] cancer [outcome]
  smoking -> "carry matches" smoking -> cancer
  "carry matches" -> cancer
}
\end{dagcode}


Edge statements can be chained together such that entire paths can be defined at once:

\begin{dagcode}
dag{ 
  "carry matches" [exposure] ; cancer [outcome]
  smoking -> "carry matches" -> cancer 
  smoking -> cancer
}
\end{dagcode}

Arrows can also be written in reverse orientation, which is quite convenient when used together with edge chaining:

\begin{dagcode}
dag{ 
  "carry matches" [exposure] ; cancer [outcome]
  cancer <- smoking -> "carry matches" -> cancer 
}
\end{dagcode}

Another very useful feature for short DAG descriptions is variable grouping using curly braces. This allows you to define several arrows at once like so:
\begin{dagcode}
dag{
  "carry matches" [exposure] ; cancer [outcome]
  smoking -> {"carry matches" cancer}
   "carry matches" -> cancer
}
\end{dagcode}

The curly braces open a new scope in which a ``sub-graph'' is defined. An arrow pointing to a sub-graph means that there will be arrows made to all variables in the sub-graph, and the sub-graph itself can also define its own internal arrows. This means that we can also write the above as:
\begin{dagcode}
dag{
  "carry matches" [exposure] ; cancer [outcome]
  smoking -> {"carry matches" -> cancer}
}
\end{dagcode}

To save even more typing, several option names can be abbreviated using single letters like so:
\begin{dagcode}
dag{
  "carry matches" [e] ; cancer [o]
  smoking -> {"carry matches" -> cancer}
}
\end{dagcode}

Like mentioned above, it is not necessary to use grouping or edge statement chaining; the only purpose of these tricks is to save some typing. In fact, once your textual syntax is entered in \pp, it will be converted back to a trivial form in which the variable and edge statements are all explicitly listed. (This is similar to what would happen in graphviz.)

The above examples covered only the structure of the DAG, but gave no layout information. A simple layout is automatically generated by \pp once you input a text description where \pp cannot detect any layout coordinates. The coordinates are also updated when you move nodes around or bend edges. See Figure~\ref{fig:syntax} for how the layout information is added to the variable statements. You could of course enter your own layout information manually into the text syntax as well.
\begin{figure}
\begin{tikzpicture}
(a)
\node [text width=2cm,align=center,anchor=north west] at (0,5) {
(a)
\begin{dagcode}
dag{
E -> D
A -> E
A -> Z
B -> Z
B -> D
Z -> E
Z -> D
}
\end{dagcode}
};
\node [text width=2cm,align=center,anchor=north west] at (3,5) {
(b)
\begin{dagcode}
dag{
A -> {Z E}
B -> {Z D}
Z -> {E D}
E -> D
}
\end{dagcode}
};
\node [text width=2cm,align=center,anchor=north west] at (6,5) {
(c)
\begin{dagcode}
dag{
A -> {Z -> E}
B -> {Z -> D}
E -> D
}
\end{dagcode}
};
\node [text width=4cm,align=center,anchor=north west] at (0,0) {
(d)
\begin{dagcode}
dag {
A [pos="0,-2"]
B [pos="2,-2"]
D [outcome,pos="2,0"]
E [exposure,pos="0,0"]
Z [pos="1,-1"]
A -> { E Z }
B -> { D Z }
E -> D
Z -> { D E }
}
\end{dagcode}
};

\node [text width=4cm,align=center,anchor=north west] at (4.5,0) {
(e)
};


\begin{scope}[xshift=5.5cm,yshift=-3.6cm,scale=1.2]
\node (a) at (0,2) {A};
\node (b) at (2,2) {B};
\node (z) at (1,1) {Z};
\node (e) at (0,0) {E};
\node (d) at (2,0) {D};

\draw [->] (a) -- (e);
\draw [->] (a) -- (z);
\draw [->] (b) -- (z);
\draw [->] (b) -- (d);
\draw [->] (z) -- (e);
\draw [->] (z) -- (d);
\draw [->] (e) -- (d);
\end{scope}

\end{tikzpicture}
\caption{
Example for a textual model definition with \pp using {\bfseries (a)} simple model code; 
{\bfseries (b)} shorter model codel
and {\bfseries (c)} very short model code of the graph in (a) using 
 grouping operations. {\bfseries (d)} When the diagram is edited within \pp, vertex labels 
and adjustment status are augmented with additional layout coordinates
for each variable, which are indicated as an option of the corresponding node.
{\bfseries (e)} Graphical layout corresponding to (d).
}
\label{fig:syntax}
\end{figure}

\subsection{Loading a model text}

To load a textually defined diagram into \pp, simply copy\&paste the 
variable list, followed by a blank line,
followed by the list of arrows into the \action{Model code} text
box. Then click on \action{Update DAG}.
\pp will now generate a preliminary graphical layout for your diagram on 
the canvas, which may not yet look the way you intended, but can be freely 
modified.

\subsection{Modifying the graphical layout of a diagram}

To layout the vertices and arrows of your diagram more clearly than \pp
did, simply drag the vertices with your mouse on the canvas. You may notice
that \pp modifies the information in the \action{Model code} field
on the fly, and augments it with additional position information for each
vertex. In general, all changes you make to your diagram within \pp 
are immediately reflected in the model code. 

\subsection{Saving the diagram} 

To save your diagram locally, just copy\&paste the contents of the \action{Model code}
field to a text file, 
and save that file locally to your computer\footnote{This is most easily done
by clicking in the text field, pressing \action{CTRL + A} to select the entire content
of the text field, then pressing \action{CTRL + C} to copy the content. You
can then paste the content in another program using \action{CTRL + V}.}.
When you wish to continue working on the
diagram, copy the model code back into \pp as explained above. 

\subsection{Exporting the diagram}

\pp can export the diagram as a PDF or SVG vector graphic (publication quality)
or a JPEG or PNG bitmap graphic (e.g. for inclusion in Powerpoint). Select the
corresponding function from the \action{Model} menu. If you want to edit the graphical
layout of the diagram or annotate it, it is recommended to export the diagram as an
SVG file and open that in a vector graphics program such as Inkscape.

\subsection{Publishing diagrams online}

Part of the appeal of using DAGs is that the assumptions underlying
one's research are made explicit, and the conclusions drawn from 
the data can be later re-checked if some of the assumptions are found
to not hold. Of course, this requires to make the DAG available together
with the data and interpretation. I have however seen many articles
where people report having used DAGs but do not actually show them.
If researchers, reviewers or editors deem it inappropriate to include the 
DAG (or its model code) in the manuscript itself, here's another option:
Store the DAG on the \pp website and get a short URL under which
this DAG will be accessible. Then include this URL in the manuscript,
or its supporting information. For example, one of the \pp examples
is stored at the URL \href{http://dagitty.net/mvcFQ}{\tt dagitty.net/mvcFQ}.

Here's how it works: Draw your DAG to full satisfaction, then choose 
\action{Publish on dagitty.net} from the \action{Model} menu. You have
two options how to publish your DAG: anonymously, or linking it to an e-mail
address. If you store the DAG anonymously, you will later on not be able
to edit it or delete it from the server.

After choosing \action{Publish on dagitty.net} from the \action{Model} menu,
a small form will appear where you can enter some metadata on the DAG,
and provide your e-mail address if you so wish. Upon clicking \action{Publish},
the DAG will be sent to the dagitty.net server, and you will receive a URL under
which the DAG is now available. If you provided your e-mail address, you
will also receive a message requesting you to confirm your ownership of the DAG.
This is simply done by clicking on a confirmation link. Only then will the DAG
be linked to your e-mail address, and you will receive a password to use when
deleting or modifying the published DAG.

If you did link your DAG to your e-mail address, you can delete it by choosing
\action{Delete on dagitty.net} from the \action{Model} menu, which will prompt you
to enter the DAG's URL and the password. If the URL and password match,
the DAG will be deleted.
Similarly, you can update a stored DAG using the \action{Load from dagitty.net} function
from the  \action{Model} menu, modifying it, and saving it again. 
You can view published DAGs (if you know their URL)
by just putting the URL into your address bar of course, but you can also do
so using the \action{Load from dagitty.net} function. 

Please note that all DAGs stored on dagitty.net are meant to be public information.
Do not store any data that you consider private or in any way secret.
Once stored on dagitty.net, every person in the world who knows your DAG's URL
can view it (but not your e-mail address if you provided one). Also note that there is
no guarantee that dagitty.net will keep running forever. Storing your DAGs is done at
your own risk. Still, you may find this feature useful, for instance to e-mail your DAGs
to colleagues or to include links to DAGs in papers under review. For archival
purposes, it may be more appropriate to include the DAG or the model code in
the paper itself or its supporting information.

\section{Editing diagrams using the graphical user interface} 

\label{sec:diagramediting}

You are free to make changes directly to the textual description of your
diagram, which will be reflected on the canvas next time you click on \action{Update DAG}.
However, you can also create, modify, and delete vertices and arrows graphically
using the mouse.

\subsection{Creating a new diagram}

To create a new diagram, select \action{New Model} from the \action{Model} menu.
You will be asked
for the names of the exposure and the outcome variable, and an initial model containing
just those variables and an arrow between them will be drawn. Then you can
add variables and arrows to the model as explained below. 

\subsection{Adding new variables}

To add a new variable to the model, double-click on a free space in the canvas
(i.e., not on an existing variable) or press the \action{n} key. A dialog will
pop up asking you for the name of the new variable. Enter the name into the dialog
and press the enter key or click \action{OK}. If you click \action{Cancel}, no new 
variable will be created.

\subsection{Renaming variables}

To rename an existing variable, move the
mouse pointer over that variable and hit the \action{r} key. A dialog
will pop up allowing you to change the variable name.

\subsection{Setting the status of a variable}

Variables can have one of the following 
statuses:

\begin{itemize} 
\item Exposure
\item Outcome
\item Unobserved (latent)
\item Adjusted
\item Other
\end{itemize}


To turn a variable into an exposure, move the
mouse pointer over that variable and hit the \action{e} key; 
for an outcome, hit the \action{o} key instead.
To toggle whether a variable is observed or unobserved,
hit the \action{u} key; to toggle whether it is 
adjusted, hit the \action{a} key.
Changing the status of variables may change the 
colors of the diagram vertices to reflect the new structure 
and information flow in the diagram (see below). 

At present, these statuses are mutually exclusive --  e.g.,
a variable cannot be both unobserved and adjusted 
or both exposure and unobserved. This could change
in future versions of \pp.

\subsection{Adding new arrows}

To add a new arrow, double-click first on the source vertex 
(which will become highlighted) and then on the target vertex.
The arrow will be inserted. If an arrow existed before
in the opposite direction, that arrow will be deleted, because otherwise
there would now be a cycle in the model. 

Instead of double-clicking on a vertex, you can also move the mouse pointer
over the vertex and press the key \action{c}. Arrows are by default
drawn using a straight line,
but you can change that moving the mouse pointer to the line,
pressing and holding down the left mouse button, and ``bending''
the line by dragging as appropriate.

\subsection{Deleting variables}

To delete a variable, move the mouse pointer over that variable 
and hit the \action{del} key on your keyboard, or alternatively
the \action{d} key (the latter comes in handy if you're on a Mac, which 
has no real delete key).
All arrows to that variable will be deleted along 
with the variable. In contrast to \pp versions prior to 2.0,
all variables can now be deleted including exposure and outcome.

\subsection{Deleting arrows}

An arrow is deleted just like it has been inserted, 
i.e., by double-clicking first on the start 
variable and then on the target variable. An arrow 
is also deleted automatically if a new one is 
inserted in the opposite direction (see above). 

\subsection{Choosing the style of display}

At present, you can choose between two DAG diagram styles: ``classic'', where nodes and
their labels are separate from each other, and SEM-like, where labels are inside nodes. 
Both have their advantages and disadvantages. By the way, ``SEM'' refers to structural
equation modeling.

\section{Analyzing diagrams}

\label{sec:diagramanalysis}

\subsection{Paths}

Causal diagrams contain two different kinds of paths between exposure and outcome
variables.

\begin{itemize}
\item \emph{Causal paths} start at the exposure, contain
only arrows pointing away from the exposure, and end at 
the outcome. That is, they have the form
$e \rightarrow x_1 \rightarrow \ldots \rightarrow x_k \rightarrow o$.
\item \emph{Biasing paths} are all other paths from exposure to outcome. For 
example, such paths can have the form 
$e \leftarrow x_1 \rightarrow \ldots \rightarrow x_k \rightarrow o$.
\end{itemize}

With respect to a set $\mathbf{Z}$ of conditioning variables (that 
can also be empty if we are not conditioning on anything), 
paths can be either \emph{open} or \emph{closed}
(also called d-separated \cite{Pearl2009}). A path 
is \emph{closed} by $\mathbf{Z}$ if one or both of the following holds: 

\begin{itemize}
 \item The path $p$ contains a chain $x \rightarrow m \rightarrow y$ 
 	or a fork $x \leftarrow m \rightarrow y$ 
    such that $m$ is in $\mathbf{Z}$.
 \item The path $p$ contains a collider $x \rightarrow c \leftarrow y$ 
 	such that $c$ is not in $\mathbf{Z}$ and 
    furthermore, $\mathbf{Z}$ does not contain
    any successor of $c$ in the graph. 
\end{itemize}

Otherwise, the path is \emph{open}.
The above criteria imply that paths consisting of only one
arrow are always open, no matter the content of $\mathbf{Z}$. 
Also it is possible that a path is closed with respect
to the empty set $\mathbf{Z}=\{\}$.

\subsection{Coloring}

It is not easy to verify by hand which paths are open and
which paths are closed, especially in larger diagrams. 
\pp highlights all arrows lying on open 
biasing paths in red and all arrows lying on open
causal paths in green. This highlighting is optional 
and is controlled via 
the \action{highlight causal paths} and \action{highlight biasing paths}
checkboxes.

\subsection{Effect analysis}

As mentioned above, arrows in DAGs represent \emph{direct effects}. That is, in a DAG
with three variables $X$, $M$, and $Y$, an arrow $X \to Y$ means that there is a causal
effect of $X$ on $Y$ that is \emph{not} mediated through the variable $M$. 
Often when building DAGs, people tend to forget this aspect and think only about whether
any kind of causal effect exists, without paying attention to how it is mediated. This 
may result in DAGs with too many arrows. 

To aid users with this, George Ellison (Leeds University) suggested to implement a 
function that identifies arrows for which also a corresponding indirect pathway exists. 
After drawing an initial DAG, one might reconsider these arrows and judge whether they
are really necessary given the indirect pathways already present in the diagram.

For example, suppose after thinking about the pairwise causal relationships between
our variables $X$, $M$, $Y$ we came up with this DAG:

\begin{tikzpicture}
\node (x) at (0,0) {$X$};
\node (m) at (1,0) {$M$};
\node (y) at (2,0) {$Y$};
\draw [very thick,->] (x) -- (m);
\draw [very thick,->] (m) -- (y);
\draw [bend left=40,->] (x) edge (y);
\end{tikzpicture}

For the arrows drawn in bold, there is no corresponding indirect path -- removing
one of these arrows from the diagram means that there will no longer be any causal 
effect between the corresponding variables. These arrows are called \emph{atomic direct
effects} in \pp, and they can be highlighted -- like in the above DAG -- by ticking
the checkbox with that name. 
On the other hand, for the thin arrow 
$X \to Y$, there is also the indirect pathway $X \to M \to Y$. One may therefore reconsider
whether the arrow $X \to Y$ is truly necessary -- 
perhaps the causal effect from $X$ to $Y$ is entirely mediated through $M$.

\subsection{View mode}

There are several ways to transform a given DAG such that it becomes better suited for 
a particular purpose. We call such a transformed DAG a \emph{derived graph}. Currently
\pp can display two kinds of derived graphs: correlation graphs, and moral graphs.
These derived graphs can be shown by clicking on the respective radio button in the
\action{View mode} field on the left-hand side of the screen. 

\subsubsection{The correlation graph}

The correlation graph is not a DAG, but a simple graph with lines instead of arrows. 
It connects each pair of variables that, according to the diagram, could be statistically
dependent. In other words, variables not connected by a line in the correlation graph
must be statistically independent. These pairwise independencies are also listed in the
\action{Testable implications} field on the right-hand side of the screen, and so the
correlation graph could be seen as encoding a subset of those implications. 

Although this is not implemented in \pp yet, it is also possible to take a given 
correlation graph (which can be obtained e.g. by thresholding a covariance matrix) and 
list all the DAGs that are ``compatible'' with it in the sense that they entail exactly
the given correlation graph \cite{textor15_uai}.

\subsubsection{The moral graph}

To identify minimal sufficient adjustment sets, \pp uses the so-called ``moral graph'',
which results from a transformation of the model to an undirected graph.
This procedure is also highly recommended if you wish to verify the calculation by hand.
See the nice explanation by Shrier and Platt \cite{ShrierP2008} for details on this
procedure.  

In \pp, you can switch between display of the model and its moral graph 
choosing ``moral graph'' in the``view mode'' section on the left-hand
side of the page.

\subsection{Causal effect identification}

Some of the most important features of \pp are concerned with the question: how
can causal effects be estimated from observational data? Currently, two types of causal
effect identification are supported: adjustment sets, and instrumental variables.

\subsubsection{Adjustment sets}

\label{sec:adjustment}

Finding sufficient adjustment sets is one main purpose 
of \pp. In a nutshell, a sufficient adjustment
set $\mathbf{Z}$ is a set of covariates such that adjustment,
stratification, or selection (e.g. by restriction or 
matching) will minimize bias when estimating the causal 
effect of the exposure on the outcome (assuming that
the causal assumptions encoded in the diagram hold). 
You can read more about controlling bias and confounding in Pearl's textbook, 
chapter 3.3 and epilogue \cite{Pearl2009}. 
Moreover, Shrier and Platt \cite{ShrierP2008} 
give a nice step-by-step tutorial on how to test if a set of covariates
is a sufficient adjustment set.

To identify adjustment sets, the diagram must contain at least
one exposure and at least one outcome.

\paragraph{Total and direct effects.}
One can understand adjustment sets graphically by viewing an adjustment set
as a set $\mathbf{Z}$ that closes all all biasing 
paths while keeping desired causal paths open
(see previous section).
\pp considers two kinds of adjustment sets: 

\begin{itemize}
 \item Adjustment sets for the \emph{total effect} are sets that 
close all biasing paths and leave all causal paths
open. 
 In the literature, if the effect is not mentioned
(e.g. \cite{ShrierP2008,KnueppelS2010}), then usually
this kind of adjustment set is meant.
 \item   Adjustment sets for the \emph{direct effect} are sets that 
close all biasing paths and all causal paths, and leave only 
the direct arrow from exposure $X$ to outcome $Y$ (i.e., the path
$X \rightarrow Y$, if it exists) open.
\end{itemize}

In a diagram where the only causal path between exposure 
and outcome is the path $X \rightarrow Y$, the total effect
and the direct effect are equal. This is true e.g. for the 
diagram in Figure~\ref{fig:syntax}. An example diagram where the 
direct and total effects are not equal is shown in 
Figure~\ref{fig:effects}.

\begin{figure}
\begin{center}
\begin{tikzpicture} [scale=2]
\tikzstyle{vertex}=[rectangle] 
\node at(-1,.5)(C1) [vertex]{$C_{1}$};
\node at(1,-.5)(C2)[vertex]{$C_{2}$};
\node at(2,0) (Y)  [vertex]{$Y$}
	edge [<-] (C2);
\node at(1,.5) (M)  [vertex]{$M$}
	edge [->,thick,densely dashed] (Y)
	edge [<-] (C1);	
\node at(0,0) (X)  [vertex]{$X$}
	edge [->,thick,densely dashed] (M)
	edge [<-] (C1)
	edge [<-] (C2);	
\draw (X) edge [->,thick] (Y);
\end{tikzpicture}
\end{center}

\caption{A causal diagram where the total and direct 
effects of exposure $X$ on outcome $Y$ are not equal. The total effect is the effect
mediated only via the thick (both dashed and solid) arrows,
while the direct effect is the effect mediated only 
via the thick arrow.}
\label{fig:effects}

\end{figure}

As proved by Lauritzen et al. \cite{Lauritzen1990} 
(see also Tian et al. \cite{TianPP1998}), 
it suffices to restrict our attention to the part of the model that consists of exposure, 
outcome, and their ancestors for identifying sufficient adjustment sets. This is indicated
by \pp by coloring irrelevant nodes in gray. The relevant variables are colored according 
to which node they are ancestors of (exposure, outcome, or both) -- see the legend on the 
left-hand side of the screen. The highlighting may be turned on and off by toggling the 
\action{highlight ancestors} checkbox.

\paragraph{Minimal sufficient adjustment sets.} 

A \emph{minimal} sufficient adjustment set is a sufficient 
adjustment set of which no proper subset is itself sufficient. For example, 
consider again the causal diagram in Figure~\ref{fig:syntaxexample}. 
The following three sets are sufficient adjustment sets
for the total and direct effects, which are equal in this case: 

$$ \{A,B,Z\} $$

$$ \{A,Z\} $$

$$ \{B,Z\} $$ 

Each of these sets is sufficient because it closes all biasing paths and leaves 
the causal path open. The sets $\{A,Z\}$ and $\{B,Z\}$ are minimal sufficient adjustment 
sets while the set $\{A,B,Z\}$ is sufficient, but not minimal. 
In contrast, the set $\{Z\}$ is \emph{not} sufficient, since this would 
open  
the path $E \leftarrow A \rightarrow Z \leftarrow B \leftarrow D$: 
Because both $E$ and 
$D$ depend on $Z$, adjusting for $Z$ will induce 
additional correlation between $E$ and $D$. 

\paragraph{Finding minimal sufficient adjustment sets.}

To find minimal sufficient adjustment sets, select the 
option \action{Adjustment (total effect)}
or \action{Adjustment (direct effect)} in the 
\action{Causal effect identification} field. 
\pp
will then calculate all minimal sufficient adjustment sets and display 
them in that field. Any changes made to the diagram will be instantly
reflected in the list of adjustment sets.

\paragraph{Forcing adjustment for specific covariates.}

You can also tell \pp that you wish a specific covariate
to be included into every adjustment set. To do this, move the
mouse over the vertex of that covariate and press the \emph{a} 
key. \pp will then update the list of minimal sufficient
adjustment sets accordingly -- every set displayed
is now minimal in the sense that removing any variable 
\emph{except those you specified} will render
that set insufficient. However, when you adjust for an intermediate
or another descendant of the exposure, \pp will tell you that it is no longer
possible to find a valid adjustment set.

\paragraph{Avoiding adjustment for unobserved covariates.}

You can tell \pp that a certain variable is unobserved 
(e.g. not measured at present, or not measurable because it is a 
latent variable) by moving the mouse 
over that covariate and pressing the \emph{u} key.
\pp will only calculate adjustment sets that do 
not contain unobserved variables. However, if too many or
some important variables are unobserved, then it may
be impossible to close all biasing paths. 

\subsubsection{Instrumental variables}

Sometimes it is not possible to estimate a causal effect by simple covariate adjustment.
For example, this is the case whenever there is an unobserved confounder that directly
effects the exposure and outcome variables. However, this does not necessarily 
mean that it is impossible to estimate the causal effect at all. 
\emph{Instrumental variable regression} is a technique that is 
often used in situations wit unobserved confounders.
Note that this technique depends on linearity assumptions. For further information
on instrumental variables, please refer to the literature \cite{AngristIR96,imbens14}. 
\pp can find instrumental variables in DAGs, as explained below. 

The validity of an instrumental variable $I$ depends on two causal conditions -- 
exogeneity and exclusion restriction. These two conditions can be expressed 
in the language of DAGs and paths as follows: (1) there must be an open path between 
$I$ and the exposure $X$; and (2) all paths between $I$ and the outcome $Y$ must be
closed in a modified graph where all edges out of $X$ are removed. 
A variable that fulfills these two conditions is called an \emph{instrumental variable}
or simply an \emph{instrument}.

Instrumental variables can also be generalized such that the two conditions are required
to hold \emph{conditional on a set of covariates} $\mathbf{Z}$ \cite{BritoPearlUAI02}. 
The two conditions then read as follows: 
(1) there must be a path between 
$I$ and $X$ that is opened by $\mathbf{Z}$; and (2) 
all paths between $I$ and $Y$ must be closed by $\mathbf{Z}$ 
in a modified graph where all edges out of $X$ are removed. 
A variable that fulfills these two conditions is called a
\emph{conditional instrument}.

\pp will find both ``classic'' and conditional instruments when the option 
\action{Instrumental Variable} is selected under the \action{Causal effect identification} 
field. Note that \pp will not always list \emph{all} possible instruments;
instead, it will restrict itself to a certain well-defined subset that we call 
``ancestral instruments''. However, whenever any instrument or conditional instrument
exists at all, then \pp is guaranteed to find one. Note also that if there are several
instruments available, then it is best to choose the one that is most strongly
correlated with $X$ (conditional on $\mathbf{Z}$ in the case of a conditional instrument).

For details regarding ancestral instruments and how \pp computes them, please
refer to the research paper where we describe these methods \cite{zander15_instrument}.

\subsection{Testable implications}

Any implications that are obtained from a causal diagram,
such as possible adjustment sets or instrumental variables,
are of course dependent on the 
assumptions encoded in the diagram.
To some extent, these assumptions can be tested via the 
(conditional) independences implied by the diagram: If two 
variables $X$ and $Y$ are $d$-separated by a set $\mathbf{Z}$, then
$X$ and $Y$ should be conditionally independent
given $\mathbf{Z}$. The converse is not true: Two variables
$X$ and $Y$ can be independent given a set $\mathbf{Z}$ even though they
are not $d$-separated in the diagram. Furthermore, two 
variables can also be $d$-separated by the empty set $\mathbf{Z}=\emptyset$.
In that case, the diagram implies that $X$ and $Y$ are
\emph{unconditionally} independent.

\pp displays all minimal testable implications 
in the \action{Testable implications} text field. Only such
implications will be displayed that are in fact testable,
i.e., that do not involve any unobserved variables. Note
that the set of testable implications displayed by \pp
does not constitute a ``basis set'' \cite{Pearl2009}. 
Future versions will allow choosing between different basis sets. 

In general, the less arrows a diagram contains, the more testable
predictions it implies. For this reason, ``simpler'' models with
fewer arrows are in general easier to falsify (Occam's razor).


\section{Acknowledgements}

I would like to thank my collaborators Maciej Li\'skiewicz
and Benito van der Zander (both at the Institute for Theoretical Computer Science,
University of L\"ubeck, Germany) for our collaborations on developing efficient algorithms
to analyze causal diagrams.  

I also thank Michael Elberfeld, Juliane Hardt, 
Sven Kn\"{u}ppel, Keith Marcus, Judea Pearl, Sabine Schipf, 
and Felix Thoemmes (in alphabetical order) for enlightening discussions
(either in person, per e-mail, or on the SEMnet discussion list)
about DAGs that made this program possible. Furthermore, I thank
Robert Balshaw, George Ellison, 
Marlene Egger, Angelo Franchini,  Ulrike F\"{o}rster, Mark Gilthorpe, 
Dirk van Kampen,
Jeff Martin, Jillian Martin, Karl Micha\"{e}lsson,
David Tritchler, Eric Vittinghof, 
and other users for sending feedback and bug reports that greatly
helped to improve \pp. 

The development of DAGitty was sponsored by funding from the 
Institute of Genetics, Health and Therapeutics at Leeds
University, UK. I thank George Ellison for arranging this
generous support.

\section{Legal notice}

Use of \pp is (and will always be) freely permitted and free of charge. 
You may download a copy of \pp's source code from its website at \url{www.dagitty.net}.
The source code is available under the GNU General Public License (GPL),
either version 2.0, or any later version, at the licensee's choice;
see the file \verb|LICENSE.txt| in the download archive for details.
In particular, the GPL permits you to  modify and redistribute the source
as you please as long as the result remains itself under the GPL.

\section{Bundled libraries}

\pp ships along with the JavaScript library \emph{Prototype.js}, 
a framework that makes life with JavaScript much easier. Only some 
  parts of Prototype (mainly those focusing on data structures) are included to keep the code small. Developed
  by the Prototype Core Team and licensed under the MIT license \cite{Prototype2010}. 

Furthermore, \pp contains some modified code from the \emph{Dracula Graph Library} by 
Philipp Strathausen, which is also licensed under the MIT license \cite{Dracula2010}. 

I am grateful to the authors of these libraries for their valuable work. 

\section{Bundled examples}

\pp contains some builtin examples for didactic and illustrative purposes. 
Some of these examples are taken from published papers or talks given at 
scientific meetings. These are, in inverse chronological order: 

\begin{itemize}
 \item van Kampen 2014 \cite{Kampen2014} 
 \item Polzer et al., 2012 \cite{Polzer2012}
 \item Schipf et al., 2010 \cite{Schipf2010}
 \item Shrier \& Pratt, 2008 \cite{ShrierP2008}
 \item Sebastiani et al.\footnote{The example actually shows only a small part of their DAG.}, 
    2005 \cite{Sebastiani2005}
 \item Acid \& de Campos, 1996 \cite{Acid1996}
\end{itemize}

Another example was provided by Felix Thoemmes 
via personal communication (2013).


\section{Author contact}

I would be glad to receive feedback from those 
who use \pp for research or educational purposes. 
Also, you are welcome to send me your 
suggestions or requests for features that 
you miss in \pp. 

\bigskip

\noindent
Johannes Textor \\
Tumor Immunology Department \\
Radboud University Medical Center \\
 Nijmegen, The Netherlands \\
\\
\href{mailto:johannes.textor@gmx.de}{\tt johannes.textor@gmx.de} \\
\href{http://johannes-textor.name}{\tt johannes-textor.name} \\
Twitter: \href{https://twitter.com/JohannesTextor}{\tt @JohannesTextor}

\bigskip


\bibliography{main}

\end{document}