Dev/prvep experiment with docs

.gitattributes

@@ -0,0 +1,19 @@
+# Force LF line endings for WSL and cross-platform (Linux/Mac/GitHub Actions) compatibility
+# This prevents obscure bugs when running Windows-edited scripts on Linux runners.
+* text=auto eol=lf
+
+*.py        text eol=lf
+*.rst       text eol=lf
+*.md        text eol=lf
+*.yml       text eol=lf
+*.yaml      text eol=lf
+*.cfg       text eol=lf
+*.toml      text eol=lf
+*.ipynb     text eol=lf
+
+*.png       binary
+*.jpg       binary
+*.jpeg      binary
+*.gif       binary
+*.ico       binary
+*.pdf       binary

.gitignore

@@ -6,6 +6,8 @@ __pycache__
 # Built as part of docs
 doc/auto_examples
 doc/_build
+doc/generated/
+doc/sg_execution_times.rst
 
 # Built by auto_examples
 examples/visual_cueing/*.csv

doc/conf.py

@@ -255,9 +255,9 @@ def setup(app):
 
 # Configurations for sphinx gallery
 
-sphinx_gallery_conf = {'filename_pattern': '(?=.*r__)(?=.*.py)', 
-                       'examples_dirs': ['../examples','../examples/visual_n170', '../examples/visual_p300','../examples/visual_ssvep', '../examples/visual_cueing', '../examples/visual_gonogo'],
-                       'gallery_dirs': ['auto_examples','auto_examples/visual_n170', 'auto_examples/visual_p300','auto_examples/visual_ssvep', 'auto_examples/visual_cueing', 'auto_examples/visual_gonogo'],
+sphinx_gallery_conf = {'filename_pattern': '(?=.*r__)(?=.*.py)',
+                       'examples_dirs': ['../examples/visual_n170', '../examples/visual_p300','../examples/visual_ssvep', '../examples/visual_cueing', '../examples/visual_gonogo'],
+                       'gallery_dirs': ['auto_examples/visual_n170', 'auto_examples/visual_p300','auto_examples/visual_ssvep', 'auto_examples/visual_cueing', 'auto_examples/visual_gonogo'],
                        'within_subsection_order': FileNameSortKey,
                        'default_thumb_file': 'img/eeg-notebooks_logo.png',
                        'backreferences_dir': 'generated',   # Where to drop linking files between examples & API

doc/getting_started/installation.rst

@@ -44,15 +44,15 @@ Use the following commands to download the repo, create and activate a conda or
 
        **Environment file options**
 
-       *Python 3.8 - 3.10:*
+       *Python 3.10:*
 
        - `eeg-expy-full`: Install all dependencies
 
        - `eeg-expy-stimpres`: Stimulus presentation
 
        - `eeg-expy-streamstim`: Combined streaming and stimulus presentation
 
-       *Python 3.8 - 3.13:*
+       *Python 3.10 - 3.13:*
 
        - `eeg-expy-docsbuild`: Documentation
 
@@ -68,7 +68,7 @@ Use the following commands to download the repo, create and activate a conda or
 
           # Create conda environment from chosen eeg-expy-*.yml
           # The Python version will be pinned by the environment file
-          conda env create -n eeg-expy --file=environments/eeg-expy-full.yml
+          conda env create -n eeg-expy -f environments/eeg-expy-full.yml
 
           # Activate the environment
           conda activate eeg-expy

doc/getting_started/loading_and_saving.md

@@ -1,82 +1,82 @@
-# Loading and Saving Data
-Knowing where the data is saved is integral to the functionality of EEG Notebooks. EEG Notebooks saves data to a default location in a hidden directory. From this directory, the individual files can be found based on a folder structure outlined below in the **naming convention.**
-
-## Locating the Default Data Directory
-
-#### Windows 10
-The default directory is found at the location `C:\Users\*USER_NAME*\.eegnb` an example of which is pictured below.
-![fig](../img/windows_default_directory.PNG)
-
-#### Linux
-
-#### MacOS
-
-## Changing the Default Data Directory
-The default directory for saving data is automatically set within the library. If you want to save and analyze data to/from a new directory, it must be passed as a parameter to both the `eegnb.generate_save_fn()` and `eegnb.analysis.load_data()` functions.
-
-**Saving to new directory:**
-``` python
-from eegnb import generate_save_fn
-from eegnb.experiments.visual_n170 import n170
-
-# Define session parameters
-board = 'cyton'
-experiment = 'visual-N170
-subject = 1
-session = 1
-
-# Define new directory and generate save filename
-new_dir = 'C:/Users/Jadin/Documents/EEG_Notebooks_Data'
-save_fn = generate_save_fn(board, experiment, subject, session, new_dir)
-
-# Continue to run experiment as normal...
-```
-
-**Loading from new directory:**
-``` python
-from eegnb.analysis.utils import load_data
-
-# Define parameters for session you want to load
-board = 'cyton'
-experiment = 'visual-N170
-subject = 1
-session = 1
-
-# Define new directory
-new_dir = 'C:/Users/Jadin/Documents/EEG_Notebooks_Data'
-
-# Load data
-raw = load_data(
-            subject_id = subject,
-            session_nb = session,
-            device_name = board,
-            experiment = experiment,
-            data_dir = new_dir
-        ) 
-```
-
-## Naming Convention
-From the specified data directory, EEG notebooks then follows a specific set of naming conventions to define subdirectories and save the data. The full path ends up taking the form
-```
-DATA_DIR\experiment\site\device\subject#\session#\file_name.csv
-```
-Each field is explained below:
-
-**Experiment:** This part is the name of the experiment being run. Example names of experiments as they appear in the example datasets are shown below.
-```
-visual-N170
-visual-P300
-visual-SSVEP
-```
-
-**Site:** The site refers to the recording location, or generally the machine it was recorded to. If you are saving and analyzing only your own data on your local machine, you do not need to specify your site name as it will default to 'local'. When loading example datasets however, it is necessary to specify from which site you would like to load data.
-
-**Device:** The name of the device being recorded from.
-
-**Subject #:** When entering subject ID as a parameter, you only need to specify the integer value. The integer will be formatted to `subjectXXXX` where "XXXX" is a four-digit representation of the integer ID#. 
-
-**Session #:** A session in this case would be the full period of time which you have the device on and are taking multiple recordings. For example: if you put the headset on and take five recordings, all five of these recording would belong to session number 1. Once you take a break from consecutive recordings, then this would constitute a new session. Just like the subject ID, this value is passed as an integer and gets converted to a read-able format.
-
-**File name:** The file name is automatically generated in the format `recording_date_time.csv`
-
+# Loading and Saving Data
+Knowing where the data is saved is integral to the functionality of EEG Notebooks. EEG Notebooks saves data to a default location in a hidden directory. From this directory, the individual files can be found based on a folder structure outlined below in the **naming convention.**
+
+## Locating the Default Data Directory
+
+#### Windows 10
+The default directory is found at the location `C:\Users\*USER_NAME*\.eegnb` an example of which is pictured below.
+![fig](../img/windows_default_directory.PNG)
+
+#### Linux
+
+#### MacOS
+
+## Changing the Default Data Directory
+The default directory for saving data is automatically set within the library. If you want to save and analyze data to/from a new directory, it must be passed as a parameter to both the `eegnb.generate_save_fn()` and `eegnb.analysis.load_data()` functions.
+
+**Saving to new directory:**
+``` python
+from eegnb import generate_save_fn
+from eegnb.experiments.visual_n170 import n170
+
+# Define session parameters
+board = 'cyton'
+experiment = 'visual-N170
+subject = 1
+session = 1
+
+# Define new directory and generate save filename
+new_dir = 'C:/Users/Jadin/Documents/EEG_Notebooks_Data'
+save_fn = generate_save_fn(board, experiment, subject, session, new_dir)
+
+# Continue to run experiment as normal...
+```
+
+**Loading from new directory:**
+``` python
+from eegnb.analysis.utils import load_data
+
+# Define parameters for session you want to load
+board = 'cyton'
+experiment = 'visual-N170
+subject = 1
+session = 1
+
+# Define new directory
+new_dir = 'C:/Users/Jadin/Documents/EEG_Notebooks_Data'
+
+# Load data
+raw = load_data(
+            subject_id = subject,
+            session_nb = session,
+            device_name = board,
+            experiment = experiment,
+            data_dir = new_dir
+        ) 
+```
+
+## Naming Convention
+From the specified data directory, EEG notebooks then follows a specific set of naming conventions to define subdirectories and save the data. The full path ends up taking the form
+```
+DATA_DIR\experiment\site\device\subject#\session#\file_name.csv
+```
+Each field is explained below:
+
+**Experiment:** This part is the name of the experiment being run. Example names of experiments as they appear in the example datasets are shown below.
+```
+visual-N170
+visual-P300
+visual-SSVEP
+```
+
+**Site:** The site refers to the recording location, or generally the machine it was recorded to. If you are saving and analyzing only your own data on your local machine, you do not need to specify your site name as it will default to 'local'. When loading example datasets however, it is necessary to specify from which site you would like to load data.
+
+**Device:** The name of the device being recorded from.
+
+**Subject #:** When entering subject ID as a parameter, you only need to specify the integer value. The integer will be formatted to `subjectXXXX` where "XXXX" is a four-digit representation of the integer ID#. 
+
+**Session #:** A session in this case would be the full period of time which you have the device on and are taking multiple recordings. For example: if you put the headset on and take five recordings, all five of these recording would belong to session number 1. Once you take a break from consecutive recordings, then this would constitute a new session. Just like the subject ID, this value is passed as an integer and gets converted to a read-able format.
+
+**File name:** The file name is automatically generated in the format `recording_date_time.csv`
+
 ### Examples

doc/getting_started/streaming.md

@@ -63,6 +63,9 @@ be run to begin the notebooks interfacing with the bluemuse backend.
 **Needed Parameters:**
 **Optional Parameters:**
 
+**Cyton USB-Serial Latency (Windows):**
+A note on Cyton USB-serial latency: the Windows FTDI driver default `LatencyTimer` of 16 ms causes batched marker delivery and corrupts millisecond-grade marker timing. The experiment scripts assert `LatencyTimer = 1 ms` at startup; recordings predating this assertion contain a ~15 ms hardware buffering lag on the marker channel that must be subtracted before comparing absolute latencies across sessions.
+
 ### OpenBCI Cyton + Daisy
 ![fig](../img/cyton_daisy.png)
 **Device Name:** *'cyton_daisy'*  or *'cyton_daisy_wifi'* with WiFi Shield

doc/index.rst

@@ -19,6 +19,7 @@
    experiments/vn170
    experiments/vp300
    experiments/vssvep
+   experiments/vprvep
    experiments/cueing
    experiments/gonogo
    experiments/all_examples

eegnb/__init__.py

@@ -32,7 +32,7 @@ def _get_recording_dir(
     """A subroutine of get_recording_dir that accepts subject and session as strings"""
     # folder structure is /DATA_DIR/experiment/board_name/site/subject/session/*.csv
     recording_dir = (
-        Path(data_dir) / experiment / site / board_name / subject_str / session_str
+        Path(data_dir or DATA_DIR) / experiment / site / board_name / subject_str / session_str
     )
 
     # check if directory exists, if not, make the directory

eegnb/analysis/__init__.py

@@ -0,0 +1 @@
+from eegnb.analysis import vep_utils  # noqa: F401