Skip to content

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.check and 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 mV and uV), merge_sessions goes 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) in merge.check and in the merge, and the merge emits one mef3io.MixedUnitsWarning per call. uV, µV and μV count as the same unit. Silence it with warnings.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 compat MefReader) and by pymef. The older mef_tools MefReader.get_data returns all zeros for such a channel. merge_sessions and transform_session now emit mef3io.MixedFactorsWarning when 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 without time_ranges was 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.mixed description 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 with Reader.segments().
  • New warnings. mef3io.MixedUnitsWarning and mef3io.MixedFactorsWarning are MefWarning subclasses, so filterwarnings("ignore", category=mef3io.MefWarning) silences them with the others.
  • Reports. MergeReport gains units_mixed; reports saved by 2.2.0 still load.
  • Windowed merges of 2.2.0. See the fix above.
  • MATLAB is unchanged.