Corrected docs and tests

Author: theogf

docs/src/api.md

@@ -28,6 +28,9 @@ LinearKernel
 PolynomialKernel
 RationalQuadraticKernel
 GammaRationalQuadraticKernel
+ZeroKernel
+ConstantKernel
+WhiteKernel
 ```
 
 ## Kernel Combinations

docs/src/kernels.md

@@ -1,34 +1,93 @@
 ```@meta
-CurrentModule = KernelFunctions
+  CurrentModule = KernelFunctions
 ```
 
 ## Exponential Kernels
 
-```@docs
-ExponentialKernel
-SqExponentialKernel
-GammaExponentialKernel
+### Exponential Kernel
+
+The [Exponential Kernel](@ref ExponentialKernel) is defined as
+```math
+  k(x,x') = \exp\left(-|x-x'|\right)
+```
+
+### Square Exponential Kernel
+
+The [Square Exponential Kernel](@ref KernelFunctions.SqExponentialKernel) is defined as 
+```math
+  k(x,x') = \exp\left(-\|x-x'\|^2\right)
+```
+
+### Gamma Exponential Kernel
+
+```math
+  k(x,x';\gamma) = \exp\left(-\|x-x'\|^{2\gamma}\right)
 ```
 
 ## Matern Kernels
 
-```@docs
-MaternKernel
-Matern32Kernel
-Matern52Kernel
+### Matern Kernel
+
+```math
+  k(x,x';\nu) = \frac{2^{1-\nu}}{\Gamma(\nu)}\left(\sqrt{2\nu}|x-x'|\right)K_\nu\left(\sqrt{2\nu}|x-x'|\right)
+```
+
+### Matern 3/2 Kernel
+
+```math
+  k(x,x') = \left(1+\sqrt{3}|x-x'|\right)\exp\left(\sqrt{3}|x-x'|\right)
+```
+
+### Matern 5/2 Kernel
+
+```math
+  k(x,x') = \left(1+\sqrt{5}|x-x'|+\frac{5}{2}\|x-x'\|^2\right)\exp\left(\sqrt{5}|x-x'|\right)
+```
+
+## Rational Quadratic
+
+### Rational Quadratic Kernel
+
+```math
+  k(x,x';\alpha) = \left(1+\frac{\|x-x'\|^2}{\alpha}\right)^{-\alpha}
+```
+
+### Gamma Rational Quadratic Kernel
+
+```math
+  k(x,x';\alpha,\gamma) = \left(1+\frac{\|x-x'\|^{2\gamma}}{\alpha}\right)^{-\alpha}
 ```
 
 ## Polynomial Kernels
 
-```@docs
-LinearKernel
-PolynomialKernel
+### LinearKernel
+
+```math
+  k(x,x';c) = \langle x,x'\rangle + c
+```
+
+### PolynomialKernel
+
+```math
+  k(x,x';c,d) = \left(\langle x,x'\rangle + c\right)^d
 ```
 
 ## Constant Kernels
 
