# ndx-dbs Extension for NWB
This extension is developed to extend NWB data standards to incorporate required (meta)data for DBS experiments. `DBSGroup`, the main neurodata-type in this extension, in fact extends the `LabMetaData` which itself extends the NWBContainer base type and incorporates data types of `DBSMeta`(as an extension of LabMetaData), `DBSSubject`(as an extension of LabMetaData) and `DBSDevice`(as an extension of Device) which itself includes `DBSElectrodes`(as an extension of DynamicTable). Instances of these data types are interlinked to each other to account for the comprehensiveness of all the required meta(data) in a general experiment including DBS.
<div align="center">
<img src="https://github.com/Hamidreza-Alimohammadi/ndx-dbs/assets/63550467/63a919ff-d564-49de-98e7-4893bfc3e43f" width="1000">
</div>
## Installation
Simply clone the repo and navigate to the root directory, then:
```
pip install .
```
## Test
A roundTrip test is runnable through ```pytest``` from the root. The test script can be found here:
```
\src\pynwb\tests
```
## An example use-case
The following is an example use case of ```ndx-dbs``` with explanatory comments. First, we build up an ```nwb_file``` and define an endpoint recording device:
```python
from datetime import datetime
from uuid import uuid4
from dateutil.tz import tzlocal
from pynwb import NWBHDF5IO, NWBFile
from ndx_dbs import (
DBSDevice,
DBSElectrodes,
DBSMeta,
DBSSubject,
DBSGroup
)
nwb_file = NWBFile(
session_description='DBS mock session',
identifier=str(uuid4()),
session_start_time=datetime.now(tzlocal()),
experimenter='experimenter',
lab='ChiWangLab',
institution='UKW',
experiment_description='',
session_id='',
)
# define an endpoint main recording device
main_device = nwb_file.create_device(
name='endpoint_recording_device',
description='description_of_the_ERD', # ERD: Endpoint recording device
manufacturer='manufacturer_of_the_ERD'
)
```
Then, we define an instance of `DBSElectrodes` to represent the meta-data on the recording electrodes:
```python
'''
creating an DBS electrodes table
as a DynamicTable
'''
dbs_electrodes_table = DBSElectrodes(
description='descriptive meta-data on DBS stimulus electrodes'
)
# add electrodes
dbs_electrodes_table.add_row(
el_id='el_0',
polarity='negative electrode (stimulation electrode, cathode)',
impedance='0.8 MOhm',
length='X cm',
tip='tip surface ~ XX micrometer sq',
material='platinum/iridium',
location='STN',
comment='none',
)
dbs_electrodes_table.add_row(
el_id='el_1',
polarity='positive electrode (reference electrode, anode)',
impedance='1 MOhm',
length='Y cm',
tip='tip surface ~ YY micrometer sq',
material='platinum/iridium',
location='scalp surface',
comment='distance D from el_0',
)
# adding the object of DynamicTable
nwb_file.add_acquisition(dbs_electrodes_table) # storage point for DT
```
Now, we can define an instance of ```DBSDevice```:
```python
# define an DBSDevice-type device for ecg recording
dbs_device = DBSDevice(
name='DBS_device',
description='cable-bound multichannel systems stimulus generator; TypeSTG4004',
manufacturer='MultichannelSystems, Reutlingen, Germany',
synchronization='taken care of via ...',
electrodes_group=dbs_electrodes_table,
endpoint_recording_device=main_device
)
# adding the object of DBSDevice
nwb_file.add_device(dbs_device)
```
And also an instance of ```DBSMeta``` to store the meta-data for a DBS experiment:
```python
dbs_meta_group = DBSMeta(
name='DBS_meta',
stim_state='ON',
stim_type='unipolar',
stim_area='STN',
stim_coordinates='–3.6mmAP, either–2.5mm (right) or 12.5mm(left)ML, and–7.7mmDV',
pulse_shape='rectangular',
pulse_width='60 micro-seconds',
pulse_frequency='130 Hz',
pulse_intensity='50 micro-Ampere',
charge_balance='pulse symmetric; set to be theoretically zero',
)
# adding the object of DBSMeta
nwb_file.add_lab_meta_data(dbs_meta_group) # storage point for custom LMD
```
Along with an instance of `DBSSubject`:
```python
dbs_subject_group = DBSSubject(
name='DBS_subject',
model='6-OHDA',
controls='specific control group in this experiment',
comment='any comments on this subject',
)
# adding the object of DBSSubject
nwb_file.add_lab_meta_data(dbs_subject_group) # storage point for custom LMD
```
Now that we have all the required components, we define the main group for DBS to connect them all:
```python
dbs_main_group = DBSGroup(
name='DBS_main_container',
DBS_phase='first phase after implementation recovery',
DBS_device=dbs_device,
DBS_meta=dbs_meta_group,
DBS_subject=dbs_subject_group,
comment='any comments ...',
)
# adding the object of DBSSubject
nwb_file.add_lab_meta_data(dbs_main_group) # storage point for custom LMD
```
Now, the `nwb_file` is ready to be written on the disk and read back.
Raw data
{
"_id": null,
"home_page": null,
"name": "ndx-dbs",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "NeurodataWithoutBorders, NWB, nwb-extension, ndx-extension",
"author": "Hamidreza Alimohammadi ([AT]DefenseCircuitsLab)",
"author_email": "\"Hamidreza Alimohammadi ([AT]DefenseCircuitsLab)\" <alimohammadi.hamidreza@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/17/a9/d0f2b22665548adfcba88a71f714b9ad1e7e56fd1cb2b4644822632fa624/ndx-dbs-0.1.0.tar.gz",
"platform": null,
"description": "# ndx-dbs Extension for NWB\r\n\r\nThis extension is developed to extend NWB data standards to incorporate required (meta)data for DBS experiments. `DBSGroup`, the main neurodata-type in this extension, in fact extends the `LabMetaData` which itself extends the NWBContainer base type and incorporates data types of `DBSMeta`(as an extension of LabMetaData), `DBSSubject`(as an extension of LabMetaData) and `DBSDevice`(as an extension of Device) which itself includes `DBSElectrodes`(as an extension of DynamicTable). Instances of these data types are interlinked to each other to account for the comprehensiveness of all the required meta(data) in a general experiment including DBS.\r\n\r\n<div align=\"center\">\r\n<img src=\"https://github.com/Hamidreza-Alimohammadi/ndx-dbs/assets/63550467/63a919ff-d564-49de-98e7-4893bfc3e43f\" width=\"1000\">\r\n</div>\r\n\r\n## Installation\r\nSimply clone the repo and navigate to the root directory, then:\r\n```\r\npip install .\r\n```\r\n## Test\r\nA roundTrip test is runnable through ```pytest``` from the root. The test script can be found here:\r\n```\r\n\\src\\pynwb\\tests\r\n```\r\n## An example use-case\r\nThe following is an example use case of ```ndx-dbs``` with explanatory comments. First, we build up an ```nwb_file``` and define an endpoint recording device:\r\n```python\r\nfrom datetime import datetime\r\nfrom uuid import uuid4\r\nfrom dateutil.tz import tzlocal\r\nfrom pynwb import NWBHDF5IO, NWBFile\r\n\r\nfrom ndx_dbs import (\r\n DBSDevice,\r\n DBSElectrodes,\r\n DBSMeta,\r\n DBSSubject,\r\n DBSGroup\r\n)\r\n\r\nnwb_file = NWBFile(\r\n session_description='DBS mock session',\r\n identifier=str(uuid4()),\r\n session_start_time=datetime.now(tzlocal()),\r\n experimenter='experimenter',\r\n lab='ChiWangLab',\r\n institution='UKW',\r\n experiment_description='',\r\n session_id='',\r\n)\r\n\r\n# define an endpoint main recording device\r\nmain_device = nwb_file.create_device(\r\n name='endpoint_recording_device',\r\n description='description_of_the_ERD', # ERD: Endpoint recording device\r\n manufacturer='manufacturer_of_the_ERD'\r\n)\r\n```\r\nThen, we define an instance of `DBSElectrodes` to represent the meta-data on the recording electrodes:\r\n```python\r\n'''\r\ncreating an DBS electrodes table\r\nas a DynamicTable\r\n'''\r\ndbs_electrodes_table = DBSElectrodes(\r\n description='descriptive meta-data on DBS stimulus electrodes'\r\n)\r\n\r\n# add electrodes\r\ndbs_electrodes_table.add_row(\r\n el_id='el_0',\r\n polarity='negative electrode (stimulation electrode, cathode)',\r\n impedance='0.8 MOhm',\r\n length='X cm',\r\n tip='tip surface ~ XX micrometer sq',\r\n material='platinum/iridium',\r\n location='STN',\r\n comment='none',\r\n)\r\ndbs_electrodes_table.add_row(\r\n el_id='el_1',\r\n polarity='positive electrode (reference electrode, anode)',\r\n impedance='1 MOhm',\r\n length='Y cm',\r\n tip='tip surface ~ YY micrometer sq',\r\n material='platinum/iridium',\r\n location='scalp surface',\r\n comment='distance D from el_0',\r\n)\r\n# adding the object of DynamicTable\r\nnwb_file.add_acquisition(dbs_electrodes_table) # storage point for DT\r\n```\r\nNow, we can define an instance of ```DBSDevice```:\r\n```python\r\n# define an DBSDevice-type device for ecg recording\r\ndbs_device = DBSDevice(\r\n name='DBS_device',\r\n description='cable-bound multichannel systems stimulus generator; TypeSTG4004',\r\n manufacturer='MultichannelSystems, Reutlingen, Germany',\r\n synchronization='taken care of via ...',\r\n electrodes_group=dbs_electrodes_table,\r\n endpoint_recording_device=main_device\r\n)\r\n# adding the object of DBSDevice\r\nnwb_file.add_device(dbs_device)\r\n```\r\nAnd also an instance of ```DBSMeta``` to store the meta-data for a DBS experiment:\r\n```python\r\ndbs_meta_group = DBSMeta(\r\n name='DBS_meta',\r\n stim_state='ON',\r\n stim_type='unipolar',\r\n stim_area='STN',\r\n stim_coordinates='\u20133.6mmAP, either\u20132.5mm (right) or 12.5mm(left)ML, and\u20137.7mmDV',\r\n pulse_shape='rectangular',\r\n pulse_width='60 micro-seconds',\r\n pulse_frequency='130 Hz',\r\n pulse_intensity='50 micro-Ampere',\r\n charge_balance='pulse symmetric; set to be theoretically zero',\r\n)\r\n# adding the object of DBSMeta\r\nnwb_file.add_lab_meta_data(dbs_meta_group) # storage point for custom LMD\r\n```\r\nAlong with an instance of `DBSSubject`:\r\n```python\r\ndbs_subject_group = DBSSubject(\r\n name='DBS_subject',\r\n model='6-OHDA',\r\n controls='specific control group in this experiment',\r\n comment='any comments on this subject',\r\n)\r\n# adding the object of DBSSubject\r\nnwb_file.add_lab_meta_data(dbs_subject_group) # storage point for custom LMD\r\n```\r\nNow that we have all the required components, we define the main group for DBS to connect them all:\r\n```python\r\ndbs_main_group = DBSGroup(\r\n name='DBS_main_container',\r\n DBS_phase='first phase after implementation recovery',\r\n DBS_device=dbs_device,\r\n DBS_meta=dbs_meta_group,\r\n DBS_subject=dbs_subject_group,\r\n comment='any comments ...',\r\n)\r\n# adding the object of DBSSubject\r\nnwb_file.add_lab_meta_data(dbs_main_group) # storage point for custom LMD\r\n```\r\nNow, the `nwb_file` is ready to be written on the disk and read back. \r\n",
"bugtrack_url": null,
"license": "BSD-3",
"summary": "This extension is developed to extend NWB data standards to incorporate DBS(DeepBrainStimulation) experiments.",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"neurodatawithoutborders",
" nwb",
" nwb-extension",
" ndx-extension"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c40ea2b35832215fe301432bd2fb2c3c3158a8845f522b34b2b1b06be8d860a7",
"md5": "97bd9953e09e6d2ec24199840bbe25cd",
"sha256": "e21f05d693aa5b23ba69640ae80e2582869d89f152160ba054161e45198d575a"
},
"downloads": -1,
"filename": "ndx_dbs-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "97bd9953e09e6d2ec24199840bbe25cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6645,
"upload_time": "2024-05-26T10:32:22",
"upload_time_iso_8601": "2024-05-26T10:32:22.326027Z",
"url": "https://files.pythonhosted.org/packages/c4/0e/a2b35832215fe301432bd2fb2c3c3158a8845f522b34b2b1b06be8d860a7/ndx_dbs-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "17a9d0f2b22665548adfcba88a71f714b9ad1e7e56fd1cb2b4644822632fa624",
"md5": "9502841eea745a6414701904a4552cf3",
"sha256": "35e7d7dd3f36d33e7c38e4dcb39ebce7b7d49604ef56e938476805bbffbdd712"
},
"downloads": -1,
"filename": "ndx-dbs-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "9502841eea745a6414701904a4552cf3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9213,
"upload_time": "2024-05-26T10:32:24",
"upload_time_iso_8601": "2024-05-26T10:32:24.349548Z",
"url": "https://files.pythonhosted.org/packages/17/a9/d0f2b22665548adfcba88a71f714b9ad1e7e56fd1cb2b4644822632fa624/ndx-dbs-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-26 10:32:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ndx-dbs"
}
JSON