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 – Optimization Platform for Tuning, Inference, Modeling, Exploration, and Orchestration
 12
 13<a href="https://doi.org/10.5281/zenodo.15308437"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.15308437.svg" alt="DOI"></a>
 14[![](https://badgen.net/badge/icon/GitHub?icon=github&label)](https://github.com/colinbousige/OPTIMEO)
 15
 16---
 17
 18## About this package
 19
 20[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.
 21
 22This 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).
 23
 24---
 25
 26## Installation
 27
 28### Installing the package
 29
 30Installing 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`.
 31
 32It should be easy enough with `pip`:
 33
 34```bash
 35git clone https://github.com/colinbousige/OPTIMEO.git
 36cd OPTIMEO
 37# Otional: create a virtual environment
 38python -m venv venv
 39source venv/bin/activate # on Linux or MacOS
 40# Then, install OPTIMEO as a package:
 41pip install .
 42```
 43
 44If you did `pip install .`, you can upgrade to new a version or uninstall with:
 45
 46```bash
 47# upgrade the optimeo package
 48cd OPTIMEO
 49pip install --upgrade .
 50# uninstall the optimeo package
 51pip uninstall optimeo
 52```
 53
 54### Using the web app
 55
 56- 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. 
 57
 58- 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:
 59
 60```bash
 61git clone https://github.com/colinbousige/OPTIMEO.git
 62cd OPTIMEO
 63# Otional: create a virtual environment
 64python -m venv venv
 65source venv/bin/activate # on Linux or MacOS
 66# Then, install the required packages:
 67pip install -r requirements.txt # to install the required packages
 68```
 69
 70Finally, you can run the app by running the following command in your terminal:
 71
 72```bash
 73streamlit run Home.py
 74```
 75
 76- 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`:
 77
 78```bash
 79git clone https://github.com/colinbousige/OPTIMEO.git
 80cd OPTIMEO
 81pip install . # to install OPTIMEO as a package
 82```
 83
 84So now, you just have to run `optimeo` in your terminal to run the app.
 85
 86---
 87
 88## Usage
 89
 90### With the web app
 91
 92You can use the app directly on its [Streamlit.io web page](https://optimeo.streamlit.app/), or run it locally (see [Installation](#installation)).
 93
 94Choose 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.
 95
 96**1. Design of Experiment:**  
 97Generate 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.
 98
 99**2. New experiments using Bayesian Optimization:**  
100From a previous set of experiments and their results, generate a new set of experiments to optimize your process. You can choose the sampler you want to use, depending on if you are on the early stages of the optimization and want to explore the phase space (then, choose the Sobol pseudo-random generator), or if you want to efficiently find the maximum of minimum in the response (then choose the Bayesian Optimization one).  
101
102**3. Data analysis and modeling:**  
103Analyze the results of your experiments and model the response of your process.
104
105### With the Python package
106
107You 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:
108
109#### For Design of Experiment
110
111A more detailed example is given in [the notebook](examples/doe.html).
112
113```python
114from optimeo.doe import * 
115parameters = [
116    {'name': 'Temperature', 'type': 'integer', 'values': [20, 40]},
117    {'name': 'Pressure', 'type': 'float', 'values': [1, 2, 3]},
118    {'name': 'Catalyst', 'type': 'categorical', 'values': ['A', 'B', 'C']}
119]
120doe = DesignOfExperiments(
121    type='Sobol sequence',
122    parameters=parameters,
123    Nexp=8
124)
125doe
126```
127
128#### For Bayesian Optimization
129
130A more detailed example is given in [the notebook](examples/bo.html).
131
132```python
133from optimeo.bo import * 
134
135features, outcomes = read_experimental_data('experimental_data.csv', out_pos=[-1])
136bo = BOExperiment(
137    features=features, 
138    outcomes=outcomes,
139    N = 2, # number of new points to generate
140    maximize=True, # we want to maximize the response
141    fixed_features=None, 
142    feature_constraints=None, 
143    optim = 'bo'
144)
145bo.suggest_next_trials()
146```
147
148#### For Data Analysis
149
150A more detailed example is given in [the notebook](examples/MLanalysis.html).
151
152```python
153from optimeo.analysis import * 
154
155data = pd.read_csv('dataML.csv')
156factors = data.columns[:-1]
157response = data.columns[-1]
158analysis = DataAnalysis(data, factors, response)
159analysis.model_type = "ElasticNetCV"
160MLmodel = analysis.compute_ML_model()
161figs = analysis.plot_ML_model()
162for fig in figs:
163    fig.show()
164```
165
166
167
168---
169
170## Support
171
172This 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).
173
174---
175
176## How to cite
177
178The source can be found [on Github](https://github.com/colinbousige/optimeo), please consider citing it as:
179
180```bibtex
181@software{Bousige_optimeo,
182    author = {Bousige, Colin},
183    title = {{OPTIMEO}},
184    url = {https://github.com/colinbousige/optimeo},
185    doi = {10.5281/zenodo.15308437}
186}
187```
188
189---
190
191## Acknowledgements
192
193This work was supported by the French National Research Agency (N° ANR-24-CE08-7639).  
194Also, this work was made possible thanks to the following open-source projects:
195
196- [ax](https://ax.dev/)
197- [BoTorch](https://botorch.org/)
198- [scikit-learn](https://scikit-learn.org/stable/)
199- [pyDOE3](https://github.com/relf/pyDOE3)
200- [dexpy](https://statease.github.io/dexpy/)
201- [doepy](https://doepy.readthedocs.io/en/latest/)
202- [definitive-screening-design](https://pypi.org/project/definitive-screening-design/)
203
204---
205
206## License
207
208[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
209
210This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
211
212
213
214"""