Skip to content

MATLAB guide

The MATLAB binding wraps the same C++ core as the Python package — identical semantics, identical performance (see the benchmark), and the same version number. It ships as a +mef3io package (two handle classes) over a single compiled MEX.

Setup

Either download the mef3io-matlab-vX.Y.Z.zip bundle from a GitHub release — classes and the CI-tested MEX for all platforms in one ready-to-addpath folder (see Install for the caveats) — or compile once from the repo (~30 s, needs a C++20 compiler via mex -setup C++):

run('<repo>/matlab/build_mex.m')
addpath('<repo>/matlab')

Verify: mef3io_mex('version') prints the library version. Test suite: run('<repo>/matlab/test_mef3io.m').

Times everywhere are uUTC (microseconds since the Unix epoch), int64 or double. Errors from the core surface as MATLAB errors (id mef3io:error) with the C++ message.

Writing

w = mef3io.Writer('session.mefd', Overwrite=true, Units='uV');
w.write('ch1', data, startUutc, 256);                 % NaN = gap, precision inferred
w.write('ch1', more, t2, 256);                        % appends in-segment
w.write('ch1', x, t3, 256, NewSegment=true);          % force a new segment
w.writeInt32('ch2', counts, 0.01, startUutc, 256, Valid=mask);
w.writeAnnotations(struct('time', t, 'text', 'note'), 'ch1');
delete(w);                                            % or let it go out of scope

