API Library

kernelmatrix(κ::Kernel, x::AbstractVector)

Compute the kernel κ for each pair of inputs in x. Returns a matrix of size (length(x), length(x)) satisfying kernelmatrix(κ, x)[p, q] == κ(x[p], x[q]).

kernelmatrix(κ::Kernel, x::AbstractVector, y::AbstractVector)

Compute the kernel κ for each pair of inputs in x and y. Returns a matrix of size (length(x), length(y)) satisfying kernelmatrix(κ, x, y)[p, q] == κ(x[p], y[q]).

kernelmatrix(κ::Kernel, X::AbstractMatrix; obsdim)
kernelmatrix(κ::Kernel, X::AbstractMatrix, Y::AbstractMatrix; obsdim)

If obsdim=1, equivalent to kernelmatrix(κ, RowVecs(X)) and kernelmatrix(κ, RowVecs(X), RowVecs(Y)), respectively. If obsdim=2, equivalent to kernelmatrix(κ, ColVecs(X)) and kernelmatrix(κ, ColVecs(X), ColVecs(Y)), respectively.

See also: ColVecs, RowVecs

kernelmatrix!(K::AbstractMatrix, κ::Kernel, x::AbstractVector)
kernelmatrix!(K::AbstractMatrix, κ::Kernel, x::AbstractVector, y::AbstractVector)

In-place version of kernelmatrix where pre-allocated matrix K will be overwritten with the kernel matrix.

kernelmatrix!(K::AbstractMatrix, κ::Kernel, X::AbstractMatrix; obsdim)
kernelmatrix!(
    K::AbstractMatrix,
    κ::Kernel,
    X::AbstractMatrix,
    Y::AbstractMatrix;
    obsdim,
)

If obsdim=1, equivalent to kernelmatrix!(K, κ, RowVecs(X)) and kernelmatrix(K, κ, RowVecs(X), RowVecs(Y)), respectively. If obsdim=2, equivalent to kernelmatrix!(K, κ, ColVecs(X)) and kernelmatrix(K, κ, ColVecs(X), ColVecs(Y)), respectively.

See also: ColVecs, RowVecs

kernelmatrix_diag(κ::Kernel, x::AbstractVector)

Compute the diagonal of kernelmatrix(κ, x) efficiently.

kernelmatrix_diag(κ::Kernel, x::AbstractVector, y::AbstractVector)

Compute the diagonal of kernelmatrix(κ, x, y) efficiently. Requires that x and y are the same length.

kernelmatrix_diag(κ::Kernel, X::AbstractMatrix; obsdim)
kernelmatrix_diag(κ::Kernel, X::AbstractMatrix, Y::AbstractMatrix; obsdim)

If obsdim=1, equivalent to kernelmatrix_diag(κ, RowVecs(X)) and kernelmatrix_diag(κ, RowVecs(X), RowVecs(Y)), respectively. If obsdim=2, equivalent to kernelmatrix_diag(κ, ColVecs(X)) and kernelmatrix_diag(κ, ColVecs(X), ColVecs(Y)), respectively.

See also: ColVecs, RowVecs

kernelmatrix_diag!(K::AbstractVector, κ::Kernel, x::AbstractVector)
kernelmatrix_diag!(K::AbstractVector, κ::Kernel, x::AbstractVector, y::AbstractVector)

In place version of kernelmatrix_diag.

kernelmatrix_diag!(K::AbstractVector, κ::Kernel, X::AbstractMatrix; obsdim)
kernelmatrix_diag!(
    K::AbstractVector,
    κ::Kernel,
    X::AbstractMatrix,
    Y::AbstractMatrix;
    obsdim
)

If obsdim=1, equivalent to kernelmatrix_diag!(K, κ, RowVecs(X)) and kernelmatrix_diag!(K, κ, RowVecs(X), RowVecs(Y)), respectively. If obsdim=2, equivalent to kernelmatrix_diag!(K, κ, ColVecs(X)) and kernelmatrix_diag!(K, κ, ColVecs(X), ColVecs(Y)), respectively.

See also: ColVecs, RowVecs

ColVecs(X::AbstractMatrix)

A lightweight wrapper for an AbstractMatrix which interprets it as a vector-of-vectors, in which each column of X represents a single vector.

That is, by writing x = ColVecs(X), you are saying "x is a vector-of-vectors, each of which has length size(X, 1). The total number of vectors is size(X, 2)."

