py-neuromodulation 0.0.4__py3-none-any.whl → 0.0.6__py3-none-any.whl

py_neuromodulation/filter/mne_filter.py

@@ -0,0 +1,128 @@
+import numpy as np
+from collections.abc import Sequence
+
+
+class MNEFilter:
+    """mne.filter wrapper
+
+    This class stores for given frequency band ranges the filter
+    coefficients with length "filter_len".
+    The filters can then be used sequentially for band power estimation with
+    apply_filter().
+    Note that this filter can be a bandpass, bandstop, lowpass, or highpass filter
+    depending on the frequency ranges given (see further details in mne.filter.create_filter).
+
+    Parameters
+    ----------
+    f_ranges : list[tuple[float | None, float | None]]
+    sfreq : float
+        Sampling frequency.
+    filter_length : str, optional
+        Filter length. Human readable (e.g. "1000ms", "1s"), by default "999ms"
+    l_trans_bandwidth : float | str, optional
+        Length of the lower transition band or "auto", by default 4
+    h_trans_bandwidth : float | str, optional
+        Length of the higher transition band or "auto", by default 4
+    verbose : bool | None, optional
+        Verbosity level, by default None
+
+    Attributes
+    ----------
+    filter_bank: np.ndarray shape (n,)
+        Factor to upsample by.
+    """
+
+    def __init__(
+        self,
+        f_ranges: Sequence[tuple[float | None, float | None]],
+        sfreq: float,
+        filter_length: str | float = "999ms",
+        l_trans_bandwidth: float | str = 4,
+        h_trans_bandwidth: float | str = 4,
+        verbose: bool | int | str | None = None,
+    ) -> None:
+        from mne.filter import create_filter
+
+        filter_bank = []
+        # mne create_filter function only accepts str and int for filter_length
+        if isinstance(filter_length, float):
+            filter_length = int(filter_length)
+
+        for f_range in f_ranges:
+            try:
+                filt = create_filter(
+                    None,
+                    sfreq,
+                    l_freq=f_range[0],
+                    h_freq=f_range[1],
+                    fir_design="firwin",
+                    l_trans_bandwidth=l_trans_bandwidth,  # type: ignore
+                    h_trans_bandwidth=h_trans_bandwidth,  # type: ignore
+                    filter_length=filter_length,  # type: ignore
+                    verbose=verbose,
+                )
+            except ValueError:
+                filt = create_filter(
+                    None,
+                    sfreq,
+                    l_freq=f_range[0],
+                    h_freq=f_range[1],
+                    fir_design="firwin",
+                    verbose=verbose,
+                    # filter_length=filter_length,
+                )
+            filter_bank.append(filt)
+
+        self.num_filters = len(filter_bank)
+        self.filter_bank = np.vstack(filter_bank)
+
+        self.filters: np.ndarray
+        self.num_channels = -1
+
+    def filter_data(self, data: np.ndarray) -> np.ndarray:
+        """Apply previously calculated (bandpass) filters to data.
+
+        Parameters
+        ----------
+        data : np.ndarray (n_samples, ) or (n_channels, n_samples)
+            Data to be filtered
+        filter_bank : np.ndarray, shape (n_fbands, filter_len)
+            Output of calc_bandpass_filters.
+
+        Returns
+        -------
+        np.ndarray, shape (n_channels, n_fbands, n_samples)
+            Filtered data.
+
+        """
+        from scipy.signal import fftconvolve
+
+        if data.ndim > 2:
+            raise ValueError(
+                f"Data must have one or two dimensions. Got:"
+                f" {data.ndim} dimensions."
+            )
+        if data.ndim == 1:
+            data = np.expand_dims(data, axis=0)
+
+        if self.num_channels == -1:
+            self.num_channels = data.shape[0]
+            self.filters = np.tile(
+                self.filter_bank[None, :, :], (self.num_channels, 1, 1)
+            )
+
+        data_tiled = np.tile(data[:, None, :], (1, self.num_filters, 1))
+
+        filtered = fftconvolve(data_tiled, self.filters, axes=2, mode="same")
+
+        # ensure here that the output dimension matches the input dimension
+        if data.shape[1] != filtered.shape[-1]:
+            # select the middle part of the filtered data
+            middle_index = filtered.shape[-1] // 2
+            filtered = filtered[
+                :,
+                :,
+                middle_index - data.shape[1] // 2 : middle_index + data.shape[1] // 2,
+            ]
+
+        return filtered

py_neuromodulation/filter/notch_filter.py