-```@docs
-ConstantKernel
-WhiteKernel
-ZeroKernel
+### ConstantKernel
+
+```math
+  k(x,x';c) = c
+```
+
+### WhiteKernel
+
+```math
+  k(x,x') = \delta(x-x')
+```
+
+### ZeroKernel
+
+```math
+  k(x,x') = 0
 ```

docs/src/transform.md

@@ -7,6 +7,9 @@ You can also create a pipeline of `Transform` via `TransformChain`. For example
 One apply a transformation on a matrix or a vector via `transform(t::Transform,v::AbstractVecOrMat)`
 
 ## Transforms :
+```@meta
+CurrentModule = KernelFunctions
+```
 
 ```@docs
   IdentityTransform

src/kernels/constant.jl

@@ -1,8 +1,7 @@
 """
-    ZeroKernel([tr=IdentityTransform()])
-
-    Create a kernel that always return a zero kernel matrix
+ZeroKernel([tr=IdentityTransform()])
 
+Create a kernel always returning zero
 """
 struct ZeroKernel{T,Tr} <: Kernel{T,Tr}
     transform::Tr
@@ -19,12 +18,12 @@ end
 @inline kappa(κ::ZeroKernel,d::T) where {T<:Real} = zero(T)
 
 """
-    WhiteKernel([tr=IdentityTransform()])
+`WhiteKernel([tr=IdentityTransform()])`
 
 ```
     κ(x,y) = δ(x,y)
 ```
-    Kernel function working as an equivalent to add white noise.
+Kernel function working as an equivalent to add white noise.
 """
 struct WhiteKernel{T,Tr} <: Kernel{T,Tr}
     transform::Tr
@@ -41,12 +40,11 @@ end
 @inline kappa(κ::WhiteKernel,δₓₓ::Real) = δₓₓ
 
 """
-    ConstantKernel([tr=IdentityTransform(),[c=1.0]])
-
+`ConstantKernel([tr=IdentityTransform(),[c=1.0]])`
 ```
     κ(x,y) = c
 ```
-    Kernel function always returning a constant value `c`
+Kernel function always returning a constant value `c`
 """
 struct ConstantKernel{T,Tr,Tc<:Real} <: Kernel{T,Tr}
     transform::Tr

src/kernels/exponential.jl

@@ -1,12 +1,10 @@
 """
-    SqExponentialKernel([ρ=1.0])
+`SqExponentialKernel([ρ=1.0])`
 
 The squared exponential kernel is an isotropic Mercer kernel given by the formula:
-
 ```
     κ(x,y) = exp(-ρ²‖x-y‖²)
 ```
-
 See also [`ExponentialKernel`](@ref) for a
 related form of the kernel or [`GammaExponentialKernel`](@ref) for a generalization.
 """
@@ -26,14 +24,11 @@ const RBFKernel = SqExponentialKernel
 const GaussianKernel = SqExponentialKernel
 
 """
-    ExponentialKernel([ρ=1.0])
-
+`ExponentialKernel([ρ=1.0])`
 The exponential kernel is an isotropic Mercer kernel given by the formula:
-
 ```
     κ(x,y) = exp(-ρ‖x-y‖)
 ```
-
 """
 struct ExponentialKernel{T,Tr} <: Kernel{T,Tr}
     transform::Tr
@@ -50,10 +45,8 @@ end
 const LaplacianKernel = ExponentialKernel
 
 """
-    GammaExponentialKernel([ρ=1.0,[gamma=2.0]])
-
+`GammaExponentialKernel([ρ=1.0,[gamma=2.0]])`
 The γ-exponential kernel is an isotropic Mercer kernel given by the formula:
-
 ```
     κ(x,y) = exp(-ρ^(2γ)‖x-y‖^(2γ))
 ```
@@ -69,7 +62,7 @@ end
 
 function GammaExponentialKernel(ρ::T₁=1.0,gamma::T₂=2.0) where {T₁<:Real,T₂<:Real}
     @check_args(GammaExponentialKernel, gamma, gamma >= zero(T₂), "gamma > 0")
-    GammaExponentialKernel{T₁,ScaleTransform{T₁},T₂}(ScaleTransform(ρ),gamma)
+    GammaExponentialKernel{T₁,ScaleTransform{Base.RefValue{T₁}},T₂}(ScaleTransform(ρ),gamma)
 end
 
 function GammaExponentialKernel(ρ::A,gamma::T₁=2.0) where {A<:AbstractVector{<:Real},T₁<:Real}

src/kernels/exponentiated.jl

@@ -1,10 +1,8 @@
 """
-    ExponentiatedKernel([ρ=1])
-
-    The exponentiated kernel is a Mercer kernel given by:
-
+`ExponentiatedKernel([ρ=1])`
+The exponentiated kernel is a Mercer kernel given by:
 ```
-        κ(x,y) = exp(xᵀy)
+    κ(x,y) = exp(ρ²xᵀy)
 ```
 """
 struct ExponentiatedKernel{T,Tr} <: Kernel{T,Tr}

src/kernels/kernelproduct.jl

@@ -1,9 +1,13 @@
 """
-    KernelProduct(kernels::Array{Kernel})
+`KernelProduct(kernels::Array{Kernel})`
 Create a multiplication of kernels.
 One can also use the operator `*`
 ```
-    kernelmatrix(SqExponentialKernel()*LinearKernel(),X) == kernelmatrix(SqExponentialKernel(),X).*kernelmatrix(LinearKernel(),X)
+k1 = SqExponentialKernel()
+k2 = LinearKernel()
+k = KernelProduct([k1,k2])
+kernelmatrix(k,X) == kernelmatrix(k1,X).*kernelmatrix(k2,X)
+kernelmatrix(k,X) == kernelmatrix(k1*k2,X)
 ```
 """
 struct KernelProduct{T,Tr} <: Kernel{T,Tr}

src/kernels/kernelsum.jl

@@ -1,9 +1,14 @@
 """
-    KernelSum(kernels::Array{Kernel};weights::Array{Real}=ones(length(kernels)))
+`KernelSum(kernels::Array{Kernel};weights::Array{Real}=ones(length(kernels)))`
 Create a positive weighted sum of kernels.
 One can also use the operator `+`
 ```
-    kernelmatrix(SqExponentialKernel()+LinearKernel(),X) == kernelmatrix(SqExponentialKernel(),X).+kernelmatrix(LinearKernel(),X)
+k1 = SqExponentialKernel()
+k2 = LinearKernel()
+k = KernelSum([k1,k2])
+kernelmatrix(k,X) == kernelmatrix(k1,X).+kernelmatrix(k2,X)
+kernelmatrix(k,X) == kernelmatrix(k1+k2,X)
+kweighted = 0.5*k1 + 2.0*k2
 ```
 """
 struct KernelSum{T,Tr} <: Kernel{T,Tr}

src/kernels/matern.jl

@@ -1,15 +1,10 @@
 """
-    MaternKernel([ρ=1.0,[ν=1.0]])
-
+`MaternKernel([ρ=1.0,[ν=1.0]])`
 The matern kernel is an isotropic Mercer kernel given by the formula:
-
 ```
     κ(x,y) = 2^{1-ν}/Γ(ν)*(√(2ν)‖x-y‖)^ν K_ν(√(2ν)‖x-y‖)
 ```
-
-For `ν=n+1/2, n=0,1,2,...` it can be simplified and you should instead use `ExponentialKernel` for `n=0`, `Matern32Kernel`, for `n=1`, Matern52Kernel for `n=2` and `SqExponentialKernel` for `n=∞`.
-`ρ` is the lengthscale parameter(s) or the transform object.
-
+For `ν=n+1/2, n=0,1,2,...` it can be simplified and you should instead use [`ExponentialKernel`](@ref) for `n=0`, [`Matern32Kernel`](@ref), for `n=1`, [`Matern52Kernel`](@ref) for `n=2` and [`SqExponentialKernel`](@ref) for `n=∞`.
 """
 struct MaternKernel{T,Tr,Tν<:Real} <: Kernel{T,Tr}
     transform::Tr
@@ -22,7 +17,7 @@ end
 
 function MaternKernel(ρ::T₁=1.0,ν::T₂=1.5) where {T₁<:Real,T₂<:Real}
     @check_args(MaternKernel, ν, ν > zero(T₂), "ν > 0")
-    MaternKernel{T₁,ScaleTransform{T₁},T₂}(ScaleTransform(ρ),ν)
+    MaternKernel{T₁,ScaleTransform{Base.RefValue{T₁}},T₂}(ScaleTransform(ρ),ν)
 end
 
 function MaternKernel(ρ::A,ν::T=1.5) where {A<:AbstractVector{<:Real},T<:Real}
@@ -38,15 +33,11 @@ end
 @inline kappa(κ::MaternKernel, d::Real) = iszero(d) ? one(d) : exp((1.0-κ.ν)*logtwo-lgamma(κ.ν) + κ.ν*log(sqrt(2κ.ν)*d)+log(besselk(κ.ν,sqrt(2κ.ν)*d)))
 
 """
-    Matern32Kernel([ρ=1.0])
-
+`Matern32Kernel([ρ=1.0])`
 The matern 3/2 kernel is an isotropic Mercer kernel given by the formula:
-
 ```
-    κ(x,y) = (1+√(3)‖x-y‖)exp(√(3)‖x-y‖)
+    κ(x,y) = (1+√(3)ρ‖x-y‖)exp(-√(3)ρ‖x-y‖)
 ```
-
-`ρ` is the lengthscale parameter(s) or a transform object.
 """
 struct Matern32Kernel{T,Tr} <: Kernel{T,Tr}
     transform::Tr
@@ -59,16 +50,11 @@ end
 @inline kappa(κ::Matern32Kernel, d::T) where {T<:Real} = (1+sqrt(3)*d)*exp(-sqrt(3)*d)
 
 """
-    Matern52Kernel([ρ=1.0])
-
+`Matern52Kernel([ρ=1.0])`
 The matern 5/2 kernel is an isotropic Mercer kernel given by the formula:
-
 ```
-    κ(x,y) = (1+√(5)‖x-y‖ + 5‖x-y‖^2/3)exp(√(5)‖x-y‖)
+    κ(x,y) = (1+√(5)ρ‖x-y‖ + 5ρ²‖x-y‖^2/3)exp(-√(5)ρ‖x-y‖)
 ```
-
-`ρ` is the lengthscale parameter(s) or a transform object.
-
 """
 struct Matern52Kernel{T,Tr} <: Kernel{T,Tr}
     transform::Tr

src/kernels/polynomial.jl

@@ -1,11 +1,10 @@
 """
-    LinearKernel([ρ=1.0,[c=0.0]])
-
-    The linear kernel is a Mercer kernel given by
+`LinearKernel([ρ=1.0,[c=0.0]])`
+The linear kernel is a Mercer kernel given by
 ```
-    κ(x,y) = xᵀy + c
+    κ(x,y) = ρ²xᵀy + c
 ```
-    Where `c` is a real number
+Where `c` is a real number
 """
 struct LinearKernel{T,Tr,Tc<:Real} <: Kernel{T,Tr}
     transform::Tr
@@ -17,7 +16,7 @@ struct LinearKernel{T,Tr,Tc<:Real} <: Kernel{T,Tr}
 end
 
 function LinearKernel(ρ::T₁=1.0,c::T₂=zero(T₁)) where {T₁<:Real,T₂<:Real}
-    LinearKernel{T₁,ScaleTransform{T₁},T₂}(ScaleTransform(ρ),c)
+    LinearKernel{T₁,ScaleTransform{Base.RefValue{T₁}},T₂}(ScaleTransform(ρ),c)
 end
 
 function LinearKernel(ρ::A,c::T=zero(eltype(ρ))) where {A<:AbstractVector{<:Real},T<:Real}
@@ -31,13 +30,12 @@ end
 @inline kappa(κ::LinearKernel, xᵀy::T) where {T<:Real} = xᵀy + κ.c
 
 """
-    PolynomialKernel([ρ=1.0[,d=2.0[,c=0.0]]])
-
-    The polynomial kernel is a Mercer kernel given by
+`PolynomialKernel([ρ=1.0[,d=2.0[,c=0.0]]])`
+The polynomial kernel is a Mercer kernel given by
 ```
-    κ(x,y) = (xᵀy + c)^d
+    κ(x,y) = (ρ²xᵀy + c)^d
 ```
-    Where `c` is a real number, and `d` is a shape parameter bigger than 1
+Where `c` is a real number, and `d` is a shape parameter bigger than 1
 """
 struct PolynomialKernel{T,Tr,Tc<:Real,Td<:Real} <: Kernel{T,Tr}
     transform::Tr
@@ -51,7 +49,7 @@ end
 
 function PolynomialKernel(ρ::T₁=1.0,d::T₂=2.0,c::T₃=zero(T₁)) where {T₁<:Real,T₂<:Real,T₃<:Real}
     @check_args(PolynomialKernel, d, d >= one(T₁), "d >= 1")
-    PolynomialKernel{T₁,ScaleTransform{T₁},T₂,T₃}(ScaleTransform(ρ),c,d)
+    PolynomialKernel{T₁,ScaleTransform{Base.RefValue{T₁}},T₂,T₃}(ScaleTransform(ρ),c,d)
 end
 
 function PolynomialKernel(ρ::A,d::T₁=2.0,c::T₂=zero(eltype(ρ))) where {A<:AbstractVector{<:Real},T₁<:Real,T₂<:Real}