metric

Metric Function Handling

MuyGPyS includes predefined metric functions with convenience functions for interacting with the rest of the library.

MuyGPyS.gp.deformation.metric.F2 = <MuyGPyS.gp.deformation.metric.MetricFn object>

F2 or squared Euclidean metric function.

Computes the Euclidean distance between points:

\[d_{F_2}(\mathbf{x}, \mathbf{y}) = \sum_{i=1}^n (x_i - y_i)^2\]

Parameters:: dists – A difference tensor of shape (..., feature_count).
Returns:: A distance tensor of shape (...).

class MuyGPyS.gp.deformation.metric.MetricFn(differences_metric_fn, crosswise_differences_fn, pairwise_diffferences_fn, apply_length_scale_fn)[source]

Metric functor class.

MuyGPyS-compatible metric functions are objects of this class. Creating a new metric function is as simple as instantiating a new MetricFn object with the desired behavior.

Parameters:

differences_metric_fn (Callable) – A Callable taking an ndarray of feature-wise dimensional comparisons with shape (..., feature_count) that collapses the last dimension into scalar distances.
crosswise_distances_fn – A Callable of signature (data, nn_data, data_indices, nn_indices) -> distances that produces a crosswise distance tensor between data and their nearest neighbors.
crosswise_differences_fn (Callable) – A Callable of signature (data, nn_data, data_indices, nn_indices) -> differences that produces a feature dimension-wise crosswise differences tensor between data and their nearest neighbors.
pairwise_distances_fn – A Callable of signature (data, nn_indices) -> distances that produces a pairwise distance tensor among sets of nearest neighbors.
pairwise_differences_fn – A Callable of signature (data, nn_data) -> differences that produces a feature dimension-wise pairwise differences tensor among sets of nearest neighbors.
apply_length_scale_fn (Callable) – A Callable of signature (dists) -> dists that applies a length scale parameter appropriately to a distances tensor.

apply_length_scale(dists, length_scale)[source]

Compute a pairwise distance tensor among sets of nearest neighbors.

Takes a full dataset of records of interest data and produces the pairwise distances between the elements indicated by each row of nn_indices.

Parameters:: dists (ndarray) – A distance tensor of any shape.
Return type:: ndarray
Returns:: A tensor of the same shape that has been element-wise scaled by the provided length scale as befits the metric.

crosswise_differences(data, nn_data, data_indices, nn_indices, **kwargs)[source]

Compute a crosswise difference tensor between data and their nearest neighbors.

Takes full datasets of records of interest data and neighbor candidates nn_data and produces a difference vector between each element of data indicated by data_indices and each of the nearest neighbors in nn_data as indicated by the corresponding rows of nn_indices. data and nn_data can refer to the same dataset.

Parameters:

data (ndarray) – The data matrix of shape (data_count, feature_count) containing batch elements.
nn_data (ndarray) – The data matrix of shape (candidate_count, feature_count) containing the universe of candidate neighbors for the batch elements. Might be the same as data.
indices – An integral vector of shape (batch_count,) containing the indices of the batch.
nn_indices (ndarray) – An integral matrix of shape (batch_count, nn_count) listing the nearest neighbor indices for the batch of data points.

Return type:

ndarray

Returns:

A tensor of shape (batch_count, nn_count, feature_count) whose last two dimensions indicate difference vectors between the feature dimensions of each batch element and those of its nearest neighbors.

crosswise_distances(data, nn_data, data_indices, nn_indices, **kwargs)[source]

Compute a crosswise distance tensor between data and their nearest neighbors.

Takes full datasets of records of interest data and neighbor candidates nn_data and produces a scalar distance between each element of data indicated by data_indices and each of the nearest neighbors in nn_data as indicated by the corresponding rows of nn_indices. data and nn_data can refer to the same dataset.

Parameters:

data (ndarray) – The data matrix of shape (data_count, feature_count) containing batch elements.
nn_data (ndarray) – The data matrix of shape (candidate_count, feature_count) containing the universe of candidate neighbors for the batch elements. Might be the same as data.
indices – An integral vector of shape (batch_count,) containing the indices of the batch.
nn_indices (ndarray) – An integral matrix of shape (batch_count, nn_count) listing the nearest neighbor indices for the batch of data points.

Return type:

ndarray

Returns:

A tensor of shape (batch_count, nn_count) whose second dimension indicates distance vectors between each batch element and its nearest neighbors.

pairwise_differences(data, nn_indices, **kwargs)[source]

Compute a pairwise difference tensor among sets of nearest neighbors.

Takes a full dataset of records of interest data and produces the pairwise differences for each feature dimension between the elements indicated by each row of nn_indices.

Parameters:

data (ndarray) – The data matrix of shape (batch_count, feature_count) containing batch elements.
nn_indices (ndarray) – An integral matrix of shape (batch_count, nn_count) listing the nearest neighbor indices for the batch of data points.

Return type:

ndarray

Returns:

A tensor of shape (batch_count, nn_count, nn_count, feature_count) containing the (nn_count, nn_count, feature_count)-shaped pairwise nearest neighbor difference tensors corresponding to each of the batch elements.

pairwise_distances(data, nn_indices, **kwargs)[source]

Compute a pairwise distance tensor among sets of nearest neighbors.

Takes a full dataset of records of interest data and produces the pairwise distances between the elements indicated by each row of nn_indices.

Parameters:

data (ndarray) – The data matrix of shape (batch_count, feature_count) containing batch elements.
nn_indices (ndarray) – An integral matrix of shape (batch_count, nn_count) listing the nearest neighbor indices for the batch of data points.

Return type:

ndarray

Returns:

A tensor of shape (batch_count, nn_count, nn_count) containing the (nn_count, nn_count)-shaped pairwise nearest neighbor distance tensors corresponding to each of the batch elements.

MuyGPyS.gp.deformation.metric.l2 = <MuyGPyS.gp.deformation.metric.MetricFn object>

l2 or Euclidean metric function.

Computes the Euclidean distance between points:

\[d_{\ell_2}(\mathbf{x}, \mathbf{y}) = \left ( \sum_{i=1}^n (x_i - y_i)^2 \right )^{1/2}\]

Parameters:: dists – A difference tensor of shape (..., feature_count).
Returns:: A distance tensor of shape (...).