Function read_source_estimate

mne/source_estimate.py:243–396

Read a source estimate object. Parameters ---------- fname : path-like Path to (a) source-estimate file(s). subject : str | None Name of the subject the source estimate(s) is (are) from. It is good practice to set this attribute to avoid combining inc

(fname, subject=None)

def read_source_estimate(fname, subject=None):
    """Read a source estimate object.

    Parameters
    ----------
    fname : path-like
        Path to (a) source-estimate file(s).
    subject : str | None
        Name of the subject the source estimate(s) is (are) from.
        It is good practice to set this attribute to avoid combining
        incompatible labels and SourceEstimates (e.g., ones from other
        subjects). Note that due to file specification limitations, the
        subject name isn't saved to or loaded from files written to disk.

    Returns
    -------
    stc : SourceEstimate | VectorSourceEstimate | VolSourceEstimate | MixedSourceEstimate
        The source estimate object loaded from file.

    Notes
    -----
     - for volume source estimates, ``fname`` should provide the path to a
       single file named ``'*-vl.stc``` or ``'*-vol.stc'``
     - for surface source estimates, ``fname`` should either provide the
       path to the file corresponding to a single hemisphere (``'*-lh.stc'``,
       ``'*-rh.stc'``) or only specify the asterisk part in these patterns. In
       any case, the function expects files for both hemisphere with names
       following this pattern.
     - for vector surface source estimates, only HDF5 files are supported.
     - for mixed source estimates, only HDF5 files are supported.
     - for single time point ``.w`` files, ``fname`` should follow the same
       pattern as for surface estimates, except that files are named
       ``'*-lh.w'`` and ``'*-rh.w'``.
    """  # noqa: E501
    fname_arg = fname

    # expand `~` without checking whether the file actually exists – we'll
    # take care of that later, as it's complicated by the different suffixes
    # STC files can have
    fname = str(_check_fname(fname=fname, overwrite="read", must_exist=False))

    # make sure corresponding file(s) can be found
    ftype = None
    if op.exists(fname):
        if fname.endswith(("-vl.stc", "-vol.stc", "-vl.w", "-vol.w")):
            ftype = "volume"
        elif fname.endswith(".stc"):
            ftype = "surface"
            if fname.endswith(("-lh.stc", "-rh.stc")):
                fname = fname[:-7]
            else:
                err = (
                    f"Invalid .stc filename: {fname!r}; needs to end with "
                    "hemisphere tag ('...-lh.stc' or '...-rh.stc')"
                )
                raise OSError(err)
        elif fname.endswith(".w"):
            ftype = "w"