nstat.Events

class nstat.Events(eventTimes, eventLabels=None, eventColor='r')[source]

Bases: object

Experimental event markers for highlighting epochs in figures.

Events represent times of importance during an experiment (e.g. stimulus onset, trial boundaries) that are overlaid on raster or signal plots.

Parameters:

  • eventTimes (array_like) – Vector of event times (seconds).

  • eventLabels (sequence of str or None) – Labels for each event. Must match the length of eventTimes when provided.

  • eventColor (str, default 'r') – Colour string for the event lines (Matlab-style colour codes).

__init__(eventTimes, eventLabels=None, eventColor='r')[source]
Parameters:
Return type:

None

plot(*_, handle=None, colorString=None, **__)[source]

Plot event markers on one or more axes.

Parameters:

  • handle (Axes or list[Axes], optional) – Axes to plot into (default: current axes).

  • colorString (str, optional) – Override line colour for event lines. When None (the default), falls back to self.eventColor set at construction. Matches MATLAB Events.m:87 after the upstream fix from hardcoded 'r' to EObj.eventColor (see AUDIT_REPORT M17). Gold fixture events_exactness.mat was regenerated 2026-06-11 against this corrected MATLAB behavior.

Notes

MATLAB single-letter colour codes ('g', 'b', …) differ from matplotlib’s defaults: MATLAB’s 'g' is RGB [0,1,0] while matplotlib’s 'g' is the darker [0,0.5,0]. Single- letter codes are translated to the MATLAB convention so the rendered colour matches MATLAB exactly.

toStructure()[source]

Serialise the Events to a plain dictionary.

Return type:

dict[str, Any]

static fromStructure(structure)[source]

Reconstruct Events from a dictionary (inverse of toStructure()).

Parameters:

structure (dict[str, Any] | None)

Return type:

‘Events’ | None