Skip to content

Loading and saving graphical models

Creative Commons LicenseaGrUMinteractive online version

pyAgrum can read and write graphical models in many file formats. This notebook gives an overview of which formats are available for each model type, what they preserve, and why the native bgum (binary) and jgum (JSON) formats are the best choice for pyAgrum workflows.

import os
import tempfile
import time
import pyagrum as gum
import pyagrum.lib.notebook as gnb

The three main model types each have their own set of supported formats.

print(f"BayesNet formats : {gum.availableBNExts()}")
print(f"InfluenceDiagram : {gum.availableIDExts()}")
print(f"MarkovRandomField : {gum.availableMRFExts()}")
BayesNet formats : bif|dsl|net|bifxml|o3prm|uai|xdsl|pkl|jgum|bgum
InfluenceDiagram : xmlbif|bifxml|xml|jgum|bgum|pkl
MarkovRandomField : uai|jgum|bgum|pkl

The load/save API is uniform across model types:

ModelLoadSave
BayesNetgum.loadBN(filename)gum.saveBN(bn, filename)
InfluenceDiagramgum.loadID(filename)gum.saveID(diag, filename)
MarkovRandomFieldgum.loadMRF(filename)gum.saveMRF(mrf, filename)

The format is selected automatically from the file extension.

Let’s load the classic Asia network and save/reload it in every available format, comparing file size and round-trip speed.

bn_asia = gum.loadBN("res/asia.bgum")
gnb.flow.row(bn_asia, captions=[f"Asia BN — {bn_asia.size()} nodes, {bn_asia.sizeArcs()} arcs"])
Asia visit_to_Asia visit_to_Asia tuberculosis tuberculosis visit_to_Asia->tuberculosis tuberculos_or_cancer tuberculos_or_cancer tuberculosis->tuberculos_or_cancer positive_XraY positive_XraY tuberculos_or_cancer->positive_XraY dyspnoea dyspnoea tuberculos_or_cancer->dyspnoea lung_cancer lung_cancer lung_cancer->tuberculos_or_cancer smoking smoking smoking->lung_cancer bronchitis bronchitis smoking->bronchitis bronchitis->dyspnoea
Asia BN — 8 nodes, 8 arcs
def benchmark_bn(bn, exts):
"""Save and reload a BN in every given format, return a comparison table."""
rows = []
with tempfile.TemporaryDirectory() as d:
for ext in exts.split("|"):
fname = os.path.join(d, f"model.{ext}")
try:
t0 = time.perf_counter()
gum.saveBN(bn, fname)
t_save = time.perf_counter() - t0
size = os.path.getsize(fname)
t0 = time.perf_counter()
bn2 = gum.loadBN(fname)
t_load = time.perf_counter() - t0
names_ok = sorted(bn.names()) == sorted(bn2.names())
labels_ok = names_ok and all(
list(bn.variable(n).labels()) == list(bn2.variable(n).labels()) for n in bn.names()
)
types_ok = names_ok and all(bn.variable(n).varType() == bn2.variable(n).varType() for n in bn.names())
rows.append((ext, size, t_save * 1000, t_load * 1000, names_ok, labels_ok, types_ok))
except Exception as e:
rows.append((ext, None, None, None, False, False, str(e)[:60]))
return rows
rows = benchmark_bn(bn_asia, gum.availableBNExts())
header = (
f"{'ext':8s} {'size (B)':>9s} {'save (ms)':>10s} {'load (ms)':>10s} {'names':>5s} {'labels':>6s} {'types':>5s}"
)
print(header)
print("-" * len(header))
for ext, size, ts, tl, n_ok, l_ok, t_ok in rows:
if size is not None:
print(f"{ext:8s} {size:9d} {ts:10.3f} {tl:10.3f} {n_ok!s:>5s} {l_ok!s:>6s} {t_ok!s:>5s}")
else:
print(f"{ext:8s} (unsupported for this model)")
ext size (B) save (ms) load (ms) names labels types
-----------------------------------------------------------------
bif 1554 0.278 0.186 True True False
dsl 1872 0.129 0.113 True True False
net 2558 0.106 0.108 True True False
bifxml 3554 0.108 0.111 True True True
o3prm (unsupported for this model)
uai 430 0.100 0.064 False False False
xdsl 2264 0.354 0.079 True True False
pkl 1339 0.136 0.098 True True True
jgum 1283 0.073 0.056 True True True
bgum 808 0.070 0.050 True True True
import matplotlib.pyplot as plt
import numpy as np
exts = [r[0] for r in rows if r[1] is not None]
sizes = [r[1] for r in rows if r[1] is not None]
t_saves = [r[2] for r in rows if r[1] is not None]
t_loads = [r[3] for r in rows if r[1] is not None]
x = np.arange(len(exts))
width = 0.35
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))
ax1.bar(x, sizes, color="steelblue")
ax1.set_xticks(x)
ax1.set_xticklabels(exts, rotation=45)
ax1.set_ylabel("size (B)")
ax1.set_title("File size per format")
ax2.bar(x - width / 2, t_saves, width, label="save (ms)", color="darkorange")
ax2.bar(x + width / 2, t_loads, width, label="load (ms)", color="seagreen")
ax2.set_xticks(x)
ax2.set_xticklabels(exts, rotation=45)
ax2.set_ylabel("time (ms)")
ax2.set_title("Save / load time per format")
ax2.legend()
fig.tight_layout()

