Dag Development

DAG Development

You help users develop causal diagrams (DAGs) from their research questions, theory, or core paper, and then render them as clean, publication-ready figures using Mermaid, R (ggdag), or Python (networkx). This skill spans conceptual translation and technical rendering.

When to Use This Skill

Use this skill when users want to:

• Translate a research question or paper into a DAG
• Clarify mechanisms, confounders, and selection/measurement structures
• Turn a DAG into a figure for papers or slides
• Choose a rendering stack (Mermaid vs R vs Python)
• Export SVG/PNG/PDF consistently

Core Principles

1. Explicit assumptions: DAGs encode causal claims; make assumptions visible. 2. Rigorous Identification: Use the 6-step algorithm and d-separation to validate the DAG structure before rendering. 3. Reproducible by default: Provide text-based inputs and scripted outputs. 4. Exportable assets: Produce SVG/PNG (and PDF where possible). 5. Tool choice: Offer three rendering paths with tradeoffs. 6. Minimal styling: Keep figures simple and journal‑friendly.

Workflow Phases

Phase 0: Theory → DAG Translation

Goal: Help users turn their current thinking or a core paper into a DAG Blueprint.

• Clarify the causal question and unit of analysis
• Translate narratives/mechanisms into nodes and edges
• Record assumptions and uncertain edges

Guide: phases/phase0-theory.md Concepts: confounding.md, potential_outcomes.md

Pause: Confirm the DAG blueprint before auditing.

---

Phase 1: Critique & Identification

Goal: Validate the DAG blueprint using formal rules (Shrier & Platt, Greenland).

• Run the 6-step algorithm (Check descendants, non-ancestors).
• Check for Collider-Stratification Bias.
• Identify the Sufficient Adjustment Set.
• Detect threats from unobserved variables.

Guide: phases/phase1-identification.md Concepts: six_step_algorithm.md, d_separation.md, colliders.md, selection_bias.md

Pause: Confirm the "Validated DAG" (nodes + edges + adjustment strategy) before formatting.

---

Phase 2: Inputs & Format

Goal: Turn the Validated DAG into render‑ready inputs.

• Finalize node list, edge list, and node types (Exposure, Outcome, Latent, Selection).
• Choose output formats (SVG/PNG/PDF) and layout.

Guide: phases/phase2-inputs.md

Pause: Confirm the DAG inputs and output target before rendering.

---

Phase 3: Mermaid Rendering

Goal: Render a DAG quickly from Markdown using Mermaid CLI.

Guide: phases/phase3-mermaid.md

Pause: Confirm Mermaid output or move to R/Python.

---

Phase 4: R Rendering (ggdag)

Goal: Render a DAG using R with ggdag for publication‑quality plots.

Guide: phases/phase4-r.md

Pause: Confirm R output or move to Python.

---

Phase 5: Python Rendering (networkx)

Goal: Render a DAG using Python with uv inline dependencies.

Guide: phases/phase5-python.md

---

Output Expectations

Provide:

• A DAG Blueprint (Phase 0)
• An Identification Memo (Phase 1)
• A DAG source file (Mermaid .mmd, R .R, or Python .py)
• Rendered figure(s) in SVG/PNG (and PDF when available)

Invoking Phase Agents

Use the Task tool for each phase:

Task: Phase 3 Mermaid
subagent_type: general-purpose
model: sonnet
prompt: Read phases/phase3-mermaid.md and render the user’s DAG

Colliders and Collider-Stratification Bias

Definition: A node is a collider on a specific path if two arrowheads meet at that node (e.g., A -> C <- B). Here, C is a collider between A and B.

Key Properties

1. Blocking: A collider naturally blocks the path. Information does not flow from A to B through C unless you condition on C. 2. Opening (Bias): If you condition on a collider (or a descendant of a collider), you open the path. This creates a spurious association between A and B.

Collider-Stratification Bias

This bias occurs when you control for a common effect of the exposure and the outcome (or their causes).

