Merge pull request #30 from caglorithm/docs/mkdocs

🚀🚀🚀🚀🚀🚀 Automatic documentation 🚀🚀🚀🚀🚀🚀
caglorithm · Feb 15, 2021 · e457ee1 · e457ee1
2 parents 18205c4 + 2c9f9df
commit e457ee1
Show file tree

Hide file tree

Showing 15 changed files with 1,918 additions and 661 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -25,25 +25,25 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python ${{ matrix.python-version }} 🚜
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
+      - name: Install dependencies 🛠
         run: |
           python -m pip install --upgrade pip
           pip install pytest flake8 codecov pytest-cov wheel setuptools
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-      - name: Lint with flake8
+      - name: Lint with flake8 🎓
         run: |
           # stop the build if there are Python syntax errors or undefined names
           flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
           # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
           flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-      - name: Test with pytest
+      - name: Test with pytest 🧪
         run: |
           PYTHONPATH=. pytest --durations=0 --cov-report=xml --cov=mopet tests/
-      - name: Upload coverage to Codecov
+      - name: Upload coverage to Codecov 📊
         uses: codecov/codecov-action@v1
         with:
           file: ./coverage.xml

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,40 @@
+name: documentation
+
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: [3.7]
+
+    steps:
+      - name: Copy Repository Contents ↩
+        uses: actions/checkout@v2
+        with:
+          persist-credentials: false
+      - name: Set up Python ${{ matrix.python-version }} 🚜
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies 🛠
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material mkdocstrings mknotebooks Pygments
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          pip install .
+      - name: Build documentation 👷‍♀️
+        run: |
+          mkdocs build
+      - name: Deploy 🚀
+        uses: JamesIves/[email protected]
+        with:
+            folder: site
+            branch: gh-pages
+
diff --git a/.github/workflows/test-notebooks.yml b/.github/workflows/test-notebooks.yml
@@ -0,0 +1,30 @@
+name: notebooks
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: [3.7]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }} 🚜
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies 🛠
+        run: |
+          python -m pip install --upgrade pip
+          pip install treon wheel setuptools jupyterlab matplotlib
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          pip install .
+      - name: Test notebooks with treon 🧪
+        run: |
+          treon examples/
diff --git a/README.md b/README.md
@@ -19,19 +19,21 @@
 
 </p>
 
-
 # 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 yet another hard disk. 
+_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 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
 
 ```
@@ -42,20 +44,21 @@ pip install .
 ```
 
 # Example usage 🐝
