diff --git a/core/nwb.base.yaml b/core/nwb.base.yaml index ce0a3fa0..81b72f4a 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. + For storing instantaneous event information, it is recommended to use an EventsTable + instead of a TimeSeries with continuity set to "instantaneous". 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..6bc2c239 --- /dev/null +++ b/core/nwb.event.yaml @@ -0,0 +1,77 @@ +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 from the + session start time. Timestamp are not required to be sorted in time. + attributes: + - name: unit + dtype: text + value: seconds + doc: The unit of measurement for the timestamps, fixed to 'seconds'. + - name: resolution + dtype: float + doc: The temporal resolution of the timestamps, in seconds. This is typically the sampling period + (1 / sampling_rate), also known as the clock period, of the data acquisition system from which the + timestamps were recorded or derived. + required: false + +- neurodata_type_def: DurationVectorData + neurodata_type_inc: VectorData + dtype: float + dims: + - num_times + 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 temporal resolution of the durations, in seconds. This is typically the sampling period + (1 / sampling_rate), also known as the clock period, of the data acquisition system from which the + durations were recorded or derived. + required: false + +groups: +- 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: '?' + - name: annotation + neurodata_type_inc: VectorData + doc: Column containing user annotations about events. + dtype: text + dims: + - num_times + shape: + - null + quantity: '?' diff --git a/core/nwb.file.yaml b/core/nwb.file.yaml index 2d74de37..4f56d018 100644 --- a/core/nwb.file.yaml +++ b/core/nwb.file.yaml @@ -404,6 +404,13 @@ 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. + quantity: '?' + 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 83db43c8..5a7b5f3f 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 EventsTable 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 1c02691e..62627097 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 diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst index 14d129e5..2c885e0c 100644 --- a/docs/format/source/format_release_notes.rst +++ b/docs/format/source/format_release_notes.rst @@ -4,11 +4,15 @@ Release Notes ============= 2.10.0 (Upcoming) ---------------------- +----------------- Major changes ^^^^^^^^^^^^^ +- Implemented NWBEP001 -- Added new neurodata types ``EventsTable``, ``TimestampVectorData``, and ``DurationVectorData``. +- Incorporated HDMF Common Schema 1.9.0 which added new data types ``MeaningsTable`` and support for ``MeaningsTable`` in ``DynamicTable``. - Added support for an optional ``HERD`` object at ``/general/external_resources``. +- Deprecated ``BehavioralEvents`` in favor of placing ``EventsTable`` tables in ``NWBFile/events``. +- Deprecated ``AnnotationSeries`` in favor of creating an ``EventsTable`` with an ``annotation`` column. Minor changes ^^^^^^^^^^^^^