Multi-Output helper function (JuliaGaussianProcesses#345)

* Add helper function

* Docs

* Update src/mokernels/moinput.jl

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Relax type constraint

Co-authored-by: st-- <[email protected]>

* Split into two methods

* Update docs

* Update src/mokernels/moinput.jl

Co-authored-by: st-- <[email protected]>

* Update src/mokernels/moinput.jl

Co-authored-by: st-- <[email protected]>

* Move consistency tests to test

* Tweak wording

* Apply suggestions from code review

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update runtests.jl

* Apply suggestions from code review

Co-authored-by: st-- <[email protected]>

* Update test/mokernels/moinput.jl

Co-authored-by: st-- <[email protected]>

* Bump patch

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: st-- <[email protected]>
Co-authored-by: Théo Galy-Fajou <[email protected]>

Author: 4 people

Project.toml

@@ -1,6 +1,6 @@
 name = "KernelFunctions"
 uuid = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
-version = "0.10.9"
+version = "0.10.10"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"

docs/src/api.md

@@ -58,7 +58,13 @@ For an explanation of this design choice, see [the design notes on multi-output
 An input to a multi-output `Kernel` should be a `Tuple{T, Int}`, whose first element specifies a location in the domain of the multi-output GP, and whose second element specifies which output the inputs corresponds to.
 The type of collections of inputs for multi-output GPs is therefore `AbstractVector{<:Tuple{T, Int}}`.
 
-KernelFunctions.jl provides the following type or situations in which all outputs are observed all of the time:
+KernelFunctions.jl provides the following helper function for situations in which all outputs are observed all of the time:
+```@docs
+prepare_isotopic_multi_output_data(x::AbstractVector, y::ColVecs)
+prepare_isotopic_multi_output_data(x::AbstractVector, y::RowVecs)
+```
+
+The input types that it constructs can also be constructed manually:
 ```@docs
 MOInput
 ```
@@ -68,7 +74,7 @@ type enables specialised implementations of e.g. [`kernelmatrix`](@ref) for
 
 To find out more about the background, read this [review of kernels for vector-valued functions](https://arxiv.org/pdf/1106.6251.pdf).
 
-## Utilities
+## Generic Utilities
 
 KernelFunctions also provides miscellaneous utility functions.
 ```@docs

src/KernelFunctions.jl

@@ -36,7 +36,7 @@ export spectral_mixture_kernel, spectral_mixture_product_kernel
 
 export ColVecs, RowVecs
 
-export MOInput
+export MOInput, prepare_isotopic_multi_output_data
 export IndependentMOKernel,
     LatentFactorMOKernel, IntrinsicCoregionMOKernel, LinearMixingModelKernel
 

src/mokernels/moinput.jl

@@ -103,3 +103,94 @@ See [Inputs for Multiple Outputs](@ref) in the docs for more info.
 and removed in version 0.12.
 """
 const MOInput = MOInputIsotopicByOutputs
+
+"""
+    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
+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}}:
+ (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
+```
+"""
+function prepare_isotopic_multi_output_data(x::AbstractVector, y::ColVecs)
+    length(x) == length(y) || throw(ArgumentError("length(x) not equal to length(y)."))
+    return MOInputIsotopicByFeatures(x, size(y.X, 1)), vec(y.X)
+end
+
+"""
+    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:
+```jldoctest
+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}}:
+ (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
+```
+"""
+function prepare_isotopic_multi_output_data(x::AbstractVector, y::RowVecs)
+    length(x) == length(y) || throw(ArgumentError("length(x) not equal to length(y)."))
+    return MOInputIsotopicByOutputs(x, size(y.X, 2)), vec(y.X)
+end

test/mokernels/moinput.jl

@@ -44,4 +44,35 @@
         @test ibf[7] == (x[3], 1)
         @test all([(x_, i) for x_ in x for i in 1:3] .== ibf)
     end
+
+    @testset "prepare_isotopic_multi_output_data" begin
+        @testset "ColVecs" begin
+            N = 5
+            P = 3
+
+            x = randn(N)
+            y = ColVecs(randn(P, N))
+
+            x_canon, y_canon = prepare_isotopic_multi_output_data(x, y)
+
+            @test x_canon isa KernelFunctions.MOInputIsotopicByFeatures
+            @test length(x_canon) == N * P
+            @test y_canon isa AbstractVector{<:Real}
+            @test length(y_canon) == length(x_canon)
+        end
+        @testset "RowVecs" begin
+            N = 5
+            P = 3
+
+            x = randn(N)
+            y = RowVecs(randn(N, P))
+
+            x_canon, y_canon = prepare_isotopic_multi_output_data(x, y)
+
+            @test x_canon isa KernelFunctions.MOInputIsotopicByOutputs
+            @test length(x_canon) == N * P
+            @test y_canon isa AbstractVector{<:Real}
+            @test length(y_canon) == length(x_canon)
+        end
+    end
 end

test/runtests.jl

@@ -183,8 +183,8 @@ include("test_utils.jl")
                 KernelFunctions;
                 doctestfilters=[
                     r"{([a-zA-Z0-9]+,\s?)+[a-zA-Z0-9]+}",
-                    r"(Array{[a-zA-Z0-9]+,\s?1}|\s?Vector{[a-zA-Z0-9]+})",
-                    r"(Array{[a-zA-Z0-9]+,\s?2}|\s?Matrix{[a-zA-Z0-9]+})",
+                    r"(\s?Array{[a-zA-Z0-9]+,\s?1}|\s?Vector{[a-zA-Z0-9]+})",
+                    r"(\s?Array{[a-zA-Z0-9]+,\s?2}|\s?Matrix{[a-zA-Z0-9]+})",
                 ],
             )
         end