What vhlab-library-python and NDI-python actually need from here: five calls, and a .mat object reader under them

Companion to #1 and #2. Those cover the convention and the PsychoPy question; this one answers "what should be built first", derived from the callers rather than from the MATLAB folder layout.

The short version: the API surface the downstream ports need is five methods, and four of them are one-line field reads. Essentially all of the work is the layer underneath — turning a MATLAB-written stims.mat back into objects.

The five calls

Verified against vhlab-NewStim-matlab 0ae6822, vhlab-library-matlab cca1cce and NDI-matlab 18ff517:

call	MATLAB	what it does
numStims(script)	Scripts/@stimscript/numStims.m	length(S.Stims)
get(script, i)	Scripts/@stimscript/get.m	S.Stims{i}, 1-based, bounds-checked
getDisplayOrder(script)	Scripts/@stimscript/getDisplayOrder.m	S.displayOrder
getparameters(stim)	Stimuli/@<class>/getparameters.m	a per-class field read: S.PSparams for @periodicstim, S.SGSparams for @stochasticgridstim, … The base @stimulus returns empty; all 19 classes override it
duration(stim)	Stimuli/@<class>/duration.m	stimulus duration in seconds; needed by one caller

Nothing in that list needs Psychtoolbox, which is why the reader scope in #1 is coherent: the data face of stimscript is pure struct access.

Who is waiting, exactly

NDI-python — one blocker. ndi.daq.metadatareader.NewStimStims (NewStimStims.m:36-37):

for i=1:numStims(ss)
    parameters{i} = getparameters(get(ss,i));
end

That is the whole dependency: numStims, get, getparameters. It is also the one with a fidelity requirement attached — those parameter structs become the stimulus parameters stored in NDI documents, so field names and types have to match MATLAB exactly or NDI-python's documents diverge from NDI-matlab's for the same experiment.

A call site that looks blocked and is not: +ndi/+setup/+daq/+reader/+mfdaq/+stimulus/vhlabvisspike2.m:116 calls getstimscript — but it never touches ss afterwards. It uses only mti (mti{i}.stimid, mti{i}.startStopTimes), which are plain structs. vhlib.StimDecode.getstimscript already returns those today, so that reader can be ported now, with no NewStim at all.

vhlab-library-python — six functions, all in StimulusDecoding, listed with what each needs:

function	needs
repairoverflow_stimtimes_txt	getDisplayOrder — already ported but incomplete; it raises without this
getstimscriptparameters	numStims, get, getparameters
getstimscriptproperties	numStims, get, getparameters, getDisplayOrder
findtransitionsSGSBL	numStims, getparameters, getDisplayOrder, plus @stochasticgridstim / @blinkingstim parameter semantics
stimscriptgraph	numStims, getDisplayOrder — currently a stub that raises NotImplementedError
mti_from_stimtimes_txt	get, duration

Two corrections while deriving this (both recorded wrongly in vhlib's bridge; I will fix them there):

• getstimscriptsync is not blocked on NewStim. It is getstimscript + tpcorrectmti, and it makes no stimscript calls at all. tpcorrectmti is not defined in vhlab-library-matlab, vhlab-toolbox-matlab, vhlab-NewStim-matlab or NDI-matlab — the VH-lab equivalent vhlabcorrectmti is already ported — so it is blocked on locating or replacing that dependency.
• check_stimtimes_txt_vs_stims_mat is not blocked on NewStim either. It reads z.MTI2{j}.stimid and nothing else out of stims.mat; the stimscript never enters. It is blocked on dirstruct plumbing.

So the NewStim-blocked set is six functions plus one NDI reader — smaller than #9 in vhlab-library-python assumed, and pointed at a narrower API.

The actual work: reading the objects

MATLAB stores saveScript as an old-style @stimscript object holding Stims (a cell array of @periodicstim, @stochasticgridstim, … objects), displayOrder, displayMethod and StimTimes. scipy.io.loadmat surfaces old-style class objects as a MATLAB-object wrapper carrying the class name, not as a struct, and the stimulus objects are nested one level down inside it. Everything above is trivial once that is unwrapped into Python objects that know their class.

Two consequences for whoever starts:

1. scipy.io.savemat cannot write a MATLAB object, so tests cannot synthesize fixtures. Real stims.mat files recorded from MATLAB have to be committed — ideally one per stimulus class that appears in VH lab data. vhlib's getstimscript tests stand a plain struct in for saveScript for exactly this reason, and are honest that they check only the directory and error logic.
2. Class coverage can be driven by data, not by the folder. There are 19 stimulus classes, but the ones that appear in recorded experiments are few — @periodicstim, @stochasticgridstim, @blinkingstim and @hartleystim cover most of it. Since getparameters is a per-class field read, each additional class is roughly one table entry once the loader exists.

Suggested order

1. The .mat → object reader for @stimscript and the @stimulus subclasses, with committed MATLAB-written fixtures. Everything else is downstream of this.
2. numStims, get, getparameters — unblocks NDI's NewStimStims (the only NDI blocker) and three vhlib functions.
3. getDisplayOrder — completes repairoverflow_stimtimes_txt and unblocks three more.
4. duration — mti_from_stimtimes_txt.
5. Per-class parameter fidelity for whichever classes the lab's data actually contains, checked field-by-field against MATLAB for the NDI document requirement above.

Related: VH-Lab/vhlab-library-python#9, VH-Lab/vhlab-library-python#6.

🤖 Generated with Claude Code

https://claude.ai/code/session_016P5BgMWNXp1mGckW4WXk6q

Start with the scipy.io.loadmat path behind getstimscript and the MATLAB @stimscript and stimulus object shapes described here. Add committed MATLAB-written stims.mat fixtures for representative classes, then implement the object reader and the five calls: numStims, get, getparameters, getDisplayOrder, and duration. Done means downstream callers can read real fixtures with MATLAB-compatible parameter fields and types.