svg

Many real-world networks contain variables of heterogeneous types: labelled (LabelizedVariable), integer ranges (RangeVariable) or discretized continuous domains (DiscretizedVariable). Not all formats can represent these faithfully.

## Build a BN that mixes all main variable types
bn_mixed = gum.BayesNet("mixed_types")
bn_mixed.add(gum.LabelizedVariable("Smoker", "Smoker", ["yes", "no"]))
bn_mixed.add(gum.RangeVariable("Age", "Age", 20, 60))
bn_mixed.add(gum.DiscretizedVariable("Temp", "Temp", [36.0, 37.0, 38.5, 42.0]))
bn_mixed.add(gum.LabelizedVariable("Cancer", "Cancer", ["yes", "no"]))
bn_mixed.addArc("Smoker", "Cancer")
bn_mixed.addArc("Age", "Cancer")
bn_mixed.addArc("Temp", "Cancer")
bn_mixed.cpt("Smoker").fillWith([0.3, 0.7])
bn_mixed.cpt("Age").fillWith(1).normalize()
bn_mixed.cpt("Temp").fillWith(1).normalize()
bn_mixed.cpt("Cancer").fillWith(1).normalize()
print("Variable types in bn_mixed:")
type_names = {
gum.VarType_LABELIZED: "Labelized",
gum.VarType_DISCRETIZED: "Discretized",
gum.VarType_RANGE: "Range",
gum.VarType_INTEGER: "Integer",
gum.VarType_NUMERICAL: "Numerical",
}
for n in bn_mixed.names():
v = bn_mixed.variable(n)
print(f" {n:10s}: {type_names.get(v.varType(), f'type={v.varType()}')}")
Variable types in bn_mixed:
Smoker : Labelized
Temp : Discretized
Cancer : Labelized
Age : Range
rows = benchmark_bn(bn_mixed, gum.availableBNExts())
header = (
f"{'ext':8s} {'size (B)':>9s} {'save (ms)':>10s} {'load (ms)':>10s} {'names':>5s} {'labels':>6s} {'types':>5s}"
)
print(header)
print("-" * len(header))
for ext, size, ts, tl, n_ok, l_ok, t_ok in rows:
if size is not None:
print(f"{ext:8s} {size:9d} {ts:10.3f} {tl:10.3f} {n_ok!s:>5s} {l_ok!s:>6s} {t_ok!s:>5s}")
else:
print(f"{ext:8s} (unsupported for this model)")
ext size (B) save (ms) load (ms) names labels types
-----------------------------------------------------------------
bif (unsupported for this model)
dsl (unsupported for this model)
net (unsupported for this model)
bifxml 8951 0.301 0.208 True True True
o3prm (unsupported for this model)
uai 6703 0.220 0.263 False False False
xdsl 7882 0.737 0.185 True True False
pkl 12187 0.319 0.178 True True True
jgum 12131 0.203 0.133 True True True
bgum 5158 0.167 0.100 True True True

Observations for BN:

FormatNotes
bif, dsl, netClassic, widely used, but do not support DiscretizedVariable
bifxml / xdslXML-based; bifxml preserves types, xdsl does not
uaiCompact but loses variable names
o3prmVerbose; requires a full class hierarchy
pklPython pickle; preserves everything but not portable across pyAgrum versions
jgumNative JSON format; preserves all types, human-readable
bgumNative binary format; smallest files, fastest I/O, preserves all types

Influence diagrams have fewer supported formats than BNs.

