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

py_neuromodulation/{nm_filter.py → filter/mne_filter.py}

@@ -1,219 +1,128 @@
-"""Module for filter functionality."""
-
-import numpy as np
-from typing import cast
-from collections.abc import Sequence
-
-from py_neuromodulation.nm_preprocessing import NMPreprocessor
-from py_neuromodulation import logger
-
-from mne.filter import create_filter
-
-
-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:
-        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
-
-
-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:
-        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",
-        )
+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/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,6 +1,3 @@
-from pyparrm import PARRM
-
-
 class PARRMArtifactRejection:
     """
     This module enables training of a PARRM filter before computation,
@@ -8,6 +5,8 @@ class PARRMArtifactRejection:
     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

py_neuromodulation/{nm_preprocessing.py → processing/data_preprocessor.py}

@@ -1,45 +1,37 @@
-from typing import Protocol, TYPE_CHECKING
-from inspect import getfullargspec
-from typing import Type
-from py_neuromodulation.nm_types import ImportDetails, get_class, PreprocessorName
+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.nm_settings import NMSettings
+    from py_neuromodulation.stream.settings import NMSettings
 
-
-class NMPreprocessor(Protocol):
-    def __init__(self, sfreq: float, settings: "NMSettings") -> None: ...
-
-    def process(self, data: "np.ndarray") -> "np.ndarray": ...
-
-
-PREPROCESSOR_DICT: dict[PreprocessorName, ImportDetails] = {
-    "preprocessing_filter": ImportDetails(
-        "nm_filter_preprocessing", "PreprocessingFilter"
-    ),
-    "notch_filter": ImportDetails("nm_filter", "NotchFilter"),
-    "raw_resampling": ImportDetails("nm_resample", "Resampler"),
-    "re_referencing": ImportDetails("nm_rereference", "ReReferencer"),
-    "raw_normalization": ImportDetails("nm_normalization", "RawNormalizer"),
+PREPROCESSOR_DICT: dict[PreprocessorName, str] = {
+    "preprocessing_filter": "PreprocessingFilter",
+    "notch_filter": "NotchFilter",
+    "raw_resampling": "Resampler",
+    "re_referencing": "ReReferencer",
+    "raw_normalization": "RawNormalizer",
 }
 
 
-class NMPreprocessors:
+class DataPreprocessor:
     "Class for initializing and holding data preprocessing classes"
 
     def __init__(
         self,
         settings: "NMSettings",
-        nm_channels: "pd.DataFrame",
+        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,
-            "nm_channels": nm_channels,
+            "channels": channels,
             "line_noise": line_noise,
         }
 
@@ -51,8 +43,10 @@ class NMPreprocessors:
 
         # Get needed preprocessor classes from settings
         preprocessor_classes: dict[str, Type[NMPreprocessor]] = {
-            preprocessor_name: get_class(import_details)
-            for preprocessor_name, import_details in PREPROCESSOR_DICT.items()
+            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
         }
 

py_neuromodulation/{nm_filter_preprocessing.py → processing/filter_preprocessing.py}

@@ -3,11 +3,10 @@ import numpy as np
 from pydantic import Field
 from typing import TYPE_CHECKING
 
-from py_neuromodulation.nm_types import BoolSelector, FrequencyRange
-from py_neuromodulation.nm_preprocessing import NMPreprocessor
+from py_neuromodulation.utils.types import BoolSelector, FrequencyRange, NMPreprocessor
 
 if TYPE_CHECKING:
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
 
 FILTER_SETTINGS_MAP = {
@@ -50,7 +49,7 @@ class FilterSettings(BoolSelector):
 
 class PreprocessingFilter(NMPreprocessor):
     def __init__(self, settings: "NMSettings", sfreq: float) -> None:
-        from py_neuromodulation.nm_filter import MNEFilter
+        from py_neuromodulation.filter import MNEFilter
 
         self.filters: list[MNEFilter] = [
             MNEFilter(

py_neuromodulation/{nm_normalization.py → processing/normalization.py}

@@ -3,11 +3,15 @@
 import numpy as np
 from typing import TYPE_CHECKING, Callable, Literal, get_args
 
-from py_neuromodulation.nm_types import NMBaseModel, Field, NormMethod
-from py_neuromodulation.nm_preprocessing import NMPreprocessor
+from py_neuromodulation.utils.types import (
+    NMBaseModel,
+    Field,
+    NormMethod,
+    NMPreprocessor,
+)
 
 if TYPE_CHECKING:
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
 NormalizerType = Literal["raw", "feature"]
 
@@ -29,7 +33,6 @@ class Normalizer(NMPreprocessor):
         settings: "NMSettings",
         type: NormalizerType,
     ) -> None:
-
         self.type = type
         self.settings: NormalizationSettings
 
@@ -86,7 +89,6 @@ class Normalizer(NMPreprocessor):
         if self.settings.clip:
             data = data.clip(min=-self.settings.clip, max=self.settings.clip)
 
-
         self.previous = self.previous[-self.num_samples_normalize + 1 :]
 
         data = np.nan_to_num(data)
@@ -143,13 +145,13 @@ def norm_median(current, previous):
 
 def norm_zscore(current, previous):
     std = nan_std(previous, axis=0)
-    std[std == 0] = 1 # same behavior as sklearn
+    std[std == 0] = 1  # same behavior as sklearn
     return (current - nan_mean(previous, axis=0)) / std
 
 
 def norm_zscore_median(current, previous):
     std = nan_std(previous, axis=0)
-    std[std == 0] = 1 # same behavior as sklearn
+    std[std == 0] = 1  # same behavior as sklearn
     return (current - nan_median(previous, axis=0)) / std