GitHub

CausalGraphs.jl

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

Domain-independent causal relationships.

Get Started
CausalGraphs.jl logo
🧠

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 Environment Buoyancy Air temperature Method Calibration procedure Equipment Resolution Balance drift

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 d6d76b00_e3f7_428e_b72f_ec810bc606ec["Memory Leak (OOM)"] 57043bbb_9eaa_489d_9f5e_812c96fabbc4(("Website Downtime")) 256e6177_d6c3_4436_bcb8_aac8ef224c41>"Database"] 1562b4ac_7251_4f20_a7bc_796233e789b8["CPU Saturation (Locks)"] ff908429_2268_42b0_84c9_5e96830028c2["DDoS Attack"] 98dffb31_8baf_406b_bb26_453c84d28679["Faulty Deployment"] 809dbe70_b0b6_41fe_8da4_457e7f8684b5["TLS Certificate Expiration"] 444d1f9a_a737_4799_9723_ca6b7ea1e635>"Network"] d1eafd23_2801_487a_b428_0221b99e2e91>"Application Code"] f2301f11_0ff6_473c_ad3c_14d9b744920f["Disk Full"] 256e6177_d6c3_4436_bcb8_aac8ef224c41 -- "Causes()" --> 57043bbb_9eaa_489d_9f5e_812c96fabbc4 444d1f9a_a737_4799_9723_ca6b7ea1e635 -- "Causes()" --> 57043bbb_9eaa_489d_9f5e_812c96fabbc4 d1eafd23_2801_487a_b428_0221b99e2e91 -- "Causes()" --> 57043bbb_9eaa_489d_9f5e_812c96fabbc4 1562b4ac_7251_4f20_a7bc_796233e789b8 -- "DecomposesInto()" --> 256e6177_d6c3_4436_bcb8_aac8ef224c41 f2301f11_0ff6_473c_ad3c_14d9b744920f -- "DecomposesInto()" --> 256e6177_d6c3_4436_bcb8_aac8ef224c41 ff908429_2268_42b0_84c9_5e96830028c2 -- "DecomposesInto()" --> 444d1f9a_a737_4799_9723_ca6b7ea1e635 809dbe70_b0b6_41fe_8da4_457e7f8684b5 -- "DecomposesInto()" --> 444d1f9a_a737_4799_9723_ca6b7ea1e635 d6d76b00_e3f7_428e_b72f_ec810bc606ec -- "DecomposesInto()" --> d1eafd23_2801_487a_b428_0221b99e2e91 98dffb31_8baf_406b_bb26_453c84d28679 -- "DecomposesInto()" --> d1eafd23_2801_487a_b428_0221b99e2e91

API Reference

CausalGraphs.IshikawaLayout — Type
IshikawaLayout

A structural layout representing an Ishikawa (Fishbone) diagram. Stores the main effect, category branches, and the underlying root causes for each category.

source
Base.read — Method
Base.read(path::AbstractString, ::Type{CauseEffectGraph})

Loads a causal graph from a file. The format is inferred from the file extension. Supported formats: .json.

source
Base.write — Method
Base.write(path::AbstractString, g::Union{CauseEffectGraph, AbstractModel})

Saves the causal graph or model to a file. The format is inferred from the file extension. Supported formats: .json, .dot (GraphViz).

source
CausalGraphs.to_ishikawa — Method
to_ishikawa(g)

Generates a Mermaid JS Ishikawa (fishbone) string representation of the causal graph. Assumes the graph contains one main effect and categories linked to it.

source