<!---
obsidian
ReadMe
-->
<div align = "center">
<img src="https://github.com/MSDLLCpapers/obsidian/blob/main/docs/_static/obsidian_logo.svg?raw=true" class="only-light" width="100" alt = "obsidian logo">
</div>
<div align="center">
<h1> obsidian</h1>
[](https://github.com/MSDLLCpapers/obsidian/blob/main/LICENSE)
[](https://github.com/MSDLLCpapers/obsidian/issues)
[](https://pypi.org/project/obsidian-apo/)
[](https://msdllcpapers.github.io/obsidian/)
[](https://codecov.io/github/kstone40/obsidian)
__obsidian__ is a library for algorithmic process design and black-box optimization using AI-guided experiment design
</div>
The _obsidian_ library offers a set of modules for designing, executing, analyzing, and visualizing algorithmic process optimization (APO) using sample-efficient strategies such as Bayesian Optimization (BO). _obsidian_ uses highly flexible models to build internal representations of the measured system in a way that can be explored for characterization and exploited for maximization based on uncertainty estimation and exploration strategies. _obsidian_ supports batch experimentation (joint optimization and parallel evaluation) and is highly configurable for varying use cases, although the default specifications are encouraged.
_We thank you for your patience and invite you to collaborate with us while __obsidian__ is in beta!_
# Key Features
1. __End-User-Friendly__: Designed to elevate the average process development scientist. No machine learning experience required.
2. __Deployable__ using pre-built _Dash_ application. Each class is fully serializable, without third-party packages, to enable web-based API usage.
3. __Explainable__ and visualizable using SHAP analysis and interactive figures.
5. __Flexible__: Handles any input (numeric, discrete) and optionally input/output constraints, multiple outcomes, batch optimization, and a variety of novelty objective compositions. We know that experiment campaigns can have fluctuating objectives and resources, and _obsidian_ is built to support that.
6. __Purpose-Driven Development__: Impactful features proposed, developed, maintained, and used by laboratory bench scientists. Revelantly designed for process development, optimization, and characterization.
# How it Works: Algorithmic Optimization
The workflow for algorithmic process optimization is an iterative workflow of the following steps:
1. Collect data
2. Fit a model to the data and estimate uncertainty across a design space
3. Search for new experiments and evaluate for objective and/or informational utility
4. Design experiments where utility is maximized
5. Repeat
The central object ob the __obsidian__ library is the `BayesianOptimizer`, which can be optionally wrapped by a `Campaign`. A bayesian optimization has two key components that govern the optimization:
1. The surrogate model: A black-box model which is regressed to data and used for inference. Most often a _Gaussian Process_ (`surrogate='GP'`).
2. The acquisition function: A mathematical description of the quality of potential experiments, as it pertains to optimization. Most often _Expected Improvement_ (`acquisition=['EI']`).
# Usage Example
## Specify Parameters & Initialize a Design
```python
from obsidian import Campaign, ParamSpace, Target
from obsidian.parameters import Param_Categorical, Param_Ordinal, Param_Continuous
params = [
Param_Continuous('Temperature', -10, 30),
Param_Continuous('Concentration', 10, 150),
Param_Continuous('Enzyme', 0.01, 0.30),
Param_Categorical('Variant', ['MRK001', 'MRK002', 'MRK003']),
Param_Ordinal('Stir Rate', ['Low', 'Medium', 'High']),
]
X_space = ParamSpace(params)
target = Target('Yield', aim='max')
campaign = Campaign(X_space, target)
X0 = campaign.designer.initialize(10, 'LHS', seed=0)
```
| | Temperature | Concentration | Enzyme | Variant | Stir Rate |
|---:|--------------:|----------------:|---------:|:----------|:------------|
| 0 | 8 | 17 | 0.1405 | MRK001 | Medium |
| 1 | 12 | 143 | 0.1695 | MRK003 | Medium |
| 2 | 4 | 101 | 0.2855 | MRK002 | High |
| 3 | 28 | 87 | 0.1115 | MRK002 | Low |
| 4 | -4 | 115 | 0.2275 | MRK001 | Low |
| 5 | -8 | 73 | 0.0825 | MRK002 | Medium |
| 6 | 20 | 129 | 0.0535 | MRK001 | High |
| 7 | 24 | 31 | 0.2565 | MRK002 | Medium |
| 8 | 16 | 59 | 0.1985 | MRK003 | High |
| 9 | 0 | 45 | 0.0245 | MRK003 | Low |
## Collect Data and Fit the Optimizer
```python
campaign.add_data(Z0)
campaign.fit()
```
## Suggest New Experiments
```python
campaign.optimizer.suggest(m_batch=2)
```
| | Temperature | Concentration | Enzyme | Variant | Stir Rate | Yield (pred) | Yield lb | Yield ub | aq Method | aq Value |
|---:|--------------:|----------------:|----------:|:----------|:------------|---------------:|-----------:|-----------:|:------------|-----------:|
| 0 | -10 | 10 | 0.0918096 | MRK001 | Medium | 112.497 | 102.558 | 122.436 | EI | 0.848569 |
| 1 | -10 | 150 | 0.0882423 | MRK002 | High | 89.8334 | 79.8589 | 99.8079 | EI | 0.870511 |
# Installation
The latest _obsidian_ release can be installed using pip:
```python
pip install obsidian-apo
```
To install the required dependencies for running the _Dash_ app:
```python
pip install obsidian-apo[app]
```
Be sure to `pip` install in a newly created `conda` environment to avoid dependency conflicts.
# Contributing
See [CONTRIBUTING](https://github.com/MSDLLCpapers/obsidian/blob/main/CONTRIBUTING.md) to learn more.
## Developers
- Kevin Stone (Merck & Co., Inc.) [kevin.stone@merck.com](mailto:kevin.stone@merck.com)
- Yuting Xu (Merck & Co., Inc.) [yuting.xu@merck.com](mailto:yuting.xu@merck.com)
## Contributors
- Ajit Vikram (Merck & Co., Inc.)
- Melodie Christensen (Merck & Co., Inc.)
- Kobi Felton (Merck & Co., Inc.)
## License
__obsidian__ is licensed by the [GPLv3 license](https://github.com/MSDLLCpapers/obsidian/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://msdllcpapers.github.io/obsidian/",
"name": "obsidian-apo",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "optimization, experiment design, Bayesian optimization, process development, APO, DOE",
"author": "Kevin Stone",
"author_email": "kevin.stone38@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/30/e3/c97dca6d603c18884fbca879aa0690be1af4021e13e45aa9ccf73fb1818a/obsidian_apo-0.8.3.tar.gz",
"platform": null,
"description": "<!---\nobsidian\nReadMe\n-->\n\n<div align = \"center\">\n <img src=\"https://github.com/MSDLLCpapers/obsidian/blob/main/docs/_static/obsidian_logo.svg?raw=true\" class=\"only-light\" width=\"100\" alt = \"obsidian logo\">\n</div>\n\n\n<div align=\"center\">\n\n<h1> obsidian</h1>\n\n\n[](https://github.com/MSDLLCpapers/obsidian/blob/main/LICENSE)\n[](https://github.com/MSDLLCpapers/obsidian/issues)\n[](https://pypi.org/project/obsidian-apo/)\n[](https://msdllcpapers.github.io/obsidian/)\n[](https://codecov.io/github/kstone40/obsidian)\n\n__obsidian__ is a library for algorithmic process design and black-box optimization using AI-guided experiment design\n\n\n</div>\n\n\nThe _obsidian_ library offers a set of modules for designing, executing, analyzing, and visualizing algorithmic process optimization (APO) using sample-efficient strategies such as Bayesian Optimization (BO). _obsidian_ uses highly flexible models to build internal representations of the measured system in a way that can be explored for characterization and exploited for maximization based on uncertainty estimation and exploration strategies. _obsidian_ supports batch experimentation (joint optimization and parallel evaluation) and is highly configurable for varying use cases, although the default specifications are encouraged.\n\n_We thank you for your patience and invite you to collaborate with us while __obsidian__ is in beta!_\n\n # Key Features\n\n 1. __End-User-Friendly__: Designed to elevate the average process development scientist. No machine learning experience required.\n 2. __Deployable__ using pre-built _Dash_ application. Each class is fully serializable, without third-party packages, to enable web-based API usage. \n 3. __Explainable__ and visualizable using SHAP analysis and interactive figures.\n 5. __Flexible__: Handles any input (numeric, discrete) and optionally input/output constraints, multiple outcomes, batch optimization, and a variety of novelty objective compositions. We know that experiment campaigns can have fluctuating objectives and resources, and _obsidian_ is built to support that.\n 6. __Purpose-Driven Development__: Impactful features proposed, developed, maintained, and used by laboratory bench scientists. Revelantly designed for process development, optimization, and characterization.\n\n# How it Works: Algorithmic Optimization\nThe workflow for algorithmic process optimization is an iterative workflow of the following steps:\n\n1. Collect data\n2. Fit a model to the data and estimate uncertainty across a design space\n3. Search for new experiments and evaluate for objective and/or informational utility\n4. Design experiments where utility is maximized\n5. Repeat\n\nThe central object ob the __obsidian__ library is the `BayesianOptimizer`, which can be optionally wrapped by a `Campaign`. A bayesian optimization has two key components that govern the optimization:\n1. The surrogate model: A black-box model which is regressed to data and used for inference. Most often a _Gaussian Process_ (`surrogate='GP'`).\n2. The acquisition function: A mathematical description of the quality of potential experiments, as it pertains to optimization. Most often _Expected Improvement_ (`acquisition=['EI']`).\n\n# Usage Example\n\n## Specify Parameters & Initialize a Design\n\n```python\nfrom obsidian import Campaign, ParamSpace, Target\nfrom obsidian.parameters import Param_Categorical, Param_Ordinal, Param_Continuous\n\nparams = [\n Param_Continuous('Temperature', -10, 30),\n Param_Continuous('Concentration', 10, 150),\n Param_Continuous('Enzyme', 0.01, 0.30),\n Param_Categorical('Variant', ['MRK001', 'MRK002', 'MRK003']),\n Param_Ordinal('Stir Rate', ['Low', 'Medium', 'High']),\n ]\n\nX_space = ParamSpace(params)\ntarget = Target('Yield', aim='max')\ncampaign = Campaign(X_space, target)\nX0 = campaign.designer.initialize(10, 'LHS', seed=0)\n```\n\n| | Temperature | Concentration | Enzyme | Variant | Stir Rate |\n|---:|--------------:|----------------:|---------:|:----------|:------------|\n| 0 | 8 | 17 | 0.1405 | MRK001 | Medium |\n| 1 | 12 | 143 | 0.1695 | MRK003 | Medium |\n| 2 | 4 | 101 | 0.2855 | MRK002 | High |\n| 3 | 28 | 87 | 0.1115 | MRK002 | Low |\n| 4 | -4 | 115 | 0.2275 | MRK001 | Low |\n| 5 | -8 | 73 | 0.0825 | MRK002 | Medium |\n| 6 | 20 | 129 | 0.0535 | MRK001 | High |\n| 7 | 24 | 31 | 0.2565 | MRK002 | Medium |\n| 8 | 16 | 59 | 0.1985 | MRK003 | High |\n| 9 | 0 | 45 | 0.0245 | MRK003 | Low |\n\n\n## Collect Data and Fit the Optimizer\n\n```python\ncampaign.add_data(Z0)\ncampaign.fit()\n```\n\n## Suggest New Experiments\n\n```python\ncampaign.optimizer.suggest(m_batch=2)\n```\n\n| | Temperature | Concentration | Enzyme | Variant | Stir Rate | Yield (pred) | Yield lb | Yield ub | aq Method | aq Value |\n|---:|--------------:|----------------:|----------:|:----------|:------------|---------------:|-----------:|-----------:|:------------|-----------:|\n| 0 | -10 | 10 | 0.0918096 | MRK001 | Medium | 112.497 | 102.558 | 122.436 | EI | 0.848569 |\n| 1 | -10 | 150 | 0.0882423 | MRK002 | High | 89.8334 | 79.8589 | 99.8079 | EI | 0.870511 |\n\n# Installation\n\nThe latest _obsidian_ release can be installed using pip:\n\n```python\npip install obsidian-apo\n```\n\nTo install the required dependencies for running the _Dash_ app:\n```python\npip install obsidian-apo[app]\n```\n\nBe sure to `pip` install in a newly created `conda` environment to avoid dependency conflicts.\n\n# Contributing\n\nSee [CONTRIBUTING](https://github.com/MSDLLCpapers/obsidian/blob/main/CONTRIBUTING.md) to learn more.\n\n## Developers\n\n- Kevin Stone (Merck & Co., Inc.) [kevin.stone@merck.com](mailto:kevin.stone@merck.com)\n- Yuting Xu (Merck & Co., Inc.) [yuting.xu@merck.com](mailto:yuting.xu@merck.com)\n\n## Contributors\n\n- Ajit Vikram (Merck & Co., Inc.)\n- Melodie Christensen (Merck & Co., Inc.)\n- Kobi Felton (Merck & Co., Inc.)\n\n## License\n__obsidian__ is licensed by the [GPLv3 license](https://github.com/MSDLLCpapers/obsidian/blob/main/LICENSE).",
"bugtrack_url": null,
"license": null,
"summary": "Automated experiment design and black-box optimization",
"version": "0.8.3",
"project_urls": {
"Changelog": "https://msdllcpapers.github.io/obsidian/stubs/changelog.html",
"Documentation": "https://msdllcpapers.github.io/obsidian/stubs/api_docs.html",
"Homepage": "https://msdllcpapers.github.io/obsidian/",
"Repository": "https://github.com/MSDLLCpapers/obsidian/"
},
"split_keywords": [
"optimization",
" experiment design",
" bayesian optimization",
" process development",
" apo",
" doe"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9277c05de3f92e37f9e8ccd7855121ea2c85d0a6ad1a7558de7de3ada120ba74",
"md5": "ac8374b0e7217807f3ca66c8565f5f1c",
"sha256": "5d74ab0999b447260bd0a6b6cfe0e9572fda5d15349241a92930454701ce786b"
},
"downloads": -1,
"filename": "obsidian_apo-0.8.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac8374b0e7217807f3ca66c8565f5f1c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 136013,
"upload_time": "2024-08-22T02:33:13",
"upload_time_iso_8601": "2024-08-22T02:33:13.111523Z",
"url": "https://files.pythonhosted.org/packages/92/77/c05de3f92e37f9e8ccd7855121ea2c85d0a6ad1a7558de7de3ada120ba74/obsidian_apo-0.8.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "30e3c97dca6d603c18884fbca879aa0690be1af4021e13e45aa9ccf73fb1818a",
"md5": "cf00ac1102d4946e9c139115a7ebbbdb",
"sha256": "8cf27008d2d71ef6ef1735e21eecb605f241d480e80008f5077257933ab0ad26"
},
"downloads": -1,
"filename": "obsidian_apo-0.8.3.tar.gz",
"has_sig": false,
"md5_digest": "cf00ac1102d4946e9c139115a7ebbbdb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 105124,
"upload_time": "2024-08-22T02:33:14",
"upload_time_iso_8601": "2024-08-22T02:33:14.370567Z",
"url": "https://files.pythonhosted.org/packages/30/e3/c97dca6d603c18884fbca879aa0690be1af4021e13e45aa9ccf73fb1818a/obsidian_apo-0.8.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-22 02:33:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MSDLLCpapers",
"github_project": "obsidian",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "obsidian-apo"
}
JSON
