GAUSSIAN PROCESS REGRESSION AND CLASSIFICATION Toolbox version 4.2 for GNU Octave 3.2.x and Matlab 7.x and higher Copyright (c) by Carl Edward Rasmussen and Hannes Nickisch, 2018-06-11. 0) HOW TO READ ============== If you want to get started without further delay, then read section 1) below and jump right to the examples in doc/index.html. 1) ABOUT THESE PROGRAMS ======================= This collection of matlab programs implements and demonstrates some of the algorithms described in a) the book by Rasmussen and Williams: "Gaussian Processes for Machine Learning", the MIT Press 2006, in b) the article by Nickisch and Rasmussen: "Approximations for Binary Gaussian Process Classification", JMLR 2008, in c) the article by Candela and Rasmussen: "A Unifying View of Sparse Approximate Gaussian Process Regression", JMLR 2005, in d) the paper by Murray, Adams and Mackay: "Elliptical slice sampling", AISTATS 2010, in e) the report by Neal: "Annealed Importance Sampling", UToronto 1998, in f) the paper by Naish-Guzman and Holden: "The Generalized FITC Approximation", NIPS, 2007, in g) the paper by Duvenaud, Nickisch and Rasmussen: "Additive Gaussian Processes", NIPS, 2011, in h) the paper by Wilson and Adams: "Gaussian Process Kernels for Pattern Discovery and Extrapolation", ICML, 2013, in i) the paper by Snelson, Rasmussen and Ghahramani: "Warped Gaussian Processes", NIPS, 2003, and in j) the paper by Wilson and Nickisch: "Kernel interpolation for scalable structured Gaussian processes (KISS-GP)", ICLM, 2015, k) the paper by Nickisch, Solin and Grigorievskiy: "State Space Gaussian Processes with Non-Gaussian Likelihood", ICLM, 2018, and l) the paper by Pleiss, Gardner, Weinberger and Wilson "Constant-Time Predictive Distributions for Gaussian Processes", ICLM, 2018. There are 7 code subdirectories: cov, doc, inf, lik, mean, prior and util. cov/ contains covariance functions cov*.m => see covFunctions.m doc/ contains an index.html file providing documentation. This information is also available from http://www.GaussianProcess.org/gpml/code. Usage of mean, cov, classification and regression is demonstrated in usage*.m. Further details can be found in the developer documentation manual.pdf. inf/ contains the inference algorithms inf*.m => see infMethods.m lik/ contains the likelihood functions lik*.m => see likFunctions.m mean/ contains the mean functions mean*.m => see meanFunctions.m prior/ contains the hyperparameter prior distributions prior*.m => see priorDistributions.m util/ contains optimisation routines, backward compatibility programs and small auxiliary scripts Before running the demos or any other part of the code, you should execute startup.m to add all necessary directories to your path. In Octave, you can also use the .octaverc file. 2) ABOUT MEX FILES ================== Some of the programs make use of the MEX facility in matlab for more efficient implementation. However, if you don't know about how to compile MEX files, you do not need to worry about this -- the code runs anyway. If you do compile the MEX files, this is automatically detected, and the program will run more efficiently. If you do not have a compiler installed on your system, you might want to consult [3]. Two components of the toolbox can be accelerated by MEX. First, there is an auxiliary functions solve_chol.m having a MEX equivalent. This can be compiled by either executing util/make.m from the Matlab/Octave command line. In addition to that, we provide a Makefile for Matlab in util/ that you can run by simply typing make in your shell after having supplied your Matlab path and your operating system. We recommend the make.m script because it works both under Matlab and Octave. Second, in order to use the L-BFGS minimiser for hyperparameter optimisation as an equivalent to minimize.m, you have to compile Peter Carbonetto's "Matlab interface for L-BFGS-B" [1] which was extended to also work for Octave by José Vallet. The challenge here is the Fortran 77 code. We provide a Makefile suitable for Linux 32/64 bit and Mac whenever you have 1) g77 or 2) gfortran properly set up. The latter is prefered on current Ubuntu systems. Under Ubuntu, you can achieve this by installing the packages fort77 and gfortran, respectively. Note that the code is GNU licensed. Compilation is done by editing util/lbfgsb/Makefile. In any case, you need to provide $MATLAB_HOME which can be found by the commands 'locate matlab' or 'find / -name "matlab"'. You can choose between two compilation modes: a) without mex utility by Matlab [default] provide $MEX_SUFFIX and $MATLAB_LIB, then type 'make nomex' b) using the mex utility by Matlab provide $MEX, then type 'make mex' c) compilation for Octave provide Octave variables and type 'make oct' In Ubuntu 10.04 LTS, the libg2c library needed for both 1)+a) and 1)+b) is not included per default. If 'ls /usr/lib/libg2c.*' does not list anything this is the case on your machine. You then whant to install the packages gcc-3.4-base and libg2c0 e.g. from http://packages.ubuntu.com/hardy/gcc-3.4-base and http://packages.ubuntu.com/hardy/libg2c0. After installation, you have to create a symbolic link by 'cd /usr/lib' and 'ln -s libg2c.so.0 libg2c.so'. There were reports of problems running the mex files on recent 64bit Ubuntu since the libgfortran.3.0.0 that comes with matlab ($(MATLAB_HOME)/sys/os/glnxa64/libgfortran.so.3.0.0) is not the same as the libgfortran.3.0.0 that comes with the ubuntu package libgfortran3 and that is used when linking. So running the mex file results in a version mismatch error. The issue can be solved by changing the name of to the matlab file and linking to the ubuntu file instead: in $(MATLAB_HOME)/sys/os/glnxa64 run 'sudo mv libgfortran.3.0.0 libgfortran.3.0.0_matlab' 'sudo ln -s /usr/lib/x86_64-linux-gnu/libgfortran.so.3.0.0 libgfortran.3.0.0' Thanks to Giampiero Salvi for posting the workaround. [1] https://github.com/pcarbo/lbfgsb-matlab [2] http://www.mathworks.com/support/compilers/R2010a 3) CURRENT VERSION ================== The current version of the programs is 4.2. Previous versions of the code are available at http://www.gaussianprocess.org/gpml/code/oldcode.html. 4) DIFFERENCES TO PREVIOUS VERSIONS =================================== NEW in version 4.2, 2018-06-11 ------------------------------ State space covariance approximation apxState, infState - In addition to sparse (apxSparse) and grid-based (apxGrid) covariance approximations, we offer fast inference for univariate GPs exploiting the state space representation (apxState) See doc/demoState to get started. See also "State Space Gaussian Processes with Non-Gaussian Likelihood", ICLM, 2018, ref [k]. Fast predictive variance estimation for grid-based approximate covariances - Lanczos subspace estimation to perform very fast predictions See doc/demoGrid for how to use it. See also "Constant-Time Predictive Distributions for Gaussian Processes", ICML, 2018, ref [l]. Bugfixes - problem in covMatern for non-integer d Little features - add modes proj and fact to covDot NEW in version 4.1, 2017-10-19 ------------------------------ Logdet-estimation functionality for grid-based approximate covariances - Lanczos subspace estimation - Chebyshef polynomial expansion More generic infEP functionality - dense computations and sparse approximations using the same code - covering KL inference as a special case of EP New infKL function contributed by Emtiyaz Khan and Wu Lin - Conjugate-Computation Variational Inference algorithm - much more scalable than previous versions Time-series covariance functions on the positive real line - covW (i-times integrated) Wiener process covariance - covOU (i-times integrated) Ornstein-Uhlenbeck process covariance (contributed by Juan Pablo Carbajal) - covULL underdamped linear Langevin process covariance (contributed by Robert MacKay) - covFBM Fractional Brownian motion covariance New covariance functions - covWarp implements k(w(x),w(z)) where w is a "warping" function - covMatern has been extended to also accept non-integer distance parameters NEW in version 4.0, 2016-10-19 ------------------------------ A major code restructuring effort did take place in the current release unifying certain inference functions and allowing more flexibility in covariance function composition. We also redesigned the whole derivative computation pipeline to strongly improve the overall runtime. We finally include grid-based covariance approximations natively. More generic sparse approximation using Power EP - unified treatment of FITC approximation, variational approaches VFE and hybrids - inducing input optimisation for all (compositions of) covariance functions dropping the previous limitation to a few standard examples - infFITC is now covered by the more generic infGaussLik function Approximate covariance object unifying sparse approximations, grid-based approximations and exact covariance computations - implementation in cov/apx, cov/apxGrid, cov/apxSparse - generic infGaussLik unifies infExact, infFITC and infGrid - generic infLaplace unifies infLaplace, infFITC_Laplace and infGrid_Laplace - generic infVB - enables efficient grid-based algebra for off-grid inputs, see reference j) above Hiearchical structure of covariance functions - clear hierachical compositional implementation - no more code duplication as present in covSEiso and covSEard pairs - two mother covariance functions covDot for dot-product-based covariances and covMaha for Mahalanobis-distance-based covariances - a variety of modifiers: eye, iso, ard, proj, fact, vlen - more flexibility as more variants are available and possible - all covariance functions offer derivatives w.r.t. inputs Faster derivative computations for mean and cov functions - switched from partial derivatives to directional derivatives - simpler and more concise interface of mean and cov functions - much faster marginal likelihood derivative computations - simpler and more compact code New mean functions - new mean/meanWSPC (Weighted Sum of Projected Cosines or Random Kitchen Sink features) following a suggestion by William Herlands - new mean/meanWarp for constructing a new mean from an existing one by means of a warping function adapted from William Herlands New optimizer - added a new minimize_minfunc, contributed by Truong X. Nghiem New prior - added prior{Equal|Same}Multi forcing a group of hyperparameters to the same value New GLM link function - added the twice logistic link function util/glm_invlink_logistic2 Smaller fixes - two-fold speedup of util/elsympol used by covADD by Truong X. Nghiem - bugfix in util/logphi as reported by John Darby NEW in version 3.6, 2015-07-07 ------------------------------ - bugfix in likGaussWarp as reported by Obaid Malik - added a new inference function infGrid_Laplace allowing to use non-Gaussian likelihoods for large grids - fixed a bug due to Octave evaluating norm([]) to a tiny nonzero value, modified all lik/lik*.m functions reported by Philipp Richter - small bugfixes in covGrid and infGrid - bugfix in predictive variance of likNegBinom due to Seth Flaxman - bugfix in infFITC_Laplace as suggested by Wu Lin - bugfix in covPP{iso,ard} NEW in version 3.5, 2014-12-08 ------------------------------ - mechanism for specifying hyperparameter priors (together with Roman Garnett and José Vallet) - new inference method inf/infGrid allowing efficient inference for data defined on a Cartesian grid (together with Andrew Wilson) - new mean/cov functions for preference learning: meanPref/covPref - new mean/cov functions for non-vectorial data: meanDiscrete/covDiscrete - new piecewise constant nearest neighbor mean function: meanNN - new mean functions being predictions from GPs: meanGP and meanGPexact - new covariance function for standard additive noise: covEye - new covariance function for factor analysis: covSEfact - new covariance function with varying length scale : covSEvlen - make covScale more general to scaling with a function instead of a scalar - bugfix in covGabor* and covSM (due to Andrew Gordon Wilson) - bugfix in lik/likBeta.m (suggested by Dali Wei) - bugfix in solve_chol.c (due to Todd Small) - bugfix in FITC inference mode (due to Joris Mooij) where the wrong mode for post.L was chosen when using infFITC and post.L being a diagonal matrix - bugfix in infVB marginal likelihood for likLogistic with nonzero mean function (reported by James Lloyd) - removed the combination likErf/infVB as it yields a bad posterior approximation and lacks theoretical justification - Matlab and Octave compilation for L-BFGS-B v2.4 and the more recent L-BFGS-B v3.0 (contributed by José Vallet) - smaller bugfixes in gp.m (due to Joris Mooij and Ernst Kloppenburg) - bugfix in lik/likBeta.m (due to Dali Wei) - updated use of logphi in lik/likErf - bugfix in util/solve_chol.c where a typing issue occured on OS X (due to Todd Small) - bugfix due to Bjørn Sand Jensen noticing that cov_deriv_sq_dist.m was missing in the distribution - bugfix in infFITC_EP for ttau->inf (suggested by Ryan Turner) NEW in version 3.4, 2013-11-11 ------------------------------ - new likelihood function for warped GPs: likGaussWarp - new exponential likelihood function: likExp - new Weibull likelihood function: likWeibull - new Gumbel likelihood function for extremal value regression: likGumbel - new polynomial mean function: meanPoly - included derivatives w.r.t. inducing points xu in infFITC, infFITC_Laplace, infFITC_EP - allow for zero noise variance for infExact NEW in version 3.3, 2013-10-19 ------------------------------ - new variational inference algorithm based on direct KL minimisation: infKL - improved inf/infVB double loop scheme so that only very few likelihood properties are required; infVB is now internally a sequence of infLaplace runs - improved inf/infLaplace to be more generic so that optimisers other than scaled Newton can be used - improved inf/infEP so that the internal variables (mu,Sigma) now represent the current posterior approximation - added three new generalised linear model likelihoods: gamma, beta, inverse Gaussian - new covariance functions: spectral mixture covSM, covGaboriso and covGaborard - new meta covariance function to turn a stationary covariance into a periodic covariance function covPERard, covPERiso - new periodic covariance function with zero DC component and correct scaling covPeriodicNoDC New likelihood functions in lik/: - likGamma.m, likBeta.m, likInvGauss.m New inference functions in inf/: - infKL.m New covariance functions in cov/: - covSM.m, covGaboriso.m, covGaborard.m (contributed by Andrew Gordon Wilson) - covPPard.m, covMaternard.m, covLINiso.m - covCos.m, covPeriodicNoDC.m (contributed by James Robert Lloyd) - covPERiso.m, covPERard.m NEW in version 3.2, 2013-01-15 ------------------------------ - added inf/infFITC_Laplace.m and inf/infFITC_EP.m for large scale approximate inference - added inf/infMCMC.m to allow for Markov Chain Monte Carlo sampling and Annealed Importance Sampling; we currently support two samplers: Elliptical Slice Sampling (ESS) and Hybrid Monte Carlo (HMC) - improved accuracy of the digamma function lik/likT.m/dloggamma from three to ten digits precision (thanks to Edward Challis) - added gfortran support to util/lbfgsb/Makefile (thanks to Ernst Kloppenburg) - fixed a stupid bug in cov/covFITC.m (thanks to Krzysztof Chalupka) - fixed a severe stability bug in the derivatives of inf/infFITC.m (thanks to Andrew McHutchon) - changed scalars in util/solve_chol.c to long to provide 64bit compatibility (thanks to Ernst Kloppenburg) - added infLOO to allow pseudo-likelihood optimisation instead of the marginal likelihood - fixed a performance issue in util/sq_dist.m (thanks to Krzysztof Chalupka) - fixed a bug causing numerical problems in infFITC and covFITC whenever Kuu is close to singular (thanks to Joris M. Mooij) - fixed an issue in covNoise (thanks to Daniel Marthaler) - fixed implicit derivative w.r.t. likelihood in infLaplace* - added two more likelihood functions likMix.m for mixtures and likUni for classification noise - slightly changed the interface for the likelihood functions - added likPoisson for Poisson regression of count data NEW in version 3.1, 2010-10-10 ------------------------------ - following a suggestion by Ed Snelson we now support FITC regression - cov/covFITC.m and inf/infFITC.m have been added with Ed Snelson's help - the covariance interface was slightly changed to make that possible - changed parametrisation in cov/covPeriodic.m (thanks to Philipp Hennig) NEW in version 3.0, 2010-07-23 ------------------------------ A major code reorganisation effort did take place in the current release. First, classification and regression are now done by a single file gp.m which is completely generic in the likelihood. The previous regression program gpr.m corresponds to gp.m with Gaussian likelihood. Several other likelihoods for robust regresssion were added. Further, the code now supports mean functions with a similar specification mechanism as already used by the covariance functions. Previous implementations correspond to using meanZero.m. We merged the covariance functions covMatern3iso.m and covMatern5.iso into a single covMaterniso.m and added a covariance function for additive functions as well as the possibility to use only certain components of the data. Finally, we included covPPiso.m a piecewise polynomial covariance function with compact support. New likelihood functions in lik/: likGauss.m, likLaplace.m, likLogistic.m and likT.m New mean functions in mean/: meanConst.m, meanLinear.m, meanPow.m, meanProd.m, meanSum.m and meanZero.m New covariance functions in cov/: covADD.m, covMask.m, covPPiso.m The gprSRPP.m function which previously provided "Subset of Regressors" and the "Projected Process" approximation has now been removed. NEW in version 2.1, 2007-07-25 ------------------------------ covConst.m: fixed a bug which caused an error in the derivative of the log marginal likelihood for certain combinations of covariance functions and approximation methods. (Thanks to Antonio Eleuteri for reporting the problem) gauher.m: added the function "gauher.m" which was mistakenly missing from the previous release. This caused an error for certain combinations of approximation method and likelihood function. logistic.m: modified the approximation of moments calculation to use a mixture of cumulative Gaussian, rather than Gauss-Hermite quadrature, as the former turns out to be more accurate. NEW in version 2.0, 2007-06-25 ------------------------------ Some code restructuring has taken place for the classification code to make it more modular, to facilitate addition of new likelihood functions and approximations methods. Now, all classification is done using the binaryGP function, which (among other things) takes an approximation method and a likelihood function as an arguments. Thus, binaryGP replaces both binaryEPGP and binaryLapaceGP, although wrapper functions are still provided for backward compatibility. This gives added flexibility: now EP can also be used wth the logistic likelihood function (implemented using Gauss-Hermite quadrature). approxEP.m: New file, containing the Expectation Propagation approximation method, which was previously contained in binaryEPGP.m approxLA.m: New file, containing Laplaces approximation method, which was previously contained in binaryLaplace.m approximations.m: New file, help for the approximation methods. binaryEPGP.m: This file has been replaced by a wrapper (for backward compatibility) which calls the more general binaryGP function. binaryGP.m: New general function to do binary classification. binaryLaplaceGP.m: This file has been replaced by a wrapper (for backward compatibility) which calls the more general binaryGP function. covMatern3iso.m, covMatern5iso.m, covNNone.m, covRQard.m, covRQiso.m, cosSEard, covSEiso: now check more carefully, that persistent variables have the correct sizes, and some variable names have been modified. cumGauss.m: New file, containing code for the cumulative Gaussian likelihood function likelihoods.m: New file, help for likelihood functions logistic.m: New file, logistic likelihood NEW in version 1.3, 2006-09-08 ------------------------------ covRQard.m: bugfix: replaced x with x' and z with z' in line 36 covRQiso.m: bugfix: replaced x with x' and z with z' in line 28 minimize.m: correction: replaced "error()" with "error('')", and made a few cosmetic changes binaryEPGP.m: added the line "lml = -n*log(2);" in line 77. This change should be largely inconsequential, but occationally may save things when the covariance matrix is exceptionally badly conditioned. NEW in version 1.2, 2006-05-10 ------------------------------ added the "erfint" function to "binaryLaplaceGP.m". The erfint function was missing by mistake, preventing the use of the "logistic" likelihood. NEW in version 1.1, 2006-04-12 ------------------------------ added files: "covProd.m" and "covPeriodic.m" changes: "covSEiso.m" was changed slightly to avoid the use of persistent variables NEW in version 1.0, 2006-03-29 ------------------------------ initial version shipped with the book