Description

This repository contains the Python scripts allowing to generate the figures of the multi-Scale Optimized Neuronal Cavitation (SONIC) model paper [1].

Contents

• figure_**.ipynb: notebooks used to generate the paper figures that result from model simulations (i.e. all except the schematic figures 1 and 3).
• LICENSE: license file.
• utils.py: module containing utilities functions used in the notebooks.
• notebook_runner: module defining functionalities to execute notebooks from the command line.
• requirements.txt: text file containing a list of python dependencies.
• root.py: module specifying the path to the data root directory.
• run_notebooks.py: script used to run the notebooks required to generate the figures, from the command line.

Requirements

• Python 3.6+
• NEURON 7.x (https://neuron.yale.edu/neuron/download/)
• PySONIC package (https://github.com/tjjlemaire/PySONIC)
• MorphoSONIC package (https://github.com/tjjlemaire/MorphoSONIC)
• nbconvert and nbformat python packages (utilities for jupyter notebooks)

Installation

• Install a Python distribution
• Install a NEURON distribution
• Download the PySONIC and MorphoSONIC code bases from their repositories, and follow the README instructions to install them as packages.
• Install the required python dependencies to run the notebooks: pip install -r requirements.txt

Usage

Create a data directory

First, you must create a directory on your machine to hold the generated data. Once this is done, open the root.py and specify the full path to your data directory (replacing None).

Generating the data

Given the cumbersome model simulations required to create the figures, it is advised to run the run_notebooks.py script in order to generate the required dataset before opening and running the notebooks. By default, that script generates the data for all the figures, but you can specify a subset of your choice using the -f option.

For instance, to generate data uniquely for figure 4:

python run_notebooks.py -f 4

To generate data for figures 4, 5 & 6:

python run_notebooks.py -f 4 5 6

To generate data for all figures:

python run_notebooks.py -f all

Be aware that the cumulated computation time required to run all simulations can easily exceed 1 week, and that the total size of entire dataset size is about 112 GB. Therefore, it is highly advised that you run that script on a high-performance, multi-core machine with enough disk space.

The generated dataset should be split between 5 sub-folders in the indicated output directory:

• comparisons: comparisons between the full NICE model and the SONIC model (figures 5 & 6)
• maps: cell-type-specific activation maps (figure 7)
• STN: sub-thalamic nucleus neuron modulation by low-intensity US (figure 9)
• coverage: effects of partial sonophore membrane coverage on neural responses (figure 10).
• figs: output folder containing PDFs of the generated figures

Generating the figures

To generate a figure:

• start a jupyter notebook / jupyter lab session:

jupyter lab / jupyter notebook

• open the figure notebook
• select all the cells (Ctrl + A) and run them (Ctrl + Enter)
• wait for the complete notebook execution

Upon completion, the figures panels should appear in the notebook. Additionally, they will be saved as PDFs in the figs sub-folder.

Authors

Code written and maintained by Theo Lemaire (theo.lemaire@epfl.ch).

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

[1] Lemaire, T., Neufeld, E., Kuster, N., and Micera, S. (2019). Understanding ultrasound neuromodulation using a computationally efficient and interpretable model of intramembrane cavitation. J. Neural Eng.