nwb-extensions/ndx-template

About

This repo provides a template for creating Neurodata Extensions (NDX) for the Neurodata Without Borders data standard.

This template currently supports creating Neurodata Extensions only using Python 3.8+. MATLAB support is in development.

Getting started

Install Python for your operating system if it is not already installed.
Install cookiecutter, pynwb, and hdmf-docutils. cookiecutter is a Python-based command-line utility that creates projects from templates.
```
python -m pip install -U cookiecutter pynwb hdmf-docutils
```
Run cookiecutter in the directory where you want to create a new directory with the extension:
```
cookiecutter gh:nwb-extensions/ndx-template
```
To overwrite the contents of an existing directory, use the --overwrite-if-exists flag:
```
cookiecutter --overwrite-if-exists gh:nwb-extensions/ndx-template
```
This can be useful if you want to populate an existing empty git repository with a new extension.
Answer the prompts, which will be used to fill in the blanks throughout the template automatically. Guidelines:
- Select a name for your extension. It must start with 'ndx-' - The name of the namespace for your extension. This could be a description of the extension (e.g., "ndx-cortical-surface") or the name of your lab or group (e.g., "ndx-allen-institute"). The name should generally follow the following naming conventions:
  - Use only lower-case ASCII letters (no special characters)
  - Use "-" to separate different parts of the name (no spaces allowed)
  - Be short and descriptive
- Select an initial version string - Version of your extension. Versioning should start at 0.1.0 and follow semantic versioning guidelines
- Select a license - Name of license used for your extension source code. A permissive license, such as BSD, should be used if possible.
A new folder with the same name as your entered namespace will be created. See NEXTSTEPS.md in that folder for the next steps in creating your awesome new Neurodata Extension.

In case cookiecutter runs into problems and you want to avoid reentering all the information, you can edit the file ~/.cookiecutter_replay/ndx-template.json, and use that via cookiecutter --replay gh:nwb-extensions/ndx-template.

See the PyNWB tutorial for guidance on how to write your extension.

When you are done creating your extension, we encourage you to follow the steps to publish your Neurodata Extension in the NDX Catalog for the benefit of the greater neuroscience community! :)

Running tests with breakpoint debugging

By default, to aid with debugging, the project is configured NOT to run code coverage as part of the tests. Code coverage testing is useful to help with creation of tests and report test coverage. However, with this option enabled, breakpoints for debugging with pdb are being ignored. To enable this option for code coverage reporting, uncomment out the following line in your pyproject.toml:

ndx-template/{{ cookiecutter.namespace }}/pyproject.toml

Lines 82 to 83 in 11ae225

    
           # uncomment below to run pytest with code coverage reporting. NOTE: breakpoints may not work 
        
           # addopts = "--cov --cov-report html"

Integrating with NWB Widgets

When answering the cookiecutter prompts, you will be asked whether you would like to create templates for integration with NWB Widgets, a library of plotting widgets for interactive visualization of NWB neurodata types within a Jupyter notebook. If you answer "yes", then an example widget and example notebook will be created for you. If you answer "no", but would like to add a widget later on, follow the instructions below:

Create a directory named widgets in src/pynwb/{your_python_package_name}/.
Copy __init__.py to that directory and adapt the contents to your extension.
Copy tetrode_series_widget.py to that directory and adapt the contents to your extension.
Create a directory named notebooks in the root of the repository.
Copy example.ipynb to that directory and adapt the contents to your extension.
Add nwbwidgets to requirements-dev.txt.

Maintainers

Copyright

Neurodata Extensions Catalog (NDX Catalog) Copyright (c) 2021-2024, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.

If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov.

NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit others to do so.

	# uncomment below to run pytest with code coverage reporting. NOTE: breakpoints may not work
	# addopts = "--cov --cov-report html"