Merge pull request #66 from theogf/docs_and_formatting

Corrected docs and improved formatting

Author: theogf

src/kernels/constant.jl

@@ -1,5 +1,5 @@
 """
-ZeroKernel()
+    ZeroKernel()
 
 Create a kernel that always returning zero
 ```
@@ -13,28 +13,40 @@ kappa(κ::ZeroKernel, d::T) where {T<:Real} = zero(T)
 
 metric(::ZeroKernel) = Delta()
 
+Base.show(io::IO, ::ZeroKernel) = print(io, "Zero Kernel")
+
+
 """
-`WhiteKernel()`
+    WhiteKernel()
 
 ```
     κ(x,y) = δ(x,y)
 ```
-Kernel function working as an equivalent to add white noise.
+Kernel function working as an equivalent to add white noise. Can also be called via `EyeKernel()`
 """
 struct WhiteKernel <: BaseKernel end
 
+"""
+    EyeKernel()
+
+See [WhiteKernel](@ref)
+"""
 const EyeKernel = WhiteKernel
 
-kappa(κ::WhiteKernel,δₓₓ::Real) = δₓₓ
+kappa(κ::WhiteKernel, δₓₓ::Real) = δₓₓ
 
 metric(::WhiteKernel) = Delta()
 
+Base.show(io::IO, ::WhiteKernel) = print(io, "White Kernel")
+
+
 """
-`ConstantKernel(c=1.0)`
+    ConstantKernel(; c=1.0)
+
+Kernel function always returning a constant value `c`
 ```
     κ(x,y) = c
 ```
-Kernel function always returning a constant value `c`
 """
 struct ConstantKernel{Tc<:Real} <: BaseKernel
     c::Vector{Tc}
@@ -46,3 +58,5 @@ end
 kappa(κ::ConstantKernel,x::Real) = first(κ.c)*one(x)
 
 metric(::ConstantKernel) = Delta()
+
+Base.show(io::IO, κ::ConstantKernel) = print(io, "Constant Kernel (c = $(first(κ.c)))")

src/kernels/cosine.jl

@@ -1,14 +1,14 @@
 """
-    CosineKernel
+    CosineKernel()
 
 The cosine kernel is a stationary kernel for a sinusoidal given by
 ```
     κ(x,y) = cos( π * (x-y) )
 ```
-
 """
 struct CosineKernel <: BaseKernel end
 
 kappa(κ::CosineKernel, d::Real) = cospi(d)
-
 metric(::CosineKernel) = Euclidean()
+
+Base.show(io::IO, ::CosineKernel) = print(io, "Cosine Kernel")

src/kernels/exponential.jl

@@ -1,18 +1,18 @@
 """
-`SqExponentialKernel()`
+    SqExponentialKernel()
 
-The squared exponential kernel is an isotropic Mercer kernel given by the formula:
+The squared exponential kernel is a Mercer kernel given by the formula:
 ```
     κ(x,y) = exp(-‖x-y‖²)
 ```
+Can also be called via `SEKernel`, `GaussianKernel` or `SEKernel`.
 See also [`ExponentialKernel`](@ref) for a
 related form of the kernel or [`GammaExponentialKernel`](@ref) for a generalization.
 """
 struct SqExponentialKernel <: BaseKernel end
 
 kappa(κ::SqExponentialKernel, d²::Real) = exp(-d²)
 iskroncompatible(::SqExponentialKernel) = true
-
 metric(::SqExponentialKernel) = SqEuclidean()
 
 Base.show(io::IO,::SqExponentialKernel) = print(io,"Squared Exponential Kernel")
@@ -23,10 +23,11 @@ const GaussianKernel = SqExponentialKernel
 const SEKernel = SqExponentialKernel
 
 """
