Merge pull request #135 from neurolib-dev/documentation/mkdocs

🚀🚀🚀🚀🚀🚀 Automatic documentation 🚀🚀🚀🚀🚀🚀

.github/workflows/ci.yml

@@ -1,6 +1,3 @@
-# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-
 name: ci
 
 on:
@@ -21,26 +18,26 @@ 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 flake8 codecov pytest-cov wheel setuptools matplotlib seaborn mne
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
           pip install .
-      - 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=neurolib tests/
-      - name: Upload coverage to Codecov
+      - name: Upload coverage to Codecov 📊
         uses: codecov/codecov-action@v1
         with:
           file: ./coverage.xml

.github/workflows/documentation.yml

@@ -0,0 +1,42 @@
+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
+            token: ${{ secrets.DOC_ACCESS_TOKEN }}
+            branch: master
+            repository-name: neurolib-dev/neurolib-dev.github.io
+

.github/workflows/test-notebooks.yml

@@ -1,6 +1,3 @@
-# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-
 name: notebooks
 
 on:
@@ -18,16 +15,16 @@ 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 treon wheel setuptools jupyterlab matplotlib seaborn
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
           pip install .
-      - name: Test notebooks with treon
+      - name: Test notebooks with treon 🧪
         run: |
           treon examples/

README.md

@@ -22,7 +22,7 @@
 
 # What is neurolib?
 
