The purpose of this guide is to introduce users to the graphical interface of DendroTweaks. To learn more about the underlying concepts and the modeling framework of DendroTweaks, please refer to the package documentation.

Getting started

Introduction

To help you get started with DendroTweaks, we have prepared a series of video tutorials that complement this user guide. These tutorials provide step-by-step instructions and demonstrations of key GUI features and modeling workflows.

You can access the full playlist here .

Installing the application on your local machine

You can try DendroTweaks online without installation by visiting the Home page and clicking Launch to access the GUI with example models.

To install the GUI locally clone the DendroTweaks GitHub repository using the following command:

git clone https://github.com/Poirazi-Lab/DendroTweaksApp.git

Create and activate a conda environment (recommended) using the provided environment.yml file:

conda env create -f environment.yml
conda activate dendrotweaksapp

Alternatively, install required packages using pip:

pip install -r requirements.txt

To run the GUI, navigate to the cloned directory and execute the following command:

bokeh serve --show app

This command will start a local server and open the DendroTweaks GUI in your default web browser.

Understanding the Model Structure

DendroTweaks models are structured as a collection of components, each representing a specific aspect of the neuronal model. The main components include:

Morphology: The 3D structure of the neuron, typically represented in SWC format.
Biophysics: The membrane mechanisms (e.g. ion channels) that govern the electrophysiological properties of the neuron, typically represented in MOD format, compatible with the NEURON simulator.
Stimuli: The synaptic inputs and other stimuli that the neuron receives during simulations.

The model files are organized in a specific directory structure to facilitate easy access and management. The main directory contains a subdirectory for each model, and within each model directory, there are separate subdirectories for morphology, biophysics, and stimuli. The following is a minimal example of the directory structure:

/path/to/data/
...
└── UserModel1/
    ├── stimuli/
    ├── morphology/
    |  └── cell.swc
    └── biophys/
        └── mod/
            ├── Nav.mod
            └── Kv.mod

GUI elements

DendroTweaks graphical user interface (GUI) is built using the Bokeh framework, which provides a powerful and flexible way to create interactive visualizations and web applications in Python.

The GUI consists of three main components:

Left menu: Handles file import and export operations, running simulations and validation protocols, and accessing application settings.
Main workspace: Contains interactive plots.
Right menu: Includes widgets and conditionally toggled auxiliary plots.

The left menu consists of two submenus:

Input / Output: Handles .swc and .mod files.
Simulation: Allows configuring general simulation parameters.

In addition, a status bar is placed at the top of the menu that displays the current status of the application, including information about the loaded model, simulation progress, and any errors or warnings that may occur during interaction with the GUI.

The right menu is divided into three submenus:

Morphology: Allows visualizing and editing the morphology of the neuron.
Biophysics: Allows visualizing and editing the membrane mechanisms of the neuron.
Recordings and Stimuli: Allows visualizing and editing the synapses of the neuron.

Suggested Workflow

In the online version of the app, we provide several example models for you to explore:

A pyramidal CA1 neuron from Poirazi et al. (2003)
A pyramidal L5 neuron from Hay et al. (2011)
A pyramidal L2/3 neuron from Park et al. (2019)

To begin working with DendroTweaks, select a model from the list of available models in the left menu under the Input / Output tab. Then, choose the corresponding morphology file.

Once selected, the Cell and Graph plots will appear in the main workspace, and the right menu will become active.

Note that to select a different model, you will need to reload the page.

Morphology

Navigate through different sections of the model using the Cell plot. Click on a section to select it. Similarly, you can select segments from the Graph plot. Use the lasso mouse tool to select multiple segments by holding the left mouse button and dragging.

Note that all elements of the workspace are synchronized. For example, selecting a section in the Cell plot will automatically highlight the corresponding segments in the Graph plot.

Open the Morphology submenu in the right menu to manage the morphology of the neuron. This submenu is divided into four tabs:

Sections: Configure section-specific parameters and visualize section geometry and the distribution of biophysical parameters.
Domains: Define the domains of the neuron based on morphological or functional criteria.
Reduction: Modify the morphology of the neuron using built-in reduction algorithms.
Analysis: Perform morphometric analysis of the neuron, including calculations for total length, surface area, volume, and the number of sections and segments.

Membrane Mechanisms

Use the Input / Output tab in the left menu to import predefined biophysical parameters. Wait until the status bar indicates that the mechanisms have been successfully loaded. Note that it may take a few seconds to compile the .mod files.

Open the Biophysics submenu in the right menu to manage membrane mechanisms and their parameters. This submenu is divided into three tabs:

Membrane Mechanisms: Select the mechanisms to be used in the model and specify the domains where they will be applied.
Segment Groups: Create and manage groups of segments based on their domain, distance from the soma, or maximum/minimum diameter.
Parameters: Update the parameters of the selected mechanisms and define how each parameter will be distributed across the segments.

Stimuli

In the Input / Output tab of the left menu, you can import a depolarizing current protocol. Once imported, a plot displaying the voltage response will appear in the main workspace.

Open the Recordings and Stimuli submenu in the right menu to manage recordings and stimuli. This submenu is divided into four tabs:

Recordings: Record activity from multiple segments simultaneously.
IClamps: Create and manage current injections in the model.
Populations: Create and manage synaptic inputs from populations of "virtual" neurons. Each population can consist of multiple synapses, sharing kinetic properties (e.g., tau rise, tau decay, equilibrium potential) and activation properties (e.g., rate, noise). You can create as many populations as needed.
Ephys Analysis: Analyze recorded activity using available validation protocols, such as detecting somatic action potentials, calculating the f-I relationship, and measuring dendritic attenuation and nonlinear input integration.

Simulation

To adjust simulation parameters, go to the Simulation tab in the left menu. Here, you can configure the duration of the simulation, the time step, the temperature, and the initial voltage.

By default, the simulation runs automatically with each interaction with the GUI widgets. If you prefer manual control, disable this option by toggling off the Run on interaction switch. Then, click the Run Simulation button to execute the simulation manually.