# ndx-photostim Extension for NWB
<div style="display:inline">
<img src="https://github.com/histedlab/ndx-photostim/blob/main/docs/images/ext.png?raw=True" height="50em" style="margin: 0em 0em 0em 0em;" align="right">
<img src="https://github.com/histedlab/ndx-photostim/blob/main/docs/images/nwb.png?raw=True" height="50em" style="margin: 0em 0em 0em 0em; " align="right">
This is a <a href="https://www.nwb.org/">NeuroData Without Borders (NWB)</a> extension for storing data and metadata from <a href="https://www.nature.com/articles/nmeth.3217">holographic photostimulation</a>
methods. It includes containers for storing photostimulation-specific device parameters, holographic patterns
(either 2D or 3D), and time series data related to photostimulation.
</div>
<br>We release six <a href="https://pynwb.readthedocs.io/en/stable/">PyNWB</a> containers as part of this extension (we currently only have a Python implementation, rather than both Python and a MATLAB ones -- this is why the `matnwb` directory is empty):
* The `SpatialLightModulator` and `Laser` containers store metadata about the spatial light modulator and laser used in the photostimulation, respectively. These containers are then stored within the `PhotostimulationMethod` parent container, which stores the remaining photostimulation method-specifici metadata.
* `HolographicPattern` stores the **holographic pattern** used in stimulation.
* `PhotostimulationSeries` contains the **time series data** corresponding to the presentation of a given stimulus (where the stimulus is represented by a `HolographicPattern` container linked to the `PhotostimulationSeries`).
* We group **all time series & patterns for a given experiment** together using the `PhotostimulationTable` container. This object is a dynamic table, where each row in the table corresponds to a single `PhotostimulationSeries`. Additionally, the table links to the `StimulationDevice` used in the experiment.
## Background
<img src="https://github.com/histedlab/ndx-photostim/blob/main/docs/images/Cap1.PNG?raw=True" width="225em" align="left" style=" margin:0.5em 0.5em 0.5em 0.5em;">
State-of-the-art <a href="https://www.nature.com/articles/s41467-017-01031-3">holographic photostimulation methods</a>, used in concert with <a href="https://www.nature.com/articles/nmeth818">two-photon imaging</a>,
allow unprecedented
control and measurement of cell activity in the living brain. Methods for managing data for two-photon imaging
experiments are improving, but there is little to no standardization of data for holographic stimulation methods.
Stimulation in vivo depends on fine-tuning many experimental variables, which poses a challenge for reproducibility
and data sharing between researchers. To improve <a href="https://www.sciencedirect.com/science/article/pii/S0896627321009557">standardization</a> of photostimulation data storage and processing,
we release this extension as a generic data format for simultaneous holographic stimulation experiments,
using the NWB format to store experimental details and data relating to both acquisition
and photostimulation.
## Installation
To install the extension, first clone the `ndx_photostim` repository to the desired folder using the command
```angular2svg
git clone https://github.com/histedlab/ndx-photostim.git
```
Then, to install the requisite python packages and extension, run:
```angular2svg
python -m pip install -r requirements.txt -r requirements-dev.txt
python setup.py install
```
The extension can then be imported into python scripts via `import ndx_photostim`.
## Usage
**For full example usage, see [tutorial.ipynb](https://github.com/histedlab/ndx-photostim/blob/main/tutorial.ipynb)**
Below is example code to:
1. Create a device used in photostimulation
2. Simulate and store photostimulation ROIs
3. Store the time series corresponding to each stimulation
4. Record all time series and patterns used in an experiment in a table
5. Write the above to an NWB file and read it back
```python
import numpy as np
from dateutil.tz import tzlocal
from datetime import datetime
from pynwb import NWBFile, NWBHDF5IO
from ndx_photostim import SpatialLightModulator, Laser, PhotostimulationMethod, HolographicPattern, \
PhotostimulationSeries, PhotostimulationTable
# create an example NWB file
nwbfile = NWBFile('ndx-photostim_example', 'EXAMPLE_ID', datetime.now(tzlocal()))
# store the spatial light modulator used
slm = SpatialLightModulator(name='slm',
model='Meadowlark',
size=np.array([512, 512]))
# store the laser used
laser = Laser(name='laser',
model='Coherent Monaco',
wavelength=1030,
power=8,
peak_pulse_energy=20,
pulse_rate=500)
# create a container for the method used for photostimulation, and link the SLM and laser to it
ps_method = PhotostimulationMethod(name="methodA",
stimulus_method="scanless",
sweep_pattern="none",
sweep_size=0,
time_per_sweep=0,
num_sweeps=0)
ps_method.add_slm(slm)
ps_method.add_laser(laser)
# define holographic pattern
hp = HolographicPattern(name='pattern1',
image_mask_roi=np.round(np.random.rand(5, 5)),
stim_duration=0.300,
power_per_target=8)
# show the mask
hp.show_mask()
# define stimulation time series using holographic pattern
ps_series = PhotostimulationSeries(name="series_1",
format='interval',
data=[1, -1, 1, -1],
timestamps=[0.5, 1, 2, 4],
pattern=hp,
method=ps_method)
# add the stimulus to the NWB file
nwbfile.add_stimulus(ps_series)
# create a table to store the time series/patterns for all stimuli together, along with experiment-specific
# parameters
stim_table = PhotostimulationTable(name='test', description='...')
stim_table.add_series(ps_series)
# plot the timestamps when the stimulus was presented
stim_table.plot_presentation_times()
# create a processing module and add the PresentationTable to it
module = nwbfile.create_processing_module(name="photostimulation", description="example photostimulation table")
module.add(stim_table)
# write to an NWB file and read it back
with NWBHDF5IO("example_file.nwb", "w") as io:
io.write(nwbfile)
with NWBHDF5IO("example_file.nwb", "r", load_namespaces=True) as io:
read_nwbfile = io.read()
# Check the file & processing module
print(read_nwbfile)
print(read_nwbfile.processing['photostimulation'])
if os.path.exists("example_file.nwb"):
os.remove("example_file.nwb")
```
## Running tests
<a href="https://pynwb.readthedocs.io/en/stable/software_process.html#continuous-integration">Unit and integration
tests</a> are implemented using <a href="https://docs.pytest.org/en/7.2.x/">pytest</a>, and can be run via the command
`pytest` from the root of the extension directory (i.e., inside `ndx-photostim/src`). In addition, the
`pytest` command will also run a test of the example code above.
## Documentation
### Specification
Documentation for the extension's <a href="https://schema-language.readthedocs.io/en/latest/">specification</a>, which is based on the YAML files, is generated and stored in
the `./docs` folder. To create it, run the following from the home directory:
```angular2svg
cd docs
make fulldoc
```
This will save documentation to the `./docs/build` folder, and can be accessed via the
`./docs/build/html/index.html` file.
### API
To generate documentation for the Python API (stores in `./api_docs`), we use <a href="https://www.sphinx-doc.org/en/master/">Sphinx</a>
and a template from <a href="https://readthedocs.org/">ReadTheDocs</a>. API documentation can
be created by running
```angular2svg
sphinx-build -b html api_docs/source/ api_docs/build/
```
from the home folder. Similar to the specification docs, API documentation is stored in `./api_docs/build`. Select
`./api_docs/build/index.html` to access the API documentation in a website format.
## Credit
Code by Carl Harris and Paul LaFosse (equal contribution). Collaboration between the NIMH's [Data Science and Sharing Team](https://cmn.nimh.nih.gov/dsst) and [Histed Lab](https://www.nimh.nih.gov/research/research-conducted-at-nimh/research-areas/clinics-and-labs/ncb).
This extension was created using [ndx-template](https://github.com/nwb-extensions/ndx-template).
Raw data
{
"_id": null,
"home_page": "",
"name": "ndx-photostim",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "NeurodataWithoutBorders,NWB,nwb-extension,ndx-extension",
"author": "Paul LaFosse, Carl Harris",
"author_email": "Paul LaFosse <paul.lafosse@nih.gov>, Carl Harris <carl.harris@nih.gov>, Adam Thomas <adam.thomas@nih.gov>, Mark Histed <mark.histed@nih.gov>",
"download_url": "https://files.pythonhosted.org/packages/95/8b/1ac4fbd18004ad0f4fdfd8ed90f5d67f4272b3eaf4e1499b2f7b330c7e32/ndx-photostim-0.0.4.tar.gz",
"platform": null,
"description": "# ndx-photostim Extension for NWB\n\n<div style=\"display:inline\">\n<img src=\"https://github.com/histedlab/ndx-photostim/blob/main/docs/images/ext.png?raw=True\" height=\"50em\" style=\"margin: 0em 0em 0em 0em;\" align=\"right\">\n<img src=\"https://github.com/histedlab/ndx-photostim/blob/main/docs/images/nwb.png?raw=True\" height=\"50em\" style=\"margin: 0em 0em 0em 0em; \" align=\"right\">\nThis is a <a href=\"https://www.nwb.org/\">NeuroData Without Borders (NWB)</a> extension for storing data and metadata from <a href=\"https://www.nature.com/articles/nmeth.3217\">holographic photostimulation</a>\nmethods. It includes containers for storing photostimulation-specific device parameters, holographic patterns \n(either 2D or 3D), and time series data related to photostimulation.\n</div>\n\n<br>We release six <a href=\"https://pynwb.readthedocs.io/en/stable/\">PyNWB</a> containers as part of this extension (we currently only have a Python implementation, rather than both Python and a MATLAB ones -- this is why the `matnwb` directory is empty):\n\n* The `SpatialLightModulator` and `Laser` containers store metadata about the spatial light modulator and laser used in the photostimulation, respectively. These containers are then stored within the `PhotostimulationMethod` parent container, which stores the remaining photostimulation method-specifici metadata.\n* `HolographicPattern` stores the **holographic pattern** used in stimulation.\n* `PhotostimulationSeries` contains the **time series data** corresponding to the presentation of a given stimulus (where the stimulus is represented by a `HolographicPattern` container linked to the `PhotostimulationSeries`).\n* We group **all time series & patterns for a given experiment** together using the `PhotostimulationTable` container. This object is a dynamic table, where each row in the table corresponds to a single `PhotostimulationSeries`. Additionally, the table links to the `StimulationDevice` used in the experiment.\n\n\n## Background\n\n<img src=\"https://github.com/histedlab/ndx-photostim/blob/main/docs/images/Cap1.PNG?raw=True\" width=\"225em\" align=\"left\" style=\" margin:0.5em 0.5em 0.5em 0.5em;\">\nState-of-the-art <a href=\"https://www.nature.com/articles/s41467-017-01031-3\">holographic photostimulation methods</a>, used in concert with <a href=\"https://www.nature.com/articles/nmeth818\">two-photon imaging</a>, \nallow unprecedented \ncontrol and measurement of cell activity in the living brain. Methods for managing data for two-photon imaging \nexperiments are improving, but there is little to no standardization of data for holographic stimulation methods. \nStimulation in vivo depends on fine-tuning many experimental variables, which poses a challenge for reproducibility \nand data sharing between researchers. To improve <a href=\"https://www.sciencedirect.com/science/article/pii/S0896627321009557\">standardization</a> of photostimulation data storage and processing, \nwe release this extension as a generic data format for simultaneous holographic stimulation experiments, \nusing the NWB format to store experimental details and data relating to both acquisition \nand photostimulation.\n\n## Installation\n\nTo install the extension, first clone the `ndx_photostim` repository to the desired folder using the command\n```angular2svg\ngit clone https://github.com/histedlab/ndx-photostim.git\n```\nThen, to install the requisite python packages and extension, run:\n```angular2svg\npython -m pip install -r requirements.txt -r requirements-dev.txt\npython setup.py install\n```\nThe extension can then be imported into python scripts via `import ndx_photostim`.\n\n## Usage\n\n**For full example usage, see [tutorial.ipynb](https://github.com/histedlab/ndx-photostim/blob/main/tutorial.ipynb)**\n\nBelow is example code to:\n1. Create a device used in photostimulation\n2. Simulate and store photostimulation ROIs\n3. Store the time series corresponding to each stimulation\n4. Record all time series and patterns used in an experiment in a table\n5. Write the above to an NWB file and read it back\n\n\n```python\nimport numpy as np\nfrom dateutil.tz import tzlocal\nfrom datetime import datetime\nfrom pynwb import NWBFile, NWBHDF5IO\nfrom ndx_photostim import SpatialLightModulator, Laser, PhotostimulationMethod, HolographicPattern, \\\n PhotostimulationSeries, PhotostimulationTable\n\n# create an example NWB file\nnwbfile = NWBFile('ndx-photostim_example', 'EXAMPLE_ID', datetime.now(tzlocal()))\n\n# store the spatial light modulator used\nslm = SpatialLightModulator(name='slm',\n model='Meadowlark',\n size=np.array([512, 512]))\n\n# store the laser used\nlaser = Laser(name='laser',\n model='Coherent Monaco',\n wavelength=1030,\n power=8,\n peak_pulse_energy=20,\n pulse_rate=500)\n\n# create a container for the method used for photostimulation, and link the SLM and laser to it\nps_method = PhotostimulationMethod(name=\"methodA\",\n stimulus_method=\"scanless\",\n sweep_pattern=\"none\",\n sweep_size=0,\n time_per_sweep=0,\n num_sweeps=0)\nps_method.add_slm(slm)\nps_method.add_laser(laser)\n\n# define holographic pattern\nhp = HolographicPattern(name='pattern1',\n image_mask_roi=np.round(np.random.rand(5, 5)),\n stim_duration=0.300,\n power_per_target=8)\n\n# show the mask\nhp.show_mask()\n\n# define stimulation time series using holographic pattern\nps_series = PhotostimulationSeries(name=\"series_1\",\n format='interval',\n data=[1, -1, 1, -1],\n timestamps=[0.5, 1, 2, 4],\n pattern=hp,\n method=ps_method)\n\n# add the stimulus to the NWB file\nnwbfile.add_stimulus(ps_series)\n\n# create a table to store the time series/patterns for all stimuli together, along with experiment-specific\n# parameters\nstim_table = PhotostimulationTable(name='test', description='...')\nstim_table.add_series(ps_series)\n\n# plot the timestamps when the stimulus was presented\nstim_table.plot_presentation_times()\n\n# create a processing module and add the PresentationTable to it\nmodule = nwbfile.create_processing_module(name=\"photostimulation\", description=\"example photostimulation table\")\nmodule.add(stim_table)\n\n# write to an NWB file and read it back\nwith NWBHDF5IO(\"example_file.nwb\", \"w\") as io:\n io.write(nwbfile)\n\nwith NWBHDF5IO(\"example_file.nwb\", \"r\", load_namespaces=True) as io:\n read_nwbfile = io.read()\n\n # Check the file & processing module\n print(read_nwbfile)\n print(read_nwbfile.processing['photostimulation'])\n\nif os.path.exists(\"example_file.nwb\"):\n os.remove(\"example_file.nwb\")\n```\n## Running tests\n\n<a href=\"https://pynwb.readthedocs.io/en/stable/software_process.html#continuous-integration\">Unit and integration\ntests</a> are implemented using <a href=\"https://docs.pytest.org/en/7.2.x/\">pytest</a>, and can be run via the command \n`pytest` from the root of the extension directory (i.e., inside `ndx-photostim/src`). In addition, the\n`pytest` command will also run a test of the example code above.\n\n## Documentation\n\n### Specification\n\n\nDocumentation for the extension's <a href=\"https://schema-language.readthedocs.io/en/latest/\">specification</a>, which is based on the YAML files, is generated and stored in\nthe `./docs` folder. To create it, run the following from the home directory:\n```angular2svg\ncd docs\nmake fulldoc\n```\nThis will save documentation to the `./docs/build` folder, and can be accessed via the \n`./docs/build/html/index.html` file.\n\n### API\n\nTo generate documentation for the Python API (stores in `./api_docs`), we use <a href=\"https://www.sphinx-doc.org/en/master/\">Sphinx</a> \nand a template from <a href=\"https://readthedocs.org/\">ReadTheDocs</a>. API documentation can\nbe created by running \n```angular2svg\nsphinx-build -b html api_docs/source/ api_docs/build/\n```\nfrom the home folder. Similar to the specification docs, API documentation is stored in `./api_docs/build`. Select \n`./api_docs/build/index.html` to access the API documentation in a website format.\n\n\n## Credit\n\nCode by Carl Harris and Paul LaFosse (equal contribution). Collaboration between the NIMH's [Data Science and Sharing Team](https://cmn.nimh.nih.gov/dsst) and [Histed Lab](https://www.nimh.nih.gov/research/research-conducted-at-nimh/research-areas/clinics-and-labs/ncb).\n\n\nThis extension was created using [ndx-template](https://github.com/nwb-extensions/ndx-template).\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Holographic photostimulation extension to NWB standard",
"version": "0.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/histedlab/ndx-photostim/issues",
"Homepage": "https://github.com/histedlab/ndx-photostim"
},
"split_keywords": [
"neurodatawithoutborders",
"nwb",
"nwb-extension",
"ndx-extension"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6cf20ff9f333993c5cb2427c7586a157a26f88a7f11fc4c8389963c4cd87282f",
"md5": "15b90a5abec5ca19f6178c2b52bff5e0",
"sha256": "34a14a43de429138d559c185ea9e5eb8427585b9e69022b036f765047e5423d1"
},
"downloads": -1,
"filename": "ndx_photostim-0.0.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "15b90a5abec5ca19f6178c2b52bff5e0",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 15272,
"upload_time": "2024-03-01T11:30:32",
"upload_time_iso_8601": "2024-03-01T11:30:32.071789Z",
"url": "https://files.pythonhosted.org/packages/6c/f2/0ff9f333993c5cb2427c7586a157a26f88a7f11fc4c8389963c4cd87282f/ndx_photostim-0.0.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "958b1ac4fbd18004ad0f4fdfd8ed90f5d67f4272b3eaf4e1499b2f7b330c7e32",
"md5": "4cd99ff8304f08e8fcb34729759442bd",
"sha256": "f705c17d6793d433472f1ea3b76bf8c530a40d47743f970bed9edf794e42bd06"
},
"downloads": -1,
"filename": "ndx-photostim-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "4cd99ff8304f08e8fcb34729759442bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 28796,
"upload_time": "2024-03-01T11:30:33",
"upload_time_iso_8601": "2024-03-01T11:30:33.893061Z",
"url": "https://files.pythonhosted.org/packages/95/8b/1ac4fbd18004ad0f4fdfd8ed90f5d67f4272b3eaf4e1499b2f7b330c7e32/ndx-photostim-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-01 11:30:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "histedlab",
"github_project": "ndx-photostim",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "ndx-photostim"
}
JSON
