CausalGraphs.jl

A Julia-native framework for representing, analyzing, composing, comparing, and visualizing cause-effect knowledge and models.

Domain-independent causal relationships.

Get Started

🧠

Cause-Effect Knowledge

Build structured graphs independent from models and views.

📦

Multiple Models

Derive models from a single knowledge base without duplication.

🔬

Metrology Support

First-class integration with uncertainty propagation workflows.

Introduction

CausalGraphs.jl is a Julia library for rigorously modeling, analyzing, and visualizing cause-and-effect relationships.

Unlike simple drawing tools, CausalGraphs.jl strictly separates knowledge (the relationship graph) from views (Ishikawa diagrams, dependency graphs) and models (measurement models, uncertainty propagation, fault trees).

Common Use Cases

Metrology and Uncertainty : Map uncertainty sources in a measurement model (e.g., Ishikawa / GUM) to automatically generate mathematical propagation models.
Systems Engineering and Reliability : Model Fault Trees to identify the root causes of complex problems.
Incident Analysis (Root Cause Analysis) : Formally record "what caused what" to capture knowledge following an IT or industrial failure.

Visual Examples (Cause-Effect Trees)

Thanks to its decoupled architecture, the same knowledge graph can be exported in visual formats.

Example 1: Metrology (Mass Calibration)

Here is how to build a typical cause-and-effect tree for weighing uncertainty.

using CausalGraphs
using Markdown

struct MermaidDisplay
    content::String
end

Base.show(io::IO, ::MIME"text/html", m::MermaidDisplay) = print(io, """
<div class="mermaid">
$(m.content)
</div>
""")

# 1. Create the graph
g = CauseEffectGraph()

# 2. Add the main effect (the problem or measurement)
effect = add_effect!(g, "Weighing Uncertainty")

# 3. Add categories (the "5Ms")
mat = add_category!(g, "Material")
env = add_category!(g, "Environment")
eqp = add_category!(g, "Equipment")
man = add_category!(g, "Manpower")
meth = add_category!(g, "Method")

# 4. Link the effect to categories
add_edge!(g, mat, effect)
add_edge!(g, env, effect)
add_edge!(g, eqp, effect)
add_edge!(g, man, effect)
add_edge!(g, meth, effect)

# 5. Add root causes
add_cause!(g, env, "Air temperature")
add_cause!(g, env, "Buoyancy")
add_cause!(g, eqp, "Balance drift")
add_cause!(g, eqp, "Resolution")
add_cause!(g, mat, "Density")
add_cause!(g, man, "Parallax error")
add_cause!(g, meth, "Calibration procedure")

# 6. Automatic visual rendering via Mermaid
MermaidDisplay(to_ishikawa(g))

ishikawa Weighing Uncertainty Manpower Parallax error Material Density Equipment Balance drift Resolution Method Calibration procedure Environment Air temperature Buoyancy

Example 2: Software Engineering (Server Crash)

Let's model an investigation following a server crash in a web infrastructure.

using CausalGraphs
using Markdown

g_it = CauseEffectGraph()

crash = add_effect!(g_it, "Website Downtime")

db = add_category!(g_it, "Database")
net = add_category!(g_it, "Network")
code = add_category!(g_it, "Application Code")

add_edge!(g_it, db, crash)
add_edge!(g_it, net, crash)
add_edge!(g_it, code, crash)

add_cause!(g_it, db, "CPU Saturation (Locks)")
add_cause!(g_it, db, "Disk Full")
add_cause!(g_it, net, "DDoS Attack")
add_cause!(g_it, net, "TLS Certificate Expiration")
add_cause!(g_it, code, "Memory Leak (OOM)")
add_cause!(g_it, code, "Faulty Deployment")

# Visual rendering
# We can reuse the MermaidDisplay struct defined above, but we have to define it again because Documenter @example blocks are isolated by default unless named the same or using a shared setup.
# Wait, let's redefine it just to be safe.
struct MermaidDisplay
    content::String
end

Base.show(io::IO, ::MIME"text/html", m::MermaidDisplay) = print(io, """
<div class="mermaid">
$(m.content)
</div>
""")

MermaidDisplay(to_mermaid(g_it))

graph LR 3654ccbe_7e0a_4d06_ae5e_8319e1358896["TLS Certificate Expiration"] de994e48_46a0_4e7c_96ba_3e25090847bd["DDoS Attack"] 014d6195_df27_454c_b894_d9221abb271e>"Database"] 07e7e006_0421_42b5_a785_c1667349f509>"Application Code"] 85157aad_1057_46e9_b7f6_1643095c86a6["Memory Leak (OOM)"] d44ad5c3_d20b_4236_993e_fad7284d3d38["Disk Full"] 15591b47_897d_4c1f_a86a_b444c11f17e3(("Website Downtime")) 24cec1bf_f0e1_4d56_b9b6_181b9eba26c8["CPU Saturation (Locks)"] d9d3cb7c_b313_437e_8f7f_e0b1ed995b64["Faulty Deployment"] 5e3290b8_6a38_433b_b94e_3048157f7116>"Network"] de994e48_46a0_4e7c_96ba_3e25090847bd -- "DecomposesInto()" --> 5e3290b8_6a38_433b_b94e_3048157f7116 d44ad5c3_d20b_4236_993e_fad7284d3d38 -- "DecomposesInto()" --> 014d6195_df27_454c_b894_d9221abb271e 5e3290b8_6a38_433b_b94e_3048157f7116 -- "Causes()" --> 15591b47_897d_4c1f_a86a_b444c11f17e3 d9d3cb7c_b313_437e_8f7f_e0b1ed995b64 -- "DecomposesInto()" --> 07e7e006_0421_42b5_a785_c1667349f509 07e7e006_0421_42b5_a785_c1667349f509 -- "Causes()" --> 15591b47_897d_4c1f_a86a_b444c11f17e3 014d6195_df27_454c_b894_d9221abb271e -- "Causes()" --> 15591b47_897d_4c1f_a86a_b444c11f17e3 85157aad_1057_46e9_b7f6_1643095c86a6 -- "DecomposesInto()" --> 07e7e006_0421_42b5_a785_c1667349f509 24cec1bf_f0e1_4d56_b9b6_181b9eba26c8 -- "DecomposesInto()" --> 014d6195_df27_454c_b894_d9221abb271e 3654ccbe_7e0a_4d06_ae5e_8319e1358896 -- "DecomposesInto()" --> 5e3290b8_6a38_433b_b94e_3048157f7116

API Reference

CausalGraphs.AbstractModel — Type

AbstractModel

Automatically generated docstring for AbstractModel.