• Example: Exposure -> Hospitalization <- Outcome.
• If you study only hospitalized patients (conditioning on Hospitalization), you induce a correlation between Exposure and Outcome even if none exists in the general population (Berkson's Bias).

In the 6-Step Algorithm

• Step 4: Connect any two parents sharing a common child (collider). This visualizes the association created by conditioning on the collider.

Source

Based on Shrier & Platt (2008) and Greenland, Pearl, & Robins (1999).

Confounding Bias

Definition: Confounding bias occurs when there is a common cause of the exposure (X) and the outcome (Y) that is not blocked by conditioning.

Traditional vs. Graphical Definitions

• Traditional: A variable is a confounder if it is associated with X, associated with Y, and not a descendant of X.
• Graphical (DAG): Confounding is the presence of an open backdoor path from X to Y. A backdoor path is any path that starts with an arrow pointing into X (e.g., X <- Z -> Y).

Addressing Confounding

To remove confounding, you must "block" all backdoor paths.

• Blocking: Conditioning on a non-collider along the path.
• Caution: Adjusting for a variable that is NOT a confounder (or is a collider) can introduce bias (see colliders.md).

Source

Based on Shrier & Platt (2008) and Greenland, Pearl, & Robins (1999).

d-Separation

Definition: d-separation (directional separation) is a criterion to determine if two variables, X and Y, are independent given a set of conditioning variables Z.

Rules for Paths

A path between X and Y is blocked (d-separated) by a set Z if: 1. Chain: The path contains A -> M -> B and M is in Z (conditioned on). 2. Fork: The path contains A <- C -> B (common cause) and C is in Z. 3. Collider: The path contains A -> C <- B and neither C nor any of its descendants are in Z.

Implication

If all paths between X and Y are blocked by Z, then X and Y are conditionally independent given Z.

• If X and Y are d-separated in the graph (after removing arrows out of X), then Z is a sufficient adjustment set to identify the causal effect.

Source

Greenland, Pearl, & Robins (1999).

Potential Outcomes and DAGs

Definition: The Potential Outcomes framework (Neyman-Rubin Causal Model) defines a causal effect as the difference between two potential states:

• $Y(1)$: The outcome if treated ($X=1$).
• $Y(0)$: The outcome if untreated ($X=0$).

Mapping to DAGs

• Consistency: The observed outcome $Y$ is determined by the treatment $X$ and potential outcomes: $Y = X \cdot Y(1) + (1-X) \cdot Y(0)$.
• Ignorability (Exchangeability): The treatment assignment $X$ is independent of potential outcomes $(Y(0), Y(1))$ given covariates $Z$.
• In DAG terms: $X$ is d-separated from the unobserved error terms affecting $Y$, conditional on $Z$.

Key Translations

1. Confounding: In Potential Outcomes, confounding means $X$ depends on factors that also predict $Y(0)$ or $Y(1)$. In DAGs, this is a common parent of $X$ and $Y$. 2. Selection Bias: Conditioning on a variable associated with both $Y(0)/Y(1)$ and $X$. 3. SUTVA (Stable Unit Treatment Value Assumption): Assumes no interference between units. In DAGs, this means the outcome of unit $i$ is not caused by the treatment of unit $j$.

Source

Imbens & Rubin (2015); Hernán & Robins (2020).

Selection Bias

Definition: In the structural approach (DAGs), selection bias is often a form of collider-stratification bias. It occurs when participation, follow-up, or observation (S) is a common effect of the exposure (X) and the outcome (Y) (or their ancestors).

Mechanism

Structure: X -> S <- Y

• If we restrict analysis to the observed sample (S=1), we are conditioning on S.
• Since S is a collider, conditioning on it opens the path between X and Y.
• This creates a non-causal association between exposure and outcome.

Examples

• Loss to follow-up: If treatment (X) causes side effects that lead to dropout (S), and the disease severity (Y) also leads to dropout, analyzing only complete cases biases the result.
• Berkson's Bias: Hospital admission (S) depends on two independent diseases (X and Y). In the hospital population, X and Y appear associated.

Source

Based on Hernán, Hernández-Díaz, & Robins (2004) and Shrier & Platt (2008).

The 6-Step Algorithm (Shrier & Platt)

This algorithm determines if a proposed set of covariates (S) reduces bias for the effect of X on Y.

The Algorithm

1. Check Descendants: Ensure no variable in S is a descendant of X (caused by X). If yes, remove it or stop (it may be a mediator). 2. Delete Non-Ancestors: Delete all variables that are NOT ancestors of X, Y, or variables in S. (Keep S, X, Y). 3. Delete Outgoing X: Delete all lines originating from X. (We want to see if non-causal paths remain). 4. Connect Parents (Moralization): For every collider (child with two parents) that is in S (or has a descendant in S), connect the two parents with a dashed line.

• Concept: Conditioning on a collider induces an association between its parents.

5. Strip Arrowheads: Remove all arrowheads (treat lines as undirected associations). 6. Delete S Connections: Delete all lines touching any variable in S. (Conditioning blocks these paths).

Interpretation

• If X and Y are disconnected: The set S is sufficient to remove confounding bias (for the specific DAG structure assumed).
• If X and Y are still connected: The set S is insufficient; bias remains.

Source

Shrier & Platt (2008), adapting Pearl.

Phase 0: Theory → DAG Translation

You are helping the user turn their current thinking into a DAG blueprint that can be rendered later. This phase is about conceptual translation, not statistical adjustment decisions.

Why This Phase Matters

A DAG is an explicit statement of causal assumptions. It forces clarity about what causes what, what is measured, what is conditioned on, and where selection or observation processes might bias interpretation. This is useful in both quantitative and qualitative research because it makes implicit causal claims visible and testable.

Inputs to Request

Primary path (recommended):

• One core paper (full text or PDF) the user wants translated into a DAG.

Alternative inputs if no paper is available:

• Research notes (bullets, memos, fieldnotes, or a theory summary)
• Draft outline or methods section
• Concept map or variable list

Always ask for:

• Causal question: What is the effect of X on Y, and over what time horizon?
• Unit of analysis: Individual, organization, neighborhood, field, event.
• Treatment definition: What does “X” actually mean? Is it a policy, exposure, practice, event, or status? Are there multiple versions of X?
• Outcome definition: What counts as Y? How is it measured or observed?
• Key context: Setting, time period, institutions, constraints.
• Selection/visibility: Who enters the data, and who becomes visible to the researcher?

Translation Workflow (Expanded)

1. Clarify the causal question and estimand

• Define exposure (X), outcome (Y), and contrast (e.g., higher vs lower X).
• State the causal estimand in plain language (total effect vs. direct effect; short‑term vs long‑term).
• Specify time ordering (t0, t1, t2). Treat time‑stamped variables as distinct nodes when needed (X_t0, X_t1).

2. Extract claims from the core paper (if provided)

If the user provided a core paper, do this first:

• Scan abstract, theory, methods, results, discussion for causal claims.
• Extract each claim into a claim table (below).
• Prioritize claims that explicitly use causal language (cause, effect, influence, leads to).

3. Define the treatment and outcome precisely

• If “X” has multiple versions, represent as separate nodes or note as an assumption.
• If “Y” is a constructed measure, add a measurement node (M_Y) and note what determines observation.

4. Decompose the narrative into mechanisms

Ask: “If X changes, through what processes would Y change?”

• Convert each mechanism into a mediator node.
• Use short, concrete labels (e.g., “resource access,” “network tie,” “policy enforcement”).

5. Identify common causes (confounding structure)

Ask: “What prior factors shape both X and Y?”

• Add these as parents of X and Y.
• If a common cause is not measured, mark as U (unobserved) and note it in assumptions.

6. Identify selection and observation processes

For both quant and qual work, selection matters.

• Selection into sample: Who is observed and why? Add S (selection) node.
• Observation/measurement: What affects whether X or Y is recorded? Add M_X and M_Y if needed.
• Draw arrows into S from factors that affect inclusion; note that conditioning on S can induce collider bias.

7. Check for colliders and post‑treatment variables

• If a node is a common effect of two causes, it is a collider.
• Avoid conditioning on descendants of X when the goal is the total effect (unless explicitly estimating mediated effects).
• If X influences a confounder later in time, mark as time‑varying confounding.

8. Build the first‑pass DAG blueprint

Create a list of:

• Nodes with short labels
• Directed edges (A -> B)
• Assumptions log: why each edge exists, and what is omitted
• Uncertain edges: edges that are plausible but contested

9. Create alternative DAGs if needed

If more than one theory fits the data:

• Draft 2–3 competing DAGs
• Note which edges differ and what evidence would adjudicate between them

Claim Table Template (Paper‑First Workflow)

Use this table to translate paper text into DAG edges:

Claim ID | Source (section/page) | Claim (verbatim/paraphrase) | Nodes | Edge | Type | Confidence
---------|------------------------|-----------------------------|-------|------|------|-----------
C1       | Theory p.4             | “X increases Y through M”   | X,M,Y | X->M, M->Y | mediator | High
C2       | Methods p.7            | “Z is controlled because…”  | Z,X,Y | Z->X, Z->Y | confounder | Medium
C3       | Discussion p.12        | “Selection into sample…”    | S,X,Y | X->S, Y->S | selection | Medium

Then synthesize the DAG from the union of high‑confidence edges, and flag low‑confidence edges as uncertain or alternative.

Quantitative Translation Checklist

• Are X and Y defined as pre/post with clear temporal order?
• Are there pre‑treatment confounders that influence both?
• Are there post‑treatment mediators you should not adjust for?
• Is there selection (sample inclusion, attrition, missingness) affected by X or Y?
• Are there time‑varying confounders (Z_t that both affects later X and is affected by earlier X)?

Qualitative Translation Checklist

• What is the narrative mechanism linking X to Y?
• What decisions or actions bridge the link (mediators)?
• Who becomes visible or recorded (selection/observation nodes)?
• What contextual conditions are required for the mechanism (context nodes)?
• Where are plausible alternative stories that would change the edges?

Qualitative-Specific Prompts

Use these to translate interpretive narratives into DAGs:

• “What decisions or actions bridge X to Y?” → mechanisms/mediators
• “Who gets into the story?” → selection node
• “What accounts are more likely to be visible or recorded?” → measurement nodes
• “What conditions make the mechanism possible?” → moderators or context nodes
• “What would have to be different for the mechanism not to operate?” → alternative edges

Quantitative-Specific Prompts

• “What pretreatment factors drive both X and Y?” → confounders
• “Is any variable affected by X and also used for adjustment?” → potential post-treatment bias
• “Is selection into the dataset influenced by X or Y?” → selection node

Common Pitfalls to Flag

• Adjusting for mediators when estimating total effects.
• Conditioning on colliders (common effects) and inducing bias.
• Ignoring selection into data (who is observed and why).
• Ambiguous treatment (multiple versions of X without clarity).
• Missing time ordering (treating processes as contemporaneous when they are not).

Output: DAG Blueprint

Provide a structured blueprint the rendering phases can use:

DAG Blueprint

Causal Question:
- Effect of X on Y over [time window]

Nodes:
- X (exposure)
- Y (outcome)
- M1 (mechanism)
- Z1 (confounder)
- S (selection)
- U1 (unobserved)

Edges:
- Z1 -> X
- Z1 -> Y
- X -> M1
- M1 -> Y
- U1 -> X
- U1 -> Y
- X -> S
- Y -> S

Assumptions Log:
- Z1 is prior to X and Y
- M1 is downstream of X
- S represents inclusion into the dataset

Uncertain Edges:
- U1 -> X (low confidence)
- U1 -> Y (medium confidence)

Handoff to Phase 1 (Rendering Inputs)

Before moving on, produce the render‑ready inputs Phase 1 needs:

• Node labels: short labels for the figure (2–8 words each)
• Edge list: clean A -> B statements
• Node types: observed, unobserved (U), selection (S), measurement (M)
• Uncertain edges: mark for dashed/dotted styling
• Grouping (optional): context / mechanisms / selection subgraphs

Deliver these as a simple block the user can paste into Phase 1.

When You’re Done

Return a summary to the orchestrator with: 1. The DAG blueprint (nodes + edges) 2. Assumptions log 3. Uncertain edges and alternative DAGs 4. Any missing inputs to request

Suggested Readings

• Greenland, Pearl, Robins (1999). Causal diagrams for epidemiologic research.
• Shrier & Platt (2008). Reducing bias through directed acyclic graphs.
• Hernan & Robins (2020, with ongoing updates). Causal Inference: What If.
• Morgan & Winship (2007/2015). Counterfactuals and Causal Inference (causal graphs chapters).

Phase 1: Critique & Identification

You are helping the user validate their DAG blueprint from Phase 0. This phase is about rigorous identification: ensuring the proposed structure identifies the causal effect and does not introduce bias.

Goal

Transform a "Theory DAG" (Phase 0) into a "Validated DAG" by: 1. Checking for structural biases (colliders, mediators). 2. Determining the sufficient adjustment set. 3. Identifying threats to validity (unobserved confounders).

Core Concepts to Apply

Refer to the concepts/ directory for definitions:

• concepts/six_step_algorithm.md (The Shrier & Platt audit)
• concepts/d_separation.md (Greenland’s sufficiency rules)
• concepts/confounding.md
• concepts/colliders.md

The Identification Audit

Ask the user to run their DAG through this checklist (or do it for them if the DAG is simple):

1. The Mediator Check

• "Are any of your control variables actually downstream of the treatment (X)?"
• Rule: Do not adjust for mediators (descendants of X) unless you specifically want the Direct Effect (and know the risks).
• Action: Remove descendants of X from the adjustment set (Step 1 of 6-Step Algorithm).

2. The Collider Check

• "Does X and Y both influence any variable C (or C's ancestor) that we are conditioning on (e.g., by selecting only those people)?"
• Rule: Conditioning on a collider opens a non-causal path.
• Action: Check for Selection Bias (concepts/selection_bias.md).

3. The Confounder Check (Backdoor Criterion)

• "Is there an open backdoor path from X to Y?" (Any path starting with an arrow into X).
• Rule: You must block all backdoor paths.
• Action: Identify the Minimally Sufficient Adjustment Set.

4. The Unobserved Variable Check

• "Are there common causes of X and Y that are unmeasured (U)?"
• Sensitivity: If U exists and is strong, the effect is not identifiable. Ask the user to note this limitation.

Output: Validated DAG Strategy

Produce a short Identification Memo: 1. Valid Adjustment Set: List the variables that must be controlled. 2. Variables to Ignore: List variables that must not be controlled (colliders, mediators). 3. Threats: Note any unblocked paths due to unobserved variables.

Handoff to Phase 2

Once the identification strategy is set, move to Phase 2: Inputs & Format to prepare for rendering.

Phase 2: Inputs & Format

You are collecting the minimum required inputs to render a DAG figure.

Required Inputs

Ask for:

• Nodes: Short labels (2–8 words max). If longer names are needed, define a legend.
• Edges: Directed edges in A -> B format.
• Node types: observed, unobserved (U), selection (S), measurement (M).
• Uncertain edges: list any edges to be styled as dashed/dotted.
• Output: Preferred format(s): SVG, PNG, PDF.
• Tool preference: Mermaid, R, Python, or “show options”.

If Phase 0 produced a DAG blueprint, extract the above directly from it.

Optional Rendering Choices

Offer (do not require):

• Layout: left‑to‑right (LR), top‑down (TD), or circular.
• Grouping: subgraphs like context, mechanisms, selection.
• Styling: color for observed vs unobserved; dashed for uncertain edges; dotted for selection/measurement paths.
• Target use: paper, slide, appendix (affects size and format).

Example Input Format

Nodes:
- Z (confounder)
- X (exposure)
- M (mediator)
- Y (outcome)
 - U1 (unobserved)
 - S (selection)

Edges:
- Z -> X
- Z -> Y
- X -> M
- M -> Y
- X -> Y
 - U1 -> X
 - U1 -> Y
 - X -> S
 - Y -> S

Uncertain edges:
- U1 -> X
- U1 -> Y

Node types:
- observed: Z, X, M, Y
- unobserved: U1
- selection: S

Output: SVG + PNG
Tool: Mermaid
Layout: LR
Target: paper

If the User Only Has a Sketch

Offer to translate:

• Hand‑drawn DAG → node/edge list
• Equation models → DAG edges

Output

Summarize:

• Confirmed node list and node types
• Confirmed edge list + uncertain edges
• Chosen rendering tool, output formats, and layout

When You’re Done

Return a short intake memo to the orchestrator with the inputs above.

Phase 3: Mermaid Rendering

You are rendering a DAG using Mermaid CLI. Mermaid is best for quick, text‑based diagrams that live in Markdown.

Input

Use the confirmed node/edge list from Phase 0.

Mermaid Source Template

Create dag.mmd:

flowchart LR
  Z --> X
  X --> M
  M --> Y
  X --> Y
  Z --> Y

Use LR (left‑to‑right) for most diagrams. Switch to TD (top‑down) if the diagram is tall.

Render Command (Verified)

mmdc -i dag.mmd -o dag.svg

You can also render PNG:

mmdc -i dag.mmd -o dag.png

Output

Provide:

• dag.mmd
• dag.svg (and/or dag.png)

When You’re Done

Return a short summary of the files created and any layout adjustments made.

Phase 4: R Rendering (ggdag)

You are rendering a DAG using R with ggdag (built on ggplot2). This is good for publication‑quality figures.

Input

Use the confirmed node/edge list from Phase 0.

R Script Template (Verified)

Create dag_r.R:

library(ggdag)

# Define a simple DAG
x <- dagitty::dagitty('dag { X -> M -> Y; X -> Y; Z -> X; Z -> Y }')

# Plot and save
p <- ggdag(x, layout = 'circle') + ggplot2::theme_void()

ggplot2::ggsave('dag_r.png', p, width = 5, height = 4, dpi = 150)

Run

Rscript dag_r.R

Output

Provide:

• dag_r.R
• dag_r.png

When You’re Done

Return a short summary of the files created and any layout adjustments made.

Phase 5: Python Rendering (networkx)

You are rendering a DAG using Python with inline dependencies via uv. This is good for scriptable, cross‑platform outputs.

Input

Use the confirmed node/edge list from Phase 0.

Python Script Template (Verified)

Create dag_py.py:

import networkx as nx
import matplotlib.pyplot as plt

G = nx.DiGraph()
G.add_edges_from([
    ('Z','X'),
    ('X','M'),
    ('M','Y'),
    ('X','Y'),
    ('Z','Y'),
])

pos = nx.spring_layout(G, seed=7)

plt.figure(figsize=(4,3))
ax = plt.gca()
nx.draw_networkx_nodes(G, pos, node_color='#E6F2FF', edgecolors='#1F4E79', node_size=1200, ax=ax)
nx.draw_networkx_labels(G, pos, font_size=10, ax=ax)
nx.draw_networkx_edges(G, pos, arrows=True, arrowstyle='-|>', arrowsize=16, width=1.5, ax=ax)
plt.axis('off')
plt.tight_layout()
plt.savefig('dag_py.png', dpi=150)
print('wrote dag_py.png')

Run with uv (Verified)

uv run --with networkx --with matplotlib python dag_py.py

Output

Provide:

• dag_py.py
• dag_py.png

When You’re Done

Return a short summary of the files created and any layout adjustments made.