Neural Circuit Visualizer (NCV) – User Guide

Version 1.0, July 2025

Overview

NCV (Neural Circuit Visualizer) is a web-based platform designed for the flexible simulation and visualization of full-scale point-neuron circuits . It provides researchers and educators with an intuitive interface to build, configure, and explore large-scale neural networks in a virtual environment

Simulate network activity using efficient, scalable back-end computation
Visualize connectivity and dynamics interactively through rich graphical tools
Record and Download videos of the simulated activity

Fig. 1 The NCV graphical user interface.

NCV’s goal is to make computational neuroscience more accessible by integrating simulation, visualization, and data exploration into a single, web-based ecosystem.

Simulation

Run Simulation

The Run Simulation panel allows users to configure and launch neural circuit simulations directly through the NCV interface. It provides flexible control over model parameters and access to supported high-performance computing (HPC) platforms. Simulations are based on a mouse CA1 hippocampal network from Gandolfi et al., 2022

Fig. 2 Run Simulation.

The model simulation workflow includes the following steps:

Select Circuit – Choose a predefined circuit model (e.g., Mouse ) to simulate.
Select HPC Platform – Choose the computational backend where the simulation will run
- JUSUF – JSC : Available to all users via a shared service account.
- CINECA – G100 : Available to CINECA users.
Set Model Parameters
- PYR2PYR / INH2PYR / PYR2INH / INH2INH: Define connection weights between neuron populations.
- Background Frequency (Hz): Controls external input rate to neurons.
- Background Weight: Adjusts the input strength of background activity.
- Simulation Duration (ms): Sets the total time of the simulation.
Submit – Once all parameters are defined, click Submit to start the simulation on the selected HPC platform.

Fetching Simulation Results

Fig. 3 Fetch Simulation Results.

After a simulation has been submitted, users can retrieve and visualize completed job results through the following steps:

Select HPC Platform – Choose the same platform used to run the job.
Fetch Jobs – Click this button to list all available jobs associated with your account.
Fetched Jobs List – Successful (green), Running (yellow) and Failed (red) jobs are displayed with unique IDs.
- Click on a job ID to load the simulation results and display the 3D circuit in the NCV canvas
- Download the simulation raw output files (if available), via the download button

Simulation, Playback and Rendering Controls

In order to manage large files at the frontend level and provide a flawless visualization experience to the users, the raw data files are divided into chunks of 200 MB.

Below, we show the toolbar that allows users to control the simulation playback over time and navigate through the recorded neural activity.

Fig. 4 Simulation, Playback and Rendering Controls.

It comprises the following:

Chunk Selector : dropdown menu to select the activity time window to be displayed
Start , Pause , Restart buttons: control real-time visualization of activity data
Simulation Time Display: shows the current simulation time t and total duration (in milliseconds)
Start / End Time Inputs: define a custom simulation time window to be played back
Slider Handle: Allows to move along the simulation timeline
New Workflow Button: allows users to generate a unique Workflow ID that will be used for job submission on the HPC systems

Visualization Panel

The Visualization Controls Panel provides interactive controls to adjust visual and spatial aspects of the neural circuit display in the NCV environment. It allows users to fine-tune how neurons and the 3D scene are rendered for analysis and presentation.

Fig. 5 Visualization Panel.

It includes:

Background Color: Customize the background of the 3D scene using a color picker. You can input a HEX code or use the interactive selector to improve contrast and visibility.
Camera Controls: Adjust the camera’s position in 3D space using x , y , and z sliders. Each axis includes a numeric field for precise manual adjustments.
Neuron Size: Control the default size of all neurons using a range slider or a dedicated input field, ensuring consistent visibility across the network.
Firing Neuron Size: Set the firing neurons size to allow clear visual emphasis on active firing events.
Camera Navigation buttons provide quick directional and zoom controls for interactive exploration of the 3D circuit
- Zoom In / Zoom Out: Adjust the zoom level to focus on specific neuron clusters or zoom out for an overall network view.
- Move Up / Down / Left / Right: Move the camera smoothly in the selected direction.
- Save / Restore / Reset: Save the current camera position, restore a previously saved view, or reset to the default camera position.

Playback Controls Panel

Playback Timestep : Set the timestep for the rendering (the simulation timestep is 0.1 ms)
Step Duration : Define the rendering time delay (in milliseconds) between animation frames. Lower values result in faster playback, while higher values create slower animations.

Fig. 6 Playback Controls Panel.