-Please read the [gentle introduction](https://caglorithm.github.io/notebooks/neurolib-intro/) to `neurolib` for an overview of the basic functionality and some background information on the science behind whole-brain simulations.
+Please read the [gentle introduction](https://caglorithm.github.io/notebooks/neurolib-intro/) to `neurolib` for an overview of the basic functionality and some background information on the science behind whole-brain simulations or read the [documentation](https://neurolib-dev.github.io/) for getting started.
 
 `neurolib` allows you to build, simulate, and optimize your own state-of-the-art whole-brain models. To simulate the neural activity of each brain area, the main implementation provides an advanced neural mass mean-field model of spiking adaptive exponential integrate-and-fire neurons (AdEx) called `ALNModel`. Each brain area is represented by two populations of excitatory and inhibitory neurons. An extensive analysis and validation of the `ALNModel` model can be found in our [paper](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1007822) and its associated [github page](https://github.com/caglarcakan/stimulus_neural_populations).
 
@@ -250,7 +250,7 @@ This will gives us a summary of the last generation and plots a distribution of
 
 ### Built With
 
-`neurolib` is built on other amazing open source projects:
+`neurolib` is built using other amazing open source projects:
 
 * [pypet](https://github.com/SmokinCaterpillar/pypet) - Python parameter exploration toolbox
 * [deap](https://github.com/DEAP/deap) - Distributed Evolutionary Algorithms in Python

docs/examples

@@ -0,0 +1 @@
+../examples

docs/exploration/boxsearch.md

@@ -0,0 +1,3 @@
+# BoxSearch
+
+::: neurolib.optimize.exploration.exploration.BoxSearch

docs/index.md

@@ -0,0 +1,70 @@
+<p align="center">
+  	<img alt="Header image of neurolib - A Python simulation framework foreasy whole-brain neural mass modeling." src="https://github.com/neurolib-dev/neurolib/raw/master/resources/readme_header.png" >
+</p> 
+
+## Getting started
+* To browse the source code of `neurolib` visit out [GitHub repository](https://github.com/neurolib-dev/neurolib).
+* Read the [gentle introduction](https://caglorithm.github.io/notebooks/neurolib-intro/) to `neurolib` for an overview of the basic functionality and some background information on the science behind whole-brain simulations.
+
+## Installation
+The easiest way to get going is to install the pypi package using `pip`:
+
+```
+pip install neurolib
+```
+Alternatively, you can also clone this repository and install all dependencies with
+
+```
+git clone https://github.com/neurolib-dev/neurolib.git
+cd neurolib/
+pip install -r requirements.txt
+pip install .
+```
+
+## Project layout
+
+
+    neurolib/					# Main module
+    	models/					# Neural mass models
+    		model.py			# Base model class
+    		/.../				# Implemented neural models
+    	optimize/				# Optimization submodule
+    		evolution/			# Evolutionary optimization
+    			evolution.py
+    			...
+    		exploration/		# Parameter exploration
+    			exploration.py
+    			...
+    	data/					# Empirical datasets (structural, functional)
+    		...
+    	utils/					# Utility belt
+    		atlases.py			# Atlases (Region names, coordinates)
+    		collections.py		# Custom data types
+    		functions.py		# Useful functions
+    		loadData.py			# Dataset loader
+    		parameterSpace.py	# Parameter space
+			saver.py			# Save simulation outputs
+			signal.py			# Signal processing functions
+			stimulus.py			# Stimulus construction
+    examples/					# Example Jupyter notebooks
+    docs/						# Documentation 			
+## More information
+
+### Built With
+
+`neurolib` is built using other amazing open source projects:
+
+* [pypet](https://github.com/SmokinCaterpillar/pypet) - Python parameter exploration toolbox
+* [deap](https://github.com/DEAP/deap) - Distributed Evolutionary Algorithms in Python
+* [numpy](https://github.com/numpy/numpy) - The fundamental package for scientific computing with Python
+* [numba](https://github.com/numba/numba) - NumPy aware dynamic Python compiler using LLVM
+* [Jupyter](https://github.com/jupyter/notebook) - Jupyter Interactive Notebook
+
+### Get in touch
+
+Caglar Cakan ([email protected])  
+Department of Software Engineering and Theoretical Computer Science, Technische Universität Berlin, Germany  
+Bernstein Center for Computational Neuroscience Berlin, Germany  
+
+### Acknowledgments
+This work was supported by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) with the project number 327654276 (SFB 1315) and the Research Training Group GRK1589/2.

docs/models/model.md

@@ -0,0 +1,17 @@
+# Models
+
+Models are the core of `neurolib`. The `Model` superclass will help you to load, simulate, and analyse models. It also makes it very easy to implement your own neural mass model (see [Example 0.6 custom model](/examples/example-0.6-custom-model/)).
+
+## Loading a model
+To load a model, we need to import the submodule of a model and instantiate it. This example shows how to load a single node of the `ALNModel`. See [Example 0 aln minimal](/examples/example-0-aln-minimal/) on how to simulate a whole-brain network using this model.
+
+
+```
+from neurolib.models.aln import ALNModel # Import the model
+model = ALNModel() # Create an instance
+model.run() # Run it
+```
+
+## Model base class methods
+
+::: neurolib.models.model.Model

docs/models/parameters.md

@@ -0,0 +1,101 @@
+# Parameters
+
+Model parameters in `neurolib` are stored as a dictionary-like object `params` as one of a model's attributes. Changing parameters is straightforward:
+
+``` python
+from neurolib.models.aln import ALNModel # Import the model
+model = ALNModel() # Create an instance
+
+model.params['duration'] = 10 * 1000 # in ms
+model.run() # Run it
+```
+
+Parameters are `dotdict` objects that can also be accessed using the more simple syntax `model.params.parameter_name = 123` (see [Collections](/utils/collections/)).
+
+## Default parameters
+
+The default parameters of a model are stored in the `loadDefaultParams.py` within each model's directory. This function is called by the `model.py` file upon initialisation and returns all necessary parameters of the model.
+
+Below is an example function that prepares the structural connectivity matrices `Cmat` and `Dmat`, all parameters of the model, and its initial values.
+
+``` python
+def loadDefaultParams(Cmat=None, Dmat=None, seed=None):
+    """Load default parameters for a model
+
+    :param Cmat: Structural connectivity matrix (adjacency matrix) of coupling strengths, will be normalized to 1. If not given, then a single node simulation will be assumed, defaults to None
+    :type Cmat: numpy.ndarray, optional
+    :param Dmat: Fiber length matrix, will be used for computing the delay matrix together with the signal transmission speed parameter `signalV`, defaults to None
+    :type Dmat: numpy.ndarray, optional
+    :param seed: Seed for the random number generator, defaults to None
+    :type seed: int, optional
+
+    :return: A dictionary with the default parameters of the model
+    :rtype: dict
+    """
+
+    params = dotdict({})
+
+    ### runtime parameters
+    params.dt = 0.1  # ms 0.1ms is reasonable
+    params.duration = 2000  # Simulation duration (ms)
+    np.random.seed(seed)  # seed for RNG of noise and ICs
+    # set seed to 0 if None, pypet will complain otherwise
+    params.seed = seed or 0
+
+    # make sure that seed=0 remains None
+    if seed == 0:
+        seed = None
+
+    # ------------------------------------------------------------------------
+    # global whole-brain network parameters
+    # ------------------------------------------------------------------------
+
+    # the coupling parameter determines how nodes are coupled.
+    # "diffusive" for diffusive coupling, "additive" for additive coupling
+    params.coupling = "diffusive"
+
+    params.signalV = 20.0
+    params.K_gl = 0.6  # global coupling strength
+
+    if Cmat is None:
+        params.N = 1
+        params.Cmat = np.zeros((1, 1))
+        params.lengthMat = np.zeros((1, 1))
+
+    else:
+        params.Cmat = Cmat.copy()  # coupling matrix
+        np.fill_diagonal(params.Cmat, 0)  # no self connections
+        params.N = len(params.Cmat)  # number of nodes
+        params.lengthMat = Dmat
+
+    # ------------------------------------------------------------------------
+    # local node parameters
+    # ------------------------------------------------------------------------
+
+    # external input parameters:
+    params.tau_ou = 5.0  # ms Timescale of the Ornstein-Uhlenbeck noise process
+    params.sigma_ou = 0.0  # mV/ms/sqrt(ms) noise intensity
+    params.x_ou_mean = 0.0  # mV/ms (OU process) [0-5]
+    params.y_ou_mean = 0.0  # mV/ms (OU process) [0-5]
+
+    # neural mass model parameters
+    params.a = 0.25  # Hopf bifurcation parameter
+    params.w = 0.2  # Oscillator frequency, 32 Hz at w = 0.2
+
+    # ------------------------------------------------------------------------
+
+    # initial values of the state variables
+    params.xs_init = 0.5 * np.random.uniform(-1, 1, (params.N, 1))
+    params.ys_init = 0.5 * np.random.uniform(-1, 1, (params.N, 1))
+
+    # Ornstein-Uhlenbeck noise state variables
+    params.x_ou = np.zeros((params.N,))
+    params.y_ou = np.zeros((params.N,))
+
+    # values of the external inputs
+    params.x_ext = np.zeros((params.N,))
+    params.y_ext = np.zeros((params.N,))
+
+    return params
+
+```

docs/optimization/evolution.md

@@ -0,0 +1,3 @@
+# Evolution
+
+::: neurolib.optimize.evolution.evolution.Evolution

docs/utils/dataset.md

@@ -0,0 +1,3 @@
+# Dataset
+
+::: neurolib.utils.loadData.Dataset

docs/utils/functions.md

@@ -0,0 +1,3 @@
+# Functions
+
+::: neurolib.utils.functions

docs/utils/parameterspace.md

@@ -0,0 +1,3 @@
+# ParameterSpace
+
+::: neurolib.utils.parameterSpace.ParameterSpace

docs/utils/signal.md

@@ -0,0 +1,3 @@
+# Signal
+
+::: neurolib.utils.signal.Signal

docs/utils/stimulus.md

@@ -0,0 +1,3 @@
+# Stimulus
+
+::: neurolib.utils.stimulus