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 95.26%. Comparing base (a256828) to head (c32ed2a).

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #2192      +/-   ##
==========================================
+ Coverage   95.24%   95.26%   +0.02%     
==========================================
  Files          30       30              
  Lines        3008     3021      +13     
  Branches      446      448       +2     
==========================================
+ Hits         2865     2878      +13     
  Misses         87       87              
  Partials       56       56              

Flag	Coverage Δ
integration	72.98% <30.76%> (-0.19%)	⬇️
unit	85.73% <100.00%> (+0.06%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 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.