Skip to content

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
bn = geobn.load("my_model.bif")
bn = geobn.load("my_model.xdsl")   # same call, GeNIe file

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:

bn.suggest_breakpoints("slope_angle", bounds=(0, 90))

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:

P(query | e₁, …, eₖ) = P(query, e₁, …, eₖ) / P(e₁, …, eₖ)

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 array
  • state_names — ordered state labels per query node
  • crs, 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 layers
  • result.to_xarray(layers={...}) — return an xarray Dataset
  • result.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.