deploy stub files [ci skip]

mne_icalabel/__init__.pyi

@@ -0,0 +1,10 @@
+from . import annotation as annotation
+from . import config as config
+from . import datasets as datasets
+from . import features as features
+from . import gui as gui
+from . import iclabel as iclabel
+from . import utils as utils
+from ._version import __version__ as __version__
+from .label_components import label_components as label_components
+from .utils.config import sys_info as sys_info

mne_icalabel/annotation/__init__.pyi

@@ -0,0 +1,2 @@
+from .bids import mark_component as mark_component
+from .bids import write_components_tsv as write_components_tsv

mne_icalabel/annotation/bids.pyi

@@ -0,0 +1,62 @@
+from pathlib import Path as Path
+from typing import Union
+
+from mne.preprocessing import ICA
+
+from ..config import ICA_LABELS_TO_MNE as ICA_LABELS_TO_MNE
+from ..iclabel._config import ICLABEL_STRING_TO_NUMERICAL as ICLABEL_STRING_TO_NUMERICAL
+from ..utils._imports import import_optional_dependency as import_optional_dependency
+
+def write_components_tsv(ica: ICA, fname: Union[str, Path]):
+    """Write channels tsv file for ICA components.
+
+    Will create an accompanying JSON sidecar to explain the
+    additional columns created in the channels tsv file for the
+    ICA component labeling.
+
+    Parameters
+    ----------
+    ica : ICA
+        An instance of the fitted ICA.
+    fname : str | Path
+        The output filename.
+
+    Notes
+    -----
+    Components are stored in a ``.tsv`` file essentially in the same manner as
+    ``channels.tsv`` files for BIDS-EEG data. For more information, see the
+    `BIDS specification <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/03-electroencephalography.html#channels-description-_channelstsv>`_
+    for EEG channels metadata.
+
+    Storage of ICA annotations as a ``.tsv`` file is currently experimental in the
+    context of BIDS-EEG Derivatives. The API and functionality is subject to change
+    as the community converges on the specification of BIDS-Derivatives.
+    """
+
+def mark_component(component: int, fname: Union[str, Path], method: str, label: str, author: str, strict_label: bool=True):
+    """Mark a component with a label.
+
+    Parameters
+    ----------
+    component : int
+        The component to mark.
+    fname : Union[str, Path]
+        The filename for the BIDS filepath.
+    method : str
+        The method to use. Must be 'manual', or one of ['iclabel'].
+    label : str
+        The label of the ICA component. Must be one of ['brain',
+        'muscle artifact', 'eye blink', 'heart beat', 'line noise',
+        'channel noise', 'other'].
+    author : str
+        The annotating author.
+    strict_label : bool
+        Whether to raise an error if ``label`` is not an accepted value.
+        Default is True.
+
+    Notes
+    -----
+    Storage of ICA annotations as a ``.tsv`` file is currently experimental in the
+    context of BIDS-EEG Derivatives. The API and functionality is subject to change
+    as the community converges on the specification of BIDS-Derivatives.
+    """

mne_icalabel/config.pyi

@@ -0,0 +1,6 @@
+from typing import Callable, Optional
+
+from .iclabel import iclabel_label_components as iclabel_label_components
+
+ICALABEL_METHODS: dict[str, Optional[Callable]]
+ICA_LABELS_TO_MNE: dict[str, str]

mne_icalabel/datasets/__init__.pyi

@@ -0,0 +1 @@
+from . import icalabel as icalabel

mne_icalabel/datasets/icalabel/__init__.pyi

@@ -0,0 +1,2 @@
+from .icalabel import data_path as data_path
+from .icalabel import has_icalabel_testing_data as has_icalabel_testing_data

mne_icalabel/datasets/icalabel/icalabel.pyi

@@ -0,0 +1,40 @@
+from pathlib import Path
+from typing import Optional
+
+from _typeshed import Incomplete
+
+has_icalabel_testing_data: Incomplete
+
+def data_path(path: Optional[str]=None, force_update: bool=False, update_path: bool=True, download: bool=True, verbose: Incomplete | None=None) -> Path:
+    """ICA label testing data generated in conjunction with EEGLab.
+
+    Parameters
+    ----------
+    path : None | str
+        Location of where to look for the dataset.
+        If None, the environment variable or config parameter is used.
+        If it doesn’t exist, the “~/mne_data” directory is used.
+        If the dataset is not found under the given path,
+        the data will be automatically downloaded to the specified folder.
+    force_update : bool
+        Force update of the dataset even if a local copy exists.
+    update_path : bool
+        If True, set the MNE_DATASETS_FNIRSMOTORGROUP_PATH in
+        mne-python config to the given path.
+    download : bool
+        If False and the dataset has not been downloaded yet,
+        it will not be downloaded and the path will be returned
+        as ‘’ (empty string). This is mostly used for debugging purposes
+        and can be safely ignored by most users.
+    
+    verbose : bool | str | int | None
+        Control verbosity of the logging output. If ``None``, use the default
+        verbosity level. See the :ref:`logging documentation <tut-logging>` and
+        :func:`mne.verbose` for details. Should only be passed as a keyword
+        argument.
+
+    Returns
+    -------
+    path : Path
+        Path to dataset directory.
+    """

