Merge branch '2.0.0rc4' into aaai_submission_tbd_later

.coveragerc

@@ -2,12 +2,15 @@
 [run]
 omit =
         *__init__*
+        *__main__*
         */usr/local/lib*
         *tests*
         *test*
         *demo*
         *exceptions.py
-        */gui/*
+        */gui/experiments/*
+        */gui/viewer/*
+        */gui/BCInterface.py
 
 [report]
 exclude_lines =

.github/workflows/main.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.8, 3.9]
+        python-version: [3.8, 3.9, 3.10.6]
 
     steps:
     - uses: actions/checkout@v2
@@ -68,7 +68,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.8, 3.9]
+        python-version: [3.8, 3.9, 3.10.6]
 
     steps:
     - uses: actions/checkout@v2
@@ -103,7 +103,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.8, 3.9]
+        python-version: [3.8, 3.9, 3.10.6]
 
     steps:
     - uses: actions/checkout@v4

CHANGELOG.md

@@ -112,7 +112,6 @@ Our final release candidate before the official 2.0 release!
     - added KenLM model `kenlm.py` #268
     - added mixture model `mixture.py` and script to tune weights `mixture_tuning.py` #268
     - added script to evaluate language model performance `lm_eval.py` #268
-    - added Oracle model #316
 - Signal Model
     - added `RdaKdeModel` and restructured to pull out common elements from the PcaRdaKdeModel #279
 - Bug Fixes

Makefile

@@ -3,7 +3,7 @@ install:
 
 dev-install:
 	pip install -r dev_requirements.txt
-	pip install psychopy==2023.2.1 --no-deps
+	pip install psychopy==2024.2.1 --no-deps
 	pip install kenlm==0.1 --global-option="--max_order=12"
 	make install
 

README.md

@@ -40,7 +40,8 @@ If using zsh, instead of bash, you may encounter a segementation fault when runn
 ## Installation
 ---------------
 
-#### BciPy Setup
+### BciPy Setup
+----------------
 
 In order to run BciPy on your computer, after following the dependencies above, you will need to install the BciPy package.
 