Record Activity Movie

The Recording button allows users to capture a live recording of the 3D neural activity visualization within NCV.
The rear camera view, the simulation time and all the actions performed by the users during the visualization (e.g., zooming, rotating, translating) will also be recorded.
This feature is designed to generate video output for analysis, sharing, and presentation of simulation results.
To start and stop the recording, the central button at the bottom of the main panel must be pressed (see Fig. 1). Once the recording is stopped, a .webm file is automatically downloaded.
Saved movies can be replayed using any standard media player to review the simulation dynamics frame by frame.

Demo Circuits

If you do not have your own network and activity files yet, you can explore the platform by loading one of the provided Demo Circuits

Human Circuit

Click the Load Full or Half Circuit button to visualize the CA1 human hippocampal network.
Use the Select Activity dropdown to load predefined activity windows for playback.
Interactively explore the circuit and activity via the simulation controls.

Fig. 7 Full Human CA1 Circuit.

Mouse Circuit

The Mouse Circuit provides an advanced demo mode, allowing users to selectively visualize specific hippocampal regions, layers, and neuron types. The neuron type definitions and census data are curated based on the mouse hippocampal neuron classifications available from Hippocampome.org . This ensures that the anatomical structure and cell-type representation in the demo circuits reflect up-to-date experimental knowledge from peer-reviewed literature.

The distribution of glutamatergic (excitatory) and GABAergic (inhibitory) neurons of distinct types across each subregion and layer of the hippocampal formation is incorporated, based on Hippocampome.org data. This organization allows users to accurately explore the spatial arrangement of excitatory and inhibitory populations within different anatomical areas such as the Dentate Gyrus (DG), CA3, CA2, CA1, Subiculum, and Entorhinal Cortex (EC).

The workflow includes the following steps:

Expand the Mouse Circuit tab.
Click Load Circuit before making selections to visualize only the selected neurons.
(Optional) Build specific connections (e.g., CA3-PC to CA1-PC) before visualization if needed.
Select the desired neural ensembles:

Toggle specific anatomical regions (e.g., DG, CA3, CA2, CA1, Subiculum, EC).
Further refine your selection by choosing specific hippocampal layers (e.g., SLM, SR, SP, SO).
Enable/disable specific Neuron Types within each region (e.g., Granule cells, Basket cells, Mossy fibers).

Select a corresponding Activity dataset (if available) to animate firing patterns.
Example: Activity visualization in CA3 based on simulations from Kopsick et al., Cognitive computation, 2024 .

Demo mouse Circuit Region Selection Screenshot

Fig. 8 Mouse Circuit (CA3 to CA1 Projection).

Demo Videos

Video 1: How to explore the mouse demo circuit via the NCV

Video 2: How to submit a job on the HPC, fetch and visualize the results

Data Upload

Supported Formats

CSV files : Two different .csv files for network and activity, respectively.
HDF5 files : Single .hdf5 file containing both network and activity.
SONATA files : Two separate .h5 files for network and activity along with a corresponding .csv file for neuron type definitions.

📝 Supported File Formats

CSV Format (2 Files Required)

Network file (.csv)
Gid, X, Y, Z

Activity file (.csv)
Gid, Time

HDF5 Format

Single HDF5 file containing both datasets
/network → (Gid, X, Y, Z)
/activity → (Gid, Time)

SONATA Format

Network file (nodes.h5)
/nodes/<population>/node_id
/nodes/<population>/<group>/x
/nodes/<population>/<group>/y
/nodes/<population>/<group>/z
/nodes/<population>/node_type_id
Activity file (spikes.h5)
/spikes/<population>/node_ids
/spikes/<population>/timestamps
Optional: Node Types file (.csv)
node_type_id, ei
(ei = "e" for excitatory, "i" for inhibitory)

If you need support to convert your data files into one of the accepted formats, please send us and email to ali.maqsood AT ibf.cnr.it

Fig. 9 Network and Activity Data Structure.

Example Files

2D Large Scale Example

The following files allow a 2D visualization of 1M neurons

Upload Process

Click UPLOAD DATA on the sidebar.
Select a .csv , .hdf5 or SONATA files to upload
Wait for upload and chunking to complete (progress bar displayed).
After processing, your 3D circuit visualization appears.

Fig. 10 Uploading files.

Fig. 11 Loading data for visualizing circuit.

Support

For any issues, please do not hesitate to contact us at: ali.maqsood AT ibf.cnr.it