Improve package overview (#116)

* do not reexport AbstractGPs

* add structure to README

* update docs/src/index.md

* add missing method implementations for SparseVariationalApproximation

* Update src/SparseVariationalApproximationModule.jl

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* patch bump

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: st--

Project.toml

@@ -1,7 +1,7 @@
 name = "ApproximateGPs"
 uuid = "298c2ebc-0411-48ad-af38-99e88101b606"
 authors = ["JuliaGaussianProcesses Team"]
-version = "0.3.1"
+version = "0.3.2"
 
 [deps]
 AbstractGPs = "99985d1d-32ba-4be9-9821-2ec096f28918"

README.md

@@ -5,3 +5,30 @@
 [![Codecov](https://codecov.io/gh/JuliaGaussianProcesses/ApproximateGPs.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaGaussianProcesses/ApproximateGPs.jl)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+
+## Aim of this package
+
+Provide various algorithms for approximate inference in latent Gaussian process models, currently focussing on non-conjugate (non-Gaussian) likelihoods and sparse approximations.
+
+## Structure
+
+Each approximation lives in its own submodule (`<Approximation>Module`), though
+in general using the exported API is sufficient.
+
+The main API is:
+
+* `posterior(approximation, lfx::LatentFiniteGP, ys)` to obtain the posterior
+  approximation to `lfx` conditioned on the observations `ys`.
+
+* `approx_lml(approximation, lfx::LatentFiniteGP, ys)` which returns the
+  marginal likelihood approximation that can be used for hyperparameter
+  optimisation.
+
+Currently implemented approximations:
+
+* `LaplaceApproximation`
+
+* `SparseVariationalApproximation`
+
+  NOTE: requires optimisation of the variational distribution even for fixed
+  hyperparameters.

docs/src/index.md

@@ -1,5 +1,5 @@
 # ApproximateGPs.jl
 
-**ApproximateGPs.jl** is a package that provides sparse variational Gaussian process
-approximations, built on top of
+**ApproximateGPs.jl** is a package that provides some approximate inference
+algorithms for Gaussian process models, built on top of
 [AbstractGPs.jl](https://github.com/JuliaGaussianProcesses/AbstractGPs.jl).

src/ApproximateGPs.jl

@@ -2,7 +2,6 @@ module ApproximateGPs
 
 using Reexport
 
-@reexport using AbstractGPs
 @reexport using GPLikelihoods
 
 include("API.jl")

src/SparseVariationalApproximationModule.jl

@@ -196,6 +196,13 @@ function AbstractGPs.posterior(
     return posterior(sva)
 end
 
+function AbstractGPs.posterior(
+    sva::SparseVariationalApproximation, lfx::LatentFiniteGP, ::Any
+)
+    @assert sva.fz.f === lfx.fx.f
+    return posterior(sva)
+end
+
 #
 # Various methods implementing the Internal AbstractGPs API.
 # See AbstractGPs.jl API docs for more info.
@@ -269,6 +276,12 @@ inducing_points(f::ApproxPosteriorGP{<:SparseVariationalApproximation}) = f.appr
 # elbo
 #
 
+function API.approx_lml(
+    sva::SparseVariationalApproximation, l_fx::Union{FiniteGP,LatentFiniteGP}, ys; kwargs...
+)
+    return elbo(sva, l_fx, ys; kwargs...)
+end
+
 """
     elbo(
         sva::SparseVariationalApproximation,