py-neuromodulation 0.0.6__tar.gz → 0.0.7__tar.gz

{py_neuromodulation-0.0.6 → py_neuromodulation-0.0.7}/.github/workflows/python-publish.yml

@@ -3,7 +3,7 @@ name: Publish Python Package
 on:
   push:
     tags:
-      - 'v*'  # Only trigger on tag pushes like v1.0.0
+      - 'v[0-9]+.[0-9]+.[0-9]+'
 
 jobs:
   publish:

{py_neuromodulation-0.0.6 → py_neuromodulation-0.0.7}/.gitignore

@@ -194,3 +194,6 @@ out_per
 
 gui_dev/node_modules/*
 test/data/*
+
+uv.lock
+lsllog.txt

{py_neuromodulation-0.0.6 → py_neuromodulation-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: py_neuromodulation
-Version: 0.0.6
+Version: 0.0.7
 Summary: Real-time analysis of intracranial neurophysiology recordings.
 Project-URL: bugtracker, https://github.com/neuromodulation/py_neuromodulation/issues
 Project-URL: repository, https://github.com/neuromodulation/py_neuromodulation
@@ -36,20 +36,21 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Requires-Dist: fooof
 Requires-Dist: joblib>=1.3.2
+Requires-Dist: llvmlite>=0.43.0
 Requires-Dist: matplotlib>=3.9.0
 Requires-Dist: mne
 Requires-Dist: mne-bids>=0.8
 Requires-Dist: mne-connectivity
 Requires-Dist: mne-lsl>=1.2.0
 Requires-Dist: mrmr-selection
-Requires-Dist: nolds
+Requires-Dist: nolds>=0.6.1
+Requires-Dist: numba>=0.60.0
 Requires-Dist: numpy>=1.21.2
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: pyarrow>=14.0.2
 Requires-Dist: pybispectra>=1.2.0
 Requires-Dist: pydantic>=2.7.3
 Requires-Dist: pyparrm
-Requires-Dist: pyqt5
 Requires-Dist: scikit-learn>=0.24.2
 Requires-Dist: scikit-optimize
 Requires-Dist: scipy>=1.7.1
@@ -108,7 +109,7 @@ The original intention for writing this toolbox was movement decoding from invas
 The application however could be any neural decoding problem.
 *py_neuromodulation* offers wrappers around common practice machine learning methods for efficient analysis.
 
-Find the documentation here http://py-neuromodulation.readthedocs.io for example usage and parametrization.
+Find the documentation here neuromodulation.github.io/py_neuromodulation/ for example usage and parametrization.
 
 Installation
 ============
@@ -119,25 +120,15 @@ py_neuromodulation requires at least python 3.10. For installation you can use p
 
     pip install py-neuromodulation
 
-Alternatively you can also install the package in a conda environment:
+Alternatively you can also clone the pacakge and install it using `uv <https://docs.astral.sh/uv/>`_:
 
 .. code-block::
 
-    conda create -n pynm-test python=3.11
-    conda activate pynm-test
+    uv python install 3.10
+    uv venv
+    . .venv/bin/activate
+    uv sync
 
-Then install the packages listed in the `pyproject.toml`:
-
-.. code-block::
-
-    pip install .
-
-
-Optionally the ipython kernel can be specified for the installed pynm-test conda environment:
-
-.. code-block::
-
-    ipython kernel install --user --name=pynm-test
 
 Then *py_neuromodulation* can be imported via:
 

{py_neuromodulation-0.0.6 → py_neuromodulation-0.0.7}/README.rst

@@ -29,7 +29,7 @@ The original intention for writing this toolbox was movement decoding from invas
 The application however could be any neural decoding problem.
 *py_neuromodulation* offers wrappers around common practice machine learning methods for efficient analysis.
 
-Find the documentation here http://py-neuromodulation.readthedocs.io for example usage and parametrization.
+Find the documentation here neuromodulation.github.io/py_neuromodulation/ for example usage and parametrization.
 
 Installation
 ============
@@ -40,25 +40,15 @@ py_neuromodulation requires at least python 3.10. For installation you can use p
 
     pip install py-neuromodulation
 
-Alternatively you can also install the package in a conda environment:
+Alternatively you can also clone the pacakge and install it using `uv <https://docs.astral.sh/uv/>`_:
 
 .. code-block::
 
-    conda create -n pynm-test python=3.11
-    conda activate pynm-test
+    uv python install 3.10
+    uv venv
+    . .venv/bin/activate
+    uv sync
 
-Then install the packages listed in the `pyproject.toml`:
-
-.. code-block::
-
-    pip install .
-
-
-Optionally the ipython kernel can be specified for the installed pynm-test conda environment:
-
-.. code-block::
-
-    ipython kernel install --user --name=pynm-test
 
 Then *py_neuromodulation* can be imported via:
 

{py_neuromodulation-0.0.6 → py_neuromodulation-0.0.7}/py_neuromodulation/default_settings.yaml

@@ -193,6 +193,7 @@ coherence_settings:
   method:
     coh: true
     icoh: true
+  nperseg: 128
 
 fooof_settings:
   aperiodic:

{py_neuromodulation-0.0.6 → py_neuromodulation-0.0.7}/py_neuromodulation/features/bispectra.py

@@ -96,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,
@@ -127,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-0.0.6 → py_neuromodulation-0.0.7}/py_neuromodulation/features/coherence.py

@@ -26,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)]
 
@@ -35,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")
@@ -49,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,
@@ -65,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
@@ -79,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:
@@ -180,6 +184,7 @@ class Coherence(NMFeature):
                     "hann",
                     fband_specs,
                     fband_names,
+                    self.settings.nperseg,
                     ch_1_name,
                     ch_2_name,
                     ch_1_idx,

{py_neuromodulation-0.0.6 → py_neuromodulation-0.0.7}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["hatchling"]
 
 [project]
 name = "py_neuromodulation"
-version = "0.0.6"
+version = "0.0.7"
 authors = [{ name = "Timon Merk", email = "timon.merk@charite.de" }]
 classifiers = [
   "Development Status :: 2 - Pre-Alpha",
@@ -35,7 +35,7 @@ dependencies = [
   "mne-bids >= 0.8",
   "mne-connectivity",
   "mrmr_selection",
-  "nolds",
+  "nolds >= 0.6.1",
   "numpy >= 1.21.2",
   "pandas >= 2.0.0",
   "scikit-learn >= 0.24.2",
@@ -46,9 +46,11 @@ dependencies = [
   "pyarrow>=14.0.2",
   "joblib>=1.3.2",
   "mne-lsl>=1.2.0",
-  "pyqt5",
+  #"pyqt5",
   "pydantic>=2.7.3",
   "seaborn >= 0.11",
+  "llvmlite>=0.43.0",
+  "numba>=0.60.0",
 ]
 
 [project.optional-dependencies]

py_neuromodulation-0.0.7/tests/test_coherence.py

@@ -0,0 +1,119 @@
+import numpy as np
+from mne_connectivity import make_signals_in_freq_bands
+
+import py_neuromodulation as nm
+
+
+def test_coherence():
+    """Check that coherence features compute properly and match expected values."""
+    # Simulate connectivity data (interaction at specified frequency band)
+    sfreq = 500  # Hz
+    n_epochs = 1
+    n_times = sfreq * 2  # samples
+    fband = (15, 20)  # frequency band of interaction, Hz
+    trans = 2  # transition bandwidth of signal, Hz
+    delay = 50  # samples
+    epochs = make_signals_in_freq_bands(
+        n_seeds=1,
+        n_targets=1,
+        freq_band=fband,
+        n_epochs=n_epochs,
+        n_times=n_times,
+        sfreq=sfreq,
+        trans_bandwidth=trans,
+        connection_delay=delay,
+        ch_names=["seed", "target"],
+        snr=0.7,  # change here requires change in `signal/noise_con` vars below
+        rng_seed=44
+    )
+
+    # Set up py_nm channels info
+    ch_names = epochs.ch_names
+    ch_types = epochs.get_channel_types()
+    channels = nm.utils.set_channels(
+        ch_names=ch_names,
+        ch_types=ch_types,
+        reference="default",
+        bads=None,
+        new_names="default",
+        used_types=tuple(np.unique(ch_types)),
+        target_keywords=None,
+    )
+
+    # Set up pn_nm processing settings
+    settings = nm.NMSettings.get_default()
+    settings.reset()
+    settings.features.coherence = True
+
+    # redefine freq. bands of interest
+    # (accounts for signal-noise transition bandwdith when defining frequencies)
+    settings.frequency_ranges_hz = {
+        "signal": {  # strong connectivity expected
+            "frequency_low_hz": fband[0],
+            "frequency_high_hz": fband[1],
+        },
+        "noise_low": {  # weak connectivity expected from 1 Hz to start of interaction
+            "frequency_low_hz": 1,
+            "frequency_high_hz": fband[0] - trans * 2,
+        },
+        "noise_high": {  # weak connectivity expected from end of interaction to Nyquist
+            "frequency_low_hz": fband[1] + trans * 2,
+            "frequency_high_hz": sfreq // 2 - 1,
+        },
+    }
+    settings.coherence_settings.frequency_bands = ["signal", "noise_low", "noise_high"]
+
+    # only average within each band required
+    settings.coherence_settings.features = {
+        "mean_fband": True, "max_fband": False, "max_allfbands": False
+    }
+
+    # unique all-to-all connectivity indices, i.e.: ([0], [1])
+    # XXX: avoids pydantic ValidationError that lists are too short (length == 1)
+    settings.coherence_settings.channels = [ch_names]
+
+    # do not normalise features for this test!
+    # (normalisation changes interpretability of connectivity values, making it harder to
+    # define 'expected' connectivity values)
+    settings.postprocessing.feature_normalization = False
+
+    # Set up py_nm stream
+    stream = nm.Stream(
+        settings=settings,
+        channels=channels,
+        path_grids=None,
+        verbose=True,
+        sfreq=epochs.info["sfreq"],
+    )
+
+    # Compute connectivity
+    features = stream.run(
+        epochs.get_data(copy=False)[0],  # extract first (and only) epoch from obj
+        out_dir="./test_data",
+        experiment_name="test_coherence",
+    )
+
+    # Aggregate results over windows
+    results = {key: None for key in features.keys()}
+    results.pop("time")
+    for key in results.keys():
+        # average over windows; take absolute before averaging icoh values
+        results[key] = np.abs(features[key].values).mean()
+
+    node_name = "seed_to_target"
+    for con_method in ["coh", "icoh"]:
+        # Define expected connectivity values for signal and noise frequencies
+        noise_con = 0.15
+        signal_con = 0.25
+
+        # Assert that frequencies of simulated interaction have strong connectivity
+        np.testing.assert_array_less(
+            signal_con, results[f"{con_method}_{node_name}_mean_fband_signal"]
+        )
+        # Assert that frequencies of noise have weak connectivity
+        np.testing.assert_array_less(
+            results[f"{con_method}_{node_name}_mean_fband_noise_low"], noise_con
+        )
+        np.testing.assert_array_less(
+            results[f"{con_method}_{node_name}_mean_fband_noise_high"], noise_con
+        )

py_neuromodulation-0.0.6/sub_SETTINGS.yaml

@@ -1,112 +0,0 @@
-bandpass_filter_settings:
-  bandpower_features: {activity: true, complexity: false, mobility: false}
-  kalman_filter: false
-  log_transform: true
-  segment_lengths_ms: {HFA: 100, alpha: 500, high_beta: 333, high_gamma: 100, low_beta: 333,
-    low_gamma: 100, theta: 1000}
-bispectrum_settings:
-  bispectrum_features: {mean: true, sum: true, var: true}
-  components: {absolute: true, imag: true, phase: true, real: true}
-  compute_features_for_whole_fband_range: true
-  f1s: {frequency_high_hz: 35.0, frequency_low_hz: 5.0}
-  f2s: {frequency_high_hz: 35.0, frequency_low_hz: 5.0}
-  frequency_bands: [theta, alpha, low_beta, high_beta]
-burst_settings:
-  burst_features: {amplitude: true, burst_rate_per_s: true, duration: true, in_burst: true}
-  frequency_bands: [low_beta, high_beta, low_gamma]
-  threshold: 75.0
-  time_duration_s: 30.0
-coherence_settings:
-  channels: []
-  features: {max_allfbands: true, max_fband: true, mean_fband: true}
-  frequency_bands: [high_beta]
-  method: {coh: true, icoh: true}
-feature_normalization_settings: {clip: 3.0, normalization_method: zscore, normalization_time_s: 30.0}
-features: {bandpass_filter: false, bispectrum: false, bursts: false, coherence: false,
-  fft: false, fooof: false, linelength: false, mne_connectivity: false, nolds: false,
-  raw_hjorth: false, return_raw: false, sharpwave_analysis: true, stft: false, welch: false}
-fft_settings:
-  features: {max: false, mean: true, median: false, std: false}
-  log_transform: true
-  return_spectrum: false
-  windowlength_ms: 1000
-fooof_settings:
-  aperiodic: {exponent: true, knee: true, offset: true}
-  freq_range_hz: {frequency_high_hz: 40.0, frequency_low_hz: 2.0}
-  knee: true
-  max_n_peaks: 3
-  min_peak_height: 0.0
-  peak_threshold: 2.0
-  peak_width_limits: {frequency_high_hz: 12.0, frequency_low_hz: 0.5}
-  periodic: {band_width: false, center_frequency: false, height_over_ap: false}
-  windowlength_ms: 800.0
-frequency_ranges_hz:
-  HFA: {frequency_high_hz: 400.0, frequency_low_hz: 200.0}
-  alpha: {frequency_high_hz: 12.0, frequency_low_hz: 8.0}
-  high_beta: {frequency_high_hz: 35.0, frequency_low_hz: 20.0}
-  high_gamma: {frequency_high_hz: 200.0, frequency_low_hz: 90.0}
-  low_beta: {frequency_high_hz: 20.0, frequency_low_hz: 13.0}
-  low_gamma: {frequency_high_hz: 80.0, frequency_low_hz: 60.0}
-  theta: {frequency_high_hz: 8.0, frequency_low_hz: 4.0}
-kalman_filter_settings:
-  Tp: 0.1
-  frequency_bands: [theta, alpha, low_beta, high_beta, low_gamma, high_gamma, HFA]
-  sigma_v: 1.0
-  sigma_w: 0.7
-mne_connectivity_settings: {method: plv, mode: multitaper}
-mne_connectiviy_settings: {method: plv, mode: multitaper}
-nolds_settings:
-  correlation_dimension: false
-  data:
-    frequency_bands: [low_beta]
-    raw: true
-  detrended_fluctutaion_analysis: false
-  features: {correlation_dimension: false, detrended_fluctuation_analysis: false,
-    hurst_exponent: false, lyapunov_exponent: true, sample_entropy: false}
-  frequency_bands: [low_beta]
-  hurst_exponent: false
-  lyapunov_exponent: true
-  raw: true
-  sample_entropy: false
-postprocessing: {feature_normalization: false, project_cortex: false, project_subcortex: false}
-preprocessing: []
-preprocessing_filter:
-  bandpass_filter: true
-  bandpass_filter_settings: {frequency_high_hz: 200.0, frequency_low_hz: 3.0}
-  bandstop_filter: true
-  bandstop_filter_settings: {frequency_high_hz: 160.0, frequency_low_hz: 100.0}
-  highpass_filter: true
-  highpass_filter_cutoff_hz: 3.0
-  lowpass_filter: true
-  lowpass_filter_cutoff_hz: 200.0
-project_cortex_settings: {max_dist_mm: 20.0}
-project_subcortex_settings: {max_dist_mm: 5.0}
-raw_normalization_settings: {clip: 3.0, normalization_method: zscore, normalization_time_s: 30.0}
-raw_resampling_settings: {resample_freq_hz: 1000.0}
-sampling_rate_features_hz: 10.0
-segment_length_features_ms: 1000.0
-sharpwave_analysis_settings:
-  apply_estimator_between_peaks_and_troughs: true
-  detect_peaks: {distance_peaks_ms: 10.0, distance_troughs_ms: 5.0, estimate: true}
-  detect_troughs: {distance_peaks_ms: 5.0, distance_troughs_ms: 10.0, estimate: true}
-  estimator:
-    max: [prominence, sharpness]
-    mean: [interval]
-    median: []
-    min: []
-    var: []
-  filter_ranges_hz:
-  - {frequency_high_hz: 80.0, frequency_low_hz: 5.0}
-  sharpwave_features: {decay_steepness: false, decay_time: false, interval: true,
-    num_peaks: false, peak_left: false, peak_right: false, prominence: true, rise_steepness: false,
-    rise_time: false, sharpness: true, slope_ratio: false, trough: false, width: false}
-stft_settings:
-  features: {max: false, mean: true, median: false, std: false}
-  log_transform: true
-  return_spectrum: false
-  windowlength_ms: 500
-welch_settings:
-  features: {max: false, mean: true, median: false, std: false}
-  log_transform: true
-  return_spectrum: false
-  windowlength_ms: 1000

py_neuromodulation-0.0.6/sub_SIDECAR.json

@@ -1,6 +0,0 @@
-{
-    "original_fs": 1000.0,
-    "final_fs": 1000.0,
-    "sfreq": 10.0,
-    "sess_right": null
-}