Clarify TimeIntervals/EventsTable docs and routing (#688)

* Clarify time-anchored data storage: TimeIntervals, EventsTable, and /events placement

Fixes #686 and #687.

- Harmonize /intervals/* group docstrings (epochs, trials).
- Rewrite TimeIntervals and EventsTable type docstrings to describe
  the type and give a usable decision rule, rather than restating
  historical use.
- Replace the placeholder docstring on the /events group and its
  inner EventsTable slot.
- Add a FAQ entry to format_description.rst covering: trials-table
  convention; TimeIntervals vs EventsTable; TimeSeries vs EventsTable
  for digital lines; EventsTable placement (/acquisition, /processing,
  /events, /analysis); /events vs /processing/behavior disambiguation;
  borderline edge-times case.
- Expand BehavioralEvents and AnnotationSeries deprecation entries
  in the 2.10.0 release notes with field-level migration guidance.

* Update format_release_notes.rst

Author: rly

core/nwb.epoch.yaml

@@ -1,8 +1,12 @@
 groups:
 - neurodata_type_def: TimeIntervals
   neurodata_type_inc: DynamicTable
-  doc: A container for aggregating epoch data and the TimeSeries that each epoch applies
-    to.
+  doc: A column-based table to store information about time intervals, one interval
+    per row. Use `TimeIntervals` when each row naturally has a start and stop time
+    and represents a contiguous period of time, often encompassing an experimental
+    condition. Rows can optionally reference `TimeSeries` data via the `timeseries`
+    column. Examples include trials, epochs, behavioral states (e.g., "running",
+    "resting"), and invalid recording windows.
   datasets:
   - name: start_time
     neurodata_type_inc: VectorData

core/nwb.event.yaml

@@ -43,9 +43,11 @@ datasets:
 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.
+  doc: A column-based table to store information about events, one event per row.
+    Use `EventsTable` when each row is anchored at a single timestamp and duration
+    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.
   attributes:
   - name: description
     dtype: text

core/nwb.file.yaml

@@ -390,12 +390,13 @@ groups:
     groups:
     - name: epochs
       neurodata_type_inc: TimeIntervals
-      doc: Divisions in time marking experimental stages or sub-divisions of a single
-        recording session.
+      doc: Time intervals marking coarse-grained experimental phases or subdivisions
+        of a recording session, such as baseline, task, rest, or sleep stages.
       quantity: '?'
     - name: trials
       neurodata_type_inc: TimeIntervals
-      doc: Repeated experimental events that have a logical grouping.
+      doc: Time intervals corresponding to repeated experimental units with consistent
+        structure, such as individual stimulus-response-reward cycles.
       quantity: '?'
     - name: invalid_times
       neurodata_type_inc: TimeIntervals
@@ -405,11 +406,23 @@ groups:
       doc: Optional additional table(s) for describing other experimental time intervals.
       quantity: '*'
   - name: events
-    doc: Events that occurred during the session.
+    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
+      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.
     quantity: '?'
     groups:
     - neurodata_type_inc: EventsTable
-      doc: Events that occurred during the session.
+      doc: An EventsTable holding a collection of event times of a particular type
+        (e.g., licks, rewards, stimulus presentations) along with their per-event
+        metadata.
       quantity: '*'
   - name: units
     neurodata_type_inc: Units

docs/format/source/format_description.rst

@@ -347,6 +347,58 @@ time series, such as if timeseries A and timeseries B, each having
 different data (or time) share time (or data). This is much more
 important information as it shows structural associations in the data.
 
+**How should I store events, intervals, and other time-anchored experimental annotations?**
+
+NWB provides several ways to annotate time-anchored experimental data. The right
+choice depends on the structure of the experiment and the shape of the annotations.
+
+*Start with trial structure.* In trial-based experiments, most per-event annotations
+(stimulus onsets, stimulus IDs, response times, reward times, etc.) belong as columns
+of ``/intervals/trials``, not as separate ``EventsTable`` instances. The trials table
+is the organizing unit, and ``DynamicTable``'s sparse-column support is designed
+for metadata where some trials have a value and others do not.
+
+*Use TimeIntervals for period-shaped annotations.* When each row naturally has a
+start and stop time and represents a contiguous period of time, store the data in
+a ``TimeIntervals`` table. Examples include behavioral states ("running", "resting"),
+experimental conditions, and invalid recording windows. Place additional
+``TimeIntervals`` tables in ``/intervals/`` alongside the predefined ``epochs``,
+``trials``, and ``invalid_times`` subgroups.
+
+*Use EventsTable for timestamp-anchored annotations that don't fit a per-trial row.*
+``EventsTable`` is the right type when each row is anchored at a single timestamp and
+duration is absent, optional, or mixed across rows. Typical cases:
+
+- TTL pulses and event markers from acquisition systems (replaces the deprecated ``AnnotationSeries``).
+- Free-behavior events not anchored to trial structure (licks, rewards, detected behaviors in continuous recordings).
+- Algorithmically detected events (ripples, sharp waves, spike-of-interest detections).
+- Experimenter-added annotations (e.g., "subject was distracted here", "experimenter adjusted the stimulus here").
+- Events occurring multiple times per trial with variable count, where ragged trial columns would be awkward.
+
+*Continuous digital traces are TimeSeries, not EventsTable.* A digital line sampled
+continuously (e.g., a 30 kHz 0/1 trace of a TTL channel) is a ``TimeSeries``. Edge
+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).
+
 
 Tables and ragged arrays
 ------------------------

docs/format/source/format_release_notes.rst

@@ -12,7 +12,15 @@ Major changes
 - 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.
+  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/``.
 
 Minor changes
 ^^^^^^^^^^^^^
@@ -30,6 +38,9 @@ Minor changes
   to the session reference time and that values should be stored in ascending order. (#676)
 - Improved documentation of ``Units.spike_times.resolution`` to clarify that it represents the temporal resolution
   (sampling period) of the spike times. (#666)
+- Harmonized ``/intervals/*`` group docstrings; rewrote ``TimeIntervals`` and ``EventsTable`` type
+  docstrings; replaced the placeholder docstring on the ``/events`` group and its inner
+  ``EventsTable`` slot; added a FAQ entry on routing time-anchored experimental data. (#688)
 
 2.9.0 (June 26, 2025)
 ---------------------