Extend absoluteToRelativeEvents with robust event filtering, trial inference, and flexible trial-start reference modes

[Copilot]

NeuralEmbedding.absoluteToRelativeEvents previously required a positional numeric trialStartTimes input and assumed all events had valid Ts and trial fields. This update makes the method resilient to incomplete event structs and adds two explicit name-value modes for trial alignment and trial assignment recovery.

• API update: named trial-start reference

  • Replaced positional second arg with trialStartReference name-value input.
  • Supports two modalities:
    • numeric vector of per-trial start times
    • event name present in evts; uses the first matching event per trial as trial start.

• Input sanitization: drop unusable events

  • Events without a valid scalar finite Ts are discarded before processing.

• Optional trial reconstruction from bounds

  • Added inferTrialFromBounds (default false).
  • When enabled and both trialstart + trialend exist, events with missing/invalid trial are assigned by Ts inclusion within [trialstart, trialend] windows.

• Docs/examples updated in-place

  • Updated inline usage examples and nearby references to the new name-value call style.

% mode 1: numeric trial starts
evts = NeuralEmbedding.absoluteToRelativeEvents(evts, ...
    'trialStartReference', trialStartTimes);

% mode 2: derive starts from an event label (first per trial)
evts = NeuralEmbedding.absoluteToRelativeEvents(evts, ...
    'trialStartReference', "trialstart");

% optional: infer missing trial ids from trialstart/trialend bounds
evts = NeuralEmbedding.absoluteToRelativeEvents(evts, ...
    'trialStartReference', "trialstart", ...
    'inferTrialFromBounds', true);

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.