diff --git a/core/nwb.base.yaml b/core/nwb.base.yaml index ce0a3fa0..090715ec 100644 --- a/core/nwb.base.yaml +++ b/core/nwb.base.yaml @@ -188,6 +188,8 @@ groups: "step" because the picture remains the same until the next timepoint. This field is optional, but is useful in providing information about the underlying data. It may inform the way this data is interpreted, the way it is visualized, and what analysis methods are applicable. + Use of "instantaneous" in this field is DEPRECATED. Use an EventsTable to store + instantaneous event information instead. required: false - name: starting_time dtype: float64 diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index 5e4e2bad..668fbf4c 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -66,7 +66,8 @@ groups: - neurodata_type_def: BehavioralEvents neurodata_type_inc: NWBDataInterface default_name: BehavioralEvents - doc: TimeSeries for storing behavioral events. See description of BehavioralEpochs + doc: DEPRECATED. Use an EventsTable instead. + TimeSeries for storing behavioral events. See description of BehavioralEpochs for more details. groups: - neurodata_type_inc: TimeSeries diff --git a/core/nwb.event.yaml b/core/nwb.event.yaml new file mode 100644 index 00000000..63f5d13c --- /dev/null +++ b/core/nwb.event.yaml @@ -0,0 +1,133 @@ +datasets: +- neurodata_type_def: TimestampVectorData + neurodata_type_inc: VectorData + dtype: float + dims: + - num_times + shape: + - null + doc: A 1-dimensional VectorData that stores timestamps in seconds. + attributes: + - name: unit + dtype: text + value: seconds + doc: The unit of measurement for the timestamps, fixed to 'seconds'. + - name: resolution + dtype: float + doc: The smallest possible difference between two timestamps. Usually 1 divided + by the sampling rate for timestamps of the data acquisition system. + required: false + +- neurodata_type_def: DurationVectorData + neurodata_type_inc: VectorData + dtype: float + dims: + - num_events + shape: + - null + doc: A 1-dimensional VectorData that stores durations in seconds. + attributes: + - name: unit + dtype: text + value: seconds + doc: The unit of measurement for the durations, fixed to 'seconds'. + - name: resolution + dtype: float + doc: The smallest possible difference between two timestamps. Usually 1 divided + by the sampling rate for timestamps of the data acquisition system. + required: false + +- neurodata_type_def: CategoricalVectorData + neurodata_type_inc: VectorData + dims: + - num_events + shape: + - null + doc: A 1-dimensional VectorData that stores categorical data of any type. This is + an experimental type. + attributes: + - name: meanings + dtype: + target_type: MeaningsTable + reftype: object + doc: The MeaningsTable object that provides the meanings of the values in this + CategoricalVectorData object. + - name: filter_values + dtype: text + dims: + - num_events + shape: + - null + doc: Optional dataset containing possible values in the parent data that represent + missing or invalid values that should be filtered out during analysis. Currently, + only string values are allowed. For example, the filter values may contain the + values "undefined" or "None" to signal that those values in the data are missing + or invalid. + required: false + +groups: +- neurodata_type_def: MeaningsTable + neurodata_type_inc: DynamicTable + doc: A table to store information about the meanings of categorical data. Intended + to be used as a lookup table for the meanings of values in a CategoricalVectorData + object. All possible values of the parent CategoricalVectorData object should + be present in the 'value' column of this table, even if the value is not observed + in the data. Additional columns may be added to store additional metadata about + each value. + datasets: + - name: value + neurodata_type_inc: VectorData + doc: The value of a row in the parent CategoricalVectorData object. + - name: meaning + neurodata_type_inc: VectorData + dtype: text + doc: The meaning of the value in the parent CategoricalVectorData object. + +- neurodata_type_def: EventsTable + neurodata_type_inc: DynamicTable + doc: A column-based table to store information about events (event instances), one + event per row. Additional columns may be added to store metadata about each event, + such as the duration of the event. + attributes: + - name: description + dtype: text + doc: A description of the events stored in the table, including information about + how the event times were computed, especially if the times are the result of + processing or filtering raw data. For example, if the experimenter is encoding + different types of events using a strobed or N-bit encoding, then the description + should describe which channels were used and how the event time is computed, + e.g., as the rise time of the first bit. + datasets: + - name: timestamp + neurodata_type_inc: TimestampVectorData + doc: Column containing the time that each event occurred, in seconds, from the + session start time. + - name: duration + neurodata_type_inc: DurationVectorData + doc: Optional column containing the duration of each event, in seconds. A value + of NaN can be used for events without a duration or with a duration that is + not yet specified. + quantity: '?' + groups: + - neurodata_type_inc: MeaningsTable + doc: Lookup tables for the meanings of the values in any CategoricalVectorData + columns. The name of the table should be the name of the corresponding CategoricalVectorData + column followed by "_meanings". + quantity: '*' + +- neurodata_type_def: AnnotationsTable + neurodata_type_inc: EventsTable + doc: A column-based table to store user annotations about events, one event per row. + If annotations come from a fixed set of values (aka controlled vocabulary or enumeration), + make the "annotation" column a CategoricalVectorData and add a MeaningsTable named + "annotation_meanings" to specify the meanings of the fixed set of values in the + "annotation" column. + datasets: + - name: annotation + neurodata_type_inc: VectorData + doc: Column containing the freeform text annotation. + dtype: text + dims: + - num_times + shape: + - null diff --git a/core/nwb.file.yaml b/core/nwb.file.yaml index a751315d..3dc04f9e 100644 --- a/core/nwb.file.yaml +++ b/core/nwb.file.yaml @@ -7,7 +7,7 @@ groups: attributes: - name: nwb_version dtype: text - value: "2.9.0" + value: "2.10.0-alpha" 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: @@ -400,6 +400,12 @@ groups: - neurodata_type_inc: TimeIntervals doc: Optional additional table(s) for describing other experimental time intervals. quantity: '*' + - name: events + doc: Events that occurred during the session. + groups: + - neurodata_type_inc: EventsTable + doc: Events that occurred during the session. + quantity: '*' - name: units neurodata_type_inc: Units doc: Data about sorted spike units. diff --git a/core/nwb.misc.yaml b/core/nwb.misc.yaml index 2d01fa82..b959596b 100644 --- a/core/nwb.misc.yaml +++ b/core/nwb.misc.yaml @@ -47,7 +47,7 @@ groups: - neurodata_type_def: AnnotationSeries neurodata_type_inc: TimeSeries - doc: Stores user annotations made during an experiment. The data[] + doc: DEPRECATED. Use an AnnotationsTable instead. Stores user annotations made during an experiment. The data[] field stores a text array, and timestamps are stored for each annotation (ie, interval=1). This is largely an alias to a standard TimeSeries storing a text array but that is identifiable as storing annotations in a machine-readable way. diff --git a/core/nwb.namespace.yaml b/core/nwb.namespace.yaml index 784ed44a..149cda7f 100644 --- a/core/nwb.namespace.yaml +++ b/core/nwb.namespace.yaml @@ -28,6 +28,9 @@ namespaces: - doc: This source module contains neurodata_types for epoch data. source: nwb.epoch.yaml title: Epochs + - doc: This source module contains neurodata_types for event data. + source: nwb.event.yaml + title: Events - doc: This source module contains neurodata_types for image data. source: nwb.image.yaml title: Image data @@ -57,4 +60,4 @@ namespaces: - doc: This source module contains neurodata_type for retinotopy data. source: nwb.retinotopy.yaml title: Retinotopy - version: "2.9.0" + version: "2.10.0" diff --git a/docs/format/source/conf.py b/docs/format/source/conf.py index 1675b0c9..f5196e95 100644 --- a/docs/format/source/conf.py +++ b/docs/format/source/conf.py @@ -83,9 +83,9 @@ def setup(app): # built documents. # # The short X.Y version. -version = '2.9.0' +version = '2.10.0' # The full version, including alpha/beta/rc tags. -release = '2.9.0' +release = '2.10.0-alpha' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst index 237afe2c..e40497e1 100644 --- a/docs/format/source/format_release_notes.rst +++ b/docs/format/source/format_release_notes.rst @@ -3,6 +3,15 @@ Release Notes ============= +2.10.0 (Upcoming) +----------------- + +Major changes +^^^^^^^^^^^^^ +- Implemented NWBEP001 -- Added new neurodata types ``EventsTable``, ``AnnotationsTable``, ``TimestampsVectorData``, ``DurationVectorData``, ``CategoricalVectorData``, and ``MeaningsTable``. +- Deprecated the use of "instantaneous" for ``TimeSeries/data.continuity``. +- Deprecated ``BehavioralEvents`` in favor of placing ``EventsTable`` tables in ``NWBFile/events``. + 2.9.0 (June 26, 2025) ---------------------