Introduction

The purpose of this guide is to introduce users to the graphical interface of DendroTweaks. For a quick overview of the toolbox, including a video demonstration, you can visit our e-poster at the World-wide.org platform.

Getting Started

DendroTweaks is a web-based Python toolbox. It can be accessed through our online platform (Home page). Alternatively, the toolbox can be installed locally and run with a Bokeh server. The core functionality of the toolbox is also available as a standalone Python library, and interactive Jupyter notebooks are included in the repository. In this section, we will explain how to locally install DendroTweaks and run it in GUI mode. If you are using the online version, feel free to skip to the next section.

Set up a Conda environment

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

conda env create -f environment.yml
conda activate dendrotweaks

Alternatively, install required packages using pip:

pip install -r requirements.txt

Run the Bokeh server

To run the Bokeh server and launch the app locally, use the following command:

bokeh serve --show app

This will start the Bokeh server and automatically open your default web browser to display the app.

Graphical Interface

The GUI consists of three main components:

1. Left menu: handles file import and export operations, running simulations and validation protocols, and accessing application settings.
2. Main workspace: contains interactive plots.
3. Right menu: includes widgets and conditionally toggled auxiliary plots.

The left menu consists of three submenus:

• Input / Output: handles .swc and .mod files.
• Simulation: allows to configure general simulation parameters.
• Validation: allows to execute predefined validation protocols.

1. Tabs for accessing submenus.
2. A selector for .swc files and a slider to set the d_lambda spatial discretization parameter. It is recommended to set d_lambda before uploading a morphology.
3. Widgets for inserting NEURON mechanisms (ion channels). Export and Import buttons can be used to save the current session, including inserted channels and their distributions, as well as stimulation parameters. Note that mechanisms for calcium dynamics, synaptic inputs and external currents are not exported. The multiselect widgets allow for adding or removing mechanisms individually.
4. A button to access the settings menu, such as switching between light and dark themes.
5. Sliders for setting simulation parameters.
6. By default, the interface responds to user actions in real time, running a simulation in NEURON with each interaction. Alternatively, for computationally demanding models, real-time updates can be disabled, and the button can be used to manually run a simulation.
7. A dropdown menu for available validation protocols.
8. After running a validation protocol, the measured parameters will be printed here.

The right menu is divided into two sections: Cell and Channels. The Cell menu further consists of three submenus:

• Morphology: allows to set morphological properties.
• Membrane: allows to distributes membrane mechanisms (ion channels).
• Stimuli: allows to specify recording sites, define external current injections, allocate synapses and adjust their properties.

1. Tabs for accessing submenus.
2. Sliders to adjust properties of the currently selected section. Note that the Ra spinner can be used to adjust the axial resistance for multiple selected sections.
3. Buttons to reduce the subtree of a selected section and export the resulting models as an .swc file.
4. A button to calculate morphometric statistics of selected sections. The auxiliary plot renders histograms for the distribution of a given parameter.
5. Spinners to adjust the equilibrium potentials of present ions throughout the model.
6. Widgets to add a new mechanism group with an associated distribution type.
7. Widgets to access created groups and change their parameters. The distribution for selected segments is dynamically plotted as a function of the distance from the soma.
8. Widgets to record activity or inject current to a selected segment.
9. Widgets to adjust the duration and amplitude of a current injection.
10. Widgets to create and access synapse groups and adjust their parameters.

Suggested Workflow

To create a new model, you typically need a neuronal morphology in the form of an .swc file and membrane mechanisms (.mod files) to be used in NEURON. In our demo, we provide some preset models for you to use:

• 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 morphology from the list of available .swc files in the left menu under the Input / Output tab. The Cell and the Graph plots will appear in the main workspace. We recommend using Park_2019.swc as a simpler and faster model for this tutorial. Note that in order to be able to select another cell, you need to reload the page.

Exploring neuronal morphology

1. Navigate through different sections of the model using the Cell plot. Click on a section to select it.
2. Similarly, select segments from the Graph plot. You can use the lasso mouse tool to select multiple segments (hold the left mouse key and drag).
3. Note that all elements of the workspace are synchronized. For example, selecting a section in the Cell plot will result in selecting the corresponding segments on the Graph plot.

Running a simple simulation

1. Go to the Input / Output tab in the left menu.
2. Import predefined biophysical parameters by clicking the Import biophys button. Wait untill the mechanism names appear in the multiselect widget. It may take a few seconds to compile the .mod files.
3. Go to the Stimuli tab in the right menu.
4. Make sure the soma is selected (default).
5. Activate the switches for Record voltage and Inject current.
6. Adjust the current amplitude using the spinner (e.g., 150 pA for Park_2019.swc). Use the Step field on the right to fine-tune the spinner's step.
7. Optionally, select a dendritic segment using the Graph plot and record activity from it by switching on the Record voltage switch.
8. Try adjusting simulation parameters such as duration and temperature by using the sliders in the Simulation tab of the left menu.

Adjusting channel distributions

1. Go to the Membrane tab in the right menu.
2. Select a channel conductance, such as gbar_na, using the Parameter dropdown widget. The distribution will be rendered on the Graph plot.
3. Try using the spinners to adjust the distribution parameters.

Adjusting ion channel kinetics

1. Click the Channels button on top of the right menu. This will open a new menu for exploring channel kinetics.
2. Select a channel from the Channel dropdown widget. Plots with channel activation/inactivation curves will appear in the workspace.
3. Try using the spinners to adjust the channel parameters.
4. Try using the Standardize button to standardize the channel model. Note that standardization applies only to voltage-gated channels.

Reducing morphology

1. Go to the Morphology tab in the right menu.
2. On the Cell plot or the Graph plot, select the section whose subtree you want to reduce.
3. Make sure synapses, currents, and recordings are not present in the subtree to be reduced. If any were added, remove them using the Stimuli tab of the right menu.
4. Click the Reduce button.
5. Try exporting the reduced morphology as an .swc file.

Adding synapses

1. Go to the Stimuli tab in the right menu.
2. Select the segments which you want to include in the synapse group.
3. Specify the Synaptic type and the number of synapses (N syn), then click on the Add synapse group button.
4. Try adjusting the kinetics of the synapse using the group widgets.

Troubleshooting

DendroTweaks is currently undergoing active development. While we strive for stability, there may still be some issues that arise. If you encounter any problems in the online version, please try reloading the page and starting over. If you encounter any problems running the app locally, we recommend restarting the Bokeh server. To do this, stop the server from the console using Ctrl + C and then restart it with the following command:

bokeh serve --show app

For any server-related issues, please consult the official Bokeh documentation for additional information.