Description

WebSONIC is an interactive web application allowing to visualize the predicted electrical response of different neuron types to ultrasonic stimuli for various combinations of sonication parameters, computed with the SONIC model [1]. A comparative module to explore predicted responses of the same neurons to electrical stimuli (computed with standard Hodgkin-Huxley equations) is also included.

This application is built in Python. It uses the Dash framework for serving and client-side rendering, and the NEURON simulation environment to run fast simulations. It depends on two other Python papckages:

• PySONIC defines the SONIC model and provides utilities
• MorphoSONIC handles the communication with NEURON

Content of repository

• the viewer module contains a core SONICViewer class inherited from dash.Dash that defines the layout and all the callbacks of the web app.
• the components module defines custom UI components used in the layout.
• the params module defines input and plotting parameters used by the web app.
• the assets folder contains CSS style sheets and static files used by the web app.
• the index.html defines a default home page used if the web app is hosted on a server.
• the run.py script allows to launch the app from the commandmline with different options.

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, and install the remaining package dependencies:

git clone https://github.com/tjjlemaire/WebSONIC.git
cd WebSONIC
pip install -r requirements.txt

That's it!

Usage

Local use

You can run the application from a local terminal with a single command line (in the app directory):

python run.py

The following command line arguments are available:

• -d / --debug: run the application in debug mode (restarting upon file save).
• -v / --verbose: add verbosity
• -t / --testUI: test the we app UI, without running internal simulations

Then, open a browser at http://127.0.0.1:8050/viewer to use the application.

Remote deployment (Linux)

To deploy the application on a pre-configured linux machine, the best way to go is to use a Green Unicorn server:

• From a terminal, activate a Python3 environment if needed:

conda activate sonic

• Install Green Unicorn as a python package

pip install gunicorn

• Move to the WebSONIC folder and serve the application with Gunicorn:

gunicorn --bind 0.0.0.0:8050 run:server

• Alternatively, you can serve the application in a separate, detached screen session:

screen -d -S app -m gunicorn --bind 0.0.0.0:8050 run:server

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. DOI.