-`ExponentialKernel([ρ=1.0])`
-The exponential kernel is an isotropic Mercer kernel given by the formula:
+    ExponentialKernel()
+
+The exponential kernel is a Mercer kernel given by the formula:
 ```
-    κ(x,y) = exp(-ρ‖x-y‖)
+    κ(x,y) = exp(-‖x-y‖)
 ```
 """
 struct ExponentialKernel <: BaseKernel end
@@ -35,21 +36,24 @@ kappa(κ::ExponentialKernel, d::Real) = exp(-d)
 iskroncompatible(::ExponentialKernel) = true
 metric(::ExponentialKernel) = Euclidean()
 
-Base.show(io::IO,::ExponentialKernel) = print(io,"Exponential Kernel")
+Base.show(io::IO, ::ExponentialKernel) = print(io, "Exponential Kernel")
 
 ## Alias ##
 const LaplacianKernel = ExponentialKernel
 
 """
-`GammaExponentialKernel([ρ=1.0, [γ=2.0]])`
+    GammaExponentialKernel(; γ = 2.0)
+
 The γ-exponential kernel is an isotropic Mercer kernel given by the formula:
 ```
-    κ(x,y) = exp(-ρ^(2γ)‖x-y‖^(2γ))
+    κ(x,y) = exp(-‖x-y‖^(2γ))
 ```
+Where `γ > 0`, (the keyword `γ` can be replaced by `gamma`)
+For `γ = 1`, see `SqExponentialKernel` and `γ = 0.5`, see `ExponentialKernel`
 """
 struct GammaExponentialKernel{Tγ<:Real} <: BaseKernel
     γ::Vector{Tγ}
-    function GammaExponentialKernel(;gamma::T=2.0, γ::T=gamma) where {T<:Real}
+    function GammaExponentialKernel(; gamma::T=2.0, γ::T=gamma) where {T<:Real}
         @check_args(GammaExponentialKernel, γ, γ >= zero(T), "γ > 0")
         return new{T}([γ])
     end
@@ -58,3 +62,5 @@ end
 kappa(κ::GammaExponentialKernel, d²::Real) = exp(-d²^first(κ.γ))
 iskroncompatible(::GammaExponentialKernel) = true
 metric(::GammaExponentialKernel) = SqEuclidean()
+
+Base.show(io::IO, κ::GammaExponentialKernel) = print(io, "Gamma Exponential Kernel (γ = $(first(κ.γ)))")

src/kernels/exponentiated.jl

@@ -1,14 +1,15 @@
 """
-`ExponentiatedKernel([ρ=1])`
+    ExponentiatedKernel()
+
 The exponentiated kernel is a Mercer kernel given by:
 ```
-    κ(x,y) = exp(ρ²xᵀy)
+    κ(x,y) = exp(xᵀy)
 ```
 """
 struct ExponentiatedKernel <: BaseKernel end
 
 kappa(κ::ExponentiatedKernel, xᵀy::Real) = exp(xᵀy)
-
 metric(::ExponentiatedKernel) = DotProduct()
-
 iskroncompatible(::ExponentiatedKernel) = true
+
+Base.show(io::IO, ::ExponentiatedKernel) = print(io, "Exponentiated Kernel")

src/kernels/fbm.jl

@@ -1,22 +1,24 @@
 """
     FBMKernel(; h::Real=0.5)
 
-Fractional Brownian motion kernel with Hurst index h from (0,1) given by
+Fractional Brownian motion kernel with Hurst index `h` from (0,1) given by
 ```
     κ(x,y) =  ( |x|²ʰ + |y|²ʰ - |x-y|²ʰ ) / 2
 ```
 
