with_lengthscale

docs/src/transform.md

@@ -36,3 +36,9 @@ SelectTransform
 ChainTransform
 PeriodicTransform
 ```
+
+## Convenience functions
+
+```@docs
+with_lengthscale
+```

docs/src/userguide.md

@@ -15,6 +15,11 @@ For example, a squared exponential kernel is created by
       k = SqExponentialKernel() ∘ ScaleTransform(2.0)
       k = compose(SqExponentialKernel(), ScaleTransform(2.0))
     ```
+    You can also use the convenience function [`with_lengthscale`](@ref):
+    ```julia
+      k = with_lengthscale(SqExponentialKernel(), 0.5)
+    ```
+    is equivalent to the manual composition. [`with_lengthscale`](@ref) also works with a vector-valued lengthscales argument for ARD.
     Check the [Input Transforms](@ref input_transforms) page for more details.
 
 !!! tip "How do I set the kernel variance?"

src/KernelFunctions.jl

@@ -27,6 +27,7 @@ export Transform,
     IdentityTransform,
     FunctionTransform,
     PeriodicTransform
+export with_lengthscale
 
 export NystromFact, nystrom
 
@@ -75,6 +76,7 @@ include(joinpath("transform", "selecttransform.jl"))
 include(joinpath("transform", "chaintransform.jl"))
 include(joinpath("transform", "periodic_transform.jl"))
 include(joinpath("kernels", "transformedkernel.jl"))
+include(joinpath("transform", "with_lengthscale.jl"))
 
 include(joinpath("basekernels", "constant.jl"))
 include(joinpath("basekernels", "cosine.jl"))

src/kernels/transformedkernel.jl

@@ -72,6 +72,10 @@ Base.:∘(k::TransformedKernel, t::Transform) = TransformedKernel(k.kernel, k.tr
 Base.:∘(k::Kernel, ::IdentityTransform) = k
 Base.:∘(k::TransformedKernel, ::IdentityTransform) = k
 
+function Base.isequal(k::TransformedKernel, k2::TransformedKernel)
+    return isequal(k.kernel, k2.kernel) && isequal(k.transform, k2.transform)
+end
+
 Base.show(io::IO, κ::TransformedKernel) = printshifted(io, κ, 0)
 
 function printshifted(io::IO, κ::TransformedKernel, shift::Int)

src/transform/chaintransform.jl

@@ -46,6 +46,8 @@ end
 set!(t::ChainTransform, θ) = set!.(t.transforms, θ)
 duplicate(t::ChainTransform, θ) = ChainTransform(duplicate.(t.transforms, θ))
 
+Base.isequal(t::ChainTransform, t2::ChainTransform) = isequal(t.transforms, t2.transforms)
+
 Base.show(io::IO, t::ChainTransform) = printshifted(io, t, 0)
 
 function printshifted(io::IO, t::ChainTransform, shift::Int)

src/transform/with_lengthscale.jl

@@ -0,0 +1,32 @@
+"""
+    with_lengthscale(kernel::Kernel, lengthscale::Real)
+    with_lengthscale(kernel::Kernel, lengthscales::AbstractVector{<:Real})
+
+Construct a transformed kernel with `lengthscale`.
+If a vector `lengthscales` is passed instead, construct an "ARD" kernel with different lengthscales for each dimension.
+
+The following two ways of constructing a squared-exponential kernel with
+a given lengthscale are equivalent:
+
+```jldoctest
+julia> ℓ = 2.5;
+
+julia> isequal(SqExponentialKernel() ∘ ScaleTransform(inv(ℓ)), with_lengthscale(SqExponentialKernel(), ℓ))
+true
+```
+
+and for the ARD case:
+
+```jldoctest
+julia> ℓ = [0.5, 2.5];
+
+julia> isequal(SqExponentialKernel() ∘ ARDTransform(inv.(ℓ)), with_lengthscale(SqExponentialKernel(), ℓ))
+true
+```
+"""
+function with_lengthscale(kernel::Kernel, lengthscale::Real)
+    return compose(kernel, ScaleTransform(inv(lengthscale)))
+end
+function with_lengthscale(kernel::Kernel, lengthscales::AbstractVector{<:Real})
+    return compose(kernel, ARDTransform(map(inv, lengthscales)))
+end