Rename kerneldiagmatrix[!] -> kernelmatrix_diag[!] (#235)

st-- · devmotion · web-flow · commit 1983d1d5eb5d · 2021-01-27T14:17:53.000Z
* Rename kerneldiagmatrix[!] -&gt; kernelmatrix_diag[!] and add deprecations for kerneldiagmatrix[!]

* add tests for in-place kernel matrix computation working correctly &amp; fix uncovered bug

* bump version

Co-authored-by: David Widmann &lt;devmotion@users.noreply.github.com&gt;
diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "KernelFunctions"
 uuid = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
-version = "0.8.22"
+version = "0.8.23"
 
 [deps]
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
diff --git a/benchmark/MLKernels.jl b/benchmark/MLKernels.jl
@@ -16,7 +16,7 @@ for k in mlkernelnames
     # SUITE["MLKernels"][k][kt]["k!(X,Y)"] = @benchmarkable MLKernels.kernelmatrix!(KXY,$(kernels[k][kt]),$X,$Y) setup=(KXY=copy($KXY))
     SUITE["MLKernels"][k]["k(X)"] = @benchmarkable MLKernels.kernelmatrix($(kernels[k]), $X)
     # SUITE["MLKernels"][k][kt]["k!(X)"] = @benchmarkable MLKernels.kernelmatrix!(KX,$(kernels[k][kt]),$X) setup=(KX=copy($KX))
-    # SUITE["MLKernels"][k][kt]["kdiag(X)"] = @benchmarkable MLKernels.kerneldiagmatrix($(kernels[k][kt]),$X)
-    # SUITE["MLKernels"][k][kt]["kdiag!(X)"] = @benchmarkable MLKernels.kerneldiagmatrix!(kX,$(kernels[k][kt]),$X) setup=(kX=copy($kX))
+    # SUITE["MLKernels"][k][kt]["kdiag(X)"] = @benchmarkable MLKernels.kernelmatrix_diag($(kernels[k][kt]),$X)
+    # SUITE["MLKernels"][k][kt]["kdiag!(X)"] = @benchmarkable MLKernels.kernelmatrix_diag!(kX,$(kernels[k][kt]),$X) setup=(kX=copy($kX))
 end
 # results = run(SUITE)
diff --git a/benchmark/kernelmatrix.jl b/benchmark/kernelmatrix.jl
@@ -32,8 +32,8 @@ for k in kernelnames
             $(kernels[k][kt]), $X; obsdim=1
         )
         # SUITE["KernelFunctions"][k][kt]["k!(X)"] = @benchmarkable KernelFunctions.kernelmatrix!(KX,$(kernels[k][kt]),$X) setup=(KX=copy($KX))
-        # SUITE["KernelFunctions"][k][kt]["kdiag(X)"] = @benchmarkable KernelFunctions.kerneldiagmatrix($(kernels[k][kt]),$X)
-        # SUITE["KernelFunctions"][k][kt]["kdiag!(X)"] = @benchmarkable KernelFunctions.kerneldiagmatrix!(kX,$(kernels[k][kt]),$X) setup=(kX=copy($kX))
+        # SUITE["KernelFunctions"][k][kt]["kdiag(X)"] = @benchmarkable KernelFunctions.kernelmatrix_diag($(kernels[k][kt]),$X)
+        # SUITE["KernelFunctions"][k][kt]["kdiag!(X)"] = @benchmarkable KernelFunctions.kernelmatrix_diag!(kX,$(kernels[k][kt]),$X) setup=(kX=copy($kX))
     end
 end
 # results = run(SUITE)
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -14,8 +14,8 @@ CurrentModule = KernelFunctions
 ```@docs
 kernelmatrix
 kernelmatrix!
-kerneldiagmatrix
-kerneldiagmatrix!
+kernelmatrix_diag
+kernelmatrix_diag!
 kernelpdmat
 nystrom
 ```
diff --git a/docs/src/userguide.md b/docs/src/userguide.md
@@ -51,7 +51,7 @@ To evaluate the kernel function on two vectors you simply call the kernel object
 
 ## Creating a kernel matrix
 