@@ -62,26 +63,86 @@ Alternately, if [Make](http://www.mingw.org/) is installed, you may run the foll
 make dev-install
 ```
 
-#### Client Usage
-   	Invoke an experiment protocol or task directly using command line utility `bcipy`.
-		- You can pass it attributes with flags, if desired.
-				Running with a User ID and Task: `bcipy --user "bci_user" --task "RSVP Calibration"`
-				Running with a User ID and Tasks with a registered Protocol: `bcipy --user "bci_user" --experiment "default"`
-				Running with fake data: `bcipy --fake`
-				Running without visualizations: `bcipy --noviz`
-				Running with alerts after each Task execution: `bcipy --alert`
-				Running with custom parameters: `bcipy --parameters "path/to/valid/parameters.json"`
+### Client Usage
+----------------
+
+##### Run an experiment protocol or task
+
+Invoke an experiment protocol or task directly using command line utility `bcipy`.
+
+- Use the help flag to see other available input options: `bcipy --help`
+	- You can pass it attributes with flags, if desired.
+		- Running with a User ID and Task: 
+    		- `bcipy --user "bci_user" --task "RSVP Calibration"`
+		- Running with a User ID and Tasks with a registered Protocol: 
+    		- `bcipy --user "bci_user" --experiment "default"`
+		- Running with fake data: 
+    		- `bcipy --fake`
+		- Running without visualizations: 
+    		- `bcipy --noviz`
+		- Running with alerts after each Task execution: 
+    		- `bcipy --alert`
+		- Running with custom parameters: 
+    		- `bcipy --parameters "path/to/valid/parameters.json"`
+
+##### Train a signal model with registered BciPy models
+
+To train a signal model (currently `PCARDAKDE`), run the following command after installing BciPy:
+
+`bcipy-train`
+
+- Use the help flag to see other available input options: `bcipy-train --help`
+	- You can pass it attributes with flags, if desired.
+		- Running without a window prompting for data session folder: 
+			- `bcipy-train -d path/to/data`
+		- Running with data visualizations (ERPs, etc.): 
+			- `bcipy-train -v`
+    	- Running with data visualizations that do not show, but save to file: 
+			- `bcipy-train -s`
+       - Running with balanced accuracy:
+           - `bcipy-train --balanced-acc`
+		- Running with alerts after each Task execution: 
+			- `bcipy-train --alert`
+		- Running with custom parameters: 
+			- `bcipy-train -p "path/to/valid/parameters.json"`
+
+##### Visualize ERP data from a session with Target / Non-Target labels
+
+To generate plots that can be shown or saved after collection of data, run the following command after installing BciPy:
+
+`bcipy-erp-viz`
+
+- Use the help flag to see other available input options: `bcipy-erp-viz --help`
+	- You can pass it attributes with flags, if desired.
+		- Running without a window prompting for data session folder: 
+			- `bcipy-erp-viz -s path/to/data`
+		- Running with data visualizations (ERPs, etc.): 
+			- `bcipy-erp-viz --show`
+		- Running with data visualizations that do not show, but save to file: 
+			- `bcipy-erp-viz --save`
+		- Running with custom parameters (default is in bcipy/parameters/parameters.json): 
+			- `bcipy-erp-viz -p "path/to/valid/parameters.json"`
+
+##### BciPy Simulator Usage
+
+The simulator can be run using the command line utility `bcipy-sim`.
+
+Ex. 
+`bcipy-sim -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5`
+
+Run `bcipy-sim --help` for documentation or see the README in the simulator module.
 
-		- Use the help flag to see other available input options: `bcipy --help`
 
-#####  Example Usage as a Package
+###  Package Usage
+-------------------
 
 ```python
 from bcipy.helpers import system_utils
 system_utils.get_system_info()
 ```
 
-#### Example Usage through the GUI
+### GUI Usage
+-------------
 
 Run the following command in your terminal to start the BciPy GUI:
 ```sh
@@ -95,16 +156,6 @@ make bci-gui
 ```
 
 
-#### Simulator Usage
-
-The simulator can be run using the command line utility `bcipy-sim`.
-
-Ex. 
-`bcipy-sim -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5`
-
-Run `bcipy-sim --help` for documentation or see the README in the simulator module.
-
-
 ## Glossary
 -----------
 
@@ -150,7 +201,7 @@ This a list of the major modules and their functionality. Each module will conta
 ## Paradigms
 ------------
 
-See `bcipy/task/README.md` for more information on all supported paradigms and modes. The following are the supported and validated paradigms:
+See `bcipy/task/README.md` for more information on all supported paradigms, tasks, actions and modes. The following are the supported and validated paradigms:
 
 
 > RSVPKeyboard
@@ -213,7 +264,6 @@ After running the above command, the recommended offset correction value will be
 ```bash
 # Let's say the recommneded offset value is 0.1
 python bcipy/helpers/offset.py --offset "0.1" -p
-
 ```
 
 Alternately, if Make is installed, you may run the follow command to run offset determination and display the results:
@@ -306,10 +356,11 @@ make type
 
 
 ### Contributions Welcome!
+--------------------------
 
 If you want to be added to the development team slack or have additional questions, please reach out to us at [email protected]!
 
-### Contribution Guidelines
+#### Contribution Guidelines
 
 We follow and will enforce the contributor's covenant to foster a safe and inclusive environment for this open source software, please reference this link for more information: https://www.contributor-covenant.org/
 
@@ -325,7 +376,7 @@ Other guidelines:
 
 See this resource for examples: http://docs.python-guide.org/en/latest/writing/style/
 
-## Contributors
+### Contributors
 ---------------
 
 All contributions are greatly appreciated!

bcipy/config.py

@@ -27,9 +27,9 @@
 DEFAULT_USER_ID = 'test_user'
 TASK_SEPERATOR = '->'
 
-DEFAULT_PARAMETER_FILENAME = 'parameters.json'
+DEFAULT_PARAMETERS_FILENAME = 'parameters.json'
 DEFAULT_DEVICES_PATH = f"{BCIPY_ROOT}/parameters"
-DEFAULT_PARAMETERS_PATH = f'{BCIPY_ROOT}/parameters/{DEFAULT_PARAMETER_FILENAME}'
+DEFAULT_PARAMETERS_PATH = f'{BCIPY_ROOT}/parameters/{DEFAULT_PARAMETERS_FILENAME}'
 DEFAULT_DEVICE_SPEC_FILENAME = 'devices.json'
 DEVICE_SPEC_PATH = f'{BCIPY_ROOT}/parameters/{DEFAULT_DEVICE_SPEC_FILENAME}'
 DEFAULT_LM_PARAMETERS_FILENAME = 'lm_params.json'

bcipy/display/__init__.py

@@ -8,7 +8,6 @@
     Display,
     InformationProperties,
     init_display_window,
-    PreviewInquiryProperties,
     StimuliProperties,
     VEPStimuliProperties
 )
@@ -20,5 +19,4 @@
     'StimuliProperties',
     'VEPStimuliProperties',
     'InformationProperties',
-    'PreviewInquiryProperties'
 ]

bcipy/display/main.py

@@ -251,37 +251,6 @@ class ButtonPressMode(Enum):
     REJECT = 2
 
 
-class PreviewInquiryProperties:
-    """"Preview Inquiry Properties.
-    An encapsulation of properties relevant to preview_inquiry() operation.
-    """
-
-    def __init__(
-            self,
-            preview_on: bool,
-            preview_only: bool,
-            preview_inquiry_length: float,
-            preview_inquiry_progress_method: int,
-            preview_inquiry_key_input: str,
-            preview_inquiry_isi: float):
-        """Initialize Inquiry Preview Parameters.
-
-        preview_on(bool): If True, display an inquiry preview before the main inquiry.
-        preview_only(bool): If True, only preview the inquiry and do not probe for response
-        preview_inquiry_length(float): Length of time in seconds to present the inquiry preview
-        preview_inquiry_progress_method(int): Method of progression for inquiry preview.
-            0 == preview only; 1 == press to accept inquiry; 2 == press to skip inquiry.
-        preview_inquiry_key_input(str): Defines which key should be listened to for progressing
-        preview_inquiry_isi(float): Length of time after displaying the inquiry preview to display a blank screen
-        """
-        self.preview_on = preview_on
-        self.preview_inquiry_length = preview_inquiry_length
-        self.preview_inquiry_key_input = preview_inquiry_key_input
-        self.press_to_accept = True if preview_inquiry_progress_method == 1 else False
-        self.preview_only = preview_only
-        self.preview_inquiry_isi = preview_inquiry_isi
-
-
 class PreviewParams(NamedTuple):
     """Parameters relevant for the Inquiry Preview functionality.
 
@@ -293,6 +262,7 @@ class PreviewParams(NamedTuple):
     preview_inquiry_key_input: str
     preview_inquiry_progress_method: int
     preview_inquiry_isi: float
+    preview_box_text_size: float
 
     @property
     def button_press_mode(self):

bcipy/display/paradigm/rsvp/display.py

@@ -73,6 +73,8 @@ def __init__(
         self.stimuli_colors = stimuli.stim_colors
         self.stimuli_timing = stimuli.stim_timing
         self.stimuli_font = stimuli.stim_font
+        # Note: there is a bug in TextBox2 that prevents certain custom fonts from being used. This is to avoid that.
+        self.textbox_font = 'Consolas'
         self.stimuli_height = stimuli.stim_height
         self.stimuli_pos = stimuli.stim_pos
         self.is_txt_stim = stimuli.is_txt_stim
@@ -271,13 +273,12 @@ def _generate_inquiry_preview(self) -> visual.TextBox2:
         text = ' '.join(self.stimuli_inquiry).split('+ ')[1]
 
         return self._create_stimulus(
-            0.12,
+            self.preview_params.preview_box_text_size,
             stimulus=text,
             units='height',
             stimuli_position=self.stimuli_pos,
             mode='textbox',
-            align_text='left',
-            wrap_width=0.025)
+            align_text='left')
 
     def _generate_inquiry(self) -> list:
         """Generate inquiry.
@@ -439,9 +440,11 @@ def _create_stimulus(
                 borderWidth=2,
                 borderColor='white',
                 units=units,
-                font=self.stimuli_font,
+                padding=0.05,
+                font=self.textbox_font,
                 letterHeight=height,
-                size=[.5, .5],
+                size=[.55, .55],
                 pos=stimuli_position,
                 alignment=align_text,
+                editable=False,
             )

bcipy/display/tests/components/test_button_press_handler.py

@@ -189,3 +189,7 @@ def test_press_to_reject_with_keypress(self, get_key_press_mock):
         self.assertTrue(handler.has_response())
         self.assertEqual('bcipy_key_press_space', handler.response_label)
         self.assertEqual(1.5, handler.response_timestamp)
+
+
+if __name__ == '__main__':
+    unittest.main()

bcipy/display/tests/paradigm/matrix/test_matrix_display.py

@@ -143,7 +143,8 @@ def test_do_inquiry_with_preview_accepted(self):
                                        preview_inquiry_length=2,
                                        preview_inquiry_key_input='return',
                                        preview_inquiry_progress_method=2,
-                                       preview_inquiry_isi=1)
+                                       preview_inquiry_isi=1,
+                                       preview_box_text_size=0.1)
         matrix = MatrixDisplay(window=self.window,
                                experiment_clock=self.experiment_clock,
                                stimuli=self.stimuli,
@@ -181,7 +182,8 @@ def test_do_inquiry_with_preview_rejected(self):
                                        preview_inquiry_length=2,
                                        preview_inquiry_key_input='return',
                                        preview_inquiry_progress_method=2,
-                                       preview_inquiry_isi=1)
+                                       preview_inquiry_isi=1,
+                                       preview_box_text_size=0.1)
         matrix = MatrixDisplay(window=self.window,
                                experiment_clock=self.experiment_clock,
                                stimuli=self.stimuli,