accusleepy 0.4.0__tar.gz → 0.4.4__tar.gz

{accusleepy-0.4.0 → accusleepy-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: accusleepy
-Version: 0.4.0
+Version: 0.4.4
 Summary: Python implementation of AccuSleep
 License: GPL-3.0-only
 Author: Zeke Barger
@@ -43,6 +43,18 @@ The data and models associated with AccuSleep are available at https://osf.io/py
 
 Please contact zekebarger (at) gmail (dot) com with any questions or comments about the software.
 
+## What's new
+
+AccuSleePy offers the following improvements over the MATLAB version:
+
+- Up to 10 brain states can be configured through the user interface
+- Models can be trained through the user interface
+    - Model files contain useful metadata (brain state configuration,
+      epoch length, number of epochs)
+    - Models optimized for real-time scoring can be trained
+- Lists of recordings can be imported and exported for repeatable batch processing
+- Undo/redo functionality in the manual scoring interface
+
 ## Installation
 
 - (recommended) create a new virtual environment (using
@@ -57,6 +69,17 @@ etc.) using python >=3.10,<3.13
 
 `python -m accusleepy` will open the primary interface.
 
+[Guide to the primary interface](accusleepy/gui/text/main_guide.md)
+
+[Guide to the manual scoring interface](accusleepy/gui/text/manual_scoring_guide.md)
+
+## Screenshots
+Primary interface
+![AccuSleePy primary interface](accusleepy/gui/images/primary_window.png)
+
+Manual scoring interface
+![AccuSleePy manual scoring interface](accusleepy/gui/images/viewer_window.png)
+
 ## Acknowledgements
 
 We would like to thank [Franz Weber](https://www.med.upenn.edu/weberlab/) for creating an

{accusleepy-0.4.0 → accusleepy-0.4.4}/README.md

@@ -15,6 +15,18 @@ The data and models associated with AccuSleep are available at https://osf.io/py
 
 Please contact zekebarger (at) gmail (dot) com with any questions or comments about the software.
 
+## What's new
+
+AccuSleePy offers the following improvements over the MATLAB version:
+
+- Up to 10 brain states can be configured through the user interface
+- Models can be trained through the user interface
+    - Model files contain useful metadata (brain state configuration,
+      epoch length, number of epochs)
+    - Models optimized for real-time scoring can be trained
+- Lists of recordings can be imported and exported for repeatable batch processing
+- Undo/redo functionality in the manual scoring interface
+
 ## Installation
 
 - (recommended) create a new virtual environment (using
@@ -29,6 +41,17 @@ etc.) using python >=3.10,<3.13
 
 `python -m accusleepy` will open the primary interface.
 
+[Guide to the primary interface](accusleepy/gui/text/main_guide.md)
+
+[Guide to the manual scoring interface](accusleepy/gui/text/manual_scoring_guide.md)
+
+## Screenshots
+Primary interface
+![AccuSleePy primary interface](accusleepy/gui/images/primary_window.png)
+
+Manual scoring interface
+![AccuSleePy manual scoring interface](accusleepy/gui/images/viewer_window.png)
+
 ## Acknowledgements
 
 We would like to thank [Franz Weber](https://www.med.upenn.edu/weberlab/) for creating an

{accusleepy-0.4.0 → accusleepy-0.4.4}/accusleepy/gui/main.py

@@ -41,7 +41,6 @@ from accusleepy.fileio import (
     save_model,
     save_recording_list,
 )
-from accusleepy.gui.text.main_guide_text import MAIN_GUIDE_TEXT
 from accusleepy.gui.manual_scoring import ManualScoringWindow
 from accusleepy.gui.primary_window import Ui_PrimaryWindow
 from accusleepy.signal_processing import (
@@ -52,10 +51,11 @@ from accusleepy.signal_processing import (
 )
 
 # max number of messages to display
-MESSAGE_BOX_MAX_DEPTH = 50
+MESSAGE_BOX_MAX_DEPTH = 200
 LABEL_LENGTH_ERROR = "label file length does not match recording length"
 # relative path to config guide txt file
 CONFIG_GUIDE_FILE = os.path.normpath(r"text/config_guide.txt")
+MAIN_GUIDE_FILE = os.path.normpath(r"text/main_guide.md")
 
 
 @dataclass
@@ -294,7 +294,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
             error_message = self.check_single_file_inputs(recording_index)
             if error_message:
                 self.show_message(
-                    f"ERROR ({self.recordings[recording_index].name}): {error_message}"
+                    f"ERROR (recording {self.recordings[recording_index].name}): {error_message}"
                 )
                 return
 
@@ -431,7 +431,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
                     f"error on recording {self.recordings[recording_index].name}"
                 )
                 self.show_message(
-                    f"ERROR ({self.recordings[recording_index].name}): {error_message}"
+                    f"ERROR (recording {self.recordings[recording_index].name}): {error_message}"
                 )
                 return
             if self.recordings[recording_index].calibration_file == "":
@@ -440,7 +440,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
                 )
                 self.show_message(
                     (
-                        f"ERROR ({self.recordings[recording_index].name}): "
+                        f"ERROR (recording {self.recordings[recording_index].name}): "
                         "no calibration file selected"
                     )
                 )
@@ -752,7 +752,7 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
         self.recordings[self.recording_index].calibration_file = filename
         self.ui.calibration_file_label.setText(filename)
 
-    def check_single_file_inputs(self, recording_index: int) -> str:
+    def check_single_file_inputs(self, recording_index: int) -> str | None:
         """Check that a recording's inputs appear valid
 
         This runs some basic tests for whether it will be possible to
@@ -772,6 +772,8 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
             return "invalid epoch length or sampling rate"
         if self.recordings[self.recording_index].recording_file == "":
             return "no recording selected"
+        if not os.path.isfile(self.recordings[self.recording_index].recording_file):
+            return "recording file does not exist"
         if self.recordings[self.recording_index].label_file == "":
             return "no label file selected"
 
@@ -1031,15 +1033,15 @@ class AccuSleepWindow(QtWidgets.QMainWindow):
 
     def show_user_manual(self) -> None:
         """Show a popup window with the user manual"""
-        label_widget = QtWidgets.QLabel()
-        label_widget.setText(MAIN_GUIDE_TEXT)
-        scroll_area = QtWidgets.QScrollArea()
-        scroll_area.setStyleSheet("background-color: white;")
-        scroll_area.setWidget(label_widget)
-        grid = QtWidgets.QGridLayout()
-        grid.addWidget(scroll_area)
         self.popup = QtWidgets.QWidget()
-        self.popup.setLayout(grid)
+        self.popup_vlayout = QtWidgets.QVBoxLayout(self.popup)
+        self.guide_textbox = QtWidgets.QTextBrowser(self.popup)
+        self.popup_vlayout.addWidget(self.guide_textbox)
+
+        url = QtCore.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.show()
 

{accusleepy-0.4.0 → accusleepy-0.4.4}/accusleepy/gui/manual_scoring.py

@@ -27,7 +27,7 @@ LABEL_CMAP = np.concatenate(
     [np.array([[0, 0, 0, 0]]), plt.colormaps["tab10"](range(10))], axis=0
 )
 # relative path to user manual text file
-USER_MANUAL_FILE = os.path.normpath(r"text/manual_scoring_guide.txt")
+USER_MANUAL_FILE = os.path.normpath(r"text/manual_scoring_guide.md")
 
 # constants used by callback functions
 # label formats
@@ -61,7 +61,7 @@ UNDEFINED_STATE = "undefined"
 # before starting to scroll again - must be in (0, 0.5)
 SCROLL_BOUNDARY = 0.35
 # max number of sequential undo actions allowed
-UNDO_LIMIT = 100
+UNDO_LIMIT = 1000
 
 
 @dataclass
@@ -446,8 +446,6 @@ class ManualScoringWindow(QtWidgets.QDialog):
         self.label_img = create_label_img(
             self.display_labels, self.label_display_options
         )
-        # update the plots
-        self.update_figures()
 
     def redo(self) -> None:
         """Redo the last change to brain state labels that was undone"""
@@ -501,21 +499,18 @@ class ManualScoringWindow(QtWidgets.QDialog):
 
     def show_user_manual(self) -> None:
         """Show a popup window with the user manual"""
-        user_manual_file = open(
-            os.path.join(os.path.dirname(os.path.abspath(__file__)), USER_MANUAL_FILE),
-            "r",
+        self.popup = QtWidgets.QWidget()
+        self.popup_vlayout = QtWidgets.QVBoxLayout(self.popup)
+        self.guide_textbox = QtWidgets.QTextBrowser(self.popup)
+        self.popup_vlayout.addWidget(self.guide_textbox)
+
+        url = QtCore.QUrl.fromLocalFile(
+            os.path.join(os.path.dirname(os.path.abspath(__file__)), USER_MANUAL_FILE)
         )
-        user_manual_text = user_manual_file.read()
-        user_manual_file.close()
-        label_widget = QtWidgets.QLabel()
-        label_widget.setText(user_manual_text)
-        label_widget.setStyleSheet("background-color: white;")
+        self.guide_textbox.setSource(url)
+        self.guide_textbox.setOpenLinks(False)
 
-        self.popup = QtWidgets.QWidget()
-        grid = QtWidgets.QGridLayout()
-        grid.addWidget(label_widget)
-        self.popup.setLayout(grid)
-        self.popup.setGeometry(QtCore.QRect(50, 100, 350, 400))
+        self.popup.setGeometry(QtCore.QRect(100, 100, 830, 600))
         self.popup.show()
 
     def jump_to_next_state(self, direction: str, target: str) -> None:
@@ -719,7 +714,6 @@ class ManualScoringWindow(QtWidgets.QDialog):
         self.ui.upperfigure.canvas.axes[2].set_xlim(
             (self.upper_left_epoch, self.upper_right_epoch + 1)
         )
-        self.ui.upperfigure.canvas.draw()
 
     def zoom_x(self, direction: str) -> None:
         """Change upper figure x-axis zoom level
@@ -757,6 +751,7 @@ class ManualScoringWindow(QtWidgets.QDialog):
             self.upper_left_epoch = 0
             self.upper_right_epoch = self.n_epochs - 1
         self.adjust_upper_figure_x_limits()
+        self.ui.upperfigure.canvas.draw()
 
     def modify_current_epoch_label(self, digit: int) -> None:
         """Change the current epoch's brain state label
@@ -977,8 +972,6 @@ class ManualScoringWindow(QtWidgets.QDialog):
         else:
             self.upper_left_epoch = self.epoch - upper_epoch_padding
             self.upper_right_epoch = self.epoch + upper_epoch_padding
-        # update upper marker
-        self.update_upper_marker()
         self.adjust_upper_figure_x_limits()
 
         # update lower figure x-axis range
@@ -993,7 +986,7 @@ class ManualScoringWindow(QtWidgets.QDialog):
             self.lower_left_epoch = self.epoch - lower_epoch_padding
             self.lower_right_epoch = self.epoch + lower_epoch_padding
 
-        self.update_lower_figure()
+        self.update_figures()
 
 
 def convert_labels(labels: np.array, style: str) -> np.array:

accusleepy-0.4.0/accusleepy/gui/text/main_guide_text.py → accusleepy-0.4.4/accusleepy/gui/text/main_guide.md

@@ -1,48 +1,31 @@
-from accusleepy.constants import (
-    BRAIN_STATE_COL,
-    CALIBRATION_FILE_TYPE,
-    EEG_COL,
-    EMG_COL,
-    LABEL_FILE_TYPE,
-    MODEL_FILE_TYPE,
-    RECORDING_FILE_TYPES,
-    UNDEFINED_LABEL,
-)
-
-MAIN_GUIDE_TEXT = f"""
-Section 0: Definitions
-Section 1: Overview of the GUI
-Section 2: AccuSleePy file types
-Section 3: Manually assigning brain state labels
-Section 4: Automatically assigning brain state labels
-
------------------------------------------------------------------------
-Section 0: Definitions
------------------------------------------------------------------------
-Recording: a table containing one channel of EEG data and one channel
-    of EMG data collected at a constant sampling rate.
-Epoch: the temporal resolution of brain state scoring. If, for example,
+# Definitions
+- Recording: a table containing one channel of electroencephalogram (EEG)
+  data and one channel of electromyogram (EMG) data collected at a
+  constant sampling rate.
+- Epoch: the temporal resolution of brain state scoring. If, for example,
     the epoch length is 5 seconds, then a brain state label will be
     assigned to each 5-second segment of a recording.
-Bout: a contiguous set of epochs with the same brain state.
-
------------------------------------------------------------------------
-Section 1: Overview of the primary interface
------------------------------------------------------------------------
-This interface allows a user to assign brain state labels to 1-channel
-electroencephalogram (EEG) and electromyogram (EMG) data.
-The overall workflow looks like this:
-1. Enter the epoch length for all recordings. This determines the time
-    resolution of the brain state labels.
-2. For each of your recordings, add to the recording list, enter its
-    sampling rate, load the EEG/EMG data, and determine where to save
-    the brain state labels (or load the labels if they already exist)
+- Bout: a contiguous set of epochs with the same brain state.
+
+
+# 1. Overview of the primary interface
+
+The workflow for sleep scoring is as follows:
+1. Set the epoch length
+2. For each of your recordings:
+   1. create a new entry in the list of recordings
+   2. enter the sampling rate
+   3. select the recording file containing the EEG and EMG data
+   4. choose a filename for saving the brain state labels,
+       or select an existing label file
+
 At this point, you can score the recordings manually.
+
 3. For each recording, create a calibration file using a small amount
     of labeled data, or choose a calibration file created using
     another recording from the same subject and under the same recording
-    conditions (i.e., equipment)
-4. Choose a trained classification model file with a matching epoch size
+    conditions
+4. Select a trained classification model file with the correct epoch length
 5. Score all recordings automatically using the classifier
 
 By default, there are three brain state options: REM, wake, and NREM.
@@ -53,49 +36,46 @@ classification model.
 
 Use the "import" and "export" buttons to load or save a list of
 recordings. This can be useful if you need to re-score a set of
-recordings with a different model, or if you want to keep a record of
-the recordings that were used when training your model.
+recordings with a new model, or if you want to keep a record of
+the recordings that were used when training a model.
 
------------------------------------------------------------------------
-Section 2: AccuSleePy file types
------------------------------------------------------------------------
+# 2. AccuSleePy file types
 There are four types of files associated with AccuSleePy.
 To select a file in the primary interface, you can either use the
 associated button, or drag/drop the file into the empty box adjacent
 to the button.
-Recording file: a {" or ".join(RECORDING_FILE_TYPES)} file containing one
+- Recording file: a .parquet or .csv file containing one
     column of EEG  data and one column of EMG data.
-    The column names must be {EEG_COL} and {EMG_COL}.
-Label file: a {LABEL_FILE_TYPE} file with one column titled {BRAIN_STATE_COL}
-    with entries that are either the undefined brain state ({UNDEFINED_LABEL})
+    The column names must be eeg and emg.
+- Label file: a .csv file with one column titled brain_state
+    with entries that are either the undefined brain state (by default, this is -1)
     or one of the digits in your brain state configuration.
     By default, these are 1-3 where REM = 1, wake = 2, NREM = 3.
-Calibration data file: required for automatic labeling. See Section 4
-    for details. These have {CALIBRATION_FILE_TYPE} format.
-Trained classification model: required for automatic labeling. See
-    Section 4 for details. These have {MODEL_FILE_TYPE} format.
-
------------------------------------------------------------------------
-Section 3: Manually assigning brain state labels
------------------------------------------------------------------------
+- Calibration data file: required for automated scoring. See Section 4
+    for details. These have .csv format.
+- Trained classification model: required for automated scoring. See
+    Section 4 for details. These have .pth format.
+
+# 3. Manually assigning brain state labels
 1. Select the recording you wish to modify from the recording list, or
     add a new one.
-2. Click the 'Select recording file' button to set the location of the
+2. Click the "Select recording file" button to set the location of the
     EEG/EMG data, or drag/drop the recording file into the box next
     to the button.
-3. Click the 'Select' label file button (or drag/drop) to choose an
-    existing label file, or click the 'create' label file button to
+3. Click the "Select" label file button (or drag/drop) to choose an
+    existing label file, or click the "create" label file button to
     enter the filename for a new label file.
-4. Click 'Score manually' to launch an interactive window for manual
-    brain state labeling. Close the window when you are finished.
-This interface has many useful keyboard shortcuts, so it's recommended
-to consult its user manual.
-
------------------------------------------------------------------------
-Section 4: Automatically scoring recordings with a classification model
------------------------------------------------------------------------
+4. Click "Score manually" to launch an interactive window for manual
+    brain state scoring. When you are finished, save your changes and
+    close the window.
+
+The manual scoring interface has many useful keyboard shortcuts,
+so please consult its user manual by clicking the question mark icon.
+
+# 4. Automatically scoring recordings with a classification model
 Automatic brain state scoring requires the inputs described in
-Section 3, as well as calibration data files and a trained classifier.
+Section 3, as well as calibration data files and a trained classification
+model.
 If you already have all of these files, proceed to Section 4C.
 Models trained on the AccuSleep dataset are provided at
 https://osf.io/py5eb under /python_format/models/ for epoch lengths of
@@ -104,14 +84,18 @@ they use several epochs of data before and after any given epoch when
 scoring that epoch. (The other model type, called "real-time", only
 uses data from the current epoch and several preceding epochs.)
 
---- Section 4A: Creating calibration data files ---
-Each recording must have a calibration file assigned to it.
+## 4A. Creating calibration data files
+
+In order to perform automated sleep scoring,
+each recording must have a calibration file assigned to it.
 This file lets AccuSleep transform features of the EEG and EMG data so
 that they are in the same range as the classifier's training data.
 You can use the same calibration file for multiple recordings, as long
 as they come from the same subject and were collected under the same
 recording conditions (i.e., the same recording equipment was used).
+
 To create a calibration data file:
+
 1. Ensure you have a file containing brain state labels. You can create
     this file by following the steps in Section 3, or select an
     existing label file.
@@ -119,20 +103,23 @@ To create a calibration data file:
     stage (e.g., REM, wakefulness, and NREM). It is recommended to
     label at least several minutes of each stage, and more labels can
     improve classification accuracy.
-3. Click 'Create calibration file'.
+3. Click "Create calibration file".
 4. Enter a filename for the calibration data file.
 5. The calibration file will automatically be assigned to the currently
     selected recording.
+
 Note that epoch length can affect the calibration process. If you make
 a calibration file for a subject using one epoch length, but want to
 score another recording from the same subject with a different epoch
 length, it's best to create a new calibration file.
 
---- Section 4B: Training your own classification model ---
+## 4B. Training your own classification model
+
 To train a new model on your own data:
+
 1. Add your scored recordings to the recording list. Make sure the
     sampling rate, recording file, and label file are set for each
-    recording.
+    recording. Calibration files are not required.
 2. Click the "Model training" tab
 3. Choose the number of epochs to consider when scoring each epoch.
     This will be the "width" of the training images. For "default"
@@ -142,32 +129,34 @@ To train a new model on your own data:
     deleted once training is complete. (It's generally best to
     leave this box checked.)
 5. Choose whether to create a "default" or "real-time"-type model.
-    Note that scoring recordings in the GUI requires a default-type
-    model.
-6. Select a directory where the training images will be saved. A
+    Note that scoring recordings in the primary interface requires
+    a default-type model.
+6. Click "Set training image directory" to select the location
+    where the images used to train the model will be saved. A
     new directory with an automatically generated name will be
     created inside the directory you choose.
-7. Click the "Train classification model" button and enter a
+7. Click "Train classification model" and enter a
     filename for the trained model. Training can take some time.
+    The console will display progress updates.
+
+## 4C. Automatic scoring
+
+Instructions for automatic scoring using this interface are below.
 
---- Section 4C: Automatic labeling ---
-Instructions for automatic labeling using this GUI are below.
 1. Set the epoch length for all recordings.
 2. Select the recording file, label file, and calibration file to use
     for each recording. See section 4A for instructions on creating
     calibration files.
-3. Click 'Load classification model' to load the trained classification
+3. Click "Load classification model" to load the trained classification
     model. It's important that the epoch length used when training this
     model is the same as the current epoch length.
 4. If you wish to preserve any existing labels in the label file, and
     only overwrite undefined epochs, check the box labeled
-    'Only overwrite undefined epochs'.
+    "Only overwrite undefined epochs".
 5. Set the minimum bout length, in seconds. A typical value could be 5.
     Following automatic labeling, any brain state bout shorter than this
-    duration will be reassigned to the surrounding stage (if the stages
-    on either side of the bout match).
-6. Click 'Score all automatically' to score all recordings in the
-    recording list. Labels will be saved to the file specified by
-    the 'Select or create label file' field of each recording. You can
-    click 'Score manually' to visualize the results.
-"""
+    duration will be reassigned to the surrounding state (if the states
+    on either side of the bout are the same).
+6. Click "Score all automatically" to score all recordings in the
+    recording list. To inspect the results, select a recording
+    in the list and click "Score manually".

accusleepy-0.4.4/accusleepy/gui/text/manual_scoring_guide.md

@@ -0,0 +1,23 @@
+# Manual scoring interface
+
+Keyboard shortcuts:
+- Mouse click on the upper 3 plots: jump to epoch
+- Ctrl + S: save labels to file
+- Right / left arrow: move one epoch forward / backward in time
+- Numbers 0-9: set current epoch to this brain state
+- Backspace: set current epoch to the undefined state
+- Ctrl + Z: undo last change to brain state labels
+- Ctrl + Y: redo last change to brain state labels
+- Shift + (number 0-9, or backspace):
+    After pressing this combination, click and drag on the upper plot of brain
+    state labels to set the selected epochs
+    to this brain state. Press Escape to cancel.
+- Plus (+): zoom in (upper panel x-axis)
+- Minus (-): zoom out (upper panel x-axis)
+- Shift + right / left arrow: jump to the next / previous epoch with a different brain state
+    than the current epoch
+- Spacebar: equivalent to shift + right arrow
+- Ctrl + right / left arrow: jump to the next / preceding undefined epoch
+- Ctrl + W: quit
+
+![ ](../images/viewer_window_annotated.png)

{accusleepy-0.4.0 → accusleepy-0.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "accusleepy"
-version = "0.4.0"
+version = "0.4.4"
 description = "Python implementation of AccuSleep"
 authors = [
     {name = "Zeke Barger",email = "zekebarger@gmail.com"}

accusleepy-0.4.0/accusleepy/gui/text/manual_scoring_guide.txt

@@ -1,28 +0,0 @@
-The lower panel shows a zoomed-in subset of the epochs shown in the upper panel.
-The red diamond in the upper panel and the red lines in the lower panel
-mark the currently selected epoch.
-The red horizontal line in the upper panel indicates the epochs shown in the lower panel.
-Click a location on the upper panel to jump to that epoch.
-The buttons next to the spectrogram control the zoom level and intensity.
-The buttons next to the EEG and EMG plots control the zoom level and y-axis offset.
-If "auto-scroll" is enabled, modifying the brain state of the current epoch
-will automatically select the next epoch.
-
-Keyboard shortcuts:
-Ctrl + S: save labels to file
-Right arrow: move one epoch forward in time
-Left arrow: move one epoch backward in time
-Numbers 0-9: set current epoch to this brain state
-Backspace: set current epoch to undefined
-Ctrl + Z: undo last change to brain state labels
-Ctrl + Y: redo last change to brain state labels
-Shift + (number 0-9, or backspace):
-    Click and drag on the upper plot of brain state labels to set the selected epochs
-    to the desired brain state. Press Esc to cancel.
-+: zoom in (upper panel x-axis)
--: zoom out (upper panel x-axis)
-Shift + right arrow, or space: jump to the next epoch of a different state
-    than the current epoch
-Shift + left arrow: jump to the preceding epoch of a different state than the current epoch
-Ctrl + right/left arrow: jump to the next/preceding undefined epoch
-Ctrl + W: quit