FIX: Make brainvision overrides robust to missing header keys; cover all spec-required keys

The override branches called cfg.get(..., key) purely to log the original
header value before announcing the override; that lookup raised
NoOptionError exactly in the case the override was meant to recover from.
Wrap the log-only lookups (DataFile, MarkerFile, NumberOfChannels) and the
required SamplingInterval lookup in _aux_hdr_info so the override actually
takes effect when the header lacks the key.

Extend overrides to every spec-required header key with three new options:
data_orientation ([Common Infos] DataOrientation), data_format ([Common
Infos] DataFormat), and binary_format ([Binary Infos] BinaryFormat).
Treat a missing or empty MarkerFile= entry as "no markers" (per the BV
Core Data Format spec, MarkerFile= is optional).

Collapse the six per-key override+log+fallback blocks behind one _hdr_get
helper, and refactor _validate_overrides into three dispatch tables
(type / range / enum) plus the two genuinely irregular cases
(marker_fname=False sentinel, ch_names per-element + uniqueness).

Tests: parametrize test_overrides_recover_missing_header_keys across all
seven file-/header-key keys; add validation cases for the three new enum
keys; add test_empty_marker_file_means_no_markers for the spec-compliant
empty-MarkerFile= path.

Author: bruAristimunha

doc/changes/dev/13884.newfeature.rst

@@ -1 +1 @@
-Add ``overrides`` parameter to :func:`mne.io.read_raw_brainvision` for reading non-spec-compliant ``.vhdr`` files where the header contradicts the actual layout (e.g. renamed BIDS siblings, missing ``MarkerFile=``, truncated ``[Channel Infos]``). Accepts a dict with keys ``data_fname``, ``marker_fname``, ``n_channels``, ``sfreq``, ``ch_names``, and ``units_fallback``; see the function docstring for details, by `Bruno Aristimunha`_.
+Add ``overrides`` parameter to :func:`mne.io.read_raw_brainvision` for reading non-spec-compliant ``.vhdr`` files where the header contradicts the actual layout (e.g. renamed BIDS siblings, missing ``MarkerFile=``, truncated ``[Channel Infos]``). Accepts a dict with keys ``data_fname``, ``marker_fname``, ``n_channels``, ``sfreq``, ``ch_names``, ``units_fallback``, ``data_orientation``, ``data_format``, and ``binary_format``; see the function docstring for details. Missing or empty ``MarkerFile=`` is now also tolerated natively (per the BV Core Data Format spec) by `Bruno Aristimunha`_.

mne/io/brainvision/brainvision.py

