# 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/).
Raw data
{
"_id": null,
"home_page": "https://github.com/DeepLabCut/DLC2NWB",
"name": "dlc2nwb",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "A. & M. Mathis Labs",
"author_email": "alexander@deeplabcut.org",
"download_url": "https://files.pythonhosted.org/packages/6d/77/b60f46e574ee4576f86886415d0db9a6b3bae8373fa0ce0b17793c20c606/dlc2nwb-0.3.tar.gz",
"platform": null,
"description": "# Welcome to the DeepLabCut 2 Neurodata Without Borders Repo\n\nHere 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.\n\nSpecifically, 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).\n\n# NWB pose ontology\n\nThe 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/).\n\n# Installation:\n\nSimply do (it only depends on `ndx-pose` and `deeplabcut`):\n\n`pip install dlc2nwb`\n\n# Example within DeepLabCut\n\nDeepLabCut's h5 data files can be readily converted to NWB format either via the GUI from the `Analyze Videos` tab or programmatically, as follows:\n\n```python\nimport deeplabcut\n\ndeeplabcut.analyze_videos_converth5_to_nwb(config_path, video_folder)\n```\nNote 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`.\n\n# Example use case of this package (directly):\n\nHere is an example for converting DLC data to NWB format (and back). Notice you can also export your data directly from DeepLabCut.\n\n```\nfrom dlc2nwb.utils import convert_h5_to_nwb, convert_nwb_to_h5\n\n# Convert DLC -> NWB:\nnwbfile = convert_h5_to_nwb(\n 'examples/config.yaml',\n 'examples/m3v1mp4DLC_resnet50_openfieldAug20shuffle1_30000.h5',\n)\n\n# Convert NWB -> DLC\ndf = convert_nwb_to_h5(nwbfile[0])\n```\n\nExample 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).\n\n\n# Funding and contributions:\n\nWe gratefully acknowledge the generous support from the [Kavli Foundation](https://kavlifoundation.org/) via a [Kavli Neurodata Without Borders Seed Grants\n](https://www.nwb.org/nwb-seed-grants/).\n\nWe also acknowledge feedback, and our collaboration with [Ben Dichter, Ryan Ly and Oliver Ruebel](https://www.nwb.org/team/).\n",
"bugtrack_url": null,
"license": "",
"summary": "DeepLabCut <-> NWB conversion utilities",
"version": "0.3",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8df45f1b1292d39d4402b8cbd592053e4c9057ee23b880815c179ecd586f2e4",
"md5": "3098b715369749f97c1f74b473a04cd7",
"sha256": "9907f802b884bc86aa8642344c487796d4cc05790b0b7b14131fd77edf9155fd"
},
"downloads": -1,
"filename": "dlc2nwb-0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3098b715369749f97c1f74b473a04cd7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8277,
"upload_time": "2023-01-26T18:17:18",
"upload_time_iso_8601": "2023-01-26T18:17:18.864996Z",
"url": "https://files.pythonhosted.org/packages/e8/df/45f1b1292d39d4402b8cbd592053e4c9057ee23b880815c179ecd586f2e4/dlc2nwb-0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6d77b60f46e574ee4576f86886415d0db9a6b3bae8373fa0ce0b17793c20c606",
"md5": "6af5e57453e3e1c6b49d46588e270108",
"sha256": "489e645a6f88aedcb1e76ff6ab9e9d61ddf198bbe541eb73c8e553970538c2a0"
},
"downloads": -1,
"filename": "dlc2nwb-0.3.tar.gz",
"has_sig": false,
"md5_digest": "6af5e57453e3e1c6b49d46588e270108",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8142,
"upload_time": "2023-01-26T18:17:20",
"upload_time_iso_8601": "2023-01-26T18:17:20.382983Z",
"url": "https://files.pythonhosted.org/packages/6d/77/b60f46e574ee4576f86886415d0db9a6b3bae8373fa0ce0b17793c20c606/dlc2nwb-0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-26 18:17:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "DeepLabCut",
"github_project": "DLC2NWB",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dlc2nwb"
}
JSON
