Add AlignedDynamicTable non-generated base class with category table validation

[ehennestad]

⚠️ Depends on #836 — merge that first - merged

Motivation

The AlignedDynamicTable schema defines two requirements in docstrings that cannot be enforced by the generated class alone:

1. All sub-tables added to an AlignedDynamicTable "MUST have the same number of rows" (source).
2. The names in the categories property MUST match the names of category tables in the AlignedDynamicTable (source).

Without additional runtime validation, users can create invalid NWB files when using AlignedDynamicTable or its subtypes.

This PR adds validation hooks for AlignedDynamicTable through a custom base class. It also adds convenience APIs so valid tables are easier to construct: schema-defined category tables auto-register in categories when assigned, and custom category tables can be added with addCategory(name, table).

This PR stacks on #836 and uses its schema validation reporting context to maintain backwards-compatibility by making AlignedDynamicTable validation on construction warn instead of error to ensure pre-PR icephys tutorial examples can still run without breaking.

Example usage (updated snippets from icephys tutorial)

1. categories do not need to be listed when the table is initialized with rows — assigning a category table later registers it automatically:

% before
ic_rec_table = types.core.IntracellularRecordingsTable( ...
    'categories', {'electrodes', 'stimuli', 'responses'}, ...  % name is manually added to categories
    'colnames', {'recordings_tag'}, ...
    'id', types.hdmf_common.ElementIdentifiers('data', int64([0; 1; 2])), ...
    'recordings_tag', ...);
ic_rec_table.electrodes = ...;   % table is assigned afterwards

% after
ic_rec_table = types.core.IntracellularRecordingsTable( ...
    'colnames', {'recordings_tag'}, ...
    'id', types.hdmf_common.ElementIdentifiers('data', int64([0; 1; 2])), ...
    'recordings_tag', ...);
ic_rec_table.electrodes = ...;   % auto-registers in name `categories`

2. Use addCategory for custom categories instead of the manual two-step:

% before
ic_rec_table.categories = [ic_rec_table.categories, {'recording_lab_data'}];
ic_rec_table.dynamictable.set('recording_lab_data', customTable);

% after
ic_rec_table.addCategory("recording_lab_data", customTable);

How to test the behavior?

runtests('+tests/+system/AlignedDynamicTableTest.m')

Checklist

• Have you ensured the PR description clearly describes the problem and solutions?
• Have you checked to ensure that there aren't other open or previously closed Pull Requests for the same change?
• If this PR fixes an issue, is the first line of the PR description fix #XX where XX is the issue number?

🤖 Generated with Codex

[bendichter]

What would be the warning with the old syntax?

[ehennestad]

What would be the warning with the old syntax?

ic_rec_table = types.core.IntracellularRecordingsTable( ...
    'categories', {'electrodes', 'stimuli', 'responses'}, ...
    'colnames', {'recordings_tag'}, ...
    'description', [ ...
        'A table to group together a stimulus and response from a single ', ...
        'electrode and a single simultaneous recording and for storing ', ...
        'metadata about the intracellular recording.'], ...
    'id', types.hdmf_common.ElementIdentifiers('data', int64([0; 1; 2])), ...
    'recordings_tag', types.hdmf_common.VectorData( ...
        'data', repmat({'Tag'}, 3, 1), ...
        'description', 'Column for storing a custom recordings tag' ...
        ) ...
);

Current warning:
Warning: The categories property lists category table(s) that have not been added to the AlignedDynamicTable: electrodes, stimuli, responses.
Add the missing table(s) with the addCategory method (or by setting the corresponding schema category property), or list categories only before the table has rows. The non-conforming value is kept. If you maintain this data, consider correcting it before export.

Maybe a better version:
Warning: The categories property lists category table(s) that have not been added to the IntracellularRecordingsTable: electrodes, stimuli, responses.
The table already has <num_rows> and all category tables must have the same height as the parent table. Add the missing table(s) with the addCategory method, or list categories only before the table has rows. The non-conforming value is kept. This needs to be corrected before export.

[codecov]

Codecov Report

❌ Patch coverage is 98.53480% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.43%. Comparing base (0343320) to head (961a13b).

Files with missing lines	Patch %	Lines
...es/+util/+dynamictable/+internal/getColumnHeight.m	90.00%	2 Missing ⚠️
...nternal/collectConstantPropertiesAcrossHierarchy.m	91.66%	1 Missing ⚠️
+matnwb/+neurodata/AlignedDynamicTableBase.m	99.34%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #837      +/-   ##
==========================================
+ Coverage   95.33%   95.43%   +0.10%     
==========================================
  Files         226      228       +2     
  Lines        7821     8064     +243     
==========================================
+ Hits         7456     7696     +240     
- Misses        365      368       +3     

☔ 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.

[bendichter]

Warning: The categories property lists category table(s) that have not been added to the IntracellularRecordingsTable: electrodes, stimuli, responses. Add the missing table(s) with the IntracellularRecordingsTable.addCategory method before exporting.

[ehennestad]

Warning: The categories property lists category table(s) that have not been added to the IntracellularRecordingsTable: electrodes, stimuli, responses. Add the missing table(s) with the IntracellularRecordingsTable.addCategory method before exporting.

Warning is updated to that text here: 7f3bb6a