Merge branch 'dev-aifpaif' into pr/152

.github/workflows/publish.yaml

@@ -13,14 +13,18 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Setup Python 3.9
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           architecture: 'x64'
       - name: Install dependencies
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools
-          python -m pip install --progress-bar off .[build]
+          python -m pip install --progress-bar off -e .[build,stubs]
+      - name: Display system information
+        run: pycrostates-sys_info --developer
+      - name: Generate stub files
+        run: python tools/stubgen.py
       - name: Build and publish
         env:
           TWINE_USERNAME: __token__

.github/workflows/pytest.yaml

@@ -27,7 +27,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Setup Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           architecture: 'x64'
@@ -43,12 +43,16 @@ jobs:
         run: |
           curl https://raw.githubusercontent.com/mne-tools/mne-testing-data/master/version.txt -o mne_testing_data_version.txt
       - name: Cache testing dataset
-        uses: actions/cache@v3
+        id: cache
+        uses: actions/cache@v4
         with:
-          key: mne-testing-${{ hashFiles('mne_testing_data_version.txt') }}
+          key: mne-testing-${{ runner.os }}-${{ hashFiles('mne_testing_data_version.txt') }}
           path: ~/mne_data
       - name: Download testing dataset
+        if: steps.cache.outputs.cache-hit != 'true'
         run: python -c "import mne; mne.datasets.testing.data_path(verbose=True)"
+      - name: Remove dataset version file
+        run: rm mne_testing_data_version.txt
       - name: Run pytest
         run: pytest pycrostates --cov=pycrostates --cov-report=xml --cov-config=pyproject.toml
       - name: Upload to codecov
@@ -74,7 +78,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Setup Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           architecture: 'x64'
@@ -83,7 +87,9 @@ jobs:
           python -m pip install --progress-bar off --upgrade pip setuptools
           python -m pip install --progress-bar off .[test]
           python -m pip install --progress-bar off --upgrade git+https://github.com/mne-tools/mne-python
-          python -m pip install --progress-bar off --upgrade --pre --only-binary :all: -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple --timeout=180 numpy scipy scikit-learn matplotlib
+          python -m pip install matplotlib
+          python -m pip install --progress-bar off --upgrade --no-deps --pre --only-binary :all: -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple --timeout=180 matplotlib
+          python -m pip install --progress-bar off --upgrade --pre --only-binary :all: -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple --timeout=180 numpy scipy scikit-learn
       - name: Display system information
         run: pycrostates-sys_info --developer
       - name: Display MNE info
@@ -92,12 +98,16 @@ jobs:
         run: |
           curl https://raw.githubusercontent.com/mne-tools/mne-testing-data/master/version.txt -o mne_testing_data_version.txt
       - name: Cache testing dataset
-        uses: actions/cache@v3
+        id: cache
+        uses: actions/cache@v4
         with:
-          key: mne-testing-${{ hashFiles('mne_testing_data_version.txt') }}
+          key: mne-testing-${{ runner.os }}-${{ hashFiles('mne_testing_data_version.txt') }}
           path: ~/mne_data
       - name: Download testing dataset
+        if: steps.cache.outputs.cache-hit != 'true'
         run: python -c "import mne; mne.datasets.testing.data_path(verbose=True)"
+      - name: Remove dataset version file
+        run: rm mne_testing_data_version.txt
       - name: Run pytest
         run: pytest pycrostates --cov=pycrostates --cov-report=xml --cov-config=pyproject.toml
       - name: Upload to codecov

.github/workflows/stubs.yaml

@@ -0,0 +1,43 @@
+name: stubs
+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:
+
+jobs:
+  generate:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Python 3.9
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9
+          architecture: 'x64'
+      - name: Install package
+        run: |
+          python -m pip install --progress-bar off --upgrade pip setuptools
+          python -m pip install --progress-bar off -e .[stubs]
+      - name: Display system information
+        run: pycrostates-sys_info --developer
+      - 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'
+          if [ -n "$(git status --porcelain)" ]; then
+            git add .
+            git commit -m "deploy stub files [ci skip]"
+            git push
+          fi

.gitignore

@@ -138,3 +138,4 @@ dmypy.json
 # ----------------------------------------------------------------------------
 .DS_Store
 junit-results.xml
+docs/source/sg_execution_times.rst

.pre-commit-config.yaml

@@ -1,32 +1,27 @@
-ci:
-    skip: [codespell, pydocstyle, yamllint]
-
 repos:
     - repo: https://github.com/pycqa/isort
-      rev: 5.12.0
+      rev: 5.13.2
       hooks:
           - id: isort
             files: pycrostates
 
-    - repo: https://github.com/psf/black-pre-commit-mirror
-      rev: 23.10.1
-      hooks:
-          - id: black
-            args: [--quiet]
-            files: pycrostates
-
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.1.4
+      rev: v0.1.14
       hooks:
           - id: ruff
