accusleepy 0.8.1__py3-none-any.whl → 0.9.2__py3-none-any.whl

accusleepy/bouts.py

@@ -42,7 +42,7 @@ def find_last_adjacent_bout(sorted_bouts: list[Bout], bout_index: int) -> int:
 
 
 def find_short_bouts(
-    labels: np.array, min_epochs: int, brain_states: set[int]
+    labels: np.ndarray, min_epochs: int, brain_states: set[int]
 ) -> list[Bout]:
     """Locate all brain state bouts below a minimum length
 
@@ -80,8 +80,8 @@ def find_short_bouts(
 
 
 def enforce_min_bout_length(
-    labels: np.array, epoch_length: int | float, min_bout_length: int | float
-) -> np.array:
+    labels: np.ndarray, epoch_length: int | float, min_bout_length: int | float
+) -> np.ndarray:
     """Ensure brain state bouts meet the min length requirement
 
     As a post-processing step for sleep scoring, we can require that any

accusleepy/brain_state_set.py

@@ -41,7 +41,7 @@ class BrainStateSet:
         i = 0
         for brain_state in self.brain_states:
             if brain_state.digit == undefined_label:
-                raise Exception(
+                raise ValueError(
                     f"Digit for {brain_state.name} matches 'undefined' label"
                 )
             if brain_state.is_scored:
@@ -56,9 +56,11 @@ class BrainStateSet:
 
         self.mixture_weights = np.array(self.mixture_weights)
         if np.sum(self.mixture_weights) != 1:
-            raise Exception("Typical frequencies for scored brain states must sum to 1")
+            raise ValueError(
+                "Typical frequencies for scored brain states must sum to 1"
+            )
 
-    def convert_digit_to_class(self, digits: np.array) -> np.array:
+    def convert_digit_to_class(self, digits: np.ndarray) -> np.ndarray:
         """Convert array of digits to their corresponding classes
 
         :param digits: array of digits
@@ -66,7 +68,7 @@ class BrainStateSet:
         """
         return np.array([self.digit_to_class[i] for i in digits])
 
-    def convert_class_to_digit(self, classes: np.array) -> np.array:
+    def convert_class_to_digit(self, classes: np.ndarray) -> np.ndarray:
         """Convert array of classes to their corresponding digits
 
         :param classes: array of classes

accusleepy/classification.py

@@ -16,7 +16,6 @@ from accusleepy.models import SSANN
 from accusleepy.signal_processing import (
     create_eeg_emg_image,
     format_img,
-    get_mixture_values,
     mixture_z_score_img,
 )
 
@@ -84,7 +83,7 @@ def create_dataloader(
 def train_ssann(
     annotations_file: str,
     img_dir: str,
-    mixture_weights: np.array,
+    training_class_balance: np.ndarray,
     n_classes: int,
     hyperparameters: Hyperparameters,
 ) -> SSANN:
@@ -92,7 +91,7 @@ def train_ssann(
 
     :param annotations_file: file with information on each training image
     :param img_dir: training image location
-    :param mixture_weights: typical relative frequencies of brain states
+    :param training_class_balance: proportion of each class in the training set
     :param n_classes: number of classes the model will learn
     :param hyperparameters: model training hyperparameters
     :return: trained Sleep Scoring Artificial Neural Network model
@@ -109,7 +108,7 @@ def train_ssann(
     model.train()
 
     # correct for class imbalance
-    weight = torch.tensor((mixture_weights**-1).astype("float32")).to(device)
+    weight = torch.tensor((training_class_balance**-1).astype("float32")).to(device)
 
     criterion = nn.CrossEntropyLoss(weight=weight)
     optimizer = optim.SGD(
@@ -133,16 +132,16 @@ def train_ssann(
 
 def score_recording(
     model: SSANN,
-    eeg: np.array,
-    emg: np.array,
-    mixture_means: np.array,
-    mixture_sds: np.array,
+    eeg: np.ndarray,
+    emg: np.ndarray,
+    mixture_means: np.ndarray,
+    mixture_sds: np.ndarray,
     sampling_rate: int | float,
     epoch_length: int | float,
     epochs_per_img: int,
     brain_state_set: BrainStateSet,
     emg_filter: EMGFilter,
-) -> np.array:
+) -> tuple[np.ndarray, np.ndarray]:
     """Use classification model to get brain state labels for a recording
 
     This assumes signals have been preprocessed to contain an integer
@@ -167,7 +166,7 @@ def score_recording(
 
     # create and scale eeg+emg spectrogram
     img = create_eeg_emg_image(eeg, emg, sampling_rate, epoch_length, emg_filter)
-    img = mixture_z_score_img(
+    img, _ = mixture_z_score_img(
         img,
         mixture_means=mixture_means,
         mixture_sds=mixture_sds,
@@ -196,10 +195,10 @@ def score_recording(
 
 def example_real_time_scoring_function(
     model: SSANN,
-    eeg: np.array,
-    emg: np.array,
-    mixture_means: np.array,
-    mixture_sds: np.array,
+    eeg: np.ndarray,
+    emg: np.ndarray,
+    mixture_means: np.ndarray,
+    mixture_sds: np.ndarray,
     sampling_rate: int | float,
     epoch_length: int | float,
     epochs_per_img: int,
@@ -244,7 +243,7 @@ def example_real_time_scoring_function(
 
     # create and scale eeg+emg spectrogram
     img = create_eeg_emg_image(eeg, emg, sampling_rate, epoch_length, emg_filter)
-    img = mixture_z_score_img(
+    img, _ = mixture_z_score_img(
         img,
         mixture_means=mixture_means,
         mixture_sds=mixture_sds,
@@ -264,38 +263,3 @@ def example_real_time_scoring_function(
 
     label = int(brain_state_set.convert_class_to_digit(predicted.cpu().numpy())[0])
     return label
-
-
-def create_calibration_file(
-    filename: str,
-    eeg: np.array,
-    emg: np.array,
-    labels: np.array,
-    sampling_rate: int | float,
-    epoch_length: int | float,
-    brain_state_set: BrainStateSet,
-    emg_filter: EMGFilter,
-) -> None:
-    """Create file of calibration data for a subject
-
-    This assumes signals have been preprocessed to contain an integer
-    number of epochs.
-
-    :param filename: filename for the calibration file
-    :param eeg: EEG signal
-    :param emg: EMG signal
-    :param labels: brain state labels, as digits
-    :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, emg_filter)
-    mixture_means, mixture_sds = get_mixture_values(
-        img=img,
-        labels=brain_state_set.convert_digit_to_class(labels),
-        brain_state_set=brain_state_set,
-    )
-    pd.DataFrame(
-        {c.MIXTURE_MEAN_COL: mixture_means, c.MIXTURE_SD_COL: mixture_sds}
-    ).to_csv(filename, index=False)

accusleepy/constants.py

@@ -18,6 +18,9 @@ MESSAGE_BOX_MAX_DEPTH = 200
 ABS_MAX_Z_SCORE = 3.5
 # upper frequency limit when generating EEG spectrograms
 SPECTROGRAM_UPPER_FREQ = 64
+# minimum number of epochs per brain state needed to create
+# a calibration file or use a recording for model training
+MIN_EPOCHS_PER_STATE = 3
 
 
 # very unlikely you will want to change values from here onwards

accusleepy/fileio.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 import numpy as np
 import pandas as pd
 from PySide6.QtWidgets import QListWidgetItem
+import toml
 
 from accusleepy.brain_state_set import BRAIN_STATES_KEY, BrainState, BrainStateSet
 import accusleepy.constants as c
@@ -56,7 +57,7 @@ class Recording:
     widget: QListWidgetItem = None  # list item widget shown in the GUI
 
 
-def load_calibration_file(filename: str) -> (np.array, np.array):
+def load_calibration_file(filename: str) -> tuple[np.ndarray, np.ndarray]:
     """Load a calibration file
 
     :param filename: filename
@@ -80,11 +81,11 @@ def load_csv_or_parquet(filename: str) -> pd.DataFrame:
     elif extension == ".parquet":
         df = pd.read_parquet(filename)
     else:
-        raise Exception("file must be csv or parquet")
+        raise ValueError("file must be csv or parquet")
     return df
 
 
-def load_recording(filename: str) -> (np.array, np.array):
+def load_recording(filename: str) -> tuple[np.ndarray, np.ndarray]:
     """Load recording of EEG and EMG time series data
 
     :param filename: filename
@@ -96,7 +97,7 @@ def load_recording(filename: str) -> (np.array, np.array):
     return eeg, emg
 
 
-def load_labels(filename: str) -> (np.array, np.array):
+def load_labels(filename: str) -> tuple[np.ndarray, np.ndarray | None]:
     """Load file of brain state labels and confidence scores
 
     :param filename: filename
@@ -110,7 +111,7 @@ def load_labels(filename: str) -> (np.array, np.array):
 
 
 def save_labels(
-    labels: np.array, filename: str, confidence_scores: np.array = None
+    labels: np.ndarray, filename: str, confidence_scores: np.ndarray | None = None
 ) -> None:
     """Save brain state labels to file
 
@@ -223,6 +224,7 @@ def save_config(
         os.path.join(os.path.dirname(os.path.abspath(__file__)), c.CONFIG_FILE), "w"
     ) as f:
         json.dump(output_dict, f, indent=4)
+        f.write("\n")
 
 
 def load_recording_list(filename: str) -> list[Recording]:
@@ -258,3 +260,20 @@ def save_recording_list(filename: str, recordings: list[Recording]) -> None:
     }
     with open(filename, "w") as f:
         json.dump(recording_dict, f, indent=4)
+
+
+def get_version() -> str:
+    """Get AccuSleePy package version
+
+    :return: AccuSleePy package version
+    """
+    version = ""
+    toml_file = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+        "pyproject.toml",
+    )
+    if os.path.isfile(toml_file):
+        toml_data = toml.load(toml_file)
+        if "project" in toml_data and "version" in toml_data["project"]:
+            version = toml_data["project"]["version"]
+    return version

accusleepy/gui/dialogs.py

@@ -0,0 +1,40 @@
+"""File dialog helpers"""
+
+import os
+
+from PySide6.QtWidgets import QFileDialog, QWidget
+
+
+def select_existing_file(parent: QWidget, title: str, file_filter: str) -> str | None:
+    """Show dialog to select an existing file.
+
+    :param parent: parent widget
+    :param title: dialog window title
+    :param file_filter: file type filter (e.g., "*.csv")
+    :return: normalized path or None if cancelled
+    """
+    dialog = QFileDialog(parent)
+    dialog.setWindowTitle(title)
+    dialog.setFileMode(QFileDialog.FileMode.ExistingFile)
+    dialog.setViewMode(QFileDialog.ViewMode.Detail)
+    dialog.setNameFilter(file_filter)
+
+    if dialog.exec():
+        return os.path.normpath(dialog.selectedFiles()[0])
+    return None
+
+
+def select_save_location(parent: QWidget, caption: str, file_filter: str) -> str | None:
+    """Show dialog to choose save location.
+
+    :param parent: parent widget
+    :param caption: dialog window caption
+    :param file_filter: file type filter (e.g., "*.csv")
+    :return: normalized path or None if cancelled
+    """
+    filename, _ = QFileDialog.getSaveFileName(
+        parent, caption=caption, filter=file_filter
+    )
+    if filename:
+        return os.path.normpath(filename)
+    return None