# ndx-wearables Extension for NWB
Store data from wearable devices in NWB
This extension is designed to help store data collected from a wide variety of wearable devices in a cross-device
capable way, and with an eye towards clinical applications.
For more details about the extension, see the paper "NDX-Wearables: An NWB Extension for Clinical Neuroscience"
(submitted to NER 2025).
## Installation
Create a new Python environment. Python 3.11 works well, python 3.8-3.12 have been tested.
```terminal
conda create -n <env_name> python=3.11
```
You should be able to install from pypi using `pip install ndx-wearables`
If you would like to install and contribute to developing the package, follow the instructions below
in [Installing in editable mode](#Installing-in-editable-mode)
## Usage
To see how the data stored using this extension looks, visit our example dataset on the
[EMBER Archive](https://dandi.emberarchive.org/dandiset/000207).
You can also generate a local copy of a synthetic dataset by running the `examples/all_modalities.py` script.
## Notes on Extension Usage
Several of the modality-specific extensions (e.g., `BloodOxygenSeries`, `HeartRateSeries`, etc.) now require additional
arguments beyond the usual `name`, `data`, and `timestamps`.
In particular:
- `wearable_device` is required for classes that link to a device (e.g., `BloodOxygenSeries`, `VO2MaxSeries`)
- `algorithm` is required for many classes to indicate how the data was derived (e.g., `HRVSeries`, `StepCountSeries`)
If these arguments are omitted, instantiating the class will raise an error. You can find working examples in the test
scripts under `src/pynwb/tests`.
## Arguments for ndx-wearables Classes
#### TimeSeries (WearableTimeSeries) based modalities
| Class Name | Required Arguments | Optional Arguments |
|------------------------|------------------------------------------------------------------------|-----------------------------------------------|
| `ActivitySeries` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm` | `comments`, `resolution`, `conversion` |
| `BloodOxygenSeries` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `resolution`, `conversion`, `comments` |
| `HeartRateSeries` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `resolution`, `conversion`, `comments` |
| `HRVSeries` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm`, `sampling_rate` | `comments`, `description`, `resolution` |
| `METSeries` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `comments`, `resolution`, `conversion` |
| `SleepMovementSeries` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm` | `comments`, `resolution`, `conversion` |
| `SleepPhaseSeries` | `name`, `data`, `timestamps`, `wearable_device`, `enums`, `algorithm` | `resolution`, `conversion`, `comments` |
| `StepCountSeries` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm` | `resolution`, `conversion`, `comments` |
| `VO2MaxSeries` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `comments`, `resolution`, `conversion` |
#### EventTable (WearableEvents) based modalities (WIP)
| Class Name | Required Arguments | Optional Arguments |
|---------------|------------------------------------------------------------------------|-----------------------------------------------|
| `Workouts` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm` | `comments`, `resolution`, `conversion` |
| `SleepEvents` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `resolution`, `conversion`, `comments` |
These reflect typical usage in constructors. For full context or updates, refer to the class definitions in
[`src/pynwb/ndx_wearables`](src/pynwb/ndx_wearables) and usage examples in [`src/pynwb/tests`](src/pynwb/tests).
## Developing the extension
We use a gitflow model for collaborative development. Each feature should be created on a branch that branches off of
the `develop` branch. Draft PRs back into develop should be open for each WIP feature, and marked as ready for review
once the feature is complete. Periodic releases will be made from develop into `main`.
### Installing in editable mode
Navigate to the project root `cd path/to/ndx-wearables`, then install the required dependencies. For developers, use:
```terminal
pip install -r requirements-dev.txt
```
Custom extensions are added to the extension spec YAML file by running:
```terminal
python src/spec/create_extension_spec.py
```
After running this script, you can verify that the extensions are correctly added to `spec/ndx-wearables.extensions.yaml`.
Running test code may be done with PyTest using the test files located in `src/pynwb/tests`.
To use custom extensions outside a PyTest setting, they must be registered by navigating to the directory root and installing the package:
```terminal
cd path/to/ndx-wearables
pip install -e .
```
---
This extension was created using [ndx-template](https://github.com/nwb-extensions/ndx-template).
Raw data
{
"_id": null,
"home_page": null,
"name": "ndx-wearables",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "NWB, NeurodataWithoutBorders, ndx-extension, nwb-extension",
"author": null,
"author_email": "Tomek Fraczek <tomek.fraczek@bcm.edu>, Nicole Guittari <nicole.guittari@jhuapl.edu>, Lauren Diaz <lauren.diaz@jhuapl.edu>, Rick Hanish <rh103@rice.edu>, Erik Johnson <erik.c.johnson@jhuapl.edu>",
"download_url": "https://files.pythonhosted.org/packages/d9/08/18630d4df58a6d21aa2ceccf568edf8af3a287e2c4d74d4ecef25d48abd2/ndx_wearables-0.1.3.tar.gz",
"platform": null,
"description": "# ndx-wearables Extension for NWB\n\nStore data from wearable devices in NWB\n\nThis extension is designed to help store data collected from a wide variety of wearable devices in a cross-device \ncapable way, and with an eye towards clinical applications.\nFor more details about the extension, see the paper \"NDX-Wearables: An NWB Extension for Clinical Neuroscience\" \n(submitted to NER 2025).\n\n\n## Installation\n\nCreate a new Python environment. Python 3.11 works well, python 3.8-3.12 have been tested.\n\n```terminal\nconda create -n <env_name> python=3.11\n```\nYou should be able to install from pypi using `pip install ndx-wearables`\n\nIf you would like to install and contribute to developing the package, follow the instructions below \nin [Installing in editable mode](#Installing-in-editable-mode)\n\n## Usage\n\nTo see how the data stored using this extension looks, visit our example dataset on the\n[EMBER Archive](https://dandi.emberarchive.org/dandiset/000207).\n\nYou can also generate a local copy of a synthetic dataset by running the `examples/all_modalities.py` script.\n\n\n## Notes on Extension Usage\n\nSeveral of the modality-specific extensions (e.g., `BloodOxygenSeries`, `HeartRateSeries`, etc.) now require additional\narguments beyond the usual `name`, `data`, and `timestamps`.\n\nIn particular:\n- `wearable_device` is required for classes that link to a device (e.g., `BloodOxygenSeries`, `VO2MaxSeries`)\n- `algorithm` is required for many classes to indicate how the data was derived (e.g., `HRVSeries`, `StepCountSeries`)\n\nIf these arguments are omitted, instantiating the class will raise an error. You can find working examples in the test \nscripts under `src/pynwb/tests`.\n\n## Arguments for ndx-wearables Classes\n\n#### TimeSeries (WearableTimeSeries) based modalities\n\n| Class Name | Required Arguments | Optional Arguments |\n|------------------------|------------------------------------------------------------------------|-----------------------------------------------|\n| `ActivitySeries` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm` | `comments`, `resolution`, `conversion` |\n| `BloodOxygenSeries` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `resolution`, `conversion`, `comments` |\n| `HeartRateSeries` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `resolution`, `conversion`, `comments` |\n| `HRVSeries` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm`, `sampling_rate` | `comments`, `description`, `resolution` |\n| `METSeries` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `comments`, `resolution`, `conversion` |\n| `SleepMovementSeries` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm` | `comments`, `resolution`, `conversion` |\n| `SleepPhaseSeries` | `name`, `data`, `timestamps`, `wearable_device`, `enums`, `algorithm` | `resolution`, `conversion`, `comments` |\n| `StepCountSeries` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm` | `resolution`, `conversion`, `comments` |\n| `VO2MaxSeries` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `comments`, `resolution`, `conversion` |\n\n\n#### EventTable (WearableEvents) based modalities (WIP)\n\n| Class Name | Required Arguments | Optional Arguments |\n|---------------|------------------------------------------------------------------------|-----------------------------------------------|\n| `Workouts` | `name`, `data`, `timestamps`, `wearable_device`, `algorithm` | `comments`, `resolution`, `conversion` |\n| `SleepEvents` | `name`, `data`, `timestamps`, `wearable_device`, `unit`, `algorithm` | `resolution`, `conversion`, `comments` |\n\n\nThese reflect typical usage in constructors. For full context or updates, refer to the class definitions in\n[`src/pynwb/ndx_wearables`](src/pynwb/ndx_wearables) and usage examples in [`src/pynwb/tests`](src/pynwb/tests).\n\n\n## Developing the extension\n\nWe use a gitflow model for collaborative development. Each feature should be created on a branch that branches off of \nthe `develop` branch. Draft PRs back into develop should be open for each WIP feature, and marked as ready for review \nonce the feature is complete. Periodic releases will be made from develop into `main`.\n\n### Installing in editable mode\nNavigate to the project root `cd path/to/ndx-wearables`, then install the required dependencies. For developers, use:\n\n```terminal\npip install -r requirements-dev.txt\n```\nCustom extensions are added to the extension spec YAML file by running:\n\n```terminal\npython src/spec/create_extension_spec.py\n```\n\nAfter running this script, you can verify that the extensions are correctly added to `spec/ndx-wearables.extensions.yaml`.\n\nRunning test code may be done with PyTest using the test files located in `src/pynwb/tests`.\n\nTo use custom extensions outside a PyTest setting, they must be registered by navigating to the directory root and installing the package:\n```terminal\ncd path/to/ndx-wearables\npip install -e .\n```\n\n---\nThis extension was created using [ndx-template](https://github.com/nwb-extensions/ndx-template).\n",
"bugtrack_url": null,
"license": "BSD-3",
"summary": "Store data from human wearables",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/BCM-Neurosurgery/ndx-wearables/issues",
"Changelog": "https://github.com/BCM-Neurosurgery/ndx-wearables/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/BCM-Neurosurgery/ndx-wearables/discussions",
"Homepage": "https://github.com/BCM-Neurosurgery/ndx-wearables"
},
"split_keywords": [
"nwb",
" neurodatawithoutborders",
" ndx-extension",
" nwb-extension"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2e9e7c8cbdc6c11345e5f9ace65f795c65d7162f73b47164dc7c55c873323228",
"md5": "98ce55b0c75fb53bddccd9d29a89933d",
"sha256": "844e63b3b1204e039ffb8c0dc678e258181173f90c1fcfe401ac5ba2c985954f"
},
"downloads": -1,
"filename": "ndx_wearables-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "98ce55b0c75fb53bddccd9d29a89933d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8295,
"upload_time": "2025-07-30T17:52:06",
"upload_time_iso_8601": "2025-07-30T17:52:06.791573Z",
"url": "https://files.pythonhosted.org/packages/2e/9e/7c8cbdc6c11345e5f9ace65f795c65d7162f73b47164dc7c55c873323228/ndx_wearables-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d90818630d4df58a6d21aa2ceccf568edf8af3a287e2c4d74d4ecef25d48abd2",
"md5": "aeb420aa3c5720ba185ef240515759fd",
"sha256": "4173906a4fc0cf6343618cb3ea3d2b916e489ee4b7b4b3caffb6a29c95e1e1ef"
},
"downloads": -1,
"filename": "ndx_wearables-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "aeb420aa3c5720ba185ef240515759fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27343,
"upload_time": "2025-07-30T17:52:08",
"upload_time_iso_8601": "2025-07-30T17:52:08.192631Z",
"url": "https://files.pythonhosted.org/packages/d9/08/18630d4df58a6d21aa2ceccf568edf8af3a287e2c4d74d4ecef25d48abd2/ndx_wearables-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 17:52:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BCM-Neurosurgery",
"github_project": "ndx-wearables",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ndx-wearables"
}
JSON
