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

accusleepy/bouts.py

@@ -11,7 +11,7 @@ class Bout:
 
     length: int  # length, in number of epochs
     start_index: int  # index where bout starts
-    end_index: int  # index where bout ends
+    end_index: int  # index where bout ends (non-inclusive)
     surrounding_state: int  # brain state on both sides of the bout
 
 
@@ -41,9 +41,47 @@ def find_last_adjacent_bout(sorted_bouts: list[Bout], bout_index: int) -> int:
         return bout_index
 
 
+def find_short_bouts(
+    labels: np.ndarray, min_epochs: int, brain_states: set[int]
+) -> list[Bout]:
+    """Locate all brain state bouts below a minimum length
+
+    :param labels: brain state labels (digits in the 0-9 range)
+    :param min_epochs: minimum number of epochs in a bout
+    :param brain_states: set of brain states in the labels
+    :return: list of Bout objects
+    """
+    # 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]
+
+            for span in spans:
+                bouts.append(
+                    Bout(
+                        length=span[1] - span[0],
+                        start_index=span[0],
+                        end_index=span[1],
+                        surrounding_state=other_state,
+                    )
+                )
+    return 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
@@ -61,11 +99,9 @@ def enforce_min_bout_length(
     :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:
+    # if the recording is very short or the minimum bout length
+    # is one epoch long, don't change anything
+    if labels.size < 3 or epoch_length == min_bout_length:
         return labels
 
     # get minimum number of epochs in a bout
@@ -73,36 +109,8 @@ def enforce_min_bout_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,
-                        )
-                    )
-
+    while True:
+        bouts = find_short_bouts(labels, min_epochs, brain_states)
         if len(bouts) == 0:
             break
 

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
@@ -29,6 +30,21 @@ class Hyperparameters:
     training_epochs: int
 
 
+@dataclass
+class AccuSleePyConfig:
+    """AccuSleePy configuration settings"""
+
+    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
+    epochs_to_show: int
+    autoscroll_state: bool
+
+
 @dataclass
 class Recording:
     """Store information about a recording"""
@@ -41,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
@@ -65,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
@@ -81,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
@@ -95,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
 
@@ -111,20 +127,11 @@ def save_labels(
         pd.DataFrame({c.BRAIN_STATE_COL: labels}).to_csv(filename, index=False)
 
 
-def load_config() -> tuple[
-    BrainStateSet,
-    int | float,
-    bool,
-    bool,
-    int | float,
-    EMGFilter,
-    Hyperparameters,
-    int,
-    bool,
-]:
+def load_config() -> AccuSleePyConfig:
     """Load configuration file with brain state options
 
-    :return: set of brain state options,
+    :return: AccuSleePyConfig containing the following:
+        set of brain state options,
         default epoch length,
         default overwrite setting,
         default confidence score output setting,
@@ -139,15 +146,21 @@ def load_config() -> tuple[
     ) as f:
         data = json.load(f)
 
-    return (
-        BrainStateSet(
+    return AccuSleePyConfig(
+        brain_state_set=BrainStateSet(
             [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(
+        default_epoch_length=data[c.DEFAULT_EPOCH_LENGTH_KEY],
+        overwrite_setting=data.get(
+            c.DEFAULT_OVERWRITE_KEY, c.DEFAULT_OVERWRITE_SETTING
+        ),
+        save_confidence_setting=data.get(
+            c.DEFAULT_CONFIDENCE_SETTING_KEY, c.DEFAULT_CONFIDENCE_SETTING
+        ),
+        min_bout_length=data.get(
+            c.DEFAULT_MIN_BOUT_LENGTH_KEY, c.DEFAULT_MIN_BOUT_LENGTH
+        ),
+        emg_filter=EMGFilter(
             **data.get(
                 c.EMG_FILTER_KEY,
                 {
@@ -157,7 +170,7 @@ def load_config() -> tuple[
                 },
             )
         ),
-        Hyperparameters(
+        hyperparameters=Hyperparameters(
             **data.get(
                 c.HYPERPARAMETERS_KEY,
                 {
@@ -168,8 +181,8 @@ def load_config() -> tuple[
                 },
             )
         ),
-        data.get(c.EPOCHS_TO_SHOW_KEY, c.DEFAULT_EPOCHS_TO_SHOW),
-        data.get(c.AUTOSCROLL_KEY, c.DEFAULT_AUTOSCROLL_STATE),
+        epochs_to_show=data.get(c.EPOCHS_TO_SHOW_KEY, c.DEFAULT_EPOCHS_TO_SHOW),
+        autoscroll_state=data.get(c.AUTOSCROLL_KEY, c.DEFAULT_AUTOSCROLL_STATE),
     )
 
 
@@ -211,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]:
@@ -246,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