refactor(dynamictable): rename getRow locals and use an arguments block

[ehennestad]

Motivation

Refactor getRow so it is easier to reason about. Its variable names and docstrings were unclear or misleading.

Background — getRow builds the table that DynamicTable.getRow and toTable return: one table variable per requested column, read for the requested rows only. #909 rewrites getRow to read ragged columns in a few calls.

Problem — A developer who reads getRow, or reviews #909, has to learn what the code does from text that misdescribes it. Three things get in the way:

• Variable and function names are unclear or misleading. A reader has to trace each name to its use to learn what it holds. The cell array that becomes the table's variables is called row. The number of subscripts used to index a column is called rank, which is also MATLAB's matrix-rank function. The helper that reads one column is called select. The row indices, the column name and the chain of index columns are abbreviated to ind, cn and colIndStack.
• Docstrings and comments are outdated. They describe an earlier version of the function. The header says the function takes a scalar 0-based index and returns a set of output arguments. The function takes a vector of 1-based indices and returns a table. Two comments call a column vector a row vector.
• Argument validation is split between two mechanisms. validateattributes calls check the table and the indices, and an inputParser with anonymous validators checks the options. A wrong option value is reported as It must satisfy the function: @(x)isempty(x)||iscellstr(x) rather than as the rule.

None of this changes what getRow returns, so nothing shows up for users or in CI.

Solution — Names say what a variable holds or what a function does. Docstrings and comments describe the current code. An arguments block validates the inputs, and its errors name the argument and the rule. #909, #923 and #912 are rebuilt on this branch, so their diffs read in the new vocabulary.

What changed

• Unclear or misleading names are replaced throughout getRow and its helpers; the full list is in the notes below. What getRow returns for valid input is unchanged.
• Outdated docstrings and comments are corrected: the header of getRow, the header of every helper, and the comments on column orientation and on compound columns.
• The arguments are validated by an arguments block. A wrong option value is reported as Invalid value for 'columns' argument. Value must be empty or a cell array of character vectors.
• Three inputs that used to stop with an error are accepted: useId given as a number is converted to logical, an empty index list returns a table with no rows, and a column vector of row indices is reshaped to a row, which the public getRow methods already do.
• The message of the invalid-shape error reads "does not match".
• fix(dynamictable): read ragged columns once per index level in getRow #909, perf(io): read gapped multi-dimensional selections in one call #923 and perf(io): read several DataStub selections in one pass #912 are rebuilt on this branch with the same commits. The commit of fix(dynamictable): read ragged columns once per index level in getRow #909 that fixed these same comments is folded in here.

Implementation notes

Renames, old to new:

Old	New
row	columnData
ind, matInd	rowIndices
cn, column_name	columnName
i	iColumn, iField
indexNames, colIndStack	vectorChainNames
structNames	compoundMemberNames
columnData (one compound member)	memberData
array_size, num_rows, is_row_dim	arraySize, numRows, isRowDimension
rank	numSubscripts
refProp	dataSize
selectInd	subscripts
id, idMatch	requestedIds, isIdFound
select, returning selected	getColumnRows, returning columnRows
getIndById	getRowIndicesById
InvalidVectorDataShapeError	createInvalidShapeError

• The table argument is validated by matnwb.common.validation.mustBeDynamicTable, which accepts the hdmf_common and the legacy core class as the old validateattributes call did. The name lists keep the old rule, empty or a cellstr, through a local validator, because mustBeText is newer than R2019b. The default categories come from a local function, since a default expression cannot branch on the table's class.
• Option names still match case-insensitively and partially, as with inputParser. The three callers in the repository pass exact names.
• The commits of fix(dynamictable): read ragged columns once per index level in getRow #909 and perf(io): read gapped multi-dimensional selections in one call #923 were rebuilt by replaying the same rename, arguments-block and comment edits on each commit's copy of getRow.m, so each keeps its author, message and diff. perf(io): read several DataStub selections in one pass #912 does not touch the file and was rebased.

Examples

Validation messages and accepted inputs

The snippet builds a three-row table in memory and calls getRow with useId given as the number 1, with an empty index list, with a wrong columns value, and with a column vector of row indices.

dynamicTable = types.hdmf_common.DynamicTable('description', 'example', 'colnames', {'score'});
dynamicTable.addRow('id', 10, 'score', 0.1);
dynamicTable.addRow('id', 20, 'score', 0.2);
dynamicTable.addRow('id', 30, 'score', 0.3);

try
    row = types.util.dynamictable.getRow(dynamicTable, 20, 'useId', 1);
    fprintf('useId given as 1: score %g\n', row.score);
catch e
    fprintf('useId given as 1: Error: %s\n', e.message);
end
try
    row = types.util.dynamictable.getRow(dynamicTable, []);
    fprintf('no indices: table of size %dx%d\n', height(row), width(row));
catch e
    fprintf('no indices: Error: %s\n', e.message);
end
try
    row = types.util.dynamictable.getRow(dynamicTable, 1, 'columns', 42);
    fprintf('columns given as 42: %s\n', class(row));
catch e
    fprintf('columns given as 42: Error: %s\n', e.message);
end
row = types.util.dynamictable.getRow(dynamicTable, [3; 1]);
fprintf('column vector of indices: scores %s\n', mat2str(row.score.'));

Before — The first two calls stop with an error, and the third reports an anonymous function instead of the rule. Only the column vector of indices returns rows.

useId given as 1: Error: The value of 'useId' is invalid. It must satisfy the function: @(x)islogical(x).
no indices: Error: Expected input to be a vector.
columns given as 42: Error: The value of 'columns' is invalid. It must satisfy the function: @(x)isempty(x)||iscellstr(x).
column vector of indices: scores [0.3 0.1]

After — useId given as 1 selects the row with id 20, the empty index list gives a table with no rows and the one requested column, and the wrong columns value is reported with the rule in words. The column vector gives the same rows as before.

useId given as 1: score 0.2
no indices: table of size 0x1
columns given as 42: Error: Invalid value for 'columns' argument. Value must be empty or a cell array of character vectors.
column vector of indices: scores [0.3 0.1]

How to test

Run the snippet above on this branch. The output should match the After block.

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 Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 86.95652% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.44%. Comparing base (ff0d00e) to head (0bb63d3).

Files with missing lines	Patch %	Lines
+types/+util/+dynamictable/getRow.m	86.95%	12 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #940      +/-   ##
==========================================
- Coverage   95.46%   95.44%   -0.03%     
==========================================
  Files         240      240              
  Lines        8869     8870       +1     
==========================================
- Hits         8467     8466       -1     
- Misses        402      404       +2     

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