FiniteGP and AbstractGP

Intended Audience

This page is best read once you have a sense of what this package is trying to achieve. Therefore, we recommend reading (or at least skimming) some of the examples before reading these docs.

AbstractGPs provides the abstract type AbstractGP, and the concrete type FiniteGP. An AbstractGP, f, should be thought of as a distribution over functions. This means that the output of rand(f) would be a real-valued function. It's not usually possible to implement this though, so we don't.

A FiniteGP fx = f(x) represents the distribution over functions at the finite collection of points specified in x. fx is a multivariate Normal distribution, so rand(fx) produces a Vector of Reals.

A FiniteGP is the interesting object computationally, so if you create a new subtype MyNewGP of AbstractGP, and wish to make it interact well with the rest of the GP ecosystem, the methods that you must implement are not those directly involving MyNewGP, but rather those involving

FiniteGP{<:MyNewGP}

We provide two ways in which to do this. The first is to implement methods directly on FiniteGP{<:MyNewGP} – this is detailed in the FiniteGP APIs. The second is to implement some methods directly involving MyNewGP, and utilise default FiniteGP methods implemented in terms of these – this is detailed in the Internal AbstractGPs API. For example, the first method involves implementing methods like AbstractGPs.mean(fx::FiniteGP{<:MyNewGP}), while the second involves AbstractGPs.mean(f::MyNewGP, x::AbstractVector).

The second interface is generally easier to implement, but isn't always the best choice. See Which API should I implement? for further discussion.

FiniteGP APIs

Let f be an AbstractGP, x an AbstractVector representing a collection of inputs, and Σ a positive-definite matrix of size (length(x), length(x)). A FiniteGP represents the multivariate Gaussian induced by "indexing" into f at each point in x, and adding independent zero-mean noise with covariance matrix Σ:

fx = f(x, Σ)

# The code below is equivalent to the above, and is just for reference.
# When writing code, prefer the above syntax.
fx = AbstractGPs.FiniteGP(f, x, Σ)

The FiniteGP has two API levels. The Primary Public API should be supported by all FiniteGPs, while the Secondary Public API will only be supported by a subset. Use only the primary API when possible.

Primary Public API

These are user-facing methods. You can expect them to be implemented whenever you encounter a FiniteGP. If you are building something on top of AbstractGPs, try to implement it in terms of these functions.

Required Methods

Base.rand — Function

rand(rng::AbstractRNG, f::FiniteGP, N::Int=1)

Obtain N independent samples from the marginals f using rng. Single-sample methods produce a length(f) vector. Multi-sample methods produce a length(f) × N Matrix.

julia> f = GP(Matern32Kernel());

julia> x = randn(11);

julia> rand(f(x)) isa Vector{Float64}
true

julia> rand(MersenneTwister(123456), f(x)) isa Vector{Float64}
true

julia> rand(f(x), 3) isa Matrix{Float64}
true

julia> rand(MersenneTwister(123456), f(x), 3) isa Matrix{Float64}
true