{"id":19463202,"url":"https://github.com/jajcayn/pygpso","last_synced_at":"2025-04-25T08:32:14.229Z","repository":{"id":51261694,"uuid":"236983676","full_name":"jajcayn/pygpso","owner":"jajcayn","description":"Gaussian-Processes Surrogate Optimisation in python","archived":false,"fork":false,"pushed_at":"2021-05-18T16:40:40.000Z","size":3240,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T23:23:01.845Z","etag":null,"topics":["bayesian-optimisation","brainweb","gaussian-processes","gaussian-processes-surrogate","gpflow","neuroscience","neuroscience-methods","optimisation","partition-tree","python3","scale-biophysical-models","space-partition-tree"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jajcayn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-29T13:04:47.000Z","updated_at":"2023-04-17T15:05:00.000Z","dependencies_parsed_at":"2022-09-26T16:31:16.144Z","dependency_job_id":null,"html_url":"https://github.com/jajcayn/pygpso","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jajcayn%2Fpygpso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jajcayn%2Fpygpso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jajcayn%2Fpygpso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jajcayn%2Fpygpso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jajcayn","download_url":"https://codeload.github.com/jajcayn/pygpso/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250782248,"owners_count":21486417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bayesian-optimisation","brainweb","gaussian-processes","gaussian-processes-surrogate","gpflow","neuroscience","neuroscience-methods","optimisation","partition-tree","python3","scale-biophysical-models","space-partition-tree"],"created_at":"2024-11-10T18:09:04.348Z","updated_at":"2025-04-25T08:32:13.862Z","avatar_url":"https://github.com/jajcayn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/jajcayn/pygpso/workflows/pytest/badge.svg)](https://github.com/jajcayn/pygpso/actions) ![](https://img.shields.io/github/v/release/jajcayn/pygpso) [![codecov](https://codecov.io/gh/jajcayn/pygpso/branch/master/graph/badge.svg)](https://codecov.io/gh/jajcayn/pygpso) [![PyPI license](https://img.shields.io/pypi/l/pygpso.svg)](https://pypi.python.org/pypi/pygpso/) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jajcayn/pygpso.git/master?filepath=examples) [![DOI](https://zenodo.org/badge/236983676.svg)](https://zenodo.org/badge/latestdoi/236983676) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n# pyGPSO\n\n*Optimise anything (but mainly large-scale biophysical models) using Gaussian Processes surrogate*\n\n`pyGPSO` is a python package for Gaussian-Processes Surrogate Optimisation. GPSO is a Bayesian optimisation method designed to cope with costly, high-dimensional, non-convex problems by switching between exploration of the parameter space (using partition tree) and exploitation of the gathered knowledge (by training the surrogate function using Gaussian Processes regression). The motivation for this method stems from the optimisation of large-scale biophysical models in neuroscience when the modelled data should match the experimental one. This package leverages [`GPFlow`](https://github.com/GPflow/GPflow) for training and predicting the Gaussian Processes surrogate.\n\nThis is port of original [Matlab implementation](https://github.com/jhadida/gpso) by the paper's author.\n\n**Reference**: Hadida, J., Sotiropoulos, S. N., Abeysuriya, R. G., Woolrich, M. W., \u0026 Jbabdi, S. (2018). Bayesian Optimisation of Large-Scale Biophysical Networks. NeuroImage, 174, 219-236.\n\nComparison of the GPR surrogate and the true objective function after optimisation.\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"resources/example_GPRsurrogate.svg\" width=\"720\"\u003e\n\u003c/p\u003e\n\nExample of ternary partition tree after optimisation.\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"resources/example_ternary_tree.svg\" width=\"720\"\u003e\n\u003c/p\u003e\n\n## Installation\n\n`GPSO` package is tested and should run without any problems on python versions 3.6 -- 3.9.\n\n### Note on python3.9 with macOS\n\nInstalling `pytables` might give you hdf5 errors. If this is the case, please do\n\n```bash\nbrew install hdf5 c-blosc\n```\n\nand all should work like a charm afterwards.\n\n### One-liner\n\nFor those who want to optimise right away just\n\n```bash\npip install pygpso\n```\n\nand go ahead! Make sure to check example notebooks in [the **examples** directory](examples/) to see how it works and what it can do. Or, alternatively, you can run interactive notebooks in binder: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jajcayn/pygpso.git/master?filepath=examples)\n\n### Go proper\n\nWhen you are the type of girl or guy who likes to install packages properly, start by cloning (or forking) this repository, then installing all the dependencies and finally install the package itself\n\n```bash\ngit clone https://github.com/jajcayn/pygpso\ncd pygpso/\npip install -r requirements.txt\n# optionally, but recommended\npip install -r requirements_optional.txt\npip install .\n```\n\nDon't forget to test!\n\n```bash\npytest\n```\n\n## Usage\n\nA guide on how to optimise and what can be done using this package is given as jupyter notebooks in [the **examples** directory](examples/). You can also try them out live thanks to binder: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jajcayn/pygpso.git/master?filepath=examples).\n\nThe basic idea is to initialise the parameter space in which the optimisation is to be run and then iteratively dig deeper and evaluate the objective function when necessary\n\n```python\nfrom gpso import ParameterSpace, GPSOptimiser\n\n\ndef objective_function(params):\n    # params as a list or tuple\n    x, y = params\n    ...\n    \u003csome hardcore computation\u003e\n    ...\n    return \u003cfloat\u003e\n\n# bounds of the parameters we will optimise\nx_bounds = [-3, 5]\ny_bounds = [-3, 3]\nspace = ParameterSpace(parameter_names=[\"x\", \"y\"], parameter_bounds=[x_bounds, y_bounds])\nopt = GPSOptimiser(parameter_space=space, n_workers=4)\nbest_point = opt.run(objective_function)\n```\n\nThe package also offers plotting functions for visualising the results. Again, those are documented and showcased in [the **examples** directory](examples/).\n\n### Notes\n\nGaussian Processes regression uses normalised coordinates within the bounds [0, 1]. All normalisation and de-normalisation is done automatically, however when you want to call `predict_y` on GPR model, do not forget to pass normalised coordinates. The normalisation is handled by `sklearn.MinMaxScaler` and `ParameterSpace` instance offers a convenience functions for this: `ParameterSpace.normalise_coords(orig_coords)` and `ParameterSpace.denormalise_coords(normed_coords)`.\n\nPlotting of the ternary tree (`gpso.plotting.plot_ternary_tree()`) requires `igraph` package, whose layout function is exploited. If you want to see the resulting beautiful tree, please install `python-igraph`.\n\nSupport of saver (for saving models run, e.g. timeseries along with the optimisation) is provided by `PyTables` (and `pandas` if you're saving results to `DataFrame`s).\n\n## Known bugs and future improvements\n\n* saving of GP surrogate is now hacky, as `GPFlow` supports only saving model for future prediction but AFAIK they cannot be trained anymore, since the information on kernels and mean-functions are not saved (only the trained weights in the computational graph). Thus, `pyGPSO` still relies on hacky saving to `pkl` files and recreating kernels and mean-function on-the-go when loading from saved.\n\n## Final notes\n\nWhen you encounter a bug or have any idea for an improvement, please open an issue and/or contact me.\n\nWhen using this package in publications, please cite the original Jonathan's paper for the methodology as\n\n```bibtex\n@article{hadida2018bayesian,\n  title={Bayesian Optimisation of Large-Scale Biophysical Networks},\n  author={Hadida, Jonathan and Sotiropoulos, Stamatios N and Abeysuriya, Romesh G and Woolrich, Mark W and Jbabdi, Saad},\n  journal={Neuroimage},\n  volume={174},\n  pages={219--236},\n  year={2018},\n  publisher={Elsevier}\n}\n```\n\nand acknowledge the usage of this software via its DOI: [![DOI](https://zenodo.org/badge/236983676.svg)](https://zenodo.org/badge/latestdoi/236983676). After clicking, you will see citation data.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjajcayn%2Fpygpso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjajcayn%2Fpygpso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjajcayn%2Fpygpso/lists"}