Merge branch 'dev' into nwbep001

Author: rly

Legal.txt

@@ -1,4 +1,4 @@
-“nwb-schema” Copyright (c) 2017-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.
+“nwb-schema” Copyright (c) 2017-2025, 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 Innovation & Partnerships Office at [email protected].
 

README.rst

@@ -3,7 +3,7 @@ NWB Schema Format
 
 A format specification schema for the Neurodata Without Borders (NWB) data format.
 
-To get started using NWB, please go to the `NWB overview website <https://nwb-overview.readthedocs.io/en/latest/>`_.
+To get started using NWB, please go to `nwb.org <https://nwb.org>`_.
 
 This repo contains:
 
@@ -27,7 +27,7 @@ The NWB 1.0 format and API are archived in the `NeurodataWithoutBorders/api-pyth
 License
 ========================
 
-“nwb-schema” Copyright (c) 2017-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.
+“nwb-schema” Copyright (c) 2017-2025, 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.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 
@@ -45,7 +45,7 @@ You are under no obligation whatsoever to provide any bug fixes, patches, or upg
 Copyright
 ========================
 
-“nwb-schema” Copyright (c) 2017-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.
+“nwb-schema” Copyright (c) 2017-2025, 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 Innovation & Partnerships Office at [email protected].
 

core/nwb.device.yaml

@@ -1,7 +1,8 @@
 groups:
 - neurodata_type_def: Device
   neurodata_type_inc: NWBContainer
-  doc: Metadata about a data acquisition device, e.g., recording system, electrode, microscope.
+  doc: Metadata about a specific instance of a data acquisition device, e.g., recording system, electrode, microscope.
+    Link to a DeviceModel.model to represent information about the model of the device.
   attributes:
   - name: description
     dtype: text
@@ -10,17 +11,48 @@ groups:
     required: false
   - name: manufacturer
     dtype: text
-    doc: The name of the manufacturer of the device, e.g., Imec, Plexon, Thorlabs.
+    doc: DEPRECATED. The name of the manufacturer of the device, e.g., Imec, Plexon, Thorlabs.
+      Instead of using this field, store the value in DeviceModel.manufacturer and link to that 
+      DeviceModel from this Device. 
     required: false
   - name: model_number
     dtype: text
-    doc: The model number (or part/product number) of the device, e.g., PRB_1_4_0480_1, PLX-VP-32-15SE(75)-(260-80)(460-10)-300-(1)CON/32m-V, BERGAMO.
+    doc: DEPRECATED. The model number (or part/product number) of the device, e.g., PRB_1_4_0480_1, 
+      PLX-VP-32-15SE(75)-(260-80)(460-10)-300-(1)CON/32m-V, BERGAMO.
+      Instead of using this field, store the value in DeviceModel.model_number and link to that 
+      DeviceModel from this Device. 
     required: false
   - name: model_name
     dtype: text
-    doc: The model name of the device, e.g., Neuropixels 1.0, V-Probe, Bergamo III.
+    doc: DEPRECATED. The model name of the device, e.g., Neuropixels 1.0, V-Probe, Bergamo III.
+      Instead of using this field, create and add a new DeviceModel named the model name and 
+      link to that DeviceModel from this Device.
     required: false
   - name: serial_number
     dtype: text
     doc: The serial number of the device.
     required: false
+  links:
+  - name: model
+    target_type: DeviceModel
+    doc: The model of the device.
+    quantity: '?'
+- neurodata_type_def: DeviceModel
+  neurodata_type_inc: NWBContainer
+  doc: Model properties of a data acquisition device, e.g., recording system, electrode, microscope.
+    This should be extended for specific types of device models to include additional attributes specific to each type.
+    The name of the DeviceModel should be the most common representation of the model name, e.g.,
+    Neuropixels 1.0, V-Probe, Bergamo III.
+  attributes:
+  - name: manufacturer
+    dtype: text
+    doc: The name of the manufacturer of the device model, e.g., Imec, Plexon, Thorlabs.
+  - name: model_number
+    dtype: text
+    doc: The model number (or part/product number) of the device, e.g., PRB_1_4_0480_1, 
+      PLX-VP-32-15SE(75)-(260-80)(460-10)-300-(1)CON/32m-V, BERGAMO.
+    required: false
+  - name: description
+    dtype: text
+    doc: Description of the device model as free-form text.
+    required: false

core/nwb.ecephys.yaml

@@ -104,6 +104,7 @@ groups:
       common experiment master-clock stored in NWBFile.timestamps_reference_time.
       Timestamps are required for the events. Unlike for TimeSeries, timestamps are
       required for SpikeEventSeries and are thus re-specified here.
+    quantity: 1
     attributes:
     - name: interval
       dtype: int32
@@ -161,25 +162,30 @@ groups:
   - name: source_idx
     dtype: int32
     dims:
-    - num_events
+    - - num_events
+    - - num_events
+      - time_index, channel_index
     shape:
-    - null
-    doc: Indices (zero-based) into source ElectricalSeries::data array corresponding
-      to time of event. ''description'' should define what is meant by time of
-      event (e.g., .25 ms before action potential peak, zero-crossing time, etc).
+    - - null
+    - - null
+      - 2
+    doc: Indices (zero-based) into the linked source ElectricalSeries::data array corresponding
+      to time of event or time and channel of event. ''description'' should define what is meant
+      by time of event (e.g., .25 ms before action potential peak, zero-crossing time, etc).
       The index points to each event from the raw data.
   - name: times
     dtype: float64
     dims:
     - num_events
     shape:
     - null
-    doc: Timestamps of events, in seconds.
+    doc: DEPRECATED. Timestamps of events, in seconds.
     attributes:
     - name: unit
       dtype: text
       value: seconds
       doc: Unit of measurement for event times, which is fixed to 'seconds'.
+    quantity: '?'
   links:
   - name: source_electricalseries
     target_type: ElectricalSeries

core/nwb.file.yaml

@@ -7,7 +7,7 @@ groups:
   attributes:
   - name: nwb_version
     dtype: text
-    value: "2.9.0-alpha"
+    value: "2.9.0"
     doc: File version string. Use semantic versioning, e.g. 1.2.1. This will be the
       name of the format with trailing major, minor and patch numbers.
   datasets:
@@ -280,6 +280,13 @@ groups:
       - neurodata_type_inc: Device
         doc: Data acquisition devices.
         quantity: '*'
+      - name: models
+        doc: Collection of data acquisition device models.
+        quantity: '?'
+        groups:
+        - neurodata_type_inc: DeviceModel
+          doc: Data acquisition device models.
+          quantity: '*'
     - name: subject
       neurodata_type_inc: Subject
       doc: Information about the animal or person from which the data was measured.

core/nwb.image.yaml

@@ -177,13 +177,20 @@ groups:
 
 - neurodata_type_def: IndexSeries
   neurodata_type_inc: TimeSeries
-  doc: Stores indices to image frames stored in an ImageSeries. The purpose of the
-    IndexSeries is to allow a static image stack to be stored in an Images
-    object, and the images in the stack to be referenced out-of-order. This can be for
-    the display of individual images, or of movie segments (as a movie is simply a
-    series of images). The data field stores the index of the frame in the referenced
-    Images object, and the timestamps array indicates when that image
-    was displayed.
+  doc: Stores indices that reference images defined in other containers. The primary purpose
+    of the IndexSeries is to allow images stored in an Images container to be referenced in a 
+    specific sequence through the 'indexed_images' link. This approach avoids duplicating image data
+    when the same image needs to be presented multiple times or when images need to be shown in a
+    different order than they are stored. Since images in an Images container do not have an inherent 
+    order, the Images container needs to include an 'order_of_images' dataset (of type 
+    ImageReferences) when being referenced by an IndexSeries. This dataset establishes the ordered 
+    sequence that the indices in IndexSeries refer to. The 'data' field stores the index into this 
+    ordered sequence, and the 'timestamps' array indicates the precise presentation time of each 
+    indexed image during an experiment. This can be used for displaying individual images or creating 
+    movie segments by referencing a sequence of images with the appropriate timestamps. While 
+    IndexSeries can also reference frames from an ImageSeries through the 'indexed_timeseries' link, 
+    this usage is discouraged and will be deprecated in favor of using Images containers with 
+    'order_of_images'.
   datasets:
   - name: data
     dtype: uint32

core/nwb.namespace.yaml

@@ -60,4 +60,4 @@ namespaces:
   - doc: This source module contains neurodata_type for retinotopy data.
     source: nwb.retinotopy.yaml
     title: Retinotopy
-  version: "2.9.0-alpha"
+  version: "2.9.0"

core/nwb.ophys.yaml

@@ -125,6 +125,7 @@ groups:
 - neurodata_type_def: PlaneSegmentation
   neurodata_type_inc: DynamicTable
   doc: Results from image segmentation of a specific imaging plane.
+    At least one of `image_mask`, `pixel_mask`, or `voxel_mask` is required.
   datasets:
   - name: image_mask
     neurodata_type_inc: VectorData
@@ -146,6 +147,7 @@ groups:
       - null
     doc: ROI masks for each ROI. Each image mask is the size of the original imaging
       plane (or volume) and members of the ROI are finite non-zero.
+      At least one of `image_mask`, `pixel_mask`, or `voxel_mask` is required.
     quantity: '?'
   - name: pixel_mask_index
     neurodata_type_inc: VectorIndex
@@ -164,7 +166,8 @@ groups:
       dtype: float32
       doc: Weight of the pixel.
     doc: 'Pixel masks for each ROI: a list of indices and weights for the ROI. Pixel
-      masks are concatenated and parsing of this dataset is maintained by the PlaneSegmentation'
+      masks are concatenated and parsing of this dataset is maintained by the PlaneSegmentation.
+      At least one of `image_mask`, `pixel_mask`, or `voxel_mask` is required.'
     quantity: '?'
   - name: voxel_mask_index
     neurodata_type_inc: VectorIndex
@@ -186,7 +189,8 @@ groups:
       dtype: float32
       doc: Weight of the voxel.
     doc: 'Voxel masks for each ROI: a list of indices and weights for the ROI. Voxel
-      masks are concatenated and parsing of this dataset is maintained by the PlaneSegmentation'
+      masks are concatenated and parsing of this dataset is maintained by the PlaneSegmentation.
+      At least one of `image_mask`, `pixel_mask`, or `voxel_mask` is required.'
     quantity: '?'
   groups:
   - name: reference_images

docs/format/Readme.md

@@ -4,7 +4,7 @@ The NWB specification documentation uses Sphinx [https://www.sphinx-doc.org/en/s
 
 **Prerequisites**
 
-```pip install hdmf-docutils```
+```pip install ../../requirements-doc.txt```
 
 **Rebuilding All**
 

docs/format/source/conf.py

@@ -76,7 +76,7 @@ def setup(app):
 
 # General information about the project.
 project = u'NWB Format Specification'
-copyright = u'2017-2024, Neurodata Without Borders'
+copyright = u'2017-2025, Neurodata Without Borders'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -85,7 +85,7 @@ def setup(app):
 # The short X.Y version.
 version = '2.9.0'
 # The full version, including alpha/beta/rc tags.
-release = '2.9.0-alpha'
+release = '2.9.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.