@@ -0,0 +1,93 @@
+import numpy as np
+from typing import cast
+
+from py_neuromodulation.utils.types import NMPreprocessor
+from py_neuromodulation import logger
+
+
+class NotchFilter(NMPreprocessor):
+    def __init__(
+        self,
+        sfreq: float,
+        line_noise: float | None = None,
+        freqs: np.ndarray | None = None,
+        notch_widths: int | np.ndarray | None = 3,
+        trans_bandwidth: float = 6.8,
+    ) -> None:
+        from mne.filter import create_filter
+
+        if line_noise is None and freqs is None:
+            raise ValueError(
+                "Either line_noise or freqs must be defined if notch_filter is"
+                "activated."
+            )
+
+        if freqs is None:
+            freqs = np.arange(line_noise, sfreq / 2, line_noise, dtype=int)
+
+        if freqs.size > 0 and freqs[-1] >= sfreq / 2:
+            freqs = freqs[:-1]
+
+        # Code is copied from filter.py notch_filter
+        if freqs.size == 0:
+            self.filter_bank = None
+            logger.warning(
+                "WARNING: notch_filter is activated but data is not being"
+                " filtered. This may be due to a low sampling frequency or"
+                " incorrect specifications. Make sure your settings are"
+                f" correct. Got: {sfreq = }, {line_noise = }, {freqs = }."
+            )
+            return
+
+        filter_length = int(sfreq - 1)
+        if notch_widths is None:
+            notch_widths = freqs / 200.0
+        elif np.any(notch_widths < 0):
+            raise ValueError("notch_widths must be >= 0")
+        else:
+            notch_widths = np.atleast_1d(notch_widths)
+            if len(notch_widths) == 1:
+                notch_widths = notch_widths[0] * np.ones_like(freqs)
+            elif len(notch_widths) != len(freqs):
+                raise ValueError(
+                    "notch_widths must be None, scalar, or the " "same length as freqs"
+                )
+        notch_widths = cast(np.ndarray, notch_widths)  # For MyPy only, no runtime cost
+
+        # Speed this up by computing the fourier coefficients once
+        tb_half = trans_bandwidth / 2.0
+        lows = [freq - nw / 2.0 - tb_half for freq, nw in zip(freqs, notch_widths)]
+        highs = [freq + nw / 2.0 + tb_half for freq, nw in zip(freqs, notch_widths)]
+
+        self.filter_bank = create_filter(
+            data=None,
+            sfreq=sfreq,
+            l_freq=highs,
+            h_freq=lows,
+            filter_length=filter_length,  # type: ignore
+            l_trans_bandwidth=tb_half,  # type: ignore
+            h_trans_bandwidth=tb_half,  # type: ignore
+            method="fir",
+            iir_params=None,
+            phase="zero",
+            fir_window="hamming",
+            fir_design="firwin",
+            verbose=False,
+        )
+
+    def process(self, data: np.ndarray) -> np.ndarray:
+        if self.filter_bank is None:
+            return data
+
+        from mne.filter import _overlap_add_filter
+
+        return _overlap_add_filter(
+            x=data,
+            h=self.filter_bank,
+            n_fft=None,
+            phase="zero",
+            picks=None,
+            n_jobs=1,
+            copy=True,
+            pad="reflect_limited",
+        )

py_neuromodulation/grid_cortex.tsv

@@ -1,40 +1,40 @@
-x	y	z
--13.1	-67.7	69.1
--35.5	-60.0	66.0
--48.3	-55.1	58.2
--60.0	-51.8	48.0
--16.9	-51.6	78.0
--34.8	-49.3	71.7
--67.5	-47.1	31.0
--46.1	-43.7	61.1
--59.8	-39.6	53.3
--14.2	-39.1	81.1
--28.3	-31.2	76.0
--42.3	-30.7	70.2
--67.6	-30.1	41.2
--50.5	-24.4	64.4
--14.6	-22.7	80.2
--60.9	-18.7	50.9
--31.6	-16.9	75.2
--5.1	-12.6	77.3
--65.6	-10.8	37.8
--41.8	-10.2	67.0
--55.1	-4.01	53.2
--22.7	1.2	72.0
--5.8	2.8	74.8
--49.2	3.7	54.7
--34.5	3.9	66.5
--61.55	6.2	35.9
--63.6	8.3	25.7
--40.4	11.8	60.7
--48.7	14.5	50.5
--21.8	16.0	68.9
--58.2	18.2	27.3
--7.0	18.4	70.3
--36.3	19.9	59.6
--48.1	24.6	44.0
--56.8	28.52	20.8
--7.3	33.8	61.7
--22.2	35.0	57.2
--36.8	35.4	47.0
--46.8	35.6	36.0
+x	y	z
+-13.1	-67.7	69.1
+-35.5	-60.0	66.0
+-48.3	-55.1	58.2
+-60.0	-51.8	48.0
+-16.9	-51.6	78.0
+-34.8	-49.3	71.7
+-67.5	-47.1	31.0
+-46.1	-43.7	61.1
+-59.8	-39.6	53.3
+-14.2	-39.1	81.1
+-28.3	-31.2	76.0
+-42.3	-30.7	70.2
+-67.6	-30.1	41.2
+-50.5	-24.4	64.4
+-14.6	-22.7	80.2
+-60.9	-18.7	50.9
+-31.6	-16.9	75.2
+-5.1	-12.6	77.3
+-65.6	-10.8	37.8
+-41.8	-10.2	67.0
+-55.1	-4.01	53.2
+-22.7	1.2	72.0
+-5.8	2.8	74.8
+-49.2	3.7	54.7
+-34.5	3.9	66.5
+-61.55	6.2	35.9
+-63.6	8.3	25.7
+-40.4	11.8	60.7
+-48.7	14.5	50.5
+-21.8	16.0	68.9
+-58.2	18.2	27.3
+-7.0	18.4	70.3
+-36.3	19.9	59.6
+-48.1	24.6	44.0
+-56.8	28.52	20.8
+-7.3	33.8	61.7
+-22.2	35.0	57.2
+-36.8	35.4	47.0
+-46.8	35.6	36.0