-Kernel matrices can be created via the `kernelmatrix` function or `kerneldiagmatrix` for only the diagonal.
+Kernel matrices can be created via the `kernelmatrix` function or `kernelmatrix_diag` for only the diagonal.
 An important argument to give is the data layout of the input `obsdim`. It specifies whether the number of observed data points is along the first dimension (`obsdim=1`, i.e. the matrix shape is number of samples times number of features) or along the second dimension (`obsdim=2`, i.e. the matrix shape is number of features times number of samples), similarly to [Distances.jl](https://github.com/JuliaStats/Distances.jl). If not given explicitly, `obsdim` defaults to `2`.
 For example:
 ```julia
diff --git a/src/KernelFunctions.jl b/src/KernelFunctions.jl
@@ -13,7 +13,7 @@ if !isfile(joinpath(@__DIR__, "update_v0.8.0"))
     touch(joinpath(@__DIR__, "update_v0.8.0"))
 end
 
-export kernelmatrix, kernelmatrix!, kerneldiagmatrix, kerneldiagmatrix!
+export kernelmatrix, kernelmatrix!, kernelmatrix_diag, kernelmatrix_diag!
 export transform
 export duplicate, set! # Helpers
 
diff --git a/src/basekernels/gabor.jl b/src/basekernels/gabor.jl
@@ -71,4 +71,4 @@ function kernelmatrix(κ::GaborKernel, x::AbstractVector, y::AbstractVector)
     return kernelmatrix(κ.kernel, x, y)
 end
 
-kerneldiagmatrix(κ::GaborKernel, x::AbstractVector) = kerneldiagmatrix(κ.kernel, x)
+kernelmatrix_diag(κ::GaborKernel, x::AbstractVector) = kernelmatrix_diag(κ.kernel, x)
diff --git a/src/deprecated.jl b/src/deprecated.jl
@@ -9,3 +9,25 @@
 )
 
 Base.@deprecate_binding TensorProduct KernelTensorProduct
+
+# TODO: remove tests when removed
+@deprecate kerneldiagmatrix(k::Kernel, x::AbstractVector) kernelmatrix_diag(k, x)
+@deprecate kerneldiagmatrix(k::Kernel, x::AbstractVector, y::AbstractVector) kernelmatrix_diag(
+    k, x, y
+)
+@deprecate kerneldiagmatrix!(K, k::Kernel, x::AbstractVector) kernelmatrix_diag!(K, k, x)
+@deprecate kerneldiagmatrix!(K, k::Kernel, x::AbstractVector, y::AbstractVector) kernelmatrix_diag!(
+    K, k, x, y
+)
+@deprecate kerneldiagmatrix(k::Kernel, X::AbstractMatrix; obsdim::Int=defaultobs) kernelmatrix_diag(
+    k, X; obsdim=obsdim
+)
+@deprecate kerneldiagmatrix(
+    k::Kernel, X::AbstractMatrix, Y::AbstractMatrix; obsdim::Int=defaultobs
+) kernelmatrix_diag(k, X, Y; obsdim=obsdim)
+@deprecate kerneldiagmatrix!(K, k::Kernel, X::AbstractMatrix; obsdim::Int=defaultobs) kernelmatrix_diag!(
+    K, k, X; obsdim=obsdim
+)
+@deprecate kerneldiagmatrix!(
+    K, k::Kernel, X::AbstractMatrix, Y::AbstractMatrix; obsdim::Int=defaultobs
+) kernelmatrix_diag!(K, k, X, Y; obsdim=obsdim)
diff --git a/src/kernels/kernelproduct.jl b/src/kernels/kernelproduct.jl
@@ -53,8 +53,8 @@ function kernelmatrix(κ::KernelProduct, x::AbstractVector, y::AbstractVector)
     return reduce(hadamard, kernelmatrix(k, x, y) for k in κ.kernels)
 end
 
-function kerneldiagmatrix(κ::KernelProduct, x::AbstractVector)
-    return reduce(hadamard, kerneldiagmatrix(k, x) for k in κ.kernels)
+function kernelmatrix_diag(κ::KernelProduct, x::AbstractVector)
+    return reduce(hadamard, kernelmatrix_diag(k, x) for k in κ.kernels)
 end
 
 function Base.show(io::IO, κ::KernelProduct)
diff --git a/src/kernels/kernelsum.jl b/src/kernels/kernelsum.jl
@@ -53,8 +53,8 @@ function kernelmatrix(κ::KernelSum, x::AbstractVector, y::AbstractVector)
     return sum(kernelmatrix(k, x, y) for k in κ.kernels)
 end
 
-function kerneldiagmatrix(κ::KernelSum, x::AbstractVector)
-    return sum(kerneldiagmatrix(k, x) for k in κ.kernels)
+function kernelmatrix_diag(κ::KernelSum, x::AbstractVector)
+    return sum(kernelmatrix_diag(k, x) for k in κ.kernels)
 end
 
 function Base.show(io::IO, κ::KernelSum)
diff --git a/src/kernels/kerneltensorproduct.jl b/src/kernels/kerneltensorproduct.jl
@@ -95,14 +95,14 @@ function kernelmatrix!(
     return K
 end
 
-function kerneldiagmatrix!(K::AbstractVector, k::KernelTensorProduct, x::AbstractVector)
+function kernelmatrix_diag!(K::AbstractVector, k::KernelTensorProduct, x::AbstractVector)
     validate_inplace_dims(K, x)
     validate_domain(k, x)
 
     kernels_and_inputs = zip(k.kernels, slices(x))
-    kerneldiagmatrix!(K, first(kernels_and_inputs)...)
+    kernelmatrix_diag!(K, first(kernels_and_inputs)...)
     for (k, xi) in Iterators.drop(kernels_and_inputs, 1)
-        K .*= kerneldiagmatrix(k, xi)
+        K .*= kernelmatrix_diag(k, xi)
     end
 
     return K
@@ -118,9 +118,9 @@ function kernelmatrix(k::KernelTensorProduct, x::AbstractVector, y::AbstractVect
     return mapreduce(kernelmatrix, hadamard, k.kernels, slices(x), slices(y))
 end
 
-function kerneldiagmatrix(k::KernelTensorProduct, x::AbstractVector)
+function kernelmatrix_diag(k::KernelTensorProduct, x::AbstractVector)
     validate_domain(k, x)
-    return mapreduce(kerneldiagmatrix, hadamard, k.kernels, slices(x))
+    return mapreduce(kernelmatrix_diag, hadamard, k.kernels, slices(x))
 end
 
 Base.show(io::IO, kernel::KernelTensorProduct) = printshifted(io, kernel, 0)
diff --git a/src/kernels/scaledkernel.jl b/src/kernels/scaledkernel.jl
@@ -33,8 +33,8 @@ function kernelmatrix(κ::ScaledKernel, x::AbstractVector)
     return κ.σ² .* kernelmatrix(κ.kernel, x)
 end
 
-function kerneldiagmatrix(κ::ScaledKernel, x::AbstractVector)
-    return κ.σ² .* kerneldiagmatrix(κ.kernel, x)
+function kernelmatrix_diag(κ::ScaledKernel, x::AbstractVector)
+    return κ.σ² .* kernelmatrix_diag(κ.kernel, x)
 end
 
 function kernelmatrix!(
@@ -51,8 +51,8 @@ function kernelmatrix!(K::AbstractMatrix, κ::ScaledKernel, x::AbstractVector)
     return K
 end
 
-function kerneldiagmatrix!(K::AbstractVector, κ::ScaledKernel, x::AbstractVector)
-    kerneldiagmatrix!(K, κ, x)
+function kernelmatrix_diag!(K::AbstractVector, κ::ScaledKernel, x::AbstractVector)
+    kernelmatrix_diag!(K, κ, x)
     K .*= κ.σ²
     return K
 end
diff --git a/src/kernels/transformedkernel.jl b/src/kernels/transformedkernel.jl
@@ -76,8 +76,8 @@ end
 
 # Kernel matrix operations
 
-function kerneldiagmatrix!(K::AbstractVector, κ::TransformedKernel, x::AbstractVector)
-    return kerneldiagmatrix!(K, κ.kernel, _map(κ.transform, x))
+function kernelmatrix_diag!(K::AbstractVector, κ::TransformedKernel, x::AbstractVector)
+    return kernelmatrix_diag!(K, κ.kernel, _map(κ.transform, x))
 end
 
 function kernelmatrix!(K::AbstractMatrix, κ::TransformedKernel, x::AbstractVector)
@@ -90,8 +90,8 @@ function kernelmatrix!(
     return kernelmatrix!(K, kernel(κ), _map(κ.transform, x), _map(κ.transform, y))
 end
 
-function kerneldiagmatrix(κ::TransformedKernel, x::AbstractVector)
-    return kerneldiagmatrix(κ.kernel, _map(κ.transform, x))
+function kernelmatrix_diag(κ::TransformedKernel, x::AbstractVector)
+    return kernelmatrix_diag(κ.kernel, _map(κ.transform, x))
 end
 
 function kernelmatrix(κ::TransformedKernel, x::AbstractVector)
diff --git a/src/matrix/kernelmatrix.jl b/src/matrix/kernelmatrix.jl
@@ -18,26 +18,26 @@ Calculate the kernel matrix of `X` (and `Y`) with respect to kernel `κ`.
 kernelmatrix
 
 """
-    kerneldiagmatrix!(K::AbstractVector, κ::Kernel, X; obsdim::Int = 2)
-    kerneldiagmatrix!(K::AbstractVector, κ::Kernel, X, Y; obsdim::Int = 2)
+    kernelmatrix_diag!(K::AbstractVector, κ::Kernel, X; obsdim::Int = 2)
+    kernelmatrix_diag!(K::AbstractVector, κ::Kernel, X, Y; obsdim::Int = 2)
 
-In place version of [`kerneldiagmatrix`](@ref)
+In place version of [`kernelmatrix_diag`](@ref)
 """
-kerneldiagmatrix!
+kernelmatrix_diag!
 
 """
-    kerneldiagmatrix(κ::Kernel, X; obsdim::Int = 2)
+    kernelmatrix_diag(κ::Kernel, X; obsdim::Int = 2)
 
 Calculate the diagonal matrix of `X` with respect to kernel `κ`
 `obsdim = 1` means the matrix `X` has size #samples x #dimension
 `obsdim = 2` means the matrix `X` has size #dimension x #samples
 
-    kerneldiagmatrix(κ::Kernel, X, Y; obsdim::Int = 2)
+    kernelmatrix_diag(κ::Kernel, X, Y; obsdim::Int = 2)
 
 Calculate the diagonal of `kernelmatrix(κ, X, Y; obsdim)` efficiently. Requires that `X` and
 `Y` are the same length.
 """
-kerneldiagmatrix
+kernelmatrix_diag
 
 #
 # Kernel implementations. Generic fallbacks that depend only on kernel evaluation.
@@ -58,20 +58,20 @@ function kernelmatrix(κ::Kernel, x::AbstractVector, y::AbstractVector)
     return κ.(x, permutedims(y))
 end
 
-function kerneldiagmatrix!(K::AbstractVector, κ::Kernel, x::AbstractVector)
+function kernelmatrix_diag!(K::AbstractVector, κ::Kernel, x::AbstractVector)
     validate_inplace_dims(K, x)
     return map!(x -> κ(x, x), K, x)
 end
 
-function kerneldiagmatrix!(
+function kernelmatrix_diag!(
     K::AbstractVector, κ::Kernel, x::AbstractVector, y::AbstractVector
 )
-    return map!(κ, x, y)
+    return map!(κ, K, x, y)
 end
 
-kerneldiagmatrix(κ::Kernel, x::AbstractVector) = map(x -> κ(x, x), x)
+kernelmatrix_diag(κ::Kernel, x::AbstractVector) = map(x -> κ(x, x), x)
 
-kerneldiagmatrix(κ::Kernel, x::AbstractVector, y::AbstractVector) = map(κ, x, y)
+kernelmatrix_diag(κ::Kernel, x::AbstractVector, y::AbstractVector) = map(κ, x, y)
 
 #
 # SimpleKernel optimisations.
@@ -130,30 +130,32 @@ function kernelmatrix(κ::Kernel, X::AbstractMatrix, Y::AbstractMatrix; obsdim=d
     return kernelmatrix(κ, vec_of_vecs(X; obsdim=obsdim), vec_of_vecs(Y; obsdim=obsdim))
 end
 
-function kerneldiagmatrix!(
+function kernelmatrix_diag!(
     K::AbstractVector, κ::Kernel, X::AbstractMatrix; obsdim::Int=defaultobs
 )
-    return kerneldiagmatrix!(K, κ, vec_of_vecs(X; obsdim=obsdim))
+    return kernelmatrix_diag!(K, κ, vec_of_vecs(X; obsdim=obsdim))
 end
 
-function kerneldiagmatrix!(
+function kernelmatrix_diag!(
     K::AbstractVector,
     κ::Kernel,
     X::AbstractMatrix,
     Y::AbstractMatrix;
     obsdim::Int=defaultobs,
 )
-    return kerneldiagmatrix!(
+    return kernelmatrix_diag!(
         K, κ, vec_of_vecs(X; obsdim=obsdim), vec_of_vecs(Y; obsdim=obsdim)
     )
 end
 
-function kerneldiagmatrix(κ::Kernel, X::AbstractMatrix; obsdim::Int=defaultobs)
-    return kerneldiagmatrix(κ, vec_of_vecs(X; obsdim=obsdim))
+function kernelmatrix_diag(κ::Kernel, X::AbstractMatrix; obsdim::Int=defaultobs)
+    return kernelmatrix_diag(κ, vec_of_vecs(X; obsdim=obsdim))
 end
 
-function kerneldiagmatrix(
+function kernelmatrix_diag(
     κ::Kernel, X::AbstractMatrix, Y::AbstractMatrix; obsdim::Int=defaultobs
 )
-    return kerneldiagmatrix(κ, vec_of_vecs(X; obsdim=obsdim), vec_of_vecs(Y; obsdim=obsdim))
+    return kernelmatrix_diag(
+        κ, vec_of_vecs(X; obsdim=obsdim), vec_of_vecs(Y; obsdim=obsdim)
+    )
 end
diff --git a/src/test_utils.jl b/src/test_utils.jl
@@ -41,38 +41,38 @@ function test_interface(
     @assert length(x0) == length(x1)
     @assert length(x0) ≠ length(x2)
 
-    # Check that kerneldiagmatrix basically works.
-    @test kerneldiagmatrix(k, x0, x1) isa AbstractVector
-    @test length(kerneldiagmatrix(k, x0, x1)) == length(x0)
+    # Check that kernelmatrix_diag basically works.
+    @test kernelmatrix_diag(k, x0, x1) isa AbstractVector
+    @test length(kernelmatrix_diag(k, x0, x1)) == length(x0)
 
     # Check that pairwise basically works.
     @test kernelmatrix(k, x0, x2) isa AbstractMatrix
     @test size(kernelmatrix(k, x0, x2)) == (length(x0), length(x2))
 
     # Check that elementwise is consistent with pairwise.
-    @test kerneldiagmatrix(k, x0, x1) ≈ diag(kernelmatrix(k, x0, x1)) atol = atol
+    @test kernelmatrix_diag(k, x0, x1) ≈ diag(kernelmatrix(k, x0, x1)) atol = atol
 
     # Check additional binary elementwise properties for kernels.
-    @test kerneldiagmatrix(k, x0, x1) ≈ kerneldiagmatrix(k, x1, x0)
+    @test kernelmatrix_diag(k, x0, x1) ≈ kernelmatrix_diag(k, x1, x0)
     @test kernelmatrix(k, x0, x2) ≈ kernelmatrix(k, x2, x0)' atol = atol
 
     # Check that unary elementwise basically works.
-    @test kerneldiagmatrix(k, x0) isa AbstractVector
-    @test length(kerneldiagmatrix(k, x0)) == length(x0)
+    @test kernelmatrix_diag(k, x0) isa AbstractVector
+    @test length(kernelmatrix_diag(k, x0)) == length(x0)
 
     # Check that unary pairwise basically works.
     @test kernelmatrix(k, x0) isa AbstractMatrix
     @test size(kernelmatrix(k, x0)) == (length(x0), length(x0))
     @test kernelmatrix(k, x0) ≈ kernelmatrix(k, x0)' atol = atol
 
     # Check that unary elementwise is consistent with unary pairwise.
-    @test kerneldiagmatrix(k, x0) ≈ diag(kernelmatrix(k, x0)) atol = atol
+    @test kernelmatrix_diag(k, x0) ≈ diag(kernelmatrix(k, x0)) atol = atol
 
     # Check that unary pairwise produces a positive definite matrix (approximately).
     @test eigmin(Matrix(kernelmatrix(k, x0))) > -atol
 
     # Check that unary elementwise / pairwise are consistent with the binary versions.
-    @test kerneldiagmatrix(k, x0) ≈ kerneldiagmatrix(k, x0, x0) atol = atol rtol = rtol
+    @test kernelmatrix_diag(k, x0) ≈ kernelmatrix_diag(k, x0, x0) atol = atol rtol = rtol
     @test kernelmatrix(k, x0) ≈ kernelmatrix(k, x0, x0) atol = atol rtol = rtol
 
     # Check that basic kernel evaluation succeeds and is consistent with `kernelmatrix`.
@@ -86,7 +86,7 @@ function test_interface(
     @test kernelmatrix!(tmp_square, k, x0) ≈ kernelmatrix(k, x0)
 
     tmp_diag = Vector{Float64}(undef, length(x0))
-    @test kerneldiagmatrix!(tmp_diag, k, x0) ≈ kerneldiagmatrix(k, x0)
+    @test kernelmatrix_diag!(tmp_diag, k, x0) ≈ kernelmatrix_diag(k, x0)
 end
 
 function test_interface(
diff --git a/test/matrix/kernelmatrix.jl b/test/matrix/kernelmatrix.jl
