Major changes for version 0.3.0

.gitignore

@@ -1,11 +1,8 @@
+# output NWB files
+*.nwb
+
 # generated docs
-docs/_build
 docs/source/_format_auto_docs
-docs/source/_static
-!docs/source/_static/theme_overrides.css
-
-# copied spec files
-src/pynwb/ndx_events/spec/*.yaml
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -29,6 +26,7 @@ parts/
 sdist/
 var/
 wheels/
+share/python-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
@@ -47,14 +45,18 @@ pip-delete-this-directory.txt
 # Unit test / coverage reports
 htmlcov/
 .tox/
+.nox/
 .coverage
 .coverage.*
 .cache
 nosetests.xml
 coverage.xml
 *.cover
+*.py,cover
 .hypothesis/
 .pytest_cache/
+cover/
+.ruff_cache/
 
 # Translations
 *.mo
@@ -64,6 +66,7 @@ coverage.xml
 *.log
 local_settings.py
 db.sqlite3
+db.sqlite3-journal
 
 # Flask stuff:
 instance/
@@ -76,16 +79,49 @@ instance/
 docs/_build/
 
 # PyBuilder
+.pybuilder/
 target/
 
 # Jupyter Notebook
 .ipynb_checkpoints
 
-# pyenv
-.python-version
+# IPython
+profile_default/
+ipython_config.py
 
-# celery beat schedule file
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
 celerybeat-schedule
+celerybeat.pid
 
 # SageMath parsed files
 *.sage.py
@@ -111,6 +147,24 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
 
 # Mac finder
 .DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+# NOTE: run `pre-commit autoupdate` to update hooks to latest version
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+    -   id: check-added-large-files
+    -   id: check-json
+    -   id: check-toml
+    -   id: name-tests-test
+        args: [--pytest-test-first]
+    -   id: check-docstring-first
+-   repo: https://github.com/psf/black
+    rev: 23.12.0
+    hooks:
+    -   id: black
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.8
+    hooks:
+    -   id: ruff
+-   repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+    -   id: codespell
+        additional_dependencies:
+        - tomli

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog for ndx-events
+
+## 0.3.0 (Upcoming)
+
+

LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Ryan Ly
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -2,6 +2,8 @@
 
 This is an NWB extension for storing timestamped event data and TTL pulses.
 
+The latest version is 0.3.0. This is a major change from previous versions.
+
 Events can be:
 1. **Simple events**. These are stored in the `Events` type. The `Events` type consists of only a name, a description,
 and a 1D array of timestamps. This should be used instead of a `TimeSeries` when the time series has no data.
@@ -20,124 +22,47 @@ subtype of `DynamicTable`, where each row corresponds to a different event type.
 Unlike for the other event types, users can add their own custom columns to annotate each event type or event time.
 This can be useful for storing event metadata related to data preprocessing and analysis, such as marking bad events.
 
-This extension was developed by Ryan Ly, Ben Dichter, Oliver Rübel, and Andrew Tritt. Information about the rationale,
-background, and alternative approaches to this extension can be found here:
+This extension was developed by Ryan Ly, Oliver Rübel, and the NWB Technical Advisory Board.
+Information about the rationale, background, and alternative approaches to this extension can be found here:
 https://docs.google.com/document/d/1qcsjyFVX9oI_746RdMoDdmQPu940s0YtDjb1en1Xtdw
 
 ## Installation
-Python:  
-```
-pip install ndx-events
-```
-Matlab:  
+Python:
+```bash
+pip install -U ndx-events
 ```
+
+Matlab:
+```matlab
 generateExtension('<directory path>/ndx-events/spec/ndx-events.namespace.yaml');
 ```
-## Example usage
-Python:  
-```python
-from datetime import datetime
-
-from pynwb import NWBFile, NWBHDF5IO
-from ndx_events import LabeledEvents, AnnotatedEventsTable
-
-
-nwb = NWBFile(
-    session_description='session description',
-    identifier='cool_experiment_001',
-    session_start_time=datetime.now().astimezone()
-)
 
-# create a new LabeledEvents type to hold events recorded from the data acquisition system
-events = LabeledEvents(
-    name='LabeledEvents',
-    description='events from my experiment',
-    timestamps=[0., 0.5, 0.6, 2., 2.05, 3., 3.5, 3.6, 4.],
-    resolution=1e-5,  # resolution of the timestamps, i.e., smallest possible difference between timestamps
-    data=[0, 1, 2, 3, 5, 0, 1, 2, 4],
-    labels=['trial_start', 'cue_onset', 'cue_offset', 'response_left', 'response_right', 'reward']
-)
-
-# add the LabeledEvents type to the acquisition group of the NWB file
-nwb.add_acquisition(events)
-
-# create a new AnnotatedEventsTable type to hold annotated events
-# each row of the table represents a single event type
-annotated_events = AnnotatedEventsTable(
-    name='AnnotatedEventsTable',
-    description='annotated events from my experiment',
-    resolution=1e-5  # resolution of the timestamps, i.e., smallest possible difference between timestamps
-)
-# add a custom indexed (ragged) column to represent whether each event time was a bad event
-annotated_events.add_column(
-    name='bad_event',
-    description='whether each event time should be excluded',
-    index=True
-)
-# add an event type (row) to the AnnotatedEventsTable instance
-annotated_events.add_event_type(
-    label='Reward',
-    event_description='Times when the subject received juice reward.',
-    event_times=[1., 2., 3.],
-    bad_event=[False, False, True],
-    id=3
-)
-# convert the AnnotatedEventsTable to a pandas.DataFrame and print it
-print(annotated_events.to_dataframe())
-
-# create a processing module in the NWB file to hold processed events data
-events_module = nwb.create_processing_module(
-    name='events',
-    description='processed event data'
-)
+## Developer installation
+In a Python 3.8-3.12 environment:
+```bash
+pip install -r requirements-dev.txt
+pip install -e .
+```
 
-# add the AnnotatedEventsTable instance to the processing module
-events_module.add(annotated_events)
+Run tests:
+```bash
+pytest
+```
 
-# write nwb file
-filename = 'test.nwb'
-with NWBHDF5IO(filename, 'w') as io:
-    io.write(nwb)
+Install pre-commit hooks:
+```bash
+pre-commit install
+```
 
-# read nwb file and check its contents
-with NWBHDF5IO(filename, 'r', load_namespaces=True) as io:
-    nwb = io.read()
-    print(nwb)
-    # access the LabeledEvents container by name from the NWBFile acquisition group and print it
-    print(nwb.acquisition['LabeledEvents'])
-    # access the AnnotatedEventsTable by name from the 'events' processing module, convert it to
-    # a pandas.DataFrame, and print that
-    print(nwb.processing['events']['AnnotatedEventsTable'].to_dataframe())
+Style and other checks:
+```bash
+black .
+ruff .
+codespell .
 ```
-Matlab (see discussion [here](https://github.com/NeurodataWithoutBorders/helpdesk/discussions/27#discussioncomment-2612231)):
-```matlab
-bad_event_col = types.hdmf_common.VectorData( ...
-	  'description', 'whether each event time should be excluded', ...
-	  'data', [false, false, true, false, true] ...
-);
-bad_event_col_index = types.hdmf_common.VectorIndex( ...
-	  'description', 'bad_event column index', ...
-	  'target', types.untyped.ObjectView(bad_event_col), ...
-	  'data', [3; 5] ...
-);
-annotated_events = types.ndx_events.AnnotatedEventsTable( ...
-	  'description', 'annotated events from my experiment', ...
-	  'colnames', {'bad_event'}, ...
-	  'bad_event', bad_event_col, ...
-	  'bad_event_index', bad_event_col_index, ...
-	  'id', types.hdmf_common.ElementIdentifiers('data', [0; 1]) ...  % 0-indexed, for compatibility with Python
-);
 
-% place the annotated events table in a "behavior" processing module in the NWB file
-behavior_mod = types.core.ProcessingModule('description', 'processed behavioral data');
-behavior_mod.dynamictable.set('AnnotatedEvents', annotated_events);
+## Example usage
+Python:
 
-nwb = NwbFile( ...
-	  'session_description', 'mouse in open exploration', ...
-	  'identifier', 'Mouse5_Day3', ...
-	  'session_start_time', datetime(2018, 4, 25, 2, 30, 3) ...
-);
 
-nwb.processing.set('behavior', behavior_mod);
-```
 This extension was created using [ndx-template](https://github.com/nwb-extensions/ndx-template).