Add RationalKernel and rename GammaRationalQuadraticKernel

Project.toml

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

docs/src/kernels.md

@@ -88,11 +88,12 @@ LinearKernel
 PolynomialKernel
 ```
 
-### Rational Quadratic Kernels
+### Rational Kernels
 
 ```@docs
+RationalKernel
 RationalQuadraticKernel
-GammaRationalQuadraticKernel
+GammaRationalKernel
 ```
 
 ### Spectral Mixture Kernels

src/KernelFunctions.jl

@@ -13,7 +13,7 @@ export ExponentiatedKernel
 export FBMKernel
 export MaternKernel, Matern12Kernel, Matern32Kernel, Matern52Kernel
 export LinearKernel, PolynomialKernel
-export RationalQuadraticKernel, GammaRationalQuadraticKernel
+export RationalKernel, RationalQuadraticKernel, GammaRationalKernel
 export GaborKernel, PiecewisePolynomialKernel
 export PeriodicKernel, NeuralNetworkKernel
 export KernelSum, KernelProduct, KernelTensorProduct
@@ -84,7 +84,7 @@ include(joinpath("basekernels", "nn.jl"))
 include(joinpath("basekernels", "periodic.jl"))
 include(joinpath("basekernels", "piecewisepolynomial.jl"))
 include(joinpath("basekernels", "polynomial.jl"))
-include(joinpath("basekernels", "rationalquad.jl"))
+include(joinpath("basekernels", "rational.jl"))
 include(joinpath("basekernels", "sm.jl"))
 include(joinpath("basekernels", "wiener.jl"))
 

src/basekernels/exponential.jl

@@ -98,15 +98,30 @@ For inputs ``x, x' \\in \\mathbb{R}^d``, the γ-exponential kernel[^RW] with par
 k(x, x'; \\gamma) = \\exp\\big(- \\|x - x'\\|_2^{\\gamma}\\big).
 ```
 
