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

py_neuromodulation/{nm_bispectra.py → features/bispectra.py}

@@ -1,15 +1,18 @@
 from collections.abc import Iterable
 from pydantic import field_validator
-from py_neuromodulation.nm_types import NMBaseModel
 from typing import TYPE_CHECKING, Callable
 
 import numpy as np
 
-from py_neuromodulation.nm_features import NMFeature
-from py_neuromodulation.nm_types import BoolSelector, FrequencyRange
+from py_neuromodulation.utils.types import (
+    NMBaseModel,
+    NMFeature,
+    BoolSelector,
+    FrequencyRange,
+)
 
 if TYPE_CHECKING:
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
 
 class BispectraComponents(BoolSelector):
@@ -67,7 +70,7 @@ class Bispectra(NMFeature):
         self.sfreq = sfreq
         self.ch_names = ch_names
         self.frequency_ranges_hz = settings.frequency_ranges_hz
-        self.settings: BispectraSettings = settings.bispectrum
+        self.settings: BispectraSettings = settings.bispectrum_settings
 
         assert all(
             f_band_bispectrum in settings.frequency_ranges_hz
@@ -93,11 +96,8 @@ class Bispectra(NMFeature):
     def calc_feature(self, data: np.ndarray) -> dict:
         from pybispectra import compute_fft, WaveShape
 
-        # PyBispectra's compute_fft uses PQDM to parallelize the calculation per channel
-        # Is this necessary? Maybe the overhead of parallelization is not worth it
-        # considering that we incur in it once per batch of data
         fft_coeffs, freqs = compute_fft(
-            data=np.expand_dims(data, axis=(0)),
+            data=np.expand_dims(data, axis=0),
             sampling_freq=self.sfreq,
             n_points=data.shape[1],
             verbose=False,
@@ -124,12 +124,11 @@ class Bispectra(NMFeature):
             f1s=tuple(self.settings.f1s),  # type: ignore
             f2s=tuple(self.settings.f2s),  # type: ignore
         )
+        waveshape = waveshape.results.get_results(copy=False)  # can overwrite obj with array
 
         feature_results = {}
         for ch_idx, ch_name in enumerate(self.ch_names):
-            bispectrum = waveshape._bicoherence[
-                ch_idx
-            ]  # Same as waveshape.results._data, skips a copy
+            bispectrum = waveshape[ch_idx]
 
             for component in self.settings.components.get_enabled():
                 spectrum_ch = COMPONENT_DICT[component](bispectrum)

py_neuromodulation/{nm_bursts.py → features/bursts.py}

@@ -8,13 +8,13 @@ from collections.abc import Sequence
 from itertools import product
 
 from pydantic import Field, field_validator
-from py_neuromodulation.nm_types import BoolSelector, NMBaseModel
-from py_neuromodulation.nm_features import NMFeature
+from py_neuromodulation.utils.types import BoolSelector, NMBaseModel, NMFeature
 
 from typing import TYPE_CHECKING, Callable
+from py_neuromodulation.utils.types import create_validation_error
 
 if TYPE_CHECKING:
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
 
 LARGE_NUM = 2**24
@@ -45,7 +45,7 @@ class BurstFeatures(BoolSelector):
     in_burst: bool = True
 
 
-class BurstSettings(NMBaseModel):
+class BurstsSettings(NMBaseModel):
     threshold: float = Field(default=75, ge=0, le=100)
     time_duration_s: float = Field(default=30, ge=0)
     frequency_bands: list[str] = ["low_beta", "high_beta", "low_gamma"]
@@ -56,17 +56,22 @@ class BurstSettings(NMBaseModel):
         return [f.replace(" ", "_") for f in frequency_bands]
 
 
-class Burst(NMFeature):
+class Bursts(NMFeature):
     def __init__(
         self, settings: "NMSettings", ch_names: Sequence[str], sfreq: float
     ) -> None:
         # Test settings
+        settings.validate()
+
+        # Validate that all frequency bands are defined in the settings
         for fband_burst in settings.burst_settings.frequency_bands:
-            assert (
-                fband_burst in list(settings.frequency_ranges_hz.keys())
-            ), f"bursting {fband_burst} needs to be defined in settings['frequency_ranges_hz']"
+            if fband_burst not in list(settings.frequency_ranges_hz.keys()):
+                raise create_validation_error(
+                    f"bursting {fband_burst} needs to be defined in settings['frequency_ranges_hz']",
+                    loc=["burst_settings", "frequency_bands"],
+                )
 
-        from py_neuromodulation.nm_filter import MNEFilter
+        from py_neuromodulation.filter import MNEFilter
 
         self.settings = settings.burst_settings
         self.sfreq = sfreq

py_neuromodulation/{nm_coherence.py → features/coherence.py}

@@ -5,12 +5,16 @@ from collections.abc import Iterable
 from typing import TYPE_CHECKING, Annotated
 from pydantic import Field, field_validator
 
-from py_neuromodulation.nm_features import NMFeature
-from py_neuromodulation.nm_types import BoolSelector, FrequencyRange, NMBaseModel
+from py_neuromodulation.utils.types import (
+    NMFeature,
+    BoolSelector,
+    FrequencyRange,
+    NMBaseModel,
+)
 from py_neuromodulation import logger
 
 if TYPE_CHECKING:
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
 
 class CoherenceMethods(BoolSelector):
@@ -22,7 +26,7 @@ class CoherenceFeatures(BoolSelector):
     mean_fband: bool = True
     max_fband: bool = True
     max_allfbands: bool = True
-
+    
 
 ListOfTwoStr = Annotated[list[str], Field(min_length=2, max_length=2)]
 
@@ -31,6 +35,7 @@ class CoherenceSettings(NMBaseModel):
     features: CoherenceFeatures = CoherenceFeatures()
     method: CoherenceMethods = CoherenceMethods()
     channels: list[ListOfTwoStr] = []
+    nperseg: int = Field(default=128, ge=0)
     frequency_bands: list[str] = Field(default=["high_beta"], min_length=1)
 
     @field_validator("frequency_bands")
@@ -45,6 +50,7 @@ class CoherenceObject:
         window: str,
         fbands: list[FrequencyRange],
         fband_names: list[str],
+        nperseg: int,
         ch_1_name: str,
         ch_2_name: str,
         ch_1_idx: int,
@@ -61,6 +67,7 @@ class CoherenceObject:
         self.ch_2 = ch_2_name
         self.ch_1_idx = ch_1_idx
         self.ch_2_idx = ch_2_idx
+        self.nperseg = nperseg
         self.coh = coh
         self.icoh = icoh
         self.features_coh = features_coh
@@ -75,14 +82,15 @@ class CoherenceObject:
     def get_coh(self, feature_results, x, y):
         from scipy.signal import welch, csd
 
-        self.f, self.Pxx = welch(x, self.sfreq, self.window, nperseg=128)
-        self.Pyy = welch(y, self.sfreq, self.window, nperseg=128)[1]
-        self.Pxy = csd(x, y, self.sfreq, self.window, nperseg=128)[1]
+        self.f, self.Pxx = welch(x, self.sfreq, self.window, nperseg=self.nperseg)
+        self.Pyy = welch(y, self.sfreq, self.window, nperseg=self.nperseg)[1]
+        self.Pxy = csd(x, y, self.sfreq, self.window, nperseg=self.nperseg)[1]
 
         if self.coh:
-            self.coh_val = np.abs(self.Pxy**2) / (self.Pxx * self.Pyy)
+            # XXX: gives different output to abs(Sxy) / sqrt(Sxx * Syy)
+            self.coh_val = np.abs(self.Pxy) ** 2 / (self.Pxx * self.Pyy)
         if self.icoh:
-            self.icoh_val = np.array(self.Pxy / (self.Pxx * self.Pyy)).imag
+            self.icoh_val = self.Pxy.imag / np.sqrt(self.Pxx * self.Pyy)
 
         for coh_idx, coh_type in enumerate([self.coh, self.icoh]):
             if coh_type:
@@ -140,11 +148,11 @@ class CoherenceObject:
         return feature_results
 
 
-class NMCoherence(NMFeature):
+class Coherence(NMFeature):
     def __init__(
         self, settings: "NMSettings", ch_names: list[str], sfreq: float
     ) -> None:
-        self.settings = settings.coherence
+        self.settings = settings.coherence_settings
         self.frequency_ranges_hz = settings.frequency_ranges_hz
         self.sfreq = sfreq
         self.ch_names = ch_names
@@ -176,6 +184,7 @@ class NMCoherence(NMFeature):
                     "hann",
                     fband_specs,
                     fband_names,
+                    self.settings.nperseg,
                     ch_1_name,
                     ch_2_name,
                     ch_1_idx,
@@ -193,7 +202,7 @@ class NMCoherence(NMFeature):
         sfreq: float,
     ):
         flat_channels = [
-            ch for ch_pair in settings.coherence.channels for ch in ch_pair
+            ch for ch_pair in settings.coherence_settings.channels for ch in ch_pair
         ]
 
         valid_coh_channel = [
@@ -203,37 +212,37 @@ class NMCoherence(NMFeature):
             if valid_coh_channel[ch_idx] == 0:
                 raise RuntimeError(
                     f"Coherence selected channel {ch_coh} does not match any channel name: \n"
-                    f"  - settings.coherence.channels: {settings.coherence.channels}\n"
+                    f"  - settings.coherence_settings.channels: {settings.coherence_settings.channels}\n"
                     f"  - ch_names: {ch_names} \n"
                 )
 
             if valid_coh_channel[ch_idx] > 1:
                 raise RuntimeError(
                     f"Coherence selected channel {ch_coh} is ambigous and matches more than one channel name: \n"
-                    f"  - settings.coherence.channels: {settings.coherence.channels}\n"
+                    f"  - settings.coherence_settings.channels: {settings.coherence_settings.channels}\n"
                     f"  - ch_names: {ch_names} \n"
                 )
 
         assert all(
             f_band_coh in settings.frequency_ranges_hz
-            for f_band_coh in settings.coherence.frequency_bands
+            for f_band_coh in settings.coherence_settings.frequency_bands
         ), (
             "coherence selected frequency bands don't match the ones"
             "specified in s['frequency_ranges_hz']"
-            f"coherence frequency bands: {settings.coherence.frequency_bands}"
+            f"coherence frequency bands: {settings.coherence_settings.frequency_bands}"
             f"specified frequency_ranges_hz: {settings.frequency_ranges_hz}"
         )
 
         assert all(
             settings.frequency_ranges_hz[fb][0] < sfreq / 2
             and settings.frequency_ranges_hz[fb][1] < sfreq / 2
-            for fb in settings.coherence.frequency_bands
+            for fb in settings.coherence_settings.frequency_bands
         ), (
             "the coherence frequency band ranges need to be smaller than the Nyquist frequency"
-            f"got sfreq = {sfreq} and fband ranges {settings.coherence.frequency_bands}"
+            f"got sfreq = {sfreq} and fband ranges {settings.coherence_settings.frequency_bands}"
         )
 
-        if not settings.coherence.method.get_enabled():
+        if not settings.coherence_settings.method.get_enabled():
             logger.warn(
                 "feature coherence enabled, but no coherence['method'] selected"
             )

py_neuromodulation/{nm_features.py → features/feature_processor.py}

@@ -1,51 +1,27 @@
-from typing import Protocol, Type, runtime_checkable, TYPE_CHECKING
-from collections.abc import Sequence
-import numpy as np
+from typing import Type, TYPE_CHECKING
 
-if TYPE_CHECKING:
-    from nm_settings import NMSettings
-
-from py_neuromodulation.nm_types import ImportDetails, get_class, FeatureName
-
-
-@runtime_checkable
-class NMFeature(Protocol):
-    def __init__(
-        self, settings: "NMSettings", ch_names: Sequence[str], sfreq: int | float
-    ) -> None: ...
+from py_neuromodulation.utils.types import NMFeature, FeatureName
 
-    def calc_feature(self, data: np.ndarray) -> dict:
-        """
-            Feature calculation method. Each method needs to loop through all channels
-
-        Parameters
-            ----------
-            data : 'np.ndarray'
-                (channels, time)
-            feature_results : dict
-
-            Returns
-            -------
-            dict
-        """
-        ...
-
-
-FEATURE_DICT: dict[FeatureName | str, ImportDetails] = {
-    "raw_hjorth": ImportDetails("nm_hjorth_raw", "Hjorth"),
-    "return_raw": ImportDetails("nm_hjorth_raw", "Raw"),
-    "bandpass_filter": ImportDetails("nm_oscillatory", "BandPower"),
-    "stft": ImportDetails("nm_oscillatory", "STFT"),
-    "fft": ImportDetails("nm_oscillatory", "FFT"),
-    "welch": ImportDetails("nm_oscillatory", "Welch"),
-    "sharpwave_analysis": ImportDetails("nm_sharpwaves", "SharpwaveAnalyzer"),
-    "fooof": ImportDetails("nm_fooof", "FooofAnalyzer"),
-    "nolds": ImportDetails("nm_nolds", "Nolds"),
-    "coherence": ImportDetails("nm_coherence", "NMCoherence"),
-    "bursts": ImportDetails("nm_bursts", "Burst"),
-    "linelength": ImportDetails("nm_linelength", "LineLength"),
-    "mne_connectivity": ImportDetails("nm_mne_connectivity", "MNEConnectivity"),
-    "bispectrum": ImportDetails("nm_bispectra", "Bispectra"),
+if TYPE_CHECKING:
+    import numpy as np
+    from py_neuromodulation import NMSettings
+
+
+FEATURE_DICT: dict[FeatureName | str, str] = {
+    "raw_hjorth": "Hjorth",
+    "return_raw": "Raw",
+    "bandpass_filter": "BandPower",
+    "stft": "STFT",
+    "fft": "FFT",
+    "welch": "Welch",
+    "sharpwave_analysis": "SharpwaveAnalyzer",
+    "fooof": "FooofAnalyzer",
+    "nolds": "Nolds",
+    "coherence": "Coherence",
+    "bursts": "Bursts",
+    "linelength": "LineLength",
+    "mne_connectivity": "MNEConnectivity",
+    "bispectrum": "Bispectra",
 }
 
 
@@ -63,12 +39,13 @@ class FeatureProcessors:
             sfreq (float): sampling frequency in Hz
         """
         from py_neuromodulation import user_features
+        from importlib import import_module
 
         # Accept 'str' for custom features
         self.features: dict[FeatureName | str, NMFeature] = {
-            feature_name: get_class(FEATURE_DICT[feature_name])(
-                settings, ch_names, sfreq
-            )
+            feature_name: getattr(
+                import_module("py_neuromodulation.features"), FEATURE_DICT[feature_name]
+            )(settings, ch_names, sfreq)
             for feature_name in settings.features.get_enabled()
         }
 
@@ -80,12 +57,12 @@ class FeatureProcessors:
 
         Parameters
         ----------
-        feature : nm_features_abc.Feature
+        feature : features_abc.Feature
             New feature to add to feature list
         """
         self.features[feature_name] = feature  # type: ignore
 
-    def estimate_features(self, data: np.ndarray) -> dict:
+    def estimate_features(self, data: "np.ndarray") -> dict:
         """Calculate features, as defined in settings.json
         Features are based on bandpower, raw Hjorth parameters and sharp wave
         characteristics.
@@ -125,7 +102,7 @@ def add_custom_feature(feature_name: str, new_feature: Type[NMFeature]):
         in this file).
     """
     from py_neuromodulation import user_features
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
     user_features[feature_name] = new_feature
     NMSettings._add_feature(feature_name)
@@ -138,7 +115,7 @@ def remove_custom_feature(feature_name: str):
         feature_name (str): Name of the feature to remove
     """
     from py_neuromodulation import user_features
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
     user_features.pop(feature_name)
     NMSettings._remove_feature(feature_name)

py_neuromodulation/{nm_fooof.py → features/fooof.py}

@@ -2,13 +2,16 @@ from collections.abc import Iterable
 import numpy as np
 
 from typing import TYPE_CHECKING
-from py_neuromodulation.nm_types import NMBaseModel
 
-from py_neuromodulation.nm_features import NMFeature
-from py_neuromodulation.nm_types import BoolSelector, FrequencyRange
+from py_neuromodulation.utils.types import (
+    NMBaseModel,
+    NMFeature,
+    BoolSelector,
+    FrequencyRange,
+)
 
 if TYPE_CHECKING:
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
 
 class FooofAperiodicSettings(BoolSelector):
@@ -48,7 +51,7 @@ class FooofAnalyzer(NMFeature):
     def __init__(
         self, settings: "NMSettings", ch_names: Iterable[str], sfreq: float
     ) -> None:
-        self.settings = settings.fooof
+        self.settings = settings.fooof_settings
         self.sfreq = sfreq
         self.ch_names = ch_names
 
@@ -59,12 +62,12 @@ class FooofAnalyzer(NMFeature):
         self.f_vec = np.arange(0, int(self.num_samples / 2) + 1, 1)
 
         assert (
-            settings.fooof.windowlength_ms <= settings.segment_length_features_ms
+            self.settings.windowlength_ms <= settings.segment_length_features_ms
         ), f"fooof windowlength_ms ({settings.fooof.windowlength_ms}) needs to be smaller equal than segment_length_features_ms ({settings.segment_length_features_ms})."
 
         assert (
-            settings.fooof.freq_range_hz[0] < sfreq
-            and settings.fooof.freq_range_hz[1] < sfreq
+            self.settings.freq_range_hz[0] < sfreq
+            and self.settings.freq_range_hz[1] < sfreq
         ), f"fooof frequency range needs to be below sfreq, got {settings.fooof.freq_range_hz}"
 
         from fooof import FOOOFGroup

py_neuromodulation/{nm_hjorth_raw.py → features/hjorth_raw.py}

@@ -5,16 +5,19 @@ Reference:  B Hjorth
             DOI: 10.1016/0013-4694(70)90143-4
 """
 
+from typing import TYPE_CHECKING
 import numpy as np
-from collections.abc import Iterable
+from collections.abc import Sequence
 
-from py_neuromodulation.nm_features import NMFeature
-from py_neuromodulation.nm_settings import NMSettings
+from py_neuromodulation.utils.types import NMFeature
+
+if TYPE_CHECKING:
+    from py_neuromodulation import NMSettings
 
 
 class Hjorth(NMFeature):
     def __init__(
-        self, settings: NMSettings, ch_names: Iterable[str], sfreq: float
+        self, settings: "NMSettings", ch_names: Sequence[str], sfreq: float
     ) -> None:
         self.ch_names = ch_names
 
@@ -40,7 +43,9 @@ class Hjorth(NMFeature):
 
 
 class Raw(NMFeature):
-    def __init__(self, settings: dict, ch_names: Iterable[str], sfreq: float) -> None:
+    def __init__(
+        self, settings: "NMSettings", ch_names: Sequence[str], sfreq: float
+    ) -> None:
         self.ch_names = ch_names
 
     def calc_feature(self, data: np.ndarray) -> dict:

py_neuromodulation/{nm_linelength.py → features/linelength.py}

@@ -1,7 +1,7 @@
 import numpy as np
 from collections.abc import Sequence
 
-from py_neuromodulation.nm_features import NMFeature
+from py_neuromodulation.features.feature_processor import NMFeature
 
 
 class LineLength(NMFeature):

py_neuromodulation/{nm_mne_connectivity.py → features/mne_connectivity.py}

@@ -1,13 +1,11 @@
 from collections.abc import Iterable
 import numpy as np
-import pandas as pd
 from typing import TYPE_CHECKING
 
-from py_neuromodulation.nm_features import NMFeature
-from py_neuromodulation.nm_types import NMBaseModel
+from py_neuromodulation.utils.types import NMFeature, NMBaseModel
 
 if TYPE_CHECKING:
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
     from mne.io import RawArray
     from mne import Epochs
 
@@ -32,8 +30,8 @@ class MNEConnectivity(NMFeature):
         self.sfreq = sfreq
 
         # Params used by spectral_connectivity_epochs
-        self.mode = settings.mne_connectivity.mode
-        self.method = settings.mne_connectivity.method
+        self.mode = settings.mne_connectivity_settings.mode
+        self.method = settings.mne_connectivity_settings.method
 
         self.fbands = settings.frequency_ranges_hz
         self.fband_ranges: list = []
@@ -48,6 +46,7 @@ class MNEConnectivity(NMFeature):
         from mne.io import RawArray
         from mne import Epochs
         from mne_connectivity import spectral_connectivity_epochs
+        import pandas as pd
 
         time_samples_s = data.shape[1] / self.sfreq
         epoch_length: float = 1  # TODO: Make this a parameter?

py_neuromodulation/{nm_nolds.py → features/nolds.py}

@@ -1,16 +1,14 @@
 import numpy as np
 from collections.abc import Iterable
 
-from py_neuromodulation.nm_types import NMBaseModel
 from typing import TYPE_CHECKING
 
-from py_neuromodulation.nm_features import NMFeature
-from py_neuromodulation.nm_types import BoolSelector
+from py_neuromodulation.utils.types import NMFeature, BoolSelector, NMBaseModel
 
 from pydantic import field_validator
 
 if TYPE_CHECKING:
-    from py_neuromodulation.nm_settings import NMSettings
+    from py_neuromodulation import NMSettings
 
 
 class NoldsFeatures(BoolSelector):
@@ -35,16 +33,16 @@ class Nolds(NMFeature):
     def __init__(
         self, settings: "NMSettings", ch_names: Iterable[str], sfreq: float
     ) -> None:
-        self.settings = settings.nolds_features
+        self.settings = settings.nolds_settings
         self.ch_names = ch_names
 
         if len(self.settings.frequency_bands) > 0:
-            from py_neuromodulation.nm_oscillatory import BandPower
+            from py_neuromodulation.features.bandpower import BandPower
 
             self.bp_filter = BandPower(settings, ch_names, sfreq, use_kf=False)
 
         # Check if the selected frequency bands are defined in the global settings
-        for fb in settings.nolds_features.frequency_bands:
+        for fb in settings.nolds_settings.frequency_bands:
             assert (
                 fb in settings.frequency_ranges_hz
             ), f"{fb} selected in nolds_features, but not defined in s['frequency_ranges_hz']"