mef3io.Writer(path, ...) name-value options: Overwrite (default false — an existing session is reopened for appending), Password1/Password2 (both required for encryption), Units, BlockLength, Threads (encode threads, 0 = automatic; w.setThreads(n) / w.threads() later), Metadata (below) and WaitForDisk (default false: a write returns once its data is handed to the operating system; true: once it is on disk). w.flush() returns only when everything written so far is on disk, in one combined wait, and delete(w) does the same (see When is my data on disk?; 2.0 removed Durability). After an unclean shutdown, mef3io.recoverSession(path) reports what is wrong (a dry run) and mef3io.recoverSession(path, Apply=true) fixes it.

  • write(channel, data, startUutc, fs, Precision=-1, NewSegment=false) — float path: NaN runs become gaps; Precision sets the conversion factor to 10^-precision, -1 infers it (or reuses the segment's on append). Returns a summary struct (samples_written, blocks, gaps_skipped, segment).
  • writeInt32(channel, data, ufact, startUutc, fs, Valid=[], NewSegment=false) — verbatim int32 counts + conversion factor (bit-exact round trip). data must be integer-typed: floating-point input errors (use write for float data) and values beyond the int32 range error instead of saturating. Valid is any numeric/logical mask, nonzero = valid.
  • writeInt32Many(channels, data, ufact, startUutc, fs, NewSegment=false) — the same run of int32 counts for many channels in one call (data is n_samples x n_channels; channels a cell array; ufact one value or one per channel). Like Python's write_int32_many: channels in parallel on the Writer's threads, one combined disk barrier, all channels rolled back on a failure before publishing. Returns one summary struct per channel.
  • writeAnnotations(records, channel) — struct array (or table) with fields time (required), type (default 'Note'), text, duration. Omit channel for session-level records. Appends to the records already stored at that level (created if absent); never replaces or deletes one.
  • setMetadata(md) / the Metadata= constructor option — session-wide subject/acquisition metadata. Use the object API (mirrors Python):
md = mef3io.Metadata( ...
    subject=mef3io.Subject(id="MRN-123", name_1="Jane", recording_location="EMU-4"), ...
    acquisition=mef3io.Acquisition(session_description="pre-surgical", line_frequency=60));
w = mef3io.Writer('s.mefd', Overwrite=true, Metadata=md);

Every field defaults, so set only what you have. setMetadata also accepts a plain struct with the flat field names (subject_id, session_description, …). Read it back with r.metadata, a mef3io.Metadata object with .subject and .acquisition (subject fields empty without a level-2 password).

Reading

r = mef3io.Reader('session.mefd');            % password as 2nd argument if encrypted
r.channels                                    % cellstr
info = r.info('ch1');                         % fs, ufact, times, subject metadata
x = r.read('ch1');                            % whole channel: double column, NaN gaps
x = r.read('ch1', t0, t1);                    % [t0, t1) window
raw = r.readRaw('ch2');                       % int32 counts + logical valid mask
segs = r.segments('ch1');                     % what data is where, per segment
blocks = r.toc('ch1');                        % block-level index (struct of vectors)
anns = r.records('ch1');                      % ch1's channel- + segment-level annotations
anns = r.records();                           % session level; r.records([], [], 'all') = all
seg0 = r.records('ch1', 0);                   % one segment's records
delete(r);

Text comes back as UTF-8 decoded into MATLAB char (UTF-16) on every platform — the same encoding strings are read in with — rather than through the locale codepage, so non-ASCII annotations and subject names round-trip on Windows too. Bytes that are not valid UTF-8 become U+FFFD, as in Python.

mef3io.Reader(path, password, nThreads, strict): strict (true, the default) fails on a segment that cannot be read; false skips it, reads its span as NaN, raises the warning mef3io:unreadableSegment, and lists it in r.problems(). nThreads is how many threads the Reader may use for everything it does (opening, file access, decoding): 0 = automatic, 1 = no extra threads; r.setThreads(n) changes it from the next call and r.threads() returns it (Threads).

info returns sampling_frequency, units_conversion_factor (NaN when the channel's segments store different factors: segments gives each segment's, read scales each sample by its own segment's, and readRaw lists the spans in units_conversion_factors, 1-based and inclusive; a segment whose factor is not set, 0, reads as its raw counts, with no warning in MATLAB yet), units_description, start_time/end_time (int64 uUTC), number_of_samples (stored samples; gaps not counted), n_segments, section3_available and the subject metadata fields (empty under a level-1 password — the signal still reads correctly, unlike the legacy stack).

Tar archives (single-file sessions)

Pack a session into one uncompressed tar file and read it in place — handy for sharing and safe archiving:

tarPath = mef3io.archiveSession('session.mefd');   % -> 'session.mefd.tar'
r = mef3io.Reader(tarPath);                        % no extraction needed

A mef3io addition, not part of MEF 3.0

meflib, pymef and mef_tools cannot open a .mefd.tar directly. It is a plain uncompressed tar file, so it can always be unpacked: mef3io.extractSession, tar -xf session.mefd.tar (built into Windows 10 and later, macOS and Linux) or the free 7-Zip on Windows. The unpacked .mefd folder works with the legacy tools.

Windowed reads stay cheap (the archive is uncompressed, so only the needed byte ranges are fetched), and any tar tool restores the directory (tar -xf session.mefd.tar). Tar sessions are read-only — mef3io.Writer refuses .tar paths; unpack first to modify:

sessionDir = mef3io.extractSession(tarPath);       % -> 'session.mefd' back
w = mef3io.Writer(sessionDir);                     % writable again

archiveSession(dir, tarPath, Overwrite=true) / extractSession(tarPath, destDir, Overwrite=true) pick targets and replace existing ones; they mirror Python's mef3io.archive_session / extract_session.

Session naming is enforced at every entry point: directories must end .mefd, archives .mefd.tar — anything else is refused, so a stray directory or file can never be misread (or overwritten) as a session.

Not in MATLAB: inspect, validation, de-identified copies, cancelling and progress

mef3io.inspect (a description of a session without reading its samples, see the Python guide) exists in Python and C++ only; neither MATLAB nor the C ABI has it. Validating and repairing a session (Validation & repair) are Python and C++ only as well; recovering after an interrupted write is available (mef3io.recoverSession).

mef3io.anonymize_session, mef3io.anonymize.check and mef3io.anonymize.verify (de-identified copies, see De-identification) are Python and C++ only too. From MATLAB, run them in a terminal: python -m mef3io anonymize SRC DST --reference-date YYYY-MM-DD (or --shift-us N).

The Python, C++ and C APIs can cancel a read or a long operation from another thread and report its progress (Cancelling and progress). The MATLAB classes do not offer it: a MEX call blocks MATLAB's single interpreter thread, so there is no second MATLAB thread to cancel from. (The C ABI has the hooks, mef3io_cancel_token_* and the *_ex functions, for other callers.)

Python's warnings carry the session path as data and keep it out of the message text (MefWarning). In MATLAB, mef3io:unreadableSegment and mef3io:legacyPassword still start with the session path, and mef3io:unreadableSegment / mef3io:unreadableRecords name the first file they skipped.

How it is put together

matlab/mef3io_mex.cpp is a single command-dispatch MEX over the flat C ABI (core/include/mef3io/c_api.h), so C++ exceptions never cross the MEX boundary. The +mef3io classes manage the native handles: delete closes them, and the MEX keeps itself locked while any handle is alive, so clear mex cannot dangle a session.