mne_icalabel/features/__init__.pyi

@@ -0,0 +1 @@
+from .topomap import get_topomaps as get_topomaps

mne_icalabel/features/topomap.pyi

@@ -0,0 +1,94 @@
+from typing import Union
+
+from _typeshed import Incomplete
+from mne import Info
+from mne.preprocessing import ICA
+from numpy.typing import NDArray
+
+from ..utils._checks import _validate_ica as _validate_ica
+from ..utils._docs import fill_doc as fill_doc
+
+def get_topomaps(ica: ICA, picks: Incomplete | None=None, res: int=64, image_interp: str=..., border: Union[float, str]=..., extrapolate: str=...) -> dict[str, NDArray[float]]:
+    """Generate an array of scalp topographies for the picked components.
+
+    Parameters
+    ----------
+    ica : ICA
+        MNE `~mne.preprocessing.ICA` decomposition.
+    picks : int | list of int | slice | None
+        Indices of the independent components (ICs) to select.
+        If an integer, represents the index of the IC to pick.
+        Multiple ICs can be selected using a list of int or a slice.
+        The indices are 0-indexed, so ``picks=1`` will pick the second IC: ``ICA001``.
+        ``None`` (default) will pick all independent components in the order fitted.
+    res : int
+        The resolution of the square topographic map (in pixels).
+    image_interp : str
+        The image interpolation to be used. All matplotlib options are
+        accepted.
+    border : float | 'mean'
+        Value to extrapolate to on the topomap borders. If ``'mean'`` (default),
+        then each extrapolated point has the average value of its neighbours.
+    extrapolate : str
+        Options:
+    
+        - ``'box'``
+            Extrapolate to four points placed to form a square encompassing all
+            data points, where each side of the square is three times the range
+            of the data in the respective dimension.
+        - ``'local'`` (default for MEG sensors)
+            Extrapolate only to nearby points (approximately to points closer than
+            median inter-electrode distance). This will also set the
+            mask to be polygonal based on the convex hull of the sensors.
+        - ``'head'`` (default for non-MEG sensors)
+            Extrapolate out to the edges of the clipping circle. This will be on
+            the head circle when the sensors are contained within the head circle,
+            but it can extend beyond the head when sensors are plotted outside
+            the head circle.
+
+    Returns
+    -------
+    topomaps : dict of array of shape (n_components, n_pixels, n_pixels)
+        Dictionary of ICs topographic maps for each channel type.
+    """
+
+def _get_topomap_array(data: NDArray[float], info: Info, res: int=64, image_interp: str=..., border: Union[float, str]=..., extrapolate: str=...) -> NDArray[float]:
+    """Generate a scalp topographic map (n_pixels, n_pixels).
+
+    Parameters
+    ----------
+    data : array of shape (n_channels,)
+        The data points used to generate the topographic map.
+    info : Info
+        Instance of `mne.Info` with the montage associated with the ``(n_channels,)``
+        points.
+    res : int
+        The resolution of the square topographic map (in pixels).
+    image_interp : str
+        The image interpolation to be used. All matplotlib options are
+        accepted.
+    border : float | 'mean'
+        Value to extrapolate to on the topomap borders. If ``'mean'`` (default),
+        then each extrapolated point has the average value of its neighbours.
+    extrapolate : str
+        Options:
+    
+        - ``'box'``
+            Extrapolate to four points placed to form a square encompassing all
+            data points, where each side of the square is three times the range
+            of the data in the respective dimension.
+        - ``'local'`` (default for MEG sensors)
+            Extrapolate only to nearby points (approximately to points closer than
+            median inter-electrode distance). This will also set the
+            mask to be polygonal based on the convex hull of the sensors.
+        - ``'head'`` (default for non-MEG sensors)
+            Extrapolate out to the edges of the clipping circle. This will be on
+            the head circle when the sensors are contained within the head circle,
+            but it can extend beyond the head when sensors are plotted outside
+            the head circle.
+
+    Returns
+    -------
+    topomap : array of shape (n_pixels, n_pixels)
+        Topographic map array.
+    """

