mef3io 2.3.0¶
Released 2026-11-07
This release fixes a silent data loss in windowed merges of recordings with inaccurate segment times, makes the checks of a short window of a long session much cheaper on network drives, and turns mixed units from a refusal into a warning. Output files are the same as before, apart from the random file IDs.
Highlights¶
- Cheaper checks and copies of a short window.
merge.check,transform.checkand the copies themselves no longer make thousands of small requests when only a short window of a large session is kept (many channels and segments, for example on a network drive). A small block index is read in one request instead of about fifteen, a channel's segments outside the window are looked at only when nothing inside it holds samples, and each small metadata file is read once per operation. Every source file is opened at most once per check and once per copy. Results and refusals are unchanged, and the copy is byte-for-byte what it was. - Merging different units warns, it never refuses. Units are free text.
When the data a merge keeps holds different units strings for a channel (for
example
mVanduV),merge_sessionsgoes ahead: every segment keeps its own string, samples are never rescaled, and the channel's label is the first kept segment's. The report names each such channel and its strings (notes,units_mixed) inmerge.checkand in the merge, and the merge emits onemef3io.MixedUnitsWarningper call.uV,µVandμVcount as the same unit. Silence it withwarnings.filterwarnings("ignore", category=mef3io.MixedUnitsWarning). - New validator check
units.mixed(warning, not repairable) reports a channel whose segments declare different units. See Validation. - Warning for channels that older tools read as zeros. A channel whose
segments have different conversion factors (recordings merged from different
gains) is read correctly by mef3io (
Reader,MultiReader, the compatMefReader) and by pymef. The oldermef_toolsMefReader.get_datareturns all zeros for such a channel.merge_sessionsandtransform_sessionnow emitmef3io.MixedFactorsWarningwhen the result has one, so you know before handing the file to that tool. See Merging recordings.
Fixed¶
- A windowed copy no longer drops data when a segment's header times are wrong (#184). When a recording's metadata file said a segment ended before its data really did (what an interrupted append or a recorder that writes a short end time leaves behind), or began after it did, the header span no longer matched the data.
- Who was affected:
merge_sessions(time_ranges=...), available since 2.2.0, left the whole window of such a source out of the result without any message. A merge withouttime_rangeswas not affected, and neither was a copy of whole recordings. transform_session(time_range=...)(and cuts), available since 1.5.0, refused such a source at its final check. Nothing was published and nothing was lost.- Segments are now judged by the blocks they hold, as reading does, so the copy holds exactly the samples a read of that window returns.
- If you ran a windowed merge with 2.2.0 on recordings that may have such segments, run it again with 2.3.0 and compare the sample counts with a read of the same window. The source recordings were never changed.
- Windows build. The micro sign in the
units.mixeddescription is UTF-8 and MSVC now compiles the sources as UTF-8 (/utf-8). - Release workflow. The coverage job now has 150 minutes (it ran out of time at 88% of its work under the former limit). A coverage failure never blocked a release.
Upgrading from 2.2.0¶
Python and C++ code need no change; nothing that worked is removed.
- Mixed units. A merge that used to be refused for different units now
succeeds with a
MixedUnitsWarning. Code that relied on the refusal, or that turns warnings into errors, should check for the warning. Samples are never rescaled; see the units of each segment withReader.segments(). - New warnings.
mef3io.MixedUnitsWarningandmef3io.MixedFactorsWarningareMefWarningsubclasses, sofilterwarnings("ignore", category=mef3io.MefWarning)silences them with the others. - Reports.
MergeReportgainsunits_mixed; reports saved by 2.2.0 still load. - Windowed merges of 2.2.0. See the fix above.
- MATLAB is unchanged.