Skip to content

Breakpoints

Helpers that compute the breakpoint list set_discretization() takes, from the data itself:

arr = bn.fetch_raw(geobn.RasterSource("slope.tif"))
bn.set_discretization("slope_angle", geobn.breakpoints.quantile(arr, 4))

For a node that already has a source registered, bn.suggest_breakpoints() does the fetch and takes the bin count from the BN:

bn.set_input("slope_angle", geobn.RasterSource("slope.tif"))
bn.set_discretization("slope_angle", bn.suggest_breakpoints("slope_angle"))

Both schemes return n + 1 ascending edges. The interior values are the bin edges; the outer pair defines the valid range [first, last], so pass bounds= to pin a node's physical range when later data may go beyond the values at hand.

Choosing a scheme

quantile equal_interval
Edges from the distribution the range
Bin occupancy roughly equal whatever the data gives
Bin width varies constant
Suits skewed data, where equal-width bins would leave states empty data spread evenly across its range, or thresholds that should read as round numbers

Breakpoints computed from data 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 needs those thresholds instead.

Function reference

quantile

quantile(values, n, *, bounds=None)

Breakpoints that put roughly the same number of values in each bin.

The interior edges are the n-quantiles of the data, so no state is left empty. On skewed data the bins have very different widths, which is the price of even occupancy.

Parameters

values: Array of any shape. It is flattened, and NaN and infinite values are ignored, so a raster's NoData pixels need no special handling. n: Number of bins, i.e. the number of BN states for the node. The returned list has n + 1 entries. bounds: (lo, hi) for the outer breakpoints, which define the valid range [lo, hi] (see :meth:~geobn.GeoBayesianNetwork.set_discretization). Either side may be None to take that side from the data, and the default None takes both. Pass a node's physical range — bounds=(0, 90) for a slope in degrees — when later data may go beyond the values at hand. (-inf, inf) leaves the range unbounded, so nothing is ever out of range.

Returns

list of float n + 1 strictly increasing breakpoints.

Raises

ValueError If n is not a positive integer, values holds no finite value, bounds is malformed, an interior edge falls outside bounds, or the data is too concentrated to form n bins.

Example

quantile([0, 1, 2, 3, 4, 5, 6, 7], 4) [0.0, 1.75, 3.5, 5.25, 7.0]

equal_interval

equal_interval(values, n, *, bounds=None)

Breakpoints that split the range into bins of equal width.

The edges are round and easy to read, and they describe the range rather than the distribution: on skewed data most values can land in one bin while the others stay nearly empty.

Parameters

values: Array of any shape. It is flattened, and NaN and infinite values are ignored, so a raster's NoData pixels need no special handling. n: Number of bins, i.e. the number of BN states for the node. The returned list has n + 1 entries. bounds: (lo, hi) for the outer breakpoints, which define both the span that is divided and the valid range [lo, hi]. Either side may be None to take that side from the data, and the default None takes both. Both bounds must be finite, because bins of equal width over an infinite span are undefined; :func:quantile accepts infinite bounds.

Returns

list of float n + 1 strictly increasing, evenly spaced breakpoints.

Raises

ValueError If n is not a positive integer, values holds no finite value, bounds is malformed or infinite, or the span is too narrow to form n bins.

Example

equal_interval([0, 1, 2, 3, 4, 5, 6, 7], 4) [0.0, 1.75, 3.5, 5.25, 7.0]