Matrix documentation

CHANGELOG.md

@@ -13,6 +13,7 @@
 - New file export features for BciPy data, including .bdf format and prefiltering #246
 - New Supported Devices: Tobii-Nano #234
 - Bug fixes #218, #225, #228, #235, #240, #246
+- Documentation for Matrix Speller and AUC calculation #253
 
 ### Added
 

README.md

@@ -122,7 +122,7 @@ Orhan, U., Hild, K. E., 2nd, Erdogmus, D., Roark, B., Oken, B., & Fried-Oken, M.
 > Matrix Speller
 
 ```
-Matrix Speller is an EEG (electroencephalography) based BCI (brain computer interface) typing system. It utilizes a visual presentation technique called Single Character Presentation (SCP).
+Matrix Speller is an EEG (electroencephalography) based BCI (brain computer interface) typing system. It utilizes a visual presentation technique called Single Character Presentation (SCP). In matrix speller, the symbols are arranged in a matrix with fixed number of rows and columns. Using SCP, subsets of these symbols are intensified (i.e. highlighted) usually in pseudorandom order to produce an odd ball paradigm to induce p300 responses. 
 ```
 
 Citation:

bcipy/display/paradigm/matrix/display.py

@@ -16,33 +16,6 @@ class MatrixDisplay(Display):
     """Matrix Display Object for Inquiry Presentation.
 
     Animates display objects in matrix grid common to any Matrix task.
-
-
-    PARAMETERS:
-    ----------
-    # Experiment
-    window(visual.Window): PsychoPy Window
-    static_clock(core.Clock): Used to schedule static periods of display time
-    experiment_clock(core.Clock): Clock used to timestamp display onsets
-
-    # Stimuli
-    stimuli(StimuliProperties): attributes used for inquiries
-
-    # Task
-    task_display(TaskDisplayProperties): attributes used for task tracking. Ex. 1/100
-
-    # Info
-    info(InformationProperties): attributes to display informational stimuli alongside task and inquiry stimuli.
-
-    marker_writer(MarkerWriter) Optional: object used to write triggers to
-        a acquisition stream.
-    trigger_type(str) default 'image': defines the calibration trigger type for the display at the beginning of any
-        task. This will be used to reconcile timing differences between acquisition and the display.
-    space_char(str) default SPACE_CHAR: defines the space character to use in the RSVP inquiry.
-    full_screen(bool) default False: Whether or not the window is set to a full screen dimension. Used for
-        scaling display items as needed.
-    symbol_set default = none : set of stimuli to be flashed during an inquiry
-
     """
 
     def __init__(
@@ -58,15 +31,40 @@ def __init__(
             space_char: str = SPACE_CHAR,
             full_screen: bool = False,
             symbol_set: Optional[List[str]] = None):
+        """Initialize Matrix display parameters and objects.
 
+        PARAMETERS:
+        ----------
+        # Experiment
+        window(visual.Window): PsychoPy Window
+        static_clock(core.Clock): Used to schedule static periods of display time
+        experiment_clock(core.Clock): Clock used to timestamp display onsets
+
+        # Stimuli
+        stimuli(StimuliProperties): attributes used for inquiries
+
+        # Task
+        task_display(TaskDisplayProperties): attributes used for task tracking. Ex. 1/100
+
+        # Info
+        info(InformationProperties): attributes to display informational stimuli alongside task and inquiry stimuli.
+
+        marker_writer(MarkerWriter) Optional: object used to write triggers to an acquisition stream.
+        trigger_type(str) default 'image': defines the calibration trigger type for the display at the beginning of any
+            task. This will be used to reconcile timing differences between acquisition and the display.
+        space_char(str) default SPACE_CHAR: defines the space character to use in the Matrix inquiry.
+        full_screen(bool) default False: Whether or not the window is set to a full screen dimension. Used for
+            scaling display items as needed.
+        symbol_set default = none : subset of stimuli to be highlighted during an inquiry
+        """
         self.window = window
         self.window_size = self.window.size  # [w, h]
         self.refresh_rate = window.getActualFrameRate()
 
         self.logger = logging.getLogger(__name__)
 
         # Stimuli parameters, these are set on display in order to allow
-        #  easy updating after defintion
+        # easy updating after definition
         self.stimuli_inquiry = stimuli.stim_inquiry
         self.stimuli_colors = stimuli.stim_colors
         self.stimuli_timing = stimuli.stim_timing

bcipy/signal/model/README.md

@@ -8,13 +8,13 @@ This model involves the following stages:
 
 1. Channelwise-PCA to reduce data dimension while preserving as much variation in the data as possible. See `pca_rda_kde/dimensionality_reduction.py`.
 
-2. Cross-validation to choose optimal regularization parameters for RDA (see the next step).
-
-3. Regularized Discriminant Analysis (RDA), which further reduces dimension to 1D by estimating class probabilities for a positive and negative class (i.e. whether a single letter was desired or not). RDA includes two key parameters, `gamma` and `lambda` which determine how much the estimated class covariances are regularized towards the whole-data covariance matrix and towards the identity matrix. See `pca_rda_kde/classifier.py`.
+2. Regularized Discriminant Analysis (RDA), which further reduces dimension to 1D by estimating class probabilities for a positive and negative class (i.e. whether a single letter was desired or not). RDA includes two key parameters, `gamma` and `lambda` which determine how much the estimated class covariances are regularized towards the whole-data covariance matrix and towards the identity matrix. See `pca_rda_kde/classifier.py`.
 
 4. Kernel Density Estimation (KDE), which performs generative modeling on the reduced dimension data, computing the probability that it arose from the positive class, and from the negative class. This method involves choosing a kernel (a notion of distance) and a bandwidth (a length scale for the kernel). See `pca_rda_kde/density_estimation.py`.
 
-5. The ratio of the likelihood terms computed by kernel density estimation (`p(eeg | +)` and `p(eeg | -)`) is used in the final decision rule. See `pca_rda_kde/pca_rda_kde.py`
+5. AUC/AUROC calculation: PCA/RDA part of the model is trained using k-fold cross-validation, then the AUC is computed using the optimized `gamma` and `lambda` values. See `pca_rda_kde/cross_validation.py`.
+
+6. In order to make a Bayesian update, we need to compute the ratio of the generative likelihood terms for the presented letter (`p(eeg | +)` and `p(eeg | -)`). This ratio is obtained from the final kernel density estimation step and is used in the final decision rule. See `pca_rda_kde/pca_rda_kde.py`.
 
 # Testing
 

bcipy/task/paradigm/matrix/calibration.py

@@ -18,13 +18,13 @@ class MatrixCalibrationTask(Task):
     """Matrix Calibration Task.
 
     Calibration task performs an Matrix stimulus inquiry
-        to elicit an ERP. Parameters will change how many stimuli
-        and for how long they present. Parameters also change
-        color and text / image inputs.
+        to elicit an ERP. Parameters change the number of stimuli
+        (i.e. the subset of matrix) and for how long they will highlight.
+        Parameters also change color and text / image inputs.
 
     A task begins setting up variables --> initializing eeg -->
         awaiting user input to start -->
-        setting up stimuli --> presenting inquiries -->
+        setting up stimuli --> highlighting inquiries -->
         saving data
 
     PARAMETERS: