Implement NeurodataWithoutBorders/nwb-schema#690: add source_description to EventsTable; add merge/query helpers to NWBFile

[rly]

Summary

• Adds the optional source_description attribute to EventsTable, per nwb-schema#690.
• Updates AnnotationSeries, BehavioralEvents, and EventsTable class docstrings to match the revised schema doc strings.
• Adds NWBFile.merge_events_tables() and NWBFile.get_all_events() per NWBEP001.
• Adds NWBFile.create_events_table().

Changes

Schema

Points the nwb-schema submodule to the head of nwb-schema#690, which:

• Adds the optional source_description attribute to EventsTable (free-text label of event origin, e.g. "Acquisition system" or "Manual video review").
• Recommends /events as the single location for all EventsTable instances regardless of provenance.
• Updates deprecation docstrings for BehavioralEvents and AnnotationSeries.

EventsTable

• New optional source_description parameter in __init__.
• Updated class docstring to match schema, including the one-event-type-per-table guidance.

NWBFile

• merge_events_tables(tables) — merges a list of EventsTable objects into a single DataFrame indexed and sorted by timestamp, with a source_events_table column identifying the origin table of each row.
• get_all_events() — calls merge_events_tables on all tables in NWBFile.events; returns an empty DataFrame if none exist.
• create_events_table() — added via __clsconf__; creates and registers an EventsTable without requiring a separate import.

Docstrings and deprecation warnings

• AnnotationSeries, BehavioralEvents, EventsTable class docstrings updated to match nwb-schema#690.
• AnnotationSeries and BehavioralEvents deprecation warnings now name nwbfile.add_events_table() and nwbfile.create_events_table() as the migration target.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.38%. Comparing base (9231882) to head (9e0201e).

❗ There is a different number of reports uploaded between BASE (9231882) and HEAD (9e0201e). Click for more details.

HEAD has 5 uploads less than BASE

Flag	BASE (9231882)	HEAD (9e0201e)
unit	4	3
integration	4	0

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #2192      +/-   ##
==========================================
- Coverage   95.18%   85.38%   -9.80%     
==========================================
  Files          30       30              
  Lines        2991     3004      +13     
  Branches      444      446       +2     
==========================================
- Hits         2847     2565     -282     
- Misses         86      344     +258     
- Partials       58       95      +37     

Flag	Coverage Δ
integration	?
unit	85.38% <100.00%> (-0.21%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.