Events

An event marks a stimulus, behavioral condition, or other interval that can be aligned with imaging frames. Continuous .dat recordings use events.mat in the Save Folder; event-split UMT data carries its own top-level eventInfo.

The EventsManager class creates, validates, loads, and saves events.mat. The Events Manager app is its graphical interface and provides convenient controls for event detection from LabeoTech imaging-system analog inputs.

Current events.mat variables

In the table, N is the number of analog samples, K is the number of recorded or selected analog channels, M is the number of detected ON/OFF transitions, and C is the number of conditions. Empty values are permitted where the corresponding source or option is not used.

Field	Class	Typical size	Meaning
RawFolder	char	1-by-path length	Raw analog-input source used to build the event information.
AnalogIN*	single	N-by-K	Loaded analog traces. Each column is one analog channel.
sr	single	scalar	Analog sampling rate in hertz.
trigThr	single or char	scalar or 1-by-K	Detection threshold for the selected channel(s), or 'auto' before detection resolves it.
trigPolarity	char	1-by-text length	positive or negative trigger polarity.
eventID	uint16	M-by-1	Condition identifier for every detected transition.
state	logical	M-by-1	true for an ON transition and false for an OFF transition.
timestamps	single	M-by-1	Transition times in seconds on the analog recording time base.
eventNameList	cell	1-by-C	Condition names indexed by eventID.
baselinePeriod	single	scalar	Pre-event baseline duration in seconds.
trigChanName*	cell	1-by-K	Names of the LabeoTech analog channels used for detection.
selectedEvents	logical	M-by-1	Saved include/ignore flag for every transition; the size matches eventID.
EventFileName	char	1-by-filename length	Optional condition-list source file.
EventFileParseMethod	char	1-by-text length	Condition-list parser: none, csv, or vpixx.
b_hasExternalSignal	logical	scalar	Indicates that the analog trace came from the MATLAB external-signal workflow.

* AnalogIN and LabeoTech channel names originate from the analog-input format of LabeoTech imaging systems. The class can also store one user-provided signal in AnalogIN through the external-signal workflow below.

Detection, conditions, and repetitions

1. EventsManager uses the threshold, polarity, trigger type, minimum inter-stimulus interval, and optional filtering to identify event transitions.
2. An optional condition file assigns condition IDs and names in chronological order. Without one, supported digital or generic detection rules assign the conditions.
3. Repeated event IDs become repetitions of the same condition.
4. The baseline duration and acquisition frame rate determine which imaging frames precede and follow each event.

Detect an external signal in MATLAB

The current app does not expose this workflow, but the class can detect one numeric trigger signal that was acquired outside a LabeoTech system:

saveFolder = "C:\data\mouse01\session01";
signal = readmatrix("external-trigger.csv");
sampleRateHz = 1000;

ev = EventsManager(saveFolder);
ev.trigType = 'EdgeSet';
ev.trigPolarity = 'positive';
ev.trigThr = 'auto';
ev.getTriggersFromSignal(signal(:,1), sampleRateHz, true, ...
    'FilterFreq', 0);
ev.saveEvents();

getTriggersFromSignal treats the vector as one condition named extSignal, updates the object, and records b_hasExternalSignal=true. Inspect the detected events before calling saveEvents.

Validation and ignored trials

The class checks field types and compatible lengths, validates timing against acquisition information when available, and prevents unusable frame selections. A missing file disables event features; malformed event information is not guessed from imaging intensity.

When a condition or repetition is deleted in DataViewer, its entries in selectedEvents are set to false and saved in events.mat. The signal and timestamps are not erased. The ignored trials remain excluded from later DataViewer displays and from analysis functions that use events.mat, until they are restored.

Event information in UMT files

When continuous data is split into trials, the UMT file keeps the event-axis description at top level so it remains interpretable outside the original Save Folder. For an entry with an E dimension, each E element must match one row of the event vectors.

Field	Class	Size	Meaning
eventID	numeric	E-by-1	Condition identifier for each event-axis element.
repetitionIndex	numeric	E-by-1	Repetition number; zero denotes a condition already aggregated across repetitions.
eventName	string or cell	E-by-1	Condition name corresponding to each E element.
eventAxisMode	char	text scalar	instances or aggregated_repetitions.
baselinePeriod	numeric	scalar, optional	Baseline duration in seconds.

See Organization of .umt files for the surrounding UMT structure.

Protect saved event annotations
Replace an existing events.mat only through the tool or validated code, and keep backups for irreplaceable event annotations.