py_neuromodulation/processing/__init__.py

@@ -0,0 +1,10 @@
+from .artifacts import PARRMArtifactRejection
+from .data_preprocessor import DataPreprocessor
+from .projection import Projection, ProjectionSettings
+from .normalization import FeatureNormalizer, RawNormalizer, NormalizationSettings
+from .resample import Resampler, ResamplerSettings
+from .rereference import ReReferencer
+from .filter_preprocessing import PreprocessingFilter, FilterSettings
+
+# Expose Notch filter also in the processing module, as it is used as a data preprocessing step
+from py_neuromodulation.filter import NotchFilter

py_neuromodulation/{nm_artifacts.py → processing/artifacts.py}

@@ -1,25 +1,29 @@
-from pyparrm import PARRM
-
-
-class PARRMArtifactRejection:
-    def __init__(self, data, sampling_freq, artefact_freq, verbose=False):
-        self.data = data
-        self.sampling_freq = sampling_freq
-        self.artefact_freq = artefact_freq
-        self.verbose = verbose
-
-        self.parrm = PARRM(
-            data=data,
-            sampling_freq=sampling_freq,
-            artefact_freq=artefact_freq,
-            verbose=False,
-        )
-
-    def filter_data(self):
-        self.parrm.find_period()
-        self.parrm.create_filter(
-            filter_direction="both",
-        )
-        filtered_data = self.parrm.filter_data()
-
-        return filtered_data
+class PARRMArtifactRejection:
+    """
+    This module enables training of a PARRM filter before computation,
+    that can in real-time then be applied.
+    https://pyparrm.readthedocs.io/en/stable/
+    """
+    def __init__(self, data, sampling_freq, artefact_freq, verbose=False):
+        from pyparrm import PARRM
+
+        self.data = data
+        self.sampling_freq = sampling_freq
+        self.artefact_freq = artefact_freq
+        self.verbose = verbose
+
+        self.parrm = PARRM(
+            data=data,
+            sampling_freq=sampling_freq,
+            artefact_freq=artefact_freq,
+            verbose=False,
+        )
+
+    def filter_data(self):
+        self.parrm.find_period()
+        self.parrm.create_filter(
+            filter_direction="both",
+        )
+        filtered_data = self.parrm.filter_data()
+
+        return filtered_data

py_neuromodulation/processing/data_preprocessor.py