## Classic Oil Wildcatter influence diagram
diag = gum.loadID("res/OilWildcatter.bgum")
gnb.flow.row(diag, captions=[f"Oil Wildcatter — {diag.size()} nodes"])
OilWildcatter TestResult TestResult Drilling Drilling TestResult->Drilling OilContents OilContents OilContents->TestResult Reward Reward OilContents->Reward Testing Testing Testing->TestResult Testing->Drilling Cost Cost Testing->Cost Drilling->Reward
Oil Wildcatter — 6 nodes
def benchmark_id(diag, exts):
rows = []
with tempfile.TemporaryDirectory() as d:
for ext in exts.split("|"):
fname = os.path.join(d, f"model.{ext}")
try:
t0 = time.perf_counter()
gum.saveID(diag, fname)
t_save = time.perf_counter() - t0
size = os.path.getsize(fname)
t0 = time.perf_counter()
diag2 = gum.loadID(fname)
t_load = time.perf_counter() - t0
names_ok = sorted(diag.names()) == sorted(diag2.names())
rows.append((ext, size, t_save * 1000, t_load * 1000, names_ok))
except Exception as e:
rows.append((ext, None, None, None, str(e)[:60]))
return rows
rows = benchmark_id(diag, gum.availableIDExts())
header = f"{'ext':8s} {'size (B)':>9s} {'save (ms)':>10s} {'load (ms)':>10s} {'names':>5s}"
print(header)
print("-" * len(header))
for ext, size, ts, tl, n_ok in rows:
if size is not None:
print(f"{ext:8s} {size:9d} {ts:10.3f} {tl:10.3f} {n_ok!s:>5s}")
else:
print(f"{ext:8s} (unsupported for this model)")
ext size (B) save (ms) load (ms) names
--------------------------------------------------
xmlbif 2730 0.324 0.203 True
bifxml 2730 0.141 0.097 True
xml 2730 0.100 0.073 True
jgum 751 0.107 0.073 True
bgum 711 0.089 0.049 True
pkl 828 0.108 0.073 True

Observations for InfluenceDiagram:

FormatNotes
bifxml / xmlbif / xmlThree aliases for the same XML format
pklPortable only within the same pyAgrum version
jgumCompact JSON, fully faithful, human-readable
bgumSmallest files, fastest I/O

MRFs have the smallest set of supported formats.

mrf = gum.fastMRF("A{yes|no}--B{low|mid|high}--C{yes|no}--A;B--D{yes|no}")
gnb.flow.row(mrf, captions=[f"MRF — {mrf.size()} nodes, {mrf.sizeEdges()} edges"])
anonymousMRF A A B B C C D D f#A#B#C f#A#B#C--A f#A#B#C--B f#A#B#C--C f#B#D f#B#D--B f#B#D--D
MRF — 4 nodes, 4 edges
def benchmark_mrf(mrf, exts):
rows = []
with tempfile.TemporaryDirectory() as d:
for ext in exts.split("|"):
fname = os.path.join(d, f"model.{ext}")
try:
t0 = time.perf_counter()
gum.saveMRF(mrf, fname)
t_save = time.perf_counter() - t0
size = os.path.getsize(fname)
t0 = time.perf_counter()
mrf2 = gum.loadMRF(fname)
t_load = time.perf_counter() - t0
names_ok = sorted(mrf.names()) == sorted(mrf2.names())
labels_ok = names_ok and all(
list(mrf.variable(n).labels()) == list(mrf2.variable(n).labels()) for n in mrf.names()
)
rows.append((ext, size, t_save * 1000, t_load * 1000, names_ok, labels_ok))
except Exception as e:
rows.append((ext, None, None, None, False, str(e)[:60]))
return rows
rows = benchmark_mrf(mrf, gum.availableMRFExts())
header = f"{'ext':8s} {'size (B)':>9s} {'save (ms)':>10s} {'load (ms)':>10s} {'names':>5s} {'labels':>6s}"
print(header)
print("-" * len(header))
for ext, size, ts, tl, n_ok, l_ok in rows:
if size is not None:
print(f"{ext:8s} {size:9d} {ts:10.3f} {tl:10.3f} {n_ok!s:>5s} {l_ok!s:>6s}")
else:
print(f"{ext:8s} (unsupported for this model)")
ext size (B) save (ms) load (ms) names labels
----------------------------------------------------------
uai 285 0.195 0.123 False False
jgum 675 0.125 0.101 True True
bgum 426 0.071 0.055 True True
pkl 756 0.502 0.205 True True

Observations for MRF:

FormatNotes
uaiOnly standard MRF format, but loses variable names and labels
pklPortable only within the same pyAgrum version
jgumFull fidelity, JSON, readable
bgumSmallest, fastest, full fidelity

