reference

Biosignal API

Public API index | App guide

labkit.biosignal.* provides GUI-free import and processing functions for physiological and wearable time-series data. Use it to build a MATLAB script from the same recording, channel, event, segment, template, and measurement structures used by LabKit apps.

labkit.biosignal.version() returns biosignal-library version and compatibility information used by labkit.contract requirement checks.

ECG peak detection is the only modality-specific detector in the current module. Import, filtering, segmentation, template construction, measurement, and group comparison use generic biosignal structures.

Public Surface

Current app-facing functions:

[recording, status] = labkit.biosignal.readRecording(filepath);
names = labkit.biosignal.listChannels(recording);
signal = labkit.biosignal.getChannel(recording, channel);
cropped = labkit.biosignal.cropSignal(signal, [startSec endSec]);
filtered = labkit.biosignal.filterSignal(signal, filterSpec);
ecgPeakOptions = labkit.biosignal.defaultEcgPeakOptions("qrs-streaming");
events = labkit.biosignal.detectEcgPeaks(signal, ecgPeakOptions);
segments = labkit.biosignal.segmentByEvents(signal, events, windowSec);
template = labkit.biosignal.buildTemplate(segments, templateOptions);
measurements = labkit.biosignal.measureSegments(segments, template, measureOptions);
comparison = labkit.biosignal.compareGroups(values, groups);

readRecording accepts MAT files containing timetable variables and delimited text tables such as CSV and TSV.

For delimited text tables, time handling is deliberately conservative. The reader does not treat an arbitrary monotonic numeric column as seconds. It uses a table column as time only when the column is datetime/duration, when the column name is time-like such as time_s or time_ms, or when the caller explicitly passes timeColumn and optionally timeUnit. Otherwise the recording uses a synthetic sample-index time axis and keeps numeric columns as signal channels.

CSV and TXT files from wearable workflows can contain preamble rows, headerless numeric data, I0/I1-style Arduino columns, sec/channel tables with per-column count rows, epoch timestamps, footer metadata rows, gaps, duplicated rows, or time axes that jump backward. The table reader tries to handle the common cases automatically and records import choices in recording.metadata. Backward or duplicate time steps are stitched forward with a nominal sample interval; large positive gaps are preserved and counted in metadata.timeRepair. If auto-detection is ambiguous, the app or caller should pass explicit import options rather than relying on inference.

Example explicit text-table time options:

opts = struct('timeColumn', 'timestamp', 'timeUnit', 'milliseconds');
[recording, status] = labkit.biosignal.readRecording(filepath, opts);

Useful delimited-table options include headerLine, hasHeader, timeColumn, timeUnit, signalColumns, fallbackFs, and timeRepair.

readRecording Options

Data Structures

Functions exchange ordinary MATLAB structures with these principal fields:

recording.sourcePath, recording.name, recording.signals, recording.metadata
signal.time, signal.values, signal.fs, signal.name, signal.displayName, signal.metadata
events.index, events.time, events.amplitude, events.score, events.label
segments.values, segments.timeOffset, segments.eventIndex, segments.eventTime, segments.fs
template.values, template.timeOffset, template.keptSegmentIndex, template.score
measurements.perSegment, measurements.summary

Open an individual function page for required fields, row/column orientation, units, empty-result behavior, and errors.

Processing Provided By This Module

The public functions cover:

• file loading and timetable/table normalization
• channel listing and extraction
• time ROI cropping
• generic filtering
• ECG/QRS peak detection
• event-centered segmentation
• template building and template-residual SNR-style segment measurements
• generic group summaries and pairwise Welch-style comparisons

detectEcgPeaks supports qrs-streaming, pan-tompkins, and local methods. Select the method through its options; no detector-specific helper call is required.

detectEcgPeaks Options

Start from labkit.biosignal.defaultEcgPeakOptions(method) and override only the fields the app exposes:

opts = labkit.biosignal.defaultEcgPeakOptions("pan-tompkins");
opts.polarity = "positive";
opts.minDistanceSec = 0.35;
events = labkit.biosignal.detectEcgPeaks(signal, opts);

Other Processing Options

Applications decide:

• ECG-specific labels and workflow wording
• which channel is treated as ECG
• GUI controls, previews, plot arrangement, and printing or export layout
• which measurements are displayed or exported
• class labels and interpretation of group comparisons

These application choices are intentionally not parameters of the generic biosignal functions.

Reference Contract

The generated page for every labkit.biosignal function documents its exact input structure, implemented options, defaults, legal values, empty-result and error behavior, and related functions. The repository documentation contract discovers the whole public package rather than relying on a hand-maintained function list, and executes every block labeled Example:.