https://github.com/deeplabcut/dlc2nwb

Utilities to convert DeepLabCut (DLC), output to/from Neurodata Without Borders (NWB) format.
https://github.com/deeplabcut/dlc2nwb

deeplabcut nwb nwb-format

Last synced: about 2 months ago
JSON representation

Utilities to convert DeepLabCut (DLC), output to/from Neurodata Without Borders (NWB) format.

• Host: GitHub
• URL: https://github.com/deeplabcut/dlc2nwb
• Owner: DeepLabCut
• License: mit
• Created: 2021-10-06T13:15:45.000Z (about 3 years ago)
• Default Branch: main
• Last Pushed: 2023-03-29T06:58:25.000Z (over 1 year ago)
• Last Synced: 2024-06-02T15:08:40.953Z (7 months ago)
• Topics: deeplabcut, nwb, nwb-format
• Language: Python
• Homepage:
• Size: 303 KB
• Stars: 12
• Watchers: 6
• Forks: 6
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Welcome to the DeepLabCut 2 Neurodata Without Borders Repo

Here we provide utilities to convert [DeepLabCut (DLC)](https://github.com/DeepLabCut/DeepLabCut) output to/from [Neurodata Without Borders (NWB) format](https://www.nwb.org/nwb-neurophysiology/). This repository also elaborates a way for how pose estimation data should be represented in NWB.

Specifically, this package allows you to convert DLC's predictions on videos (*.h5 files) into NWB format. This is best explained with an example (see below).

# NWB pose ontology

The standard is presented [here](https://github.com/rly/ndx-pose). Our code is based on this NWB extension (PoseEstimationSeries, PoseEstimation) that was developed with [Ben Dichter, Ryan Ly and Oliver Ruebel](https://www.nwb.org/team/).

# Installation:

Simply do (it only depends on `ndx-pose` and `deeplabcut`):

`pip install dlc2nwb`

# Example within DeepLabCut

DeepLabCut's h5 data files can be readily converted to NWB format either via the GUI from the `Analyze Videos` tab or programmatically, as follows:

```python

import deeplabcut

deeplabcut.analyze_videos_converth5_to_nwb(config_path, video_folder)

```

Note that DLC does not strictly depend on dlc2nwb just yet; if attempting to convert to NWB, a user would be asked to run `pip install dlc2nwb`.

# Example use case of this package (directly):

Here is an example for converting DLC data to NWB format (and back). Notice you can also export your data directly from DeepLabCut.

```

from dlc2nwb.utils import convert_h5_to_nwb, convert_nwb_to_h5

# Convert DLC -> NWB:

nwbfile = convert_h5_to_nwb(

    'examples/config.yaml',

    'examples/m3v1mp4DLC_resnet50_openfieldAug20shuffle1_30000.h5',

)

# Convert NWB -> DLC

df = convert_nwb_to_h5(nwbfile[0])

```

Example data to run the code is provided in the folder [examples](/examples). The data is based on a DLC project you can find on [Zenodo](https://zenodo.org/record/4008504#.YWhD7NOA4-R) and that was originally presented in [Mathis et al., Nat. Neuro](https://www.nature.com/articles/s41593-018-0209-y) as well as [Mathis et al., Neuron](https://www.sciencedirect.com/science/article/pii/S0896627320307170?via%3Dihub). To limit space, the folder only contains the project file `config.yaml` and DLC predictions for an example video called `m3v1mp4.mp4`, which are stored in `*.h5` format. The video is available, [here](https://github.com/DeepLabCut/DeepLabCut/tree/master/examples/openfield-Pranav-2018-10-30/videos).

# Funding and contributions:

We gratefully acknowledge the generous support from the [Kavli Foundation](https://kavlifoundation.org/) via a [Kavli Neurodata Without Borders Seed Grants

](https://www.nwb.org/nwb-seed-grants/).

We also acknowledge feedback, and our collaboration with [Ben Dichter, Ryan Ly and Oliver Ruebel](https://www.nwb.org/team/).