How it works
Pipeline overview
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ DataSource │────►│ align_to_grid() │────►│ discretize() │────►│ BN inference │
│ (per node) │ │ reproject + resample │ continuous → │ │ VariableElim. │
└──────────────┘ │ to reference grid│ │ BN states │ │ batched queries │
└──────────────────┘ └──────────────┘ └──────────┬───────┘
│
┌──────────▼───────┐
│ InferenceResult │
│ (H, W, n_states) │
│ + entropy map │
└──────────────────┘
Loading a Bayesian network
geobn.load() picks a reader from the file extension:
| Extension | Format | Typically written by |
|---|---|---|
.bif |
BIF (Bayesian Interchange Format) | bnlearn, most exporters |
.xmlbif |
XMLBIF | Weka, JavaBayes |
.net |
Hugin NET | Hugin, GeNIe |
.xdsl |
GeNIe XDSL | GeNIe / SMILE |
.uai |
UAI | UAI competition files |
.xml |
sniffed from the root element | see below |
All readers ship with pgmpy, so no extra dependency is needed. Files are decoded as UTF-8, falling back to the platform default encoding.
A bare .xml file is resolved from its root element: <BIF> is read as XMLBIF,
<smile> as GeNIe XDSL and <ANALYSISNOTEBOOK> as Microsoft XBN. Any other root
element raises ValueError.
load() also runs pgmpy's check_model(), so a truncated file or a CPT whose columns
do not sum to 1 fails at load time rather than deep inside infer().
UAI files carry no names
The UAI format stores no variable or state names, so nodes come back as var_0,
var_1, … and states as integers, in file order. geobn.load() emits a
UserWarning and set_input() / set_discretization() must use those names.
Netica .dne
Not supported — pgmpy has no Netica reader. Export to .net or .bif from Netica.
Using a pgmpy model directly
GeoBayesianNetwork accepts any pgmpy DiscreteBayesianNetwork, so a model built in
code, fitted with a pgmpy estimator, or read with a reader load() does not dispatch on
can be used without going through a file:
from pgmpy.readwrite import XBNReader
bn = geobn.GeoBayesianNetwork(XBNReader("model.dat").get_model())
Unlike load(), this does not run check_model().
Attaching data sources
Any node in the BN can be an evidence variable. Usually these are the root nodes (no
parents), but an intermediate or leaf node can be observed just as well. Attach a
DataSource to each one:
bn.set_input("slope_angle", geobn.WCSSource(url="https://example.com/wcs", layer="dtm"))
bn.set_input("recent_snow", geobn.ConstantSource(30.0))
At inference time, geobn inspects all registered georeferenced sources and selects the
one with the finest resolution as the reference grid (CRS, resolution, extent).
Pixel sizes are compared in metres on the ground (measured at each grid's centre), so a
10 m UTM raster correctly beats a 0.001° WGS84 raster even though 0.001 < 10 in CRS units. All other sources are reprojected to this grid
automatically. To override this behaviour, call bn.set_grid(crs, resolution, extent)
explicitly before running inference.
Evidence on intermediate nodes
Evidence is not limited to the nodes at the top of the network. A source attached to an intermediate or leaf node observes that node, and the evidence flows in both directions: down to its descendants and up to its parents. A dataset that measures an intermediate concept directly can therefore be used in place of the layers behind it.
In the bundled Lyngen model, terrain_factor is an intermediate node with parents
slope_angle, sun_exposure and forest_cover. Observing it and querying a parent
gives a distribution over slope classes:
bn = geobn.load("avalanche_risk.bif")
bn.set_input("terrain_factor", geobn.RasterSource("terrain_class.tif"))
bn.set_discretization("terrain_factor", [0, 1, 2, 3], ["low", "medium", "high"])
result = bn.infer(query=["slope_angle"]) # P(slope | observed terrain)
slope_angle has a uniform prior in that model, so the observation shifts it
substantially:
| observed | flat | gentle | steep | extreme |
|---|---|---|---|---|
| (prior) | 0.250 | 0.250 | 0.250 | 0.250 |
terrain_factor="low" |
0.422 | 0.375 | 0.123 | 0.081 |
terrain_factor="high" |
0.006 | 0.039 | 0.372 | 0.583 |
This is ordinary Bayesian inference read in the less common direction, and its accuracy depends entirely on the CPD being inverted. It is useful for filling gaps and for cross-checking one layer against another, and it yields a distribution over states rather than a measured value.
Root inputs are marginally independent, so any combination of them is possible. Inputs
on nodes with parents are not: observing a node together with its parent in a
combination the CPD gives probability zero leaves the posterior undefined. Those pixels
become NaN with a UserWarning, as with any other impossible evidence (see below).
A node cannot be both an input and a query node. infer(), precompute() and
load_precomputed() raise ValueError naming it, before any data is fetched.
GridSpec and alignment
The reference grid is described by a GridSpec(crs, transform, shape). Every source is
reprojected and resampled onto it with numpy and pyproj; rasterio is not involved.
How a source is resampled is set per source with resampling=:
| Method | Value of a grid pixel | Typical use |
|---|---|---|
"bilinear" (default) |
Interpolated from the four source pixels around its centre | Continuous data at a similar or coarser resolution than the grid |
"nearest" |
The source pixel under its centre | Class rasters |
"mode" |
The most frequent source value within it (ties: smallest value) | Class rasters finer than the grid, e.g. land cover or seabed type |
"average" |
The mean of the source pixels within it | Continuous data finer than the grid |
"min" / "max" |
The minimum / maximum of the source pixels within it | Hazard layers finer than the grid |
bn.set_input("land_cover", geobn.RasterSource("landcover_10m.tif", resampling="mode"))
bn.set_input("slope", geobn.RasterSource("slope_1m.tif", resampling="max"))
Bilinear interpolation of a class raster produces codes that are not classes, such as 1.5
between classes 1 and 2, which are then discretized as if they were real values. Bilinear
interpolation also samples a source finer than the grid at one point per grid pixel, so a
narrow feature such as a steep gully or a shallow shoal can fall between the samples and
vanish. "max" or "min" keeps it.
The aggregating methods ("mode", "average", "min", "max") ignore NaN, so a grid
pixel is NaN only when none of its source pixels has data. Where the source is coarser
than the grid, each grid pixel lies within one source pixel and these methods give the
same result as "nearest". They visit the source pixels by sampling each grid pixel on a
regular lattice spaced at most one source pixel apart, capped at 64 × 64 samples per grid
pixel. A source already on the grid and a source without a CRS are used as they are, whatever
the method.
ConstantSource is a special case: it returns a 1×1 sentinel array with crs=None,
which align_to_grid() recognises and broadcasts to the full grid shape.
Derived inputs
An input can be computed from other sources with DerivedSource(fn, *sources). The
sources are aligned to the reference grid, and fn is called with the aligned arrays:
dem = geobn.WCSSource(url, layer="dtm", cache_dir="cache/")
bn.set_input("slope_angle", geobn.terrain.slope(dem))
bn.set_input("forest_cover", geobn.DerivedSource(lambda z: np.where(z < 400, 2.0, 0.0), dem))
geobn.terrain provides slope, aspect, roughness and tpi, each returning a
DerivedSource. Slope and aspect are computed from the ground distance between pixel
centres on the WGS84 ellipsoid, so they are correct on grids in degrees as well as in
metres, and aspect is measured from true north. Next to a NaN pixel the derivative is a
one-sided difference, so the edge of the data does not show up as a cliff.
A derived source is fetched like any other, when infer() or fetch_raw() needs it, and
can be frozen. Because the derivation runs on the reference grid, derivatives such as
slope describe the terrain at the grid's resolution.
Discretization
Bayesian networks operate on discrete states. Every continuous evidence source must be
mapped to BN state names via set_discretization():
bn.set_discretization(
"slope_angle",
breakpoints=[0, 25, 40, 90], # bin edges
labels=["gentle", "steep", "extreme"], # must match BN state names exactly
)
breakpoints must have len(labels) + 1 values. The interior values are the bin
edges; a value exactly on an edge goes to the upper bin.
The first and last breakpoints define the valid range [breakpoints[0], breakpoints[-1]]
(inclusive). By default (out_of_range="clip"), values outside it are assigned to the
first or last state, so a slope of 95° counts as "extreme". Pass
out_of_range="nan" to treat them as NoData instead:
bn.set_discretization(
"slope_angle",
breakpoints=[0, 25, 40, 90],
labels=["gentle", "steep", "extreme"],
out_of_range="nan", # values < 0 or > 90 → NaN output
)
This is useful when out-of-range values mean bad data (sensor errors, fill values) rather than extreme conditions.
Breakpoints from the data
geobn.breakpoints computes a breakpoint list from an array, for the two standard
classification schemes:
arr = bn.fetch_raw(geobn.RasterSource("slope.tif"))
geobn.breakpoints.quantile(arr, 3) # bins with equal pixel counts
geobn.breakpoints.equal_interval(arr, 3) # bins of equal width
bn.suggest_breakpoints(node) does the same for a node that already has a source,
taking the bin count from the node's states in the BN:
bn.set_input("slope_angle", geobn.RasterSource("slope.tif"))
bn.set_discretization("slope_angle", bn.suggest_breakpoints("slope_angle"))
The outer breakpoints are the data's minimum and maximum, which makes them the valid
range as well. Pass bounds= to pin a node's physical range instead, so later data
beyond the values at hand is still in range:
Breakpoints computed this way describe the data they were computed from. They fit the case where a model's conditional probabilities are authored alongside its breakpoints; a CPT elicited against fixed thresholds — "steep means over 30°" — needs those thresholds.
NaN / NoData propagation
An input that is NaN at a pixel has no state there. A query node is NaN at that pixel if the missing input can affect it, that is, if the input is d-connected to the query node given the inputs that do have data at the pixel. Query nodes the missing input cannot affect are computed from the other inputs, and their posterior is the same as if the input had been observed.
Take a network with slope → avalanche_risk and water_depth → grounding_risk. Where
water_depth is NaN, grounding_risk is NaN and avalanche_risk is computed from
slope as usual. Where an input feeds both query nodes, both are NaN.
Whether a missing input can affect a query node depends on which other inputs are
observed. In X → M → Q with M observed, a missing X leaves Q unaffected; with
M missing too, Q is NaN. The check reads the network's structure only, so an input
whose effect happens to cancel out in the conditional probability tables still counts
as able to affect the query node. A missing input is never replaced by its prior;
the query nodes it can affect are NaN.
NaN inputs come from:
- Pixels outside WCS coverage
- Sea pixels in a land DEM
- Invalid sensor readings
- Values outside the breakpoint range with out_of_range="nan"
- File nodata: RasterSource, URLSource and WCSSource automatically convert
pixels matching the GeoTIFF's declared nodata value (or its internal mask) to NaN
If the observed inputs at a pixel have probability zero under the model, every query
node that is not already NaN because of a missing input is NaN too, with a
UserWarning (see below).
An ArraySource without crs/transform must either match the grid shape exactly
(pre-aligned) or be a single value; any other shape raises ValueError rather than
being silently broadcast.
Inference batching
Running one pgmpy VariableElimination.query() per pixel is prohibitively slow for
large rasters, so geobn never queries per pixel. Instead, inference proceeds in two
steps: first measure how much distinct evidence the map actually contains, then
choose the cheapest strategy for that amount.
Step 1 — group pixels by observed evidence combination
After discretization, every pixel is described by one state index per evidence node
— e.g. (slope=steep, rainfall=high). geobn groups all valid pixels by these
combinations and counts how many distinct combinations actually occur on the map.
This count is the key quantity, and it is usually far smaller than the number of theoretically possible combinations:
- It can never exceed the number of valid pixels.
- Geography is spatially correlated — neighbouring pixels tend to share the same slope class, forest class, etc.
- Scalar inputs (
ConstantSource, live weather values) contribute exactly one state each, collapsing the combination count further.
A network with millions of possible combinations may still produce only a few dozen observed ones, and geobn's strategy choice is driven entirely by the observed count — the size of the theoretical state space costs nothing by itself.
Step 2 — choose a strategy
Few observed combinations (≤ 200): per-combination queries. pgmpy
VariableElimination queries run per observed combination. For a 500×500 grid with
3 evidence nodes (3 states each) there are at most 27 combinations regardless of grid
size — a handful of targeted queries is the cheapest possible approach.
Within one combination, how the query nodes are requested depends on the size of their joint table (the product of their state counts). pgmpy computes the full joint over all requested nodes before splitting it into per-node marginals, so:
- Small joint (≤ 20,000 cells): all query nodes in one pgmpy call, which shares the elimination work (up to ~3× faster than separate calls).
- Large joint: one pgmpy call per query node. The joint grows multiplicatively with every query node — 19 query nodes with 2–5 states each is 192 million cells — while separate calls grow linearly (10 s vs 32 ms per combination in that case).
Many observed combinations: one joint query. Asking thousands of nearly identical questions repeats the same internal propagation work each time. Instead, geobn asks pgmpy a single bigger question: the joint distribution P(query, e₁, …, eₖ) with no evidence at all. Normalising that array along the query axis converts it into the full conditional table P(query | e₁, …, eₖ) — the answer for every combination at once:
Per-pixel results are then read from the table by numpy fancy indexing. This keeps networks with many evidence nodes tractable: 10 nodes × 3 states (59,049 combinations) resolves in well under a second, where the per-combination loop would take minutes.
Safety valve: the joint table's size is the product of all evidence state counts × the query state count. If that exceeds an in-memory bound (~80 MB), the joint strategy is skipped and the per-combination loop is used — slower, but it only ever pays for combinations that actually occur.
Summary of regimes
| Observed combos | Table fits in memory? | Strategy | Cost |
|---|---|---|---|
| ≤ 200 | (irrelevant) | per-combination queries | milliseconds |
| many | yes | single joint query + table lookup | ~constant, sub-second |
| many | no | per-combination queries | proportional to observed combos |
In all cases the per-combination results are scattered back to the original pixel positions.
Pixels with NaN inputs are grouped by which inputs are missing, and each group goes through the same steps with its observed inputs as the evidence. With a precomputed table, a query node the missing inputs cannot affect has the same posterior in every table row over their states, so geobn reads it from the first row that is defined.
Impossible evidence. When an evidence combination has probability zero (e.g. an
input observed in a state whose prior is 0), the posterior is undefined and every
query node gets NaN, on every path. pgmpy on its own would still return numbers for
query nodes it can prune away from the contradiction, so geobn checks P(evidence)
explicitly: the product of the priors for root inputs, and the chain rule
P(e₁)·P(e₂ | e₁)·… for any other evidence. infer() and query_batch() also emit a
UserWarning naming the observed states with prior 0 and the number of affected
pixels or points, since a zero prior on an input is often a modelling slip.
Output
InferenceResult holds:
probabilities— dict mapping each query node to a(H, W, n_states)float32 arraystate_names— ordered state labels per query nodecrs,transform— spatial metadata for the output grid
From an InferenceResult you can:
result.entropy("node")— Shannon entropy map (bits), shape (H, W)- summary maps:
expected_value,std,mode,mode_probability,exceedance,ignorance,quantile(see InferenceResult) result.to_geotiff("out/", layers={...})— write multi-band GeoTIFFs, plus optional extra layersresult.to_xarray(layers={...})— return an xarray Datasetresult.show_map()— interactive Leaflet map
Real-time / repeated inference
When running inference repeatedly (e.g. updating weather forecasts while terrain stays fixed), geobn provides two optimisation tiers:
Tier 1 — bn.freeze(*nodes): marks nodes as static. The discrete index array
is computed once on the first infer() call and cached for all subsequent calls.
The pgmpy VariableElimination object is also cached.
Tier 2 — bn.precompute(query): solves all ∏ n_states combinations once (via a
single joint query per query node) and stores a numpy lookup table. Subsequent
infer() calls use O(H×W) fancy indexing — zero pgmpy queries per call. Best for
real-time dashboards with a fixed BN structure.
Call bn.clear_cache() to reset all caches if inputs change.