accusleepy 0.6.0__tar.gz → 0.7.1__tar.gz

{accusleepy-0.6.0 → accusleepy-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: accusleepy
-Version: 0.6.0
+Version: 0.7.1
 Summary: Python implementation of AccuSleep
 License: GPL-3.0-only
 Author: Zeke Barger
@@ -39,6 +39,7 @@ It offers the following improvements over the MATLAB version (AccuSleep):
     - Model files contain useful metadata (brain state configuration,
       epoch length, number of epochs)
     - Models optimized for real-time scoring can be trained
+- Confidence scores can be saved and visualized
 - Lists of recordings can be imported and exported for repeatable batch processing
 - Undo/redo functionality in the manual scoring interface
 
@@ -75,6 +76,8 @@ to the [config file](accusleepy/config.json).
 
 ## Changelog
 
+- 0.7.1: Bugfixes, code cleanup
+- 0.7.0: More settings can be configured in the UI
 - 0.6.0: Confidence scores can now be displayed and saved. Retraining your models is recommended
     since the new calibration feature will make the confidence scores more accurate.
 - 0.5.0: Performance improvements

{accusleepy-0.6.0 → accusleepy-0.7.1}/README.md

@@ -11,6 +11,7 @@ It offers the following improvements over the MATLAB version (AccuSleep):
     - Model files contain useful metadata (brain state configuration,
       epoch length, number of epochs)
     - Models optimized for real-time scoring can be trained
+- Confidence scores can be saved and visualized
 - Lists of recordings can be imported and exported for repeatable batch processing
 - Undo/redo functionality in the manual scoring interface
 
@@ -47,6 +48,8 @@ to the [config file](accusleepy/config.json).
 
 ## Changelog
 
+- 0.7.1: Bugfixes, code cleanup
+- 0.7.0: More settings can be configured in the UI
 - 0.6.0: Confidence scores can now be displayed and saved. Retraining your models is recommended
     since the new calibration feature will make the confidence scores more accurate.
 - 0.5.0: Performance improvements

{accusleepy-0.6.0 → accusleepy-0.7.1}/accusleepy/classification.py

@@ -11,6 +11,7 @@ from tqdm import trange
 
 import accusleepy.constants as c
 from accusleepy.brain_state_set import BrainStateSet
+from accusleepy.fileio import EMGFilter, Hyperparameters
 from accusleepy.models import SSANN
 from accusleepy.signal_processing import (
     create_eeg_emg_image,
@@ -19,11 +20,6 @@ from accusleepy.signal_processing import (
     mixture_z_score_img,
 )
 
-BATCH_SIZE = 64
-LEARNING_RATE = 1e-3
-MOMENTUM = 0.9
-TRAINING_EPOCHS = 6
-
 
 class AccuSleepImageDataset(Dataset):
     """Dataset for loading AccuSleep training images"""
@@ -62,12 +58,16 @@ def get_device():
 
 
 def create_dataloader(
-    annotations_file: str, img_dir: str, shuffle: bool = True
+    annotations_file: str,
+    img_dir: str,
+    hyperparameters: Hyperparameters,
+    shuffle: bool = True,
 ) -> DataLoader:
     """Create DataLoader for a dataset of training or calibration images
 
     :param annotations_file: file with information on each training image
     :param img_dir: training image location
+    :param hyperparameters: model training hyperparameters
     :param shuffle: reshuffle data for every epoch
     :return: DataLoader for the data
 
@@ -76,7 +76,9 @@ def create_dataloader(
         annotations_file=annotations_file,
         img_dir=img_dir,
     )
-    return DataLoader(image_dataset, batch_size=BATCH_SIZE, shuffle=shuffle)
+    return DataLoader(
+        image_dataset, batch_size=hyperparameters.batch_size, shuffle=shuffle
+    )
 
 
 def train_ssann(
@@ -84,6 +86,7 @@ def train_ssann(
     img_dir: str,
     mixture_weights: np.array,
     n_classes: int,
+    hyperparameters: Hyperparameters,
 ) -> SSANN:
     """Train a SSANN classification model for sleep scoring
 
@@ -91,10 +94,13 @@ def train_ssann(
     :param img_dir: training image location
     :param mixture_weights: typical relative frequencies of brain states
     :param n_classes: number of classes the model will learn
+    :param hyperparameters: model training hyperparameters
     :return: trained Sleep Scoring Artificial Neural Network model
     """
     train_dataloader = create_dataloader(
-        annotations_file=annotations_file, img_dir=img_dir
+        annotations_file=annotations_file,
+        img_dir=img_dir,
+        hyperparameters=hyperparameters,
     )
 
     device = get_device()
@@ -106,9 +112,13 @@ def train_ssann(
     weight = torch.tensor((mixture_weights**-1).astype("float32")).to(device)
 
     criterion = nn.CrossEntropyLoss(weight=weight)
-    optimizer = optim.SGD(model.parameters(), lr=LEARNING_RATE, momentum=MOMENTUM)
+    optimizer = optim.SGD(
+        model.parameters(),
+        lr=hyperparameters.learning_rate,
+        momentum=hyperparameters.momentum,
+    )
 
-    for _ in trange(TRAINING_EPOCHS):
+    for _ in trange(hyperparameters.training_epochs):
         for data in train_dataloader:
             inputs, labels = data
             (inputs, labels) = (inputs.to(device), labels.to(device))
@@ -131,6 +141,7 @@ def score_recording(
     epoch_length: int | float,
     epochs_per_img: int,
     brain_state_set: BrainStateSet,
+    emg_filter: EMGFilter,
 ) -> np.array:
     """Use classification model to get brain state labels for a recording
 
@@ -146,6 +157,7 @@ def score_recording(
     :param epoch_length: epoch length, in seconds
     :param epochs_per_img: number of epochs for the model to consider
     :param brain_state_set: set of brain state options
+    :param emg_filter: EMG filter parameters
     :return: brain state labels, confidence scores
     """
     # prepare model
@@ -154,7 +166,7 @@ def score_recording(
     model.eval()
 
     # create and scale eeg+emg spectrogram
-    img = create_eeg_emg_image(eeg, emg, sampling_rate, epoch_length)
+    img = create_eeg_emg_image(eeg, emg, sampling_rate, epoch_length, emg_filter)
     img = mixture_z_score_img(
         img,
         mixture_means=mixture_means,
@@ -192,6 +204,7 @@ def example_real_time_scoring_function(
     epoch_length: int | float,
     epochs_per_img: int,
     brain_state_set: BrainStateSet,
+    emg_filter: EMGFilter,
 ) -> int:
     """Example function that could be used for real-time scoring
 
@@ -220,6 +233,7 @@ def example_real_time_scoring_function(
     :param epoch_length: epoch length, in seconds
     :param epochs_per_img: number of epochs shown to the model at once
     :param brain_state_set: set of brain state options
+    :param emg_filter: EMG filter parameters
     :return: brain state label
     """
     # prepare model
@@ -229,7 +243,7 @@ def example_real_time_scoring_function(
     model.eval()
 
     # create and scale eeg+emg spectrogram
-    img = create_eeg_emg_image(eeg, emg, sampling_rate, epoch_length)
+    img = create_eeg_emg_image(eeg, emg, sampling_rate, epoch_length, emg_filter)
     img = mixture_z_score_img(
         img,
         mixture_means=mixture_means,
@@ -260,6 +274,7 @@ def create_calibration_file(
     sampling_rate: int | float,
     epoch_length: int | float,
     brain_state_set: BrainStateSet,
+    emg_filter: EMGFilter,
 ) -> None:
     """Create file of calibration data for a subject
 
@@ -273,8 +288,9 @@ def create_calibration_file(
     :param sampling_rate: sampling rate, in Hz
     :param epoch_length: epoch length, in seconds
     :param brain_state_set: set of brain state options
+    :param emg_filter: EMG filter parameters
     """
-    img = create_eeg_emg_image(eeg, emg, sampling_rate, epoch_length)
+    img = create_eeg_emg_image(eeg, emg, sampling_rate, epoch_length, emg_filter)
     mixture_means, mixture_sds = get_mixture_values(
         img=img,
         labels=brain_state_set.convert_digit_to_class(labels),

{accusleepy-0.6.0 → accusleepy-0.7.1}/accusleepy/config.json

@@ -20,5 +20,18 @@
         }
     ],
     "default_epoch_length": 2.5,
-    "save_confidence_setting": true
+    "default_overwrite_setting": false,
+    "save_confidence_setting": true,
+    "default_min_bout_length": 5.0,
+    "emg_filter": {
+        "order": 8,
+        "bp_lower": 20.0,
+        "bp_upper": 50.0
+    },
+    "hyperparameters": {
+        "batch_size": 64,
+        "learning_rate": 0.001,
+        "momentum": 0.9,
+        "training_epochs": 6
+    }
 }

{accusleepy-0.6.0 → accusleepy-0.7.1}/accusleepy/constants.py

@@ -1,3 +1,5 @@
+import numpy as np
+
 # probably don't change these unless you really need to
 UNDEFINED_LABEL = -1  # can't be the same as a brain state's digit, must be an integer
 # calibration file columns
@@ -9,9 +11,16 @@ EMG_COL = "emg"
 # label file columns
 BRAIN_STATE_COL = "brain_state"
 CONFIDENCE_SCORE_COL = "confidence_score"
+# max number of messages to store in main window message box
+MESSAGE_BOX_MAX_DEPTH = 200
+# clip mixture z-scores above and below this level
+# in the matlab implementation, 4.5 was used
+ABS_MAX_Z_SCORE = 3.5
+# upper frequency limit when generating EEG spectrograms
+SPECTROGRAM_UPPER_FREQ = 64
 
 
-# really don't change these
+# very unlikely you will want to change values from here onwards
 # config file location
 CONFIG_FILE = "config.json"
 # number of times to include the EMG power in a training image
@@ -20,8 +29,15 @@ EMG_COPIES = 9
 MIN_WINDOW_LEN = 5
 # frequency above which to downsample EEG spectrograms
 DOWNSAMPLING_START_FREQ = 20
-# upper frequency cutoff for EEG spectrograms
+# highest EEG frequency used as model input
 UPPER_FREQ = 50
+# height in pixels of each training image
+IMAGE_HEIGHT = (
+    len(np.arange(0, DOWNSAMPLING_START_FREQ, 1 / MIN_WINDOW_LEN))
+    + len(np.arange(DOWNSAMPLING_START_FREQ, UPPER_FREQ, 2 / MIN_WINDOW_LEN))
+    + EMG_COPIES
+)
+
 # classification model types
 DEFAULT_MODEL_TYPE = "default"  # current epoch is centered
 REAL_TIME_MODEL_TYPE = "real-time"  # current epoch on the right
@@ -36,11 +52,33 @@ LABEL_COL = "label"
 # recording list file header:
 RECORDING_LIST_NAME = "recording_list"
 RECORDING_LIST_FILE_TYPE = ".json"
-# key for default epoch length in config
-DEFAULT_EPOCH_LENGTH_KEY = "default_epoch_length"
-# key used for default confidence score behavior in config
-DEFAULT_CONFIDENCE_SETTING_KEY = "save_confidence_setting"
 # filename used to store info about training image datasets
 ANNOTATIONS_FILENAME = "annotations.csv"
 # filename for annotation file for the calibration set
 CALIBRATION_ANNOTATION_FILENAME = "calibration_set.csv"
+
+# config file keys
+# ui setting keys
+DEFAULT_EPOCH_LENGTH_KEY = "default_epoch_length"
+DEFAULT_CONFIDENCE_SETTING_KEY = "save_confidence_setting"
+DEFAULT_MIN_BOUT_LENGTH_KEY = "default_min_bout_length"
+DEFAULT_OVERWRITE_KEY = "default_overwrite_setting"
+# EMG filter parameters key
+EMG_FILTER_KEY = "emg_filter"
+# model training hyperparameters key
+HYPERPARAMETERS_KEY = "hyperparameters"
+
+# default values
+# default UI settings
+DEFAULT_MIN_BOUT_LENGTH = 5.0
+DEFAULT_CONFIDENCE_SETTING = True
+DEFAULT_OVERWRITE_SETTING = False
+# default EMG filter parameters (order, bandpass frequencies)
+DEFAULT_EMG_FILTER_ORDER = 8
+DEFAULT_EMG_BP_LOWER = 20
+DEFAULT_EMG_BP_UPPER = 50
+# default hyperparameters
+DEFAULT_BATCH_SIZE = 64
+DEFAULT_LEARNING_RATE = 1e-3
+DEFAULT_MOMENTUM = 0.9
+DEFAULT_TRAINING_EPOCHS = 6

{accusleepy-0.6.0 → accusleepy-0.7.1}/accusleepy/fileio.py

@@ -7,19 +7,26 @@ import pandas as pd
 from PySide6.QtWidgets import QListWidgetItem
 
 from accusleepy.brain_state_set import BRAIN_STATES_KEY, BrainState, BrainStateSet
-from accusleepy.constants import (
-    BRAIN_STATE_COL,
-    CONFIDENCE_SCORE_COL,
-    CONFIG_FILE,
-    DEFAULT_CONFIDENCE_SETTING_KEY,
-    DEFAULT_EPOCH_LENGTH_KEY,
-    EEG_COL,
-    EMG_COL,
-    MIXTURE_MEAN_COL,
-    MIXTURE_SD_COL,
-    RECORDING_LIST_NAME,
-    UNDEFINED_LABEL,
-)
+import accusleepy.constants as c
+
+
+@dataclass
+class EMGFilter:
+    """Convenience class for a EMG filter parameters"""
+
+    order: int  # filter order
+    bp_lower: int | float  # lower bandpass frequency
+    bp_upper: int | float  # upper bandpass frequency
+
+
+@dataclass
+class Hyperparameters:
+    """Convenience class for model training hyperparameters"""
+
+    batch_size: int
+    learning_rate: float
+    momentum: float
+    training_epochs: int
 
 
 @dataclass
@@ -41,8 +48,8 @@ def load_calibration_file(filename: str) -> (np.array, np.array):
     :return: mixture means and SDs
     """
     df = pd.read_csv(filename)
-    mixture_means = df[MIXTURE_MEAN_COL].values
-    mixture_sds = df[MIXTURE_SD_COL].values
+    mixture_means = df[c.MIXTURE_MEAN_COL].values
+    mixture_sds = df[c.MIXTURE_SD_COL].values
     return mixture_means, mixture_sds
 
 
@@ -69,8 +76,8 @@ def load_recording(filename: str) -> (np.array, np.array):
     :return: arrays of EEG and EMG data
     """
     df = load_csv_or_parquet(filename)
-    eeg = df[EEG_COL].values
-    emg = df[EMG_COL].values
+    eeg = df[c.EEG_COL].values
+    emg = df[c.EMG_COL].values
     return eeg, emg
 
 
@@ -81,10 +88,10 @@ def load_labels(filename: str) -> (np.array, np.array):
     :return: array of brain state labels and, optionally, array of confidence scores
     """
     df = load_csv_or_parquet(filename)
-    if CONFIDENCE_SCORE_COL in df.columns:
-        return df[BRAIN_STATE_COL].values, df[CONFIDENCE_SCORE_COL].values
+    if c.CONFIDENCE_SCORE_COL in df.columns:
+        return df[c.BRAIN_STATE_COL].values, df[c.CONFIDENCE_SCORE_COL].values
     else:
-        return df[BRAIN_STATE_COL].values, None
+        return df[c.BRAIN_STATE_COL].values, None
 
 
 def save_labels(
@@ -98,48 +105,92 @@ def save_labels(
     """
     if confidence_scores is not None:
         pd.DataFrame(
-            {BRAIN_STATE_COL: labels, CONFIDENCE_SCORE_COL: confidence_scores}
+            {c.BRAIN_STATE_COL: labels, c.CONFIDENCE_SCORE_COL: confidence_scores}
         ).to_csv(filename, index=False)
     else:
-        pd.DataFrame({BRAIN_STATE_COL: labels}).to_csv(filename, index=False)
+        pd.DataFrame({c.BRAIN_STATE_COL: labels}).to_csv(filename, index=False)
 
 
-def load_config() -> tuple[BrainStateSet, int | float, bool]:
+def load_config() -> tuple[
+    BrainStateSet, int | float, bool, bool, int | float, EMGFilter, Hyperparameters
+]:
     """Load configuration file with brain state options
 
-    :return: set of brain state options, other settings
+    :return: set of brain state options,
+        default epoch length,
+        default overwrite setting,
+        default confidence score output setting,
+        default minimum bout length,
+        EMG filter parameters,
+        model training hyperparameters
     """
     with open(
-        os.path.join(os.path.dirname(os.path.abspath(__file__)), CONFIG_FILE), "r"
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), c.CONFIG_FILE), "r"
     ) as f:
         data = json.load(f)
 
     return (
         BrainStateSet(
-            [BrainState(**b) for b in data[BRAIN_STATES_KEY]], UNDEFINED_LABEL
+            [BrainState(**b) for b in data[BRAIN_STATES_KEY]], c.UNDEFINED_LABEL
+        ),
+        data[c.DEFAULT_EPOCH_LENGTH_KEY],
+        data.get(c.DEFAULT_OVERWRITE_KEY, c.DEFAULT_OVERWRITE_SETTING),
+        data.get(c.DEFAULT_CONFIDENCE_SETTING_KEY, c.DEFAULT_CONFIDENCE_SETTING),
+        data.get(c.DEFAULT_MIN_BOUT_LENGTH_KEY, c.DEFAULT_MIN_BOUT_LENGTH),
+        EMGFilter(
+            **data.get(
+                c.EMG_FILTER_KEY,
+                {
+                    "order": c.DEFAULT_EMG_FILTER_ORDER,
+                    "bp_lower": c.DEFAULT_EMG_BP_LOWER,
+                    "bp_upper": c.DEFAULT_EMG_BP_UPPER,
+                },
+            )
+        ),
+        Hyperparameters(
+            **data.get(
+                c.HYPERPARAMETERS_KEY,
+                {
+                    "batch_size": c.DEFAULT_BATCH_SIZE,
+                    "learning_rate": c.DEFAULT_LEARNING_RATE,
+                    "momentum": c.DEFAULT_MOMENTUM,
+                    "training_epochs": c.DEFAULT_TRAINING_EPOCHS,
+                },
+            )
         ),
-        data[DEFAULT_EPOCH_LENGTH_KEY],
-        data.get(DEFAULT_CONFIDENCE_SETTING_KEY, True),
     )
 
 
 def save_config(
     brain_state_set: BrainStateSet,
     default_epoch_length: int | float,
+    overwrite_setting: bool,
     save_confidence_setting: bool,
+    min_bout_length: int | float,
+    emg_filter: EMGFilter,
+    hyperparameters: Hyperparameters,
 ) -> None:
     """Save configuration of brain state options to json file
 
     :param brain_state_set: set of brain state options
-    :param default_epoch_length: epoch length to use when the GUI starts
-    :param save_confidence_setting: whether the option to save confidence
-        scores should be True by default
+    :param default_epoch_length: default epoch length
+    :param save_confidence_setting: default setting for
+        saving confidence scores
+    :param emg_filter: EMG filter parameters
+    :param min_bout_length: default minimum bout length
+    :param overwrite_setting: default setting for overwriting
+        existing labels
+    :param hyperparameters: model training hyperparameters
     """
     output_dict = brain_state_set.to_output_dict()
-    output_dict.update({DEFAULT_EPOCH_LENGTH_KEY: default_epoch_length})
-    output_dict.update({DEFAULT_CONFIDENCE_SETTING_KEY: save_confidence_setting})
+    output_dict.update({c.DEFAULT_EPOCH_LENGTH_KEY: default_epoch_length})
+    output_dict.update({c.DEFAULT_OVERWRITE_KEY: overwrite_setting})
+    output_dict.update({c.DEFAULT_CONFIDENCE_SETTING_KEY: save_confidence_setting})
+    output_dict.update({c.DEFAULT_MIN_BOUT_LENGTH_KEY: min_bout_length})
+    output_dict.update({c.EMG_FILTER_KEY: emg_filter.__dict__})
+    output_dict.update({c.HYPERPARAMETERS_KEY: hyperparameters.__dict__})
     with open(
-        os.path.join(os.path.dirname(os.path.abspath(__file__)), CONFIG_FILE), "w"
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), c.CONFIG_FILE), "w"
     ) as f:
         json.dump(output_dict, f, indent=4)
 
@@ -152,7 +203,7 @@ def load_recording_list(filename: str) -> list[Recording]:
     """
     with open(filename, "r") as f:
         data = json.load(f)
-    recording_list = [Recording(**r) for r in data[RECORDING_LIST_NAME]]
+    recording_list = [Recording(**r) for r in data[c.RECORDING_LIST_NAME]]
     for i, r in enumerate(recording_list):
         r.name = i + 1
     return recording_list
@@ -165,7 +216,7 @@ def save_recording_list(filename: str, recordings: list[Recording]) -> None:
     :param recordings: list of recordings to export
     """
     recording_dict = {
-        RECORDING_LIST_NAME: [
+        c.RECORDING_LIST_NAME: [
             {
                 "recording_file": r.recording_file,
                 "label_file": r.label_file,