What is neurolib?

neurolib is a simulation and optimization framework for whole-brain modeling. It allows you to implement your own neural mass models which can simulate fMRI BOLD activity. neurolib helps you to analyse your simulations, to load and handle structural and functional brain data, and to use powerful evolutionary algorithms to tune your model's parameters and fit it to empirical data.

You can chose from different neural mass models to simulate the activity of each brain area. The main implementation is a mean-field model of spiking adaptive exponential integrate-and-fire neurons (AdEx) called ALNModel where each brain area contains two populations of excitatory and inhibitory neurons. An analysis and validation of the ALNModel model can be found in our paper.

📚 Please read the gentle introduction to neurolib for an overview of the basic functionality and the science behind whole-brain simulations or read the documentation for getting started.

To browse the source code of neurolib visit out GitHub repository.

📝 <a href="#how-to-cite">Cite</a> the following paper if you use neurolib for your own research:

Cakan, C., Jajcay, N. & Obermayer, K. neurolib: A Simulation Framework for Whole-Brain Neural Mass Modeling. Cogn. Comput. (2021).

The figure below shows a schematic of how a brain network is constructed:

<img src="https://github.com/neurolib-dev/neurolib/raw/master/resources/pipeline.jpg"> Examples: <a href="#single-node">Single node simulation</a> · <a href="#whole-brain-network">Whole-brain network</a> · <a href="#parameter-exploration">Parameter exploration</a> · <a href="#evolutionary-optimization">Evolutionary optimization</a>

Whole-brain modeling

Typically, in whole-brain modeling, diffusion tensor imaging (DTI) is used to infer the structural connectivity (the connection strengths) between different brain areas. In a DTI scan, the direction of the diffusion of molecules is measured across the whole brain. Using tractography, this information can yield the distribution of axonal fibers in the brain that connect distant brain areas, called the connectome. Together with an atlas that divides the brain into distinct areas, a matrix can be computed that encodes how many fibers go from one area to another, the so-called structural connectivity (SC) matrix. This matrix defines the coupling strengths between brain areas and acts as an adjacency matrix of the brain network. The fiber length determines the signal transmission delay between all brain areas. Combining the structural data with a computational model of the neuronal activity of each brain area, we can create a dynamical model of the whole brain.

The resulting whole-brain model consists of interconnected brain areas, with each brain area having their internal neural dynamics. The neural activity can also be used to simulate hemodynamic BOLD activity using the Balloon-Windkessel model, which can be compared to empirical fMRI data. Often, BOLD activity is used to compute correlations of activity between brain areas, the so called resting state functional connectivity, resulting in a matrix with correlations between each brain area. This matrix can then be fitted to empirical fMRI recordings of the resting-state activity of the brain.

Below is an animation of the neuronal activity of a whole-brain model plotted on a brain.

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 .

It is recommended to clone or fork the entire repository since it will also include all examples and tests.

Project layout

neurolib/	 				# Main module
├── models/ 					# Neural mass models
	├──model.py 				# Base model class
	└── /.../ 				# Implemented mass models
├── optimize/ 					# Optimization submodule
	├── evolution/ 				# Evolutionary optimization
	└── exploration/ 			# Parameter exploration
├── control/optimal_control/			# Optimal control submodule
	├── oc.py 				# Optimal control base class
	├── cost_functions.py 			# cost functions for OC
	├── /.../ 				# Implemented OC models
├── 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 
└── tests/					# Automated tests

Examples

Example IPython Notebooks on how to use the library can be found in the ./examples/ directory, don't forget to check them out! You can run the examples in your browser using Binder by clicking here or one of the following links:

Example 0.0 - Basic use of the aln model
Example 0.3 - Fitz-Hugh Nagumo model fhn on a brain network
Example 0.6 - Minimal example of how to implement your own model in neurolib
Example 1.2 - Parameter exploration of a brain network and fitting to BOLD data
Example 2.0 - A simple example of the evolutionary optimization framework
Example 5.2 - Example of optimal control of the noise-free Wilson-Cowan model

A basic overview of the functionality of neurolib is also given in the following.

Single node

This example is available in detail as a IPython Notebook.

To create a single aln model with the default parameters, simply run

from neurolib.models.aln import ALNModel

model = ALNModel()
model.params['sigma_ou'] = 0.1 # add some noise

model.run()

The results from this small simulation can be plotted easily:

import matplotlib.pyplot as plt
plt.plot(model.t, model.output.T)

Whole-brain network

A detailed example is available as a IPython Notebook.

To simulate a whole-brain network model, first we need to load a DTI and a resting-state fMRI dataset. neurolib already provides some example data for you:

from neurolib.utils.loadData import Dataset

ds = Dataset("gw")

The dataset that we just loaded, looks like this:

We initialize a model with the dataset and run it:

model = ALNModel(Cmat = ds.Cmat, Dmat = ds.Dmat)
model.params['duration'] = 5*60*1000 # in ms, simulates for 5 minutes

model.run(bold=

Neurolib

Install / Use

README