accusleepy 0.4.4__py3-none-any.whl → 0.5.0__py3-none-any.whl

accusleepy/bouts.py

@@ -0,0 +1,142 @@
+import re
+from dataclasses import dataclass
+from operator import attrgetter
+
+import numpy as np
+
+
+@dataclass
+class Bout:
+    """Stores information about a brain state bout"""
+
+    length: int  # length, in number of epochs
+    start_index: int  # index where bout starts
+    end_index: int  # index where bout ends
+    surrounding_state: int  # brain state on both sides of the bout
+
+
+def find_last_adjacent_bout(sorted_bouts: list[Bout], bout_index: int) -> int:
+    """Find index of last consecutive same-length bout
+
+     When running the post-processing step that enforces a minimum duration
+     for brain state bouts, there is a special case when bouts below the
+     duration threshold occur consecutively. This function performs a
+     recursive search for the index of a bout at the end of such a sequence.
+     When initially called, bout_index will always be 0. If, for example, the
+     first three bouts in the list are consecutive, the function will return 2.
+
+    :param sorted_bouts: list of brain state bouts, sorted by start time
+    :param bout_index: index of the bout in question
+    :return: index of the last consecutive same-length bout
+    """
+    # if we're at the end of the bout list, stop
+    if bout_index == len(sorted_bouts) - 1:
+        return bout_index
+
+    # if there is an adjacent bout
+    if sorted_bouts[bout_index].end_index == sorted_bouts[bout_index + 1].start_index:
+        # look for more adjacent bouts using that one as a starting point
+        return find_last_adjacent_bout(sorted_bouts, bout_index + 1)
+    else:
+        return bout_index
+
+
+def enforce_min_bout_length(
+    labels: np.array, epoch_length: int | float, min_bout_length: int | float
+) -> np.array:
+    """Ensure brain state bouts meet the min length requirement
+
+    As a post-processing step for sleep scoring, we can require that any
+    bout (continuous period) of a brain state have a minimum duration.
+    This function sets any bout shorter than the minimum duration to the
+    surrounding brain state (if the states on the left and right sides
+    are the same). In the case where there are consecutive short bouts,
+    it either creates a transition at the midpoint or removes all short
+    bouts, depending on whether the number is even or odd. For example:
+    ...AAABABAAA...  -> ...AAAAAAAAA...
+    ...AAABABABBB... -> ...AAAAABBBBB...
+
+    :param labels: brain state labels (digits in the 0-9 range)
+    :param epoch_length: epoch length, in seconds
+    :param min_bout_length: minimum bout length, in seconds
+    :return: updated brain state labels
+    """
+    # if recording is very short, don't change anything
+    if labels.size < 3:
+        return labels
+
+    if epoch_length == min_bout_length:
+        return labels
+
+    # get minimum number of epochs in a bout
+    min_epochs = int(np.ceil(min_bout_length / epoch_length))
+    # get set of states in the labels
+    brain_states = set(labels.tolist())
+
+    while True:  # so true
+        # convert labels to a string for regex search
+        # There is probably a regex that can find all patterns like ab+a
+        # without consuming each "a" but I haven't found it :(
+        label_string = "".join(labels.astype(str))
+
+        bouts = list()
+
+        for state in brain_states:
+            for other_state in brain_states:
+                if state == other_state:
+                    continue
+                # get start and end indices of each bout
+                expression = (
+                    f"(?<={other_state}){state}{{1,{min_epochs - 1}}}(?={other_state})"
+                )
+                matches = re.finditer(expression, label_string)
+                spans = [match.span() for match in matches]
+
+                # if some bouts were found
+                for span in spans:
+                    bouts.append(
+                        Bout(
+                            length=span[1] - span[0],
+                            start_index=span[0],
+                            end_index=span[1],
+                            surrounding_state=other_state,
+                        )
+                    )
+
+        if len(bouts) == 0:
+            break
+
+        # only keep the shortest bouts
+        min_length_in_list = np.min([bout.length for bout in bouts])
+        bouts = [i for i in bouts if i.length == min_length_in_list]
+        # sort by start index
+        sorted_bouts = sorted(bouts, key=attrgetter("start_index"))
+
+        while len(sorted_bouts) > 0:
+            # get row index of latest adjacent bout (of same length)
+            last_adjacent_bout_index = find_last_adjacent_bout(sorted_bouts, 0)
+            # if there's an even number of adjacent bouts
+            if (last_adjacent_bout_index + 1) % 2 == 0:
+                midpoint = sorted_bouts[
+                    round((last_adjacent_bout_index + 1) / 2)
+                ].start_index
+                labels[sorted_bouts[0].start_index : midpoint] = sorted_bouts[
+                    0
+                ].surrounding_state
+                labels[midpoint : sorted_bouts[last_adjacent_bout_index].end_index] = (
+                    sorted_bouts[last_adjacent_bout_index].surrounding_state
+                )
+            else:
+                labels[
+                    sorted_bouts[0].start_index : sorted_bouts[
+                        last_adjacent_bout_index
+                    ].end_index
+                ] = sorted_bouts[0].surrounding_state
+
+            # delete the bouts we just fixed
+            if last_adjacent_bout_index == len(sorted_bouts) - 1:
+                sorted_bouts = []
+            else:
+                sorted_bouts = sorted_bouts[(last_adjacent_bout_index + 1) :]
+
+    return labels