@@ -22,6 +22,7 @@
 from ...transforms import _sph_to_cart
 from ...utils import (
     _check_dict_keys,
+    _check_option,
     _check_range,
     _DefaultEventParser,
     _validate_type,
@@ -405,6 +406,7 @@ def _check_bv_version(header, kind):
 
 _OVERRIDES_VALID_KEYS = frozenset(
     {"data_fname", "marker_fname", "n_channels", "sfreq", "ch_names", "units_fallback"}
+    | {"data_orientation", "data_format", "binary_format"}
 )
 
 
@@ -416,31 +418,53 @@ def _validate_overrides(overrides):
     _check_dict_keys(
         overrides, _OVERRIDES_VALID_KEYS, "override key(s)", "valid override keys"
     )
-    if "data_fname" in overrides:
-        _validate_type(overrides["data_fname"], "path-like", "overrides['data_fname']")
+
+    def _name(key):
+        return f"overrides['{key}']"
+
+    type_specs = {
+        "data_fname": "path-like",
+        "n_channels": "int-like",
+        "sfreq": "numeric",
+        "ch_names": (list, tuple),
+        "units_fallback": str,
+    }
+    for key, type_ in type_specs.items():
+        if key in overrides:
+            _validate_type(overrides[key], type_, _name(key))
+
+    range_specs = {
+        "n_channels": dict(min_val=1, max_val=np.inf),
+        "sfreq": dict(min_val=0, max_val=np.inf, min_inclusive=False),
+    }
+    for key, kw in range_specs.items():
+        if key in overrides:
+            _check_range(overrides[key], name=_name(key), **kw)
+
+    enum_specs = {
+        "data_orientation": tuple(_orientation_dict),
+        "data_format": ("BINARY", "ASCII"),
+        "binary_format": tuple(_fmt_dict),
+    }
+    for key, allowed in enum_specs.items():
+        if key in overrides:
+            _check_option(_name(key), overrides[key], allowed)
+
+    # marker_fname accepts False as a sentinel for "skip annotations"
     if "marker_fname" in overrides and overrides["marker_fname"] is not False:
         _validate_type(
             overrides["marker_fname"],
             "path-like",
-            "overrides['marker_fname']",
+            _name("marker_fname"),
             extra="(or False to skip annotation reading)",
         )
-    if "n_channels" in overrides:
-        _validate_type(overrides["n_channels"], "int-like", "overrides['n_channels']")
-        _check_range(overrides["n_channels"], 1, np.inf, "overrides['n_channels']")
-    if "sfreq" in overrides:
-        _validate_type(overrides["sfreq"], "numeric", "overrides['sfreq']")
-        _check_range(
-            overrides["sfreq"], 0, np.inf, "overrides['sfreq']", min_inclusive=False
-        )
+    # ch_names: per-element type + uniqueness
     if "ch_names" in overrides:
-        _validate_type(overrides["ch_names"], (list, tuple), "overrides['ch_names']")
         for i, name in enumerate(overrides["ch_names"]):
             _validate_type(name, str, f"overrides['ch_names'][{i}]")
         if len(set(overrides["ch_names"])) != len(overrides["ch_names"]):
             raise ValueError("overrides['ch_names'] must contain unique names")
-    if "units_fallback" in overrides:
-        _validate_type(overrides["units_fallback"], str, "overrides['units_fallback']")
+
     return overrides
 
 
@@ -485,6 +509,27 @@ def _str_to_meas_date(date_str):
     return meas_date
 
 
+_MISSING = object()
+
+
+def _hdr_get(cfg, section, option, overrides, key, *, getter="get", missing=_MISSING):
+    """Read header value or apply ``overrides[key]``; log when overriding."""
+    fn = getattr(cfg, getter)
+    if key in overrides:
+        try:
+            original = fn(section, option)
+        except (configparser.NoOptionError, configparser.NoSectionError):
+            original = "(missing)"
+        logger.info(f"Overriding {option} {original!r} -> {overrides[key]!r}")
+        return overrides[key]
+    try:
+        return fn(section, option)
+    except (configparser.NoOptionError, configparser.NoSectionError):
+        if missing is _MISSING:
+            raise
+        return missing
+
+
 def _aux_hdr_info(hdr_fname):
     """Aux function for _get_hdr_info."""
     with open(hdr_fname, "rb") as f:
@@ -534,7 +579,10 @@ def _aux_hdr_info(hdr_fname):
 
     # get sampling info
     # Sampling interval is given in microsec
-    sfreq = 1e6 / cfg.getfloat(cinfostr, "SamplingInterval")
+    try:
+        sfreq = 1e6 / cfg.getfloat(cinfostr, "SamplingInterval")
+    except configparser.NoOptionError:
+        sfreq = float("nan")  # caller may recover via overrides=dict(sfreq=...)
     info = _empty_info(sfreq)
     info._unlocked = False
     return settings, cfg, cinfostr, info
@@ -597,15 +645,17 @@ def _get_hdr_info(hdr_fname, eog, misc, scale, overrides=None):
     if "sfreq" in overrides:
         logger.info(f"Overriding sfreq {info['sfreq']} -> {overrides['sfreq']} Hz")
         info["sfreq"] = overrides["sfreq"]
+    elif np.isnan(info["sfreq"]):
+        raise configparser.NoOptionError("samplinginterval", cinfostr)
 
-    order = cfg.get(cinfostr, "DataOrientation")
+    order = _hdr_get(cfg, cinfostr, "DataOrientation", overrides, "data_orientation")
     if order not in _orientation_dict:
         raise NotImplementedError(f"Data Orientation {order} is not supported")
     order = _orientation_dict[order]
 
-    data_format = cfg.get(cinfostr, "DataFormat")
+    data_format = _hdr_get(cfg, cinfostr, "DataFormat", overrides, "data_format")
     if data_format == "BINARY":
-        fmt = cfg.get("Binary Infos", "BinaryFormat")
+        fmt = _hdr_get(cfg, "Binary Infos", "BinaryFormat", overrides, "binary_format")
         if fmt not in _fmt_dict:
             raise NotImplementedError(f"Datatype {fmt} is not supported")
         fmt = _fmt_dict[fmt]
@@ -619,26 +669,19 @@ def _get_hdr_info(hdr_fname, eog, misc, scale, overrides=None):
 
     # locate EEG binary file and marker file for the stim channel
     path = op.dirname(hdr_fname)
-    if "data_fname" in overrides:
-        data_fname = op.join(path, overrides["data_fname"])
-        logger.info(
-            f"Overriding DataFile {cfg.get(cinfostr, 'DataFile')!r} -> "
-            f"{overrides['data_fname']!r}"
-        )
-    else:
-        data_fname = op.join(path, cfg.get(cinfostr, "DataFile"))
-
-    if "marker_fname" in overrides:
-        mrk_override = overrides["marker_fname"]
-        header_mrk = cfg.get(cinfostr, "MarkerFile")
-        if mrk_override is False:
-            mrk_fname = None
-            logger.info(f"Overriding MarkerFile {header_mrk!r} -> skipped")
-        else:
-            mrk_fname = op.join(path, mrk_override)
-            logger.info(f"Overriding MarkerFile {header_mrk!r} -> {mrk_override!r}")
+    data_fname = op.join(
+        path, _hdr_get(cfg, cinfostr, "DataFile", overrides, "data_fname")
+    )
+
+    # MarkerFile is optional per BV spec: missing/empty/override=False = no markers
+    if overrides.get("marker_fname") is False:
+        logger.info("Overriding MarkerFile -> skipped")
+        mrk_fname = None
     else:
-        mrk_fname = op.join(path, cfg.get(cinfostr, "MarkerFile"))
+        mrk = _hdr_get(
+            cfg, cinfostr, "MarkerFile", overrides, "marker_fname", missing=""
+        )
+        mrk_fname = op.join(path, mrk) if mrk else None
 
     # Try to get measurement date from marker file
     # Usually saved with a marker "New Segment", see BrainVision documentation
@@ -657,14 +700,9 @@ def _get_hdr_info(hdr_fname, eog, misc, scale, overrides=None):
                 break
 
     # load channel labels
-    if "n_channels" in overrides:
-        nchan = overrides["n_channels"]
-        logger.info(
-            f"Overriding NumberOfChannels "
-            f"{cfg.getint(cinfostr, 'NumberOfChannels')} -> {nchan}"
-        )
-    else:
-        nchan = cfg.getint(cinfostr, "NumberOfChannels")
+    nchan = _hdr_get(
+        cfg, cinfostr, "NumberOfChannels", overrides, "n_channels", getter="getint"
+    )
     if ahdr_format:
         # add one fake channel for ahdr format
         nchan += 1

mne/io/brainvision/tests/test_brainvision.py

@@ -4,6 +4,7 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
+import configparser
 import datetime
 import re
 import shutil
@@ -710,6 +711,9 @@ def test_ignore_marker_types():
         ({"ch_names": ["A", "A", "B"]}, ValueError, "must contain unique names"),
         ({"ch_names": list("abcde")}, ValueError, "length 5 but the file declares"),
         ({"units_fallback": 7}, TypeError, "units_fallback.*str"),
+        ({"data_orientation": "SIDEWAYS"}, ValueError, "Invalid.*data_orientation"),
+        ({"data_format": "PARQUET"}, ValueError, "Invalid.*data_format"),
+        ({"binary_format": "FLOAT_64"}, ValueError, "Invalid.*binary_format"),
     ],
 )
 def test_overrides_validation(overrides, exc, match):