Phrased differently, ColVecs(X) says that X should be interpreted as a vector of horizontally-concatenated column-vectors, hence the name ColVecs.

julia> X = randn(2, 5);

julia> x = ColVecs(X);

julia> length(x) == 5
true

julia> X[:, 3] == x[3]
true

ColVecs is related to RowVecs via transposition:

julia> X = randn(2, 5);

julia> ColVecs(X) == RowVecs(X')
true

RowVecs(X::AbstractMatrix)

A lightweight wrapper for an AbstractMatrix which interprets it as a vector-of-vectors, in which each row of X represents a single vector.

That is, by writing x = RowVecs(X), you are saying "x is a vector-of-vectors, each of which has length size(X, 2). The total number of vectors is size(X, 1)."

Phrased differently, RowVecs(X) says that X should be interpreted as a vector of vertically-concatenated row-vectors, hence the name RowVecs.

Internally, the data continues to be represented as an AbstractMatrix, so using this type does not introduce any kind of performance penalty.

julia> X = randn(5, 2);

julia> x = RowVecs(X);

julia> length(x) == 5
true

julia> X[3, :] == x[3]
true

RowVecs is related to ColVecs via transposition:

julia> X = randn(5, 2);

julia> RowVecs(X) == ColVecs(X')
true

prepare_isotopic_multi_output_data(x::AbstractVector, y::ColVecs)

Utility functionality to convert a collection of N = length(x) inputs x, and a vector-of-vectors y (efficiently represented by a ColVecs) into a format suitable for use with multi-output kernels.

y[n] is the vector-valued output corresponding to the input x[n]. Consequently, it is necessary that length(x) == length(y).

For example, if outputs are initially stored in a num_outputs × N matrix:

julia> x = [1.0, 2.0, 3.0];

julia> Y = [1.1 2.1 3.1; 1.2 2.2 3.2]
2×3 Matrix{Float64}:
 1.1  2.1  3.1
 1.2  2.2  3.2

julia> inputs, outputs = prepare_isotopic_multi_output_data(x, ColVecs(Y));

julia> inputs
6-element KernelFunctions.MOInputIsotopicByFeatures{Float64, Vector{Float64}, Int64}:
 (1.0, 1)
 (1.0, 2)
 (2.0, 1)
 (2.0, 2)
 (3.0, 1)
 (3.0, 2)

julia> outputs
6-element Vector{Float64}:
 1.1
 1.2
 2.1
 2.2
 3.1
 3.2

See also prepare_heterotopic_multi_output_data.

prepare_isotopic_multi_output_data(x::AbstractVector, y::RowVecs)

Utility functionality to convert a collection of N = length(x) inputs x and output vectors y (efficiently represented by a RowVecs) into a format suitable for use with multi-output kernels.

y[n] is the vector-valued output corresponding to the input x[n]. Consequently, it is necessary that length(x) == length(y).

For example, if outputs are initial stored in an N × num_outputs matrix:

julia> x = [1.0, 2.0, 3.0];

julia> Y = [1.1 1.2; 2.1 2.2; 3.1 3.2]
3×2 Matrix{Float64}:
 1.1  1.2
 2.1  2.2
 3.1  3.2

julia> inputs, outputs = prepare_isotopic_multi_output_data(x, RowVecs(Y));

julia> inputs
6-element KernelFunctions.MOInputIsotopicByOutputs{Float64, Vector{Float64}, Int64}:
 (1.0, 1)
 (2.0, 1)
 (3.0, 1)
 (1.0, 2)
 (2.0, 2)
 (3.0, 2)

julia> outputs
6-element Vector{Float64}:
 1.1
 2.1
 3.1
 1.2
 2.2
 3.2

See also prepare_heterotopic_multi_output_data.

prepare_heterotopic_multi_output_data(
    x::AbstractVector, y::AbstractVector{<:Real}, output_indices::AbstractVector{Int},
)

Utility functionality to convert a collection of inputs x, observations y, and output_indices into a format suitable for use with multi-output kernels. Handles the situation in which only one (or a subset) of outputs are observed at each feature. Ensures that all arguments are compatible with one another, and returns a vector of inputs and a vector of outputs.

y[n] should be the observed value associated with output output_indices[n] at feature x[n].

julia> x = [1.0, 2.0, 3.0];

julia> y = [-1.0, 0.0, 1.0];

julia> output_indices = [3, 2, 1];

julia> inputs, outputs = prepare_heterotopic_multi_output_data(x, y, output_indices);

julia> inputs
3-element Vector{Tuple{Float64, Int64}}:
 (1.0, 3)
 (2.0, 2)
 (3.0, 1)

julia> outputs
3-element Vector{Float64}:
 -1.0
  0.0
  1.0

See also prepare_isotopic_multi_output_data.

MOInput(x::AbstractVector, out_dim::Integer)

A data type to accommodate modelling multi-dimensional output data. MOInput(x, out_dim) has length length(x) * out_dim.

julia> x = [1, 2, 3];

julia> MOInput(x, 2)
6-element KernelFunctions.MOInputIsotopicByOutputs{Int64, Vector{Int64}, Int64}:
 (1, 1)
 (2, 1)
 (3, 1)
 (1, 2)
 (2, 2)
 (3, 2)

As shown above, an MOInput represents a vector of tuples. The first length(x) elements represent the inputs for the first output, the second length(x) elements represent the inputs for the second output, etc. See Inputs for Multiple Outputs in the docs for more info.

MOInput will be deprecated in version 0.11 in favour of MOInputIsotopicByOutputs, and removed in version 0.12.

nystrom(k::Kernel, X::AbstractVector, S::AbstractVector{<:Integer})

Compute a factorization of a Nystrom approximation of the square kernel matrix of data vector X with respect to kernel k, using indices S. Returns a NystromFact struct which stores a Nystrom factorization satisfying:

\[\mathbf{K} \approx \mathbf{C}^{\intercal}\mathbf{W}\mathbf{C}\]

nystrom(k::Kernel, X::AbstractVector, r::Real)

Compute a factorization of a Nystrom approximation of the square kernel matrix of data vector X with respect to kernel k using a sample ratio of r. Returns a NystromFact struct which stores a Nystrom factorization satisfying:

\[\mathbf{K} \approx \mathbf{C}^{\intercal}\mathbf{W}\mathbf{C}\]

nystrom(k::Kernel, X::AbstractMatrix, S::AbstractVector{<:Integer}; obsdim)

If obsdim=1, equivalent to nystrom(k, RowVecs(X), S). If obsdim=2, equivalent to nystrom(k, ColVecs(X), S).

See also: ColVecs, RowVecs

nystrom(k::Kernel, X::AbstractMatrix, r::Real; obsdim)

If obsdim=1, equivalent to nystrom(k, RowVecs(X), r). If obsdim=2, equivalent to nystrom(k, ColVecs(X), r).

See also: ColVecs, RowVecs

NystromFact

Type for storing a Nystrom factorization. The factorization contains two fields: W and C, two matrices satisfying:

\[\mathbf{K} \approx \mathbf{C}^{\intercal}\mathbf{W}\mathbf{C}\]

kronecker_kernelmatrix(
    k::Union{IndependentMOKernel,IntrinsicCoregionMOKernel}, x::MOI, y::MOI
) where {MOI<:IsotopicMOInputsUnion}

Requires Kronecker.jl: Computes the kernelmatrix for the IndependentMOKernel and the IntrinsicCoregionMOKernel, but returns a lazy kronecker product. This object can be very efficiently inverted or decomposed. See also kernelmatrix.

kernelkronmat(κ::Kernel, X::AbstractVector{<:Real}, dims::Int) -> KroneckerPower

Return a KroneckerPower matrix on the D-dimensional input grid constructed by $\otimes_{i=1}^D X$, where D is given by dims.

kernelkronmat(κ::Kernel, X::AbstractVector{<:AbstractVector}) -> KroneckerProduct

Returns a KroneckerProduct matrix on the grid built with the collection of vectors $\{X_i\}_{i=1}^D$: $\otimes_{i=1}^D X_i$.

kernelpdmat(k::Kernel, X::AbstractVector)

Compute a positive-definite matrix in the form of a PDMat matrix (see PDMats.jl), with the Cholesky decomposition precomputed. The algorithm adds a diagonal "nugget" term to the kernel matrix which is increased until positive definiteness is achieved. The algorithm gives up with an error if the nugget becomes larger than 1% of the largest value in the kernel matrix.

kernelpdmat(k::Kernel, X::AbstractMatrix; obsdim)

If obsdim=1, equivalent to kernelpdmat(k, RowVecs(X)). If obsdim=2, equivalent to kernelpdmat(k, ColVecs(X)).

See also: ColVecs, RowVecs