accusleepy/classification.py

@@ -61,13 +61,13 @@ def get_device():
     )
 
 
-def train_model(
+def train_ssann(
     annotations_file: str,
     img_dir: str,
     mixture_weights: np.array,
     n_classes: int,
 ) -> SSANN:
-    """Train a classification model for sleep scoring
+    """Train a SSANN classification model for sleep scoring
 
     :param annotations_file: file with information on each training image
     :param img_dir: training image location

accusleepy/constants.py

@@ -37,3 +37,5 @@ RECORDING_LIST_NAME = "recording_list"
 RECORDING_LIST_FILE_TYPE = ".json"
 # key for default epoch length in config
 DEFAULT_EPOCH_LENGTH_KEY = "default_epoch_length"
+# filename used to store info about training image datasets
+ANNOTATIONS_FILENAME = "annotations.csv"

accusleepy/fileio.py

@@ -4,7 +4,6 @@ from dataclasses import dataclass
 
 import numpy as np
 import pandas as pd
-import torch
 from PySide6.QtWidgets import QListWidgetItem
 
 from accusleepy.brain_state_set import BRAIN_STATES_KEY, BrainState, BrainStateSet
@@ -19,7 +18,6 @@ from accusleepy.constants import (
     RECORDING_LIST_NAME,
     UNDEFINED_LABEL,
 )
-from accusleepy.models import SSANN
 
 
 @dataclass
@@ -46,57 +44,6 @@ def load_calibration_file(filename: str) -> (np.array, np.array):
     return mixture_means, mixture_sds
 
 
-def save_model(
-    model: SSANN,
-    filename: str,
-    epoch_length: int | float,
-    epochs_per_img: int,
-    model_type: str,
-    brain_state_set: BrainStateSet,
-) -> None:
-    """Save classification model and its metadata
-
-    :param model: classification model
-    :param epoch_length: epoch length used when training the model
-    :param epochs_per_img: number of epochs in each model input
-    :param model_type: default or real-time
-    :param brain_state_set: set of brain state options
-    :param filename: filename
-    """
-    state_dict = model.state_dict()
-    state_dict.update({"epoch_length": epoch_length})
-    state_dict.update({"epochs_per_img": epochs_per_img})
-    state_dict.update({"model_type": model_type})
-    state_dict.update(
-        {BRAIN_STATES_KEY: brain_state_set.to_output_dict()[BRAIN_STATES_KEY]}
-    )
-
-    torch.save(state_dict, filename)
-
-
-def load_model(filename: str) -> tuple[SSANN, int | float, int, str, dict]:
-    """Load classification model and its metadata
-
-    :param filename: filename
-    :return: model, epoch length used when training the model,
-        number of epochs in each model input, model type
-        (default or real-time), set of brain state options
-        used when training the model
-    """
-    state_dict = torch.load(
-        filename, weights_only=True, map_location=torch.device("cpu")
-    )
-    epoch_length = state_dict.pop("epoch_length")
-    epochs_per_img = state_dict.pop("epochs_per_img")
-    model_type = state_dict.pop("model_type")
-    brain_states = state_dict.pop(BRAIN_STATES_KEY)
-    n_classes = len([b for b in brain_states if b["is_scored"]])
-
-    model = SSANN(n_classes=n_classes)
-    model.load_state_dict(state_dict)
-    return model, epoch_length, epochs_per_img, model_type, brain_states
-
-
 def load_csv_or_parquet(filename: str) -> pd.DataFrame:
     """Load a csv or parquet file as a dataframe
 

accusleepy/gui/main.py

@@ -5,20 +5,37 @@ import datetime
 import os
 import shutil
 import sys
-import toml
 from dataclasses import dataclass
 from functools import partial
 
 import numpy as np
-from PySide6 import QtCore, QtGui, QtWidgets
+import toml
+from PySide6.QtCore import (
+    QEvent,
+    QKeyCombination,
+    QObject,
+    QRect,
+    Qt,
+    QUrl,
+)
+from PySide6.QtGui import QKeySequence, QShortcut
+from PySide6.QtWidgets import (
+    QApplication,
+    QCheckBox,
+    QDoubleSpinBox,
+    QFileDialog,
+    QLabel,
+    QListWidgetItem,
+    QMainWindow,
+    QTextBrowser,
+    QVBoxLayout,
+    QWidget,
+)
 
+from accusleepy.bouts import enforce_min_bout_length
 from accusleepy.brain_state_set import BRAIN_STATES_KEY, BrainState, BrainStateSet
-from accusleepy.classification import (
-    create_calibration_file,
-    score_recording,
-    train_model,
-)
 from accusleepy.constants import (
+    ANNOTATIONS_FILENAME,
     CALIBRATION_FILE_TYPE,
     DEFAULT_MODEL_TYPE,
     LABEL_FILE_TYPE,
@@ -33,23 +50,21 @@ from accusleepy.fileio import (
     load_calibration_file,
     load_config,
     load_labels,
-    load_model,
     load_recording,
     load_recording_list,
     save_config,
     save_labels,
-    save_model,
     save_recording_list,
 )
 from accusleepy.gui.manual_scoring import ManualScoringWindow
 from accusleepy.gui.primary_window import Ui_PrimaryWindow
 from accusleepy.signal_processing import (
-    ANNOTATIONS_FILENAME,
     create_training_images,
-    enforce_min_bout_length,
     resample_and_standardize,
 )
 
+# note: functions using torch or scipy are lazily imported
+
 # max number of messages to display
 MESSAGE_BOX_MAX_DEPTH = 200
 LABEL_LENGTH_ERROR = "label file length does not match recording length"
@@ -63,13 +78,13 @@ class StateSettings:
     """Widgets for config settings for a brain state"""
 
     digit: int
-    enabled_widget: QtWidgets.QCheckBox
-    name_widget: QtWidgets.QLabel
-    is_scored_widget: QtWidgets.QCheckBox
-    frequency_widget: QtWidgets.QDoubleSpinBox
+    enabled_widget: QCheckBox
+    name_widget: QLabel
+    is_scored_widget: QCheckBox
+    frequency_widget: QDoubleSpinBox
 
 
-class AccuSleepWindow(QtWidgets.QMainWindow):
+class AccuSleepWindow(QMainWindow):
     """AccuSleePy primary window"""
 
     def __init__(self):
@@ -103,9 +118,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
         # set up the list of recordings
         first_recording = Recording(
-            widget=QtWidgets.QListWidgetItem(
-                "Recording 1", self.ui.recording_list_widget
-            ),
+            widget=QListWidgetItem("Recording 1", self.ui.recording_list_widget),
         )
         self.ui.recording_list_widget.addItem(first_recording.widget)
         self.ui.recording_list_widget.setCurrentRow(0)
@@ -132,10 +145,8 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
         self.ui.version_label.setText(f"v{version}")
 
         # user input: keyboard shortcuts
-        keypress_quit = QtGui.QShortcut(
-            QtGui.QKeySequence(
-                QtCore.QKeyCombination(QtCore.Qt.Modifier.CTRL, QtCore.Qt.Key.Key_W)
-            ),
+        keypress_quit = QShortcut(
+            QKeySequence(QKeyCombination(Qt.Modifier.CTRL, Qt.Key.Key_W)),
             self,
         )
         keypress_quit.activated.connect(self.close)
@@ -187,7 +198,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
     def export_recording_list(self) -> None:
         """Save current list of recordings to file"""
         # get the name for the recording list file
-        filename, _ = QtWidgets.QFileDialog.getSaveFileName(
+        filename, _ = QFileDialog.getSaveFileName(
             self,
             caption="Save list of recordings as",
             filter="*" + RECORDING_LIST_FILE_TYPE,
@@ -200,10 +211,10 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
     def import_recording_list(self):
         """Load list of recordings from file, overwriting current list"""
-        file_dialog = QtWidgets.QFileDialog(self)
+        file_dialog = QFileDialog(self)
         file_dialog.setWindowTitle("Select list of recordings")
-        file_dialog.setFileMode(QtWidgets.QFileDialog.FileMode.ExistingFile)
-        file_dialog.setViewMode(QtWidgets.QFileDialog.ViewMode.Detail)
+        file_dialog.setFileMode(QFileDialog.FileMode.ExistingFile)
+        file_dialog.setViewMode(QFileDialog.ViewMode.Detail)
         file_dialog.setNameFilter("*" + RECORDING_LIST_FILE_TYPE)
 
         if file_dialog.exec():
@@ -219,7 +230,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
         self.recordings = load_recording_list(filename)
 
         for recording in self.recordings:
-            recording.widget = QtWidgets.QListWidgetItem(
+            recording.widget = QListWidgetItem(
                 f"Recording {recording.name}", self.ui.recording_list_widget
             )
             self.ui.recording_list_widget.addItem(self.recordings[-1].widget)
@@ -228,7 +239,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
         self.ui.recording_list_widget.setCurrentRow(0)
         self.show_message(f"Loaded list of recordings from {filename}")
 
-    def eventFilter(self, obj: QtCore.QObject, event: QtCore.QEvent) -> bool:
+    def eventFilter(self, obj: QObject, event: QEvent) -> bool:
         """Filter mouse events to detect when user drags/drops a file
 
         :param obj: UI object receiving the event
@@ -243,7 +254,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
             self.ui.model_label,
         ]:
             event.accept()
