kind-lab-to-nwb

NWB conversion scripts for Kind lab data to the Neurodata Without Borders data format.

This repository contains conversion pipelines for multiple datasets from the Kind lab, each organized in its own module with specific conversion scripts and utilities.

Repository Structure

kind-lab-to-nwb/ ├── LICENSE ├── make_env.yml ├── pyproject.toml ├── README.md ├── MANIFEST.in ├── .gitignore ├── .pre-commit-config.yaml ├── dj_local_conf.json ├── misc/ └── src/ └── kind_lab_to_nwb/ ├── __init__.py ├── arc_ecephys_2024/ # Fear conditioning EEG/LFP dataset │ ├── __init__.py │ ├── convert_session.py # Single session conversion │ ├── convert_all_sessions.py # Batch conversion script │ ├── insert_session.py # Database insertion utilities │ ├── metadata.yaml # Experiment metadata │ ├── notes.md # Detailed conversion notes │ ├── spyglass_mock/ # Spyglass compatibility utilities │ ├── tutorial/ # Data access tutorials │ └── utils/ # Conversion utility functions └── rat_behavioural_phenotyping_2025/ # Behavioral phenotyping datasets ├── auditory_fear_conditioning/ ├── marble_interaction/ ├── object_location_memory/ ├── object_recognition/ ├── one_trial_social/ ├── prey_capture/ ├── water_maze/ ├── interfaces/ # Custom data interfaces ├── tutorials/ # Analysis tutorials └── utils/ # Shared utilities

Installation

Installation from GitHub

You can install the package with:

bash git clone https://github.com/catalystneuro/kind-lab-to-nwb cd kind-lab-to-nwb conda env create --file make_env.yml conda activate kind-lab-to-nwb-env

Alternatively, using pip only:

bash git clone https://github.com/catalystneuro/kind-lab-to-nwb cd kind-lab-to-nwb pip install --editable .

Datasets

arcecephys2024: Fear Conditioning EEG/LFP Dataset

This module converts data from a fear conditioning experiment investigating neural responses in Syngap1+/Delta-GAP rats. The dataset includes EEG, LFP, accelerometer, and behavioral video recordings across multiple experimental sessions.

Dataset Description

Experiment: Fear conditioning paradigm in male wild-type and Syngap1+/Delta-GAP rats (n=31, ages 3-6 months)

Data Types: - Local Field Potentials (LFP) - 2 kHz sampling, 0.1-600 Hz bandpass - Electroencephalogram (EEG) - surface recordings from multiple brain regions - 3-axis accelerometer data - 500 Hz sampling - Behavioral videos - ~30 Hz - TTL trigger events - 2 kHz sampling

Experimental Sessions: 1. Hab_1: Context habituation (Day 1) 2. Seizure_screening: Seizure monitoring (Day 2, subset of animals) 3. Hab_2: Second context habituation (Day 3) 4. Baselinetoneflash_hab: CS pre-exposure (Day 4, subset) 5. Cond: Fear conditioning with CS-US pairings (Day 4) 6. Recall: Fear response testing (Day 5)

Quick Start

Converting a Single Session

```python from pathlib import Path from kindlabtonwb.arcecephys2024.convertsession import sessiontonwb from neuroconv.tools.path_expansion import LocalPathExpander

Set up paths

datadirpath = Path("/path/to/your/data") outputdirpath = Path("/path/to/output")

Define source data specification

sourcedataspec = { "OpenEphysRecording": { "basedirectory": datadirpath, "folderpath": "{subjectid}/{sessionid}/{subjectid}{sessiondate}{sessiontime}{task}", }, }

Expand paths and extract metadata

pathexpander = LocalPathExpander() metadatalist = pathexpander.expandpaths(sourcedataspec)

Convert first session

sessiontonwb( datadirpath=datadirpath, outputdirpath=outputdirpath, pathexpandermetadata=metadatalist[0], stubtest=False, verbose=True, ) ```

