Function read_forward_solution

mne/forward/forward.py:519–714

Read a forward solution a.k.a. lead field. Parameters ---------- fname : path-like The file name, which should end with ``-fwd.fif``, ``-fwd.fif.gz``, ``_fwd.fif``, ``_fwd.fif.gz``, ``-fwd.h5``, or ``_fwd.h5``. include : list, optional List of names of channe

(fname, include=(), exclude=(), *, ordered=True, verbose=None)

@verbose
def read_forward_solution(fname, include=(), exclude=(), *, ordered=True, verbose=None):
    """Read a forward solution a.k.a. lead field.

    Parameters
    ----------
    fname : path-like
        The file name, which should end with ``-fwd.fif``, ``-fwd.fif.gz``,
        ``_fwd.fif``, ``_fwd.fif.gz``, ``-fwd.h5``, or ``_fwd.h5``.
    include : list, optional
        List of names of channels to include. If empty all channels
        are included.
    exclude : list, optional
        List of names of channels to exclude. If empty include all channels.
    %(ordered)s
    %(verbose)s

    Returns
    -------
    fwd : instance of Forward
        The forward solution.

    See Also
    --------
    write_forward_solution, make_forward_solution

    Notes
    -----
    Forward solutions, which are derived from an original forward solution with
    free orientation, are always stored on disk as forward solution with free
    orientation in X/Y/Z RAS coordinates. To apply any transformation to the
    forward operator (surface orientation, fixed orientation) please apply
    :func:`convert_forward_solution` after reading the forward solution with
    :func:`read_forward_solution`.

    Forward solutions, which are derived from an original forward solution with
    fixed orientation, are stored on disk as forward solution with fixed
    surface-based orientations. Please note that the transformation to
    surface-based, fixed orientation cannot be reverted after loading the
    forward solution with :func:`read_forward_solution`.
    """
    check_fname(
        fname,
        "forward",
        ("-fwd.fif", "-fwd.fif.gz", "_fwd.fif", "_fwd.fif.gz", "-fwd.h5", "_fwd.h5"),
    )
    fname = _check_fname(fname=fname, must_exist=True, overwrite="read")
    #   Open the file, create directory
    logger.info(f"Reading forward solution from {fname}...")
    if fname.suffix == ".h5":
        return _read_forward_hdf5(fname)
    f, tree, _ = fiff_open(fname)
    with f as fid:
        #   Find all forward solutions
        fwds = dir_tree_find(tree, FIFF.FIFFB_MNE_FORWARD_SOLUTION)
        if len(fwds) == 0:
            raise ValueError(f"No forward solutions in {fname}")

        #   Parent MRI data