Recommend /events as single location for EventsTable; add source attribute (#690)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rly

core/nwb.behavior.yaml

@@ -66,9 +66,17 @@ groups:
 - neurodata_type_def: BehavioralEvents
   neurodata_type_inc: NWBDataInterface
   default_name: BehavioralEvents
-  doc: DEPRECATED. Use an EventsTable instead. 
-    TimeSeries for storing behavioral events. See description of BehavioralEpochs
-    for more details.
+  doc: 'DEPRECATED. Use an `EventsTable` instead, placed in the top-level `/events`
+    group of the `NWBFile`. Each `TimeSeries` formerly stored under
+    `BehavioralEvents` becomes one `EventsTable`. The `timestamps` field maps to
+    the `timestamp` column, and the `data` field maps to an additional column
+    named after the event marker (e.g., `reward_magnitude`, `port_number`); for
+    multi-dimensional `data`, use one column per field. Any other per-event
+    metadata becomes additional columns. Use the `source_description` attribute
+    on the `EventsTable` to record where the events came from (e.g., "Acquisition
+    system", "Thresholding of analog signal ANALOG1 at 3 V", "Manual video
+    review"). Original definition: TimeSeries for storing behavioral events. See
+    description of BehavioralEpochs for more details.'
   groups:
   - neurodata_type_inc: TimeSeries
     doc: TimeSeries object containing behavioral events.

core/nwb.event.yaml

@@ -48,6 +48,10 @@ groups:
     is absent, optional, or mixed across rows. Additional columns may be added to
     store metadata about each event, such as the duration of the event. Examples
     include TTL pulses, licks, rewards, stimulus onsets, and detected ripples.
+    Each `EventsTable` should hold events of a single type, so that all rows share
+    the same set of per-event metadata columns. Events of different types (e.g.,
+    licks and stimulus presentations) should be stored in separate `EventsTable`
+    instances.
   attributes:
   - name: description
     dtype: text
@@ -57,6 +61,18 @@ groups:
       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.
+  - name: source_description
+    dtype: text
+    doc: Optional short text description of where the events came from, applying
+      to every row in the table. For example, "Acquisition system" for events
+      emitted directly by the acquisition system (e.g., TTL edges or hardware
+      event channels); "Thresholding of analog signal ANALOG1 at 3 V" for events
+      produced by a detection algorithm run on acquired data; or "Manual video
+      review" for events added by a human annotator. This is a free-text label of
+      origin only; use `description` for the longer narrative of how the event
+      times were computed (channels used, encoding scheme, algorithm parameters,
+      etc.).
+    required: false
   datasets:
   - name: timestamp
     neurodata_type_inc: TimestampVectorData

core/nwb.file.yaml

@@ -406,17 +406,19 @@ groups:
       doc: Optional additional table(s) for describing other experimental time intervals.
       quantity: '*'
   - name: events
-    doc: Primary experimental event tables for the session, stored as `EventsTable`
-      instances. This location is intended for event data that are ready to be used
-      in downstream analysis. It replaces the deprecated `BehavioralEvents` placement.
-      Events emitted directly by the acquisition system (TTL edges, hardware event
-      channels) belong in `/acquisition/`. Events derived by user processing
-      (filtering, detection algorithms, annotation with experimental context) belong
-      in a `ProcessingModule` under `/processing/`. For periods with required start
-      and stop times, see `/intervals/`. For continuous acquired signals or stimulus
+    doc: Experimental event tables for the session, stored as `EventsTable`
+      instances. This is the recommended location for all event tables in the file,
+      regardless of whether the events were emitted directly by the acquisition
+      system (TTL edges, hardware event channels), derived by user processing
+      (filtering, detection algorithms), or added as post-hoc annotations. The
+      provenance of each table can be recorded in the `source_description`
+      attribute of the `EventsTable` and described in more detail in its
+      `description`. Each
+      `EventsTable` should hold events of a single type (i.e., events sharing the
+      same per-event metadata columns). For periods with required start and stop
+      times, see `/intervals/`. For continuous acquired signals or stimulus
       templates from which events may have been derived, see `/acquisition/` or
-      `/stimulus/`. For more guidance on choosing between `/events/`, `/acquisition/`,
-      `/processing/`, and `/analysis/`, see the schema docs FAQ.
+      `/stimulus/`.
     quantity: '?'
     groups:
     - neurodata_type_inc: EventsTable

core/nwb.misc.yaml

@@ -47,10 +47,15 @@ groups:
 
 - neurodata_type_def: AnnotationSeries
   neurodata_type_inc: TimeSeries
-  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.
+  doc: 'DEPRECATED. Use an `EventsTable` instead, placed in the top-level `/events`
+    group of the `NWBFile`. The `timestamps` field maps to the `timestamp` column,
+    and the `data` field (annotation strings) maps to the `annotation` column on
+    `EventsTable`. Use the `source_description` attribute on the `EventsTable` to
+    record where the annotations came from (e.g., "Manual video review"). Original definition: 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.'
   datasets:
   - name: data
     dtype: text

docs/format/source/format_description.rst

@@ -380,24 +380,25 @@ continuously (e.g., a 30 kHz 0/1 trace of a TTL channel) is a ``TimeSeries``. Ed
 times derived from that trace are an ``EventsTable``. The continuous-vs-edges
 distinction is independent of where the data is stored in the file hierarchy.
 
-*Place EventsTable instances based on how the data was derived.* ``EventsTable`` is
-allowed in multiple groups, mirroring ``TimeSeries`` placement conventions:
-
-- ``/acquisition`` — events emitted directly by the acquisition system (Neuralynx ``.nev``, Open Ephys event channels, TTL edges parsed from a directly-recorded digital line).
-- ``/processing/<module>`` — events derived by user processing: filtering, debouncing, detection algorithms, or events annotated with experimental context.
-- ``/events`` — primary experimental event tables for the session, ready to be used in downstream analysis. The ``BehavioralEvents`` replacement case from NWBEP001.
-- ``/analysis`` — events tied to final scientific analysis.
-
-The ``/events`` versus ``/processing/behavior/`` choice is the most common source of
-confusion. Prefer ``/events`` when the table is a top-level experimental annotation
-ready for downstream analysis. Prefer ``/processing`` when the table is an
-intermediate output consumed by other processing steps.
-
-For the borderline case of edge times derived from a directly-recorded digital line,
-default to ``/acquisition``. Edge detection on a binary line is information-preserving
-— the events are what the acquisition system would have emitted if configured to do
-so. Reserve ``/processing`` for cases involving actual decisions (thresholding analog
-signals, debouncing, filtering, selection).
+*Place all EventsTable instances in /events.* Event tables are organized by data
+modality, not by processing stage. All ``EventsTable`` instances for the session
+go in the top-level ``/events`` group.
+
+Use the optional ``source_description`` attribute on each ``EventsTable`` to record
+where the events came from, as a short human-readable phrase. Examples:
+
+- ``"Acquisition system"``
+- ``"Thresholding of analog signal ANALOG1 at 3 V"``
+- ``"Manual video review"``
+
+Use the longer ``description`` attribute for the narrative of how the event times
+were computed (channels used, encoding scheme, algorithm parameters, etc.).
+
+*Each EventsTable holds events of a single type.* All rows in a given table should
+share the same set of per-event metadata columns. Store events of different types
+(licks vs. stimulus presentations vs. rewards) in separate ``EventsTable``
+instances within ``/events``. APIs may provide helpers to merge tables across
+sources for downstream analysis.
 
 
 Tables and ragged arrays

docs/format/source/format_release_notes.rst

@@ -8,19 +8,19 @@ Release Notes
 
 Major changes
 ^^^^^^^^^^^^^
-- Implemented NWBEP001 -- Added new neurodata types ``EventsTable``, ``TimestampVectorData``, and ``DurationVectorData``.
+- Implemented NWBEP001 -- Added new neurodata types ``EventsTable``, ``TimestampVectorData``, and ``DurationVectorData``. (#645)
 - 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``.
-  Each ``TimeSeries`` formerly stored under ``BehavioralEvents`` becomes one ``EventsTable``: the
-  ``timestamps`` field maps to the ``timestamp`` column, and any per-event metadata becomes
-  additional columns. See the schema docs FAQ for guidance on choosing between ``/events/``,
-  ``/acquisition/``, ``/processing/``, and ``/analysis/``.
-- Deprecated ``AnnotationSeries`` in favor of creating an ``EventsTable`` with an ``annotation``
-  column. The ``timestamps`` field maps to the ``timestamp`` column, and the ``data`` field
-  (annotation strings) maps to the new ``annotation`` column. Event markers from acquisition systems
-  that were previously stored as ``AnnotationSeries`` typically belong in ``/acquisition/`` rather
-  than ``/events/``.
+- Added support for an optional ``HERD`` object at ``/general/external_resources``. (#646)
+- Deprecated ``BehavioralEvents`` and ``AnnotationSeries`` in favor of ``EventsTable``. All
+  ``EventsTable`` instances for a session belong in the top-level ``/events`` group of the
+  ``NWBFile``, regardless of provenance; the optional ``source_description`` attribute on each
+  table captures where the events came from (e.g., ``"Acquisition system"``, ``"Thresholding of
+  analog signal ANALOG1 at 3 V"``, ``"Manual video review"``). For ``BehavioralEvents``:
+  each ``TimeSeries`` formerly stored under ``BehavioralEvents`` becomes one ``EventsTable``,
+  with ``timestamps`` mapping to the ``timestamp`` column and any per-event metadata mapping
+  to additional columns. For ``AnnotationSeries``: ``timestamps`` maps to the ``timestamp``
+  column and ``data`` (annotation strings) maps to the new ``annotation`` column. See the
+  schema docs FAQ for details. (#688, #690)
 
 Minor changes
 ^^^^^^^^^^^^^