accusleepy 0.1.0__py3-none-any.whl

accusleepy/gui/text/config_guide.txt

@@ -0,0 +1,24 @@
+This is the current brain state configuration.
+
+Each brain state has several attributes:
+
+- Digit: how the brain state is represented in label files,
+    and the key on the keyboard that, during manual scoring,
+    sets an epoch to this brain state.
+
+- Enabled: whether a brain state for this digit exists.
+
+- Name: unique name of the brain state (e.g., REM).
+
+- Scored: whether a classification model should output this
+    brain state. If you have a state that corresponds to
+    missing or corrupted data, for example, you would
+    probably want to uncheck this box.
+
+- Frequency: approximate relative frequency of this brain
+    state. Does not need to be very accurate, but it can
+    influence classification accuracy slightly. The values
+    for all scored brain states must sum to 1.
+
+Note that changing these settings can invalidate existing
+label files, calibration files, and trained models!

accusleepy/gui/text/main_guide.txt

@@ -0,0 +1,142 @@
+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 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)
+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
+5. Score all recordings automatically using the classifier
+
+By default, there are three brain state options: REM, wake, and NREM.
+If you want to change this configuration, click the "Settings" tab.
+Note that if you change the configuration, you might be unable to load
+existing labels and calibration data, and you may need to train a new
+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.
+
+-----------------------------------------------------------------------
+Section 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 .csv or .parquet file containing one column of EEG
+    data and one column of EMG data. The column names must match the
+    ones listed in constants.py (EEG_COL, EMG_COL).
+Label file: a .csv file with one column whose title matches
+    BRAIN_STATE_COL in config.py, with entries that are either the
+    undefined brain state (UNDEFINED_LABEL) or one of the valid
+    "digit" attributes of your brain states. By default, these are 1-3
+    and REM = 1, wake = 2, NREM = 3.
+Calibration data file: required for automatic labeling. See Section 4
+    for details.
+Trained classification model: required for automatic labeling. See
+    Section 4 for details.
+
+-----------------------------------------------------------------------
+Section 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
+    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
+    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
+-----------------------------------------------------------------------
+Automatic brain state scoring requires the inputs described in
+Section 3, as well as calibration data files and a trained classifier.
+If you already have all of these files, proceed to Section 4C.
+
+--- Section 4A: Creating calibration data files ---
+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.
+2. The label file must contain at least some labels for each sleep
+    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'.
+4. Enter a filename for the calibration data file.
+5. The calibration file will automatically be assigned to the currently
+    selected recording.
+
+--- Section 4B: Training your own classification model ---
+Pre-trained classification models are provided with AccuSleePy for
+epoch lengths of 2.5, 4, 5, and 10 seconds. These models are the
+"default" type, in that 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.
+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.
+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"
+    type models, this must be an odd number. In general, about 30
+    seconds worth of data is enough.
+4. Choose whether the images used to train the model should be
+    deleted once training is complete.
+5. Select a directory where the training images will be saved. A
+    new directory with an automatically generated name will be
+    created inside the directory you choose.
+6. Click the "Train classification model" button and enter a
+    filename for the trained model. Training can take some time.
+
+--- 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
+    model. The epoch length used when training this network should be
+    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'.
+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.

accusleepy/gui/text/manual_scoring_guide.txt

@@ -0,0 +1,28 @@
+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