1# write the proper __init__.py file
  2# This is the __init__.py file for the OPTIMA package.
  3# It is used to mark the directory as a Python package.
  4
  5# import the necessary modules
  6# from . import analysis
  7# from . import bo
  8# from . import doe
  9
 10"""
 11# OPTIMEO – Bayesian Optimization Web App for Process Tuning, Modeling, and Orchestration
 12
 13[![](https://badgen.net/badge/icon/GitHub?icon=github&label)](https://github.com/colinbousige/OPTIMEO)
 14[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15308437.svg)](https://doi.org/10.5281/zenodo.15308437)
 15[![paper](https://joss.theoj.org/papers/5df5fbe4e131d230b13fb3c98db545d8/status.svg)](https://joss.theoj.org/papers/5df5fbe4e131d230b13fb3c98db545d8)
 16[![Documentation](https://github.com/colinbousige/OPTIMEO/actions/workflows/build-docs.yml/badge.svg)](https://colinbousige.github.io/OPTIMEO/optimeo.html)
 17
 18
 19---
 20
 21## About this package
 22
 23[OPTIMEO](https://optimeo.streamlit.app/) is a package doubled by a web application that helps you optimize your experimental process by generating a Design of Experiment (DoE), generating new experiments using Bayesian Optimization, and analyzing the results of your experiments using Machine Learning models.
 24
 25This package was developed within the frame of an academic research project, MOFSONG, funded by the French National Research Agency (N° ANR-24-CE08-7639). See the related paper reference in [How to cite](#how-to-cite).
 26
 27---
 28
 29## Installation
 30
 31### Installing the package
 32
 33Installing the package and its dependencies should take up about 1.3 GB on your hard disk, the main "heavy" dependencies being `botorch`, `scikit_learn`, `plotly`, `scipy`, `pandas` and `streamlit`.
 34
 35It should be easy enough with `pip`:
 36
 37```bash
 38git clone https://github.com/colinbousige/OPTIMEO.git
 39cd OPTIMEO
 40# Otional: create a virtual environment
 41python -m venv venv
 42source venv/bin/activate # on Linux or MacOS
 43# Then, install OPTIMEO as a package:
 44pip install .
 45```
 46
 47If you did `pip install .`, you can upgrade to new a version or uninstall with:
 48
 49```bash
 50# upgrade the optimeo package
 51cd OPTIMEO
 52pip install --upgrade .
 53# uninstall the optimeo package
 54pip uninstall optimeo
 55```
 56
 57### Using the web app
 58
 59- You can use the app directly on its [Streamlit.io web page](https://optimeo.streamlit.app/), but it might be a bit slow if you have a lot of data to process. 
 60
 61- If you'd rather run this app on your local machine (which will most probably make it faster than running it on streamlit.io), you can do so by running the following command in your terminal:
 62
 63```bash
 64git clone https://github.com/colinbousige/OPTIMEO.git
 65cd OPTIMEO
 66# Otional: create a virtual environment
 67python -m venv venv
 68source venv/bin/activate # on Linux or MacOS
 69# Then, install the required packages:
 70pip install -r requirements.txt # to install the required packages
 71```
 72
 73Finally, you can run the app by running the following command in your terminal:
 74
 75```bash
 76streamlit run Home.py
 77```
 78
 79- You can also modify the path to the `OPTIMEO` folder in `OPTIMEO/bin/optimeo`. Then, doing the following will add the `optimeo` command to your `PATH`:
 80
 81```bash
 82git clone https://github.com/colinbousige/OPTIMEO.git
 83cd OPTIMEO
 84pip install . # to install OPTIMEO as a package
 85chmod +x bin/optimeo
 86ln -s $(pwd)/bin/optimeo /usr/local/bin/optimeo # or any folder in your PATH
 87```
 88
 89So now, you just have to run `optimeo` in your terminal to run the app.
 90
 91---
 92
 93## Usage
 94
 95### With the web app
 96
 97You can use the app directly on its [Streamlit.io web page](https://optimeo.streamlit.app/), or run it locally (see [Installation](#installation)).
 98
 99Choose the page you want to use in the sidebar, and follow the instructions. Hover the mouse on the question marks to get more information about the parameters.
100
101**1. Design of Experiment:**  
102Generate a Design of Experiment (DoE) for the optimization of your process. Depending on the number of factors and levels, you can choose between different types of DoE, such as Sobol sequence, Full Factorial, Fractional Factorial, or Definitive Screening Design.
103
104**2. New experiments using Bayesian Optimization:**  
105From a previous set of experiments and their results, generate a new set of experiments to optimize your process. You can use up to 10 outcomes, of which 2 can be objectives (i.e. outcomes that you want to minimize or maximize) and the outcomes that are not objectives can be constrained.  
106
107**3. Data analysis and modeling:**  
108Analyze the results of your experiments and model the response of your process.
109
110### With the Python package
111
112You might want to use the app as a Python package in order to integrate it in your own code, or to automate some tasks. For example:
113
114- you are maybe using a robotic platform to run your experiments and characterize your results, and you want to use Bayesian Optimization to suggest new experiments to run automatically
115- you are running a simulation and you want to optimize its parameters using Design of Experiment and Bayesian Optimization.
116
117You can also use the app as a Python package (see [Installation](#installation)). You can import the different modules of the app and use them in your own code. Here is an example of how to use the app as a package:
118
119#### For Design of Experiment
120
121A more detailed example is given in [the notebook](https://colab.research.google.com/github/colinbousige/OPTIMEO/blob/main/notebooks/doe.ipynb).
122
123```python
124from optimeo.doe import * 
125parameters = [
126    {'name': 'Temperature', 'type': 'integer', 'values': [20, 40]},
127    {'name': 'Pressure', 'type': 'float', 'values': [1, 2, 3]},
128    {'name': 'Catalyst', 'type': 'categorical', 'values': ['A', 'B', 'C']}
129]
130doe = DesignOfExperiments(
131    type='Sobol sequence',
132    parameters=parameters,
133    Nexp=8
134)
135doe
136```
137
138#### For Bayesian Optimization
139
140A more detailed example is given in [the notebook](https://colab.research.google.com/github/colinbousige/OPTIMEO/blob/main/notebooks/bo.ipynb).
141
142```python
143from optimeo.bo import * 
144
145features, outcomes = read_experimental_data('experimental_data.csv', out_pos=[-1])
146bo = BOExperiment(
147    features=features, 
148    outcomes=outcomes,
149    N = 2, # number of new points to generate
150    maximize=True, # we want to maximize the response
151    fixed_features=None, 
152    feature_constraints=None, 
153    optim = 'bo'
154)
155bo.suggest_next_trials()
156```
157
158#### For Data Analysis
159
160A more detailed example is given in [the notebook](https://colab.research.google.com/github/colinbousige/OPTIMEO/blob/main/notebooks/MLanalysis.ipynb).
161
162```python
163from optimeo.analysis import * 
164
165data = pd.read_csv('dataML.csv')
166factors = data.columns[:-1].tolist()
167response = data.columns[-1]
168analysis = DataAnalysis(data, factors, response)
169analysis.model_type = "ElasticNetCV"
170MLmodel = analysis.compute_ML_model()
171figs = analysis.plot_ML_model()
172for fig in figs:
173    fig.show()
174```
175
176
177
178---
179
180## Support
181
182This app was made by [Colin Bousige](mailto:colin.bousige@cnrs.fr). Contact me for support or to signal a bug, or leave a message on the [GitHub page of the app](https://github.com/colinbousige/OPTIMEO).
183
184---
185
186## How to cite
187
188This work has been published in the article "OPTIMEO: Bayesian Optimization Web App for Process Tuning, Modeling, and Orchestration", C. Bousige, [J. Open Source Softw. **10**, 115 (2025), 8510](https://joss.theoj.org/papers/10.21105/joss.08510). Please cite this paper if you publish using this code:
189
190```bibtex
191@article{bousige_optimeo_2025,
192  title = {{{OPTIMEO}}: {{Bayesian Optimization Web App}} for {{Process Tuning}}, {{Modeling}}, and {{Orchestration}}},
193  author = {Bousige, Colin},
194  year = 2025,
195  journal = {J. Open Source Softw.},
196  volume = {10},
197  number = {115},
198  pages = {8510},
199  doi = {10.21105/joss.08510}
200}
201```
202
203---
204
205## Acknowledgements
206
207This work was supported by the French National Research Agency (N° ANR-24-CE08-7639).  
208Also, this work was made possible thanks to the following open-source projects:
209
210- [ax](https://ax.dev/)
211- [BoTorch](https://botorch.org/)
212- [scikit-learn](https://scikit-learn.org/stable/)
213- [pyDOE3](https://github.com/relf/pyDOE3)
214- [dexpy](https://statease.github.io/dexpy/)
215- [doepy](https://doepy.readthedocs.io/en/latest/)
216- [definitive-screening-design](https://pypi.org/project/definitive-screening-design/)
217
218---
219
220## License
221
222[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
223
224This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
225
226
227
228"""