Improve stubs generation (#167)

* improve stubs generation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/stubs.yaml

@@ -3,6 +3,7 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
   cancel-in-progress: true
 on:  # yamllint disable-line rule:truthy
+  pull_request:
   schedule:
     - cron: '0 3 * * *'
   workflow_dispatch:
@@ -35,6 +36,7 @@ jobs:
       - name: Generate stub files
         run: python tools/stubgen.py
       - name: Push stub files
+        if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
         run: |
           git config --global user.name 'github-actions[bot]'
           git config --global user.email 'github-actions[bot]@users.noreply.github.com'

mne_icalabel/annotation/bids.pyi

@@ -33,7 +33,14 @@ def write_components_tsv(ica: ICA, fname: Union[str, Path]):
     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):
+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
@@ -59,4 +66,4 @@ def mark_component(component: int, fname: Union[str, Path], method: str, label:
     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

@@ -3,4 +3,4 @@ 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]
+ICA_LABELS_TO_MNE: dict[str, str]

mne_icalabel/datasets/__init__.pyi

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

mne_icalabel/datasets/icalabel/icalabel.pyi

@@ -5,7 +5,13 @@ 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:
+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
@@ -26,7 +32,7 @@ def data_path(path: Optional[str]=None, force_update: bool=False, update_path: b
         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
@@ -37,4 +43,4 @@ def data_path(path: Optional[str]=None, force_update: bool=False, update_path: b
     -------
     path : Path
         Path to dataset directory.
-    """
+    """

mne_icalabel/features/__init__.pyi

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

mne_icalabel/features/topomap.pyi

@@ -8,7 +8,14 @@ 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]]:
+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
@@ -31,7 +38,7 @@ def get_topomaps(ica: ICA, picks: Incomplete | None=None, res: int=64, image_int
         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
@@ -52,7 +59,14 @@ def get_topomaps(ica: ICA, picks: Incomplete | None=None, res: int=64, image_int
         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]:
+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
@@ -72,7 +86,7 @@ def _get_topomap_array(data: NDArray[float], info: Info, res: int=64, image_inte
         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
@@ -91,4 +105,4 @@ def _get_topomap_array(data: NDArray[float], info: Info, res: int=64, image_inte
     -------
     topomap : array of shape (n_pixels, n_pixels)
         Topographic map array.
-    """
+    """

mne_icalabel/gui/__init__.pyi

@@ -1,6 +1,6 @@
 from mne.preprocessing import ICA
 
-def label_ica_components(inst, ica: ICA, show: bool=True, block: bool=False):
+def label_ica_components(inst, ica: ICA, show: bool = True, block: bool = False):
     """Launch the IC labelling GUI.
 
     Parameters
@@ -19,4 +19,4 @@ def label_ica_components(inst, ica: ICA, show: bool=True, block: bool=False):
     -------
     gui : instance of ICAComponentLabeler
         The graphical user interface (GUI) window.
-    """
+    """

mne_icalabel/gui/_label_components.pyi

@@ -17,15 +17,16 @@ class ICAComponentLabeler(QMainWindow):
     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 __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
@@ -98,4 +99,4 @@ class ICAComponentLabeler(QMainWindow):
 
         Update the labels since the user might have selected one for the
         currently being displayed IC.
-        """
+        """

mne_icalabel/iclabel/__init__.pyi

@@ -1,3 +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
+from .network import run_iclabel as run_iclabel

mne_icalabel/iclabel/_config.pyi

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

mne_icalabel/iclabel/_utils.pyi

@@ -1,7 +1,9 @@
 from mne.io import BaseRaw
 from numpy.typing import ArrayLike, NDArray
 
-def _mne_to_eeglab_locs(raw: BaseRaw, picks: list[str]) -> tuple[NDArray[float], NDArray[float]]:
+def _mne_to_eeglab_locs(
+    raw: BaseRaw, picks: list[str]
+) -> tuple[NDArray[float], NDArray[float]]:
     """Obtain EEGLab-like spherical coordinate from EEG channel positions.
 
     TODO: @JACOB:
@@ -25,7 +27,9 @@ def _mne_to_eeglab_locs(raw: BaseRaw, picks: list[str]) -> tuple[NDArray[float],
         Degree in spherical coordinates of each EEG channel.
     """
 
-def _pol2cart(theta: NDArray[float], rho: NDArray[float]) -> tuple[NDArray[float], NDArray[float]]:
+def _pol2cart(
+    theta: NDArray[float], rho: NDArray[float]
+) -> tuple[NDArray[float], NDArray[float]]:
     """Convert polar coordinates to cartesian coordinates.
 
     Parameters
@@ -39,7 +43,9 @@ def _pol2cart(theta: NDArray[float], rho: NDArray[float]) -> tuple[NDArray[float
 def _next_power_of_2(x) -> int:
     """Equivalent to 2^nextpow2 in MATLAB."""
 
-def _gdatav4(x: ArrayLike, y: ArrayLike, v: ArrayLike, xq: ArrayLike, yq: ArrayLike) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
+def _gdatav4(
+    x: ArrayLike, y: ArrayLike, v: ArrayLike, xq: ArrayLike, yq: ArrayLike
+) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
     """GDATAV4 MATLAB 4 GRIDDATA interpolation.
 
     Parameters
@@ -69,7 +75,9 @@ def _gdatav4(x: ArrayLike, y: ArrayLike, v: ArrayLike, xq: ArrayLike, yq: ArrayL
     Describes interpolation using value of gradient of value in any dimension.
     """
 
-def _mergepoints2D(x: ArrayLike, y: ArrayLike, v: ArrayLike) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
+def _mergepoints2D(
+    x: ArrayLike, y: ArrayLike, v: ArrayLike
+) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
     """Averages values for points that are close to each other.
 
     Parameters
@@ -88,7 +96,9 @@ def _mergepoints2D(x: ArrayLike, y: ArrayLike, v: ArrayLike) -> tuple[ArrayLike,
     v : array
     """
 
-def _mergesimpts(data: ArrayLike, tols: list[ArrayLike], mode: str='average') -> ArrayLike:
+def _mergesimpts(
+    data: ArrayLike, tols: list[ArrayLike], mode: str = "average"
+) -> ArrayLike:
     """
     Parameters
     ----------
@@ -99,4 +109,4 @@ def _mergesimpts(data: ArrayLike, tols: list[ArrayLike], mode: str='average') ->
     Returns
     -------
     array
-    """
+    """

mne_icalabel/iclabel/features.pyi

@@ -52,7 +52,9 @@ def _retrieve_eeglab_icawinv(ica: ICA) -> tuple[NDArray[float], NDArray[float]]:
     weights : array
     """
 
-def _compute_ica_activations(inst: Union[BaseRaw, BaseEpochs], ica: ICA) -> NDArray[float]:
+def _compute_ica_activations(
+    inst: Union[BaseRaw, BaseEpochs], ica: ICA
+) -> NDArray[float]:
     """Compute the ICA activations 'icaact' variable from an MNE ICA instance.
 
     Parameters
@@ -83,25 +85,45 @@ def _compute_ica_activations(inst: Union[BaseRaw, BaseEpochs], ica: ICA) -> NDAr
     average reference.
     """
 
-def _eeg_topoplot(inst: Union[BaseRaw, BaseEpochs], icawinv: NDArray[float], picks: list[str]) -> NDArray[float]:
+def _eeg_topoplot(
+    inst: Union[BaseRaw, BaseEpochs], icawinv: NDArray[float], picks: list[str]
+) -> NDArray[float]:
     """Topoplot feature."""
 
-def _topoplotFast(values: NDArray[float], rd: NDArray[float], th: NDArray[float]) -> NDArray[float]:
+def _topoplotFast(
+    values: NDArray[float], rd: NDArray[float], th: NDArray[float]
+) -> NDArray[float]:
     """Implement topoplotFast.m from MATLAB. Each topographic map is a 32x32 images."""
 
-def _eeg_rpsd(inst: Union[BaseRaw, BaseEpochs], ica: ICA, icaact: NDArray[float]) -> NDArray[float]:
+def _eeg_rpsd(
+    inst: Union[BaseRaw, BaseEpochs], ica: ICA, icaact: NDArray[float]
+) -> NDArray[float]:
     """PSD feature."""
 
-def _eeg_rpsd_constants(inst: Union[BaseRaw, BaseEpochs], ica: ICA) -> tuple[int, int, int, int, NDArray[int], NDArray[float], NDArray[int]]:
+def _eeg_rpsd_constants(
+    inst: Union[BaseRaw, BaseEpochs], ica: ICA
+) -> tuple[int, int, int, int, NDArray[int], NDArray[float], NDArray[int]]:
     """Compute the constants before ``randperm`` is used to compute the subset."""
 
-def _eeg_rpsd_compute_psdmed(inst: Union[BaseRaw, BaseEpochs], icaact: NDArray[float], ncomp: int, nfreqs: int, n_points: int, nyquist: int, index: NDArray[int], window: NDArray[float], subset: NDArray[int]) -> NDArray[float]:
+def _eeg_rpsd_compute_psdmed(
+    inst: Union[BaseRaw, BaseEpochs],
+    icaact: NDArray[float],
+    ncomp: int,
+    nfreqs: int,
+    n_points: int,
+    nyquist: int,
+    index: NDArray[int],
+    window: NDArray[float],
+    subset: NDArray[int],
+) -> NDArray[float]:
     """Compute the variable 'psdmed', annotated as windowed spectrums."""
 
 def _eeg_rpsd_format(psd: NDArray[float]) -> NDArray[float]:
     """Apply the formatting steps after 'eeg_rpsd.m'."""
 
-def _eeg_autocorr_welch(raw: BaseRaw, ica: ICA, icaact: NDArray[float]) -> NDArray[float]:
+def _eeg_autocorr_welch(
+    raw: BaseRaw, ica: ICA, icaact: NDArray[float]
+) -> NDArray[float]:
     """Autocorrelation feature applied on raw object with at least 5 * fs samples.
 
     MATLAB: 'eeg_autocorr_welch.m'.
@@ -113,7 +135,9 @@ def _eeg_autocorr(raw: BaseRaw, ica: ICA, icaact: NDArray[float]) -> NDArray[flo
     MATLAB: 'eeg_autocorr.m'.
     """
 
-def _eeg_autocorr_fftw(epochs: BaseEpochs, ica: ICA, icaact: NDArray[float]) -> NDArray[float]:
+def _eeg_autocorr_fftw(
+    epochs: BaseEpochs, ica: ICA, icaact: NDArray[float]
+) -> NDArray[float]:
     """Autocorrelation feature applied on epoch object.
 
     MATLAB: 'eeg_autocorr_fftw.m'.
@@ -137,4 +161,4 @@ def _resample(ac: NDArray[float], fs: Union[int, float]) -> NDArray[float]:
         Array of shape (n_comp, samples).
     fs : int | float
         Sampling frequency of the MNE instance.
-    """
+    """

mne_icalabel/iclabel/label_components.pyi

@@ -7,7 +7,12 @@ from mne.preprocessing import ICA
 from .features import get_iclabel_features as get_iclabel_features
 from .network import run_iclabel as run_iclabel
 
-def iclabel_label_components(inst: Union[BaseRaw, BaseEpochs], ica: ICA, inplace: bool=True, backend: Optional[str]=None):
+def iclabel_label_components(
+    inst: Union[BaseRaw, BaseEpochs],
+    ica: ICA,
+    inplace: bool = True,
+    backend: Optional[str] = None,
+):
     """Label the provided ICA components with the ICLabel neural network.
 
     ICLabel is designed to classify ICs fitted with an extended infomax ICA
@@ -54,4 +59,4 @@ def iclabel_label_components(inst: Union[BaseRaw, BaseEpochs], ica: ICA, inplace
     References
     ----------
     .. footbibliography::
-    """
+    """

mne_icalabel/iclabel/network/__init__.pyi

@@ -2,7 +2,12 @@ from typing import Optional
 
 from numpy.typing import ArrayLike, NDArray
 
-def run_iclabel(images: ArrayLike, psds: ArrayLike, autocorr: ArrayLike, backend: Optional[str]='pytorch') -> NDArray:
+def run_iclabel(
+    images: ArrayLike,
+    psds: ArrayLike,
+    autocorr: ArrayLike,
+    backend: Optional[str] = "pytorch",
+) -> NDArray:
     """Run the ICLabel network on the provided set of features.
 
     The features are un-formatted and are as-returned by
@@ -26,4 +31,4 @@ def run_iclabel(images: ArrayLike, psds: ArrayLike, autocorr: ArrayLike, backend
         The predicted numerical probability values for all labels in ICLabel output.
         Columns are ordered with ``'Brain'``, ``'Muscle'``, ``'Eye'``,
         ``'Heart'``, ``'Line Noise'``, ``'Channel Noise'``, and ``'Other'``.
-    """
+    """

mne_icalabel/iclabel/network/onnx.pyi

@@ -6,4 +6,4 @@ def _format_input_for_onnx(topo: ArrayLike, psd: ArrayLike, autocorr: ArrayLike)
     """Format the features to the correct shape and type for ONNX."""
 
 def _run_iclabel(images: ArrayLike, psds: ArrayLike, autocorr: ArrayLike) -> NDArray:
-    """Run ICLabel using onnx."""
+    """Run ICLabel using onnx."""