Description

This repository contains the Python scripts allowing to generate the figures of the morphoSONIC paper by Lemaire et al. (2021).

Contents

• fig**.py: scripts used to generate the paper figures that result from model simulations.
• utils.py: utilities module
• LICENSE: license file.

Requirements

• Python 3.6+
• NEURON 8.x (https://neuron.yale.edu/neuron/download/)
• PySONIC package (https://github.com/tjjlemaire/PySONIC)
• MorphoSONIC package (https://c4science.ch/diffusion/7145/)

Installation

• Download and install Anaconda if not already done.
• Open a terminal. For Windows users, you might need to use the Anaconda Prompt if you did not add Anaconda to the path.
• Create a new Anaconda environment called sonic with an appropriate Python version (i.e., 3.6 or more recent), and activate it. For instance with Python 3.11:

conda create -n sonic python=3.11
conda activate sonic

• Clone the PySONIC and MorphoSONIC repositories, and install them sequentially as python packages in the sonic conda environment. The detailed installation instructions are on the PySONIC and MorphoSONIC webpages.
• Clone this repository:

git clone https://github.com/tjjlemaire/ISCIENCE-D-21-00690.git
cd ISCIENCE-D-21-00690

• Create a user configuration file called config.py inside the repo, and define in it a variable called dataroot indicating the path to the root directory where output data/figures will be saved.

Usage

Generating the data

To run the necessary underlying simulations and render a specific figure (or sub-figure), just call the associated python script, e.g. for figure xxx:

python figxxx.py

Upon completion, the figure panels should appear as matplotlib figures. Additionally, you can ue the -s option to save them as PDF files in the figs sub-folder.

Be aware that the raw simulations as well as intermediate computation results are stored upon script executation, in order to avoid re-running simulations twice. The total size of entire dataset exceeds 50 GB, so make sure to plan for enough disk space. Complementarily, some scripts are optimized to distribute simulations among across CPUs (using the --mpi option), so you might want to run them on a high-performance, multi-core machine.

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

• benchmarks: contains primary results and divergence maps files of two-compartment benchmark simulations
• bundle: contains results files of the nerve bundle simluation
• fields: contains results from acoustic fields computations
• figs: output folder containing PDFs of the generated figures
• modulation: contains primary results and intermediate firing rate maps from fiber neuromodulation simulations
• multiplexing: contains primary results and firing rate maps files of MUX-LIFUS analysis
• responses: contains simulation results from fiber "typical" simulations
• SDcurves: contains intermediate SD curves data from fiber threshold simulations.

Authors

Code written and maintained by Theo Lemaire (theo.lemaire1@gmail.com).

License & citation

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

If this code base contributes to a project that leads to a scientific publication, please acknowledge this fact by citing Lemaire, T., Vicari E., Neufeld, E., Kuster, N., and Micera, S. (2021). MorphoSONIC: a morphologically structured intramembrane cavitation model reveals fiber-specific neuromodulation by ultrasound. iScience.