-Setting up an exploration is as easy as can be!
+
+Feel free to have a look at the [Documentation page](https://caglorithm.github.io/mopet/). Setting up an exploration is as easy as can be!
 
 ```python
 # first we define an toy evaluation function
 def distance_from_circle(params):
-	# let's simply calculate the distance of 
+	# let's simply calculate the distance of
 	# the x-y parameters to the unit circle
-	distance = abs((params["x"] ** 2 + params["y"] ** 2) - 
-	
+	distance = abs((params["x"] ** 2 + params["y"] ** 2) -
+
 	# we package the result into 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:
 
@@ -80,21 +83,21 @@ After your exploration has finished, you will find a file `exploration.h5` in yo
   	<img alt="Build" src="resources/hdf_file.jpg">
 </p>
 
-  
+
 
 ## Loading exploration results
 
-You can load the exploration results using 
+You can load the exploration results using
 
 ```python
-ex.load_results(all=True)
-``` 
+ex.load_results(arrays=True)
+```
 
-Note that using `all=True` will load all results into memory (as opposed to just the parameters of each run). Please make sure that you have enough free memory for this since your simulation results could be huge. If you do not want this, you can load individual results using their `run_id` (which is an integer counting up one per run):
+Note that using `arrays=True` will load all results into memory (as opposed to just the parameters of each run). Please make sure that you have enough free memory for this since your simulation results could be huge. If you do not want this, you can load individual results using their `run_id` (which is an integer counting up one per run):
 
 ```python
 ex.get_run(run_id=0)
-``` 
+```
 
 After using `ex.load_results()`, an overview of all runs and their parameters is given as a `pandas` DataFrame, available as `ex.df`. Using `ex.load_results()` with the default parameters will automatically aggregate all scalar results into this table, like `distance` in our example above, which is a float.
 
@@ -103,6 +106,7 @@ Using some fancy pivoting, we can create a 2D matrix with the results as entries
 ```python
 pivoted = ex.df.pivot_table(values='result', index = 'y', columns='x', aggfunc='first')
 ```
+
 <p align="center">
   <img src="https://github.com/caglorithm/mopet/raw/master/resources/pandas_pivot_table.png", width="480">
 </p>
@@ -128,14 +132,14 @@ plt.ylabel("y")
 
 ### Inspired by 🤔
 
-`mopet` is inspired by [`pypet`](https://github.com/SmokinCaterpillar/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`. 
+`mopet` is inspired by [`pypet`](https://github.com/SmokinCaterpillar/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:
 
-* [`ray`](https://github.com/ray-project/ray) - A fast and simple framework for building and running distributed applications.
-* [`pytables`](https://github.com/PyTables/PyTables) - A Python package to manage extremely large amounts of data.
-* [`tqdm`](https://github.com/tqdm/tqdm) - A Fast, Extensible Progress Bar for Python and CLI
-* [`pandas`](https://github.com/pandas-dev/pandas) - Flexible and powerful data analysis / manipulation library for Python
-* [`numpy`](https://github.com/numpy/numpy) - The fundamental package for scientific computing with Python
+- [`ray`](https://github.com/ray-project/ray) - A fast and simple framework for building and running distributed applications.
+- [`pytables`](https://github.com/PyTables/PyTables) - A Python package to manage extremely large amounts of data.
+- [`tqdm`](https://github.com/tqdm/tqdm) - A Fast, Extensible Progress Bar for Python and CLI
+- [`pandas`](https://github.com/pandas-dev/pandas) - Flexible and powerful data analysis / manipulation library for Python
+- [`numpy`](https://github.com/numpy/numpy) - The fundamental package for scientific computing with Python
diff --git a/docs/examples b/docs/examples
@@ -0,0 +1 @@
+../examples
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,145 @@
+<p align="center">
+  <a href="https://travis-ci.org/neurolib-dev/neurolib">
+  	<img alt="Build" src="https://travis-ci.org/caglorithm/mopet.svg?branch=master"></a>
+
+  <a href="https://zenodo.org/badge/latestdoi/246940409">
+  	<img alt="10.5281/zenodo.3941539" src="https://zenodo.org/badge/246940409.svg"></a>
+
+  <a href="https://github.com/caglorithm/mopet/releases">
+  	<img alt="Release" src="https://img.shields.io/github/v/release/caglorithm/mopet"></a>
+
+  <a href="https://codecov.io/gh/caglorithm/mopet">
+  	<img alt="codecov" src="https://codecov.io/gh/caglorithm/mopet/branch/master/graph/badge.svg"></a>
+
+  <a href="https://pepy.tech/project/mopet">
+  	<img src="https://pepy.tech/badge/mopet"></a>
+
+  <a href="https://github.com/psf/black">
+  	<img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+
+</p>
+
+# 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 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 🐝
+
+Feel free to have a look at the [Documentation page](https://caglorithm.github.io/mopet/). Setting up an exploration is as easy as can be!
+
+```python
+# 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) -
+
+	# we package the result into 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:
+
+```python
+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](https://ray.readthedocs.io/en/latest/autoscaling.html) for more info.
+
+```python
+ex.run()
+>> 100%|██████████| 441/441 [426.57it/s]
+```
+
+After your exploration has finished, you will find a file `exploration.h5` in your current directory with all the runs, their parameters and their outputs, neatly organized. If you open this file (with [HDFView](https://www.hdfgroup.org/downloads/hdfview/) for example), you'll see something like this:
+
+<p align="center">
+  	<img alt="Build" src="resources/hdf_file.jpg">
+</p>
+
+
+
+## Loading exploration results
+
+You can load the exploration results using
+
+```python
+ex.load_results(arrays=True)
+```
+
+Note that using `arrays=True` will load all results into memory (as opposed to just the parameters of each run). Please make sure that you have enough free memory for this since your simulation results could be huge. If you do not want this, you can load individual results using their `run_id` (which is an integer counting up one per run):
+
+```python
+ex.get_run(run_id=0)
+```
+
+After using `ex.load_results()`, an overview of all runs and their parameters is given as a `pandas` DataFrame, available as `ex.df`. Using `ex.load_results()` with the default parameters will automatically aggregate all scalar results into this table, like `distance` in our example above, which is a float.
+
+Using some fancy pivoting, we can create a 2D matrix with the results as entries
+
+```python
+pivoted = ex.df.pivot_table(values='result', index = 'y', columns='x', aggfunc='first')
+```
+
+<p align="center">
+  <img src="https://github.com/caglorithm/mopet/raw/master/resources/pandas_pivot_table.png", width="480">
+</p>
+
+Let's plot the results!
+
+```python
+
+import matplotlib.pyplot as plt
+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")
+```
+
+<p align="center">
+  <img src="https://github.com/caglorithm/mopet/raw/master/resources/unit_circle.png", width="350">
+</p>
+
+## More information 📓
+
+### Inspired by 🤔
+
+`mopet` is inspired by [`pypet`](https://github.com/SmokinCaterpillar/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:
+
+- [`ray`](https://github.com/ray-project/ray) - A fast and simple framework for building and running distributed applications.
+- [`pytables`](https://github.com/PyTables/PyTables) - A Python package to manage extremely large amounts of data.
+- [`tqdm`](https://github.com/tqdm/tqdm) - A Fast, Extensible Progress Bar for Python and CLI
+- [`pandas`](https://github.com/pandas-dev/pandas) - Flexible and powerful data analysis / manipulation library for Python
+- [`numpy`](https://github.com/numpy/numpy) - The fundamental package for scientific computing with Python
diff --git a/docs/js/config.js b/docs/js/config.js
@@ -0,0 +1,12 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
diff --git a/docs/mopet.md b/docs/mopet.md
@@ -0,0 +1,3 @@
+# Mopet
+
+::: mopet.mopet