-            if event.type() == QtCore.QEvent.Drop:
+            if event.type() == QEvent.Drop:
                 urls = event.mimeData().urls()
                 if len(urls) == 1:
                     filename = os.path.normpath(urls[0].toLocalFile())
@@ -299,7 +310,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
                 return
 
         # get filename for the new model
-        model_filename, _ = QtWidgets.QFileDialog.getSaveFileName(
+        model_filename, _ = QFileDialog.getSaveFileName(
             self,
             caption="Save classification model file as",
             filter="*" + MODEL_FILE_TYPE,
@@ -322,11 +333,10 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
         os.makedirs(temp_image_dir, exist_ok=True)
 
         # create training images
-        self.show_message(
-            (f"Creating training images in {temp_image_dir}, please wait...")
-        )
+        self.show_message("Training, please wait. See console for progress updates.")
+        self.show_message((f"Creating training images in {temp_image_dir}"))
         self.ui.message_area.repaint()
-        QtWidgets.QApplication.processEvents()
+        QApplication.processEvents()
         print("Creating training images")
         failed_recordings = create_training_images(
             recordings=self.recordings,
@@ -349,11 +359,14 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
                 )
 
         # train model
-        self.show_message("Training model, please wait...")
+        self.show_message("Training model")
         self.ui.message_area.repaint()
-        QtWidgets.QApplication.processEvents()
+        QApplication.processEvents()
         print("Training model")
-        model = train_model(
+        from accusleepy.classification import train_ssann
+        from accusleepy.models import save_model
+
+        model = train_ssann(
             annotations_file=os.path.join(temp_image_dir, ANNOTATIONS_FILENAME),
             img_dir=temp_image_dir,
             mixture_weights=self.brain_state_set.mixture_weights,
@@ -374,11 +387,12 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
         if self.delete_training_images:
             shutil.rmtree(temp_image_dir)
 
-        self.show_message(f"Training complete, saved model to {model_filename}")
+        self.show_message(f"Training complete. Saved model to {model_filename}")
+        print("Training complete.")
 
     def set_training_folder(self) -> None:
         """Select location in which to create a folder for training images"""
-        training_folder_parent = QtWidgets.QFileDialog.getExistingDirectory(
+        training_folder_parent = QFileDialog.getExistingDirectory(
             self, "Select directory for training images"
         )
         if training_folder_parent:
@@ -421,7 +435,9 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
         self.ui.score_all_status.setText("running...")
         self.ui.score_all_status.repaint()
-        QtWidgets.QApplication.processEvents()
+        QApplication.processEvents()
+
+        from accusleepy.classification import score_recording
 
         # check some inputs for each recording
         for recording_index in range(len(self.recordings)):
@@ -570,11 +586,13 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
         :param filename: model filename, if it's known
         """
+        from accusleepy.models import load_model
+
         if filename is None:
-            file_dialog = QtWidgets.QFileDialog(self)
+            file_dialog = QFileDialog(self)
             file_dialog.setWindowTitle("Select classification model")
-            file_dialog.setFileMode(QtWidgets.QFileDialog.FileMode.ExistingFile)
-            file_dialog.setViewMode(QtWidgets.QFileDialog.ViewMode.Detail)
+            file_dialog.setFileMode(QFileDialog.FileMode.ExistingFile)
+            file_dialog.setViewMode(QFileDialog.ViewMode.Detail)
             file_dialog.setNameFilter("*" + MODEL_FILE_TYPE)
 
             if file_dialog.exec():
@@ -634,7 +652,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
         self.ui.model_label.setText(filename)
 
     def load_single_recording(
-        self, status_widget: QtWidgets.QLabel
+        self, status_widget: QLabel
     ) -> (np.array, np.array, int | float, bool):
         """Load and preprocess one recording
 
@@ -721,7 +739,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
             return
 
         # get the name for the calibration file
-        filename, _ = QtWidgets.QFileDialog.getSaveFileName(
+        filename, _ = QFileDialog.getSaveFileName(
             self,
             caption="Save calibration file as",
             filter="*" + CALIBRATION_FILE_TYPE,
@@ -730,6 +748,8 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
             return
         filename = os.path.normpath(filename)
 
+        from accusleepy.classification import create_calibration_file
+
         create_calibration_file(
             filename=filename,
             eeg=eeg,
@@ -799,7 +819,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
         # immediately display a status message
         self.ui.manual_scoring_status.setText("loading...")
         self.ui.manual_scoring_status.repaint()
-        QtWidgets.QApplication.processEvents()
+        QApplication.processEvents()
 
         # load the recording
         eeg, emg, sampling_rate, success = self.load_single_recording(
@@ -889,7 +909,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
     def create_label_file(self) -> None:
         """Set the filename for a new label file"""
-        filename, _ = QtWidgets.QFileDialog.getSaveFileName(
+        filename, _ = QFileDialog.getSaveFileName(
             self,
             caption="Set filename for label file (nothing will be overwritten yet)",
             filter="*" + LABEL_FILE_TYPE,
@@ -901,10 +921,10 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
     def select_label_file(self) -> None:
         """User can select an existing label file"""
-        file_dialog = QtWidgets.QFileDialog(self)
+        file_dialog = QFileDialog(self)
         file_dialog.setWindowTitle("Select label file")
-        file_dialog.setFileMode(QtWidgets.QFileDialog.FileMode.ExistingFile)
-        file_dialog.setViewMode(QtWidgets.QFileDialog.ViewMode.Detail)
+        file_dialog.setFileMode(QFileDialog.FileMode.ExistingFile)
+        file_dialog.setViewMode(QFileDialog.ViewMode.Detail)
         file_dialog.setNameFilter("*" + LABEL_FILE_TYPE)
 
         if file_dialog.exec():
@@ -916,10 +936,10 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
     def select_calibration_file(self) -> None:
         """User can select a calibration file"""
-        file_dialog = QtWidgets.QFileDialog(self)
+        file_dialog = QFileDialog(self)
         file_dialog.setWindowTitle("Select calibration file")
-        file_dialog.setFileMode(QtWidgets.QFileDialog.FileMode.ExistingFile)
-        file_dialog.setViewMode(QtWidgets.QFileDialog.ViewMode.Detail)
+        file_dialog.setFileMode(QFileDialog.FileMode.ExistingFile)
+        file_dialog.setViewMode(QFileDialog.ViewMode.Detail)
         file_dialog.setNameFilter("*" + CALIBRATION_FILE_TYPE)
 
         if file_dialog.exec():
@@ -931,10 +951,10 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
     def select_recording_file(self) -> None:
         """User can select a recording file"""
-        file_dialog = QtWidgets.QFileDialog(self)
+        file_dialog = QFileDialog(self)
         file_dialog.setWindowTitle("Select recording file")
-        file_dialog.setFileMode(QtWidgets.QFileDialog.FileMode.ExistingFile)
-        file_dialog.setViewMode(QtWidgets.QFileDialog.ViewMode.Detail)
+        file_dialog.setFileMode(QFileDialog.FileMode.ExistingFile)
+        file_dialog.setViewMode(QFileDialog.ViewMode.Detail)
         file_dialog.setNameFilter(f"(*{' *'.join(RECORDING_FILE_TYPES)})")
 
         if file_dialog.exec():
@@ -1009,7 +1029,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
             Recording(
                 name=new_name,
                 sampling_rate=self.recordings[self.recording_index].sampling_rate,
-                widget=QtWidgets.QListWidgetItem(
+                widget=QListWidgetItem(
                     f"Recording {new_name}", self.ui.recording_list_widget
                 ),
             )
@@ -1033,16 +1053,16 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
     def show_user_manual(self) -> None:
         """Show a popup window with the user manual"""
-        self.popup = QtWidgets.QWidget()
-        self.popup_vlayout = QtWidgets.QVBoxLayout(self.popup)
-        self.guide_textbox = QtWidgets.QTextBrowser(self.popup)
+        self.popup = QWidget()
+        self.popup_vlayout = QVBoxLayout(self.popup)
+        self.guide_textbox = QTextBrowser(self.popup)
         self.popup_vlayout.addWidget(self.guide_textbox)
 
-        url = QtCore.QUrl.fromLocalFile(MAIN_GUIDE_FILE)
+        url = QUrl.fromLocalFile(MAIN_GUIDE_FILE)
         self.guide_textbox.setSource(url)
         self.guide_textbox.setOpenLinks(False)
 
-        self.popup.setGeometry(QtCore.QRect(100, 100, 600, 600))
+        self.popup.setGeometry(QRect(100, 100, 600, 600))
         self.popup.show()
 
     def initialize_settings_tab(self):
@@ -1389,7 +1409,7 @@ def check_config_consistency(
 
 
 def run_primary_window() -> None:
-    app = QtWidgets.QApplication(sys.argv)
+    app = QApplication(sys.argv)
     AccuSleepWindow()
     sys.exit(app.exec())