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

py_neuromodulation/nm_settings.py

@@ -1,68 +1,289 @@
-"""Module for handling settings."""
-import pathlib
-
-import pandas as pd
-
-from py_neuromodulation import nm_IO
-
-
-def get_default_settings() -> dict:
-    """Read default settings from nm_settings.json"""
-    settings_path = str(
-        pathlib.Path(__file__).parent.resolve() / "nm_settings.json"
-    )
-    return nm_IO.read_settings(settings_path)
-
-
-def reset_settings(
-    settings: dict,
-) -> dict:
-    for f in settings["features"]:
-        settings["features"][f] = False
-    settings["preprocessing"] = []
-    for f in settings["postprocessing"]:
-        settings["postprocessing"][f] = False
-    return settings
-
-
-def set_settings_fast_compute(
-    settings: dict,
-) -> dict:
-    settings = reset_settings(settings)
-    settings["features"]["fft"] = True
-    settings["preprocessing"] = [
-        "raw_resampling",
-        "notch_filter",
-        "re_referencing",
-    ]
-    settings["postprocessing"]["feature_normalization"] = True
-    settings["postprocessing"]["project_cortex"] = False
-    settings["postprocessing"]["project_subcortex"] = False
-    return settings
-
-
-def test_settings(
-    settings: dict,
-) -> None:
-    """Test if settings are specified correctly in nm_settings.json
-    Parameters
-    ----------
-    settings: dict
-        settings to tests
-    verbose: boolean
-        set to True if feedback is desired.
-    Returns
-    -------
-    None
-    """
-    s = settings
-
-    assert isinstance(s["sampling_rate_features_hz"], (float, int))
-
-    assert (
-        isinstance(value, bool) for value in s["features"].values()
-    ), "features must be a boolean value."
-
-    assert any(
-        value is True for value in s["features"].values()
-    ), "Set at least one feature to True."
+"""Module for handling settings."""
+
+from pathlib import Path
+from typing import ClassVar
+from pydantic import Field, model_validator
+
+from py_neuromodulation import PYNM_DIR, logger, user_features
+from py_neuromodulation.nm_types import (
+    BoolSelector,
+    FrequencyRange,
+    PreprocessorName,
+    _PathLike,
+)
+
+from py_neuromodulation.nm_types import NMBaseModel
+from py_neuromodulation.nm_filter_preprocessing import FilterSettings
+from py_neuromodulation.nm_kalmanfilter import KalmanSettings
+from py_neuromodulation.nm_projection import ProjectionSettings
+from py_neuromodulation.nm_bispectra import BispectraSettings
+from py_neuromodulation.nm_nolds import NoldsSettings
+from py_neuromodulation.nm_mne_connectivity import MNEConnectivitySettings
+from py_neuromodulation.nm_fooof import FooofSettings
+from py_neuromodulation.nm_coherence import CoherenceSettings
+from py_neuromodulation.nm_sharpwaves import SharpwaveSettings
+from py_neuromodulation.nm_oscillatory import OscillatorySettings, BandpassSettings
+from py_neuromodulation.nm_bursts import BurstSettings
+from py_neuromodulation.nm_normalization import NormMethod, NormalizationSettings
+from py_neuromodulation.nm_resample import ResamplerSettings
+
+
+class FeatureSelection(BoolSelector):
+    raw_hjorth: bool = True
+    return_raw: bool = True
+    bandpass_filter: bool = False
+    stft: bool = False
+    fft: bool = True
+    welch: bool = True
+    sharpwave_analysis: bool = True
+    fooof: bool = False
+    nolds: bool = False
+    coherence: bool = False
+    bursts: bool = True
+    linelength: bool = True
+    mne_connectivity: bool = False
+    bispectrum: bool = False
+
+
+class PostprocessingSettings(BoolSelector):
+    feature_normalization: bool = True
+    project_cortex: bool = False
+    project_subcortex: bool = False
+
+
+class NMSettings(NMBaseModel):
+    # Class variable to store instances
+    _instances: ClassVar[list["NMSettings"]] = []
+
+    # General settings
+    sampling_rate_features_hz: float = Field(default=10, gt=0)
+    segment_length_features_ms: float = Field(default=1000, gt=0)
+    frequency_ranges_hz: dict[str, FrequencyRange] = {
+        "theta": FrequencyRange(4, 8),
+        "alpha": FrequencyRange(8, 12),
+        "low_beta": FrequencyRange(13, 20),
+        "high_beta": FrequencyRange(20, 35),
+        "low_gamma": FrequencyRange(60, 80),
+        "high_gamma": FrequencyRange(90, 200),
+        "HFA": FrequencyRange(200, 400),
+    }
+
+    # Preproceessing settings
+    preprocessing: list[PreprocessorName] = [
+        "raw_resampling",
+        "notch_filter",
+        "re_referencing",
+    ]
+    raw_resampling_settings: ResamplerSettings = ResamplerSettings()
+    preprocessing_filter: FilterSettings = FilterSettings()
+    raw_normalization_settings: NormalizationSettings = NormalizationSettings()
+
+    # Postprocessing settings
+    postprocessing: PostprocessingSettings = PostprocessingSettings()
+    feature_normalization_settings: NormalizationSettings = NormalizationSettings()
+    project_cortex_settings: ProjectionSettings = ProjectionSettings(max_dist_mm=20)
+    project_subcortex_settings: ProjectionSettings = ProjectionSettings(max_dist_mm=5)
+
+    # Feature settings
+    features: FeatureSelection = FeatureSelection()
+
+    fft_settings: OscillatorySettings = OscillatorySettings()
+    welch_settings: OscillatorySettings = OscillatorySettings()
+    stft_settings: OscillatorySettings = OscillatorySettings()
+    bandpass_filter_settings: BandpassSettings = BandpassSettings()
+    kalman_filter_settings: KalmanSettings = KalmanSettings()
+    burst_settings: BurstSettings = BurstSettings()
+    sharpwave_analysis_settings: SharpwaveSettings = SharpwaveSettings()
+    mne_connectivity: MNEConnectivitySettings = MNEConnectivitySettings()
+    coherence: CoherenceSettings = CoherenceSettings()
+    fooof: FooofSettings = FooofSettings()
+    nolds_features: NoldsSettings = NoldsSettings()
+    bispectrum: BispectraSettings = BispectraSettings()
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+        for feat_name in user_features.keys():
+            setattr(self.features, feat_name, True)
+
+        NMSettings._add_instance(self)
+
+    @classmethod
+    def _add_instance(cls, instance: "NMSettings") -> None:
+        """Keep track of all instances created in class variable"""
+        cls._instances.append(instance)
+
+    @classmethod
+    def _add_feature(cls, feature: str) -> None:
+        for instance in cls._instances:
+            setattr(instance.features, feature, True)
+
+    @classmethod
+    def _remove_feature(cls, feature: str) -> None:
+        for instance in cls._instances:
+            delattr(instance.features, feature)
+
+    @model_validator(mode="after")
+    def validate_settings(self):
+        if len(self.features.get_enabled()) == 0:
+            raise ValueError("At least one feature must be selected.")
+
+        # Replace spaces with underscores in frequency band names
+        self.frequency_ranges_hz = {
+            k.replace(" ", "_"): v for k, v in self.frequency_ranges_hz.items()
+        }
+
+        if self.features.bandpass_filter:
+            # Check BandPass settings frequency bands
+            self.bandpass_filter_settings.validate_fbands(self)
+
+            # Check Kalman filter frequency bands
+            if self.bandpass_filter_settings.kalman_filter:
+                self.kalman_filter_settings.validate_fbands(self)
+
+        for k, v in self.frequency_ranges_hz.items():
+            if not isinstance(v, FrequencyRange):
+                self.frequency_ranges_hz[k] = FrequencyRange.create_from(v)
+
+        return self
+
+    def reset(self) -> "NMSettings":
+        self.features.disable_all()
+        self.preprocessing = []
+        self.postprocessing.disable_all()
+        return self
+
+    def set_fast_compute(self) -> "NMSettings":
+        self.reset()
+        self.features.fft = True
+        self.preprocessing = [
+            "raw_resampling",
+            "notch_filter",
+            "re_referencing",
+        ]
+        self.postprocessing.feature_normalization = True
+        self.postprocessing.project_cortex = False
+        self.postprocessing.project_subcortex = False
+
+        return self
+
+    def enable_all_features(self):
+        self.features.enable_all()
+        return self
+
+    def disable_all_features(self):
+        self.features.disable_all()
+        return self
+
+    @staticmethod
+    def get_fast_compute() -> "NMSettings":
+        return NMSettings.get_default().set_fast_compute()
+
+    @classmethod
+    def load(cls, settings: "NMSettings | _PathLike | None") -> "NMSettings":
+        if isinstance(settings, cls):
+            return settings.validate()
+        if settings is None:
+            return cls.get_default()
+        return cls.from_file(str(settings))
+
+    @staticmethod
+    def from_file(PATH: _PathLike) -> "NMSettings":
+        """Load settings from file or a directory.
+
+        Args:
+            PATH (_PathLike): Path to settings file or to directory containing settings file,
+                              or path to experiment including experiment prefix
+                              (e.g. /path/to/exp/exp_prefix[_SETTINGS.json]).
+                              Supported file types are .json and .yaml
+
+        Raises:
+            ValueError: when file format is not supported.
+
+        Returns:
+            NMSettings: PyNM settings object
+        """
+        path = Path(PATH)
+
+        # If directory is passed, look for settings file inside
+        if path.is_dir():
+            for child in path.iterdir():
+                if child.is_file() and child.suffix in [".json", ".yaml"]:
+                    path = child
+                    break
+
+        # If prefix is passed, look for settings file matching prefix
+        if not path.is_dir() and not path.is_file():
+            for child in path.parent.iterdir():
+                ext = child.suffix.lower()
+                if (
+                    child.is_file()
+                    and ext in [".json", ".yaml"]
+                    and child.name == path.stem + "_SETTINGS" + ext
+                ):
+                    path = child
+                    break
+
+        match path.suffix:
+            case ".json":
+                import json
+
+                with open(path) as f:
+                    model_dict = json.load(f)
+            case ".yaml":
+                import yaml
+
+                # with open(path) as f:
+                #    model_dict = yaml.safe_load(f)
+
+                # Timon: this is potentially dangerous since python code is directly executed
+                with open(path) as f:
+                    model_dict = yaml.load(f, Loader=yaml.Loader)
+
+            case _:
+                raise ValueError("File format not supported.")
+
+        return NMSettings(**model_dict)
+
+    @staticmethod
+    def get_default() -> "NMSettings":
+        return NMSettings.from_file(PYNM_DIR / "nm_settings.yaml")
+
+    @staticmethod
+    def list_normalization_methods() -> list[NormMethod]:
+        return NormalizationSettings.list_normalization_methods()
+
+    def save(
+        self, out_dir: _PathLike = ".", prefix: str = "", format: str = "yaml"
+    ) -> None:
+        filename = f"{prefix}_SETTINGS.{format}" if prefix else f"SETTINGS.{format}"
+
+        path_out = Path(out_dir) / filename
+
+        with open(path_out, "w") as f:
+            match format:
+                case "json":
+                    f.write(self.model_dump_json(indent=4))
+                case "yaml":
+                    import yaml
+
+                    yaml.dump(self.model_dump(), f, default_flow_style=None)
+
+        logger.info(f"Settings saved to {path_out.resolve()}")
+
+
+# For retrocompatibility with previous versions of PyNM
+def get_default_settings() -> NMSettings:
+    return NMSettings.get_default()
+
+
+def reset_settings(settings: NMSettings) -> NMSettings:
+    return settings.reset()
+
+
+def set_settings_fast_compute() -> NMSettings:
+    return NMSettings.get_fast_compute()
+
+
+def test_settings(settings: NMSettings) -> NMSettings:
+    return settings.validate()

