Recommend /events as single location for EventsTable; add source attribute

[rly]

Summary

Closes #689 (pending consensus on this PR).

• Single recommended location for EventsTable. All EventsTable instances for a session belong in the top-level /events group of NWBFile, regardless of provenance. Replaces the three-way /acquisition vs /processing/<module> vs /events guidance that landed earlier in the 2.10.0 cycle.
• New optional source attribute on EventsTable (text, free-form short phrase) records where the events came from. Examples used in docs: "Acquisition system", "Thresholding of analog signal ANALOG1 at 3 V", "Manual video review". The longer description attribute still carries the algorithm/channel narrative.
• One event type per table. Clarified in the EventsTable type docstring, the /events group docstring, and the FAQ that each table should hold events of a single type (same per-event metadata columns across all rows). This was stated in NWBEP001 but not previously reflected in the schema docs.
• Deprecation docstrings updated. BehavioralEvents and AnnotationSeries now point at EventsTable, name /events as the destination, mention the source attribute, and spell out the per-field migration mapping (including data → an event-marker-named column for BehavioralEvents, and data → annotation column for AnnotationSeries).

Discussion captured the consensus for Option 1 from #689 (single location, with optional categorical info on the table itself rather than encoded by path). The source attribute is intentionally free text rather than a controlled vocabulary, because the acquisition/processing distinction is exactly what made the path-based layout inconsistent across labs in the first place.

Files changed

• core/nwb.event.yaml — source attribute on EventsTable; single-type clarification in type docstring.
• core/nwb.file.yaml — rewrote /events group docstring for the single-location guidance.
• core/nwb.behavior.yaml, core/nwb.misc.yaml — rewrote BehavioralEvents and AnnotationSeries deprecation docstrings.
• docs/format/source/format_description.rst — FAQ section on routing time-anchored experimental data updated to single-location.
• docs/format/source/format_release_notes.rst — combined Where to store EventsTable objects in the NWB file? #689 entry under Major changes (covers both deprecations + the single-location and source story); separate Minor changes entry covers schema-side additions.

Test plan

• Schema loads cleanly via NamespaceCatalog (hdmf-common 1.9.0 + core 2.10.0-alpha) in a pynwb/hdmf dev env.
• Sphinx docs build (make doc) — should be checked before merging; FAQ section changes are RST.
• PyNWB integration: confirm EventsTable.source round-trips through add_events_table / get_events_table and that no schema validation regresses.
• Verify CHANGELOG / release-notes entries render correctly under 2.10.0.

Notes for reviewers

• The schema still permits EventsTable under /acquisition or in a ProcessingModule (because EventsTable inherits from DynamicTable). This PR does not forbid that placement; it only changes the recommendation. The FAQ no longer mentions alternate placements at all — please flag if you'd prefer to mention this explicitly.
• The source attribute is free text. If you'd prefer a controlled vocabulary (e.g., {acquisition, processing, annotation}), please weigh in — I argued against it in the discussion thread but it's a reasonable alternative.

🤖 Generated with Claude Code

[oruebel]

Overall this looks good to me. I added a suggestion, please take a look.