-For h=1/2, this is the Wiener Kernel, for h>1/2, the increments are
-positively correlated and for h<1/2 the increments are negatively correlated.
+For `h=1/2`, this is the Wiener Kernel, for `h>1/2`, the increments are
+positively correlated and for `h<1/2` the increments are negatively correlated.
 """
 struct FBMKernel{T<:Real} <: BaseKernel
     h::T
-    function FBMKernel(;h::T=0.5) where {T<:Real}
+    function FBMKernel(; h::T=0.5) where {T<:Real}
         @assert h<=1.0 && h>=0.0 "FBMKernel: Given Hurst index h is invalid."
         return new{T}(h)
     end
 end
 
+Base.show(io::IO, κ::FBMKernel) = print(io, "Fractional Brownian Motion Kernel (h = $(k.h))")
+
 _fbm(modX, modY, modXY, h) = (modX^h + modY^h - modXY^h)/2
 
 function kernelmatrix(κ::FBMKernel, X::AbstractMatrix; obsdim::Int = defaultobs)
@@ -40,7 +42,7 @@ function kernelmatrix(
     Y::AbstractMatrix;
     obsdim::Int = defaultobs,
 )
-    @assert obsdim ∈ [1,2] "obsdim should be 1 or 2 (see docs of kernelmatrix))"   
+    @assert obsdim ∈ [1,2] "obsdim should be 1 or 2 (see docs of kernelmatrix))"
     modX = sum(abs2, X, dims=3-obsdim)
     modY = sum(abs2, Y, dims=3-obsdim)
     modXY = pairwise(SqEuclidean(), X, Y,dims=obsdim)
@@ -54,7 +56,7 @@ function kernelmatrix!(
     Y::AbstractMatrix;
     obsdim::Int = defaultobs,
 )
-    @assert obsdim ∈ [1,2] "obsdim should be 1 or 2 (see docs of kernelmatrix))"   
+    @assert obsdim ∈ [1,2] "obsdim should be 1 or 2 (see docs of kernelmatrix))"
     modX = sum(abs2, X, dims=3-obsdim)
     modY = sum(abs2, Y, dims=3-obsdim)
     modXY = pairwise(SqEuclidean(), X, Y,dims=obsdim)

src/kernels/kernelproduct.jl

@@ -1,13 +1,14 @@
 """
-`KernelProduct(kernels::Array{Kernel})`
-Create a multiplication of kernels.
-One can also use the operator `*`
+    KernelProduct(kernels::Array{Kernel})
+
+Create a product of kernels.
+One can also use the operator `*` :
 ```
-k1 = SqExponentialKernel()
-k2 = LinearKernel()
-k = KernelProduct([k1,k2])
-kernelmatrix(k,X) == kernelmatrix(k1,X).*kernelmatrix(k2,X)
-kernelmatrix(k,X) == kernelmatrix(k1*k2,X)
+    k1 = SqExponentialKernel()
+    k2 = LinearKernel()
+    k = KernelProduct([k1, k2]) == k1 * k2
+    kernelmatrix(k, X) == kernelmatrix(k1, X) .* kernelmatrix(k2, X)
+    kernelmatrix(k, X) == kernelmatrix(k1 * k2, X)
 ```
 """
 struct KernelProduct <: Kernel
@@ -47,14 +48,14 @@ function kerneldiagmatrix(
     reduce(hadamard,kerneldiagmatrix(κ.kernels[i],X,obsdim=obsdim) for i in 1:length(κ))
 end
 
-function Base.show(io::IO,κ::KernelProduct)
-    printshifted(io,κ,0)
+function Base.show(io::IO, κ::KernelProduct)
+    printshifted(io, κ, 0)
 end
 
-function printshifted(io::IO,κ::KernelProduct, shift::Int)
-    print(io,"Product of $(length(κ)) kernels:")
+function printshifted(io::IO, κ::KernelProduct, shift::Int)
+    print(io, "Product of $(length(κ)) kernels:")
     for i in 1:length(κ)
-        print(io,"\n"*("\t"^(shift+1))*"- ")
-        printshifted(io,κ.kernels[i],shift+2)
+        print(io, "\n" * ("\t" ^ (shift + 1))* "- ")
+        printshifted(io, κ.kernels[i], shift + 2)
     end
 end

src/kernels/kernelsum.jl

@@ -1,14 +1,15 @@
 """
