1# GPy 2 3The Gaussian processes framework in Python. 4 5* GPy [homepage](http://sheffieldml.github.io/GPy/) 6* Tutorial [notebooks](http://nbviewer.ipython.org/github/SheffieldML/notebook/blob/master/GPy/index.ipynb) 7* User [mailing-list](https://lists.shef.ac.uk/sympa/subscribe/gpy-users) 8* Developer [documentation](http://gpy.readthedocs.io/) [documentation (devel branch)](https://gpy.readthedocs.io/en/devel/) 9* Travis-CI [unit-tests](https://travis-ci.org/SheffieldML/GPy) 10* [![licence](https://img.shields.io/badge/licence-BSD-blue.svg)](http://opensource.org/licenses/BSD-3-Clause) 11 [![Research software impact](http://depsy.org/api/package/pypi/GPy/badge.svg)](http://depsy.org/package/python/GPy) 12 13## Status 14 15| Branch | travis-ci.org | ci.appveyor.com | coveralls.io | codecov.io | 16| --- | --- | --- | --- | --- | 17| Default branch (`devel`) | [![travis-devel](https://travis-ci.org/SheffieldML/GPy.svg?branch=devel)](https://travis-ci.org/SheffieldML/GPy/branches) | [![appveyor-devel](https://ci.appveyor.com/api/projects/status/662o6tha09m2jix3/branch/devel?svg=true)](https://ci.appveyor.com/project/mzwiessele/gpy/branch/devel) | [![coveralls-devel](https://coveralls.io/repos/github/SheffieldML/GPy/badge.svg?branch=devel)](https://coveralls.io/github/SheffieldML/GPy?branch=devel) | [![codecov-devel](http://codecov.io/github/SheffieldML/GPy/coverage.svg?branch=devel)](http://codecov.io/github/SheffieldML/GPy?branch=devel) | 18| Deployment branch (`deploy`) | [![travis-deploy](https://travis-ci.org/SheffieldML/GPy.svg?branch=deploy)](https://travis-ci.org/SheffieldML/GPy/branches) | [![appveyor-deploy](https://ci.appveyor.com/api/projects/status/662o6tha09m2jix3/branch/deploy?svg=true)](https://ci.appveyor.com/project/mzwiessele/gpy/branch/deploy) | [![coveralls-deploy](https://coveralls.io/repos/github/SheffieldML/GPy/badge.svg?branch=deploy)](https://coveralls.io/github/SheffieldML/GPy?branch=deploy) | [![codecov-deploy](http://codecov.io/github/SheffieldML/GPy/coverage.svg?branch=deploy)](http://codecov.io/github/SheffieldML/GPy?branch=deploy) | 19 20## What's new: 21 22From now on we keep track of changes in the CHANGELOG.md. 23If you want your changes to show up there follow the [guidelines](#gl). 24In particular tag your commits by the [gitchangelog](https://github.com/vaab/gitchangelog) commit message format. 25 26## Contributing to GPy 27 28We welcome any contributions to GPy, after all it is an open source project. We use the GitHub feature of pull requests for contributions. 29 30For an in depth description of pull requests, please visit https://help.github.com/articles/using-pull-requests/ . 31 32### Steps to a successful contribution: 33 34 1. Fork GPy: https://help.github.com/articles/fork-a-repo/ 35 2. Make your changes to the source in your fork. 36 3. Make sure the [guidelines](#gl) are met. 37 4. Set up tests to test your code. We are using unittests in the testing subfolder of GPy. There is a good chance 38 that there is already a framework set up to test your new model in model_tests.py or kernel in kernel_tests.py. have a look at the source and you might be able to just add your model (or kernel or others) as an additional test in the appropriate file. There is more frameworks for testing the other bits and pieces, just head over to the testing folder and have a look. 39 5. Create a pull request to the devel branch in GPy, see above. 40 6. The tests will be running on your pull request. In the comments section we will be able to discuss the changes and help you with any problems. Let us know if there are any in the comments, so we can help. 41 7. The pull request gets accepted and your awesome new feature will be in the next GPy release :) 42 43For any further questions/suggestions head over to the issues section in GPy. 44 45<a name=gl></a> 46### Pull Request Guidelines 47 48 - Check your code with PEP8 or pylint. Try to stick to 80 columns wide. 49 - Separate commits per smallest concern. 50 - Each functionality/bugfix commit should contain code, tests, and doc. 51 - We are using gitchangelog to keep track of changes and log new features. So if you want your changes to show up in the changelog, make sure you follow the [gitchangelog](https://github.com/vaab/gitchangelog) commit message format. 52 53## Support and questions to the community 54 55Ask questions using the issues section. 56 57## Updated Structure 58 59We have pulled the core parameterization out of GPy. It is a package called [paramz](https://github.com/sods/paramz) and is the pure gradient based model optimization. 60 61If you installed GPy with pip, just upgrade the package using: 62 63 $ pip install --upgrade GPy 64 65If you have the developmental version of GPy (using the develop or -e option) just install the dependencies by running 66 67 $ python setup.py develop 68 69again, in the GPy installation folder. 70 71A warning: This usually works, but sometimes `distutils/setuptools` opens a 72whole can of worms here, specially when compiled extensions are involved. 73If that is the case, it is best to clean the repo and reinstall. 74 75## Supported Platforms: 76 77[<img src="https://www.python.org/static/community_logos/python-logo-generic.svg" height=40px>](https://www.python.org/) 78[<img src="https://upload.wikimedia.org/wikipedia/commons/5/5f/Windows_logo_-_2012.svg" height=40px>](http://www.microsoft.com/en-gb/windows) 79[<img src="https://upload.wikimedia.org/wikipedia/commons/8/8e/OS_X-Logo.svg" height=40px>](http://www.apple.com/osx/) 80[<img src="https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg" height=40px>](https://en.wikipedia.org/wiki/List_of_Linux_distributions) 81 82Python 3.5 and higher 83 84## Citation 85 86 @Misc{gpy2014, 87 author = {{GPy}}, 88 title = {{GPy}: A Gaussian process framework in python}, 89 howpublished = {\url{http://github.com/SheffieldML/GPy}}, 90 year = {since 2012} 91 } 92 93### Pronounciation: 94 95We like to pronounce it 'g-pie'. 96 97## Getting started: installing with pip 98 99We are requiring a recent version (1.3.0 or later) of 100[scipy](http://www.scipy.org/) and thus, we strongly recommend using 101the [anaconda python distribution](http://continuum.io/downloads). 102With anaconda you can install GPy by the following: 103 104 conda update scipy 105 106Then potentially try, 107 108 sudo apt-get update 109 sudo apt-get install python3-dev 110 sudo apt-get install build-essential 111 conda update anaconda 112 113And finally, 114 115 pip install gpy 116 117We've also had luck with [enthought](http://www.enthought.com). Install scipy 1.3.0 (or later) 118 and then pip install GPy: 119 120 pip install gpy 121 122If you'd like to install from source, or want to contribute to the project (i.e. by sending pull requests via github), read on. 123 124### Troubleshooting installation problems 125 126If you're having trouble installing GPy via `pip install GPy` here is a probable solution: 127 128 git clone https://github.com/SheffieldML/GPy.git 129 cd GPy 130 git checkout devel 131 python setup.py build_ext --inplace 132 nosetests GPy/testing 133 134### Direct downloads 135 136[![PyPI version](https://badge.fury.io/py/GPy.svg)](https://pypi.python.org/pypi/GPy) [![source](https://img.shields.io/badge/download-source-green.svg)](https://pypi.python.org/pypi/GPy) 137[![Windows](https://img.shields.io/badge/download-windows-orange.svg)](https://pypi.python.org/pypi/GPy) 138[![MacOSX](https://img.shields.io/badge/download-macosx-blue.svg)](https://pypi.python.org/pypi/GPy) 139 140# Saving models in a consistent way across versions: 141 142As pickle is inconsistent across python versions and heavily dependent on class structure, it behaves inconsistent across versions. 143Pickling as meant to serialize models within the same environment, and not to store models on disk to be used later on. 144 145To save a model it is best to save the m.param_array of it to disk (using numpy’s np.save). 146Additionally, you save the script, which creates the model. 147In this script you can create the model using initialize=False as a keyword argument and with the data loaded as normal. 148You then set the model parameters by setting m.param_array[:] = loaded_params as the previously saved parameters. 149Then you initialize the model by m.initialize_parameter(), which will make the model usable. 150Be aware that up to this point the model is in an inconsistent state and cannot be used to produce any results. 151 152```python 153# let X, Y be data loaded above 154# Model creation: 155m = GPy.models.GPRegression(X, Y) 156m.optimize() 157# 1: Saving a model: 158np.save('model_save.npy', m.param_array) 159# 2: loading a model 160# Model creation, without initialization: 161m_load = GPy.models.GPRegression(X, Y, initialize=False) 162m_load.update_model(False) # do not call the underlying expensive algebra on load 163m_load.initialize_parameter() # Initialize the parameters (connect the parameters up) 164m_load[:] = np.load('model_save.npy') # Load the parameters 165m_load.update_model(True) # Call the algebra only once 166print(m_load) 167``` 168## For Admins and Developers: 169 170### Running unit tests: 171 172New way of running tests is using coverage: 173 174Ensure nose and coverage is installed: 175 176 pip install nose coverage 177 178Run nosetests from root directory of repository: 179 180 coverage run travis_tests.py 181 182Create coverage report in htmlcov/ 183 184 coverage html 185 186The coverage report is located in htmlcov/index.html 187 188##### Legacy: using nosetests 189 190Ensure nose is installed via pip: 191 192 pip install nose 193 194Run nosetests from the root directory of the repository: 195 196 nosetests -v GPy/testing 197 198or from within IPython 199 200 import GPy; GPy.tests() 201 202or using setuptools 203 204 python setup.py test 205 206 207### Compiling documentation: 208 209The documentation is stored in doc/ and is compiled with the Sphinx Python documentation generator, and is written in the reStructuredText format. 210 211The Sphinx documentation is available here: http://sphinx-doc.org/latest/contents.html 212 213**Installing dependencies:** 214 215To compile the documentation, first ensure that Sphinx is installed. On Debian-based systems, this can be achieved as follows: 216 217 sudo apt-get install python-pip 218 sudo pip install sphinx 219 220**Compiling documentation:** 221 222The documentation can be compiled as follows: 223 224 cd doc 225 sphinx-apidoc -o source/ ../GPy/ 226 make html 227 228alternatively: 229 230```{shell} 231cd doc 232sphinx-build -b html -d build/doctrees -D graphviz_dot='<path to dot>' source build/html 233``` 234 235The HTML files are then stored in doc/build/html 236 237### Commit new patch to devel 238 239If you want to merge a branch into devel make sure the following steps are met: 240 241 - Create a local branch from the pull request and merge the current devel in. 242 - Look through the changes on the pull request. 243 - Check that tests are there and are checking code where applicable. 244 - [optional] Make changes if necessary and commit and push to run tests. 245 - [optional] Repeat the above until tests pass. 246 - [optional] bump up the version of GPy using bumpversion. The configuration is done, so all you need is bumpversion [major|minor|patch]. 247 - Update the changelog using gitchangelog: `gitchangelog > CHANGELOG.md` 248 - Commit the changes of the changelog as silent update: `git commit -m "chg: pkg: CHANGELOG update" CHANGELOG.md 249 - Push the changes into devel. 250 251A usual workflow should look like this: 252 253 $ git fetch origin 254 $ git checkout -b <pull-origin>-devel origin/<pull-origin>-devel 255 $ git merge devel 256 $ coverage run travis_tests.py 257 258**Make changes for tests to cover corner cases (if statements, None arguments etc.)** 259Then we are ready to make the last changes for the changelog and versioning: 260 261 $ git commit -am "fix: Fixed tests for <pull-origin>" 262 $ bumpversion patch # [optional] 263 $ gitchangelog > CHANGELOG.md 264 $ git commit -m "chg: pkg: CHANGELOG update" CHANGELOG.md 265 266Now we can merge the pull request into devel: 267 268 $ git checkout devel 269 $ git merge --no-ff <pull-origin>-devel 270 $ git push origin devel 271 272This will update the devel branch of GPy. 273 274### Deploying GPy 275 276We have set up all deployment automatic. 277Thus, all you need to do is create a pull request from devel to deploy. 278Wait for the tests to finish (successfully!) and merge the pull request. 279This will update the package on pypi for all platforms fully automatically. 280 281## Funding Acknowledgements 282 283Current support for the GPy software is coming through the following projects. 284 285* [EU FP7-HEALTH Project Ref 305626](http://radiant-project.eu) "RADIANT: Rapid Development and Distribution of Statistical Tools for High-Throughput Sequencing Data" 286 287* [EU FP7-PEOPLE Project Ref 316861](http://staffwww.dcs.shef.ac.uk/people/N.Lawrence/projects/mlpm/) "MLPM2012: Machine Learning for Personalized Medicine" 288 289* MRC Special Training Fellowship "Bayesian models of expression in the transcriptome for clinical RNA-seq" 290 291* [EU FP7-ICT Project Ref 612139](http://staffwww.dcs.shef.ac.uk/people/N.Lawrence/projects/wysiwyd/) "WYSIWYD: What You Say is What You Did" 292 293Previous support for the GPy software came from the following projects: 294 295- [BBSRC Project No BB/K011197/1](http://staffwww.dcs.shef.ac.uk/people/N.Lawrence/projects/recombinant/) "Linking recombinant gene sequence to protein product manufacturability using CHO cell genomic resources" 296- [EU FP7-KBBE Project Ref 289434](http://staffwww.dcs.shef.ac.uk/people/N.Lawrence/projects/biopredyn/) "From Data to Models: New Bioinformatics Methods and Tools for Data-Driven Predictive Dynamic Modelling in Biotechnological Applications" 297- [BBSRC Project No BB/H018123/2](http://staffwww.dcs.shef.ac.uk/people/N.Lawrence/projects/iterative/) "An iterative pipeline of computational modelling and experimental design for uncovering gene regulatory networks in vertebrates" 298- [Erasysbio](http://staffwww.dcs.shef.ac.uk/people/N.Lawrence/projects/synergy/) "SYNERGY: Systems approach to gene regulation biology through nuclear receptors" 299