The mildly ominous parameter exploration toolkit

# mopet 🛵

The mildly ominous parameter exploration toolkit

Isn't it strange that, although parameter explorations are a crucial part of computational modeling, there are almost no Python tools available for making your life easier? `mopet` is here to help! You can run extensive grid searches in parallel (powered by `ray`) and store extremely huge amounts of data into a HDF file (powered by `pytables`) for later analysis - or whatever your excuse is for buying a yet another hard disk.

# Installation 💻

The easiest way to get going is to install the pypi package using `pip`:

``````pip install mopet
``````

Alternatively, you can also clone this repository and install all dependencies with

``````git clone https://github.com/caglorithm/mopet.git
cd mopet/
pip install -r requirements.txt
pip install .
``````

# Example usage 🐝

Setting up an exploration is as easy as can be!

```# first we define an toy evaluation function
def distance_from_circle(params):
# let's simply calculate the distance of
# the x-y parameters to the unit circle
distance = abs((params["x"] ** 2 + params["y"] ** 2) - 1)

# we package the result in a dictionary
result = {"result" : distance}
return result
```

Let's set up the exploration by defining the parameters to explore and passing the evaluation function from above:

```import numpy as np
import mopet

explore_params = {"x": np.linspace(-2, 2, 21), "y": np.linspace(-2, 2, 21)}
ex = mopet.Exploration(distance_from_circle, explore_params)
```

Running the exploration is in parallel and is handled by `ray`. You can also use a private cluster or cloud infrastructure, see here for more info.

```ex.run()
>> 100%|██████████| 441/441 [426.57it/s]
```

An overview of the runs and runs is given as a `pandas` DataFrame, available as `ex.df`. Here we load the result, which is simply a `float`, directly into the DataFrame. However, if the result was a timeseries (a `numpy.ndarray`), we could process it at this stage and extract some scalar value, for example the amplitude of the data or the dominant frequency. Using some fancy pivoting, we can create a 2D matrix with the results as entries

```ex.df["result"] = None
for r in ex.df.index:
ex.df.loc[r, "result"] = ex.results[r]['result']

pivoted = ex.df.pivot_table(values='result', index = 'y', columns='x', aggfunc='first')
``` Let's plot the results!

```import matplotlib.pyplot as plt
# a nice color map
plt.imshow(pivoted, \
extent = [min(ex.df.x), max(ex.df.x),
min(ex.df.y), max(ex.df.y)], origin='lower')
plt.colorbar(label='Distance from unit circle')
plt.xlabel("x")
plt.ylabel("y")
``` ### Inspired by 🤔

`mopet` is inspired by `pypet`, a wonderful python parameter exploration toolkit. I have been using `pypet` for a very long time and I'm greatful for its existence! Unfortunately, the project is not maintained anymore and has run into several compatibility issues, which was the primary reason why I built `mopet`.

### Built With 💞

`mopet` is built on other amazing open source projects:

## Project details

This version 0.1.1 0.1