Why bgum and jgum are the best choice for pyAgrum

Section titled “Why bgum and jgum are the best choice for pyAgrum”

The bgum and jgum formats are the native aGrUM formats, designed specifically for all model types supported by pyAgrum. They share the same advantages:

  1. Universal — same format works for BayesNet, InfluenceDiagram and MarkovRandomField.
  2. Full fidelity — all variable types (LabelizedVariable, RangeVariable, DiscretizedVariable, IntegerVariable) are preserved exactly.
  3. Fast — both I/O are among the fastest of all formats.
  4. Compact — bgum typically produces the smallest files; jgum is still compact while remaining human-readable.
  5. No external dependencies — no need for third-party parsers.

The only difference between the two is readability:

  • bgum (binary) — optimal for production workflows, automated pipelines, storing large models.
  • jgum (JSON) — easier to inspect, diff, or version-control.
## Build a BN with mixed variable types to stress-test fidelity
bn_demo = gum.BayesNet("demo")
bn_demo.add(gum.LabelizedVariable("Smoker", "Smoker", ["yes", "no"]))
bn_demo.add(gum.RangeVariable("Age", "Age", 20, 60))
bn_demo.add(gum.DiscretizedVariable("Temp", "Temp", [36.0, 37.0, 38.5, 42.0]))
bn_demo.add(gum.LabelizedVariable("Cancer", "Cancer", ["yes", "no"]))
bn_demo.addArc("Smoker", "Cancer")
bn_demo.addArc("Age", "Cancer")
bn_demo.addArc("Temp", "Cancer")
bn_demo.cpt("Smoker").fillWith([0.3, 0.7])
bn_demo.cpt("Age").fillWith(1).normalize()
bn_demo.cpt("Temp").fillWith(1).normalize()
bn_demo.cpt("Cancer").fillWith(1).normalize()
type_names = {
gum.VarType_LABELIZED: "Labelized",
gum.VarType_DISCRETIZED: "Discretized",
gum.VarType_RANGE: "Range",
gum.VarType_INTEGER: "Integer",
gum.VarType_NUMERICAL: "Numerical",
}
print("Variable types before save:")
for n in bn_demo.names():
v = bn_demo.variable(n)
print(
f" {n:8s}: {type_names.get(v.varType(), f'type={v.varType()}'):12s} labels={list(v.labels()[:4])}{'...' if v.domainSize() > 4 else ''}"
)
Variable types before save:
Smoker : Labelized labels=['yes', 'no']
Temp : Discretized labels=['[36;37[', '[37;38.5[', '[38.5;42]']
Cancer : Labelized labels=['yes', 'no']
Age : Range labels=['20', '21', '22', '23']...
with tempfile.TemporaryDirectory() as d:
for ext in ("bgum", "jgum"):
fname = os.path.join(d, f"demo.{ext}")
gum.saveBN(bn_demo, fname)
bn2 = gum.loadBN(fname)
print(f"\n--- {ext} ({os.path.getsize(fname)} bytes) ---")
for n in bn2.names():
v = bn2.variable(n)
print(
f" {n:8s}: {type_names.get(v.varType(), f'type={v.varType()}'):12s} labels={list(v.labels()[:4])}{'...' if v.domainSize() > 4 else ''}"
)
--- bgum (5151 bytes) ---
Smoker : Labelized labels=['yes', 'no']
Temp : Discretized labels=['[36;37[', '[37;38.5[', '[38.5;42]']
Cancer : Labelized labels=['yes', 'no']
Age : Range labels=['20', '21', '22', '23']...
--- jgum (12124 bytes) ---
Smoker : Labelized labels=['yes', 'no']
Temp : Discretized labels=['[36;37[', '[37;38.5[', '[38.5;42]']
Cancer : Labelized labels=['yes', 'no']
Age : Range labels=['20', '21', '22', '23']...
## jgum is plain JSON — easy to inspect
import json
with tempfile.TemporaryDirectory() as d:
fname = os.path.join(d, "demo.jgum")
gum.saveBN(bn_demo, fname)
with open(fname) as f:
data = json.load(f)
# Show just the variable descriptions
print(json.dumps(data.get("variables", data.get("nodes", {})), indent=2))
[
"Smoker{yes|no}",
"Age[20,60]",
"Temp[36,37,38.5,42]",
"Cancer{yes|no}"
]

bgum and jgum work identically for all model types