py_neuromodulation/nm_settings.yaml

@@ -0,0 +1,244 @@
+---
+
+########################
+### General settings ###
+########################
+sampling_rate_features_hz: 10
+segment_length_features_ms: 1000
+
+frequency_ranges_hz: # frequency band ranges can be added, removed and altered
+  theta: [4, 8]
+  alpha: [8, 12]
+  low_beta: [13, 20]
+  high_beta: [20, 35]
+  low_gamma: [60, 80]
+  high_gamma: [90, 200]
+  HFA: [200, 400]
+
+
+# Enabled features
+features:
+  raw_hjorth: true
+  return_raw: true
+  bandpass_filter: false
+  stft: false
+  fft: true
+  welch: true
+  sharpwave_analysis: true
+  fooof: false
+  bursts: true
+  linelength: true
+  coherence: false
+  nolds: false
+  mne_connectivity: false
+  bispectrum: false
+
+##############################
+### Preprocessing settings ###
+##############################
+# preprocessing options: raw_resampling, notch_filter, re_referencing, preprocessing_filter, raw_normalization
+# note: the list order specifies also the order of execution
+preprocessing: [raw_resampling, notch_filter, re_referencing]
+
+raw_resampling_settings:
+  resample_freq_hz: 1000
+
+raw_normalization_settings:
+  normalization_time_s: 30
+  normalization_method: zscore # supported methods: mean, median, zscore, zscore-median, quantile, power, robust, minmax
+  clip: 3
+
+preprocessing_filter:
+  bandstop_filter: true
+  lowpass_filter: true
+  highpass_filter: true
+  bandpass_filter: true
+  bandstop_filter_settings:
+    frequency_low_hz: 100
+    frequency_high_hz: 160
+  bandpass_filter_settings:
+    frequency_low_hz: 3
+    frequency_high_hz: 200
+  lowpass_filter_cutoff_hz: 200
+  highpass_filter_cutoff_hz: 3
+
+
+################################
+### Postprocessing settings ####
+################################
+postprocessing:
+  feature_normalization: true
+  project_cortex: false
+  project_subcortex: false
+
+feature_normalization_settings:
+  normalization_time_s: 30
+  normalization_method: zscore # supported methods: mean, median, zscore, zscore-median, quantile, power, robust, minmax
+  clip: 3
+
+project_cortex_settings:
+  max_dist_mm: 20
+
+project_subcortex_settings:
+  max_dist_mm: 5
+
+
+#################################
+### Feature specific settings ###
+#################################
+
+fft_settings:
+  windowlength_ms: 1000
+  log_transform: true
+  features:
+    mean: true
+    median: false
+    std: false
+    max: false
+  return_spectrum: false
+
+welch_settings:
+  windowlength_ms: 1000
+  log_transform: true
+  features:
+    mean: true
+    median: false
+    std: false
+    max: false
+  return_spectrum: false
+
+stft_settings:
+  windowlength_ms: 500
+  log_transform: true
+  features:
+    mean: true
+    median: false
+    std: false
+    max: false
+  return_spectrum: false
+
+bandpass_filter_settings:
+  segment_lengths_ms:
+    theta: 1000
+    alpha: 500
+    low_beta: 333
+    high_beta: 333
+    low_gamma: 100
+    high_gamma: 100
+    HFA: 100
+  bandpower_features:
+    activity: true
+    mobility: false
+    complexity: false
+  log_transform: true
+  kalman_filter: false
+
+kalman_filter_settings:
+  Tp: 0.1
+  sigma_w: 0.7
+  sigma_v: 1
+  frequency_bands:
+    [theta, alpha, low_beta, high_beta, low_gamma, high_gamma, HFA]
+
+burst_settings:
+  threshold: 75
+  time_duration_s: 30
+  frequency_bands: [low_beta, high_beta, low_gamma]
+  burst_features:
+    duration: true
+    amplitude: true
+    burst_rate_per_s: true
+    in_burst: true
+
+sharpwave_analysis_settings:
+  sharpwave_features:
+    peak_left: false
+    peak_right: false
+    trough: false
+    width: false
+    prominence: true
+    interval: true
+    decay_time: false
+    rise_time: false
+    sharpness: true
+    rise_steepness: false
+    decay_steepness: false
+    slope_ratio: false
+  filter_ranges_hz:
+    - frequency_low_hz: 5
+      frequency_high_hz: 80
+    - frequency_low_hz: 5
+      frequency_high_hz: 30
+  detect_troughs:
+    estimate: true
+    distance_troughs_ms: 10
+    distance_peaks_ms: 5
+  detect_peaks:
+    estimate: true
+    distance_troughs_ms: 5
+    distance_peaks_ms: 10
+  estimator:
+    mean: [interval]
+    median: []
+    max: [prominence, sharpness]
+    min: []
+    var: []
+  apply_estimator_between_peaks_and_troughs: true
+
+coherence:
+  channels: [] # List of channel pairs, empty by default. Each pair is a list of two channels.
+  # Example channels: [[STN_RIGHT_0, ECOG_RIGHT_0], [STN_RIGHT_1, ECOG_RIGHT_1]]
+  frequency_bands: [high_beta]
+  features:
+    mean_fband: true
+    max_fband: true
+    max_allfbands: true
+  method:
+    coh: true
+    icoh: true
+
+fooof:
+  aperiodic:
+    exponent: true
+    offset: true
+    knee: true
+  periodic:
+    center_frequency: false
+    band_width: false
+    height_over_ap: false
+  windowlength_ms: 800
+  peak_width_limits: [0.5, 12]
+  max_n_peaks: 3
+  min_peak_height: 0
+  peak_threshold: 2
+  freq_range_hz: [2, 40]
+  knee: true
+
+nolds_features:
+  sample_entropy: false
+  correlation_dimension: false
+  lyapunov_exponent: true
+  hurst_exponent: false
+  detrended_fluctutaion_analysis: false
+  data:
+    raw: true
+    frequency_bands: [low_beta]
+
+mne_connectiviy:
+  method: plv
+  mode: multitaper
+
+bispectrum:
+  f1s: [5, 35]
+  f2s: [5, 35]
+  compute_features_for_whole_fband_range: true
+  frequency_bands: [theta, alpha, low_beta, high_beta]
+  components:
+    absolute: true
+    real: true
+    imag: true
+    phase: true
+  bispectrum_features:
+    mean: true
+    sum: true
+    var: true