-            args: [--fix, --exit-non-zero-on-fix]
+            name: ruff linter
+            args: [--fix]
+            files: pycrostates
+          - id: ruff-format
+            name: ruff formatter
             files: pycrostates
 
     - repo: https://github.com/codespell-project/codespell
       rev: v2.2.6
       hooks:
           - id: codespell
-            args: [--check-filenames, --ignore-words=.codespellignore, --skip=*.bib]
+            args: [--write-changes]
+            additional_dependencies: [tomli]
 
     - repo: https://github.com/pycqa/pydocstyle
       rev: 6.3.0
@@ -36,7 +31,7 @@ repos:
             additional_dependencies: [tomli]
 
     - repo: https://github.com/mscheltienne/bibclean
-      rev: 0.7.1
+      rev: 0.8.0
       hooks:
           - id: bibclean-fix
             files: docs/references.bib
@@ -49,7 +44,7 @@ repos:
             files: pyproject.toml
 
     - repo: https://github.com/adrienverge/yamllint
-      rev: v1.32.0
+      rev: v1.33.0
       hooks:
           - id: yamllint
             args: [--strict, -c, .yamllint.yaml]

MANIFEST.in

@@ -0,0 +1 @@
+exclude pycrostates/conftest.py

docs/source/conf.py

@@ -275,8 +275,9 @@ def append_attr_meth_examples(app, what, name, obj, options, lines):
 .. _sphx_glr_backreferences_{1}:
 .. rubric:: Examples using ``{0}``:
 .. minigallery:: {1}
-""".format(
-                name.split(".")[-1], name
-            ).split(
-                "\n"
-            )
+""".format(name.split(".")[-1], name).split("\n")
+
+
+# -- sphinx_copybutton -----------------------------------------------------------------
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True

docs/source/install.rst

@@ -40,15 +40,15 @@ Methods
 
         .. code-block:: bash
 
-            pip install pycrostates
+            $ pip install pycrostates
 
     .. tab-item:: Conda
 
         ``pycrostates`` can be installed from `conda-forge <project conda_>`_:
 
         .. code-block:: bash
 
-            conda install -c conda-forge pycrostates
+            $ conda install -c conda-forge pycrostates
 
     .. tab-item:: Snapshot of the current version
 

pycrostates/__init__.py

@@ -1,11 +1,11 @@
 """Pycrostates."""
 
-from . import cluster, datasets, metrics, preprocessing, utils, viz
+from . import cluster, datasets, io, metrics, preprocessing, utils, viz
 from ._version import __version__  # noqa: F401
 from .utils._logs import set_log_level
 from .utils.sys_info import sys_info  # noqa: F401
 
-__all__ = (
+__all__: tuple[str, ...] = (
     "cluster",
     "datasets",
     "metrics",

pycrostates/__init__.pyi

@@ -0,0 +1,12 @@
+from . import cluster as cluster
+from . import datasets as datasets
+from . import io as io
+from . import metrics as metrics
+from . import preprocessing as preprocessing
+from . import utils as utils
+from . import viz as viz
+from ._version import __version__ as __version__
+from .utils._logs import set_log_level as set_log_level
+from .utils.sys_info import sys_info as sys_info
+
+__all__: tuple[str, ...]

pycrostates/_typing.pyi

@@ -0,0 +1,20 @@
+from abc import ABC
+from typing import Optional, Union
+
+from numpy.random import Generator, RandomState
+from numpy.typing import NDArray
+
+class CHData(ABC):
+    """Typing for CHData."""
+
+class CHInfo(ABC):
+    """Typing for CHInfo."""
+
+class Cluster(ABC):
+    """Typing for a clustering class."""
+
+class Segmentation(ABC):
+    """Typing for a clustering class."""
+
+RANDomState = Optional[Union[int, RandomState, Generator]]
+Picks = Optional[Union[str, NDArray[int]]]

pycrostates/cluster/__init__.py

@@ -18,7 +18,7 @@
 from .aahc import AAHCluster  # noqa: F401
 from .kmeans import ModKMeans  # noqa: F401
 
-__all__ = (
+__all__: tuple[str, ...] = (
     "ModKMeans",
     "AAHCluster",
 )

pycrostates/cluster/__init__.pyi

@@ -0,0 +1,5 @@
+from . import utils as utils
+from .aahc import AAHCluster as AAHCluster
+from .kmeans import ModKMeans as ModKMeans
+
+__all__: tuple[str, ...]

pycrostates/cluster/_base.py

@@ -1086,7 +1086,7 @@ def _reject_edge_segments(segmentation: NDArray[int]) -> NDArray[int]:
         segmentation[:n] = -1
 
         # set last segment to unlabeled
-        n = np.flip((segmentation != segmentation[-1])).argmax()
+        n = np.flip(segmentation != segmentation[-1]).argmax()
         segmentation[-n:] = -1
 
         return segmentation