@@ -0,0 +1,77 @@
+from typing import TYPE_CHECKING, Type
+from py_neuromodulation.utils.types import PreprocessorName, NMPreprocessor
+
+if TYPE_CHECKING:
+    import numpy as np
+    import pandas as pd
+    from py_neuromodulation.stream.settings import NMSettings
+
+PREPROCESSOR_DICT: dict[PreprocessorName, str] = {
+    "preprocessing_filter": "PreprocessingFilter",
+    "notch_filter": "NotchFilter",
+    "raw_resampling": "Resampler",
+    "re_referencing": "ReReferencer",
+    "raw_normalization": "RawNormalizer",
+}
+
+
+class DataPreprocessor:
+    "Class for initializing and holding data preprocessing classes"
+
+    def __init__(
+        self,
+        settings: "NMSettings",
+        channels: "pd.DataFrame",
+        sfreq: float,
+        line_noise: float | None = None,
+    ) -> None:
+        from importlib import import_module
+        from inspect import getfullargspec
+
+        possible_arguments = {
+            "sfreq": sfreq,
+            "settings": settings,
+            "channels": channels,
+            "line_noise": line_noise,
+        }
+
+        for preprocessing_method in settings.preprocessing:
+            if preprocessing_method not in PREPROCESSOR_DICT.keys():
+                raise ValueError(
+                    f"Invalid preprocessing method '{preprocessing_method}'. Must be one of {PREPROCESSOR_DICT.keys()}"
+                )
+
+        # Get needed preprocessor classes from settings
+        preprocessor_classes: dict[str, Type[NMPreprocessor]] = {
+            preprocessor_name: getattr(
+                import_module("py_neuromodulation.processing"), class_name
+            )
+            for preprocessor_name, class_name in PREPROCESSOR_DICT.items()
+            if preprocessor_name in settings.preprocessing
+        }
+
+        # Function to instantiate preprocessor with settings
+        def instantiate_preprocessor(
+            preprocessor_class: Type[NMPreprocessor], preprocessor_name: str
+        ) -> NMPreprocessor:
+            settings_str = f"{preprocessor_name}_settings"
+            # Filter out arguments that are not in the preprocessor's __init__ method
+            args = {
+                arg: possible_arguments[arg]
+                for arg in getfullargspec(preprocessor_class).args
+                if arg in possible_arguments
+            }
+            # Retrieve more possible arguments from settings
+            args |= getattr(settings, settings_str, {})
+            # Pass arguments to preprocessor class and return instance
+            return preprocessor_class(**args)
+
+        self.preprocessors: list[NMPreprocessor] = [
+            instantiate_preprocessor(preprocessor_class, preprocessor_name)
+            for preprocessor_name, preprocessor_class in preprocessor_classes.items()
+        ]
+
+    def process_data(self, data: "np.ndarray") -> "np.ndarray":
+        for preprocessor in self.preprocessors:
+            data = preprocessor.process(data)
+        return data

py_neuromodulation/processing/filter_preprocessing.py

@@ -0,0 +1,78 @@
+import numpy as np
+
+from pydantic import Field
+from typing import TYPE_CHECKING
+
+from py_neuromodulation.utils.types import BoolSelector, FrequencyRange, NMPreprocessor
+
+if TYPE_CHECKING:
+    from py_neuromodulation import NMSettings
+
+
+FILTER_SETTINGS_MAP = {
+    "bandstop_filter": "bandstop_filter_settings",
+    "bandpass_filter": "bandpass_filter_settings",
+    "lowpass_filter": "lowpass_filter_cutoff_hz",
+    "highpass_filter": "highpass_filter_cutoff_hz",
+}
+
+
+class FilterSettings(BoolSelector):
+    bandstop_filter: bool = True
+    bandpass_filter: bool = True
+    lowpass_filter: bool = True
+    highpass_filter: bool = True
+
+    bandstop_filter_settings: FrequencyRange = FrequencyRange(100, 160)
+    bandpass_filter_settings: FrequencyRange = FrequencyRange(2, 200)
+    lowpass_filter_cutoff_hz: float = Field(default=200)
+    highpass_filter_cutoff_hz: float = Field(default=3)
+
+    def get_filter_tuple(self, filter_name) -> tuple[float | None, float | None]:
+        filter_value = self[FILTER_SETTINGS_MAP[filter_name]]
+
+        match filter_name:
+            case "bandstop_filter":
+                return (filter_value.frequency_high_hz, filter_value.frequency_low_hz)
+            case "bandpass_filter":
+                return (filter_value.frequency_low_hz, filter_value.frequency_high_hz)
+            case "lowpass_filter":
+                return (None, filter_value)
+            case "highpass_filter":
+                return (filter_value, None)
+            case _:
+                raise ValueError(
+                    "Filter name must be one of 'bandstop_filter', 'lowpass_filter', "
+                    "'highpass_filter', 'bandpass_filter'"
+                )
+
+
+class PreprocessingFilter(NMPreprocessor):
+    def __init__(self, settings: "NMSettings", sfreq: float) -> None:
+        from py_neuromodulation.filter import MNEFilter
+
+        self.filters: list[MNEFilter] = [
+            MNEFilter(
+                f_ranges=[settings.preprocessing_filter.get_filter_tuple(filter_name)],  # type: ignore
+                sfreq=sfreq,
+                filter_length=sfreq - 1,
+                verbose=False,
+            )
+            for filter_name in settings.preprocessing_filter.get_enabled()
+        ]
+
+    def process(self, data: np.ndarray) -> np.ndarray:
+        """Preprocess data according to the initialized list of PreprocessingFilter objects
+
+        Args:
+            data (numpy ndarray) :
+                shape(n_channels, n_samples) - data to be preprocessed.
+
+        Returns:
+            preprocessed_data (numpy ndarray):
+            shape(n_channels, n_samples) - preprocessed data
+        """
+
+        for filter in self.filters:
+            data = filter.filter_data(data if len(data.shape) == 2 else data[:, 0, :])
+        return data if len(data.shape) == 2 else data[:, 0, :]