nwb2bids

nwb2bids reorganizes NWB files into a BIDS directory layout.

Features:

• Automatically renames NWB files and their directories to conform to BIDS conventions.

• Extracts relevant metadata from NWB files to populate BIDS sidecar TSV & JSON files.

• Currently supports BEP32 (micro-electrode electrophysiology) data types, such as extracellular (ecephys) and intracellular (icephys) electrophysiology, as well as associated behavioral events.

In the future, we plan to support:

• stimuli

• videos

• ndx-events

• Hierarchical Event Descriptors (HED)

• microscopy

• ndx-pose + BIDS motion

• eye tracking

Installation

To install the latest stable release of nwb2bids you can use either pip or conda.

To do this, run:

pipconda-forge

pip install nwb2bids

Some extra optional dependencies include the ability to run remotely on a dataset hosted on DANDI.

The easiest way to install these extras is to run:

pip

pip install "nwb2bids[dandi]"

How to use the documentation

Our documentation is structured to cater to users ranging from beginners to advanced developers and contributors. Below is an overview of the key sections to help you navigate our documentation effectively

• User Guide

  The User Guide offers a comprehensive overview of our data models and core functionalities. It is recommended for users who wish to understand the underlying concepts and extend their scripts beyond basic conversions.

• Developer Guide

  For developers interested in contributing to nwb2bids, the Developer Guide provides essential information such as instructions for building your own classes, our coding style, instructions on how to build the documentation, run the testing suite, etc.

• API Reference

  Detailed documentation of the nwb2bids API can be found in the API section.

Do you find that some information is missing or some section lacking or unclear? Reach out with an issue or pull request on our GitHub repository. We are happy to help and appreciate your feedback.

Data Standards and Related Resources

Understanding the Standardization Landscape

nwb2bids operates at the intersection of multiple neuroscience data standards. This section clarifies which standards are currently supported, which are planned for future implementation, and how they relate to the broader standardization ecosystem.

For a comprehensive overview of neuroscience data standards and their relationships, see the SfN 2025: “The Ecosystem of Standards in Neuroscience: Which Ones Are For You?” Poster by Oliver Rübel et al.

Currently Supported Standards

nwb2bids currently provides full support for:

• NWB (Neurodata Without Borders): A data standard for neurophysiology that provides a common format for cellular-based neurophysiology data, along with trial structure, metadata, and behavioral data. nwb2bids reads and processes NWB files as input.

  • NWB Format Specification: Technical specification of the NWB format.

  • NWB Overview: High-level overview of NWB and its ecosystem.

  • NWB Extensions: Catalog of community-developed extensions (NDX) that extend NWB for specific data types and use cases.

• BIDS (Brain Imaging Data Structure): A specification for organizing neuroscience data in a standardized directory structure with accompanying metadata. nwb2bids outputs data organized according to BIDS conventions.

  • BIDS Specification: Official BIDS specification.

  • BIDS Extension Proposals (BEPs): Overview of ongoing extensions to BIDS for additional modalities (eye tracking, microscopy, etc.). Note that this page evolves as new extensions are proposed and adopted.

  • BEP032 (BIDS Extension Proposal 032): Currently supported for micro-electrode electrophysiology, including extracellular (ecephys) and intracellular (icephys) electrophysiology, as well as associated behavioral events. See the BEP032 pull request for specification details.

• HED (Hierarchical Event Descriptors) (hedtags.org): Basic support for annotating events and experimental structure with standardized vocabularies. nwb2bids currently includes HED version specification (v8.3.0) in dataset metadata and automatically assigns basic HED tags to event tables (e.g., “Experimental-trial” for trials, “Time-block” for epochs). Future work will extend HED annotation capabilities.

Planned Future Support

We are actively planning to extend nwb2bids support to include:

• ndx-events: NWB extension for representing timestamped event and TTL pulse data.

• ndx-pose + BIDS motion: For pose estimation and motion capture data.

• Additional data modalities: stimuli, videos, microscopy (BEP031), and eye tracking (BEP020)

• Extended HED annotation capabilities beyond basic tagging.

These extensions will require integration with their respective standards and may depend on external tooling or additional NWB extensions.

Related Standardization Efforts

nwb2bids operates in the broader context of neuroscience data standardization initiatives:

• DICOM WG-32: Neurophysiology Data: The Digital Imaging and Communications in Medicine (DICOM) working group focused on standardizing neurophysiology data, including EEG, EMG, evoked potentials, and other clinical neurophysiology signals. While DICOM and NWB/BIDS serve different use cases and communities, awareness of parallel standardization efforts helps users understand the broader landscape of neurophysiology data standards.

Related Tools and Converters

nwb2bids is part of a broader ecosystem of tools for working with NWB and BIDS data:

NWB Converters:

• NWB Guide: A no-code graphical interface for converting data to NWB format.

• NeuroConv: A Python library providing low-code conversion pipelines to NWB format from various proprietary and open formats.

BIDS Converters for Other Modalities:

• BIDS Converters: Collection of converters for different neuroimaging and neuroscience data modalities (MRI, EEG, MEG, iEEG, PET, and more).

AI Assistants for Standards:

• qp - AI Assistants Collection: A curated collection of AI assistants for various neuroscience projects and data standards, providing interactive help with BIDS, NWB, and related tools.