{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Create System Diagrams\n",
"\n",
"## Making Systems Diagrams with GraphPlot.jl\n",
"\n",
"This tutorial shows you how to create **node-link diagrams** in Julia\n",
"using `Graphs.jl` and `GraphPlot.jl`. These diagrams are perfect for\n",
"system maps — think stocks connected by flows, or components linked by\n",
"relationships. You’ll learn how to build a graph, label nodes and edges,\n",
"apply colours, and export your diagram. We will also use `Compose.jl` to\n",
"draw the graphs, and `Cairo.jl` and `Fontconfig.jl` to render the graphs\n",
"as SVGs for display.\n",
"\n",
"### Your first graph: nodes and edges\n",
"\n",
"A graph is a collection of **nodes** (vertices) connected by **edges**.\n",
"Let’s create a simple graph with four nodes connected in a chain:"
],
"id": "2b634710-6363-41ac-a942-fdb8b3ac3e4c"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"import Pkg\n",
"\n",
"using Graphs\n",
"using GraphPlot\n",
"using Measures\n",
"using Compose\n",
"import Cairo\n",
"import Fontconfig\n",
"\n",
"# Create a graph with 4 nodes and 3 edges\n",
"g = Graphs.path_graph(4)\n",
"\n",
"# Draw it\n",
"gplot(g) |> SVG()"
],
"id": "2"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You should see a diagram with four circles connected by lines.\n",
"`path_graph(4)` creates nodes 1–2–3–4 linked in sequence.\n",
"\n",
"> **How to view the plot**\n",
">\n",
"> - **In VS Code:** Install `Cairo.jl` (`Pkg.add(\"Cairo\")`). The plot\n",
"> will appear in the Plot pane.\n",
"> - **In the REPL (terminal):** Use `gplothtml(g)` to open it in your\n",
"> browser.\n",
"\n",
"### Adding node labels\n",
"\n",
"Without labels, you can’t tell the nodes apart. Add labels as a vector\n",
"of strings (one per node):"
],
"id": "224d8adc-22f1-441c-87a6-cc52f471e400"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"nodelabel = [\"Solar\", \"Battery\", \"Grid\", \"Load\"]\n",
"gplot(g, nodelabel=nodelabel) |> SVG()"
],
"id": "4"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If labels overwrite the nodes, pull them farther out:"
],
"id": "90e4cbb6-df25-42f9-9547-193ca8a9dc5d"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"gplot(g, nodelabel=nodelabel, nodelabeldist=1, nodelabelangleoffset=π/4) |> SVG()"
],
"id": "6"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"- `nodelabeldist` — distance from centre of node to label\n",
"- `nodelabelangleoffset` — rotation angle; default `π/4` puts them\n",
" top-right\n",
"\n",
"### Colouring nodes\n",
"\n",
"Colour nodes to distinguish types (e.g., generation vs. consumption).\n",
"Use the `nodefillc` keyword with a vector the same length as the number\n",
"of nodes:"
],
"id": "152d7122-effc-4029-b08d-d8de6da1d78e"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"using Colors\n",
"\n",
"# One colour per node\n",
"nodefillc = [colorant\"gold\", colorant\"steelblue\",\n",
" colorant\"orange\", colorant\"tomato\"]\n",
"gplot(g, nodelabel=nodelabel, nodefillc=nodefillc) |> SVG()"
],
"id": "8"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Or generate a palette automatically:"
],
"id": "faf32199-ab66-4b07-a52f-6fc99fe51635"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"nodefillc = distinguishable_colors(4, colorant\"blue\")\n",
"gplot(g, nodelabel=nodelabel, nodefillc=nodefillc) |> SVG()"
],
"id": "10"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Directed graphs for stocks & flows\n",
"\n",
"In a stock-and-flow diagram, flows have **direction**. A directed graph\n",
"uses arrows to show which way material (money, energy, information)\n",
"moves. `GraphPlot.jl` draws arrowheads automatically on directed edges."
],
"id": "c75f4512-ca31-4f52-a546-81ef74eb92fb"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"# Create a directed graph: 4 nodes, edges from 1→2, 2→3, 3→4\n",
"g = Graphs.path_digraph(4)\n",
"\n",
"stock_labels = [\"Atmosphere\", \"Plants\", \"Soil\", \"Ocean\"]\n",
"flow_labels = [\"Photosynthesis\", \"Decomposition\", \"Runoff\"]\n",
"\n",
"gplot(g, nodelabel=stock_labels, edgelabel=flow_labels) |> SVG(15cm, 10cm)"
],
"id": "12"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"> **Note**\n",
">\n",
"> Use `SimpleDiGraph` (directed) for flows with arrows. Use\n",
"> `SimpleGraph` (undirected) for mutual relationships. See the\n",
"> [Graphs.jl docs](https://juliagraphs.org/Graphs.jl/stable/) for the\n",
"> full API.\n",
"\n",
"### Edge labels and line styling\n",
"\n",
"Label your edges to show what each flow represents:"
],
"id": "9032c51f-c893-4f91-8add-ac3cf6a84f2f"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"edgelabel = [\"Photosynthesis\", \"Decomposition\", \"Runoff\"]\n",
"gplot(g, nodelabel=stock_labels, edgelabel=edgelabel) |> SVG(15cm, 10cm)"
],
"id": "14"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Adjust edge label placement with `edgelabeldistx` and `edgelabeldisty`:"
],
"id": "206a835a-a9c7-4b13-923c-d86d38e6db8f"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"gplot(g, nodelabel=stock_labels, edgelabel=edgelabel,\n",
" edgelabeldistx=0.5, edgelabeldisty=0.5) |> SVG(15cm, 10cm)"
],
"id": "16"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To colour specific edges differently, use `edgestrokec`:"
],
"id": "50d63ea0-59b8-4c6b-8e09-fea2ccb21550"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"edge_colours = [colorant\"green\", colorant\"brown\", colorant\"blue\"]\n",
"gplot(g, nodelabel=stock_labels, edgelabel=edgelabel,\n",
" edgestrokec=edge_colours) |> SVG(15cm, 10cm)"
],
"id": "18"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Choosing a layout\n",
"\n",
"Different layouts reveal different structure. Try these on your graph:"
],
"id": "d5fa0895-d4f3-4e25-82e4-19341a8bf685"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"# Force-directed (default, good for most cases)\n",
"gplot(g, layout=spring_layout, nodelabel=stock_labels) |> SVG(15cm, 10cm)"
],
"id": "20"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"# Circular --- good for closed loops like nutrient cycles\n",
"gplot(g, layout=circular_layout, nodelabel=stock_labels) |> SVG(15cm, 10cm)"
],
"id": "22"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Saving your diagram\n",
"\n",
"Use `Compose.jl` with `Cairo.jl` and `Fontconfig.jl` to export your\n",
"diagram as PNG, PDF, or SVG:"
],
"id": "ba6721f5-5b7d-465a-b597-e1ee30e5dbd4"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"execute": false
},
"outputs": [],
"source": [
"using Compose\n",
"import Cairo\n",
"import Fontconfig\n",
"\n",
"# Create the plot\n",
"p = gplot(g, nodelabel=stock_labels, nodefillc=nodefillc)\n",
"\n",
"# Save as PNG\n",
"p |> PNG(\"stock-flow.png\", 16cm, 16cm)\n",
"\n",
"# Save as PDF (vector format, scales to any size)\n",
"p |> PDF(\"stock-flow.pdf\", 16cm, 16cm)\n",
"\n",
"# Save as SVG\n",
"p |> SVG(\"stock-flow.svg\", 16cm, 16cm)"
],
"id": "24"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Complete example: carbon cycle diagram\n",
"\n",
"Here is a full script you can copy and run, using `SimpleDiGraph`\n",
"instead of `path_digraph` as above. It builds a simple carbon-cycle\n",
"model with four stocks (atmosphere, plants, soil, ocean) and five flows."
],
"id": "ca7f58fd-dc34-4020-919e-6cc6ef5127ef"
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"output_type": "display_data",
"metadata": {},
"data": {
"text/html": [
"\n",
"\n",
"\n",
"\n",
""
]
}
}
],
"source": [
"using Graphs\n",
"using GraphPlot\n",
"using Colors\n",
"using Compose\n",
"import Cairo\n",
"import Fontconfig\n",
"\n",
"# --- Build the directed graph ---\n",
"# Nodes: 1=Atmosphere, 2=Plants, 3=Soil, 4=Ocean\n",
"# Edges (flows):\n",
"# 1→2 photosynthesis\n",
"# 2→3 litter fall\n",
"# 3→1 decomopsi\n",
"# 1→4 ocean uptake\n",
"# 4→1 ocean release\n",
"\n",
"g = SimpleDiGraph(4) # argument is number of nodes\n",
"add_edge!(g, 1, 2) # atmosphere → plants\n",
"add_edge!(g, 1, 4) # atmosphere → ocean\n",
"add_edge!(g, 2, 3) # plants → soil\n",
"add_edge!(g, 3, 1) # soil → atmosphere\n",
"add_edge!(g, 4, 1) # ocean → atmosphere\n",
"\n",
"# --- Labels ---\n",
"nodelabel = [\"Atmosphere\", \"Plants\", \"Soil\", \"Ocean\"]\n",
"edgelabel = [\"Photosynthesis\", \"Ocean uptake\", \"Litter fall\", \n",
" \"Respiration\", \"Ocean release\"]\n",
"\n",
"# --- Colours ---\n",
"nodefillc = [colorant\"lightblue\", colorant\"green\",\n",
" colorant\"tan2\", colorant\"deepskyblue\"]\n",
"\n",
"# --- Draw ---\n",
"p = gplot(g,\n",
" nodelabel = nodelabel,\n",
" nodefillc = nodefillc,\n",
" edgelabel = edgelabel,\n",
" layout = circular_layout, \n",
" linetype = \"curve\",\n",
" plot_size = (15cm, 10cm)\n",
")\n",
"\n",
"# --- Save ---\n",
"p |> SVG(15cm, 10cm)"
],
"id": "26"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Node shapes and other customisation\n",
"\n",
"> **Warning**\n",
">\n",
"> GraphPlot.jl only draws **circular nodes**. If you need rectangles,\n",
"> diamonds, or custom shapes for stock-and-flow diagrams (e.g.,\n",
"> rectangles for stocks, valves for flows), you will need a different\n",
"> package:\n",
">\n",
"> - **GraphRecipes.jl** (with Plots.jl) — supports `markershape` for\n",
"> different node shapes.\n",
"> - **GraphMakie.jl** — the most flexible; supports custom node markers,\n",
"> interactive plots, and 3D.\n",
">\n",
"> You can install these packages the same way as the others\n",
"> (`Pkg.add(\"GraphRecipes\")` or `Pkg.add(\"GraphMakie\")`).\n",
"\n",
"### Troubleshooting\n",
"\n",
"| Symptom | Fix |\n",
"|----------------------------|--------------------------------------------|\n",
"| `Package GraphPlot not found` | Run `Pkg.add(\"GraphPlot\")` in the REPL. |\n",
"| Plot doesn’t appear in VS Code | Run `Pkg.add(\"Cairo\")`, then restart Julia. |\n",
"| Labels overlap nodes | Increase `nodelabeldist` (e.g., `2.0`). |\n",
"| “No display backend” error | Install Cairo (`Pkg.add(\"Cairo\")`) and try `using Cairo` first. |\n",
"| All nodes same colour | `nodefillc` must be a vector with length equal to the number of nodes. |\n",
"\n",
"### Next steps\n",
"\n",
"- Experiment with `shell_layout` to group nodes in concentric rings.\n",
"- Use `nodesize` to make important stocks larger relative to others.\n",
"- Explore the [GraphPlot.jl\n",
" README](https://github.com/JuliaGraphs/GraphPlot.jl) for the full list\n",
" of keyword arguments."
],
"id": "ead48688-b781-43fb-bbe7-11348f0a1abc"
}
],
"nbformat": 4,
"nbformat_minor": 5,
"metadata": {
"kernel_info": {
"name": "julia"
},
"kernelspec": {
"name": "julia",
"display_name": "Julia",
"language": "julia"
},
"language_info": {
"name": "julia",
"codemirror_mode": "julia",
"version": "1.11.5"
}
}
}