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 ofnn_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 candidatesnn_data
and produces a difference vector between each element ofdata
indicated bydata_indices
and each of the nearest neighbors innn_data
as indicated by the corresponding rows ofnn_indices
.data
andnn_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 asdata
.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 candidatesnn_data
and produces a scalar distance between each element ofdata
indicated bydata_indices
and each of the nearest neighbors innn_data
as indicated by the corresponding rows ofnn_indices
.data
andnn_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 asdata
.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 ofnn_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 ofnn_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
(...)
.