geoml.data.inducing

Building the inducing points a latent network is given.

latent.BasicInput takes either one PointData of inducing points or a list of them, one per expert, and until now both had to be assembled by hand. The functions here produce them:

from_kmeans(data, n) one set, at the k-means centroids of the data from_grid(data, step) one set, on a regular lattice from_hull(data, step, d) one set, on a lattice kept where the data reach combine(a, b, …) one set out of several, duplicates dropped grid_experts(data, step) a list of sets, laid out as overlapping blocks experts(points, n_experts) a list of sets, from overlapping clusters

The two *_experts functions divide a set of inducing points among experts so that neighbouring ones overlap, which is what keeps a prediction from showing a seam where the experts meet. They differ only in how the division is made. grid_experts cuts space into regular blocks and extends each by one step, so every expert is the same size and its neighbours are known in advance – the Moore neighbourhood, 8 in the plane and 26 in space. experts is the unordered counterpart: it clusters whatever points it is given into compact clusters of about the same size and lends each the points nearest its own, which suits a survey that does not fill its bounding box, such as drillholes or a shoreline.

experts takes inducing points rather than data, so the usual way to build an irregular network is to choose the points first and then divide them:

sets = experts(from_kmeans(data, 1500), 12)

geoml.data.inducing.from_kmeans(data, n, seed=None)

Inducing points at the k-means centroids of the data.

The centroids follow the data’s density: many inducing points where the samples are crowded, few where they are sparse, which is where a sparse GP needs them. Deterministic for a given seed.

Parameters:

• data (_SpatialData | ArrayLike) – A spatial container, or an (n_data, n_dim) array of coordinates.

• n (int) – Number of inducing points. Must not exceed the number of data points.

• seed (int | None) – Passed to sklearn.cluster.KMeans for a reproducible result. This is separate from geoml.set_seed(), which governs the model’s parameter initialization.

Returns:

geoml.data.PointData – n points, in no particular order.

Return type:

PointData

geoml.data.inducing.from_grid(data, step)

Inducing points on a regular lattice covering the data.

Evenly spread whatever the data’s density, so the model has something to say away from the samples too. Often combined with from_kmeans, through combine.

Parameters:

• data (_SpatialData | ArrayLike) – A spatial container, or an (n_data, n_dim) array of coordinates.

• step (float | ArrayLike) – Spacing between neighbouring inducing points, one value per dimension or a single value for all of them.

Returns:

geoml.data.PointData – The lattice nodes, the first axis varying slowest.

Return type:

PointData

geoml.data.inducing.from_hull(data, step, distance)

Inducing points on a regular lattice, kept where the data reach.

The lattice of from_grid, extended by distance beyond the data’s box, loses the nodes the data say nothing about: every node inside the data’s convex hull stays, and a node outside it stays only within distance of a sample. A survey that does not fill its box – a fan of drillholes, a shoreline – keeps an even backbone where it is, and a margin of distance around it, without the nodes in the empty corners.

Parameters:

• data (_SpatialData | ArrayLike) – A spatial container, or an (n_data, n_dim) array of coordinates.

• step (float | ArrayLike) – Spacing between neighbouring nodes, one value per dimension or a single value for all of them.

• distance (float) – How far outside the convex hull a node may lie from the nearest sample and stay. Zero keeps the hull alone. Data that enclose no volume – every sample on one plane in space, say – have nothing inside, and the distance alone decides.

Returns:

geoml.data.PointData – The nodes kept, the first axis varying slowest.

Return type:

PointData

See also

from_grid

the whole lattice over the data’s box.

geoml.data.inducing.combine(*sources, tolerance=0.0)

One inducing point set out of several, dropping duplicates.

Useful for the usual mixture of a regular backbone and the data’s own locations, combine(from_grid(data, 50), from_kmeans(data, 200)).

Parameters:

• sources (_SpatialData | ArrayLike) – Spatial containers or coordinate arrays, all of the same dimension.

• tolerance (float) – Points closer than this to one already kept are dropped. The default of zero removes only exact repeats.

Returns:

geoml.data.PointData

Return type:

PointData

geoml.data.inducing.grid_experts(data, step, block=4)

Experts laid out as overlapping blocks of a regular lattice.

The space is cut into blocks of block inducing points per side, and each expert takes its own block plus one node of margin all around, so neighbouring experts overlap by one step. Two things follow from that layout, and both matter to the model:

• every expert holds exactly (block + 2) ** n_dim inducing points, so the per-expert state is rectangular;

• an expert’s neighbours are known from the block indices rather than measured – the Moore neighbourhood, 8 in the plane and 26 in space.

Parameters:

• data (_SpatialData | ArrayLike) – A spatial container, or an (n_data, n_dim) array of coordinates.

• step (float | ArrayLike) – Spacing between neighbouring inducing points.

• block (int) – Inducing points per block side, before the margin is added.

Returns:

list of geoml.data.PointData – One set per expert, ordered with the first axis varying slowest.

Return type:

list[PointData]

geoml.data.inducing.experts(points, n_experts, overlap=0.1, seed=None, balance=0.1)

Experts from overlapping clusters of an unstructured point set.

The unordered counterpart to grid_experts, for inducing points that follow the data rather than a lattice. The points are split into compact clusters of about the same size – k-means whose assignment keeps every cluster within balance of the mean size, solved for all the points at once, so that clusters trade points rather than fill up – and each cluster then borrows up to overlap of its own count, rounded up, from its neighbours evenly: one point from each neighbour a round, that neighbour’s nearest to any of its own members, so a cluster with many neighbours spreads its overlap over all of them. A borrowed point keeps its own cluster too, so neighbouring experts come to share the points between them — which is what stops a prediction showing a seam where one expert gives way to the next, and is the irregular equivalent of the one step of margin grid_experts adds to each block. An expert reaches every neighbour once its overlap is at least its number of neighbours, which asks for experts that are not too small.

Counting the overlap in points rather than in distance is what keeps the experts the same size. Growing each cluster by a radius instead lets a cluster in a crowded part of the survey swallow far more than one out on its own, and the experts come out wildly uneven.

Since this divides inducing points rather than data, the usual call is experts(from_kmeans(data, 1500), 12).

Parameters:

• points (_SpatialData | ArrayLike) – The inducing points to divide: a spatial container, or an (n_points, n_dim) array.

• n_experts (int) – Number of experts. Must not exceed the number of points.

• overlap (float) – How many points each expert borrows from its neighbours, as a fraction of its own count, rounded up, so an expert ends up with about 1 + overlap times the points its cluster holds. Zero leaves the experts a strict partition, sharing nothing.

• seed (int | None) – Passed to sklearn.cluster.KMeans for a reproducible result.

• balance (float) – How far a cluster’s size may stray from n_points / n_experts, as a fraction of it: the room the clusters have to trade points for compactness. Zero makes them all the same size, within one point.

Returns:

list of geoml.data.PointData – One set per expert: its own cluster, plus what it borrowed.

Return type:

list[PointData]