+!!! warning
+    The default value of parameter `γ` will be changed to `1.0` in the next breaking release
+    of KernelFunctions.
+
 See also: [`ExponentialKernel`](@ref), [`SqExponentialKernel`](@ref)
 
 [^RW]: C. E. Rasmussen & C. K. I. Williams (2006). Gaussian Processes for Machine Learning.
 """
 struct GammaExponentialKernel{Tγ<:Real} <: SimpleKernel
     γ::Vector{Tγ}
-    function GammaExponentialKernel(; gamma::Real=2.0, γ::Real=gamma)
-        @check_args(GammaExponentialKernel, γ, zero(γ) < γ ≤ 2, "γ ∈ (0, 2]")
-        return new{typeof(γ)}([γ])
+    # function GammaExponentialKernel(; gamma::Real=1.0, γ::Real=gamma)
+    function GammaExponentialKernel(; gamma=nothing, γ=gamma)
+        γ2 = if γ === nothing
+            Base.depwarn(
+                "the default value of parameter `γ` of the `GammaExponentialKernel` will " *
+                "be changed to `1.0` in the next breaking release of KernelFunctions",
+                :GammaExponentialKernel,
+            )
+            2.0
+        else
+            γ
+        end
+        @check_args(GammaExponentialKernel, γ2, zero(γ2) < γ2 ≤ 2, "γ ∈ (0, 2]")
+        return new{typeof(γ2)}([γ2])
     end
 end
 

src/basekernels/rational.jl

@@ -0,0 +1,129 @@
+"""
+    RationalKernel(; α::Real=2.0)
+
+Rational kernel with shape parameter `α`.
+
+# Definition
+
+For inputs ``x, x' \\in \\mathbb{R}^d``, the rational kernel with shape parameter
+``\\alpha > 0`` is defined as
+```math
+k(x, x'; \\alpha) = \\bigg(1 + \\frac{\\|x - x'\\|_2}{\\alpha}\\bigg)^{-\\alpha}.
+```
+
+The [`ExponentialKernel`](@ref) is recovered in the limit as ``\\alpha \\to \\infty``.
+
+See also: [`GammaRationalKernel`](@ref)
+"""
+struct RationalKernel{Tα<:Real} <: SimpleKernel
+    α::Vector{Tα}
+    function RationalKernel(; alpha::T=2.0, α::T=alpha) where {T}
+        @check_args(RationalKernel, α, α > zero(T), "α > 0")
+        return new{T}([α])
+    end
+end
+
+@functor RationalKernel
+
+function kappa(κ::RationalKernel, d::Real)
+    return (one(d) + d / first(κ.α))^(-first(κ.α))
+end
+
+metric(::RationalKernel) = Euclidean()
+
+function Base.show(io::IO, κ::RationalKernel)
+    return print(io, "Rational Kernel (α = $(first(κ.α)))")
+end
+
+"""
+    RationalQuadraticKernel(; α::Real=2.0)
+
+Rational-quadratic kernel with shape parameter `α`.
+
+# Definition
+
+For inputs ``x, x' \\in \\mathbb{R}^d``, the rational-quadratic kernel with shape parameter
+``\\alpha > 0`` is defined as
+```math
+k(x, x'; \\alpha) = \\bigg(1 + \\frac{\\|x - x'\\|_2^2}{2\\alpha}\\bigg)^{-\\alpha}.
+```
+
+The [`SqExponentialKernel`](@ref) is recovered in the limit as ``\\alpha \\to \\infty``.
+
+See also: [`GammaRationalKernel`](@ref)
+"""
+struct RationalQuadraticKernel{Tα<:Real} <: SimpleKernel
+    α::Vector{Tα}
+    function RationalQuadraticKernel(; alpha::T=2.0, α::T=alpha) where {T}
+        @check_args(RationalQuadraticKernel, α, α > zero(T), "α > 0")
+        return new{T}([α])
+    end
+end
+
+@functor RationalQuadraticKernel
+
+function kappa(κ::RationalQuadraticKernel, d²::T) where {T<:Real}
+    return (one(T) + d² / (2 * first(κ.α)))^(-first(κ.α))
+end
+
+metric(::RationalQuadraticKernel) = SqEuclidean()
+
+function Base.show(io::IO, κ::RationalQuadraticKernel)
+    return print(io, "Rational Quadratic Kernel (α = $(first(κ.α)))")
+end
+
+"""
+    GammaRationalKernel(; α::Real=2.0, γ::Real=2.0)
+
+γ-rational kernel with shape parameters `α` and `γ`.
+
+# Definition
+
+For inputs ``x, x' \\in \\mathbb{R}^d``, the γ-rational kernel with shape
+parameters ``\\alpha > 0`` and ``\\gamma \\in (0, 2]`` is defined as
+```math
+k(x, x'; \\alpha, \\gamma) = \\bigg(1 + \\frac{\\|x - x'\\|_2^{\\gamma}}{\\alpha}\\bigg)^{-\\alpha}.
+```
+
+The [`GammaExponentialKernel`](@ref) is recovered in the limit as ``\\alpha \\to \\infty``.
+
+!!! warning
+    The default value of parameter `γ` will be changed to `1.0` in the next breaking release
+    of KernelFunctions.
+
+See also: [`RationalKernel`](@ref), [`RationalQuadraticKernel`](@ref)
+"""
+struct GammaRationalKernel{Tα<:Real,Tγ<:Real} <: SimpleKernel
+    α::Vector{Tα}
+    γ::Vector{Tγ}
+    # function GammaRationalKernel(;
+    #     alpha::Real=2.0, gamma::Real=1.0, α::Real=alpha, γ::Real=gamma
+    # )
+    function GammaRationalKernel(; alpha::Real=2.0, gamma=nothing, α::Real=alpha, γ=gamma)
+        γ2 = if γ === nothing
+            Base.depwarn(
+                "the default value of parameter `γ` of the `GammaRationalKernel` will " *
+                "be changed to `1.0` in the next breaking release of KernelFunctions",
+                :GammaRationalKernel,
+            )
+            2.0
+        else
+            γ
+        end
+        @check_args(GammaRationalKernel, α, α > zero(α), "α > 0")
+        @check_args(GammaRationalKernel, γ2, zero(γ2) < γ2 ≤ 2, "γ ∈ (0, 2]")
+        return new{typeof(α),typeof(γ2)}([α], [γ2])
+    end
+end
+
+@functor GammaRationalKernel
+
+function kappa(κ::GammaRationalKernel, d::Real)
+    return (one(d) + d^first(κ.γ) / first(κ.α))^(-first(κ.α))
+end
+
+metric(::GammaRationalKernel) = Euclidean()
+
+function Base.show(io::IO, κ::GammaRationalKernel)
+    return print(io, "Gamma Rational Kernel (α = $(first(κ.α)), γ = $(first(κ.γ)))")
+end

src/deprecations.jl

@@ -2,3 +2,7 @@
 @deprecate transform(k::TransformedKernel, t::Transform) k.kernel ∘ t ∘ k.transform
 @deprecate transform(k::Kernel, ρ::Real) k ∘ ScaleTransform(ρ)
 @deprecate transform(k::Kernel, ρ::AbstractVector) k ∘ ARDTransform(ρ)
+
+# TODO: Remove deprecations in the constructors and docstrings of `GammaExponentialKernel`
+# and `GammaRationalKernel`
+Base.@deprecate_binding GammaRationalQuadraticKernel GammaRationalKernel