@@ -781,6 +785,63 @@ def test_overrides_file_paths(tmp_path):
     assert raw.info["meas_date"] is None
 
 
+@pytest.mark.parametrize(
+    "key, override, header_key, recoverable, check",
+    [
+        # MarkerFile is optional per BV spec → recoverable without an override
+        (
+            "marker_fname",
+            False,
+            "MarkerFile",
+            True,
+            lambda r: r.info["meas_date"] is None,
+        ),
+        # The rest are spec-required → must be supplied via overrides
+        ("data_fname", "test.eeg", "DataFile", False, lambda r: r.info["nchan"] == 32),
+        ("n_channels", 32, "NumberOfChannels", False, lambda r: r.info["nchan"] == 32),
+        (
+            "sfreq",
+            1000.0,
+            "SamplingInterval",
+            False,
+            lambda r: r.info["sfreq"] == 1000.0,
+        ),
+        ("data_orientation", "MULTIPLEXED", "DataOrientation", False, lambda r: True),
+        ("data_format", "BINARY", "DataFormat", False, lambda r: True),
+        ("binary_format", "INT_16", "BinaryFormat", False, lambda r: True),
+    ],
+)
+def test_overrides_recover_missing_header_keys(
+    tmp_path, key, override, header_key, recoverable, check
+):
+    """Overrides recover when the header is missing the corresponding key."""
+    shutil.copy(eeg_path, tmp_path / "test.eeg")
+    shutil.copy(vmrk_path, tmp_path / "test.vmrk")
+    use_vhdr = tmp_path / f"no_{key}.vhdr"
+    skip = (f"{header_key}=".encode(),)
+    with open(vhdr_path, "rb") as fin, open(use_vhdr, "wb") as fout:
+        fout.writelines(line for line in fin if not line.startswith(skip))
+    if recoverable:
+        assert check(read_raw_brainvision(use_vhdr))
+    else:
+        with pytest.raises(configparser.NoOptionError, match=header_key.lower()):
+            read_raw_brainvision(use_vhdr)
+    assert check(
+        read_raw_brainvision(use_vhdr, overrides={key: override}, preload=True)
+    )
+
+
+def test_empty_marker_file_means_no_markers(tmp_path):
+    """Empty ``MarkerFile=`` value is spec-compliant and means no markers."""
+    shutil.copy(eeg_path, tmp_path / "test.eeg")
+    use_vhdr = tmp_path / "empty_marker.vhdr"
+    with open(vhdr_path, "rb") as fin, open(use_vhdr, "wb") as fout:
+        for line in fin:
+            fout.write(b"MarkerFile=\n" if line.startswith(b"MarkerFile=") else line)
+    raw = read_raw_brainvision(use_vhdr)
+    assert len(raw.annotations) == 0 and raw.info["meas_date"] is None
+
+
 @testing.requires_testing_data
 def test_read_vhdr_annotations_and_events(tmp_path):
     """Test load brainvision annotations and parse them to events."""

mne/utils/docs.py

@@ -600,6 +600,13 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
         Recovers an incomplete ``[Channel Infos]`` section by filling missing
         entries with ``resolution=1.0`` and this unit; missing names become
         ``"Ch<N>"``.
+    ``"data_orientation"`` (``"MULTIPLEXED"`` | ``"VECTORIZED"``)
+        Replaces ``[Common Infos] DataOrientation=``.
+    ``"data_format"`` (``"BINARY"`` | ``"ASCII"``)
+        Replaces ``[Common Infos] DataFormat=``.
+    ``"binary_format"`` (``"INT_16"`` | ``"INT_32"`` | ``"IEEE_FLOAT_32"``)
+        Replaces ``[Binary Infos] BinaryFormat=``. Only consulted when the
+        effective ``DataFormat`` is ``"BINARY"``.
 
     Each applied override is logged at INFO level. Unknown keys raise
     ``ValueError``.