roiextract 0.0.2__tar.gz

roiextract-0.0.2/.github/workflows/documentation.yml

@@ -0,0 +1,40 @@
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements_docs.txt
+          pip install -e .
+
+      - name: Sphinx build
+        run: |
+          make html
+
+      - name: Move the generated HTML files
+        run: |
+          cp -a _build/html/ _publish/
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _publish/
+          force_orphan: true

roiextract-0.0.2/.gitignore

@@ -0,0 +1,19 @@
+# Python
+**/__pycache__/
+**/.ipynb_checkpoints
+
+# Build & tools
+build/
+*.egg-info
+.pytest_cache/
+.ruff_cache/
+
+# Docs
+_build/
+docs/generated/
+
+# Tests
+.coverage
+
+# IDEA
+.idea

roiextract-0.0.2/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v3.2.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+  - id: check-added-large-files
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.1.8
+  hooks:
+    # Run the linter.
+    - id: ruff
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format

roiextract-0.0.2/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## Unreleased
+
+## 0.0.2 - January 25th, 2024
+
+### Added
+
+* Estimation of CTF homogeneity
+* Numerical solution for optimizing a combination of CTF ratio and homogeneity
+* Tests to cover the basic functionality
+* Binary search for suggesting lambda_ based on the desired properties
+* SpatialFilter class for storing the result of the optimization
+
+### Changed
+
+* Re-structured the package, split into several files preparing for future extensions (free orientations, data-driven method)
+
+## 0.0.1 - May 8th, 2023
+
+### Added
+
+* Analytic solution for a spatial filter that optimizes a combination of CTF ratio and similarity with a template
+* Structured the code as a Python package

roiextract-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Nikolai Kapralov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roiextract-0.0.2/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = docs
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

roiextract-0.0.2/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.3
+Name: roiextract
+Version: 0.0.2
+Summary: Data-independent and data-driven optimization of extraction of ROI time series based on M/EEG
+Project-URL: Homepage, https://github.com/ctrltz/roiextract
+Project-URL: Bug Tracker, https://github.com/ctrltz/roiextract/issues
+Author-email: Nikolai Kapralov <kapralov@cbs.mpg.de>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Requires-Dist: mne
+Requires-Dist: numpy
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# ROIextract
+
+Optimization of extraction of ROI time series based on the cross-talk function (CTF) or source reconstruction of spatial patterns (REC). **Work in progress!**
+
+## Usage
+
+Obtain a spatial filter that optimizes CTF properties:
+
+```python
+from roiextract import ctf_optimize_label
+
+sf = ctf_optimize_label(fwd, label, template, lambda_)
+
+sf, props = ctf_optimize_label(fwd, label, template, lambda_, quantify=True)
+
+sf = ctf_optimize_label(fwd, label, template, lambda_='auto', threshold=0.95)
+```
+
+Plot the filter as a topomap:
+
+```python
+sf.plot(info)
+```
+
+Apply it to the data to obtain the time course of activity in the ROI/label:
+
+```python
+label_tc = sf.apply(data)
+```
+
+Estimate the CTF for the filter:
+
+```python
+ctf = sf.get_ctf_fwd(fwd)  # ctf is an instance of mne.SourceEstimate
+```
+
+Plot the CTF on the brain surface:
+
+```python
+ctf.plot()
+```

roiextract-0.0.2/README.md

@@ -0,0 +1,41 @@
+# ROIextract
+
+Optimization of extraction of ROI time series based on the cross-talk function (CTF) or source reconstruction of spatial patterns (REC). **Work in progress!**
+
+## Usage
+
+Obtain a spatial filter that optimizes CTF properties:
+
+```python
+from roiextract import ctf_optimize_label
+
+sf = ctf_optimize_label(fwd, label, template, lambda_)
+
+sf, props = ctf_optimize_label(fwd, label, template, lambda_, quantify=True)
+
+sf = ctf_optimize_label(fwd, label, template, lambda_='auto', threshold=0.95)
+```
+
+Plot the filter as a topomap:
+
+```python
+sf.plot(info)
+```
+
+Apply it to the data to obtain the time course of activity in the ROI/label:
+
+```python
+label_tc = sf.apply(data)
+```
+
+Estimate the CTF for the filter:
+
+```python
+ctf = sf.get_ctf_fwd(fwd)  # ctf is an instance of mne.SourceEstimate
+```
+
+Plot the CTF on the brain surface:
+
+```python
+ctf.plot()
+```

roiextract-0.0.2/docs/api.rst

@@ -0,0 +1,18 @@
+API
+===
+
+.. currentmodule:: roiextract.filter
+
+.. autosummary::
+   :toctree: generated
+
+   SpatialFilter
+   apply_batch
+
+
+.. currentmodule:: roiextract.optimize
+
+.. autosummary::
+   :toctree: generated
+
+   ctf_optimize

roiextract-0.0.2/docs/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "ROIextract"
+copyright = "2024, Nikolai Kapralov"
+author = "Nikolai Kapralov"
+release = "0.0.2"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.duration",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]
+
+
+# -- Copybutton settings -----------------------------------------------------
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html#strip-and-configure-input-prompts-for-code-cells
+
+copybutton_exclude = ".linenos, .gp"
+
+
+# -- Autodoc settings --------------------------------------------------------
+
+autodoc_typing_aliases = {
+    "ArrayLike": "numpy.typing.ArrayLike",
+}
+
+
+# -- Intersphinx settings ----------------------------------------------------
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+
+# -- Napoleon settings -------------------------------------------------------
+
+napoleon_numpy_docstring = True

