.. _module_slowwaveclassifier:

Slow Wave Classifier
====================

**Module name:** ``SlowWaveClassifier``

**Package:** CEAMSModules 7.4.0

**Version:** 2.0.0

Overview
--------

This plugin classifies slow wave events based on a gaussian mixture. 

.. note:: It selects the best gaussian fit based on Akaike information criterion (AIC) and passes those informations to a KMean function which then seperates each detected slow wave into n categories, where n is determined by the best gaussian fit. Values of n range between 1 and 4. Categorized slow waves are then saved in cache along with data for each slow wave criterion.

Inputs
------

.. list-table::
   :widths: 25 20 15 50
   :header-rows: 1
   :align: left
   :class: left-align-caption wrap-table

   * - Input
     - Format
     - Default
     - Description
   * - ``sw_char_files``
     - list of strings
     - []
     - | List of filename to load events_details.
       | events_details are pandas DataFrames (columns=['group', 'name', 'cycle', 'stage',
       | 'start_sec', 'duration_sec', 'pkpk_amp_uV', 'freq_Hz', 'neg_amp_uV', 'neg_sec', 'pos_sec',\|
       | 'slope_0_min', 'slope_min_max', 'slope_max_0', 'trans_freq_Hz', 'channels'])
   * - ``sw_cohort_file``
     - string
     - —
     - File containing the slow wave cohort information generated by the slow wave detector.
   * - ``sw_stages_files``
     - list of strings
     - —
     - List of filename to load sleep stages.
   * - ``automatic_classification``
     - boolean
     - 1
     - | The user specifies whether they want to specify the number of categories or not.
       | Usually selected (True) for a group classification. Unselect (False)
       | when the user inputs an individual of the same group in a second round
       | of classification to have more details.
   * - ``num_categories``
     - int
     - 2
     - The number of categories of sleep slow waves to analyse.
   * - ``num_divisions``
     - int
     - 2
     - The number of divisions in the recording length to divide the night into.
   * - ``report_constants``
     - dict
     - {'N_HOURS': 9, 'N_CYCLES': 6}
     - Constants used in the report (N_HOURS, N_CYCLES)
   * - ``output_dir``
     - string
     - —
     - The directory where the results are saved.

Outputs
-------

.. list-table::
   :widths: 25 20 65
   :header-rows: 1
   :align: left
   :class: left-align-caption wrap-table

   * - Output
     - Format
     - Description
   * - ``categorized_data``
     - pandas DataFrame
     - | DataFrame events (columns=['category','n_t','PaP','Neg', 'tNe', 'tPo', 'Pap_raw', 'Neg_raw', 'mfr', 'trans_freq_Hz'])
       | containing data analysis of parameters for each slow wave category found
   * - ``data_details``
     - Pandas DataFrame
     - | DataFrame containing a column for each category of sleep slow waves
       | found. The indexes describe what the data is about.
   * - ``distr_time``
     - Pandas DataFrame
     - | DataFrame events showing the number of ssw in each category accros each
       | the entire night.
   * - ``distr_cycle``
     - Pandas DataFrame
     - DataFrame events showing the mean value for each quarter of the night
   * - ``distr_quarter``
     - Pandas DataFrame
     - | DataFrame events showing the number of ssw in each category accros each
       | cycle.

Usage in a process
------------------

1. Open **Dev Tools -> New process** in Snooz.
2. In the Module Library, find **Slow Wave Classifier** under the **Statistics** category.
3. Drag the module onto the process canvas.
4. Connect the required inputs from upstream modules (or set values in the **Settings** tab).
5. Connect outputs to downstream modules as needed.
6. Double-click the module to configure parameters in the **Settings** tab.
7. Run the process and inspect results in the **Results** tab.

.. note::

   For general guidance on building processes with modules, see :doc:`/dev_guide/explore_ex`.