{"id":15704888,"url":"https://github.com/ziatdinovmax/gpim","last_synced_at":"2025-04-14T12:42:21.520Z","repository":{"id":51946346,"uuid":"241448693","full_name":"ziatdinovmax/GPim","owner":"ziatdinovmax","description":"Gaussian processes and Bayesian optimization for images and hyperspectral data","archived":false,"fork":false,"pushed_at":"2023-11-24T06:29:59.000Z","size":55845,"stargazers_count":55,"open_issues_count":1,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-05-08T05:35:43.873Z","etag":null,"topics":["bayesian-optimization","colab-notebook","gaussian-processes","hyperspectral-images","image-processing","lattice-models","microscopy"],"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/ziatdinovmax.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,"governance":null}},"created_at":"2020-02-18T19:28:27.000Z","updated_at":"2024-04-04T11:01:21.000Z","dependencies_parsed_at":"2023-11-24T07:25:58.423Z","dependency_job_id":null,"html_url":"https://github.com/ziatdinovmax/GPim","commit_stats":{"total_commits":471,"total_committers":4,"mean_commits":117.75,"dds":"0.39490445859872614","last_synced_commit":"022f8240b6b0c1b283d38d4d72fb30a567ec0f6a"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziatdinovmax%2FGPim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziatdinovmax%2FGPim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziatdinovmax%2FGPim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziatdinovmax%2FGPim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ziatdinovmax","download_url":"https://codeload.github.com/ziatdinovmax/GPim/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248883160,"owners_count":21177168,"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-optimization","colab-notebook","gaussian-processes","hyperspectral-images","image-processing","lattice-models","microscopy"],"created_at":"2024-10-03T20:14:11.434Z","updated_at":"2025-04-14T12:42:21.489Z","avatar_url":"https://github.com/ziatdinovmax.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Downloads](https://pepy.tech/badge/gpim/month)](https://pepy.tech/project/gpim/month)\n[![PyPI version](https://badge.fury.io/py/gpim.svg)](https://badge.fury.io/py/gpim)\n\n[![build](https://github.com/pycroscopy/atomai/actions/workflows/actions.yml/badge.svg)](https://github.com/ziatdinovmax/GPim/actions/workflows/actions.yml)\n[![Documentation Status](https://readthedocs.org/projects/gpim/badge/?version=latest)](https://gpim.readthedocs.io/en/latest/?badge=latest)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/07ee1606a88b48d1bc46453f3ae1b1c8)](https://app.codacy.com/manual/ziatdinovmax/GPim?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=ziatdinovmax/GPim\u0026utm_campaign=Badge_Grade_Dashboard)\n\n[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ziatdinovmax/GPim/blob/master/examples/notebooks/Quickstart_GPim.ipynb)\n[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ziatdinovmax/GPim)\n\n## What is GPim\n\nGPim is a python package that provides an easy way to apply Gaussian processes (GP) in [Pyro](https://pyro.ai/) and [Gpytorch](https://gpytorch.ai/) to images and hyperspectral data and to perform GP-based Bayesian optimization on grid data. The intended audience are domain scientists (for example, microscopists) with a basic knowledge of how to work with numpy arrays in Python.\n\u003cbr\u003e\u003cbr\u003e\nScientific papers that use GPim:\n\n-   GP for 3D hyperspectral microscopy data: [npj Comput Mater 6, 21 (2020)](https://www.nature.com/articles/s41524-020-0289-6)\n-   GP for 4D hyperspectral microscopy data: [Journal of Applied Physics 128, 055101 (2020)](https://aip.scitation.org/doi/10.1063/5.0013847)\n-   GP and GP-based BO for Ising model: [Journal of Applied Physics 128, 164304 (2020)](https://aip.scitation.org/doi/10.1063/5.0021762)\n-   GP-based BO for hysteresis loop engineering in ferroelectrics: [Journal of Applied Physics 128, 024102 (2020)](https://aip.scitation.org/doi/10.1063/5.0011917)\n-   GP-based BO for automated experiments in microscopy: [ACS Nano 15, 11253–11262 (2021)](https://doi.org/10.1021/acsnano.0c10239)\n \n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"misc/GPim_illustration_v3.jpg\" width=\"95%\" title=\"GPim\"\u003e\n\u003cp align=\"justify\"\u003e\n\n## Installation\n\nFirst install [PyTorch](https://pytorch.org/). Then install GPim using\n\n```bash\npip install gpim\n```\n\n\n## How to use\n### GP reconstruction\n\nBelow is a simple example of applying GPim to reconstructing a sparse 2D image. It can be similarly applied to 3D and 4D hyperspectral data. The missing data points in sparse data must be represented as [NaNs](https://docs.scipy.org/doc/numpy/reference/constants.html?highlight=numpy%20nan#numpy.nan). In the absense of missing observation GPim can be used for image and spectroscopic data cleaning/smoothing in all the dimensions simultaneously, as well as for the resolution enhancement.\n\n```python\nimport gpim\nimport numpy as np\n\n# # Load dataset\nR = np.load('sparse_exp_data.npy') \n\n# Get full (ideal) grid indices\nX_full = gpim.utils.get_full_grid(R, dense_x=1)\n# Get sparse grid indices\nX_sparse = gpim.utils.get_sparse_grid(R)\n# Kernel lengthscale constraints (optional)\nlmin, lmax = 1., 4.\nlscale = [[lmin, lmin], [lmax, lmax]] \n\n# Run GP reconstruction to obtain mean prediction and uncertainty for each predictied point\nmean, sd, hyperparams = gpim.reconstructor(\n    X_sparse, R, X_full, lengthscale=lscale,\n    learning_rate=0.1, iterations=250, \n    use_gpu=True, verbose=False).run()\n\n# Plot reconstruction results\ngpim.utils.plot_reconstructed_data2d(R, mean, cmap='jet')\n# Plot evolution of kernel hyperparameters during training\ngpim.utils.plot_kernel_hyperparams(hyperparams)\n```\n\n### GP-based Bayesian optimization\nWhen performing measurements (real or simulated), one can use the information about the expected function value and uncertainty in GP reconstruction to select the next measurement point. This is usually referred to as exploration-exploitation approach in the context of Bayesian optimization. A simple example with a \"dummy\" function is shown below.\n\n```python\nimport gpim\nimport numpy as np\nnp.random.seed(42)\n\n# Create a dummy 2D function\ndef trial_func(idx):\n    \"\"\"\n    Takes a list of indices as input and returns function value at these indices\n    \"\"\"\n    def func(x0, y0, a, b, fwhm): \n        return np.exp(-4*np.log(2) * (a*(idx[0]-x0)**2 + b*(idx[1]-y0)**2) / fwhm**2)\n    Z1 = func(5, 10, 1, 1, 4.5)\n    Z2 = func(10, 8, 0.75, 1.5, 7)\n    Z3 = func(18, 18, 1, 1.5, 10)\n    return Z1 + Z2 + Z3\n\n# Create an empty observation matrix\ngrid_size = 25\nZ_sparse = np.ones((grid_size, grid_size)) * np.nan\n# Seed it with several random observations\nidx = np.random.randint(0, grid_size, size=(4, 2))\nfor i in idx:\n    Z_sparse[tuple(i)] = trial_func(i) \n\n# Get full and sparse grid indices for GP\nX_full = gpim.utils.get_full_grid(Z_sparse)\nX_sparse= gpim.utils.get_sparse_grid(Z_sparse)\n# Initialize Bayesian optimizer with an 'expected improvement' acquisition function\nboptim = gpim.boptimizer(\n    X_sparse, Z_sparse, X_full, \n    trial_func, acquisition_function='ei',\n    exploration_steps=30,\n    use_gpu=False, verbose=1)\n# Run Bayesian optimization\nboptim.run()\n\n# Plot exploration history\ngpim.utils.plot_query_points(boptim.indices_all, plot_lines=True)\n```\n\n## Running GPim notebooks in the cloud\n\n1) Executable Google Colab [notebook](https://colab.research.google.com/github/ziatdinovmax/GPim/blob/master/examples/notebooks/GP_2D3D_images.ipynb) with the examples of applying GP to sparse spiral 2D scans in piezoresponse force microscopy (PFM), simulated 2D atomic image in electron microscopy, and hyperspectral 3D data in Band Excitation PFM.\n2) Executable Google Colab [notebook](https://colab.research.google.com/github/ziatdinovmax/GPim/blob/master/examples/notebooks/GP_EELS.ipynb) with the example of applying \"parallel\" GP method to analysis of EELS data.\n3) Executable Google Colab [notebook](https://colab.research.google.com/github/ziatdinovmax/GPim/blob/master/examples/notebooks/GP_TD_cKPFM.ipynb) with the example of applying GP to 4D spectroscopic dataset for smoothing and resolution enhancement in contact Kelvin Probe Force Microscopy (cKPFM).\n4) Executable Google Colab [notebook](https://colab.research.google.com/github/ziatdinovmax/GPim/blob/master/examples/notebooks/GP_based_exploration_exploitation.ipynb) with a simple example of performing GP-based exploration-exploitation on a toy dataset.\n\n## Requirements\n\nIt is strongly recommended to run the codes with a GPU hardware accelerator (such as NVIDIA's P100 or V100 GPU). If you don't have a GPU on your local machine, you may rent a cloud GPU from [Google Cloud AI Platform](https://cloud.google.com/deep-learning-vm/). Running the [example notebooks](https://colab.research.google.com/github/ziatdinovmax/GPim/blob/master/examples/notebooks/Quickstart_GPim.ipynb) one time from top to bottom will cost about 1 USD with a standard deep learning VM instance (one P100 GPU and 15 GB of RAM).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fziatdinovmax%2Fgpim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fziatdinovmax%2Fgpim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fziatdinovmax%2Fgpim/lists"}