Converting All Sessions

```python from kindlabtonwb.arcecephys2024.convertallsessions import datasetto_nwb

datasettonwb( datadirpath="/path/to/your/data", outputdirpath="/path/to/output", verbose=True, ) ```

Data Access Tutorial

The module includes a comprehensive Jupyter notebook tutorial (tutorial/access_data_tutorial.ipynb) demonstrating how to:

• Stream NWB files from DANDI Archive
• Access EEG and LFP signals
• View behavioral videos
• Analyze accelerometer data
• Extract TTL trigger events
• Visualize multi-modal data

Expected Data Structure

Your raw data should be organized as follows:

data_directory/ ├── channels_details_v2.xlsx # Electrode configuration ├── cs_video_frames.xlsx # Video synchronization data ├── subject_id_1/ │ └── session_id/ │ ├── subject_id_session_date_session_time_task/ # OpenEphys data │ └── video_file.avi # Behavioral video └── subject_id_2/ └── session_id/ └── ...

Key Features

• Time Alignment: Automatic synchronization between electrophysiology, video, and behavioral triggers
• Multi-modal Integration: Combines EEG, LFP, accelerometer, and video data in single NWB files
• Spyglass Compatibility: Includes utilities for integration with the Spyglass analysis framework
• Flexible Processing: Supports both single session and batch conversion workflows
• Rich Metadata: Comprehensive experimental metadata including electrode locations and task descriptions

Spyglass Integration

The module includes specialized utilities for Spyglass compatibility:

```python

For Spyglass integration, use the custom branch

git clone -b populatesensordata https://github.com/alessandratrapani/spyglass.git ```

The spyglass_mock/ directory contains utilities for testing Spyglass integration and mock data generation.

ratbehaviouralphenotyping_2025

This module contains conversion scripts for various behavioral phenotyping experiments including:

• Auditory Fear Conditioning: Fear learning paradigms
• Marble Interaction: Object interaction behaviors
  
• Object Location Memory: Spatial memory tasks
• Object Recognition: Recognition memory tests
• One Trial Social: Social behavior assessment
• Prey Capture: Predatory behavior analysis
• Water Maze: Spatial navigation tasks

Each sub-module includes its own conversion scripts, metadata files, and analysis tutorials.

Usage Guidelines

General Workflow

1. Prepare your data according to the expected structure for your dataset
2. Install the package and dependencies
3. Configure paths in the conversion scripts
4. Run conversion (single session or batch)
5. Validate output using the provided tutorials

Customization

Each conversion module can be customized by:

• Modifying metadata.yaml files for experiment-specific metadata
• Adjusting conversion parameters in the main scripts
• Adding custom interfaces for new data types
• Extending utility functions for specific analysis needs

Contributing

When adding new conversion modules:

1. Create a new directory under src/kind_lab_to_nwb/
2. Include the standard files: convert_session.py, metadata.yaml, notes.md
3. Add utility functions in a utils/ subdirectory
4. Provide tutorials and documentation
5. Follow the existing code structure and naming conventions

Support

For questions about specific conversions or to report issues, please:

1. Check the notes.md file in the relevant module
2. Review the tutorial notebooks
3. Open an issue on the GitHub repository

References

• arcecephys2024: Based on Katsanevaki, D., et al. (2024). "Key roles of C2/GAP domains in SYNGAP1-related pathophysiology." Cell Reports, 43(9), 114733.
• DANDI Archive: Dataset available at DANDI:001457
• EMBER Archive: Datasets available at:
  • EMBER:000199 - Auditory Fear Conditioning
  • EMBER:000200 - Marble Interaction
  • EMBER:000201 - Object Location Memory
  • EMBER:000202 - Object Recognition
  • EMBER:000203 - One Trial Social
  • EMBER:000204 - Prey Capture
  • EMBER:000205 - Water Maze