mne_icalabel/gui/__init__.pyi

@@ -0,0 +1,22 @@
+from mne.preprocessing import ICA
+
+def label_ica_components(inst, ica: ICA, show: bool=True, block: bool=False):
+    """Launch the IC labelling GUI.
+
+    Parameters
+    ----------
+    inst : Raw | Epochs
+        `~mne.io.Raw` or `~mne.Epochs` instance used to fit the `~mne.preprocessing.ICA`
+        decomposition.
+    ica : ICA
+        The ICA object fitted on ``inst``.
+    show : bool
+        Show the GUI if True.
+    block : bool
+        Whether to halt program execution until the figure is closed.
+
+    Returns
+    -------
+    gui : instance of ICAComponentLabeler
+        The graphical user interface (GUI) window.
+    """

mne_icalabel/gui/_label_components.pyi

@@ -0,0 +1,101 @@
+from typing import Union
+
+from _typeshed import Incomplete
+from mne import BaseEpochs
+from mne.io import BaseRaw
+from mne.preprocessing import ICA
+from qtpy.QtWidgets import QMainWindow
+
+from mne_icalabel.config import ICA_LABELS_TO_MNE as ICA_LABELS_TO_MNE
+
+class ICAComponentLabeler(QMainWindow):
+    """Qt GUI to annotate components.
+
+    Parameters
+    ----------
+    inst : Raw | Epochs
+    ica : ICA
+    show : bool
+    """
+    _inst: Incomplete
+    _ica: Incomplete
+    _labels: Incomplete
+    selected_labels: Incomplete
+    _selected_component: int
+
+    def __init__(self, inst: Union[BaseRaw, BaseEpochs], ica: ICA, show: bool=True) -> None:
+        ...
+
+    def _save_labels(self) -> None:
+        """Save the selected labels to the ICA instance."""
+    _central_widget: Incomplete
+    _components_listWidget: Incomplete
+    _labels_buttonGroup: Incomplete
+    _mpl_figures: Incomplete
+    _mpl_widgets: Incomplete
+    _timeSeries_widget: Incomplete
+
+    def _load_ui(self) -> None:
+        """Prepare the GUI.
+
+        Widgets
+        -------
+        self._components_listWidget
+        self._labels_buttonGroup
+        self._mpl_widgets (dict)
+            - topomap
+            - psd
+        self._timeSeries_widget
+
+        Matplotlib figures
+        ------------------
+        self._mpl_figures (dict)
+            - topomap
+            - psd
+        """
+
+    @staticmethod
+    def _check_inst_ica(inst: Union[BaseRaw, BaseEpochs], ica: ICA) -> None:
+        """Check if the ICA was fitted."""
+
+    @property
+    def inst(self) -> Union[BaseRaw, BaseEpochs]:
+        """Instance on which the ICA has been fitted."""
+
+    @property
+    def ica(self) -> ICA:
+        """Fitted ICA decomposition."""
+
+    @property
+    def n_components_(self) -> int:
+        """The number of fitted components."""
+
+    @property
+    def labels(self) -> list[str]:
+        """List of valid labels."""
+
+    @property
+    def selected_component(self) -> int:
+        """IC selected and displayed."""
+
+    def _connect_signals_to_slots(self) -> None:
+        """Connect all the signals and slots of the GUI."""
+
+    def _components_listWidget_clicked(self) -> None:
+        """Update the plots and the saved labels accordingly."""
+
+    def _update_selected_labels(self) -> None:
+        """Update the labels saved."""
+
+    def _reset(self) -> None:
+        """Action of the reset button."""
+
+    def _reset_buttons(self) -> None:
+        """Reset all buttons."""
+
+    def closeEvent(self, event) -> None:
+        """Clean up upon closing the window.
+
+        Update the labels since the user might have selected one for the
+        currently being displayed IC.
+        """

mne_icalabel/iclabel/__init__.pyi

@@ -0,0 +1,3 @@
+from .features import get_iclabel_features as get_iclabel_features
+from .label_components import iclabel_label_components as iclabel_label_components
+from .network import run_iclabel as run_iclabel

mne_icalabel/iclabel/_config.pyi

@@ -0,0 +1,2 @@
+ICLABEL_NUMERICAL_TO_STRING: dict[int, str]
+ICLABEL_STRING_TO_NUMERICAL: dict[str, int]