Metadata-Version: 2.1
Name: dlc2nwb
Version: 0.1
Summary: DeepLabCut <-> NWB conversion utilities
Home-page: https://github.com/DeepLabCut/DLC2NWB
Author: A. & M. Mathis Labs
Author-email: alexander@deeplabcut.org
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/DeepLabCut/DLC2NWB/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: deeplabcut (>=2.2.0.5)
Requires-Dist: ndx-pose (>=0.1.1)
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'

# 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 use case:

Here is an example for converting DLC data to NWB format (and back). Notice you can also export your data directly from DeepLabCut. This will be further documented, and is currently in this [branch](https://github.com/DeepLabCut/DeepLabCut/tree/nwb)!

```
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/).