roiextract-0.0.2/docs/index.rst

@@ -0,0 +1,28 @@
+.. ROIextract documentation master file, created by
+   sphinx-quickstart on Fri Mar 22 22:56:38 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to ROIextract's documentation!
+======================================
+
+**ROIextract** is a Python library for extraction of time series of MEG or EEG activity from regions of interest.
+The main focus is on using the *cross-talk function* for quantifying, visualizing and optimizing the remaining field spread.
+Check out the :doc:`usage` section for further information, including how to :ref:`install <installation>` the project.
+
+.. note::
+
+   This project is under active development, current API may still change.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+Contents
+--------
+
+.. toctree::
+
+   usage
+   api

roiextract-0.0.2/docs/usage.rst

@@ -0,0 +1,13 @@
+Usage
+=====
+
+.. _installation:
+
+Installation
+------------
+
+To use ROIextract, first install it using pip in your virtual environment:
+
+.. code-block:: console
+
+   (.venv) $ pip install roiextract

roiextract-0.0.2/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=docs
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

roiextract-0.0.2/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roiextract"
+version = "0.0.2"
+authors = [
+    { name="Nikolai Kapralov", email="kapralov@cbs.mpg.de" }
+]
+description = "Data-independent and data-driven optimization of extraction of ROI time series based on M/EEG"
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy",
+    "mne",
+    "scipy"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/ctrltz/roiextract"
+"Bug Tracker" = "https://github.com/ctrltz/roiextract/issues"
+
+[tool.ruff]
+line-length = 80
+indent-width = 4

roiextract-0.0.2/requirements.txt

@@ -0,0 +1,4 @@
+numpy
+mne
+pre-commit
+scipy

roiextract-0.0.2/requirements_docs.txt

@@ -0,0 +1,3 @@
+furo
+sphinx
+sphinx-copybutton

roiextract-0.0.2/requirements_testing.txt

@@ -0,0 +1,3 @@
+mock
+pytest
+pytest-cov

roiextract-0.0.2/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

roiextract-0.0.2/src/roiextract/__init__.py

@@ -0,0 +1,6 @@
+try:
+    from importlib.metadata import version
+
+    __version__ = version("roiextract")
+except Exception:
+    __version__ = "Failed to determine the version"

roiextract-0.0.2/src/roiextract/analytic.py

@@ -0,0 +1,73 @@
+import numpy as np
+
+from numpy.linalg import norm
+from scipy.linalg import eig
+
+
+def ctf_optimize_ratio_similarity(
+    leadfield, template, mask, lambda_, regA=0.001, regB=0.001
+):
+    """
+    Optimize a linear combination of similarity with a template CTF and
+    within/outside CTF ratio
+
+    Parameters
+    ----------
+    leadfield: array_like
+        Lead field matrix for dipoles with fixed orientation with shape
+        (channels, voxels).
+    template: array_like
+        Template CTF pattern for voxels with shape (voxels,). Only values
+        within the ROI are used.
+    mask: array_like
+        Voxel mask of the region of interest with shape (voxels,). Contains
+        ones and zeros for voxels within and outside ROI, respectively.
+    lambda_: float
+        If 0, only ratio is optimized. If 1, only similarity. Values in between
+        allow tweaking the balance between optimization for similarity or ratio.
+    regA, regB: float
+        Regularization parameters to ensure that it is possible to calculate the
+        inverse matrices.
+
+    Returns
+    -------
+    w: array
+        Spatial filter produced by the optimization.
+
+    Raises
+    ------
+    ValueError
+        If the provided lambda_ value is out of [0, 1] range.
+    """
+    if lambda_ > 1.0 or lambda_ < 0.0:
+        raise ValueError("Value of lambda_ should lie in [0, 1] range")
+
+    # Make sure w0 is a row vector with unit length
+    template = np.atleast_1d(np.squeeze(template))
+    if template.ndim > 1:
+        raise ValueError(
+            f"Template weights should be a vector, got "
+            f"{template.ndim} dimensions instead"
+        )
+    template = template / norm(template)
+    template = template[np.newaxis, :]
+
+    # Split lead field matrix into in and out parts
+    L_in = leadfield[:, mask]
+    L_out = leadfield[:, ~mask]
+
+    # Solve the generalized eigenvalue problem
+    A_rat = L_out @ L_out.T
+    A_sim = L_in @ (template.T @ template) @ L_in.T
+    A = (1 - lambda_) * A_rat - lambda_ * A_sim
+    A_reg = A + regA * np.trace(A) * np.eye(*A.shape) / A.shape[0]
+    B = L_in @ L_in.T
+    B_reg = B + regB * np.trace(B) * np.eye(*B.shape) / B.shape[0]
+    [eigvals, eigvecs] = eig(A_reg, B_reg)
+
+    # Get the eigenvector that corresponds to the smallest eigenvalue
+    w = eigvecs[:, eigvals.argmin()]
+    if np.dot(w @ L_in, template.T) < 0:
+        w *= -1
+
+    return w