Section titled “bgum and jgum work identically for all model types”
with tempfile.TemporaryDirectory() as d:
# BayesNet
gum.saveBN(bn_asia, os.path.join(d, "asia.bgum"))
bn_rt = gum.loadBN(os.path.join(d, "asia.bgum"))
print(f"BN round-trip via bgum: names match = {sorted(bn_asia.names()) == sorted(bn_rt.names())}")
# InfluenceDiagram
gum.saveID(diag, os.path.join(d, "oil.bgum"))
diag_rt = gum.loadID(os.path.join(d, "oil.bgum"))
print(f"ID round-trip via bgum: names match = {sorted(diag.names()) == sorted(diag_rt.names())}")
# MarkovRandomField
gum.saveMRF(mrf, os.path.join(d, "mrf.bgum"))
mrf_rt = gum.loadMRF(os.path.join(d, "mrf.bgum"))
print(f"MRF round-trip via bgum: names match = {sorted(mrf.names()) == sorted(mrf_rt.names())}")
BN round-trip via bgum: names match = True
ID round-trip via bgum: names match = True
MRF round-trip via bgum: names match = True
bif/dsl/netbifxml/xdsluaipkljgumbgum
BayesNet✓✓partial✓✓✓
InfluenceDiagram✗✓✗✓✓✓
MarkovRandomField✗✗partial✓✓✓
Preserves all variable types✗partial✗✓✓✓
Preserves variable names✓✓✗✓✓✓
Human-readable✓✓✓✗✓✗
Compact sizemediumlargesmallmediumsmallsmallest
I/O speedmediummediumfastfastfastfastest
Version-stable✓✓✓✗✓✓

Recommendation:

  • Use bgum whenever storage size or I/O speed matters, or when working with non-BN models.
  • Use jgum when the file needs to be inspected, diffed, or stored in version control.
  • Use bif/bifxml only when interoperability with other tools (GeNIe, Netica, …) is required.
import matplotlib.pyplot as plt
columns = ["", "bif/dsl/net", "bifxml/xdsl", "uai", "pkl", "jgum", "bgum"]
rows = [
["BayesNet", "✓", "✓", "partial", "✓", "✓", "✓"],
["InfluenceDiagram", "✗", "✓", "✗", "✓", "✓", "✓"],
["MarkovRandomField", "✗", "✗", "partial", "✓", "✓", "✓"],
["Preserves all variable types", "✗", "partial", "✗", "✓", "✓", "✓"],
["Preserves variable names", "✓", "✓", "✗", "✓", "✓", "✓"],
["Human-readable", "✓", "✓", "NA", "NA", "✓", "NA"],
["Compact size", "medium", "large", "small", "medium", "small", "smallest"],
["I/O speed", "medium", "medium", "fast", "fast", "fast", "fastest"],
["Version-stable", "✓", "✓", "✓", "✗", "✓", "✓"],
]
RED = "#f5c6c6" # same as crosses
ORANGE = "#fde0b3" # same as partial
LIGHTGREEN = "#dff0d8" # same as check (jgum/bgum columns)
FRANCEGREEN = "#00b140" # smallest/fastest
SIZE_SPEED_COLORS = {
"large": RED,
"medium": ORANGE,
"small": LIGHTGREEN,
"fast": LIGHTGREEN,
"smallest": FRANCEGREEN,
"fastest": FRANCEGREEN,
}
fig, ax = plt.subplots(figsize=(9, 3.6))
ax.axis("off")
ax.set_title("I/O Summary", fontsize=14, fontweight="bold", pad=12)
table = ax.table(cellText=rows, colLabels=columns, cellLoc="center", loc="center")
table.auto_set_font_size(False)
table.set_fontsize(9)
table.scale(1, 1.4)
table.auto_set_column_width(col=list(range(len(columns))))
green_cols = {5, 6} # jgum, bgum: always green, whatever the value
for (row, col), cell in table.get_celld().items():
if row == 0:
cell.set_facecolor("#404040")
cell.set_text_props(color="white", fontweight="bold")
continue
if col == 0:
cell.set_text_props(ha="left")
continue
label = rows[row - 1][0]
value = rows[row - 1][col]
if label in ("Compact size", "I/O speed"):
cell.set_facecolor(SIZE_SPEED_COLORS[value])
elif col in green_cols:
cell.set_facecolor(LIGHTGREEN)
elif value == "✗":
cell.set_facecolor(RED)
elif value == "partial":
cell.set_facecolor(ORANGE)
elif value == "NA":
pass
fig.tight_layout()
plt.show()

svg