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 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 and grows each cluster by a fraction of its own Mahalanobis radius, 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.

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.

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.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)

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 clusters of about the same size, and each cluster then borrows a further overlap of its own count from its surroundings: the points nearest its centre, in Mahalanobis distance, among those belonging to other clusters. 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.

Counting the overlap in points rather than in distance is what keeps the experts the same size. Growing each cluster’s Mahalanobis 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, 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.

Returns:

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

Return type:

list[PointData]