Aluode/PerceptionLabPortable

1"""Utility functions for spectral and spectrotemporal analysis."""2 3# Authors: The MNE-Python contributors.4# License: BSD-3-Clause5# Copyright the MNE-Python contributors.6 7from inspect import currentframe, getargvalues, signature8 9from ..utils import warn10 11 12def _get_instance_type_string(inst):13    """Get string representation of the originating instance type."""14    from numpy import ndarray15 16    from ..epochs import BaseEpochs17    from ..evoked import Evoked, EvokedArray18    from ..io import BaseRaw19 20    parent_classes = inst._inst_type.__bases__21    if BaseRaw in parent_classes:22        inst_type_str = "Raw"23    elif BaseEpochs in parent_classes:24        inst_type_str = "Epochs"25    elif inst._inst_type in (Evoked, EvokedArray):26        inst_type_str = "Evoked"27    elif inst._inst_type == ndarray:28        inst_type_str = "Array"29    else:30        raise RuntimeError(31            f"Unknown instance type {inst._inst_type} in {type(inst).__name__}"32        )33    return inst_type_str34 35 36def _pop_with_fallback(mapping, key, fallback_fun):37    """Pop from a dict and fallback to a function parameter's default value."""38    fallback = signature(fallback_fun).parameters[key].default39    return mapping.pop(key, fallback)40 41 42def _update_old_psd_kwargs(kwargs):43    """Modify passed-in kwargs to match new API.44 45    NOTE: using plot_raw_psd as fallback (even for epochs) is fine because46    their kwargs are the same (and will stay the same: both are @legacy funcs).47    """48    from ..viz import plot_raw_psd as fallback_fun49 50    may_change = ("axes", "alpha", "ci_alpha", "amplitude", "ci")51    for kwarg in may_change:52        if kwarg in kwargs:53            warn(54                "The legacy plot_psd() method got an unexpected keyword argument "55                f"'{kwarg}', which is a parameter of Spectrum.plot(). Try rewriting as "56                f"object.compute_psd(...).plot(..., {kwarg}=<whatever>)."57            )58    kwargs.setdefault("axes", _pop_with_fallback(kwargs, "ax", fallback_fun))59    kwargs.setdefault("alpha", _pop_with_fallback(kwargs, "line_alpha", fallback_fun))60    kwargs.setdefault(61        "ci_alpha", _pop_with_fallback(kwargs, "area_alpha", fallback_fun)62    )63    est = _pop_with_fallback(kwargs, "estimate", fallback_fun)64    kwargs.setdefault("amplitude", est == "amplitude")65    area_mode = _pop_with_fallback(kwargs, "area_mode", fallback_fun)66    kwargs.setdefault("ci", "sd" if area_mode == "std" else area_mode)67 68 69def _split_psd_kwargs(*, plot_fun=None, kwargs=None):70    from ..io import BaseRaw71    from ..time_frequency import Spectrum72 73    # if no kwargs supplied, get them from calling func74    if kwargs is None:75        frame = currentframe().f_back76        arginfo = getargvalues(frame)77        kwargs = {k: v for k, v in arginfo.locals.items() if k in arginfo.args}78        if arginfo.keywords is not None:  # add in **method_kw79            kwargs.update(arginfo.locals[arginfo.keywords])80 81    # for compatibility with `plot_raw_psd`, `plot_epochs_psd` and82    # `plot_epochs_psd_topomap` functions (not just the instance methods/mixin)83    if "raw" in kwargs:84        kwargs["self"] = kwargs.pop("raw")85    elif "epochs" in kwargs:86        kwargs["self"] = kwargs.pop("epochs")87 88    # `reject_by_annotation` not needed for Epochs or Evoked89    if not isinstance(kwargs.pop("self", None), BaseRaw):90        kwargs.pop("reject_by_annotation", None)91 92    # handle API changes from .plot_psd(...) to .compute_psd(...).plot(...)93    if plot_fun is Spectrum.plot:94        _update_old_psd_kwargs(kwargs)95 96    # split off the plotting kwargs97    plot_kwargs = {98        k: v99        for k, v in kwargs.items()100        if k in signature(plot_fun).parameters and k != "picks"101    }102    for k in plot_kwargs:103        del kwargs[k]104    return kwargs, plot_kwargs105