-`KernelSum(kernels::Array{Kernel};weights::Array{Real}=ones(length(kernels)))`
-Create a positive weighted sum of kernels.
+    KernelSum(kernels::Array{Kernel}; weights::Array{Real}=ones(length(kernels)))
+
+Create a positive weighted sum of kernels. All weights should be positive.
 One can also use the operator `+`
 ```
-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
+    k1 = SqExponentialKernel()
+    k2 = LinearKernel()
+    k = KernelSum([k1, k2]) == 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 == KernelSum([k1, k2], weights = [0.5, 2.0])
 ```
 """
 struct KernelSum <: Kernel
@@ -68,14 +69,14 @@ function kerneldiagmatrix(
     sum(κ.weights[i] * kerneldiagmatrix(κ.kernels[i], X, obsdim = obsdim) for i in 1:length(κ))
 end
 
-function Base.show(io::IO,κ::KernelSum)
-    printshifted(io,κ,0)
+function Base.show(io::IO, κ::KernelSum)
+    printshifted(io, κ, 0)
 end
 
 function printshifted(io::IO,κ::KernelSum, shift::Int)
     print(io,"Sum of $(length(κ)) kernels:")
     for i in 1:length(κ)
-        print(io,"\n"*("\t"^(shift+1))*"- (w=$(κ.weights[i])) ")
-        printshifted(io,κ.kernels[i],shift+2)
+        print(io, "\n" * ("\t" ^ (shift + 1)) * "- (w = $(κ.weights[i])) ")
+        printshifted(io, κ.kernels[i], shift + 2)
     end
 end

src/kernels/maha.jl

@@ -1,7 +1,7 @@
 """
     MahalanobisKernel(P::AbstractMatrix)
 
-    Mahalanobis distance-based kernel given by
+Mahalanobis distance-based kernel given by
 ```math
     κ(x,y) =  exp(-r^2), r^2 = maha(x,P,y) = (x-y)'*inv(P)*(x-y)
 ```
@@ -16,6 +16,7 @@ struct MahalanobisKernel{T<:Real, A<:AbstractMatrix{T}} <: BaseKernel
     end
 end
 
-kappa(κ::MahalanobisKernel, d::T) where {T<:Real} = exp(-d) 
-
+kappa(κ::MahalanobisKernel, d::T) where {T<:Real} = exp(-d)
 metric(κ::MahalanobisKernel) = SqMahalanobis(κ.P)
+
+Base.show(io::IO, κ::MahalanobisKernel) = print(io, "Mahalanobis Kernel (size(P) = $(size(κ.P))")

src/kernels/matern.jl

@@ -1,6 +1,7 @@
 """
-`MaternKernel([ρ=1.0,[ν=1.0]])`
-The matern kernel is an isotropic Mercer kernel given by the formula:
+    MaternKernel(; ν = 1.0)
+
+The matern kernel is a Mercer kernel given by the formula:
 ```
     κ(x,y) = 2^{1-ν}/Γ(ν)*(√(2ν)‖x-y‖)^ν K_ν(√(2ν)‖x-y‖)
 ```
@@ -26,28 +27,34 @@ end
 
 metric(::MaternKernel) = Euclidean()
 
+Base.show(io::IO, κ::MaternKernel) = print(io, "Matern Kernel (ν = $(first(κ.ν)))")
+
 """
-`Matern32Kernel([ρ=1.0])`
-The matern 3/2 kernel is an isotropic Mercer kernel given by the formula:
+    Matern32Kernel()
+
+The matern 3/2 kernel is a 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‖)
 ```
 """
 struct Matern32Kernel <: BaseKernel end
 
 kappa(κ::Matern32Kernel, d::Real) = (1 + sqrt(3) * d) * exp(-sqrt(3) * d)
-
 metric(::Matern32Kernel) = Euclidean()
 
+Base.show(io::IO, ::Matern32Kernel) = print(io, "Matern 3/2 Kernel")
+
 """
-`Matern52Kernel([ρ=1.0])`
-The matern 5/2 kernel is an isotropic Mercer kernel given by the formula:
+    Matern52Kernel()
+
+The matern 5/2 kernel is a 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/3‖x-y‖^2)exp(-√(5)‖x-y‖)
 ```
 """
 struct Matern52Kernel <: BaseKernel end
 
 kappa(κ::Matern52Kernel, d::Real) = (1 + sqrt(5) * d + 5 * d^2 / 3) * exp(-sqrt(5) * d)
-
 metric(::Matern52Kernel) = Euclidean()
+
+Base.show(io::IO, ::Matern52Kernel) = print(io, "Matern 5/2 Kernel")