MuyGPS
- class MuyGPyS.gp.muygps.MuyGPS(kernel, noise=<MuyGPyS.gp.noise.homoscedastic.HomoscedasticNoise object>, scale=<MuyGPyS.gp.hyperparameter.scale.FixedScale object>, _backend_mean_fn=<function _muygps_posterior_mean>, _backend_var_fn=<function _muygps_diagonal_variance>, _backend_fast_mean_fn=<function _muygps_fast_posterior_mean>, _backend_fast_precompute_fn=<function _muygps_fast_posterior_mean_precompute>)[source]
Local Kriging Gaussian Process.
Performs approximate GP inference by locally approximating an observation’s response using its nearest neighbors. Implements the MuyGPs algorithm as articulated in [muyskens2021muygps].
Kernels accept different hyperparameter dictionaries specifying hyperparameter settings. Keys can include
val
andbounds
.bounds
must be either a len == 2 iterable container whose elements are scalars in increasing order, or the stringfixed
. Ifbounds == fixed
(the default behavior), the hyperparameter value will remain fixed during optimization.val
must be either a scalar (within the range of the upper and lower bounds if given) or the strings"sample"
orlog_sample"
, which will randomly sample a value within the range given by the bounds.In addition to individual kernel hyperparamters, each MuyGPS object also possesses a noise model, possibly with parameters, and a vector of \(\sigma^2\) indicating the scale parameter associated with the posterior variance of each dimension of the response.
Example
>>> from MuyGPyS.gp import MuyGPS >>> muygps = MuyGPS( ... kernel=Matern( ... smoothness=Parameter(0.38, (0.1, 2.5)), ... deformation=Isotropy( ... metric=F2, ... length_scale=Parameter(0.2), ... ), ... ), ... noise=HomoscedasticNoise(1e-5), ... scale=AnalyticScale(), ... )
MuyGPyS depends upon linear operations on specially-constructed tensors in order to efficiently estimate GP realizations. One can use (see their documentation for details)
MuyGPyS.gp.tensors.pairwise_tensor()
to construct pairwise difference tensors andMuyGPyS.gp.tensors.crosswise_tensor()
to produce crosswise diff tensors thatMuyGPS
can then use to construct kernel tensors and cross-covariance matrices, respectively.We can easily realize kernel tensors using a
MuyGPS
object’skernel
functor once we have computed apairwise_diffs
tensor and acrosswise_diffs
matrix.Example
>>> K = muygps.kernel(pairwise_diffs) >>> Kcross = muygps.kernel(crosswise_diffs)
- Parameters:
kernel (
KernelFn
) – The kernel to be used. Defines \(K_\theta(\cdot, \cdot)\) as referenced inMuyGPS
functions.noise (
NoiseFn
) – A noise model. Defines \(\varepsilon\) as referenced inMuyGPS
functions.scale (
ScaleFn
) – A variance scale parameter. Defines \(\sigma^2\) as referenced inMuyGPS
functions.
- fast_coefficients(K, train_nn_targets_fast)[source]
Produces coefficient matrix for the fast posterior mean given in Equation (8) of [dunton2022fast].
Given observation set \(X\) with responses \(Y\), noise prior set \(\varepsilon\), and kernel function \(K_\theta(\cdot, \cdot)\), computes the following for each observation element \(\mathbf{x}_i\) with nearest neighbors index set \(N^*_i\), containing
i
and the indices of thenn_count - 1
nearest neighbors of \(\mathbf{x}_i\):\[C_i = \left ( K_\theta (X_{N_i}, X_{N_i} \right ) + \varepsilon_{N_i})^{-1} Y(X_{N_i}).\]- Parameters:
K (
ndarray
) – A tensor of shape(batch_count, nn_count, nn_count)
containing the(nn_count, nn_count)
-shaped kernel matrices corresponding to each of the batch elements.Kcross – A matrix of shape
(batch_count, nn_count)
whose rows consist of(1, nn_count)
-shaped cross-covariance vector corresponding to each of the batch elements and its nearest neighbors.
- Return type:
ndarray
- Returns:
A matrix \(C\) of shape
(train_count, nn_count)
whose rows are the precomputed coefficients for fast posterior mean inference.
- fast_posterior_mean(Kcross, coeffs_tensor)[source]
Performs fast posterior mean inference using provided cross-covariance and precomputed coefficient matrix.
Assumes that cross-covariance matrix
Kcross
is already computed and given as an argument.Returns the predicted response in the form of a posterior mean for each element of the batch of observations, as computed in Equation (9) of [dunton2022fast]. Given the coefficients \(C\) created by
fast_coefficients()
and Equation (8) of [dunton2022fast], observation set \(X\), noise prior set \(\varepsilon\), and kernel function \(K_\theta(\cdot, \cdot)\), computes the following for each test point \(\mathbf{z}\) and index set \(N^*_i\) containing the union of the index \(i\) of the nearest neighbor \(\mathbf{x}_i\) of \(\mathbf{z}\) and thenn_count - 1
nearest neighbors of \(\mathbf{x}_i\):\[\widehat{Y} \left ( \mathbf{z} \mid X \right ) = \sigma^2 K_\theta(\mathbf{z}, X_{N^*_i}) C_i.\]- Parameters:
Kcross (
ndarray
) – A matrix of shape(batch_count, nn_count)
whose rows consist of(1, nn_count)
-shaped cross-covariance vector corresponding to each of the batch elements and its nearest neighbors.coeffs_tensor (
ndarray
) – A matrix of shape(batch_count, nn_count, response_count)
whose rows are given by precomputed coefficients.
- Return type:
ndarray
- Returns:
A matrix of shape
(batch_count, response_count)
whose rows are the predicted response for each of the given indices.
- fixed()[source]
Checks whether all kernel and model parameters are fixed.
This is a convenience utility to determine whether optimization is required.
- Return type:
bool
- Returns:
Returns
True
if all parameters are fixed, andFalse
otherwise.
- get_opt_mean_fn()[source]
Return a posterior mean function for use in optimization.
Assumes that optimization parameter literals will be passed as keyword arguments.
- Return type:
Callable
- Returns:
A function implementing the posterior mean, where
noise
is either fixed or takes updating values during optimization. The function expects keyword arguments corresponding to current hyperparameter values for unfixed parameters.
- get_opt_params()[source]
Return lists of unfixed hyperparameter names, values, and bounds.
- Return type:
Tuple
[List
[str
],ndarray
,ndarray
]- Returns:
- names:
A list of unfixed hyperparameter names.
- params:
A list of unfixed hyperparameter values.
- bounds:
A list of unfixed hyperparameter bound tuples.
- get_opt_var_fn()[source]
Return a posterior variance function for use in optimization.
Assumes that optimization parameter literals will be passed as keyword arguments.
- Return type:
Callable
- Returns:
A function implementing posterior variance, where
noise
is either fixed or takes updating values during optimization. The function expects keyword arguments corresponding to current hyperparameter values for unfixed parameters.
- optimize_scale(pairwise_diffs, nn_targets)[source]
Optimize the value of the \(sigma^2\) scale parameter.
Uses the optimization method specified by the type of the
scale
parameter to optimize its value.- Parameters:
pairwise_diffs (
ndarray
) – 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.nn_targets (
ndarray
) – Tensor of floats of shape(batch_count, nn_count, response_count)
containing the expected response for each nearest neighbor of each batch element.
- Returns:
A reference to this model with a freshly-optimized
scale
parameter.
- posterior_mean(K, Kcross, batch_nn_targets)[source]
Returns the posterior mean from the provided covariance, cross-covariance, and target tensors.
Computes parallelized local solves of systems of linear equations using the last two dimensions of
K
along withKcross
andbatch_nn_targets
to predict responses in terms of the posterior mean. Assumes that kernel tensorK
and cross-covariance matrixKcross
are already computed and given as arguments.Returns the predicted response in the form of a posterior mean for each element of the batch of observations, as computed in Equation (3.4) of [muyskens2021muygps]. Given observation set \(X\) with responses \(Y\), noise prior set \(\varepsilon\), and kernel function \(K_\theta(\cdot, \cdot)\), computes the following for each prediction element \(\mathbf{z}_i\) with nearest neighbors index set \(N_i\):
\[\widehat{Y} (\mathbf{z}_i \mid X_{N_i}) = \sigma^2 K_\theta (\mathbf{z}_i, X_{N_i}) (K_\theta (X_{N_i}, X_{N_i}) + \varepsilon_{N_i})^{-1} Y(X_{N_i}).\]- Parameters:
K (
ndarray
) – A tensor of shape(batch_count, nn_count, nn_count)
containing the(nn_count, nn_count)
-shaped kernel matrices corresponding to each of the batch elements.Kcross (
ndarray
) – A matrix of shape(batch_count, nn_count)
whose rows consist of(1, nn_count)
-shaped cross-covariance vector corresponding to each of the batch elements and its nearest neighbors.batch_nn_targets (
ndarray
) – A tensor of shape(batch_count, nn_count, response_count)
whose last dimension lists the vector-valued responses for the nearest neighbors of each batch element.
- Return type:
ndarray
- Returns:
A matrix of shape
(batch_count, response_count)
whose rows are the predicted response for each of the given indices.
- posterior_variance(K, Kcross)[source]
Returns the posterior variance from the provided covariance and cross-covariance tensors.
Return the local posterior variances of each prediction, corresponding to the diagonal elements of a covariance matrix. Given observation set \(X\) with responses \(Y\), noise prior set \(\varepsilon\), and kernel function \(K_\theta(\cdot, \cdot)\), computes the following for each prediction element \(\mathbf{z}_i\) with nearest neighbors index set \(N_i\):
\[Var \left ( \widehat{Y} (\mathbf{z}_i \mid X_{N_i}) \right) = \sigma^2 \left ( K_\theta (\mathbf{z}_i, \mathbf{z}_i) - K_\theta (\mathbf{z}_i, X_{N_i}) \left ( K_\theta (X_{N_i}, X_{N_i} \right ) + \varepsilon_{N_i})^{-1} K_\theta (X_{N_i}, \mathbf{z}_i) \right ).\]- Parameters:
K (
ndarray
) – A tensor of shape(batch_count, nn_count, nn_count)
containing the(nn_count, nn_count)
-shaped kernel matrices corresponding to each of the batch elements.Kcross (
ndarray
) – A matrix of shape(batch_count, nn_count)
whose rows consist of(1, nn_count)
-shaped cross-covariance vector corresponding to each of the batch elements and its nearest neighbors.
- Return type:
ndarray
- Returns:
A vector of shape
(batch_count, response_count)
consisting of the diagonal elements of the posterior variance.