diff --git a/.bcipy/README.md b/.bcipy/README.md deleted file mode 100644 index e1349f633..000000000 --- a/.bcipy/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# Experiments and Fields - -BciPy experiments and fields allow users to collect metadata that may be integrated alongside core BciPy data. This is particularly useful when the experiment has completed and a researcher wants to curate their files for sharing with the community. - -## Experiments - -An experiment defines the name, summary and fields to collect. At this level, the requirement for collection during every task and whether or not to anonymize later will be set. The anonymization does not encrypt the data at rest, but instead defines how to handle the field later when uploading/sharing. The registered experiments are defined in `.bcipy/experiment/experiments.json` in the following format: - -```js -{ - name: { - fields : { - name: "", - required: bool, - anonymize: bool - }, - summary: "" - } -} -``` - -## Fields - -A field is a unit of data collection for an experiment. It has a name, help text and type. The type will determine how it is collected and validated. The registered fields are defined in `.bcipy/field/fields.json` in the following format: - - -```js -{ - name: { - help_text: "", - type: "FieldType" - } -} -``` - -where FieldType may be str, bool, int, or float. \ No newline at end of file diff --git a/.bcipy/downloads/pyWinhook-1.6.2-cp39-cp39-win_amd64.whl b/.bcipy/downloads/pyWinhook-1.6.2-cp39-cp39-win_amd64.whl deleted file mode 100644 index d46b4ca08..000000000 Binary files a/.bcipy/downloads/pyWinhook-1.6.2-cp39-cp39-win_amd64.whl and /dev/null differ diff --git a/.coveragerc b/.coveragerc deleted file mode 100644 index 3d8cc939e..000000000 --- a/.coveragerc +++ /dev/null @@ -1,25 +0,0 @@ - -[run] -omit = - *__init__* - *__main__* - */usr/local/lib* - *tests* - *test* - *demo* - *exceptions.py - */gui/experiments/* - */gui/viewer/* - */gui/BCInterface.py - */signal/model/offline_analysis.py - */signal/evaluate/fusion.py - -[report] -exclude_lines = - pragma: no cover - def __repr__ - def __str__ - raise NotImplementedError - @abstract - if __name__ == .__main__.: - logging.getLogger(__name__) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ddcd9d3a3..aef8daf55 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -18,7 +18,7 @@ jobs: strategy: fail-fast: false matrix: - python-version: [3.8, 3.9, 3.10.6] + python-version: [3.9, 3.10.6] steps: - uses: actions/checkout@v2 @@ -69,7 +69,7 @@ jobs: strategy: fail-fast: false matrix: - python-version: [3.8, 3.9, 3.10.6] + python-version: [3.9, 3.10.6] steps: - uses: actions/checkout@v2 @@ -80,10 +80,6 @@ jobs: - name: update pip & install custom dependencies run: | python -m pip install --upgrade pip - - name: install manually downloaded pyWinhook wheel for Python 3.9 - if: matrix.python-version == 3.9 - run: | - pip install ./.bcipy/downloads/pyWinhook-1.6.2-cp39-cp39-win_amd64.whl - name: install dependencies run: | make dev-install @@ -97,17 +93,17 @@ jobs: - name: lint run: | make lint - - name: integration-test + - name: build run: | - make integration-test + make build build-macos: - runs-on: macos-latest + runs-on: macos-14 strategy: fail-fast: false matrix: - python-version: [3.8, 3.9, 3.10.6] + python-version: [3.9, 3.10.6] steps: - uses: actions/checkout@v4 @@ -117,9 +113,12 @@ jobs: python-version: ${{ matrix.python-version }} - name: update pip & install custom dependencies run: | + python -m pip install --upgrade pip + brew update sh scripts/shell/m2chip_install.sh brew install labstreaminglayer/tap/lsl - python -m pip install --upgrade pip + pip install psychopy --no-deps + make install - name: install dependencies run: | make dev-install @@ -127,14 +126,17 @@ jobs: if: always() run: | make coverage-report + make coverage-xml - name: type-check run: | make type - name: lint run: | make lint - - name: integration-test + - name: build run: | - make integration-test - - + make build + - name: codacy + run: | + export CODACY_PROJECT_TOKEN=${{ secrets.CODACY_PROJECT_TOKEN }} + bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r "cobertura.xml" diff --git a/.gitignore b/.gitignore index 1fdadd6e1..30c3caabc 100644 --- a/.gitignore +++ b/.gitignore @@ -11,22 +11,22 @@ mypy-html.css index.html htmlcov/ html/ +*.xml # Virtualenv venv/ venv*/ __pycache__/ +.pytest_cache/ .cache/ # BciPy files and directories -*.csv *.pdf buffer.db lmwrap.log env.txt .idea bcipy.egg-info/ -data/ build/ dist/ bcipy/parameters/parameters_* @@ -35,6 +35,9 @@ bcipy/language/lms/lm_dec19_char_large_12gram.* bcipy/language/lms/out_* bcipy/language/out/ - bcipy/simulator/tests/resource/ -!bcipy/simulator/data \ No newline at end of file +# Ignore the data directory, which contains the raw data files, but not the data modules +data/ +bids/ +!bcipy/simulator/data + diff --git a/CHANGELOG.md b/CHANGELOG.md index b2c2f1c38..3d2f47480 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,36 @@ +# 2.0.0 + +The next major BciPy release is here! All features included from release canidates rc1-rc4 and contributions described below. + +## Contributions + +- BIDS + - Bundling support and refactor of `convert` module. See `demo_convert.py` #362 Add support for 1020 channels and eye tracker data #369 +- Library Refactor + - Refactor `helpers` into `io` and `core` #362 +- Refactor to use `pyproject.toml` for installs #367 +- Language Model Refactor to use lm-toolkit #381 #390 +- Gaze Model integration #384 +- Simulator + - Multimodal support #385 + - Replay feature #376 + - Verbose mode configuration #375 and logging fixes #373 + - Inquiry- Ranger Sampler #374 Trial Sampler #372 + - Metrics #371 +- Dependencies + - Upgrade + - `seaborn` #362 + - Add + - `mne-bids` #362 + - `pybv` #362 + - `EDFlib-Python` #362 + - Remove + - `pyedflib` #362 + - Drop support for python 3.8 #391 +- General documentation improvements + - README updates #391 + - Drop Twitter links #391 + # 2.0.1-rc.4 Patch on final release candidate diff --git a/LICENSE.md b/LICENSE.md index 907d40b62..341ee96fe 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,33 +1,11 @@ -BciPy Copyright 2021 (CAMBI)(“Licensor”) +Copyright 2025 (CAMBI)("Licensor") -Hippocratic License Version Number: 2.1. +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: -Purpose. The purpose of this License is for the Licensor named above to permit the Licensee (as defined below) broad permission, if consistent with Human Rights Laws and Human Rights Principles (as each is defined below), to use and work with the Software (as defined below) within the full scope of Licensor’s copyright and patent rights, if any, in the Software, while ensuring attribution and protecting the Licensor from liability. +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -Permission and Conditions. The Licensor grants permission by this license (“License”), free of charge, to the extent of Licensor’s rights under applicable copyright and patent law, to any person or entity (the “Licensee”) obtaining a copy of this software and associated documentation files (the “Software”), to do everything with the Software that would otherwise infringe (i) the Licensor’s copyright in the Software or (ii) any patent claims to the Software that the Licensor can license or becomes able to license, subject to all of the following terms and conditions: +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -* Acceptance. This License is automatically offered to every person and entity subject to its terms and conditions. Licensee accepts this License and agrees to its terms and conditions by taking any action with the Software that, absent this License, would infringe any intellectual property right held by Licensor. +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. -* Notice. Licensee must ensure that everyone who gets a copy of any part of this Software from Licensee, with or without changes, also receives the License and the above copyright notice (and if included by the Licensor, patent, trademark and attribution notice). Licensee must cause any modified versions of the Software to carry prominent notices stating that Licensee changed the Software. For clarity, although Licensee is free to create modifications of the Software and distribute only the modified portion created by Licensee with additional or different terms, the portion of the Software not modified must be distributed pursuant to this License. If anyone notifies Licensee in writing that Licensee has not complied with this Notice section, Licensee can keep this License by taking all practical steps to comply within 30 days after the notice. If Licensee does not do so, Licensee’s License (and all rights licensed hereunder) shall end immediately. - -* Compliance with Human Rights Principles and Human Rights Laws. - - 1. Human Rights Principles. - - (a) Licensee is advised to consult the articles of the United Nations Universal Declaration of Human Rights and the United Nations Global Compact that define recognized principles of international human rights (the “Human Rights Principles”). Licensee shall use the Software in a manner consistent with Human Rights Principles. - - (b) Unless the Licensor and Licensee agree otherwise, any dispute, controversy, or claim arising out of or relating to (i) Section 1(a) regarding Human Rights Principles, including the breach of Section 1(a), termination of this License for breach of the Human Rights Principles, or invalidity of Section 1(a) or (ii) a determination of whether any Law is consistent or in conflict with Human Rights Principles pursuant to Section 2, below, shall be settled by arbitration in accordance with the Hague Rules on Business and Human Rights Arbitration (the “Rules”); provided, however, that Licensee may elect not to participate in such arbitration, in which event this License (and all rights licensed hereunder) shall end immediately. The number of arbitrators shall be one unless the Rules require otherwise. - - Unless both the Licensor and Licensee agree to the contrary: (1) All documents and information concerning the arbitration shall be public and may be disclosed by any party; (2) The repository referred to under Article 43 of the Rules shall make available to the public in a timely manner all documents concerning the arbitration which are communicated to it, including all submissions of the parties, all evidence admitted into the record of the proceedings, all transcripts or other recordings of hearings and all orders, decisions and awards of the arbitral tribunal, subject only to the arbitral tribunal's powers to take such measures as may be necessary to safeguard the integrity of the arbitral process pursuant to Articles 18, 33, 41 and 42 of the Rules; and (3) Article 26(6) of the Rules shall not apply. - - 2. Human Rights Laws. The Software shall not be used by any person or entity for any systems, activities, or other uses that violate any Human Rights Laws. “Human Rights Laws” means any applicable laws, regulations, or rules (collectively, “Laws”) that protect human, civil, labor, privacy, political, environmental, security, economic, due process, or similar rights; provided, however, that such Laws are consistent and not in conflict with Human Rights Principles (a dispute over the consistency or a conflict between Laws and Human Rights Principles shall be determined by arbitration as stated above). Where the Human Rights Laws of more than one jurisdiction are applicable or in conflict with respect to the use of the Software, the Human Rights Laws that are most protective of the individuals or groups harmed shall apply. - - 3. Indemnity. Licensee shall hold harmless and indemnify Licensor (and any other contributor) against all losses, damages, liabilities, deficiencies, claims, actions, judgments, settlements, interest, awards, penalties, fines, costs, or expenses of whatever kind, including Licensor’s reasonable attorneys’ fees, arising out of or relating to Licensee’s use of the Software in violation of Human Rights Laws or Human Rights Principles. - -* Failure to Comply. Any failure of Licensee to act according to the terms and conditions of this License is both a breach of the License and an infringement of the intellectual property rights of the Licensor (subject to exceptions under Laws, e.g., fair use). In the event of a breach or infringement, the terms and conditions of this License may be enforced by Licensor under the Laws of any jurisdiction to which Licensee is subject. Licensee also agrees that the Licensor may enforce the terms and conditions of this License against Licensee through specific performance (or similar remedy under Laws) to the extent permitted by Laws. For clarity, except in the event of a breach of this License, infringement, or as otherwise stated in this License, Licensor may not terminate this License with Licensee. - -* Enforceability and Interpretation. If any term or provision of this License is determined to be invalid, illegal, or unenforceable by a court of competent jurisdiction, then such invalidity, illegality, or unenforceability shall not affect any other term or provision of this License or invalidate or render unenforceable such term or provision in any other jurisdiction; provided, however, subject to a court modification pursuant to the immediately following sentence, if any term or provision of this License pertaining to Human Rights Laws or Human Rights Principles is deemed invalid, illegal, or unenforceable against Licensee by a court of competent jurisdiction, all rights in the Software granted to Licensee shall be deemed null and void as between Licensor and Licensee. Upon a determination that any term or provision is invalid, illegal, or unenforceable, to the extent permitted by Laws, the court may modify this License to affect the original purpose that the Software be used in compliance with Human Rights Principles and Human Rights Laws as closely as possible. The language in this License shall be interpreted as to its fair meaning and not strictly for or against any party. - -* Disclaimer. TO THE FULL EXTENT ALLOWED BY LAW, THIS SOFTWARE COMES “AS IS,” WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED, AND LICENSOR AND ANY OTHER CONTRIBUTOR SHALL NOT BE LIABLE TO ANYONE FOR ANY DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THIS LICENSE, UNDER ANY KIND OF LEGAL CLAIM. - -This Hippocratic License is an Ethical Source license (https://ethicalsource.dev) and is offered for use by licensors and licensees at their own risk, on an “AS IS” basis, and with no warranties express or implied, to the maximum extent permitted by Laws. +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/Makefile b/Makefile index e5a022bc1..f350c89e5 100644 --- a/Makefile +++ b/Makefile @@ -2,19 +2,17 @@ install: pip install -e . dev-install: - pip install -r dev_requirements.txt - pip install kenlm==0.1 --global-option="--max_order=12" + pip install -e ".[dev]" make install build: - make dev-install - python setup.py sdist bdist_wheel + pip install -e ".[release]" + python -m build --sdist --wheel test-all: make coverage-report make type make lint - make integration-test unit-test: pytest --mpl -k "not slow" @@ -23,18 +21,21 @@ integration-test: pytest --mpl -k "slow" coverage-report: - coverage run --branch --source=bcipy -m pytest --mpl -k "not slow" + coverage run --branch -m pytest --mpl -k "not slow" coverage report +coverage-xml: + coverage xml -o "cobertura.xml" + coverage-html: - coverage run --branch --source=bcipy -m pytest --mpl -k "not slow" + coverage run --branch -m pytest --mpl -k "not slow" coverage html lint: flake8 bcipy lint-fix: - autopep8 --in-place --aggressive -r bcipy + autopep8 --in-place --aggressive --max-line-length 120 --ignore "E402,E226,E24,W50,W690" -r bcipy flake8 bcipy type: @@ -47,6 +48,15 @@ clean: find . -name "*.py[co]" -o -name __pycache__ -exec rm -rf {} + find . -path "*/*.pyo" -delete find . -path "*/*.pyc" -delete + find . -path "*/*/__pycache__" -delete + rm -rf .pytest_cache + rm -rf .mypy_cache + rm -rf .coverage + rm -rf htmlcov + rm -rf dist + rm -rf build + rm -rf bcipy.egg-info + rm -rf bcipy_cache bci-gui: python bcipy/gui/BCInterface.py diff --git a/README.md b/README.md index 9f7a048ec..f100d5b45 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,95 @@ # BciPy: Brain-Computer Interface Software in Python [![BciPy](https://github.com/CAMBI-tech/BciPy/actions/workflows/main.yml/badge.svg)](https://github.com/CAMBI-tech/BciPy/actions/workflows/main.yml) +[![Codacy Badge](https://app.codacy.com/project/badge/Grade/96e31da4b0554dae9db7a1356556b0d5)](https://app.codacy.com/gh/CAMBI-tech/BciPy/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://github.com/CAMBI-tech/BciPy/fork) -[![Follow on Twitter](https://img.shields.io/twitter/follow/cambi_tech?label=Follow&style=social)](https://twitter.com/cambi_tech) +[![BSD-3-Clause License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) -BciPy is a library for conducting Brain-Computer Interface experiments in Python. It functions as a standalone application for experimental data collection or you can take the tools you need and start coding your own system. See our official BciPy documentation including affiliations and more context information [here](https://bcipy.github.io/). +[![CAMBI_logo](./bcipy/static/images/gui/CAMBI_full_logo.png)](https://cambi.tech) -It will run on the latest windows (7, 10, 11), linux (ubuntu 22.04) and macos (Big Sur). Other versions may work as well, but are not guaranteed. To see supported versions and operating systems as of this release see here: [BciPy Builds](https://github.com/CAMBI-tech/BciPy/actions/workflows/main.yml). +BciPy is a library for conducting Brain-Computer Interface experiments in Python. It is designed to be modular and extensible, allowing researchers to easily add new paradigms, models, and processing methods. The focus of BciPy is on paradigms for communication and control, including Rapid Serial Visual Presentation (RSVP) and Matrix Speller. See our official documentation including affiliations and more context information [here](https://bcipy.github.io/). -*Please cite us when using!* +BciPy is released open-source under the BSD-3 clause. Please refer to [LICENSE.md](LICENSE.md). + +**If you use BciPy in your research, please cite the following manuscript:** ```text Memmott, T., Koçanaoğulları, A., Lawhead, M., Klee, D., Dudy, S., Fried-Oken, M., & Oken, B. (2021). BciPy: brain–computer interface software in Python. Brain-Computer Interfaces, 1-18. ``` +## Table of Contents + +- [BciPy: Brain-Computer Interface Software in Python](#bcipy-brain-computer-interface-software-in-python) + - [Table of Contents](#table-of-contents) + - [Dependencies](#dependencies) + - [Linux](#linux) + - [Windows](#windows) + - [Mac](#mac) + - [Installation](#installation) + - [BciPy Setup](#bcipy-setup) + - [Editable Install and GUI usage](#editable-install-and-gui-usage) + - [PyPi Install](#pypi-install) + - [Make install](#make-install) + - [Usage](#usage) + - [Package Usage](#package-usage) + - [GUI Usage](#gui-usage) + - [Client Usage](#client-usage) + - [General Usage](#general-usage) + - [Running Experiments or Tasks via Command Line](#running-experiments-or-tasks-via-command-line) + - [Options](#options) + - [Train a Signal Model via Command Line](#train-a-signal-model-via-command-line) + - [Basic Commands Signal Model Training](#basic-commands-signal-model-training) + - [Visualize ERP data from a session with Target / Non-Target labels via Command Line](#visualize-erp-data-from-a-session-with-target--non-target-labels-via-command-line) + - [Basic Commands ERP Viz](#basic-commands-erp-viz) + - [BciPy Simulator](#bcipy-simulator) + - [Running the Simulator](#running-the-simulator) + - [Basic Commands Simulator](#basic-commands-simulator) + - [Other Options](#other-options) + - [Core Modules](#core-modules) + - [Top-Level Modules Overview](#top-level-modules-overview) + - [`Acquisition`](#acquisition) + - [`Core`](#core) + - [`Display`](#display) + - [`Feedback`](#feedback) + - [`GUI`](#gui) + - [`Helpers`](#helpers) + - [`IO`](#io) + - [`Language`](#language) + - [`Signal`](#signal) + - [`Simulator`](#simulator) + - [`Task`](#task) + - [Entry Point and Configuration Modules](#entry-point-and-configuration-modules) + - [`main.py`](#mainpy) + - [`parameters/`](#parameters) + - [`config.py`](#configpy) + - [`static/`](#static) + - [Paradigms](#paradigms) + - [RSVPKeyboard](#rsvpkeyboard) + - [Matrix Speller](#matrix-speller) + - [Offset Determination and Correction](#offset-determination-and-correction) + - [What is a Static Offset?](#what-is-a-static-offset) + - [How to Determine the Offset](#how-to-determine-the-offset) + - [Running Offset Determination](#running-offset-determination) + - [Applying the Offset Correction](#applying-the-offset-correction) + - [Using Make for Offset Determination](#using-make-for-offset-determination) + - [Additional Resources](#additional-resources) + - [Glossary](#glossary) + - [Scientific Publications using BciPy](#scientific-publications-using-bcipy) + - [2025](#2025) + - [2024](#2024) + - [2023](#2023) + - [2022](#2022) + - [2021](#2021) + - [2020](#2020) + - [Contributions Welcome](#contributions-welcome) + - [Contribution Guidelines](#contribution-guidelines) + - [Contributors](#contributors) + ## Dependencies -This project requires Python 3.8 or 3.9. Please see notes below for additional OS specific dependencies before installation can be completed and reference our documentation/FAQs for more information: +This project requires Python 3.9, 3.10 or 3.11. + +It will run on the latest windows (10, 11), linux (ubuntu 22.04) and macos (Sonoma). Other versions may work as well, but are not guaranteed. To see supported versions and operating systems as of this release see our GitHub builds: [BciPy Builds](https://github.com/CAMBI-tech/BciPy/actions/workflows/main.yml). Please see notes below for additional OS specific dependencies before installation can be completed and reference our documentation here: ### Linux @@ -26,184 +99,285 @@ You will need to install the prerequisites defined in `scripts\shell\linux_requi If you are using a Windows machine, you will need to install the [Microsoft Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). -*python 3.9 only!* -You will need to install pyWinhook manually. See [here](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pywinhook) for the appropriate wheel file (`pyWinhook‑1.6.2‑cp39‑cp39‑win_amd64.whl`). Then run `pip install `. We also include the 64-bit wheel file in the `.bcipy/downloads/` directory. - ### Mac -If you are using a Mac, you will need to install XCode and enable command line tools. `xcode-select --install`. If using an m1/2 chip, you will need to use the install script in `scripts/shell/m2chip_install.sh` to install the prerequisites. You may also need to use the Rosetta terminal to run the install script, but this has not been necessary in our testing using m2 chips. +If you are using a Mac, you will need to install XCode and enable command line tools. `xcode-select --install`. If using an m1/2 chip, you may need to use the install script in `scripts/shell/m2chip_install.sh` to install the prerequisites. You may also need to use the Rosetta terminal to run the install script, but this has not been necessary in our testing using m2 chips. -If using zsh, instead of bash, you may encounter a segementation fault when running BciPy. This is due to an issue in a dependeancy of psychopy with no known fix as of yet. Please use bash instead of zsh for now. +If using zsh, instead of bash, you may encounter a segmentation fault when running BciPy. This is due to an issue in a dependency of psychopy with no known fix as of yet. Please use bash instead of zsh for now. ## Installation ### BciPy Setup -In order to run BciPy on your computer, after following the dependencies above, you will need to install the BciPy package. +In order to run BciPy on your computer, after ensuring the OS dependencies above are met, you can proceed to install the BciPy package. + +#### Editable Install and GUI usage -To install for use locally and use of the GUI: +If wanting to run the GUI or make changes to the code, you will need to install BciPy in editable mode. This will ensure that all dependencies are installed and the package is linked to your local directory. This will allow you to make changes to the code and see them reflected in your local installation without needing to reinstall the package. 1. Git clone . 2. Change directory in your terminal to the repo directory. -3. Install the kenlm language model package. `pip install kenlm==0.1 --global-option="--max_order=12"`. -4. Install PsychoPy with no dependencies. `pip install psychopy==2023.2.1 --no-deps`. -5. Install BciPy in development mode. `pip install -e .`. +3. Install BciPy in development mode. -If wanting the latest version from PyPi and to build using modules: + ```sh + pip install -e . + ``` + +#### PyPi Install + +If you do not want to run the GUI or make changes to the code, you can install BciPy from PyPi. This will install the package and all dependencies, but will not link it to your local directory. This means that any changes you make to the code will not be reflected in your local installation. This is the recommended installation method if wanting to use the modules without making changes to the BciPy code. + +```sh +pip install bcipy +``` -1. `pip install bcipy` +#### Make install Alternately, if [Make](http://www.mingw.org/) is installed, you may run the follow command to install: ```sh -# install in development mode +# install in development mode with all testing and demo dependencies make dev-install ``` +## Usage + +The BciPy package may be used in two ways: via the command line interface (CLI) or via the graphical user interface (GUI). The CLI is useful for running experiments, training models, and visualizing data without needing to run the GUI. The GUI is useful for running experiments, editing parameters and training models with a more user-friendly interface. + +### Package Usage + +To run the package, you will need to import the modules you want to use. For example, to run the the system info module, you can run the following: + +```python +from bcipy.helpers import system_utils +system_utils.get_system_info() +``` + +### GUI Usage + +Run the following command in your terminal to start the BciPy GUI: + +```sh +python bcipy/gui/BCInterface.py +``` + +Alternately, if Make is installed, you may run the follow command to start the GUI from the BciPy root directory: + +```sh +make bci-gui +``` + ### Client Usage -#### Run an experiment protocol or task +Once BciPy is installed, it can be used via the command line interface. This is useful for running experiments, training models, and visualizing data without needing to run the GUI. -Invoke an experiment protocol or task directly using command line utility `bcipy`. +#### General Usage -Use the help flag to see other available input options: `bcipy --help` +Use the help flag to explore all available options: -You can pass it attributes with flags, if desired. +```sh +bcipy --help +``` -- Run with a User ID and Task: - - `bcipy --user "bci_user" --task "RSVP Calibration"` -- Run with a User ID and Tasks with a registered Protocol: - - `bcipy --user "bci_user" --experiment "default"` -- Run with fake data: - - `bcipy --fake` -- Run without visualizations: - - `bcipy --noviz` -- Run with alerts after each Task execution: - - `bcipy --alert` -- Run with custom parameters: - - `bcipy --parameters "path/to/valid/parameters.json"` - -#### Train a signal model with registered BciPy models +#### Running Experiments or Tasks via Command Line -To train a signal model (currently `PCARDAKDE` and `GazeModels`), run the following command after installing BciPy: +You can invoke an experiment protocol or task directly using the `bcipy` command-line utility. This allows for flexible execution of tasks with various configurations. -`bcipy-train` +##### Options -Use the help flag to see other available input options: `bcipy-train --help` - -You can pass it attributes with flags, if desired. - -- Run without a window prompting for data session folder: - - `bcipy-train -d path/to/data` -- Run with data visualizations (ERPs, etc.): - - `bcipy-train -v` -- Run with data visualizations that do not show, but save to file: - - `bcipy-train -s` -- Run with balanced accuracy: - - `bcipy-train --balanced-acc` -- Run with alerts after each Task execution: - - `bcipy-train --alert` -- Run with custom parameters: - - `bcipy-train -p "path/to/valid/parameters.json"` +```sh +# Run with a User ID and Task +bcipy --user "bci_user" --task "RSVP Calibration" + +# Run with a User ID and Experiment Protocol +bcipy --user "bci_user" --experiment "default" + +# Run with Simulated Data +bcipy --fake + +# Run without Visualizations +bcipy --noviz + +# Run with Alerts after Task Execution +bcipy --alert + +# Run with Custom Parameters +bcipy --parameters "path/to/valid/parameters.json" +``` + +These options provide flexibility for running experiments tailored to your specific needs. -#### Visualize ERP data from a session with Target / Non-Target labels +#### Train a Signal Model via Command Line -To generate plots that can be shown or saved after collection of data, run the following command after installing BciPy: +To train a signal model (e.g., `PCARDAKDE` or `GazeModels`), use the `bcipy-train` command. -`bcipy-erp-viz` +##### Basic Commands Signal Model Training -Use the help flag to see other available input options: `bcipy-erp-viz --help` +```sh +# Display help information +bcipy-train --help -You can pass it attributes with flags, if desired. +# Train using data from a specific folder +bcipy-train -d path/to/data -- Run without a window prompt for a data session folder: - - `bcipy-erp-viz -s path/to/data` -- Run with data visualizations (ERPs, etc.): - - `bcipy-erp-viz --show` -- Run with data visualizations that do not show, but save to file: - - `bcipy-erp-viz --save` -- Run with custom parameters (default is in bcipy/parameters/parameters.json): - - `bcipy-erp-viz -p "path/to/valid/parameters.json"` +# Display data visualizations (e.g., ERPs) +bcipy-train -v -#### BciPy Simulator Usage +# Save visualizations to a file without displaying them +bcipy-train -s -The simulator can be run using the command line utility `bcipy-sim`. +# Train with balanced accuracy metrics +bcipy-train --balanced-acc -To run the simulator with a single data folder, a custom parameters file, a trained model, and 5 iterations, use the following command: +# Receive alerts after each task execution +bcipy-train --alert -`bcipy-sim -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5` +# Use a custom parameters file +bcipy-train -p path/to/parameters.json +``` + +#### Visualize ERP data from a session with Target / Non-Target labels via Command Line -For more information or to see other available input options, use the help flag: `bcipy-sim --help`. In addition, more information can be found in the simulator module README. +To visualize ERP data from a session with Target / Non-Target labels, use the `bcipy-erp-viz` command. This command allows you to visualize the data collected during a session and provides options for saving or displaying the visualizations. -### Package Usage +##### Basic Commands ERP Viz -```python -from bcipy.helpers import system_utils -system_utils.get_system_info() +```sh +# Display help information +bcipy-erp-viz --help + +# Run without a window prompt for a data session folder +bcipy-erp-viz -s path/to/data + +# Run with data visualizations (ERPs, etc.) +bcipy-erp-viz --show + +# Run with data visualizations that do not show, but save to file +bcipy-erp-viz --save + +# Run with custom parameters (default is in bcipy/parameters/parameters.json) +bcipy-erp-viz -p "path/to/valid/parameters.json" ``` -### GUI Usage +### BciPy Simulator -Run the following command in your terminal to start the BciPy GUI: +The BciPy simulator allows you to run simulations based on previously collected data. This is useful for testing and validating models and algorithms without needing to collect new data. + +#### Running the Simulator + +The simulator can be executed using the `bcipy-sim` command-line utility. + +##### Basic Commands Simulator ```sh -python bcipy/gui/BCInterface.py +bcipy-sim --help ``` -Alternately, if Make is installed, you may run the follow command to start the GUI from the BciPy root directory: +##### Other Options + +- `-d`: Path to the data folder. +- `-p`: Path to the custom parameters file. [optional] +- `-m`: Path to the directory of trained model pickle files. +- `-n`: Number of iterations to run. ```sh -make bci-gui +bcipy-sim -d path/to/data -p path/to/parameters.json -m path/to/model.pkl/ -n 5 ``` -## Glossary +More comprehensive information can be found in the [Simulator Module README](./bcipy/simulator/README.md). -***Stimuli***: A single letter, tone or image shown (generally in an inquiry). Singular = stimulus, plural = stimuli. +## Core Modules -***Trial***: A collection of data after a stimuli is shown. A---- +### Top-Level Modules Overview -***Inquiry***: The set of stimuli after a fixation cross in a spelling task to gather user intent. A ---- B --- C ---- +Each module includes its own README, demo, and tests. Click on the module name to view its README for more information. -***Series***: Each series contains at least one inquiry. A letter/icon decision is made after a series in a spelling task. +#### [`Acquisition`](./bcipy/acquisition/README.md) -***Session***: Data collected for a task. Comprised of metadata about the task and a list of Series. +Captures data, returns desired time series, and saves to file at the end of a session. -***Protocol***: A collection of tasks and actions to be executed in a session. This is defined as within experiments and can be registered using the BciPy GUI. +#### [`Core`](./bcipy/core/README.md) -***Task***: An experimental design with stimuli, trials, inquiries and series for use in BCI. For instance, "RSVP Calibration" is a task. +Core data structures and methods essential for BciPy operation. -***Mode***: Common design elements between task types. For instance, Calibration and Free Spelling are modes. +- Includes triggers, parameters, and raw data handling. -***Paradigm***: Display paradigm with unique properties and modes. Ex. Rapid-Serial Visual Presentation (RSVP), Matrix Speller, Steady-State Visual Evoked Potential (SSVEP). +#### [`Display`](./bcipy/display/README.md) -## Core Modules +Manages the display of stimuli on the screen and records stimuli timing. + +#### [`Feedback`](./bcipy/feedback/README.md) + +Provides feedback mechanisms for sound and visual stimuli. + +#### [`GUI`](./bcipy/gui/README.md) + +End-user interface for registered BCI tasks and parameter editing. + +- Key files: [BCInterface.py](./bcipy/gui/BCInterface.py) and [ParamsForm](./bcipy/gui/parameters/params_form.py). + +#### [`Helpers`](./bcipy/helpers/README.md) + +Utility functions for interactions between modules and general-purpose tasks. + +#### [`IO`](./bcipy/io/README.md) + +Handles data file operations such as loading, saving, and format conversion. + +- Supported formats: BIDS, BrainVision, EDF, MNE, CSV, JSON, etc. + +#### [`Language`](./bcipy/language/README.md) + +Provides symbol probability predictions during typing tasks. + +#### [`Signal`](./bcipy/signal/README.md) + +Includes EEG signal models, gaze signal models, filters, processing tools, evaluators, and viewers. + +#### [`Simulator`](./bcipy/simulator/README.md) -This a list of the major modules and their functionality. Each module will contain its own README, demo and tests. Please check them out for more information! - -- `acquisition`: acquires data, gives back desired time series, saves to file at end of session. -- `display`: handles display of stimuli on screen and passes back stimuli timing. -- `signal`: eeg signal models, gaze signal models, filters, processing, evaluators and viewers. -- `gui`: end-user interface into registered bci tasks and parameter editing. See BCInterface.py. -- `helpers`: helpful functions needed for interactions between modules, basic I/O, and data visualization. -- `language`: gives probabilities of next symbols during typing. -- `parameters`: location of json parameters. This includes parameters.json (main experiment / app configuration) and device.json (device registry and configuration). -- `static`: image and sound stimuli, misc manuals, and readable texts for gui. -- `task`: bcipy implemented user tasks. Main collection of bci modules for use during various experimentation. Ex. RSVP Calibration. -- `feedback`: feedback mechanisms for sound and visual stimuli. -- `main`: executor of experiments. Main entry point into the application -- `config`: configuration parameters for the application, including paths and data filenames. -- `simulator`: provides support for running simulations based off of previously collected data. +Supports running simulations based on previously collected data. + +#### [`Task`](./bcipy/task/README.md) + +Implements user tasks and actions for BCI experiments. + +- Examples: RSVP Calibration, InterTaskAction. + +### Entry Point and Configuration Modules + +#### [`main.py`](./bcipy/main.py) + +The main executor of experiments and the primary entry point into the application. See the [Running Experiments](#running-experiments-or-tasks-via-command-line) section for more information. + +#### [`parameters/`](./bcipy/parameters/) + +Contains JSON configuration files: + +- [`parameters.json`](./bcipy/parameters/parameters.json): Main experiment and application configuration. +- [`device.json`](./bcipy/parameters/device.json): Device registry and configuration. +- [`experiments.json`](./bcipy/parameters/experiment/experiments.json): Experiment / protocol registry and configuration. +- [`phrases.json`](./bcipy/parameters/experiment/phrases.json): Phrase registry and configuration. This can be used to define a list of phrases used in the RSVP and Matrix Speller Copy phrase tasks. If not defined in parameters.json, the `task_text` parameter will be used. + +#### [`config.py`](./bcipy/config.py) + +Holds configuration parameters for BciPy, including paths and default data filenames. + +#### [`static/`](./bcipy/static/) + +Includes resources such as: + +- Image and sound stimuli. +- Miscellaneous manuals and readable texts for the GUI. ## 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: +See the [Task README](./bcipy/task/README.md) for more information on all supported paradigms, tasks, actions and modes. The major paradigms are listed below. ### RSVPKeyboard *RSVP KeyboardTM* is an EEG (electroencephalography) based BCI (brain computer interface) typing system. It utilizes a visual presentation technique called rapid serial visual presentation (RSVP). In RSVP, the options are presented rapidly at a single location with a temporal separation. Similarly in RSVP KeyboardTM, the symbols (the letters and additional symbols) are shown at the center of screen. When the subject wants to select a symbol, they await the intended symbol during the presentation and elicit a p300 response to a target symbol. -References: - ```text Orhan, U., Hild, K. E., 2nd, Erdogmus, D., Roark, B., Oken, B., & Fried-Oken, M. (2012). RSVP Keyboard: An EEG Based Typing Interface. Proceedings of the ... IEEE International Conference on Acoustics, Speech, and Signal Processing. ICASSP (Conference), 10.1109/ICASSP.2012.6287966. https://doi.org/10.1109/ICASSP.2012.6287966 ``` @@ -212,152 +386,121 @@ Orhan, U., Hild, K. E., 2nd, Erdogmus, D., Roark, B., Oken, B., & Fried-Oken, M. 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. -References: - ```text Farwell, L. A., & Donchin, E. (1988). Talking off the top of your head: toward a mental prosthesis utilizing event-related brain potentials. Electroencephalography and clinical Neurophysiology, 70(6), 510-523. Ahani A, Moghadamfalahi M, Erdogmus D. Language-Model Assisted And Icon-based Communication Through a Brain Computer Interface With Different Presentation Paradigms. IEEE Trans Neural Syst Rehabil Eng. 2018 Jul 25. doi: 10.1109/TNSRE.2018.2859432. ``` -## Demo - -All major functions and modules have demo and test files associated with them which may be run locally. This should help orient you to the functionality as well as serve as documentation. *If you add to the repo, you should be adding tests and fixing any test that fail when you change the code.* - -For example, you may run the main BciPy demo by: - -`python demo/bci_main_demo.py` +## Offset Determination and Correction -This demo will load in parameters and execute a demo task defined in the file. There are demo files contained in most modules, excepting gui, signal and parameters. Run them as a python script! +> [!CAUTION] +> Static offset determination and correction are critical steps before starting an experiment. BciPy uses LSL to acquire EEG data and Psychopy to present stimuli. The synchronization between the two systems is crucial for accurate data collection and analysis. -## Offset Determination and Correction +### What is a Static Offset? -Static offset determination and correction are critical steps before starting an experiment. BciPy uses LSL to acquire EEG data and Psychopy to present stimuli. The synchronization between the two systems is crucial for accurate data collection and analysis. +A static offset is the regular time difference between signals and stimuli presentation. This offset is determined through testing using a photodiode or another triggering mechanism. Once determined, the offset is corrected by shifting the EEG signal using the `static_offset` parameter in devices.json. -[LSL synchronization documentation](https://labstreaminglayer.readthedocs.io/info/time_synchronization.html) -[PsychoPy timing documentation](https://www.psychopy.org/general/timing/index.html) +#### How to Determine the Offset -A static offset is the regular time difference between our signals and stimuli. This offset is determined through testing via a photodiode or other triggering mechanism. The offset correction is done by shifting the EEG signal by the determined offset using the `static_offset` parameter. +To determine the static offset, you can run a timing verification task (e.g., `RSVPTimingVerification`) with a photodiode attached to the display and connected to your device. After collecting the data, use the `offset` module to analyze the results and recommend an offset correction value. -After running a timing verification task (such as, RSVPTimingVerification) with a photodiode attached to the display and connected to a device, the offset can be determined by analyzing the data. Use the `offset` module to recommend an offset correction value and display the results. +#### Running Offset Determination -To run the offset determination and print the results, use the following command: +To calculate the offset and display the results, use the following command: ```bash python bcipy/helpers/offset.py -r ``` -After running the above command, the recommended offset correction value will be displayed in the terminal and can be passed to determine system stability and display the results. +This will analyze the data and recommend an offset correction value, which will be displayed in the terminal. + +#### Applying the Offset Correction + +Once you have the recommended offset value, you can apply it to verify system stability and display the results. For example, if the recommended offset value is `0.1`, run the following command: ```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: +#### Using Make for Offset Determination + +If `Make` is installed, you can simplify the process by running the following command to determine the offset and display the results: ```sh make offset-recommend ``` -## Testing - -When writing tests, put them in the correct module, in a tests folder, and prefix the file and test itself with `test_` in order for pytest to discover it. See other module tests for examples! - -Development requirements must be installed before running: `pip install -r dev_requirements.txt` - -To run all tests, in the command line: +#### Additional Resources -```python -py.test -``` +For more information on synchronization and timing, refer to the following documentation: -To run a single modules tests (ex. acquisition), in the command line: +- [LSL Synchronization Documentation](https://labstreaminglayer.readthedocs.io/info/time_synchronization.html) +- [PsychoPy Timing Documentation](https://www.psychopy.org/general/timing/index.html) -```python -py.test acquisition -``` +## Glossary -To generate test coverage metrics, in the command line: +***Stimuli***: A single letter, tone or image shown (generally in an inquiry). Singular = stimulus, plural = stimuli. -```bash -coverage run --branch --source=bcipy -m pytest --mpl -k "not slow" +***Trial***: A collection of data after a stimuli is shown. A---- -#Generate a command line report -coverage report +***Inquiry***: The set of stimuli after a fixation cross in a spelling task to gather user intent. A ---- B --- C ---- -# Generate html doc in the bci folder. Navigate to index.html and click. -coverage html -``` +***Series***: Each series contains at least one inquiry. A letter/icon decision is made after a series in a spelling task. -Alternately, if Make is installed, you may run the follow command to run coverage/pytest and generate the html: +***Session***: Data collected for a task. Comprised of metadata about the task and a list of Series. -```sh -make coverage-html -``` +***Protocol***: A collection of tasks and actions to be executed in a session. This is defined for each experiment and can be registered in experiments.json via the BCI GUI. -## Linting +***Experiment***: A protocol with a set of parameters. This is defined within experiments and can be registered in experiments.json via the BCI GUI. -This project enforces `PEP` style guidelines using [flake8](http://flake8.pycqa.org/en/latest/). +***Task***: An experimental design with stimuli, trials, inquiries and series for use in BCI. For instance, "RSVP Calibration" is a task. -To avoid spending unnecessary time on formatting, we recommend using `autopep8`. You can specify a file or directory to auto format. When ready to push your code, you may run the following commands to format your code: +***Action***: A task without a paradigm. For instance, "RSVP Calibration" is a task, but "InterTaskAction" is an action. These are most often used to define the actions that take place in between tasks. -```sh -# autoformat all files in bcipy -autopep8 --in-place --aggressive -r bcipy +***Mode***: Common design elements between task types. For instance, Calibration and Free Spelling are modes. -# autoformat only the processor file -autopep8 --in-place --aggressive bcipy/acquisition/processor.py -``` +***Paradigm***: Display paradigm with unique properties and modes. Ex. Rapid-Serial Visual Presentation (RSVP), Matrix Speller, Steady-State Visual Evoked Potential (SSVEP). -Finally, run the lint check: `flake8 bcipy`. +## Scientific Publications using BciPy -Alternately, if Make is installed, you may run the follow command to run autopep8 and flake8: +### 2025 -```sh -make lint -``` +- Memmott, T., Klee, D., Smedemark-Margulies, N., & Oken, B. (2025). Artifact filtering application to increase online parity in a communication BCI: progress toward use in daily-life. Frontiers in Human Neuroscience, 19, 1551214. +- Peters, B., Celik, B., Gaines, D., Galvin-McLaughlin, D., Imbiriba, T., Kinsella, M., ... & Fried-Oken, M. (2025). RSVP keyboard with inquiry preview: mixed performance and user experience with an adaptive, multimodal typing interface combining EEG and switch input. Journal of neural engineering, 22(1), 016022. -## Type Checking +### 2024 -This project enforces `mypy` type checking. The typing project configuration is found in the mypy.ini file. To run type checking, run the following command: +- Klee, D., Memmott, T., & Oken, B. (2024). The Effect of Jittered Stimulus Onset Interval on Electrophysiological Markers of Attention in a Brain–Computer Interface Rapid Serial Visual Presentation Paradigm. Signals, 5(1), 18-39. +- Kocanaogullari, D. (2024). Detection and Assessment of Spatial Neglect Using a Novel Augmented Reality-Guided Eeg-Based Brain-Computer Interface (Doctoral dissertation, University of Pittsburgh). +- Smedemark-Margulies, N. (2024). Reducing Calibration Effort for Brain-Computer Interfaces (Doctoral dissertation, Northeastern University). -```sh -mypy bcipy -``` +### 2023 -To generate a report, run the following command: +- Smedemark-Margulies, N., Celik, B., Imbiriba, T., Kocanaogullari, A., & Erdoğmuş, D. (2023, June). Recursive estimation of user intent from noninvasive electroencephalography using discriminative models. In ICASSP 2023-2023 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP) (pp. 1-5). IEEE. -```sh -mypy --html-report bcipy -``` +### 2022 -Alternately, if Make is installed, you may run the follow command to run mypy: +- Mak, J., Kocanaogullari, D., Huang, X., Kersey, J., Shih, M., Grattan, E. S., ... & Akcakaya, M. (2022). Detection of stroke-induced visual neglect and target response prediction using augmented reality and electroencephalography. IEEE Transactions on Neural Systems and Rehabilitation Engineering, 30, 1840-1850. +- Galvin-McLaughlin, D., Klee, D., Memmott, T., Peters, B., Wiedrick, J., Fried-Oken, M., ... & Dudy, S. (2022). Methodology and preliminary data on feasibility of a neurofeedback protocol to improve visual attention to letters in mild Alzheimer's disease. Contemporary Clinical Trials Communications, 28, 100950. +- Klee, D., Memmott, T., Smedemark-Margulies, N., Celik, B., Erdogmus, D., & Oken, B. S. (2022). Target-related alpha attenuation in a brain-computer interface rapid serial visual presentation calibration. Frontiers in Human Neuroscience, 16, 882557. -```sh -make type -``` +### 2021 -### Contributions Welcome +- Koçanaoğulları, A., Akcakaya, M., & Erdoğmuş, D. (2021). Stopping criterion design for recursive Bayesian classification: analysis and decision geometry. IEEE Transactions on Pattern Analysis and Machine Intelligence, 44(9), 5590-5601. -If you want to be added to the development team slack or have additional questions, please reach out to us at ! +### 2020 -#### Contribution Guidelines +- Koçanaogullari, A. (2020). Active Recursive Bayesian Classification (Querying and Stopping) for Event Related Potential Driven Brain Computer Interface Systems (Doctoral dissertation, Northeastern University). +- Koçanaoğulları, A., Akçakaya, M., Oken, B., & Erdoğmuş, D. (2020, June). Optimal modality selection using information transfer rate for event related potential driven brain computer interfaces. In Proceedings of the 13th ACM International Conference on PErvasive Technologies Related to Assistive Environments (pp. 1-7). -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: +## Contributions Welcome -We welcome all contributions to BciPy! Please follow the guidelines below: +If you want to be added to the development team Discord or have additional questions, please reach out to us at ! -- All modules require tests and a demo. -- All tests must pass to merge, even if they are seemingly unrelated to your work. -- Use Spaces, not Tabs. -- Use informative names for functions and classes. -- Document the input and output of your functions / classes in the code. eg in-line commenting and typing. -- Do not push IDE or other local configuration files. -- All new modules or major functionality should be documented outside of the code with a README.md. --- See README.md in repo or go to this site for inspiration: . Always use a Markdown interpreter before pushing. +### Contribution Guidelines -See this resource for examples: +We follow and will enforce the code of conduct outlined [here](CODE_OF_CONDUCT.md). Please read it before contributing. ### Contributors diff --git a/bcipy/acquisition/datastream/generator.py b/bcipy/acquisition/datastream/generator.py index 8c6798bb5..79c31ebd3 100644 --- a/bcipy/acquisition/datastream/generator.py +++ b/bcipy/acquisition/datastream/generator.py @@ -1,14 +1,20 @@ """Functions for generating mock data to be used for testing/development.""" -from typing import Optional, Generator, Callable +from typing import Any, Callable, Generator, List, Optional, TextIO + from past.builtins import range from bcipy.config import DEFAULT_ENCODING from bcipy.signal.generator.generator import gen_random_data -def advance_to_row(filehandle, rownum): - """Utility function to advance a file cursor to the given row.""" +def advance_to_row(filehandle: TextIO, rownum: int) -> None: + """Utility function to advance a file cursor to the given row. + + Args: + filehandle (TextIO): The file handle to advance. + rownum (int): The target row number to advance to (1-indexed). + """ for _ in range(rownum - 1): filehandle.readline() @@ -20,39 +26,52 @@ class _DefaultEncoder: """Encodes data by returning the raw data.""" # pylint: disable=no-self-use - def encode(self, data): - """Encode the data that will be output by the file_data generator.""" + def encode(self, data: Any) -> Any: + """Encodes the input data. + + Args: + data (Any): The data to be encoded. + + Returns: + Any: The raw input data, as no actual encoding is performed. + """ return data -def generator_with_args(generator_fn, **generator_args) -> Callable[[], Generator]: +def generator_with_args(generator_fn: Callable[..., Generator], **generator_args: Any) -> Callable[..., Generator]: """Constructs a generator with the given arguments. - Parameters - ---------- - generator_fn : Function - a generator function - - Returns - ------- - Function which creates a generator using the given args. + + Args: + generator_fn (Callable[..., Generator]): A generator function. + **generator_args (Any): Keyword arguments to be passed to the generator_fn. + + Returns: + Callable[..., Generator]: A function that creates a generator using the given args. """ - def factory(**args): + def factory(**args: Any) -> Generator: return generator_fn(**{**generator_args, **args}) return factory -def random_data_generator(encoder=_DefaultEncoder(), - low=-1000, - high=1000, - channel_count=25): +def random_data_generator(encoder: _DefaultEncoder = _DefaultEncoder(), + low: int = -1000, + high: int = 1000, + channel_count: int = 25) -> Generator[Any, None, None]: """Generator that outputs random EEG-like data encoded according to the provided encoder. - Returns - ------- - A generator that produces packet of data, which decodes into a list of - floats in the range low to high with channel_count number of items. + Args: + encoder (_DefaultEncoder, optional): An encoder object to encode the output data. + Defaults to _DefaultEncoder(). + low (int, optional): The lower bound for random data generation. Defaults to -1000. + high (int, optional): The upper bound for random data generation. Defaults to 1000. + channel_count (int, optional): The number of channels (items) in the generated data. + Defaults to 25. + + Yields: + Any: A packet of data, which decodes into a list of floats in the range + low to high with `channel_count` number of items, encoded by the encoder. """ while True: @@ -60,23 +79,29 @@ def random_data_generator(encoder=_DefaultEncoder(), yield encoder.encode(sensor_data) -def file_data_generator(filename, header_row=3, encoder=_DefaultEncoder(), channel_count: Optional[int] = None): +def file_data_generator(filename: str, + header_row: int = 3, + encoder: _DefaultEncoder = _DefaultEncoder(), + channel_count: Optional[int] = None) -> Generator[List[float], None, None]: """Generates data from a source file and encodes it according to the provided encoder. - Parameters - ---------- - filename: str - Name of file containing a sample EEG session output. This file will - be the source of the generated data. File should be a csv file. - header_row: int, optional - Row with the header data (channel names); the default is 3, - assuming the first 2 rows are for metadata. - encoder : Encoder, optional - Used to encode the output data. - channel_count : int, optional - If provided this is used to truncate the data to the given number - of channels. + Args: + filename (str): Name of file containing a sample EEG session output. + This file will be the source of the generated data. + File should be a csv file. + header_row (int, optional): Row with the header data (channel names). + The default is 3, assuming the first 2 rows + are for metadata. + encoder (_DefaultEncoder, optional): Used to encode the output data. + Defaults to _DefaultEncoder(). + channel_count (Optional[int], optional): If provided this is used to truncate + the data to the given number of channels. + Defaults to None. + + Yields: + List[float]: A list of float values representing sensor data from the file, + encoded by the encoder. """ with open(filename, 'r', encoding=DEFAULT_ENCODING) as infile: @@ -94,8 +119,17 @@ def file_data_generator(filename, header_row=3, encoder=_DefaultEncoder(), chann def data_value(value: str) -> float: - """Convert to a float; some trigger values are strings, rather than - numbers (ex. indicating the letter); convert these to 1.0.""" + """Converts a string value to a float. + + Some trigger values might be strings (e.g., indicating a letter), + which are converted to 1.0. Empty strings are converted to 0.0. + + Args: + value (str): The string value to convert. + + Returns: + float: The converted float value. + """ if value: try: return float(value) diff --git a/bcipy/acquisition/datastream/lsl_server.py b/bcipy/acquisition/datastream/lsl_server.py index 0f8f82aa3..71f6f5bee 100644 --- a/bcipy/acquisition/datastream/lsl_server.py +++ b/bcipy/acquisition/datastream/lsl_server.py @@ -1,11 +1,11 @@ # mypy: disable-error-code="misc" -"""Data server that streams EEG data over a LabStreamingLayer StreamOutlet -using pylsl.""" +"""Data server that streams EEG data over a LabStreamingLayer StreamOutlet using pylsl.""" + import logging import time import uuid from queue import Empty, Queue -from typing import Optional, Generator +from typing import Generator, List, Optional, Tuple from pylsl import StreamInfo, StreamOutlet @@ -13,7 +13,8 @@ from bcipy.acquisition.datastream.producer import Producer from bcipy.acquisition.devices import DeviceSpec from bcipy.acquisition.util import StoppableThread -from bcipy.config import DEFAULT_ENCODING, MARKER_STREAM_NAME, SESSION_LOG_FILENAME +from bcipy.config import (DEFAULT_ENCODING, MARKER_STREAM_NAME, + SESSION_LOG_FILENAME) log = logging.getLogger(SESSION_LOG_FILENAME) # pylint: disable=too-many-arguments @@ -28,22 +29,21 @@ class LslDataServer(StoppableThread): fake_data can be set to false and this module can be run standalone in its own python instance. - Parameters - ---------- - device_spec : DeviceSpec - parameters used to configure the server. Should have at least - a list of channels and the sample frequency. - generator : optional Generator (see generator.py for options) - used to generate the data to be served. Uses random_data_generator - by default. - include_meta: bool, optional - if True, writes metadata to the outlet stream. - add_markers: bool, optional - if True, creates a the marker channel and streams data to this - channel at a fixed frequency. - marker_stream_name: str, optional - name of the sample marker stream - chunk_size: int, optional chunk size. + Args: + device_spec (DeviceSpec): Parameters used to configure the server. + Should have at least a list of channels and the + sample frequency. + generator (Optional[Generator], optional): Used to generate the data to be + served. Uses `random_data_generator` + by default. Defaults to None. + include_meta (bool, optional): If True, writes metadata to the outlet stream. + Defaults to True. + add_markers (bool, optional): If True, creates a the marker channel and + streams data to this channel at a fixed + frequency. Defaults to False. + marker_stream_name (str, optional): Name of the sample marker stream. + Defaults to `MARKER_STREAM_NAME`. + chunk_size (int, optional): Chunk size for the LSL stream. Defaults to 0. """ def __init__(self, @@ -56,7 +56,8 @@ def __init__(self, super(LslDataServer, self).__init__() self.device_spec = device_spec - self.generator = generator or random_data_generator(channel_count=device_spec.channel_count) + self.generator = generator or random_data_generator( + channel_count=device_spec.channel_count) log.debug("Starting LSL server for device: %s", device_spec.name) print(f"Serving: {device_spec}") @@ -95,8 +96,12 @@ def __init__(self, self.markers_outlet = StreamOutlet(markers_info) self.started = False - def stop(self): - """Stop the thread and cleanup resources.""" + def stop(self) -> None: + """Stops the thread and cleans up resources. + + This method sets the internal flag to stop the thread's execution + and closes the LSL `StreamOutlet`s, making them no longer discoverable. + """ log.debug("[*] Stopping data server") super(LslDataServer, self).stop() @@ -110,10 +115,12 @@ def stop(self): del self.markers_outlet self.markers_outlet = None - def run(self): - """Main loop of the thread. Continuously streams data to the stream - outlet at a rate consistent with the sample frequency. May also - output markers at a different interval.""" + def run(self) -> None: + """Main loop of the thread. + + Continuously streams data to the stream outlet at a rate consistent + with the sample frequency. May also output markers at a different interval. + """ sample_counter = 0 self.started = True @@ -137,8 +144,16 @@ def run(self): log.debug("[*] No longer pushing data") -def _settings(filename): - """Read the daq settings from the given data file""" +def _settings(filename: str) -> Tuple[str, int, List[str]]: + """Reads the DAQ settings from the given data file. + + Args: + filename (str): The path to the data file containing DAQ settings. + + Returns: + Tuple[str, int, List[str]]: A tuple containing the DAQ type (str), + sample rate (int), and a list of channel names (List[str]). + """ with open(filename, 'r', encoding=DEFAULT_ENCODING) as datafile: daq_type = datafile.readline().strip().split(',')[1] @@ -147,15 +162,20 @@ def _settings(filename): return (daq_type, sample_hz, channels) -def await_start(dataserver: LslDataServer, max_wait: float = 2.0): - """Blocks until server is started. Raises if max_wait is exceeded before - server is started. +def await_start(dataserver: LslDataServer, max_wait: float = 2.0) -> None: + """Blocks until the LSL data server is started. + + Raises an exception if `max_wait` is exceeded before the server starts. + + Args: + dataserver (LslDataServer): An instantiated (unstarted) server on which to wait. + max_wait (float, optional): The maximum number of seconds to wait. + Defaults to 2.0. After this period, if the + server has not successfully started, an + exception is thrown. - Parameters - ---------- - dataserver - instantiated (unstarted) server on which to wait. - max_wait - the max number of seconds to wait. After this period if the - server has not succesfully started an exception is thrown. + Raises: + Exception: If the server cannot start up within the `max_wait` period. """ dataserver.start() @@ -169,8 +189,14 @@ def await_start(dataserver: LslDataServer, max_wait: float = 2.0): raise Exception("Server couldn't start up in time.") -def main(): - """Initialize and start the server.""" +def main() -> None: + """Initializes and starts the LSL data server. + + This function parses command-line arguments to configure the server + (e.g., source filename, marker inclusion, device name, chunk size). + It then creates and starts an `LslDataServer` instance, running until + a `KeyboardInterrupt` is received. + """ import argparse from bcipy.acquisition.datastream.generator import file_data_generator @@ -181,8 +207,10 @@ def main(): help="file containing data to be streamed; " "if missing, random data will be served.") parser.add_argument('-m', '--markers', action="store_true", default=False) - parser.add_argument('-n', '--name', default='DSI-24', help='Name of the device spec to mock.') - parser.add_argument('-c', '--chunk_size', default=0, type=int, help='Chunk size') + parser.add_argument('-n', '--name', default='DSI-24', + help='Name of the device spec to mock.') + parser.add_argument('-c', '--chunk_size', default=0, + type=int, help='Chunk size') args = parser.parse_args() if args.filename: diff --git a/bcipy/acquisition/datastream/mock/eye_tracker_server.py b/bcipy/acquisition/datastream/mock/eye_tracker_server.py index 9cc3c3e73..948d5f6c5 100644 --- a/bcipy/acquisition/datastream/mock/eye_tracker_server.py +++ b/bcipy/acquisition/datastream/mock/eye_tracker_server.py @@ -3,6 +3,7 @@ import logging import math import time +from typing import Generator, List from numpy.random import uniform @@ -14,7 +15,11 @@ def eye_tracker_device() -> DeviceSpec: - """Mock DeviceSpec for an eye tracker.""" + """Mock DeviceSpec for an eye tracker. + + Returns: + DeviceSpec: A DeviceSpec object configured for an eye tracker. + """ return DeviceSpec(name='EyeTracker', channels=[ 'leftEyeX', 'leftEyeY', 'rightEyeX', 'rightEyeY', @@ -25,15 +30,24 @@ def eye_tracker_device() -> DeviceSpec: content_type='Gaze') -def eye_tracker_data_generator(display_x=1920, display_y=1080): +def eye_tracker_data_generator(display_x: int = 1920, display_y: int = 1080) -> Generator[List[float], None, None]: """Generates sample eye tracker data. TODO: determine appropriate values for pixelsPerDegree fields. TODO: look info alternatives; maybe PyGaze. http://www.pygaze.org/about/ + + Args: + display_x (int): The width of the display in pixels. Defaults to 1920. + display_y (int): The height of the display in pixels. Defaults to 1080. + + Yields: + List[float]: A list of float values representing eye tracker data, including + left eye X/Y, right eye X/Y, left pupil area, right pupil area, + pixels per degree X, and pixels per degree Y. """ - def area(diameter): + def area(diameter: float) -> float: return math.pi * (diameter / 2.0)**2 while True: @@ -50,14 +64,23 @@ def area(diameter): def eye_tracker_server() -> LslDataServer: - """Create a demo lsl_server that serves eye tracking data.""" + """Create a demo lsl_server that serves eye tracking data. + + Returns: + LslDataServer: An LslDataServer instance configured for eye tracking data. + """ return LslDataServer(device_spec=eye_tracker_device(), generator=eye_tracker_data_generator()) def main(): - """Create an run an lsl_server""" + """Create and run an lsl_server. + + This function initializes and starts an LSL data server for eye tracking. + It runs indefinitely until a KeyboardInterrupt is received, at which point + the server is stopped. + """ try: server = eye_tracker_server() log.info("New server created") diff --git a/bcipy/acquisition/datastream/mock/switch.py b/bcipy/acquisition/datastream/mock/switch.py index 824195171..94b4ffda3 100644 --- a/bcipy/acquisition/datastream/mock/switch.py +++ b/bcipy/acquisition/datastream/mock/switch.py @@ -4,15 +4,23 @@ from pylsl import StreamInfo, StreamOutlet -from bcipy.acquisition.devices import DeviceSpec, IRREGULAR_RATE -from bcipy.gui.main import BCIGui, app +from bcipy.acquisition.devices import (IRREGULAR_RATE, DeviceSpec, + preconfigured_device) from bcipy.config import SESSION_LOG_FILENAME +from bcipy.gui.main import BCIGui, app log = logging.getLogger(SESSION_LOG_FILENAME) def switch_device() -> DeviceSpec: - """Mock DeviceSpec for a switch""" + """Mock DeviceSpec for a switch. + + Returns: + DeviceSpec: A DeviceSpec object configured for a switch. + """ + device = preconfigured_device('Switch', strict=False) + if device: + return device return DeviceSpec(name='Switch', channels=['Marker'], sample_rate=IRREGULAR_RATE, @@ -23,21 +31,27 @@ class Switch: """Mock switch which streams data over LSL at an irregular interval.""" def __init__(self): + """Initializes the Switch with a DeviceSpec and LSL StreamOutlet.""" super().__init__() - self.device = switch_device() - self.lsl_id = 'bci_demo_switch' + self.device: DeviceSpec = switch_device() + self.lsl_id: str = 'bci_demo_switch' info = StreamInfo(self.device.name, self.device.content_type, self.device.channel_count, self.device.sample_rate, self.device.data_type, self.lsl_id) - self.outlet = StreamOutlet(info) + self.outlet: StreamOutlet = StreamOutlet(info) + + def click(self, _position: list) -> None: + """Pushes a sample to the LSL stream when a click event occurs. - def click(self, _position): - """Click event that pushes a sample""" + Args: + _position (list): The position of the click event. This parameter is + currently unused. + """ log.debug("Click!") self.outlet.push_sample([1.0]) - def quit(self): - """Quit and cleanup""" + def quit(self) -> None: + """Cleans up and releases the LSL StreamOutlet.""" del self.outlet self.outlet = None @@ -45,13 +59,19 @@ def quit(self): class SwitchGui(BCIGui): # pragma: no cover """GUI to emulate a switch.""" - def __init__(self, switch: Switch, *args, **kwargs): + def __init__(self, switch: 'Switch', *args, **kwargs): + """Initializes the SwitchGui with a Switch object. + + Args: + switch (Switch): The Switch object to control. + *args: Variable length argument list for the base class. + **kwargs: Arbitrary keyword arguments for the base class. + """ super().__init__(*args, **kwargs) - self.switch = switch + self.switch: Switch = switch def build_buttons(self) -> None: - """Build all buttons necessary for the UI. - """ + """Build all buttons necessary for the UI.""" self.add_button(message='Click!', position=[100, 75], size=[50, 50], @@ -71,9 +91,15 @@ def build_text(self) -> None: font_size=16) -def main(switch: Switch): # pragma: no cover - """Creates a PyQt5 GUI with a single button in the middle. Performs the - switch action when clicked.""" +def main(switch: Switch) -> None: # pragma: no cover + """Creates a PyQt6 GUI with a single button in the middle and runs it. + + Performs the switch action when the button is clicked and cleans up + the switch resources upon exit. + + Args: + switch (Switch): The Switch object to associate with the GUI. + """ gui = app(sys.argv) ex = SwitchGui(switch=switch, title='Demo Switch!', diff --git a/bcipy/acquisition/datastream/producer.py b/bcipy/acquisition/datastream/producer.py index d62ba60d3..82e698f66 100644 --- a/bcipy/acquisition/datastream/producer.py +++ b/bcipy/acquisition/datastream/producer.py @@ -1,11 +1,12 @@ -"""Code for mocking an EEG data stream. Code in this module produces data -at a specified frequency.""" +"""Code for mocking an EEG data stream. Code in this module produces data at a specified frequency.""" + import logging -from builtins import next -from queue import Queue import random import threading import time +from builtins import next +from queue import Queue +from typing import Any, Iterator, Optional from bcipy.acquisition.datastream.generator import random_data_generator from bcipy.config import SESSION_LOG_FILENAME @@ -16,76 +17,106 @@ class Producer(threading.Thread): """Produces generated data at a specified frequency. - Parameters - ---------- - queue : Queue - Generated data will be written to the queue. - freq : float, optional - Data will be generated at the given frequency. - generator : object, optional - python generator for creating data. - maxiters : int, optional - if provided, stops generating data after the given number of iters. + This class extends `threading.Thread` to run data generation in a separate + thread, pushing generated samples into a queue at a specified frequency. + It can also act as a context manager to automatically start and stop the + thread. + + Args: + queue (Queue): The queue where generated data will be written. + freq (float, optional): The frequency (in Hz) at which data will be generated. + Defaults to 1/100 (0.01 Hz). + generator (Optional[Any], optional): A Python generator for creating data. + Defaults to `random_data_generator()`. + maxiters (Optional[int], optional): If provided, stops generating data + after this many iterations. Defaults to None. """ def __init__(self, - queue, - freq=1 / 100, - generator=None, - maxiters=None): + queue: Queue, + freq: float = 1 / 100, + generator: Optional[Any] = None, + maxiters: Optional[int] = None): super(Producer, self).__init__() - self.daemon = True - self._running = True + self.daemon: bool = True + self._running: bool = True + + self.freq: float = freq + self.generator: Any = generator or random_data_generator() + self.maxiters: Optional[int] = maxiters + self.queue: Queue = queue - self.freq = freq - self.generator = generator or random_data_generator() - self.maxiters = maxiters - self.queue = queue + def __enter__(self) -> 'Producer': + """Enters the runtime context related to this object. - # @override to make this class a context manager - def __enter__(self): + Starts the producer thread when entering the context. + + Returns: + Producer: The Producer instance. + """ self.start() return self - # @override to make this class a context manager - def __exit__(self, _exc_type, _exc_value, _traceback): + def __exit__(self, _exc_type: Any, _exc_value: Any, _traceback: Any) -> None: + """Exits the runtime context related to this object. + + Stops the producer thread when exiting the context. + + Args: + _exc_type (Any): The exception type, if an exception was raised. + _exc_value (Any): The exception value, if an exception was raised. + _traceback (Any): The traceback, if an exception was raised. + """ self.stop() - def _genitem(self): - """Generates the data item to be added to the queue.""" + def _genitem(self) -> Any: + """Generates the data item to be added to the queue. + Returns: + Any: The next data item from the configured generator. + """ return next(self.generator) - def _additem(self): - """Adds the data item to the queue.""" + def _additem(self) -> None: + """Adds the data item to the queue. + This method fetches an item using `_genitem` and places it into the internal queue. + """ self.queue.put(self._genitem()) - def stop(self): - """Stop the thread; stopped threads cannot be restarted.""" + def stop(self) -> None: + """Stops the thread. + + Sets an internal flag to stop the thread's execution and waits for the thread to finish. + Stopped threads cannot be restarted. + """ self._running = False self.join() - def run(self): + def run(self) -> None: """Provides a control loop, adding a data item to the queue at the configured frequency. - @overrides the Thread run method + This method overrides the `threading.Thread.run` method. """ - def tick(): + def tick() -> Iterator[float]: """Corrects the time interval if the time of the work to add the - item causes drift.""" - current_time = time.time() - count = 0 + item causes drift. + + Yields: + float: The calculated sleep duration to maintain the target frequency. + """ + current_time: float = time.time() + count: int = 0 while True: count += 1 yield max(current_time + count * self.freq - time.time(), 0) - sleep_len = tick() - times = 0 + sleep_len: Iterator[float] = tick() + times: int = 0 while self._running and (self.maxiters is None or times < self.maxiters): times += 1 @@ -94,25 +125,39 @@ def tick(): class _ConsumerThread(threading.Thread): - """Consumer used to test the Producer by consuming generated items.""" + """Consumer used to test the Producer by consuming generated items. - def __init__(self, queue, name=None): - super(_ConsumerThread, self).__init__() - self.daemon = True - self.name = name - self._q = queue + Args: + queue (Queue): The queue from which to consume items. + name (Optional[str], optional): The name of the consumer thread. + Defaults to None. + """ - def run(self): + def __init__(self, queue: Queue, name: Optional[str] = None): + super(_ConsumerThread, self).__init__(name=name) + self.daemon: bool = True + self._q: Queue = queue + + def run(self) -> None: + """Main loop for the consumer thread. + + Continuously checks the queue for items and processes them, logging + the item and the queue size. + """ while True: if not self._q.empty(): - item = self._q.get() + item: Any = self._q.get() log.info('Getting %s: %s items in queue', str(item), str(self._q.qsize())) time.sleep(random.random()) -def main(): - """Main method""" +def main() -> None: + """Main method to demonstrate the Producer and Consumer threads. + + Initializes a Producer and a Consumer thread, starts them, and lets them run + for a short period (5 seconds) before the program exits. + """ data_queue: Queue = Queue() producer: Producer = Producer(data_queue) consumer: _ConsumerThread = _ConsumerThread(data_queue) diff --git a/bcipy/acquisition/demo/demo_eeg_with_switch.py b/bcipy/acquisition/demo/demo_eeg_with_switch.py index 3ce2d5fb3..bb371666b 100644 --- a/bcipy/acquisition/demo/demo_eeg_with_switch.py +++ b/bcipy/acquisition/demo/demo_eeg_with_switch.py @@ -2,11 +2,11 @@ import subprocess import time -from bcipy.config import BCIPY_ROOT +from bcipy.acquisition import LslAcquisitionClient, LslDataServer, await_start from bcipy.acquisition.datastream.mock.switch import switch_device from bcipy.acquisition.devices import preconfigured_device -from bcipy.acquisition import LslAcquisitionClient, LslDataServer, await_start -from bcipy.helpers.system_utils import log_to_stdout +from bcipy.config import BCIPY_ROOT +from bcipy.helpers.utils import log_to_stdout def start_switch(): diff --git a/bcipy/acquisition/demo/demo_eye_tracker_client_and_server.py b/bcipy/acquisition/demo/demo_eye_tracker_client_and_server.py index 6d0003420..cf0b95887 100644 --- a/bcipy/acquisition/demo/demo_eye_tracker_client_and_server.py +++ b/bcipy/acquisition/demo/demo_eye_tracker_client_and_server.py @@ -2,8 +2,8 @@ import time from bcipy.acquisition import LslAcquisitionClient, await_start -from bcipy.acquisition.datastream.mock.eye_tracker_server import (eye_tracker_device, - eye_tracker_server) +from bcipy.acquisition.datastream.mock.eye_tracker_server import ( + eye_tracker_device, eye_tracker_server) def main(): diff --git a/bcipy/acquisition/demo/demo_lsl_acq_client.py b/bcipy/acquisition/demo/demo_lsl_acq_client.py index 3679e94c4..b1c0eacbf 100644 --- a/bcipy/acquisition/demo/demo_lsl_acq_client.py +++ b/bcipy/acquisition/demo/demo_lsl_acq_client.py @@ -1,6 +1,7 @@ """Demo for the LslAcquisitionClient""" import time + from bcipy.acquisition import LslAcquisitionClient diff --git a/bcipy/acquisition/demo/demo_lsl_recorder.py b/bcipy/acquisition/demo/demo_lsl_recorder.py index b2efe1af8..2b14feb28 100644 --- a/bcipy/acquisition/demo/demo_lsl_recorder.py +++ b/bcipy/acquisition/demo/demo_lsl_recorder.py @@ -1,8 +1,9 @@ """Sample script to demonstrate usage of the LSL Recorder for writing data from an LSL stream.""" -from bcipy.acquisition.protocols.lsl.lsl_recorder import LslRecorder import time +from bcipy.acquisition.protocols.lsl.lsl_recorder import LslRecorder + SLEEP = 10 PATH = '.' diff --git a/bcipy/acquisition/demo/demo_switch.py b/bcipy/acquisition/demo/demo_switch.py new file mode 100644 index 000000000..ded73a7bc --- /dev/null +++ b/bcipy/acquisition/demo/demo_switch.py @@ -0,0 +1,61 @@ +"""Sample script to demonstrate usage of LSL client and server.""" +import subprocess +import time + +from bcipy.acquisition import LslAcquisitionClient +from bcipy.acquisition.datastream.mock.switch import switch_device +from bcipy.config import BCIPY_ROOT +from bcipy.helpers.utils import log_to_stdout + + +def start_switch(): + """Start the demo switch""" + return subprocess.Popen( + f'python {BCIPY_ROOT}/acquisition/datastream/mock/switch.py', + shell=True) + + +def main(debug: bool = False): + # pylint: disable=too-many-locals + """Creates a sample lsl client that reads data from a sample LSL server + (see demo/server.py). + + The client/server can be stopped with a Keyboard Interrupt (Ctl-C).""" + + if debug: + log_to_stdout() + + switch_client = LslAcquisitionClient(max_buffer_len=1024, + device_spec=switch_device(), + save_directory='.') + + # Open the Demo Switch GUI. + start_switch() + # Wait for switch start + print("Waiting for Switch") + time.sleep(0.5) + try: + seconds = 5 + switch_client.start_acquisition() + + print(f"\nCollecting data for {seconds}s...", + "Click in the demo switch GUI to register a switch hit.", + "Close the GUI when finished.\n") + + time.sleep(seconds) + switch_client.stop_acquisition() + print("\nThe collected data has been written to the local directory") + + except KeyboardInterrupt: + print("Keyboard Interrupt; stopping.") + switch_client.stop_acquisition() + print("\nThe collected data has been written to the local directory") + + +if __name__ == '__main__': + import argparse + + parser = argparse.ArgumentParser() + parser.add_argument('--debug', action='store_true') + args = parser.parse_args() + main(args.debug) diff --git a/bcipy/acquisition/devices.py b/bcipy/acquisition/devices.py index 74b152e58..bf39917bf 100644 --- a/bcipy/acquisition/devices.py +++ b/bcipy/acquisition/devices.py @@ -1,13 +1,13 @@ -"""Functionality for loading and querying configuration for supported hardware -devices.""" +"""Functionality for loading and querying configuration for supported hardware devices.""" + import json import logging from enum import Enum, auto from pathlib import Path -from typing import Dict, List, NamedTuple, Optional, Union - -from bcipy.config import DEFAULT_ENCODING, DEVICE_SPEC_PATH, SESSION_LOG_FILENAME +from typing import Any, Dict, List, NamedTuple, Optional, Union +from bcipy.config import (DEFAULT_ENCODING, DEVICE_SPEC_PATH, + SESSION_LOG_FILENAME) IRREGULAR_RATE: int = 0 DEFAULT_CONFIG = DEVICE_SPEC_PATH @@ -23,26 +23,41 @@ class ChannelSpec(NamedTuple): - """Represents metadata about a channel.""" - name: str # Label in the LSL metadata - label: str # Label used within BciPy (raw_data, etc.) - type: str = None - units: str = None + """Represents metadata about a channel. + + Attributes: + name (str): Label in the LSL metadata. + label (str): Label used within BciPy (raw_data, etc.). + type (Optional[str]): Type of the channel (e.g., 'EEG', 'Pupil'). Defaults to None. + units (Optional[str]): Units of measurement for the channel data (e.g., 'microvolts'). + Defaults to None. + """ + name: str + label: str + type: Optional[str] = None + units: Optional[str] = None - def __repr__(self): + def __repr__(self) -> str: + """Returns a string representation of the ChannelSpec object.""" fields = ['name', 'label', 'type', 'units'] items = [(field, self.__getattribute__(field)) for field in fields] props = [f"{key}='{val}'" for key, val in items if val] - return f"ChannelSpec({', '.join(props)})" + return f"ChannelSpec({ ', '.join(props) })" + + +def channel_spec(channel: Union[str, Dict[str, Any], ChannelSpec]) -> ChannelSpec: + """Creates a ChannelSpec from the given channel information. + Args: + channel (Union[str, Dict[str, Any], ChannelSpec]): Acquisition channel + information, specified as either just the label (str), a dictionary + with channel properties, or an existing ChannelSpec object. -def channel_spec(channel: Union[str, dict, ChannelSpec]) -> ChannelSpec: - """Creates a ChannelSpec from the given channel. + Returns: + ChannelSpec: A `ChannelSpec` object. - Parameters - ---------- - channel - acquisition channel information specified as either just the - label or with additional data represented by a dict or ChannelSpec. + Raises: + Exception: If an unexpected channel type is provided. """ if isinstance(channel, str): return ChannelSpec(name=channel, label=channel) @@ -59,40 +74,49 @@ class DeviceStatus(Enum): PASSIVE = auto() def __str__(self) -> str: - """String representation""" + """Returns the lowercase string representation of the DeviceStatus enum member.""" return self.name.lower() @classmethod def from_str(cls, name: str) -> 'DeviceStatus': - """Returns the DeviceStatus associated with the given string - representation.""" + """Returns the `DeviceStatus` enum member associated with the given string + representation. + + Args: + name (str): The string representation of the device status (e.g., 'active', 'passive'). + + Returns: + DeviceStatus: The corresponding `DeviceStatus` enum member. + """ return cls[name.upper()] class DeviceSpec: """Specification for a hardware device used in data acquisition. - Parameters - ---------- - name - device short name; ex. DSI-24 - channels - list of data collection channels; devices must have at least - one channel. Channels may be provided as a list of names or list of - ChannelSpecs. - sample_rate - sample frequency in Hz. - content_type - type of device; likely one of ['EEG', 'MoCap', 'Gaze', - 'Audio', 'Markers']; see https://github.com/sccn/xdf/wiki/Meta-Data. - description - device description - ex. 'Wearable Sensing DSI-24 dry electrode EEG headset' - data_type - data format of a channel; all channels must have the same type; - see https://labstreaminglayer.readthedocs.io/projects/liblsl/ref/enums.html - excluded_from_analysis - list of channels (label) to exclude from analysis. - status - recording status - static_offset - Specifies the static trigger offset (in seconds) used to align - triggers properly with EEG data from LSL. The system includes built-in - offset correction, but there is still a hardware-limited offset between EEG - and trigger timing values for which the system does not account. The correct - value may be different for each computer, and must be determined on a - case-by-case basis. Default: 0.1", + Args: + name (str): Device short name (e.g., 'DSI-24'). + channels (Union[List[str], List[ChannelSpec], List[dict]]): A list of + data collection channels. Devices must have at least one channel. + Channels may be provided as a list of names (str), a list of + `ChannelSpec` objects, or a list of dictionaries representing channel properties. + sample_rate (int): Sample frequency in Hz. + content_type (str, optional): Type of device (e.g., 'EEG', 'MoCap', 'Gaze', + 'Audio', 'Markers'). Defaults to `DEFAULT_DEVICE_TYPE` ('EEG'). + See https://github.com/sccn/xdf/wiki/Meta-Data. + description (Optional[str], optional): Device description (e.g., + 'Wearable Sensing DSI-24 dry electrode EEG headset'). + Defaults to `name` if not provided. + excluded_from_analysis (Optional[List[str]], optional): A list of channel labels + to exclude from analysis. + Defaults to an empty list. + data_type (str, optional): Data format of a channel. All channels must have the same type. + Defaults to 'float32'. See https://labstreaminglayer.readthedocs.io/projects/liblsl/ref/enums.html. + status (DeviceStatus, optional): Recording status of the device. + Defaults to `DeviceStatus.ACTIVE`. + static_offset (float, optional): Specifies the static trigger offset (in seconds) + used to align triggers properly with EEG data from LSL. + Defaults to `DEFAULT_STATIC_OFFSET` (0.1). """ def __init__(self, @@ -109,38 +133,40 @@ def __init__(self, assert sample_rate >= 0, "Sample rate can't be negative." assert data_type in SUPPORTED_DATA_TYPES - self.name = name - self.channel_specs = [channel_spec(ch) for ch in channels] - self.sample_rate = int(sample_rate) - self.content_type = content_type - self.description = description or name - self.data_type = data_type - self.excluded_from_analysis = excluded_from_analysis or [] + self.name: str = name + self.channel_specs: List[ChannelSpec] = [ + channel_spec(ch) for ch in channels] + self.sample_rate: int = int(sample_rate) + self.content_type: str = content_type + self.description: str = description or name + self.data_type: str = data_type + self.excluded_from_analysis: List[str] = excluded_from_analysis or [] self._validate_excluded_channels() - self.status = status - self.static_offset = static_offset + self.status: DeviceStatus = status + self.static_offset: float = static_offset @property def channel_count(self) -> int: - """Number of channels""" + """Returns the number of channels for the device.""" return len(self.channel_specs) @property def channels(self) -> List[str]: - """List of channel labels. These may be customized for BciPy.""" + """Returns a list of channel labels, which may be customized for BciPy.""" return [ch.label for ch in self.channel_specs] @property def channel_names(self) -> List[str]: - """List of channel names from the device.""" + """Returns a list of channel names as reported by the device.""" return [ch.name for ch in self.channel_specs] @property def analysis_channels(self) -> List[str]: - """List of channels used for analysis by the signal module. - Parameters: - ----------- - exclude_trg - indicates whether or not to exclude a TRG channel if present. + """Returns a list of channels used for analysis by the signal module. + + Returns: + List[str]: A list of channel labels to be used for analysis, excluding + any channels specified in `excluded_from_analysis`. """ return list( @@ -149,12 +175,19 @@ def analysis_channels(self) -> List[str]: @property def is_active(self) -> bool: - """Returns a boolean indicating if the device is currently active - (recording status set to DeviceStatus.ACTIVE).""" + """Checks if the device is currently active (recording status set to `DeviceStatus.ACTIVE`). + + Returns: + bool: True if the device is active, False otherwise. + """ return self.status == DeviceStatus.ACTIVE - def to_dict(self) -> dict: - """Converts the DeviceSpec to a dict.""" + def to_dict(self) -> Dict[str, Any]: + """Converts the `DeviceSpec` object to a dictionary representation. + + Returns: + Dict[str, Any]: A dictionary containing the device's properties. + """ return { 'name': self.name, 'content_type': self.content_type, @@ -166,21 +199,25 @@ def to_dict(self) -> dict: 'static_offset': self.static_offset } - def __str__(self): - """Custom str representation.""" + def __str__(self) -> str: + """Returns a custom string representation of the `DeviceSpec` object.""" names = [ 'name', 'content_type', 'channels', 'sample_rate', 'description' ] - def quoted_value(name): + def quoted_value(name: str) -> Union[str, Any]: value = self.__getattribute__(name) return f"'{value}'" if isinstance(value, str) else value props = [f"{name}={quoted_value(name)}" for name in names] - return f"DeviceSpec({', '.join(props)})" + return f"DeviceSpec({ ', '.join(props) })" + + def _validate_excluded_channels(self) -> None: + """Warns if any excluded channels are not found in the device's channel list. - def _validate_excluded_channels(self): - """Warn if excluded channels are not in the list of channels""" + This method logs a warning for each channel in `excluded_from_analysis` + that does not exist in `self.channels`. + """ for channel in self.excluded_from_analysis: if channel not in self.channels: logger.warning( @@ -188,9 +225,18 @@ def _validate_excluded_channels(self): ) -def make_device_spec(config: dict) -> DeviceSpec: - """Constructs a DeviceSpec from a dict. Throws a KeyError if any fields - are missing.""" +def make_device_spec(config: Dict[str, Any]) -> DeviceSpec: + """Constructs a `DeviceSpec` object from a dictionary configuration. + + Args: + config (Dict[str, Any]): A dictionary containing device configuration parameters. + + Returns: + DeviceSpec: A `DeviceSpec` object initialized with the provided configuration. + + Raises: + KeyError: If any required fields are missing in the `config` dictionary. + """ default_status = str(DeviceStatus.ACTIVE) return DeviceSpec(name=config['name'], content_type=config['content_type'], @@ -199,19 +245,23 @@ def make_device_spec(config: dict) -> DeviceSpec: description=config['description'], excluded_from_analysis=config.get( 'excluded_from_analysis', []), - status=DeviceStatus.from_str(config.get('status', default_status)), + status=DeviceStatus.from_str( + config.get('status', default_status)), static_offset=config.get('static_offset', DEFAULT_STATIC_OFFSET)) -def load(config_path: Path = Path(DEFAULT_CONFIG), replace: bool = False) -> Dict[str, DeviceSpec]: - """Load the list of supported hardware for data acquisition from the given +def load(config_path: Path = Path(DEFAULT_CONFIG), replace: bool = False) -> Dict[str, 'DeviceSpec']: + """Loads the list of supported hardware devices for data acquisition from a configuration file. - Parameters - ---------- - config_path - path to the devices json file - replace - optional; if true, existing devices are replaced; if false, - values will be overwritten or appended. + Args: + config_path (Path, optional): Path to the devices JSON file. + Defaults to `Path(DEFAULT_CONFIG)`. + replace (bool, optional): If True, existing devices are replaced; if False, + values will be overwritten or appended. Defaults to False. + + Returns: + Dict[str, DeviceSpec]: A dictionary of loaded `DeviceSpec` objects, keyed by device name. """ global _SUPPORTED_DEVICES @@ -225,9 +275,14 @@ def load(config_path: Path = Path(DEFAULT_CONFIG), replace: bool = False) -> Dic return _SUPPORTED_DEVICES -def preconfigured_devices() -> Dict[str, DeviceSpec]: - """Returns the preconfigured devices keyed by name. If no devices have yet - been configured, loads and returns the DEFAULT_CONFIG.""" +def preconfigured_devices() -> Dict[str, 'DeviceSpec']: + """Returns the preconfigured devices, keyed by name. + + If no devices have yet been configured, it loads and returns the `DEFAULT_CONFIG`. + + Returns: + Dict[str, DeviceSpec]: A dictionary of preconfigured `DeviceSpec` objects. + """ global _SUPPORTED_DEVICES if not _SUPPORTED_DEVICES: load() @@ -235,33 +290,55 @@ def preconfigured_devices() -> Dict[str, DeviceSpec]: def preconfigured_device(name: str, strict: bool = True) -> DeviceSpec: - """Retrieve the DeviceSpec with the given name. An exception is raised - if the device is not found.""" + """Retrieves the `DeviceSpec` with the given name. + + Args: + name (str): The name of the device to retrieve. + strict (bool, optional): If True, raises an exception if the device is not found. + Defaults to True. + + Returns: + DeviceSpec: The `DeviceSpec` object for the specified device. + + Raises: + ValueError: If `strict` is True and the device is not found. + """ device = preconfigured_devices().get(name, None) if strict and not device: current = ', '.join( - [f"'{key}'" for key, _ in preconfigured_devices().items()]) + [f"' {key}'" for key, _ in preconfigured_devices().items()]) msg = ( - f"Device not found: {name}." - "\n\n" - f"The current list of devices includes the following: {current}." - "\n" + f"Device not found: {name}.\n\n" + f"The current list of devices includes the following: {current}.\n" "You may register new devices using the device module `register` function or in bulk" " using `load`.") logger.error(msg) raise ValueError(msg) - return device + return device # type: ignore def with_content_type(content_type: str) -> List[DeviceSpec]: - """Retrieve the list of DeviceSpecs with the given content_type.""" + """Retrieves a list of `DeviceSpec` objects with the given content type. + + Args: + content_type (str): The content type to filter devices by. + + Returns: + List[DeviceSpec]: A list of `DeviceSpec` objects matching the specified content type. + """ return [ spec for spec in preconfigured_devices().values() if spec.content_type == content_type ] -def register(device_spec: DeviceSpec): - """Register the given DeviceSpec.""" +def register(device_spec: DeviceSpec) -> None: + """Registers the given `DeviceSpec`. + + Adds the provided `DeviceSpec` to the collection of preconfigured devices. + + Args: + device_spec (DeviceSpec): The `DeviceSpec` object to register. + """ config = preconfigured_devices() config[device_spec.name] = device_spec diff --git a/bcipy/acquisition/exceptions.py b/bcipy/acquisition/exceptions.py index 7caaf1f54..de13064e4 100644 --- a/bcipy/acquisition/exceptions.py +++ b/bcipy/acquisition/exceptions.py @@ -1,12 +1,19 @@ - class InvalidClockError(Exception): - def __init__(self, msg): - Exception.__init__(self, msg) + """Exception raised for invalid clock operations in acquisition.""" + + def __init__(self, msg: str): + """Initializes the InvalidClockError with a message. + + Args: + msg (str): The error message. + """ + super().__init__(msg) class UnsupportedContentType(Exception): """Error that occurs when attempting to collect data from a device with a - content type that is not yet supported by BciPy.""" + content type that is not yet supported by BciPy. + """ class InsufficientDataException(Exception): diff --git a/bcipy/acquisition/marker_writer.py b/bcipy/acquisition/marker_writer.py index 6d4172654..d45616de4 100644 --- a/bcipy/acquisition/marker_writer.py +++ b/bcipy/acquisition/marker_writer.py @@ -1,54 +1,76 @@ """Defines classes that can write markers to LabStreamingLayer StreamOutlet.""" import logging -from typing import Any +from typing import Any, Optional import pylsl + from bcipy.config import SESSION_LOG_FILENAME log = logging.getLogger(SESSION_LOG_FILENAME) -class MarkerWriter(): +class MarkerWriter: """Abstract base class for an object that can be used to handle stimulus markers. """ - def push_marker(self, marker: Any): - """Push the given stimulus marker for processing. + def push_marker(self, marker: Any) -> None: + """Pushes the given stimulus marker for processing. + + This method must be implemented by subclasses. + + Args: + marker (Any): Any object that can be converted to a string, representing + the stimulus marker. - Parameters - ---------- - - marker : any object that can be converted to a str + Raises: + NotImplementedError: If the method is not implemented by a subclass. """ raise NotImplementedError() - def cleanup(self): - """Performs any necessary cleanup""" + def cleanup(self) -> None: + """Performs any necessary cleanup. + + This method must be implemented by subclasses. + + Raises: + NotImplementedError: If the method is not implemented by a subclass. + """ raise NotImplementedError() class LslMarkerWriter(MarkerWriter): - """Writes stimulus markers to a LabStreamingLayer StreamOutlet - using pylsl. To consume this data, the client code would need to create a - pylsl.StreamInlet. See https://github.com/sccn/labstreaminglayer/wiki. + """Writes stimulus markers to a LabStreamingLayer StreamOutlet using pylsl. + + To consume this data, client code would typically create a `pylsl.StreamInlet`. + See https://github.com/sccn/labstreaminglayer/wiki for more information. + + Args: + stream_name (str, optional): The name of the LSL stream. Defaults to + "BCI_Stimulus_Markers". + stream_id (str, optional): The unique ID of the LSL stream. Defaults to + "bci_stim_markers". """ def __init__(self, stream_name: str = "BCI_Stimulus_Markers", stream_id: str = "bci_stim_markers"): - super(LslMarkerWriter, self).__init__() - self.stream_name = stream_name + super().__init__() + self.stream_name: str = stream_name markers_info = pylsl.StreamInfo(stream_name, "Markers", 1, 0, 'string', stream_id) - self.markers_outlet = pylsl.StreamOutlet(markers_info) - self.first_marker_stamp: float = None + self.markers_outlet: pylsl.StreamOutlet = pylsl.StreamOutlet(markers_info) + self.first_marker_stamp: Optional[float] = None - def push_marker(self, marker: Any): - """Push the given stimulus marker for processing. + def push_marker(self, marker: Any) -> None: + """Pushes the given stimulus marker to the LSL stream. - Parameters - ---------- - - marker : any object that can be converted to a str + The marker is converted to a string and sent along with a local timestamp. + The `first_marker_stamp` is set upon the first marker push. + + Args: + marker (Any): Any object that can be converted to a string, representing + the stimulus marker. """ stamp = pylsl.local_clock() log.info(f'Pushing marker {str(marker)} at {stamp}') @@ -56,27 +78,28 @@ def push_marker(self, marker: Any): if not self.first_marker_stamp: self.first_marker_stamp = stamp - def cleanup(self): - """Cleans up the StreamOutlet.""" + def cleanup(self) -> None: + """Cleans up and releases the LSL StreamOutlet.""" del self.markers_outlet class NullMarkerWriter(MarkerWriter): """MarkerWriter which doesn't write anything. - A NullMarkerWriter can be passed in to the calling object in scenarios - where marker handling occurs indirectly (ex. through a trigger box). By - using a NullMarkerWriter rather than a None value, the calling - object does not have to do additional null checks and a separation - of concerns is maintained regarding how triggers are written for different - devices. + A `NullMarkerWriter` can be passed to calling objects in scenarios where + marker handling occurs indirectly (e.g., through a trigger box). By using + a `NullMarkerWriter` instead of `None`, the calling object avoids additional + null checks, maintaining a separation of concerns regarding how triggers + are written for different devices. See the Null Object Design Pattern: https://en.wikipedia.org/wiki/Null_object_pattern """ - def push_marker(self, marker: Any): + def push_marker(self, marker: Any) -> None: + """Overrides the abstract method to do nothing.""" pass def cleanup(self): + """Overrides the abstract method to do nothing.""" pass diff --git a/bcipy/acquisition/multimodal.py b/bcipy/acquisition/multimodal.py index f39d0c266..ad4ad2a5e 100644 --- a/bcipy/acquisition/multimodal.py +++ b/bcipy/acquisition/multimodal.py @@ -8,20 +8,22 @@ UnsupportedContentType) from bcipy.acquisition.protocols.lsl.lsl_client import LslAcquisitionClient from bcipy.acquisition.record import Record -from bcipy.helpers.system_utils import AutoNumberEnum from bcipy.config import SESSION_LOG_FILENAME +from bcipy.helpers.utils import AutoNumberEnum logger = logging.getLogger(SESSION_LOG_FILENAME) class ContentType(AutoNumberEnum): - """Enum of supported acquisition device (LSL) content types. Allows for - case-insensitive matching, as well as synonyms for some types. + """Enum of supported acquisition device (LSL) content types. - >>> ContentType(1) == ContentType.EEG - True - >>> ContentType('Eeg') == ContentType.EEG - True + Allows for case-insensitive matching, as well as synonyms for some types. + + Examples: + >>> ContentType(1) == ContentType.EEG + True + >>> ContentType('Eeg') == ContentType.EEG + True """ def __init__(self, synonyms: List[str]): @@ -33,34 +35,40 @@ def __init__(self, synonyms: List[str]): @classmethod def _missing_(cls, value: Any) -> 'ContentType': - """Lookup function used when a value is not found.""" + """Lookup function used when a value is not found. + + This method enables case-insensitive matching and allows for synonyms. + + Args: + value (Any): The value to lookup, which will be converted to a string and lowercased. + + Returns: + ContentType: The matching ContentType enum member. + + Raises: + UnsupportedContentType: If no matching content type is found. + """ value = str(value).lower() - for member in cls: - if member.name.lower() == value or value in member.synonyms: + for member in cls: # type: ignore + if member.name.lower() == value or value in member.synonyms: # type: ignore return member raise UnsupportedContentType(f"ContentType not supported: {value}") class ClientManager(): - """Manages multiple acquisition clients. This class can also act as an - acquisition client. If used in this way, it dispatches to the managed - client with the default_client_type. - - >>> from bcipy.acquisition import LslAcquisitionClient - >>> from bcipy.acquisition.devices import DeviceSpec - >>> spec = DeviceSpec('Testing', ['ch1', 'ch2', 'ch3'], 60.0, 'EEG') - >>> manager = ClientManager() - >>> eeg_client = LslAcquisitionClient(device_spec=spec) - >>> manager.add_client(eeg_client) - >>> manager.device_spec == spec - True - - Parameters - ---------- - default_content_type - used for dispatching calls to an LslClient. + """Manages multiple acquisition clients. + + This class can also act as an acquisition client. If used in this way, + it dispatches to the managed client with the `default_client_type`. + + Args: + default_content_type (ContentType, optional): The default content type + to use for dispatching calls to an `LslClient`. Defaults to `ContentType.EEG`. """ - def __init__(self, default_content_type: ContentType = ContentType.EEG) -> None: + inlet: Any = None # To satisfy mypy, as ClientManager can act as an LslAcquisitionClient + + def __init__(self, default_content_type: ContentType = ContentType.EEG) -> None: # type: ignore self._clients: Dict[ContentType, LslAcquisitionClient] = {} self.default_content_type = default_content_type @@ -71,27 +79,25 @@ def clients(self) -> List[LslAcquisitionClient]: @property def clients_by_type(self) -> Dict[ContentType, LslAcquisitionClient]: - """Returns a dict of clients keyed by their content type""" + """Returns a dictionary of clients keyed by their content type.""" return self._clients @property def device_specs(self) -> List[DeviceSpec]: - """Returns a list of DeviceSpecs for all the clients.""" - return [client.device_spec for client in self.clients] + """Returns a list of `DeviceSpec` objects for all the clients.""" + return [client.device_spec for client in self.clients if client.device_spec] # type: ignore @property def device_content_types(self) -> List[ContentType]: - """Returns a list of ContentTypes provided by the configured devices. - """ + """Returns a list of `ContentType` enums provided by the configured devices.""" return list(self._clients.keys()) @property def active_device_content_types(self) -> List[ContentType]: - """Returns a list of ContentTypes provided by the active configured - devices.""" + """Returns a list of `ContentType` enums provided by the active configured devices.""" return [ content_type for content_type, client in self._clients.items() - if client.device_spec.is_active + if client.device_spec and client.device_spec.is_active # type: ignore ] @property @@ -99,24 +105,38 @@ def default_client(self) -> Optional[LslAcquisitionClient]: """Returns the default client.""" return self.get_client(self.default_content_type) - def add_client(self, client: LslAcquisitionClient): - """Add the given client to the manager.""" - content_type = ContentType(client.device_spec.content_type) + def add_client(self, client: LslAcquisitionClient) -> None: # type: ignore + """Adds the given client to the manager. + + Args: + client (LslAcquisitionClient): The client instance to add. + """ + content_type = ContentType( + client.device_spec.content_type) # type: ignore self._clients[content_type] = client def get_client( self, content_type: ContentType) -> Optional[LslAcquisitionClient]: - """Get client by content type""" + """Retrieves a client by its content type. + + Args: + content_type (ContentType): The content type of the client to retrieve. + + Returns: + Optional[LslAcquisitionClient]: The `LslAcquisitionClient` instance if found, + otherwise None. + """ return self._clients.get(content_type, None) - def start_acquisition(self): - """Start acquiring data for all clients""" + def start_acquisition(self) -> None: # type: ignore + """Starts data acquisition for all clients.""" for client in self.clients: + # type: ignore logger.info(f"Connecting to {client.device_spec.name}...") client.start_acquisition() - def stop_acquisition(self): - """Stop acquiring data for all clients""" + def stop_acquisition(self) -> None: # type: ignore + """Stops data acquisition for all clients.""" logger.info("Stopping acquisition...") for client in self.clients: client.stop_acquisition() @@ -128,52 +148,83 @@ def get_data_by_device( content_types: Optional[List[ContentType]] = None, strict: bool = True ) -> Dict[ContentType, List[Record]]: - """Get data for one or more devices. The number of samples for each - device depends on the sample rate and may be different for item. - - Parameters - ---------- - start - start time (acquisition clock) of data window; NOTE: the - actual start time will be adjusted to by the static_offset - configured for each device. - seconds - duration of data to return for each device - content_types - specifies which devices to include; if not - unspecified, data for all types is returned. - strict - if True, raises an exception if the returned rows is - less than the requested number of records. + """Retrieves data for one or more devices within a specified time window. + + The number of samples for each device depends on the sample rate and may + differ. The actual start time will be adjusted by the `static_offset` + configured for each device. + + Args: + start (Optional[float]): Start time (acquisition clock) of the data window. + seconds (Optional[float]): Duration of data to return for each device. + content_types (Optional[List[ContentType]], optional): Specifies which + devices to include. If None, data for all types is returned. + Defaults to None. + strict (bool, optional): If True, raises an `InsufficientDataException` + if the number of returned records is less than the requested number. + Defaults to True. + + Returns: + Dict[ContentType, List[Record]]: A dictionary where keys are `ContentType` + and values are lists of `Record` objects. + + Raises: + InsufficientDataException: If `strict` is True and the returned data count + is less than the requested count for a device. """ - output = {} + output: Dict[ContentType, List[Record]] = {} if not content_types: content_types = self.device_content_types for content_type in content_types: name = content_type.name client = self.get_client(content_type) - adjusted_start = start + client.device_spec.static_offset - if client.device_spec.sample_rate > 0: - count = round(seconds * client.device_spec.sample_rate) - logger.info(f'Need {count} records for processing {name} data') - output[content_type] = client.get_data(start=adjusted_start, - limit=count) - data_count = len(output[content_type]) - if strict and data_count < count: - msg = f'Needed {count} {name} records but received {data_count}' - logger.error(msg) - raise InsufficientDataException(msg) + if client and client.device_spec: + adjusted_start = start + client.device_spec.static_offset + if client.device_spec.sample_rate > 0: + count = round(seconds * client.device_spec.sample_rate) + logger.info( + f'Need {count} records for processing {name} data') + output[content_type] = client.get_data(start=adjusted_start, + limit=count) + data_count = len(output[content_type]) + if strict and data_count < count: + msg = f'Needed {count} {name} records but received {data_count}' + logger.error(msg) + raise InsufficientDataException(msg) + else: + # Markers have an IRREGULAR_RATE. + logger.info(f'Querying {name} data') + output[content_type] = client.get_data(start=adjusted_start, + end=adjusted_start + seconds) + logger.info( + f"Received {len(output[content_type])} records.") else: - # Markers have an IRREGULAR_RATE. - output[content_type] = client.get_data(start=adjusted_start, - end=adjusted_start + seconds) + logger.error( + f"No client and device spec found for content type: {content_type.name}") return output - def cleanup(self): - """Perform any cleanup tasks""" + def cleanup(self) -> None: # type: ignore + """Performs any necessary cleanup tasks for all managed clients.""" for client in self.clients: client.cleanup() def __getattr__(self, name: str) -> Any: - """Dispatch unknown properties and methods to the client with the - default content type.""" + """Dispatches unknown properties and methods to the client with the + default content type. + + This allows `ClientManager` to act as a proxy for the default client. + + Args: + name (str): The name of the attribute being accessed. + + Returns: + Any: The attribute from the default client. + + Raises: + AttributeError: If the default client is not set or the attribute + does not exist on the default client. + """ client = self.default_client if client: return client.__getattribute__(name) diff --git a/bcipy/acquisition/protocols/lsl/connect.py b/bcipy/acquisition/protocols/lsl/connect.py index 96e49ba35..097a76fc0 100644 --- a/bcipy/acquisition/protocols/lsl/connect.py +++ b/bcipy/acquisition/protocols/lsl/connect.py @@ -9,7 +9,24 @@ def resolve_device_stream( device_spec: Optional[DeviceSpec] = None) -> StreamInfo: - """Get the LSL stream for the given device.""" + """Resolves and returns the LSL stream for the given device. + + This function searches for an LSL stream based on the `content_type` of the + provided `DeviceSpec`. If no `DeviceSpec` is provided, it defaults to + `DEFAULT_DEVICE_TYPE`. + + Args: + device_spec (Optional[DeviceSpec], optional): The DeviceSpec object + containing the content type + of the stream to resolve. + Defaults to None. + + Returns: + StreamInfo: The resolved LSL `StreamInfo` object. + + Raises: + Exception: If an LSL stream with the specified content type is not found. + """ content_type = device_spec.content_type if device_spec else DEFAULT_DEVICE_TYPE streams = resolve_stream('type', content_type) if not streams: @@ -19,7 +36,14 @@ def resolve_device_stream( def device_from_metadata(metadata: StreamInfo) -> DeviceSpec: - """Create a device_spec from the data stream metadata.""" + """Creates a `DeviceSpec` object from LSL stream metadata. + + Args: + metadata (StreamInfo): The LSL `StreamInfo` object containing device metadata. + + Returns: + DeviceSpec: A `DeviceSpec` object populated with information from the metadata. + """ return DeviceSpec(name=metadata.name(), channels=channel_names(metadata), sample_rate=metadata.nominal_srate(), diff --git a/bcipy/acquisition/protocols/lsl/lsl_client.py b/bcipy/acquisition/protocols/lsl/lsl_client.py index 754a4d119..d0a14de81 100644 --- a/bcipy/acquisition/protocols/lsl/lsl_client.py +++ b/bcipy/acquisition/protocols/lsl/lsl_client.py @@ -1,7 +1,7 @@ """DataAcquisitionClient for LabStreamingLayer data sources.""" import logging from multiprocessing import Queue -from typing import Dict, List, Optional +from typing import Any, Dict, List, Optional import pandas as pd from pylsl import StreamInlet, local_clock, resolve_byprop @@ -25,7 +25,19 @@ def time_range(stamps: List[float], precision: int = 3, sep: str = " to ") -> str: - """Utility for printing a range of timestamps""" + """Utility for formatting a range of timestamps into a string. + + Args: + stamps (List[float]): A list of timestamps. + precision (int, optional): The number of decimal places for rounding timestamps. + Defaults to 3. + sep (str, optional): The separator string between the start and end timestamps. + Defaults to " to ". + + Returns: + str: A string representing the range of timestamps (e.g., "1.234 to 5.678"), + or an empty string if `stamps` is empty. + """ if stamps: return "".join([ str(round(stamps[0], precision)), sep, @@ -35,8 +47,17 @@ def time_range(stamps: List[float], def request_desc(start: Optional[float], end: Optional[float], - limit: Optional[int]): - """Returns a description of the request which can be logged.""" + limit: Optional[int]) -> str: + """Returns a descriptive string of a data request for logging purposes. + + Args: + start (Optional[float]): The starting timestamp of the request. + end (Optional[float]): The ending timestamp of the request. + limit (Optional[int]): The maximum number of records requested. + + Returns: + str: A formatted string describing the data request. + """ start_str = round(start, 3) if start else "None" end_str = round(end, 3) if end else "None" return f"Requesting data from: {start_str} to: {end_str} limit: {limit}" @@ -44,28 +65,35 @@ def request_desc(start: Optional[float], end: Optional[float], class LslAcquisitionClient: """Data Acquisition Client for devices streaming data using Lab Streaming - Layer. Its primary use is dynamically querying streaming data in realtime, - however, if the save_directory and filename parameters are provided it uses - a LslRecordingThread to persist the data. - - Parameters - ---------- - max_buffer_len: the maximum length of data to be queried. For continuously - streaming data this is the number of seconds of data to retain. For - irregular data, specify the number of samples. When using the RSVP - paradigm, the max_buffer_len should be large enough to store data for - the entire inquiry. - device_spec: spec for the device from which to query data; if missing, - this class will attempt to find the first EEG stream. - save_directory: if present, persists the data to the given location. - raw_data_file_name: if present, uses this name for the data file. + Layer. + + Its primary use is dynamically querying streaming data in realtime. + If `save_directory` and `filename` parameters are provided, it uses a + `LslRecordingThread` to persist the data. + + Args: + max_buffer_len (float, optional): The maximum length of data to be queried. + For continuously streaming data, this is the + number of seconds of data to retain. For + irregular data, it specifies the number of samples. + When using the RSVP paradigm, `max_buffer_len` + should be large enough to store data for the + entire inquiry. Defaults to 1. + device_spec (Optional[DeviceSpec], optional): The `DeviceSpec` for the device + from which to query data. + If missing, this class will attempt + to find the first EEG stream. Defaults to None. + save_directory (Optional[str], optional): If present, persists the data to + the given location. Defaults to None. + raw_data_file_name (Optional[str], optional): If present, uses this name + for the data file. Defaults to None. """ - inlet: StreamInlet = None - recorder: LslRecordingThread = None - buffer: RingBuffer = None - _first_sample_time: float = None - experiment_clock: Clock = None + inlet: Optional[StreamInlet] = None + recorder: Optional[LslRecordingThread] = None + buffer: Optional[RingBuffer] = None + _first_sample_time: Optional[float] = None + experiment_clock: Optional[Clock] = None def __init__(self, max_buffer_len: float = 1, @@ -74,35 +102,59 @@ def __init__(self, raw_data_file_name: Optional[str] = None): super().__init__() - self.device_spec = device_spec - self.max_buffer_len = max_buffer_len - self.save_directory = save_directory - self.raw_data_file_name = raw_data_file_name - self._max_samples = None + self.device_spec: Optional[DeviceSpec] = device_spec + self.max_buffer_len: float = max_buffer_len + self.save_directory: Optional[str] = save_directory + self.raw_data_file_name: Optional[str] = raw_data_file_name + self._max_samples: Optional[int] = None + + @property + def has_irregular_rate(self) -> bool: + """Checks if the device has an irregular sampling rate. + + Returns: + bool: True if the device's sample rate is `IRREGULAR_RATE`, + False otherwise. + """ + return self.device_spec.sample_rate == IRREGULAR_RATE # type: ignore @property - def first_sample_time(self) -> float: - """Timestamp returned by the first sample. If the data is being - recorded this value reflects the timestamp of the first recorded sample""" + def first_sample_time(self) -> Optional[float]: + """Returns the timestamp of the first sample. + + If data is being recorded, this value reflects the timestamp of the first + recorded sample. + + Returns: + Optional[float]: The timestamp of the first sample, or None if not set. + """ return self._first_sample_time @property def max_samples(self) -> int: - """Maximum number of samples available at any given time.""" + """Calculates the maximum number of samples available at any given time. + + This depends on `max_buffer_len` and the device's sample rate. + + Returns: + int: The maximum number of samples. + """ if self._max_samples is None: - if self.device_spec.sample_rate == IRREGULAR_RATE: + if self.has_irregular_rate: self._max_samples = int(self.max_buffer_len) else: self._max_samples = int(self.max_buffer_len * - self.device_spec.sample_rate) + self.device_spec.sample_rate) # type: ignore return self._max_samples def start_acquisition(self) -> bool: - """Connect to the datasource and start acquiring data. + """Connects to the data source and begins acquiring data. + + Initializes the LSL `StreamInlet` and optionally an `LslRecordingThread` + if a `save_directory` is provided. - Returns - ------- - bool : False if acquisition is already in progress, otherwise True. + Returns: + bool: False if acquisition is already in progress, otherwise True. """ if self.inlet: return False @@ -121,29 +173,38 @@ def start_acquisition(self) -> bool: self.device_spec = device_from_metadata(self.inlet.info()) if self.save_directory: - msg_queue = Queue() + msg_queue: Queue[float] = Queue() self.recorder = LslRecordingThread( directory=self.save_directory, filename=self.raw_data_file_name, device_spec=self.device_spec, queue=msg_queue) self.recorder.start() - logger.info("Waiting for first sample from lsl_recorder") - self._first_sample_time = msg_queue.get(block=True, - timeout=LSL_TIMEOUT) - logger.info(f"First sample time: {self.first_sample_time}") + if not self.has_irregular_rate: + logger.info("Waiting for first sample from lsl_recorder") + self._first_sample_time = msg_queue.get(block=True, + timeout=LSL_TIMEOUT) + logger.info(f"First sample time: {self.first_sample_time}") self.inlet.open_stream(timeout=LSL_TIMEOUT) if self.max_buffer_len and self.max_buffer_len > 0: self.buffer = RingBuffer(size_max=self.max_samples) if not self._first_sample_time: - _, self._first_sample_time = self.inlet.pull_sample() + timeout = 0.0 if self.has_irregular_rate else LSL_TIMEOUT + _, self._first_sample_time = self.inlet.pull_sample( + timeout=timeout) return True def stop_acquisition(self) -> None: - """Disconnect from the data source.""" - logger.info(f"Stopping Acquisition from {self.device_spec.name} ...") + """Disconnects from the data source and cleans up resources. + + Stops the `LslRecordingThread` if active, closes the LSL `StreamInlet`, + and clears the internal buffer. + """ + logger.info( + f"Stopping Acquisition from {self.device_spec.name} ...") # type: ignore if self.recorder: + # type: ignore logger.info(f"Closing {self.device_spec.name} data recorder") self.recorder.stop() self.recorder.join() @@ -155,29 +216,50 @@ def stop_acquisition(self) -> None: self.buffer = None - def __enter__(self): - """Context manager enter method that starts data acquisition.""" + def __enter__(self) -> 'LslAcquisitionClient': + """Context manager enter method that starts data acquisition. + + Returns: + LslAcquisitionClient: The instance of the acquisition client. + """ self.start_acquisition() return self - def __exit__(self, _exc_type, _exc_value, _traceback): - """Context manager exit method to clean up resources.""" + def __exit__(self, _exc_type: Any, _exc_value: Any, _traceback: Any) -> None: + """Context manager exit method to clean up resources. + + Args: + _exc_type (Any): The exception type, if an exception was raised. + _exc_value (Any): The exception value, if an exception was raised. + _traceback (Any): The traceback, if an exception was raised. + """ self.stop_acquisition() def _data_stats(self, data: List[Record]) -> Dict[str, float]: - """Summarize a list of records for logging and inspection.""" + """Summarizes a list of records for logging and inspection. + + Args: + data (List[Record]): A list of `Record` objects. + + Returns: + Dict[str, float]: A dictionary containing statistics such as count, + total seconds, start/end timestamps, expected difference, + mean difference, and max difference between samples. + Returns an empty dict if `data` is empty. + """ if data: diffs = pd.DataFrame(data)['timestamp'].diff() data_start = data[0].timestamp data_end = data[-1].timestamp precision = 3 + expected_diff = 0.0 if self.has_irregular_rate else round( + 1 / self.device_spec.sample_rate, precision) # type: ignore return { 'count': len(data), 'seconds': round(data_end - data_start, precision), 'from': round(data_start, precision), 'to': round(data_end, precision), - 'expected_diff': round(1 / self.device_spec.sample_rate, - precision), + 'expected_diff': expected_diff, 'mean_diff': round(diffs.mean(), precision), 'max_diff': round(diffs.max(), precision) } @@ -187,20 +269,28 @@ def get_data(self, start: Optional[float] = None, end: Optional[float] = None, limit: Optional[int] = None) -> List[Record]: - """Get data in time range. + """Retrieves data within a specified time range from the current buffer. - Only data in the current buffer is available to query; - requests for data outside of this will fail. + Only data currently in the buffer is available for querying. + Requests for data outside of this range will fail. - Parameters - ---------- - start : starting timestamp (acquisition clock). - end : end timestamp (in acquisition clock). - limit: the max number of records that should be returned. + Args: + start (Optional[float]): The starting timestamp (in acquisition clock). + Defaults to None, which means the beginning + of available data. + end (Optional[float]): The end timestamp (in acquisition clock). + Defaults to None, which means the end of + available data. + limit (Optional[int]): The maximum number of records to return. + Defaults to None, which means no limit. + + Returns: + List[Record]: A list of `Record` objects within the specified range. + Returns an empty list if no records are available. - Returns - ------- - List of Records + Raises: + AssertionError: If `start` or `end` times are out of the available data range + for regular rate devices. """ logger.info(request_desc(start, end, limit)) @@ -218,21 +308,27 @@ def get_data(self, if end is None: end = data_end - assert start >= data_start, 'Start time out of range' - assert end <= data_end, 'End time out of range' + if not self.has_irregular_rate: + assert start is not None and start >= data_start, 'Start time out of range' + assert end is not None and end <= data_end, 'End time out of range' data_slice = [ - record for record in data if start <= record.timestamp <= end + record for record in data if start <= record.timestamp <= end # type: ignore ][0:limit] logger.info(f"Filtered records: {self._data_stats(data_slice)}") return data_slice def get_latest_data(self) -> List[Record]: - """Add all available samples in the inlet to the buffer. + """Adds all currently available samples from the inlet to the buffer. The number of items returned depends on the size of the configured - max_buffer_len and the amount of data available in the inlet.""" + `max_buffer_len` and the amount of data available in the inlet. + + Returns: + List[Record]: A list of the latest `Record` objects from the buffer. + Returns an empty list if no buffer is initialized. + """ if not self.buffer: return [] @@ -244,76 +340,101 @@ def get_latest_data(self) -> List[Record]: return self.buffer.get() def _pull_chunk(self) -> int: - """Pull a chunk of samples from LSL and record in the buffer. - Returns the count of samples pulled. + """Pulls a chunk of samples from LSL and records them in the buffer. + + Returns: + int: The count of samples pulled in this operation. """ logger.debug(f"\tPulling chunk (max_samples: {self.max_samples})") # A timeout of 0.0 gets currently available samples without blocking. - samples, timestamps = self.inlet.pull_chunk( + samples, timestamps = self.inlet.pull_chunk( # type: ignore timeout=0.0, max_samples=self.max_samples) count = len(samples) - logger.debug(f"\t-> received {count} samples: {time_range(timestamps)}") + logger.debug( + f"\t-> received {count} samples: {time_range(timestamps)}") for sample, stamp in zip(samples, timestamps): - self.buffer.append(Record(sample, stamp)) + self.buffer.append(Record(sample, stamp)) # type: ignore return count def convert_time(self, experiment_clock: Clock, timestamp: float) -> float: - """ - Convert a timestamp from the experiment clock to the acquisition clock. + """Converts a timestamp from the experiment clock to the acquisition clock. + Used for querying the acquisition data for a time slice. - Parameters: - ---------- - - experiment_clock : clock used to generate the timestamp - - timestamp : timestamp from the experiment clock + Args: + experiment_clock (Clock): The clock used to generate the timestamp. + timestamp (float): The timestamp from the experiment clock. Returns: - -------- - corresponding timestamp for the acquistion clock + float: The corresponding timestamp for the acquisition clock. """ # experiment_time = pylsl.local_clock() - offset return timestamp + self.clock_offset(experiment_clock) def get_data_seconds(self, seconds: int) -> List[Record]: - """Returns the last n second of data""" + """Returns the last 'n' seconds of data available in the buffer. + + Args: + seconds (int): The number of seconds of data to retrieve. + + Returns: + List[Record]: A list of `Record` objects covering the last `seconds`. + + Raises: + AssertionError: If `seconds` exceeds `max_buffer_len`. + """ assert seconds <= self.max_buffer_len, f"Seconds can't exceed {self.max_buffer_len}" - sample_count = seconds * self.device_spec.sample_rate + sample_count = seconds * self.device_spec.sample_rate # type: ignore records = self.get_latest_data() start_index = 0 if len( records) > sample_count else len(records) - sample_count - return records[start_index:] + return records[int(start_index):] @property - def is_calibrated(self): - """Returns boolean indicating whether or not acquisition has been - calibrated (an offset calculated based on a trigger).""" + def is_calibrated(self) -> bool: + """Checks whether acquisition has been calibrated (an offset calculated based on a trigger). + + Returns: + bool: True, as this property is currently hardcoded to return True. + """ return True @is_calibrated.setter - def is_calibrated(self, bool_val): - """Setter for the is_calibrated property that allows the user to - override the calculated value and use a 0 offset. - - Parameters - ---------- - - bool_val : boolean - if True, uses a 0 offset; if False forces the calculation. + def is_calibrated(self, bool_val: bool) -> None: + """Setter for the `is_calibrated` property. + + Allows the user to override the calculated value and use a 0 offset. + + Args: + bool_val (bool): If True, forces a 0 offset; if False, forces the calculation. + Note: Current implementation always returns True for getter. """ + # This setter currently has no effect on the getter's return value. + pass def clock_offset(self, experiment_clock: Optional[Clock] = None) -> float: - """ - Offset in seconds from the experiment clock to the acquisition local clock. + """Calculates the offset in seconds from the experiment clock to the acquisition local clock. + + The experiment clock should be monotonic from experiment start time. The + acquisition clock (`pylsl.local_clock()`) is monotonic from local machine + start time (or since 1970-01-01 00:00). Therefore the acquisition clock + should always be greater than experiment clock. + + Args: + experiment_clock (Optional[Clock], optional): The experiment clock object. + Defaults to None, in which + case `self.experiment_clock` is used. - The experiment clock should be monotonic from experiment start time. - The acquisition clock (pylsl.local_clock()) is monotonic from local - machine start time (or since 1970-01-01 00:00). Therefore the acquisition - clock should always be greater than experiment clock. An exception is - raised if this doesn't hold. + Returns: + float: The offset in seconds. - See https://labstreaminglayer.readthedocs.io/info/faqs.html#lsl-local-clock + Raises: + AssertionError: If an experiment clock is not provided or available. + InvalidClockError: If the acquisition clock is not greater than the + experiment clock. """ clock = experiment_clock or self.experiment_clock assert clock, "An experiment clock must be provided" @@ -326,17 +447,14 @@ def clock_offset(self, experiment_clock: Optional[Clock] = None) -> float: return diff def event_offset(self, event_clock: Clock, event_time: float) -> float: - """Compute number of seconds that recording started prior to the given - event. + """Computes the number of seconds that recording started prior to the given event. - Parameters - ---------- - - event_clock : monotonic clock used to record the event time. - - event_time : timestamp of the event of interest. + Args: + event_clock (Clock): Monotonic clock used to record the event time. + event_time (float): Timestamp of the event of interest. - Returns - ------- - Seconds between acquisition start and the event. + Returns: + float: Seconds between acquisition start and the event, or 0.0 if `first_sample_time` is not set. """ if self.first_sample_time: lsl_event_time = self.convert_time(event_clock, event_time) @@ -344,33 +462,46 @@ def event_offset(self, event_clock: Clock, event_time: float) -> float: return 0.0 def offset(self, first_stim_time: float) -> float: - """Offset in seconds from the start of acquisition to the given stim - time. + """Calculates the offset in seconds from the start of acquisition to the given stimulus time. - Parameters - ---------- - - first_stim_time : LSL local clock timestamp of the first stimulus. + Args: + first_stim_time (float): LSL local clock timestamp of the first stimulus. - Returns - ------- - The number of seconds between acquisition start and the calibration - event, or 0.0 . - """ + Returns: + float: The number of seconds between acquisition start and the calibration + event, or 0.0 if `first_stim_time` is zero or `has_irregular_rate` is True. - if not first_stim_time: + Raises: + AssertionError: If `first_sample_time` is not set and `has_irregular_rate` is False. + """ + if not first_stim_time or self.has_irregular_rate: return 0.0 assert self.first_sample_time, "Acquisition was not started." offset_from_stim = first_stim_time - self.first_sample_time logger.info(f"Acquisition offset: {offset_from_stim}") return offset_from_stim - def cleanup(self): - """Perform any necessary cleanup.""" + def cleanup(self) -> None: + """Performs any necessary cleanup tasks. + + Currently, this method is a placeholder and does not perform any specific actions. + """ + pass def discover_device_spec(content_type: str) -> DeviceSpec: """Finds the first LSL stream with the given content type and creates a - device spec from the stream's metadata.""" + device spec from the stream's metadata. + + Args: + content_type (str): The content type of the LSL stream to discover (e.g., "EEG", "Markers"). + + Returns: + DeviceSpec: A `DeviceSpec` object created from the metadata of the discovered stream. + + Raises: + Exception: If an LSL stream with the specified content type is not found within `LSL_TIMEOUT`. + """ logger.info(f"Waiting for {content_type} data to be streamed over LSL.") streams = resolve_byprop('type', content_type, timeout=LSL_TIMEOUT) if not streams: diff --git a/bcipy/acquisition/protocols/lsl/lsl_connector.py b/bcipy/acquisition/protocols/lsl/lsl_connector.py index 31363db38..4c2002e8a 100644 --- a/bcipy/acquisition/protocols/lsl/lsl_connector.py +++ b/bcipy/acquisition/protocols/lsl/lsl_connector.py @@ -1,8 +1,7 @@ -# pylint: disable=fixme -"""Defines the driver for the Device for communicating with -LabStreamingLayer (LSL).""" +"""Defines the driver for the Device for communicating with LabStreamingLayer (LSL).""" + import logging -from typing import Dict, List +from typing import Any, Dict, List, Optional, Tuple import pylsl @@ -15,43 +14,84 @@ LSL_TIMEOUT_SECONDS = 5.0 -class Marker(): - """Data class which wraps a LSL marker; data pulled from a marker stream is - a tuple where the first item is a list of channels and second item is the - timestamp. Assumes that marker inlet only has a single channel.""" +class Marker: + """Data class which wraps an LSL marker. + + Data pulled from a marker stream is a tuple where the first item is a list + of channels (typically one) and the second item is the timestamp. + Assumes that the marker inlet only has a single channel. - def __init__(self, data=(None, None)): - super(Marker, self).__init__() - self.channels, self.timestamp = data + Args: + data (Tuple[Optional[List[Any]], Optional[float]], optional): A tuple + containing the channel data (list) and its timestamp (float). + Defaults to (None, None). + """ + + def __init__(self, data: Tuple[Optional[List[Any]], Optional[float]] = (None, None)): + super().__init__() + self.channels: Optional[List[Any]] = data[0] + self.timestamp: Optional[float] = data[1] @classmethod - def empty(cls): - """Creates an empty Marker.""" + def empty(cls) -> 'Marker': + """Creates an empty Marker instance. + + Returns: + Marker: An empty Marker object. + """ return Marker() - def __repr__(self): + def __repr__(self) -> str: + """Returns a string representation of the Marker object.""" return f"" @property - def is_empty(self): - """Test to see if the current marker is empty.""" + def is_empty(self) -> bool: + """Checks if the current marker is empty. + + Returns: + bool: True if both channels and timestamp are None, False otherwise. + """ return self.channels is None or self.timestamp is None @property - def trg(self): - """Get the trigger.""" + def trg(self) -> Optional[Any]: + """Gets the trigger value from the marker's channels. + + Assumes the trigger is the first element in the channels list. + + Returns: + Optional[Any]: The trigger value, or None if channels is empty or None. + """ # pylint: disable=unsubscriptable-object return self.channels[0] if self.channels else None -def inlet_name(inlet) -> str: - """Returns the name of a pylsl streamInlet.""" +def inlet_name(inlet: pylsl.StreamInlet) -> str: + """Returns a sanitized name of a pylsl `StreamInlet`. + + Converts the stream info name by replacing spaces and hyphens with underscores. + + Args: + inlet (pylsl.StreamInlet): The LSL StreamInlet object. + + Returns: + str: The sanitized name of the inlet. + """ name = '_'.join(inlet.info().name().split()) return name.replace('-', '_') def channel_names(stream_info: pylsl.StreamInfo) -> List[str]: - """Extracts the channel names from the LSL Stream metadata.""" + """Extracts the channel names from the LSL Stream metadata. + + Args: + stream_info (pylsl.StreamInfo): The LSL `StreamInfo` object. + + Returns: + List[str]: A list of channel names. If the stream type is 'Markers', + it returns `['Marker']`. + """ channels: List[str] = [] if stream_info.type() == 'Markers': return ['Marker'] @@ -67,9 +107,19 @@ def channel_names(stream_info: pylsl.StreamInfo) -> List[str]: return channels -def check_device(device_spec: DeviceSpec, metadata: pylsl.StreamInfo): - """Confirm that the properties of the given device_spec match the metadata - acquired from the device.""" +def check_device(device_spec: DeviceSpec, metadata: pylsl.StreamInfo) -> None: + """Confirms that the properties of the given `DeviceSpec` match the metadata + acquired from the LSL stream. + + Args: + device_spec (DeviceSpec): The expected `DeviceSpec` for the device. + metadata (pylsl.StreamInfo): The LSL `StreamInfo` object containing the + actual device metadata. + + Raises: + Exception: If channel names, channel count, or sample rate do not match + between `device_spec` and `metadata`. + """ channels = channel_names(metadata) # Confirm that provided channels match metadata, or meta is empty. if channels and device_spec.channel_names != channels: @@ -77,8 +127,7 @@ def check_device(device_spec: DeviceSpec, metadata: pylsl.StreamInfo): print(device_spec.channel_names) raise Exception("Channels read from the device do not match " "the provided parameters.") - assert device_spec.channel_count == metadata.channel_count( - ), "Channel count error" + assert device_spec.channel_count == metadata.channel_count(), "Channel count error" if device_spec.sample_rate != metadata.nominal_srate(): raise Exception("Sample frequency read from device does not match " @@ -86,11 +135,14 @@ def check_device(device_spec: DeviceSpec, metadata: pylsl.StreamInfo): def rename_items(items: List[str], rules: Dict[str, str]) -> None: - """Renames items based on the provided rules. - Parameters - ---------- - items - list of items ; values will be mutated - rules - change key -> value + """Renames items in a list based on a provided mapping of rules. + + The list of items is modified in place. + + Args: + items (List[str]): A list of strings whose values may be mutated. + rules (Dict[str, str]): A dictionary where keys are original item names + and values are their new names. """ for key, val in rules.items(): if key in items: diff --git a/bcipy/acquisition/protocols/lsl/lsl_recorder.py b/bcipy/acquisition/protocols/lsl/lsl_recorder.py index 75ddee170..f4e633f77 100644 --- a/bcipy/acquisition/protocols/lsl/lsl_recorder.py +++ b/bcipy/acquisition/protocols/lsl/lsl_recorder.py @@ -3,7 +3,7 @@ import time from multiprocessing import Queue from pathlib import Path -from typing import List, Optional +from typing import Any, List, Optional from pylsl import StreamInfo, StreamInlet, resolve_streams @@ -14,7 +14,8 @@ check_device) from bcipy.acquisition.util import StoppableProcess from bcipy.config import SESSION_LOG_FILENAME -from bcipy.helpers.raw_data import RawDataWriter +from bcipy.core.raw_data import RawDataWriter +from bcipy.helpers.utils import log_to_stdout log = logging.getLogger(SESSION_LOG_FILENAME) @@ -22,22 +23,30 @@ class LslRecorder: """Records LSL data to a datastore. Resolves streams when started. - Parameters: - ----------- - - path : location to store the recordings - - filenames : optional dict mapping device type to its raw data filename. - Devices without an entry will use a naming convention. + Args: + path (str): Location to store the recordings. + filenames (Optional[dict], optional): Optional dictionary mapping device + type to its raw data filename. + Devices without an entry will use a + naming convention. Defaults to None. """ - streams: List['LslRecordingThread'] = None + streams: Optional[List['LslRecordingThread']] = None def __init__(self, path: str, filenames: Optional[dict] = None) -> None: super().__init__() - self.path = path - self.filenames = filenames or {} + self.path: str = path + self.filenames: dict = filenames or {} def start(self) -> None: - """Start recording all streams currently on the network.""" + """Starts recording all LSL streams currently on the network. + + This method creates an `LslRecordingThread` for each discovered stream + and starts them. It also validates that stream names are unique. + + Raises: + Exception: If data stream names are not unique. + """ if not self.streams: log.info("Recording data") @@ -57,32 +66,40 @@ def start(self) -> None: stream.start() def stop(self, wait: bool = False) -> None: - """Stop recording. + """Stops recording for all active streams. - Parameters - ---------- - - wait : if True waits for all threads to stop before returning. + Args: + wait (bool, optional): If True, waits for all recording threads + to stop before returning. Defaults to False. """ - for stream in self.streams: - stream.stop() - if wait: - stream.join() - self.streams = None + if self.streams: + for stream in self.streams: + stream.stop() + if wait: + stream.join() + self.streams = None class LslRecordingThread(StoppableProcess): """Records data for the given LabStreamingLayer (LSL) data stream. - Parameters: - ---------- - - device_spec : DeviceSpec ; specifies the device from which to record. - - directory : location to store the recording - - filename : optional, name of the data file. - - queue : optional multiprocessing queue; if provided the first_sample_time - will be written here when available. + This class extends `StoppableProcess` to run recording in a separate process. + + Args: + device_spec (DeviceSpec): Specifies the device from which to record. + directory (Optional[str], optional): Location to store the recording. + Defaults to '.'. + filename (Optional[str], optional): Optional name of the data file. + If None, a default filename based + on device properties will be used. + Defaults to None. + queue (Optional[Queue], optional): Optional multiprocessing queue. + If provided, the `first_sample_time` + will be written to this queue when available. + Defaults to None. """ - writer: RawDataWriter = None + writer: Optional[RawDataWriter] = None def __init__(self, device_spec: DeviceSpec, @@ -91,30 +108,41 @@ def __init__(self, queue: Optional[Queue] = None) -> None: super().__init__() - self.directory = directory - self.device_spec = device_spec - self.queue = queue + self.directory: Optional[str] = directory + self.device_spec: DeviceSpec = device_spec + self.queue: Optional[Queue] = queue - self.sample_count = 0 + self.sample_count: int = 0 # see: https://labstreaminglayer.readthedocs.io/info/faqs.html#chunk-sizes - self.max_chunk_size = 1024 + self.max_chunk_size: int = 1024 # seconds to sleep between data pulls from LSL - self.sleep_seconds = 0.2 + self.sleep_seconds: float = 0.2 - self.filename = filename if filename else self.default_filename() - self.first_sample_time = None - self.last_sample_time = None + self.filename: str = filename if filename else self.default_filename() + self.first_sample_time: Optional[float] = None + self.last_sample_time: Optional[float] = None + + def default_filename(self) -> str: + """Generates a default filename to use if a name is not provided. + + The filename is based on the device's content type and name. - def default_filename(self): - """Default filename to use if a name is not provided.""" + Returns: + str: The generated default filename (e.g., "eeg_data_dsi_24.csv"). + """ content_type = '_'.join(self.device_spec.content_type.split()).lower() name = '_'.join(self.device_spec.name.split()).lower() return f"{content_type}_data_{name}.csv" @property def recorded_seconds(self) -> float: - """Total seconds of data recorded.""" + """Calculates the total seconds of data recorded. + + Returns: + float: The duration of recorded data in seconds, or 0.0 if recording + hasn't started or completed. + """ if self.first_sample_time and self.last_sample_time: return self.last_sample_time - self.first_sample_time return 0.0 @@ -122,9 +150,11 @@ def recorded_seconds(self) -> float: def _init_data_writer(self, stream_info: StreamInfo) -> None: """Initializes the raw data writer. - Parameters: - ---------- - - metadata : metadata about the data stream. + Args: + stream_info (StreamInfo): Metadata about the data stream. + + Raises: + AssertionError: If the data writer has already been initialized. """ assert self.writer is None, "Data store has already been initialized." @@ -134,7 +164,7 @@ def _init_data_writer(self, stream_info: StreamInfo) -> None: check_device(self.device_spec, stream_info) channels = self.device_spec.channels - path = str(Path(self.directory, self.filename)) + path = str(Path(self.directory, self.filename)) # type: ignore log.info(f"Writing data to {path}") self.writer = RawDataWriter( path, @@ -144,37 +174,38 @@ def _init_data_writer(self, stream_info: StreamInfo) -> None: self.writer.__enter__() def _cleanup(self) -> None: - """Performs cleanup tasks.""" + """Performs cleanup tasks for the data writer. + + Closes the `RawDataWriter` if it was initialized. + """ if self.writer: self.writer.__exit__() self.writer = None - def _write_chunk(self, data: List, timestamps: List) -> None: - """Persists the data resulting from pulling a chunk from the inlet. + def _write_chunk(self, data: List[List[Any]], timestamps: List[float]) -> None: + """Persists a chunk of data pulled from the LSL inlet. - Parameters - ---------- - data : list of samples - timestamps : list of timestamps + Args: + data (List[List[Any]]): A list of samples, where each sample is a list of channel values. + timestamps (List[float]): A list of timestamps corresponding to each sample. """ assert self.writer, "Writer not initialized" - chunk = [] + chunk: List[List[Any]] = [] for i, sample in enumerate(data): self.sample_count += 1 chunk.append([self.sample_count] + sample + [timestamps[i]]) self.writer.writerows(chunk) def _pull_chunk(self, inlet: StreamInlet) -> int: - """Pull a chunk of data and persist. Updates first_sample_time, - last_sample_time, and sample_count. + """Pulls a chunk of data from the `StreamInlet` and persists it. + + Updates `first_sample_time`, `last_sample_time`, and `sample_count`. - Parameters - ---------- - inlet : stream inlet from which to pull + Args: + inlet (StreamInlet): The LSL `StreamInlet` from which to pull data. - Returns - ------- - number of samples pulled + Returns: + int: The number of samples pulled in this operation. """ # A timeout of 0.0 does not block and only gets samples immediately # available. @@ -190,14 +221,20 @@ def _pull_chunk(self, inlet: StreamInlet) -> int: return len(timestamps) def _reset(self) -> None: - """Reset state""" + """Resets the internal state of the recorder. + + This includes resetting the sample count and clearing the first and last + sample timestamps. + """ self.sample_count = 0 self.first_sample_time = None self.last_sample_time = None # @override - def run(self): - """Process startup. Connects to the device, reads chunks of data at the + def run(self) -> None: + """Process startup and main recording loop. + + Connects to the device, continuously reads chunks of data at the given interval, and persists the results. This happens continuously until the `stop()` method is called. """ @@ -235,12 +272,20 @@ def run(self): self._cleanup() -def main(path: str, seconds: int = 5, debug: bool = False): - """Function to demo the LslRecorder. Expects LSL data streams to be already - running.""" +def main(path: str, seconds: int = 5, debug: bool = False) -> None: + """Demonstrates the `LslRecorder` functionality. + + This function initializes an `LslRecorder` and records data for a specified + duration. It expects LSL data streams to be already running. + + Args: + path (str): The directory path to save the recorded data. + seconds (int, optional): The duration in seconds to record data. + Defaults to 5. + debug (bool, optional): If True, enables logging to stdout for debugging. + Defaults to False. + """ if debug: - # pylint: disable=import-outside-toplevel - from bcipy.helpers.system_utils import log_to_stdout log_to_stdout() recorder = LslRecorder(path) print(f"\nCollecting data for {seconds}s...") diff --git a/bcipy/acquisition/record.py b/bcipy/acquisition/record.py index 8d93a5a9c..14b331264 100644 --- a/bcipy/acquisition/record.py +++ b/bcipy/acquisition/record.py @@ -4,9 +4,17 @@ class Record(NamedTuple): - """Domain object used for storing data and timestamp - information, where data is a single reading from a device and is a list - of channel information (float).""" + """Domain object used for storing data and timestamp information. + + The `data` attribute represents a single reading from a device and is a list + of channel information (typically float values). + + Attributes: + data (List[Any]): A list of values representing channel information from a device. + timestamp (float): The timestamp associated with the data recording. + rownum (Optional[int], optional): The row number of the record, if applicable. + Defaults to None. + """ data: List[Any] timestamp: float rownum: Optional[int] = None diff --git a/bcipy/acquisition/tests/datastream/test_generator.py b/bcipy/acquisition/tests/datastream/test_generator.py index a4469553c..035e0a9f2 100644 --- a/bcipy/acquisition/tests/datastream/test_generator.py +++ b/bcipy/acquisition/tests/datastream/test_generator.py @@ -1,10 +1,14 @@ # pylint: disable=too-few-public-methods,no-self-use """Tests for datastream generator module""" -from builtins import next import unittest -from past.builtins import map, range +from builtins import next + from mock import mock_open, patch -from bcipy.acquisition.datastream.generator import random_data_generator, file_data_generator, generator_with_args +from past.builtins import map, range + +from bcipy.acquisition.datastream.generator import (file_data_generator, + generator_with_args, + random_data_generator) from bcipy.acquisition.util import mock_data @@ -90,7 +94,8 @@ def test_file_generator_channel_count(self): with patch('bcipy.acquisition.datastream.generator.open', mock_open(read_data=test_data), create=True): - gen = file_data_generator(filename='foo', header_row=1, channel_count=2) + gen = file_data_generator( + filename='foo', header_row=1, channel_count=2) generated_data = [next(gen) for _ in range(row_count)] for i, row in enumerate(generated_data): @@ -159,7 +164,8 @@ def count_generator(low=0, high=10, step=1): self.assertEqual(1, next(gen2)) self.assertEqual(3, next(gen1)) - new_rand_gen = generator_with_args(random_data_generator, channel_count=10) + new_rand_gen = generator_with_args( + random_data_generator, channel_count=10) gen3 = new_rand_gen() data = next(gen3) self.assertEqual(10, len(data)) diff --git a/bcipy/acquisition/tests/protocols/lsl/test_lsl_recorder.py b/bcipy/acquisition/tests/protocols/lsl/test_lsl_recorder.py index e0649e3d2..06f77dfcb 100644 --- a/bcipy/acquisition/tests/protocols/lsl/test_lsl_recorder.py +++ b/bcipy/acquisition/tests/protocols/lsl/test_lsl_recorder.py @@ -1,18 +1,18 @@ """Tests for LslRecorder""" +import logging import tempfile import time import unittest from pathlib import Path import pytest -import logging from bcipy.acquisition.datastream.lsl_server import LslDataServer from bcipy.acquisition.datastream.mock.eye_tracker_server import \ eye_tracker_server from bcipy.acquisition.devices import preconfigured_device from bcipy.acquisition.protocols.lsl.lsl_recorder import LslRecorder -from bcipy.helpers.raw_data import TIMESTAMP_COLUMN, load +from bcipy.core.raw_data import TIMESTAMP_COLUMN, load log = logging.getLogger(__name__) diff --git a/bcipy/acquisition/tests/test_devices.py b/bcipy/acquisition/tests/test_devices.py index dc86980cd..0b63a0976 100644 --- a/bcipy/acquisition/tests/test_devices.py +++ b/bcipy/acquisition/tests/test_devices.py @@ -26,7 +26,7 @@ def test_default_supported_devices(self): dsi = supported['DSI-24'] self.assertEqual('EEG', dsi.content_type) - self.assertEqual(len(devices.with_content_type('EEG')), 4) + self.assertEqual(len(devices.with_content_type('EEG')), 5) def test_load_from_config(self): """Should be able to load a list of supported devices from a @@ -142,7 +142,7 @@ def test_device_spec_defaults(self): """DeviceSpec should require minimal information with default values.""" spec = devices.DeviceSpec(name='TestDevice', channels=['C1', 'C2', 'C3'], - sample_rate=256.0) + sample_rate=256) self.assertEqual(3, spec.channel_count) self.assertEqual('EEG', spec.content_type) self.assertEqual(devices.DeviceStatus.ACTIVE, spec.status) @@ -151,7 +151,7 @@ def test_device_spec_analysis_channels(self): """DeviceSpec should have a list of channels used for analysis.""" spec = devices.DeviceSpec(name='TestDevice', channels=['C1', 'C2', 'C3', 'TRG'], - sample_rate=256.0, + sample_rate=256, excluded_from_analysis=['TRG']) self.assertEqual(['C1', 'C2', 'C3'], spec.analysis_channels) @@ -160,7 +160,7 @@ def test_device_spec_analysis_channels(self): spec2 = devices.DeviceSpec(name='Device2', channels=['C1', 'C2', 'C3', 'TRG'], - sample_rate=256.0, + sample_rate=256, excluded_from_analysis=['C1', 'TRG']) self.assertEqual(['C2', 'C3'], spec2.analysis_channels) @@ -178,7 +178,7 @@ def test_device_spec_analysis_channels(self): 'name': 'C4', 'label': 'TRG' }], - sample_rate=256.0, + sample_rate=256, excluded_from_analysis=['ch1', 'TRG']) self.assertEqual(['ch2', 'ch3'], spec3.analysis_channels) @@ -192,7 +192,7 @@ def test_irregular_sample_rate(self): with self.assertRaises(AssertionError): devices.DeviceSpec(name='Mouse', channels=['Btn1', 'Btn2'], - sample_rate=-100.0, + sample_rate=-100, content_type='Markers') def test_data_type(self): @@ -239,7 +239,7 @@ def test_device_spec_to_dict(self): 'type': None, 'units': None }] - sample_rate = 256.0 + sample_rate = 256 content_type = 'EEG' spec = devices.DeviceSpec(name=device_name, channels=channels, @@ -290,7 +290,7 @@ def test_load_static_offset(self): content_type="EEG", description="My Device", channels=["a", "b", "c"], - sample_rate=100.0, + sample_rate=100, status=str(devices.DeviceStatus.PASSIVE), static_offset=offset) ] diff --git a/bcipy/acquisition/util.py b/bcipy/acquisition/util.py index 15472c23d..1e909dee2 100644 --- a/bcipy/acquisition/util.py +++ b/bcipy/acquisition/util.py @@ -1,6 +1,7 @@ """Defines utility classes and functions used by the acquisition module.""" import multiprocessing import threading + import numpy as np diff --git a/bcipy/config.py b/bcipy/config.py index 9325e2447..ec31fd991 100644 --- a/bcipy/config.py +++ b/bcipy/config.py @@ -6,7 +6,8 @@ from pathlib import Path DEFAULT_ENCODING = 'utf-8' -DEFAULT_EVIDENCE_PRECISION = 5 # number of decimal places to round evidence to by default +# number of decimal places to round evidence to by default +DEFAULT_EVIDENCE_PRECISION = 5 MARKER_STREAM_NAME = 'TRG_device_stream' DEFAULT_TRIGGER_CHANNEL_NAME = 'TRG' DIODE_TRIGGER = '\u25A0' @@ -25,7 +26,7 @@ DEFAULT_EXPERIMENT_PATH = f'{BCIPY_ROOT}/parameters/experiment' DEFAULT_FIELD_PATH = f'{BCIPY_ROOT}/parameters/field' DEFAULT_USER_ID = 'test_user' -TASK_SEPERATOR = '->' +TASK_SEPARATOR = '->' DEFAULT_PARAMETERS_FILENAME = 'parameters.json' DEFAULT_DEVICES_PATH = f"{BCIPY_ROOT}/parameters" diff --git a/bcipy/core/README.md b/bcipy/core/README.md new file mode 100644 index 000000000..ea6af701c --- /dev/null +++ b/bcipy/core/README.md @@ -0,0 +1,167 @@ +# BciPy Core Module + +Core data strucutres and methods needed for BciPy operation. These include triggers, parameters, and raw data. + +## Contents + +- `list`: utility methods for list processing +- `parameters`: module for functionality related to system configuration via the parameters.json file +- `raw_data`: functionality for reading and writing raw signal data +- `report`: methods for generating BciPy PDF reports +- `session`: methods for managing and parsing session.json data +- `stimuli`: methods for generating stimuli and inquiries for presentation +- `symbols`: methods for working with symbols and symbol lists. Ex. Alphabet, QWERTY, etc. +- `triggers`: methods and data classes defining BciPy internal triggering + + +## Triggers + +Triggers consist of a label, type and a timestamp. These are what is used to align events both in real-time and after a session for further processing or model training. During operation of a BciPy task, Triggers are generated when display or other events of interest occur. These are timestamped using a monotonic clock (See helpers/clock.py). + +A new Trigger may defined as follows: +```python +from bcipy.core.triggers import Trigger, TriggerType + +# label can be any utf-8 compliant string +nontarget_trigger = Trigger('nontarget_label', TriggerType.NONTARGET, 1.0111) +``` + +### Trigger Types + +The supported internal trigger types are as follows: + +```python +NONTARGET = "nontarget" +TARGET = "target" +FIXATION = "fixation" +PROMPT = "prompt" +SYSTEM = "system" +OFFSET = "offset" +EVENT = "event" +PREVIEW = "preview" +``` + +### TriggerHandler + +You can use the BciPy TriggerHandler to read and write any Triggers! + +### Writing + +You will need three pieces of information to create a new handler for writing: + +1. path where trigger data should be written +2. name of the trigger file without extension +3. a defined FlushFrequency. This sets how often the handler should write the data. Incrementally (FlushFrequency.EVERY) or at session end (FlushFrequency.END). + +```python +from bcipy.core.triggers import TriggerHandler, FlushFrequency + +path_to_trigger_save_location = '.' +trigger_file_name = 'triggers' # BciPy will add the correct extension. Currently, .txt is used. +flush = FlushFrequency.END + +handler = TriggerHandler(path_to_trigger_save_location, trigger_file_name, flush) + +triggers = [ + Trigger('test_trigger', TriggerType.SYSTEM, 1.0111), + Trigger('target', TriggerType.TARGET, 2), + Trigger('nontarget', TriggerType.NONTARGET, 3), +] + +handler.add_triggers(triggers) +handler.close() # this will call write one final time on any triggers added since last flush +``` + + +### Loading + +To load a BciPy triggers.txt file, the TriggerHandler load method can be used. Because it is a staticmethod, the class does not need to be initialized before the load method is used. + +```python +from bcipy.core.triggers import TriggerHandler + +path_to_trigger_save_location = './triggers.txt' + +triggers = TriggerHandler.load(path_to_trigger_save_location) +# it will load in data like this: +# [Trigger: label=[starting_offset] type=[offset] time=[-13149613.488788936], Trigger: label=[x] type=[prompt] time=[4.96745322458446]] +``` + +Alternately, you can pass offset and exclusion as keyword arguments to modify the behavior of `TriggerHandler.load`. Offset will add time to every timestamp loaded. Use this to correct any static system offsets! The default value for offset is 0.0. Exclusions can be used to pre-filter any unwanted Triggers, such as SYSTEM. + +```python +from bcipy.core.triggers import TriggerHandler + +path_to_trigger_save_location = './triggers.txt' + +# exclude system triggers +triggers = TriggerHandler.load(path_to_trigger_save_location, exclusion=[TriggerType.SYSTEM]) + +# apply a 2 second offset to all timestamps loaded +triggers = TriggerHandler.load(path_to_trigger_save_location, offset=2.0) +``` + +### Trigger File Format + +Triggers as written from BciPy tasks are assumed to have the following structure, + +1. A single trigger is written per line with three columns (label type timestamp). +2. If a clock offset is present and subsequent triggers should be corrected, it may be written with the trigger type `offset`. The value of that Trigger will be added to any timestamp values written in the file. When using various clocks that don't start at zero, this can be used to align the data to similar t=0. If time should be subtracted, write a negative value as demonstrated below for both offset values. BciPy will only apply the first instance of offset, but will return all Triggers and the additional offsets may be applied as desired. In the example below, only starting_offset would be applied to all other triggers; another_offset would be returned. +3. Only a valid TriggerType may be read. + +``` +starting_offset offset -3421.2852307 +another_offset offset -2 +N prompt 3490.3607581 ++ fixation 3491.3668763 +Y nontarget 3491.8722132 +P nontarget 3492.0780858 +J nontarget 3492.2839911 +F nontarget 3492.4900032 +D nontarget 3492.6959695 +K nontarget 3492.9021379 +X nontarget 3493.1079959 +< nontarget 3493.3139829 +M nontarget 3493.5198677 +N target 3493.7257014 +X prompt 3495.4642608 ++ fixation 3496.4697921 +Z nontarget 3496.9749562 +``` + +### Multiple Devices + +When multiple devices are in use, each device should provide its own starting_offset trigger. The trigger time should be the timestamp associated with the first sample in the data for that device. + +```python +from bcipy.core.triggers import Trigger, TriggerType, offset_label + +# label can be any utf-8 compliant string +eeg_offset = Trigger(offset_label(device_type='EEG'), TriggerType.OFFSET, -3400.0) +eyetracker_offset = Trigger(offset_label(device_type='EYETRACKER'), TriggerType.OFFSET, -3450.0) +``` + +After adding other triggers, the resulting file will look something like: + +``` +starting_offset offset -3400.0 +starting_offset_EYETRACKER offset -3450.0 +N prompt 3490.3607581 ++ fixation 3491.3668763 +Y nontarget 3491.8722132 +... +``` + +Triggers can then be loaded with timestamps relative to a device's start. + +```python +from bcipy.core.triggers import trigger_decoder, TriggerType + +types, times, labels = trigger_decoder('triggers.txt', device_type='EEG') +# types == ['prompt', 'fixation', 'prompt'] +# times == [90.36075810000011, 91.36687630000006, 91.8722131999998] +# labels == ['N', '+', 'Y'] + +_, times, _ = trigger_decoder('triggers.txt', device_type='EYETRACKER') +# times == [40.36075810000011, 41.36687630000006, 41.872213199999806] +``` diff --git a/bcipy/core/__init__.py b/bcipy/core/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/bcipy/helpers/demo/demo_report.py b/bcipy/core/demo/demo_report.py similarity index 82% rename from bcipy/helpers/demo/demo_report.py rename to bcipy/core/demo/demo_report.py index 1ee4ff363..b4dfe46dc 100644 --- a/bcipy/helpers/demo/demo_report.py +++ b/bcipy/core/demo/demo_report.py @@ -1,20 +1,17 @@ from pathlib import Path -from bcipy.helpers.load import load_json_parameters, load_raw_data, load_experimental_data -from bcipy.helpers.triggers import trigger_decoder, TriggerType -from bcipy.config import ( - BCIPY_ROOT, - DEFAULT_PARAMETERS_FILENAME, - RAW_DATA_FILENAME, - TRIGGER_FILENAME, - DEFAULT_DEVICE_SPEC_FILENAME) from bcipy.acquisition import devices +from bcipy.config import (BCIPY_ROOT, DEFAULT_DEVICE_SPEC_FILENAME, + DEFAULT_PARAMETERS_FILENAME, RAW_DATA_FILENAME, + TRIGGER_FILENAME) +from bcipy.core.report import Report, SessionReportSection, SignalReportSection +from bcipy.core.triggers import TriggerType, trigger_decoder from bcipy.helpers.acquisition import analysis_channels from bcipy.helpers.visualization import visualize_erp -from bcipy.signal.process import get_default_transform +from bcipy.io.load import (load_experimental_data, load_json_parameters, + load_raw_data) from bcipy.signal.evaluate.artifact import ArtifactDetection -from bcipy.helpers.report import Report, SignalReportSection, SessionReportSection - +from bcipy.signal.process import get_default_transform if __name__ == "__main__": import argparse @@ -31,7 +28,10 @@ # if no path is provided, prompt for one using a GUI path = args.path if not path: - path = load_experimental_data() + path = load_experimental_data( + message="Select the folder containing the raw_data.csv, parameters.json and triggers.txt", + strict=True + ) trial_window = (0, 1.0) @@ -40,14 +40,16 @@ # loop through the sessions, pausing after each one to allow for manual stopping if session.is_dir(): print(f'Processing {session}') - prompt = input('Hit enter to continue or type "skip" to skip processing: ') + prompt = input( + 'Hit enter to continue or type "skip" to skip processing: ') if prompt != 'skip': # load the parameters from the data directory parameters = load_json_parameters( f'{session}/{DEFAULT_PARAMETERS_FILENAME}', value_cast=True) # load the raw data from the data directory - raw_data = load_raw_data(Path(session, f'{RAW_DATA_FILENAME}.csv')) + raw_data = load_raw_data( + Path(session, f'{RAW_DATA_FILENAME}.csv')) type_amp = raw_data.daq_type channels = raw_data.channels sample_rate = raw_data.sample_rate @@ -72,7 +74,8 @@ trigger_type, trigger_timing, trigger_label = trigger_decoder( offset=parameters.get('static_trigger_offset'), trigger_path=f"{session}/{TRIGGER_FILENAME}", - exclusion=[TriggerType.PREVIEW, TriggerType.EVENT, TriggerType.FIXATION], + exclusion=[TriggerType.PREVIEW, + TriggerType.EVENT, TriggerType.FIXATION], ) triggers = (trigger_type, trigger_timing, trigger_label) else: diff --git a/bcipy/helpers/demo/demo_session_tools.py b/bcipy/core/demo/demo_session_tools.py similarity index 85% rename from bcipy/helpers/demo/demo_session_tools.py rename to bcipy/core/demo/demo_session_tools.py index e9711fe57..daa09f337 100644 --- a/bcipy/helpers/demo/demo_session_tools.py +++ b/bcipy/core/demo/demo_session_tools.py @@ -4,9 +4,9 @@ from pathlib import Path from bcipy.config import SESSION_DATA_FILENAME, SESSION_SUMMARY_FILENAME +from bcipy.core.session import (read_session, session_csv, session_data, + session_db, session_excel) from bcipy.gui.file_dialog import ask_directory -from bcipy.helpers.session import (read_session, session_csv, session_data, - session_db, session_excel) def main(data_dir: str): @@ -39,7 +39,7 @@ def main(data_dir: str): args = parser.parse_args() path = args.path if not path: - path = ask_directory() + path = ask_directory(strict=True) if args.db or args.csv or args.charts: session = read_session(Path(path, SESSION_DATA_FILENAME)) @@ -48,6 +48,7 @@ def main(data_dir: str): if args.csv: session_csv(session, csv_file=str(Path(path, "session.csv"))) if args.charts: - session_excel(session, excel_file=str(Path(path, SESSION_SUMMARY_FILENAME))) + session_excel(session, excel_file=str( + Path(path, SESSION_SUMMARY_FILENAME))) else: main(path) diff --git a/bcipy/helpers/demo/demo_stimuli_generation.py b/bcipy/core/demo/demo_stimuli_generation.py similarity index 96% rename from bcipy/helpers/demo/demo_stimuli_generation.py rename to bcipy/core/demo/demo_stimuli_generation.py index 0518fb206..1ed8c3648 100644 --- a/bcipy/helpers/demo/demo_stimuli_generation.py +++ b/bcipy/core/demo/demo_stimuli_generation.py @@ -1,6 +1,8 @@ -from bcipy.helpers.stimuli import StimuliOrder, generate_calibration_inquiries, best_case_rsvp_inq_gen import numpy as np +from bcipy.core.stimuli import (StimuliOrder, best_case_rsvp_inq_gen, + generate_calibration_inquiries) + def _demo_random_rsvp_inquiry_generator(): alp = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'J', 'K', 'L', 'M', 'N', diff --git a/bcipy/core/list.py b/bcipy/core/list.py new file mode 100644 index 000000000..8bfeae51a --- /dev/null +++ b/bcipy/core/list.py @@ -0,0 +1,144 @@ +"""Utility functions for list processing.""" +from itertools import zip_longest +from typing import Any, Callable, Iterator, List, Optional, Tuple, Union + + +def destutter(items: List[Any], key: Callable = lambda x: x) -> List: + """Removes sequential duplicates from a list. Retains the last item in the + sequence. + + Equality is determined using the provided key function. + + Args: + items (List[Any]): List of items with sequential duplicates. + key (Callable, optional): Equality function. Defaults to `lambda x: x`. + + Returns: + List: A new list with sequential duplicates removed. + """ + deduped: List[Any] = [] + for item in items: + if len(deduped) == 0 or key(item) != key(deduped[-1]): + deduped.append(item) + else: + deduped[-1] = item + return deduped + + +def grouper(iterable: Any, chunk_size: int, incomplete: str = "fill", + fillvalue: Optional[Any] = None) -> Union[Iterator[Tuple], Iterator[Any]]: + """Collect data into non-overlapping fixed-length chunks or blocks. + + Args: + iterable (Any): The iterable to group. + chunk_size (int): The size of each chunk. + incomplete (str, optional): Strategy for incomplete chunks. Can be "fill" or "ignore". + Defaults to "fill". + fillvalue (Optional[Any], optional): Value to fill incomplete chunks with if `incomplete` is "fill". + Defaults to None. + + Returns: + Union[Iterator[Tuple], Iterator[Any]]: An iterator yielding chunks. + + Raises: + ValueError: If `fillvalue` is not defined when `incomplete` is "fill", or if `incomplete` + is neither "fill" nor "ignore". + + Examples: + grouper('ABCDEFG', 3, fillvalue='x') --> ABC DEF Gxx + grouper('ABCDEFG', 3, incomplete='ignore') --> ABC DEF + """ + chunks = [iter(iterable)] * chunk_size + if incomplete == "fill": + if fillvalue: + return zip_longest(*chunks, fillvalue=fillvalue) + raise ValueError('fillvalue must be defined if using incomplete=fill') + if incomplete == "ignore": + return zip(*chunks) + + raise ValueError("Expected fill or ignore") + + +def find_index(iterable: List, + match_item: Union[Any, Callable], + key: Callable = lambda x: x) -> Optional[int]: + """Find the index of the first item in the iterable which matches. + + Args: + iterable (List): The list to search through. + match_item (Union[Any, Callable]): The item to match or a callable to apply to each item. + key (Callable, optional): A function to apply to each item before comparison. Defaults to `lambda x: x`. + + Returns: + Optional[int]: The index of the first matching item, or None if no match is found. + """ + for i, value in enumerate(iterable): + if callable(match_item): + result = match_item(value) + else: + result = key(value) == match_item + if result: + return i + return None + + +def swapped(lst: List[Any], index1: int, index2: int) -> List[Any]: + """Creates a copy of the provided list with elements at the given indices swapped. + + Args: + lst (List[Any]): The original list. + index1 (int): The index of the first element to swap. + index2 (int): The index of the second element to swap. + + Returns: + List[Any]: A new list with the elements at `index1` and `index2` swapped. + """ + replacements = {index1: lst[index2], index2: lst[index1]} + return [replacements.get(i, val) for i, val in enumerate(lst)] + + +def expanded(lst: List[Any], + length: int, + fill: Union[Any, Callable] = lambda x: x[-1]) -> List[Any]: + """Creates a copy of the provided list expanded to the given length. + + By default, the last item is used as the fill item. + + Args: + lst (List[Any]): List of items to copy. + length (int): The target length to expand the list to. + fill (Union[Any, Callable], optional): Used to determine which element to use for + the fill, given the list. Defaults to the last element. + + Returns: + List[Any]: The expanded list. + + Examples: + >>> expanded([1,2,3], length=5) + [1,2,3,3,3] + """ + times = length - len(lst) + if lst and times > 0: + item = fill(lst) if callable(fill) else fill + return lst + ([item] * times) + return lst + + +def pairwise(iterable: Any) -> Iterator[Tuple]: + """Returns an iterator over overlapping pairs from the input iterable. + + Args: + iterable (Any): The iterable to process. + + Yields: + Tuple: A tuple containing two consecutive elements from the iterable. + + Examples: + pairwise('ABCDEFG') → AB BC CD DE EF FG + https://docs.python.org/3/library/itertools.html#itertools.pairwise + """ + iterator = iter(iterable) + a = next(iterator, None) + for b in iterator: + yield a, b + a = b diff --git a/bcipy/core/parameters.py b/bcipy/core/parameters.py new file mode 100644 index 000000000..230b66960 --- /dev/null +++ b/bcipy/core/parameters.py @@ -0,0 +1,481 @@ +"""Module for functionality related to system configuration""" +from codecs import open as codecsopen +from collections import abc +from json import dump, load +from pathlib import Path +from re import fullmatch +from typing import Any, Dict, List, NamedTuple, Optional, Tuple, Union + +from bcipy.config import DEFAULT_ENCODING, DEFAULT_PARAMETERS_PATH + + +class Parameter(NamedTuple): + """Represents a single parameter." + + Attributes: + value (Any): The value of the parameter. + section (str): The section the parameter belongs to. + name (str): The display name of the parameter. + helpTip (str): A helpful tip or description for the parameter. + recommended (list): Recommended values for the parameter. + editable (bool): Whether the parameter is editable. + type (str): The data type of the parameter (e.g., 'int', 'float', 'bool', 'str', 'range'). + """ + value: Any + section: str + name: str + helpTip: str + recommended: list + editable: bool + type: str + + +class ParameterChange(NamedTuple): + """Represents a Parameter that has been modified from a different value." + + Attributes: + parameter (Parameter): The modified parameter. + original_value (Any): The original value of the parameter before modification. + """ + parameter: Union[Parameter, dict] + original_value: Any + + +def parse_range(range_str: str) -> Tuple[Union[int, float], Union[int, float]]: + """Parses the range description into a tuple of (low, high). + + If either value can be parsed as a float, the resulting tuple will have + float values; otherwise, they will be integers. + + Args: + range_str (str): Range description formatted as 'low:high'. + + Returns: + Tuple[Union[int, float], Union[int, float]]: A tuple containing the low and high values of the range. + + Raises: + AssertionError: If the `range_str` is not in the format 'low:high' or if the low value is not less than the high value. + + Examples: + >>> parse_range("1:10") + (1, 10) + """ + assert ':' in range_str, "Invalid range format; values must be separated by ':'" + low_str, high_str = range_str.split(':') + int_pattern = "-?\\d+" + if fullmatch(int_pattern, low_str) and fullmatch(int_pattern, high_str): + low: Union[int, float] = int(low_str) + high: Union[int, float] = int(high_str) + else: + low = float(low_str) + high = float(high_str) + + assert low < high, "Low value must be less that the high value" + return (low, high) + + +def serialize_value(value_type: str, value: Any) -> str: + """Serializes the given value to a string. + + Serialized values should be able to be cast using the `conversions` dictionary + defined in the `Parameters` class. + + Args: + value_type (str): The declared type of the value (e.g., 'bool', 'range'). + value (Any): The value to serialize. + + Returns: + str: The serialized string representation of the value. + """ + if value_type == 'bool': + return str(value).lower() + if value_type == 'range': + low, high = value + return f"{low}:{high}" + return str(value) + + +class Parameters(dict): + """Configuration parameters for BciPy. + + This class extends `dict` to provide type-casting and validation for + configuration parameters, typically loaded from a JSON file. + + Args: + source (Optional[str], optional): Optional path to a JSON file. If the file exists, + data will be loaded from here. Raises an exception unless the entries are + dictionaries with the required keys. Defaults to None. + cast_values (bool, optional): If True, values will be cast to their specified type + when accessed. Defaults to False. + """ + + def __init__(self, source: Optional[str] = None, cast_values: bool = False): + super().__init__() + self.source = source + self.cast_values = cast_values + + self.required_keys = set(Parameter._fields) + self.conversions = { + 'int': int, + 'float': float, + 'bool': lambda val: val == 'true' or val is True, + 'str': str, + 'directorypath': str, + 'filepath': str, + 'range': parse_range + } + self.load_from_source() + + @classmethod + def from_cast_values(cls, **kwargs: Any) -> 'Parameters': + """Creates a new `Parameters` object from cast values. + + This is useful primarily for testing. + + Args: + **kwargs (Any): Keyword arguments representing parameter names and their values. + + Returns: + Parameters: A new `Parameters` instance with values cast. + + Examples: + >>> Parameters.from_cast_values(time_prompt=1.0, fake_data=True) + """ + params = Parameters(source=None, cast_values=True) + for key, val in kwargs.items(): + value_type = type(val).__name__ + # Convert tuple to range + if value_type == 'tuple': + value_type = 'range' + value_str = serialize_value(value_type, val) + params.add_entry( + key, { + 'value': value_str, + 'section': '', + 'name': '', + 'helpTip': '', + 'recommended': '', + 'editable': '', + 'type': value_type + }) + return params + + @property + def supported_types(self) -> list: + """Returns the set of supported types for casting values.""" + return list(self.conversions.keys()) + + def cast_value(self, entry: Dict[str, Any]) -> Any: + """Takes an entry with a desired type and attempts to cast it to that type. + + Args: + entry (Dict[str, Any]): A dictionary representing a parameter entry with a 'type' key. + + Returns: + Any: The value cast to the specified type. + """ + cast = self.conversions[entry['type']] + return cast(entry['value']) # type: ignore + + def serialized_value(self, value: Any, entry_type: str) -> str: + """Converts a value back into its serialized string form." + + Args: + value (Any): The value to serialize. + entry_type (str): The declared type of the value. + + Returns: + str: The serialized string representation of the value. + """ + serialized = str(value) + return serialized.lower() if entry_type == 'bool' else serialized + + def __getitem__(self, key: str) -> Any: + """Overrides dictionary item access to handle cast values." + + Args: + key (str): The key of the parameter to retrieve. + + Returns: + Any: The cast value of the parameter if `cast_values` is True, otherwise the raw entry dictionary. + """ + entry = self.get_entry(key) + if self.cast_values: + return self.cast_value(entry) + return entry + + def __setitem__(self, key: str, value: Any) -> None: + """Overrides dictionary item assignment to handle cast values and validate entries." + + If `cast_values` is True, it attempts to set the serialized value for an existing entry. + Otherwise, it adds a new entry after validation. + + Args: + key (str): The key of the parameter to set. + value (Any): The value to set for the parameter. + """ + if self.cast_values: + # Can only set values for existing entries when cast. + entry = self.get_entry(key) + entry['value'] = self.serialized_value(value, entry['type']) + else: + self.add_entry(key, value) + + def add_entry(self, key: str, value: Dict[str, Any]) -> None: + """Adds a configuration parameter after validating its format." + + Args: + key (str): The name of the configuration parameter. + value (Dict[str, Any]): A dictionary containing the parameter properties. + """ + self.check_valid_entry(key, value) + super().__setitem__(key, value) + + def get_entry(self, key: str) -> Dict[str, Any]: + """Gets the non-cast entry associated with the given key." + + Args: + key (str): The key of the parameter entry to retrieve. + + Returns: + Dict[str, Any]: The raw dictionary entry for the parameter. + """ + return super().__getitem__(key) + + def get(self, key: str, d: Optional[Any] = None) -> Any: + """Overrides dictionary `get` method to handle cast values." + + Args: + key (str): The key of the parameter to retrieve. + d (Optional[Any], optional): Default value to return if the key is not found. + Defaults to None. + + Returns: + Any: The cast value of the parameter if `cast_values` is True and the key is found, + otherwise the raw entry or the default value. + """ + entry = super().get(key, d) + if self.cast_values and entry != d: + return self.cast_value(entry) + return entry + + def entries(self) -> List[Tuple[str, Dict[str, Any]]]: + """Returns the uncast items (key-value pairs) of the parameters. + + Returns: + List[Tuple[str, Dict[str, Any]]]: A list of key-value tuples, where values are raw entry dictionaries. + """ + return list(super().items()) # type: ignore + + def items(self) -> List[Tuple[str, Any]]: # type: ignore + """Overrides dictionary `items` method to handle cast values. + + Returns: + List[Tuple[str, Any]]: A list of key-value tuples, where values are cast if `cast_values` is True. + """ + if self.cast_values: + return [(key, self.cast_value(entry)) + for key, entry in self.entries()] + return self.entries() + + def values(self) -> List[Any]: # type: ignore + """Override to handle cast values. + + Returns: + List[Any]: A list of parameter values, cast if `cast_values` is True. + """ + vals = super().values() + if self.cast_values: + return [self.cast_value(entry) for entry in vals] + return list(vals) # type: ignore + + def update(self, *args: Any, **kwargs: Any) -> None: + """Overrides dictionary `update` method to ensure `__setitem__` is used for each item." + + Args: + *args (Any): Positional arguments for dictionary update. + **kwargs (Any): Keyword arguments for dictionary update. + """ + for key, value in dict(*args, **kwargs).items(): + self[key] = value + + def copy(self) -> 'Parameters': + """Creates a shallow copy of the `Parameters` object." + + Returns: + Parameters: A new `Parameters` instance with the same parameters. + """ + params = Parameters(source=None, cast_values=self.cast_values) + params.load(super().copy()) # type: ignore + return params + + def load(self, data: Dict[str, Dict[str, Any]]) -> None: + """Loads values from a dictionary, validating entries and raising an exception for invalid values." + + Args: + data (Dict[str, Dict[str, Any]]): A dictionary of configuration parameters. + """ + for name, entry in data.items(): + self.add_entry(name, entry) + + def load_from_source(self) -> None: + """Loads data from the configured JSON file." + + If `self.source` is set, it attempts to open and load the JSON data from that path. + """ + if self.source: + with codecsopen(self.source, 'r', + encoding=DEFAULT_ENCODING) as json_file: + data = load(json_file) + self.load(data) # type: ignore + + def check_valid_entry(self, entry_name: str, entry: Dict[str, Any]) -> None: + """Checks if the given entry is valid. Raises an exception unless the entry is formatted as expected." + + Expected format: + ```json + "fake_data": { + "value": "true", + "section": "bci_config", + "name": "Fake Data Sessions", + "helpTip": "If true, fake data server used", + "recommended": "", + "editable": true, + "type": "bool" + } + ``` + + Args: + entry_name (str): Name of the configuration parameter. + entry (Dict[str, Any]): Parameter properties. + + Raises: + AttributeError: If `entry` is not a dictionary. + Exception: If `entry` does not contain required keys, if the 'type' is not supported, + or if the 'value' for a 'bool' type is invalid. + """ + if not isinstance(entry, abc.Mapping): + raise AttributeError(f"'{entry_name}' value must be a dict") + if set(entry.keys()) != self.required_keys: + raise Exception( + f"Incorrect format for key: {entry_name}; value must contain required keys" + ) + if entry['type'] not in self.supported_types: + raise Exception( + f"Type not supported for key: {entry_name}, type: {entry['type']}" + ) + if entry['type'] == "bool" and entry['value'] not in ['true', 'false']: + raise Exception( + f"Invalid value for key: {entry_name}. Must be either 'true' or 'false'" + ) + + def source_location(self) -> Tuple[Optional[Path], Optional[str]]: + """Returns the location of the source JSON data if a source was provided." + + Returns: + Tuple[Optional[Path], Optional[str]]: A tuple containing the parent directory path and the filename. + """ + if self.source: + path = Path(self.source) + return (path.parent, path.name) + return (None, None) + + def save(self, directory: Optional[str] = None, name: Optional[str] = None) -> str: + """Saves parameters to the given location." + + Args: + directory (Optional[str], optional): Optional location to save the file. Defaults to the source directory. + name (Optional[str], optional): Optional name of the new parameters file. Defaults to the source filename. + + Returns: + str: The path of the saved file. + + Raises: + AttributeError: If neither `directory` and `name` are provided nor a `source` path is set. + """ + if (not directory or not name) and not self.source: + raise AttributeError('name and directory parameters are required') + + source_directory, source_name = self.source_location() + location = directory if directory else source_directory + filename = name if name else source_name + path = Path(location, filename) # type: ignore + with open(path, 'w', encoding=DEFAULT_ENCODING) as json_file: + dump(dict(self.entries()), json_file, + ensure_ascii=False, indent=2) # type: ignore + return str(path) + + def add_missing_items(self, parameters: 'Parameters') -> bool: + """Given another `Parameters` instance, adds any items that are not already present. + + Existing items will not be updated. + + Args: + parameters (Parameters): Object from which to add parameters. + + Returns: + bool: True if any new items were added, False otherwise. + """ + updated = False + existing_keys = self.keys() + for key, val in parameters.entries(): + if key not in existing_keys: + self.add_entry(key, val) + updated = True + return updated + + def diff(self, parameters: 'Parameters') -> Dict[str, ParameterChange]: + """Lists the differences between this and another set of parameters. + A None original_value indicates a new parameter. + + Args: + parameters (Parameters): Set of parameters for comparison; these + are considered the original values and the current set the + changed values. + + Returns: + Dict[str, ParameterChange]: A dictionary where keys are parameter names + and values are ParameterChange objects. + """ + diffs: Dict[str, ParameterChange] = {} + + for key, param in self.entries(): + if key in parameters.keys(): + original = parameters.get_entry(key) + if self.cast_value(original) != self.cast_value(param): + diffs[key] = ParameterChange( + parameter=param, original_value=original['value']) + else: + diffs[key] = ParameterChange(parameter=param, + original_value=None) + return diffs + + def instantiate(self, named_tuple_class: type[NamedTuple]) -> NamedTuple: + """Instantiates a `NamedTuple` whose fields represent a subset of the parameters." + + Args: + named_tuple_class (type[NamedTuple]): The `NamedTuple` class to instantiate. + + Returns: + NamedTuple: An instance of the provided `NamedTuple` class with values populated from parameters. + """ + vals = [ + self.cast_value(self.get_entry(key)) + for key in named_tuple_class._fields + ] + return named_tuple_class(*vals) + + +def changes_from_default(source: str) -> Dict[str, ParameterChange]: + """Determines which parameters have changed from the default parameters. + + Args: + source (str): Path to the parameters JSON file that will be compared with + the default parameters. + + Returns: + Dict[str, ParameterChange]: A dictionary of `ParameterChange` objects representing the differences. + """ + default = Parameters(source=DEFAULT_PARAMETERS_PATH, cast_values=True) + params = Parameters(source=source, cast_values=True) + return params.diff(default) diff --git a/bcipy/core/raw_data.py b/bcipy/core/raw_data.py new file mode 100644 index 000000000..6a05e2da6 --- /dev/null +++ b/bcipy/core/raw_data.py @@ -0,0 +1,581 @@ +"""Functionality for reading and writing raw signal data.""" +import csv +from io import TextIOWrapper +from typing import Any, List, Optional, TextIO, Tuple, Union + +import numpy as np +import pandas as pd + +from bcipy.config import DEFAULT_ENCODING +from bcipy.exceptions import BciPyCoreException +from bcipy.signal.generator.generator import gen_random_data +from bcipy.signal.process import Composition + +TIMESTAMP_COLUMN = 'timestamp' + + +class RawData: + """Represents the raw data format used by BciPy. + + This class is used primarily for loading a raw data file into memory. It provides + methods to access and manipulate the data in various formats. + + Attributes: + daq_type (str): Type of data acquisition device. + sample_rate (int): Sample rate in Hz. + columns (List[str]): List of column names in the data. + """ + + def __init__(self, daq_type: str, sample_rate: int, columns: List[str]) -> None: + """Initialize RawData. + + Args: + daq_type (str): Type of data acquisition device. + sample_rate (int): Sample rate in Hz. + columns (List[str]): List of column names in the data. + """ + self.daq_type = daq_type + self.sample_rate = sample_rate + self.columns = columns + + self._dataframe: Optional[pd.DataFrame] = None + self._rows: List[Any] = [] + + @classmethod + def load(cls, filename: str) -> 'RawData': + """Constructs a RawData object by deserializing the given file. + + All data will be read into memory. If you want to lazily read data one + record at a time, use a RawDataReader. + + Args: + filename (str): Path to the csv file to read. + + Returns: + RawData: A new RawData instance containing the loaded data. + """ + return load(filename) + + @property + def rows(self) -> List[List]: + """Returns the data rows. + + Returns: + List[List]: List of data rows. + """ + return self._rows + + @rows.setter + def rows(self, value: Any) -> None: + """Sets the data rows and invalidates the cached dataframe. + + Args: + value (Any): New data rows to set. + """ + self._rows = value + self._dataframe = None + + @property + def channels(self) -> List[str]: + """Compute the list of channels. + + Channels are the numeric columns excluding the timestamp column. + + Returns: + List[str]: List of channel names. + """ + # Start data slice at 1 to remove the timestamp column. + return list(self.numeric_data.columns[1:]) + + @property + def numeric_data(self) -> pd.DataFrame: + """Data for columns with numeric data. + + This is usually comprised of the timestamp column and device channels, + excluding string triggers. + + Returns: + pd.DataFrame: DataFrame containing only numeric columns. + """ + return self.dataframe.select_dtypes(exclude=['object']) + + @property + def channel_data(self) -> np.ndarray: + """Data for columns with numeric data, excluding the timestamp column. + + Returns: + np.ndarray: Array of channel data with shape (channels, samples). + """ + numeric_data = self.numeric_data + + numeric_vals = numeric_data.values + numeric_column_count = numeric_vals.shape[1] + # Start data slice at 1 to remove the timestamp column. + return numeric_vals[:, 1:numeric_column_count].transpose() + + def by_channel(self, transform: Optional[Composition] = None) -> Tuple[np.ndarray, int]: + """Data organized by channel. + + Optionally, it can apply a BciPy Composition to the data before returning using the transform arg. + This will apply n tranformations to the data before returning. For an example Composition with + EEG preprocessing, see bcipy.signal.get_default_transform(). + + Args: + transform (Optional[Composition]): Optional transformation to apply to the data. + + Returns: + Tuple[np.ndarray, int]: A tuple containing: + - data: C x N numpy array with samples where C is the number of channels and N + is number of time samples + - fs: resulting sample rate if any transformations applied + """ + data = self.channel_data + fs = self.sample_rate + + if transform: + data, fs = self.apply_transform(data, transform) + + return data, fs + + def by_channel_map( + self, + channel_map: List[int], + transform: Optional[Composition] = None) -> Tuple[np.ndarray, List[str], int]: + """Returns channels with columns removed if index in list (channel_map) is zero. + + The channel map must align with the numeric channels read in as self.channels. + We assume most trigger or other string columns are removed, however some are + numeric trigger columns from devices that will require filtering before returning + data. Other cases could be dropping bad channels before running further analyses. + + Args: + channel_map (List[int]): List of 1s and 0s indicating which channels to keep. + transform (Optional[Composition]): Optional transformation to apply to the data. + + Returns: + Tuple[np.ndarray, List[str], int]: A tuple containing: + - data: Array of channel data with shape (channels, samples) + - channels: List of channel names + - fs: Sample rate + """ + data, fs = self.by_channel(transform) + channels_to_remove = [idx for idx, + value in enumerate(channel_map) if value == 0] + data = np.delete(data, channels_to_remove, axis=0) + channels: List[str] = np.delete( + self.channels, channels_to_remove, axis=0).tolist() + + return data, channels, fs + + def apply_transform(self, data: np.ndarray, transform: Composition) -> Tuple[np.ndarray, int]: + """Apply Transform. + + Using data provided as an np.ndarray, call the Composition with self.sample_rate to apply + transformations to the data. This will return the transformed data and resulting sample rate. + + Args: + data (np.ndarray): Input data to transform. + transform (Composition): Transformation to apply. + + Returns: + Tuple[np.ndarray, int]: A tuple containing: + - data: Transformed data + - fs: Resulting sample rate + """ + return transform(data, self.sample_rate) + + @property + def dataframe(self) -> pd.DataFrame: + """Returns a dataframe of the row data. + + Returns: + pd.DataFrame: DataFrame containing all data. + """ + if self._dataframe is None: + self._dataframe = pd.DataFrame(data=self.rows, + columns=self.columns) + return self._dataframe + + @property + def total_seconds(self) -> float: + """Total recorded seconds. + + Defined as the diff between the first and last timestamp. + + Returns: + float: Total duration in seconds. + """ + frame = self.dataframe + col = 'lsl_timestamp' + return frame.iloc[-1][col] - frame.iloc[0][col] + + @property + def total_samples(self) -> int: + """Number of samples recorded. + + Returns: + int: Total number of samples. + """ + return int(self.dataframe.iloc[-1]['timestamp']) + + def query(self, + start: Optional[float] = None, + stop: Optional[float] = None, + column: str = 'lsl_timestamp') -> pd.DataFrame: + """Query for a subset of data. + + Args: + start (Optional[float]): Find records greater than or equal to this value. + stop (Optional[float]): Find records less than or equal to this value. + column (str): Column to compare to the given start and stop values. + + Returns: + pd.DataFrame: DataFrame for the given slice of data. + """ + dataframe = self.dataframe + start = start or dataframe.iloc[0][column] + stop = stop or dataframe.iloc[-1][column] + mask = (dataframe[column] >= start) & (dataframe[column] <= stop) + return dataframe[mask] + + def append(self, row: list) -> None: + """Append the given row of data. + + Args: + row (list): Row of data to append. + """ + assert len(row) == len(self.columns), "Wrong number of columns" + self._rows.append(row) + self._dataframe = None + + def __str__(self) -> str: + """String representation of RawData. + + Returns: + str: String representation. + """ + return f"RawData({self.daq_type})" + + def __repr__(self) -> str: + """String representation of RawData. + + Returns: + str: String representation. + """ + return f"RawData({self.daq_type})" + + +def maybe_float(val: Any) -> Union[float, Any]: + """Attempt to convert the given value to float. + + If conversion fails return the value as is. + + Args: + val (Any): Value to convert to float. + + Returns: + Union[float, Any]: Float if conversion succeeds, original value otherwise. + """ + try: + return float(val) + except ValueError: + return val + + +class RawDataReader: + """Lazily reads raw data from a file. + + Intended to be used as a ContextManager using Python's `with` keyword. + + Example usage: + ``` + with RawDataReader(path) as reader: + print(f"Data from ${reader.daq_type}") + print(reader.columns) + for row in reader: + print(row) + ``` + + Attributes: + file_path (str): Path to the csv file. + convert_data (bool): If True attempts to convert data values to floats. + daq_type (str): Type of data acquisition device. + sample_rate (int): Sample rate in Hz. + columns (List[str]): List of column names. + """ + _file_obj: TextIOWrapper + + def __init__(self, file_path: str, convert_data: bool = False): + """Initialize RawDataReader. + + Args: + file_path (str): Path to the csv file. + convert_data (bool, optional): If True attempts to convert data values to floats. + Defaults to False. + """ + self.file_path = file_path + self.convert_data = convert_data + + def __enter__(self) -> 'RawDataReader': + """Enter the context manager. + + Returns: + RawDataReader: Self. + """ + self._file_obj = open(self.file_path, mode="r", + encoding=DEFAULT_ENCODING) + self.daq_type, self.sample_rate = read_metadata(self._file_obj) + self._reader = csv.reader(self._file_obj) + self.columns = next(self._reader) + return self + + def __exit__(self, *args, **kwargs) -> None: + """Exit the context manager. Close resources.""" + if self._file_obj: + self._file_obj.close() + + def __iter__(self) -> 'RawDataReader': + """Return self as iterator. + + Returns: + RawDataReader: Self. + """ + return self + + def __next__(self) -> List[Any]: + """Get next row of data. + + Returns: + List[Any]: Next row of data. + + Raises: + AssertionError: If reader is not initialized. + """ + assert self._reader, "Reader must be initialized" + row = next(self._reader) + if self.convert_data: + return list(map(maybe_float, row)) + return row + + +class RawDataWriter: + """Writes a raw data file one row at a time without storing the records in memory. + + Intended to be used as a ContextManager using Python's `with` keyword. + + Example usage: + ``` + with RawDataWriter(path, daq_type, sample_rate, columns) as writer: + for row in data: + writer.writerow(row) + ``` + + Attributes: + file_path (str): Path to the csv file. + daq_type (str): Name of device. + sample_rate (float): Sample frequency in Hz. + columns (List[str]): List of column names. + """ + _file_obj: TextIOWrapper + + def __init__(self, file_path: str, daq_type: str, sample_rate: float, + columns: List[str]) -> None: + """Initialize RawDataWriter. + + Args: + file_path (str): Path to the csv file. + daq_type (str): Name of device. + sample_rate (float): Sample frequency in Hz. + columns (List[str]): List of column names. + """ + self.file_path = file_path + self.daq_type = daq_type + self.sample_rate = sample_rate + self.columns = columns + + def __enter__(self) -> 'RawDataWriter': + """Enter the context manager. Initializes the underlying data file. + + Returns: + RawDataWriter: Self. + """ + self._file_obj = open(self.file_path, + mode='w', + encoding=DEFAULT_ENCODING, + newline='') + # write metadata + self._file_obj.write(f"daq_type,{self.daq_type}\n") + self._file_obj.write(f"sample_rate,{self.sample_rate}\n") + + # If flush is missing the previous content may be appended at the end. + self._file_obj.flush() + + self._csv_writer = csv.writer(self._file_obj, delimiter=',') + self._csv_writer.writerow(self.columns) + + return self + + def __exit__(self, *args, **kwargs) -> None: + """Exit the context manager. Close resources.""" + self._file_obj.close() + + def writerow(self, row: List) -> None: + """Write a single row of data. + + Args: + row (List): Row of data to write. + + Raises: + AssertionError: If writer is not initialized or row has wrong number of columns. + """ + assert self._csv_writer, "Writer must be initialized" + assert len(row) == len(self.columns), "Wrong number of columns" + self._csv_writer.writerow(row) + + def writerows(self, rows: List[List]) -> None: + """Write multiple rows of data. + + Args: + rows (List[List]): Rows of data to write. + """ + for row in rows: + self.writerow(row) + + +def load(filename: str) -> RawData: + """Reads the file at the given path and initializes a RawData object. + + All data will be read into memory. If you want to lazily read data one + record at a time, use a RawDataReader. + + Args: + filename (str): Path to the csv file to read. + + Returns: + RawData: A new RawData instance containing the loaded data. + + Raises: + BciPyCoreException: If the file is not found. + """ + # Loading all data from a csv is faster using pandas than using the + # RawDataReader. + try: + with open(filename, mode='r', encoding=DEFAULT_ENCODING) as file_obj: + daq_type, sample_rate = read_metadata(file_obj) + dataframe = pd.read_csv(file_obj) + data = RawData(daq_type, sample_rate, list(dataframe.columns)) + data.rows = dataframe.values.tolist() + return data + except FileNotFoundError: + raise BciPyCoreException( + f"\nError loading BciPy RawData. Valid data not found at: {filename}") + + +def read_metadata(file_obj: TextIO) -> Tuple[str, int]: + """Reads the metadata from an open raw data file and returns the result as a tuple. + + Increments the reader. + + Args: + file_obj (TextIO): Open TextIO object. + + Returns: + Tuple[str, int]: Tuple of (daq_type, sample_rate). + """ + daq_type = next(file_obj).strip().split(',')[1] + sample_rate = int(float(next(file_obj).strip().split(",")[1])) + return daq_type, sample_rate + + +def write(data: RawData, filename: str) -> None: + """Write the given raw data file. + + Args: + data (RawData): Raw data object to write. + filename (str): Path to destination file. + """ + with RawDataWriter(filename, data.daq_type, data.sample_rate, + data.columns) as writer: + for row in data.rows: + writer.writerow(row) + + +def settings(filename: str) -> Tuple[str, float, List[str]]: + """Read the daq settings from the given data file. + + Args: + filename (str): Path to the raw data file (csv). + + Returns: + Tuple[str, float, List[str]]: Tuple of (acquisition type, sample_rate, columns). + """ + with RawDataReader(filename) as reader: + return reader.daq_type, reader.sample_rate, reader.columns + + +def sample_data(rows: int = 1000, + ch_names: List[str] = ['ch1', 'ch2', 'ch3'], + daq_type: str = 'SampleDevice', + sample_rate: int = 256, + triggers: List[Tuple[float, str]] = []) -> RawData: + """Creates sample data to be written as a raw_data.csv file. + + The resulting data has a column for the timestamp, one for each channel, + and a TRG column. + + Args: + rows (int, optional): Number of sample rows to generate. Defaults to 1000. + ch_names (List[str], optional): List of channel names. Defaults to ['ch1', 'ch2', 'ch3']. + daq_type (str, optional): Metadata for the device name. Defaults to 'SampleDevice'. + sample_rate (int, optional): Device sample rate in hz. Defaults to 256. + triggers (List[Tuple[float, str]], optional): List of (timestamp, trigger_value) tuples + to be inserted in the data. Defaults to []. + + Returns: + RawData: A new RawData instance containing the sample data. + """ + channels = [name for name in ch_names if name != 'TRG'] + columns = [TIMESTAMP_COLUMN] + channels + ['TRG'] + trg_times = dict(triggers) + + data = RawData(daq_type, sample_rate, columns) + + for i in range(rows): + timestamp = i + 1 + channel_data = gen_random_data(low=-1000, + high=1000, + channel_count=len(channels)) + trg = trg_times.get(timestamp, '0.0') + data.append([timestamp] + channel_data + [trg]) + + return data + + +def get_1020_channels() -> List[str]: + """Returns the standard 10-20 channel names. + + Note: The 10-20 system is a standard for EEG electrode placement. The following + is not a complete list of all possible channels, but the most common ones used + in BCI research. This excludes the reference and ground channels. + + Returns: + List[str]: List of channel names. + """ + return [ + 'Fp1', 'Fp2', 'F7', 'F3', 'Fz', 'F4', 'F8', 'T3', 'C3', 'Cz', 'C4', + 'T4', 'T5', 'P3', 'Pz', 'P4', 'T6', 'O1', 'O2', 'PO7', 'PO3', 'POz', + 'PO4', 'PO8', 'Oz', 'A1', 'A2', + ] + + +def get_1020_channel_map(channels_name: List[str]) -> List[int]: + """Returns a list of 1s and 0s indicating if the channel name is in the 10-20 system. + + Args: + channels_name (List[str]): List of channel names. + + Returns: + List[int]: List of 1s and 0s indicating if the channel name is in the 10-20 system. + """ + valid_channels = get_1020_channels() + return [1 if name in valid_channels else 0 for name in channels_name] diff --git a/bcipy/helpers/report.py b/bcipy/core/report.py similarity index 55% rename from bcipy/helpers/report.py rename to bcipy/core/report.py index 774e7ea8e..25e9e7c4f 100644 --- a/bcipy/helpers/report.py +++ b/bcipy/core/report.py @@ -1,51 +1,73 @@ # mypy: disable-error-code="union-attr" import io from abc import ABC -from typing import List, Optional, Tuple +from typing import Any, Dict, List, Optional, Tuple from matplotlib import pyplot as plt - from matplotlib.figure import Figure -from reportlab.platypus import SimpleDocTemplate, Paragraph, Image from reportlab.lib.pagesizes import letter from reportlab.lib.styles import getSampleStyleSheet -from reportlab.platypus import Flowable, KeepTogether from reportlab.lib.units import inch +from reportlab.platypus import (Flowable, Image, KeepTogether, Paragraph, + SimpleDocTemplate) from bcipy.config import BCIPY_FULL_LOGO_PATH from bcipy.signal.evaluate.artifact import ArtifactDetection class ReportSection(ABC): - """Report Section. + """Abstract base class for report sections in BciPy. - An abstract class to handle the creation of a section in a BciPy Report. + This class defines the interface for creating sections in a BciPy Report. + All report sections must implement the `compile` method to generate their content. """ def compile(self) -> Flowable: - """Compile. + """Compile the section into a flowable for the report. + + This method must be implemented by child classes. It is intended to be called + during final report build, not immediately after class initialization. - This method must be implemented by the child class. - It is intented to be called on final Report build, - as opposed to immediatley after class initiatlization, - to compile the section into a usuable flowable for a Report. + Returns: + Flowable: A reportlab flowable object containing the section's content. """ ... def _create_header(self) -> Flowable: + """Create the header for the section. + + Returns: + Flowable: A reportlab flowable object containing the section header. + """ ... class SignalReportSection(ReportSection): - """Signal Report Section. + """Section for displaying signal analysis results in a BciPy Report. + + This section can include signal figures and artifact detection results. - A class to handle the creation of a Signal Report section in a BciPy Report. + Attributes: + figures (List[Figure]): List of matplotlib figures to include in the report. + report_flowables (List[Flowable]): List of reportlab flowables for the section. + artifact (Optional[ArtifactDetection]): Optional artifact detection results. + style: Reportlab style sheet for formatting. """ def __init__( self, figures: List[Figure], artifact: Optional[ArtifactDetection] = None) -> None: + """Initialize SignalReportSection. + + Args: + figures (List[Figure]): List of matplotlib figures to include. + artifact (Optional[ArtifactDetection], optional): Artifact detection results. + Defaults to None. + + Raises: + AssertionError: If artifact is provided but analysis is not complete. + """ self.figures = figures self.report_flowables: List[Flowable] = [] self.artifact = artifact @@ -56,9 +78,10 @@ def __init__( self.style = getSampleStyleSheet() def compile(self) -> Flowable: - """Compile. + """Compile the signal report section into a flowable. - Compiles the Signal Report sections into a flowable that can be used to generate a Report. + Returns: + Flowable: A reportlab flowable containing the compiled section. """ self.report_flowables.append(self._create_header()) if self.artifact: @@ -68,9 +91,10 @@ def compile(self) -> Flowable: return KeepTogether(self.report_flowables) def _create_artifact_section(self) -> Flowable: - """Create Artifact Section. + """Create a section displaying artifact detection results. - Creates a paragraph with the artifact information. This is only included if an artifact detection is provided. + Returns: + Flowable: A reportlab flowable containing artifact information and visualizations. """ artifact_report = [] artifacts_detected = self.artifact.dropped @@ -92,7 +116,8 @@ def _create_artifact_section(self) -> Flowable: if self.artifact.voltage_annotations: voltage_artifacts = f'Voltage Artifacts: {len(self.artifact.voltage_annotations)}' - voltage_section = Paragraph(voltage_artifacts, self.style['BodyText']) + voltage_section = Paragraph( + voltage_artifacts, self.style['BodyText']) artifact_report.append(voltage_section) # create a heatmap with the onset values of the voltage artifacts @@ -105,9 +130,15 @@ def _create_artifact_section(self) -> Flowable: return KeepTogether(artifact_report) def _create_heatmap(self, onsets: List[float], range: Tuple[float, float], type: str) -> Image: - """Create Heatmap. + """Create a heatmap visualization of artifact onsets. - Creates a heatmap image with the onset values of the voltage artifacts. + Args: + onsets (List[float]): List of artifact onset times. + range (Tuple[float, float]): Time range for the heatmap. + type (str): Type of artifact being visualized. + + Returns: + Image: A reportlab Image containing the heatmap. """ # create a heatmap with the onset values fig, ax = plt.subplots() @@ -121,19 +152,23 @@ def _create_heatmap(self, onsets: List[float], range: Tuple[float, float], type: return heatmap def _create_epochs_section(self) -> List[Image]: - """Create Epochs Section. + """Create a section containing all signal figures. - Creates a flowable image for each figure in the Signal Report. + Returns: + List[Image]: List of reportlab Images containing the signal figures. """ # create a flowable for each figure flowables = [self.convert_figure_to_image(fig) for fig in self.figures] return flowables def convert_figure_to_image(self, fig: Figure) -> Image: - """Convert Figure to Image. + """Convert a matplotlib figure to a reportlab Image. + + Args: + fig (Figure): Matplotlib figure to convert. - Converts a matplotlib figure to a reportlab Image. - retrieved from: https://nicd.org.uk/knowledge-hub/creating-pdf-reports-with-reportlab-and-pandas + Returns: + Image: A reportlab Image containing the figure. """ buf = io.BytesIO() fig.savefig(buf, format='png', dpi=300) @@ -142,42 +177,54 @@ def convert_figure_to_image(self, fig: Figure) -> Image: return Image(buf, x * inch, y * inch) def _create_header(self) -> Paragraph: - """Create Header. + """Create the header for the signal report section. - Creates a header for the Signal Report section. + Returns: + Paragraph: A reportlab Paragraph containing the section header. """ header = Paragraph('Signal Report', self.style['Heading3']) return header class SessionReportSection(ReportSection): - """Session Report Section. + """Section for displaying session summary information in a BciPy Report. - A class to handle the creation of a Session Report section in a BciPy Report using a summary dictionary. + Attributes: + summary (dict): Dictionary containing session summary information. + session_name (str): Name of the session or default name if not specified. + style: Reportlab style sheet for formatting. + summary_table (Optional[Flowable]): The compiled summary table. """ - def __init__(self, summary: dict) -> None: + def __init__(self, summary: Dict[str, Any]) -> None: + """Initialize SessionReportSection. + + Args: + summary (Dict[str, Any]): Dictionary containing session summary information. + """ self.summary = summary if 'task' in self.summary: self.session_name = self.summary['task'] else: self.session_name = 'Session Summary' self.style = getSampleStyleSheet() - self.summary_table = None + self.summary_table: Optional[Flowable] = None def compile(self) -> Flowable: - """Compile. + """Compile the session report section into a flowable. - Compiles the Session Report sections into a flowable that can be used to generate a Report. + Returns: + Flowable: A reportlab flowable containing the compiled section. """ summary_table = self._create_summary_flowable() self.summary_table = summary_table return summary_table def _create_summary_flowable(self) -> Flowable: - """Create Summary Flowable. + """Create a flowable containing the session summary. - Creates a flowable table with the summary dictionary. + Returns: + Flowable: A reportlab flowable containing the formatted summary. """ if self.summary: # split the summary keys and values into a list @@ -190,10 +237,15 @@ def _create_summary_flowable(self) -> Flowable: summary_list = self._create_summary_text(keys, values) return KeepTogether(summary_list) - def _create_summary_text(self, keys: list, values: list) -> List[Paragraph]: - """Create Summary Text. + def _create_summary_text(self, keys: List[str], values: List[Any]) -> List[Paragraph]: + """Create formatted text for the summary. + + Args: + keys (List[str]): List of summary keys. + values (List[Any]): List of summary values. - Creates a list of paragraphs with the keys and values from the provided summary. + Returns: + List[Paragraph]: List of reportlab Paragraphs containing the formatted summary. """ # create a table with the keys and values, adding a header table = [self._create_header()] @@ -203,18 +255,31 @@ def _create_summary_text(self, keys: list, values: list) -> List[Paragraph]: return table def _create_header(self) -> Paragraph: - """Create Header. + """Create the header for the session report section. - Creates a header for the Session Report section. + Returns: + Paragraph: A reportlab Paragraph containing the section header. """ - header = Paragraph(f'{self.session_name}', self.style['Heading3']) + header = Paragraph( + f'{self.session_name}', self.style['Heading3']) return header class Report: - """Report. - - A class to handle compiling and saving a BciPy Report after at least one session. + """Class for compiling and saving BciPy Reports. + + This class handles the creation of PDF reports containing multiple sections + of signal analysis and session information. + + Attributes: + DEFAULT_NAME (str): Default name for the report file. + sections (List[ReportSection]): List of report sections to include. + elements (List[Flowable]): List of reportlab flowables for the report. + name (str): Name of the report file. + path (str): Full path where the report will be saved. + document (SimpleDocTemplate): Reportlab document template. + styles: Reportlab style sheet for formatting. + header (Optional[Flowable]): Report header containing logo and title. """ DEFAULT_NAME: str = 'BciPyReport.pdf' @@ -224,6 +289,20 @@ def __init__(self, name: Optional[str] = None, sections: Optional[List[ReportSection]] = None, autocompile: bool = False): + """Initialize Report. + + Args: + save_path (str): Directory where the report will be saved. + name (Optional[str], optional): Name of the report file. Defaults to None. + sections (Optional[List[ReportSection]], optional): List of report sections. + Defaults to None. + autocompile (bool, optional): Whether to compile the report immediately. + Defaults to False. + + Raises: + AssertionError: If sections is not a list or contains invalid section types. + AssertionError: If name does not end with .pdf. + """ if sections: assert isinstance(sections, list), "Sections should be a list." assert all(isinstance(section, ReportSection) @@ -245,17 +324,15 @@ def __init__(self, self.compile() def add(self, section: ReportSection) -> None: - """Add. + """Add a section to the report. - Adds a ReportSection to the Report. + Args: + section (ReportSection): The section to add to the report. """ self.sections.append(section) def compile(self) -> None: - """Compile. - - Compiles the Report by adding the header and all sections to the elements list. - """ + """Compile the report by adding the header and all sections.""" if self.header is None: self._construct_report_header() header_group = KeepTogether(self.header) @@ -264,19 +341,17 @@ def compile(self) -> None: self.elements.append(section.compile()) def save(self) -> None: - """Save. - - Exports the Report to a PDF file. - """ + """Save the report as a PDF file.""" self.document.build(self.elements) def _construct_report_header(self) -> None: - """Construct Report Header. + """Construct the report header with logo and title. - Constructs the header for the Report. This should be called before adding any other elements. - The header should consist of the CAMBI logo and a report title. + Raises: + AssertionError: If called after other elements have been added. """ - assert len(self.elements) < 1, "The report header should be constructed before other elements" + assert len( + self.elements) < 1, "The report header should be constructed before other elements" report_title = Paragraph('BciPy Report', self.styles['Title']) logo = Image(BCIPY_FULL_LOGO_PATH, hAlign='LEFT', width=170, height=50) report_title.hAlign = 'CENTER' diff --git a/bcipy/helpers/session.py b/bcipy/core/session.py similarity index 60% rename from bcipy/helpers/session.py rename to bcipy/core/session.py index d447d17f6..7fa121251 100644 --- a/bcipy/helpers/session.py +++ b/bcipy/core/session.py @@ -1,41 +1,68 @@ +# mypy: disable-error-code="arg-type" """Helper functions for managing and parsing session.json data.""" import csv import itertools import json +import logging import os import sqlite3 -import subprocess from dataclasses import dataclass, fields -from typing import Any, Dict, List, Optional +from typing import Any, Dict, Iterator, List, Optional, Union import openpyxl from openpyxl.chart import BarChart, Reference from openpyxl.styles import PatternFill from openpyxl.styles.borders import BORDER_THIN, Border, Side from openpyxl.styles.colors import COLOR_INDEX +from openpyxl.worksheet.worksheet import Worksheet + +from bcipy.config import (DEFAULT_ENCODING, DEFAULT_PARAMETERS_FILENAME, + SESSION_DATA_FILENAME, SESSION_LOG_FILENAME, + SESSION_SUMMARY_FILENAME) +from bcipy.io.load import load_json_parameters +from bcipy.task.data import Session + +# Configure logging +logger = logging.getLogger(SESSION_LOG_FILENAME) + BLACK = COLOR_INDEX[0] WHITE = COLOR_INDEX[1] YELLOW = COLOR_INDEX[5] -from bcipy.config import (BCIPY_ROOT, DEFAULT_ENCODING, - DEFAULT_PARAMETERS_FILENAME, EXPERIMENT_DATA_FILENAME, - SESSION_DATA_FILENAME, SESSION_SUMMARY_FILENAME) -from bcipy.helpers.load import (load_experiment_fields, load_experiments, - load_json_parameters) -from bcipy.helpers.validate import validate_field_data_written -from bcipy.task.data import Session def read_session(file_name: str = SESSION_DATA_FILENAME) -> Session: - """Read the session data from the given file.""" + """Read session data from a JSON file. + + Args: + file_name (str, optional): Path to the session data file. + Defaults to SESSION_DATA_FILENAME. + + Returns: + Session: A Session object containing the parsed data. + + Raises: + FileNotFoundError: If the specified file does not exist. + json.JSONDecodeError: If the file contains invalid JSON. + """ with open(file_name, 'r', encoding=DEFAULT_ENCODING) as json_file: return Session.from_dict(json.load(json_file)) -def session_data(data_dir: str) -> Dict: - """Returns a dict of session data transformed to map the alphabet letter - to the likelihood when presenting the evidence. Also removes attributes - not useful for debugging.""" +def session_data(data_dir: str) -> Dict[str, Any]: + """Transform session data to map alphabet letters to likelihood values. + Args: + data_dir (str): Directory containing the session data and parameters. + + Returns: + Dict[str, Any]: Dictionary containing transformed session data with: + - Mapped alphabet letters to likelihood values + - Target text from parameters + - Removed debugging attributes + + Raises: + FileNotFoundError: If required files are not found in data_dir. + """ parameters = load_json_parameters(os.path.join(data_dir, DEFAULT_PARAMETERS_FILENAME), value_cast=True) @@ -45,24 +72,24 @@ def session_data(data_dir: str) -> Dict: return data -def collect_experiment_field_data(experiment_name: str, - save_path: str, - file_name: str = EXPERIMENT_DATA_FILENAME) -> None: - experiment = load_experiments()[experiment_name] - experiment_fields = load_experiment_fields(experiment) - - if experiment_fields: - cmd = (f'python {BCIPY_ROOT}/gui/experiments/ExperimentField.py -e' - f' "{experiment_name}" -p "{save_path}" -f "{file_name}"') - subprocess.check_call(cmd, shell=True) - # verify data was written before moving on - if not validate_field_data_written(save_path, file_name): - raise Exception('Field data not collected!') - - @dataclass(frozen=True) class EvidenceRecord: - """Record summarizing Inquiry evidence.""" + """Record summarizing Inquiry evidence. + + Attributes: + series (int): Series number. + inquiry (int): Inquiry number within the series. + stim (str): Stimulus (letter or icon). + lm (float): Language model probability. + eeg (float): EEG evidence value. + eye (float): Eye tracking evidence value. + btn (float): Button press evidence value. + cumulative (float): Cumulative likelihood value. + inq_position (Optional[int]): Position in inquiry sequence. + is_target (int): Whether this is the target (1) or not (0). + presented (int): Whether this was presented (1) or not (0). + above_threshold (int): Whether above decision threshold (1) or not (0). + """ series: int inquiry: int stim: str @@ -76,12 +103,25 @@ class EvidenceRecord: presented: int above_threshold: int - def __iter__(self): + def __iter__(self) -> Iterator[Any]: + """Iterate over the record's field values. + + Returns: + Iterator[Any]: Iterator over the record's field values. + """ return iter([getattr(self, field.name) for field in fields(self)]) def sqlite_ddl(cls: Any, table_name: str) -> str: - """Sqlite create table statement for the given dataclass""" + """Generate SQLite CREATE TABLE statement for a dataclass. + + Args: + cls (Any): Dataclass to generate DDL for. + table_name (str): Name of the table to create. + + Returns: + str: SQLite CREATE TABLE statement. + """ conversions = {int: 'integer', str: 'text', float: 'real'} column_defs = [ @@ -92,13 +132,31 @@ def sqlite_ddl(cls: Any, table_name: str) -> str: def sqlite_insert(cls: Any, table_name: str) -> str: - """sqlite INSERT statement for the given dataclass.""" + """Generate SQLite INSERT statement for a dataclass. + + Args: + cls (Any): Dataclass to generate INSERT for. + table_name (str): Name of the table to insert into. + + Returns: + str: SQLite INSERT statement with placeholders. + """ placeholders = ['?' for _ in fields(cls)] return f"INSERT INTO {table_name} VALUES ({','.join(placeholders)})" def evidence_records(session: Session) -> List[EvidenceRecord]: - """Summarize the session evidence data.""" + """Generate evidence records from session data. + + Args: + session (Session): Session data to process. + + Returns: + List[EvidenceRecord]: List of evidence records. + + Raises: + AssertionError: If session has no evidence or no symbol set. + """ assert session.has_evidence( ), "There is no evidence in the provided session" assert session.symbol_set, "Session must define a symbol_set" @@ -122,7 +180,8 @@ def evidence_records(session: Session) -> List[EvidenceRecord]: eye=evidence.get('eye_evidence', {}).get(stim, ''), btn=evidence.get('btn_evidence', {}).get(stim, ''), cumulative=evidence['likelihood'][stim], - inq_position=stimuli.index(stim) if stim in stimuli else None, + inq_position=stimuli.index( + stim) if stim in stimuli else None, is_target=int(inquiry.target_letter == stim), presented=int(stim in stimuli), above_threshold=int(evidence['likelihood'][stim] > @@ -130,34 +189,27 @@ def evidence_records(session: Session) -> List[EvidenceRecord]: return records -def session_db(session: Session, db_file: str = 'session.db'): - """Creates a sqlite database from the given session data. - - Parameters - ---------- - session - task data (evidence values, stim times, etc.) - db_file - path of database to write; defaults to session.db - - Database Schema - --------------- - evidence: - - trial integer (0-based) - - inquiry integer (0-based) - - letter text (letter or icon) - - lm real (language model probability for the trial; same for every - inquiry and only considered in the cumulative value during the - first inquiry) - - eeg real (likelihood for the given inquiry; a value of 1.0 indicates - that the letter was not presented) - - btn real (button press evidence) - - eye real (eyetracker evidence) - - cumulative real (cumulative likelihood for the trial thus far) - - inq_position integer (inquiry position; null if not presented) - - is_target integer (boolean; true(1) if this letter is the target) - - presented integer (boolean; true if the letter was presented in - this inquiry) - - above_threshold (boolean; true if cumulative likelihood was above - the configured threshold) +def session_db(session: Session, db_file: str = 'session.db') -> None: + """Create a SQLite database from session data. + + Args: + session (Session): Session data to store in database. + db_file (str, optional): Path to database file. Defaults to 'session.db'. + + Database Schema: + evidence: + - trial integer (0-based) + - inquiry integer (0-based) + - letter text (letter or icon) + - lm real (language model probability) + - eeg real (likelihood for the inquiry) + - btn real (button press evidence) + - eye real (eyetracker evidence) + - cumulative real (cumulative likelihood) + - inq_position integer (inquiry position) + - is_target integer (boolean) + - presented integer (boolean) + - above_threshold integer (boolean) """ # Create database conn = sqlite3.connect(db_file) @@ -171,8 +223,13 @@ def session_db(session: Session, db_file: str = 'session.db'): conn.commit() -def session_csv(session: Session, csv_file='session.csv'): - """Create a csv file summarizing the evidence data for the given session.""" +def session_csv(session: Session, csv_file: str = 'session.csv') -> None: + """Create a CSV file summarizing session evidence data. + + Args: + session (Session): Session data to summarize. + csv_file (str, optional): Path to CSV file. Defaults to 'session.csv'. + """ with open(csv_file, "w", encoding=DEFAULT_ENCODING, newline='') as output: csv_writer = csv.writer(output, delimiter=',') @@ -182,8 +239,20 @@ def session_csv(session: Session, csv_file='session.csv'): csv_writer.writerow(record) -def write_row(excel_sheet, rownum, data, background=None, border=None): - """Helper method to write a row to an Excel spreadsheet""" +def write_row(excel_sheet: Worksheet, + rownum: int, + data: Union[EvidenceRecord, List[Any]], + background: Optional[PatternFill] = None, + border: Optional[Border] = None) -> None: + """Write a row to an Excel spreadsheet. + + Args: + excel_sheet (Worksheet): Worksheet to write to. + rownum (int): Row number to write to. + data (Union[EvidenceRecord, List[Any]]): Data to write. + background (Optional[PatternFill], optional): Background fill. Defaults to None. + border (Optional[Border], optional): Cell border. Defaults to None. + """ for col, val in enumerate(data, start=1): cell = excel_sheet.cell(row=rownum, column=col) cell.value = val @@ -194,10 +263,15 @@ def write_row(excel_sheet, rownum, data, background=None, border=None): def session_excel(session: Session, - excel_file=SESSION_SUMMARY_FILENAME, - include_charts=True): - """Create an Excel spreadsheet summarizing the evidence data for the given session.""" - + excel_file: str = SESSION_SUMMARY_FILENAME, + include_charts: bool = True) -> None: + """Create an Excel spreadsheet summarizing session evidence data. + + Args: + session (Session): Session data to summarize. + excel_file (str, optional): Path to Excel file. Defaults to SESSION_SUMMARY_FILENAME. + include_charts (bool, optional): Whether to include charts. Defaults to True. + """ # Define styles and borders to use within the spreadsheet. gray_background = PatternFill(start_color='ededed', fill_type='solid') white_background = PatternFill(start_color=WHITE, fill_type=None) @@ -296,7 +370,7 @@ def session_excel(session: Session, # Freeze header row sheet.freeze_panes = 'A2' workbook.save(excel_file) - print("Wrote output to " + excel_file) + logger.info("Wrote output to %s", excel_file) if __name__ == "__main__": diff --git a/bcipy/helpers/stimuli.py b/bcipy/core/stimuli.py similarity index 60% rename from bcipy/helpers/stimuli.py rename to bcipy/core/stimuli.py index 558a513e2..b466cd1d4 100644 --- a/bcipy/helpers/stimuli.py +++ b/bcipy/core/stimuli.py @@ -21,10 +21,11 @@ from PIL import Image from psychopy import core -from bcipy.config import DEFAULT_FIXATION_PATH, DEFAULT_TEXT_FIXATION, SESSION_LOG_FILENAME +from bcipy.config import (DEFAULT_FIXATION_PATH, DEFAULT_TEXT_FIXATION, + SESSION_LOG_FILENAME) +from bcipy.core.list import grouper +from bcipy.core.symbols import alphabet from bcipy.exceptions import BciPyCoreException -from bcipy.helpers.list import grouper -from bcipy.helpers.symbols import alphabet # Prevents pillow from filling the console with debug info logging.getLogger('PIL').setLevel(logging.WARNING) @@ -34,45 +35,62 @@ class StimuliOrder(Enum): - """Stimuli Order. + """Defines the ordering of stimuli for inquiry. - Enum to define the ordering of stimuli for inquiry. + Attributes: + RANDOM (str): Random ordering of stimuli. + ALPHABETICAL (str): Alphabetical ordering of stimuli. """ RANDOM = 'random' ALPHABETICAL = 'alphabetical' @classmethod - def list(cls): - """Returns all enum values as a list""" + def list(cls) -> list: + """Returns all enum values as a list. + + Returns: + list: List of all enum values. + """ return list(map(lambda c: c.value, cls)) class TargetPositions(Enum): - """Target Positions. + """Defines the positions of targets within the inquiry. - Enum to define the positions of targets within the inquiry. + Attributes: + RANDOM (str): Random positioning of targets. + DISTRIBUTED (str): Evenly distributed positioning of targets. """ RANDOM = 'random' DISTRIBUTED = 'distributed' @classmethod - def list(cls): - """Returns all enum values as a list""" + def list(cls) -> list: + """Returns all enum values as a list. + + Returns: + list: List of all enum values. + """ return list(map(lambda c: c.value, cls)) class PhotoDiodeStimuli(Enum): - """Photodiode Stimuli. + """Defines unicode stimuli needed for testing system timing. - Enum to define unicode stimuli needed for testing system timing. + Attributes: + EMPTY (str): Box with a white border, no fill (□). + SOLID (str): Solid white box (■). """ - EMPTY = '\u25A1' # box with a white border, no fill SOLID = '\u25A0' # solid white box @classmethod - def list(cls): - """Returns all enum values as a list""" + def list(cls) -> list: + """Returns all enum values as a list. + + Returns: + list: List of all enum values. + """ return list(map(lambda c: c.value, cls)) @@ -80,19 +98,21 @@ class InquirySchedule(NamedTuple): """Schedule for the next inquiries to present, where each inquiry specifies the stimulus, duration, and color information. - Attributes - ---------- - - stimuli: `List[List[str]]` - - durations: `List[List[float]]` - - colors: `List[List[str]]` + Attributes: + stimuli (List[Any]): List of stimuli for each inquiry. + durations (Union[List[List[float]], List[float]]): Duration for each stimulus. + colors (Union[List[List[str]], List[str]]): Color for each stimulus. """ stimuli: List[Any] durations: Union[List[List[float]], List[float]] colors: Union[List[List[str]], List[str]] def inquiries(self) -> Iterator[Tuple]: - """Generator that iterates through each Inquiry. Yields tuples of - (stim, duration, color).""" + """Generator that iterates through each Inquiry. + + Yields: + Tuple: Tuple of (stim, duration, color) for each inquiry. + """ count = len(self.stimuli) index = 0 while index < count: @@ -102,13 +122,25 @@ def inquiries(self) -> Iterator[Tuple]: class Reshaper(ABC): + """Abstract base class for reshaping data in BCI experiments.""" @abstractmethod def __call__(self, *args, **kwargs) -> Any: + """Reshape data for a specific paradigm. + + Args: + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + + Returns: + Any: Reshaped data. + """ ... class InquiryReshaper: + """Reshapes EEG data, timing, and labels for inquiries in BCI experiments.""" + def __call__(self, trial_targetness_label: List[str], timing_info: List[float], @@ -124,30 +156,28 @@ def __call__(self, """Extract inquiry data and labels. Args: - trial_targetness_label (List[str]): labels each trial as "target", "non-target", "first_pres_target", etc - timing_info (List[float]): Timestamp of each event in seconds - eeg_data (np.ndarray): shape (channels, samples) preprocessed EEG data - sample_rate (int): sample rate of data provided in eeg_data - trials_per_inquiry (int): number of trials in each inquiry + trial_targetness_label (List[str]): Labels each trial as "target", "non-target", etc. + timing_info (List[float]): Timestamp of each event in seconds. + eeg_data (np.ndarray): Shape (channels, samples) preprocessed EEG data. + sample_rate (int): Sample rate of data provided in eeg_data. + trials_per_inquiry (int): Number of trials in each inquiry. offset (float, optional): Any calculated or hypothesized offsets in timings. Defaults to 0. - channel_map (List[int], optional): Describes which channels to include or discard. - Defaults to None; all channels will be used. - poststimulus_length (float, optional): time in seconds needed after the last trial in an inquiry. - prestimulus_length (float, optional): time in seconds needed before the first trial in an inquiry. - transformation_buffer (float, optional): time in seconds to buffer the end of the inquiry. Defaults to 0.0. - target_label (str): label of target symbol. Defaults to "target" + channel_map (List[int], optional): Describes which channels to include or discard. Defaults to None. + poststimulus_length (float, optional): Time in seconds needed after the last trial. Defaults to 0.5. + prestimulus_length (float, optional): Time in seconds needed before the first trial. Defaults to 0.0. + transformation_buffer (float, optional): Time in seconds to buffer the end of the inquiry. Defaults to 0.0. + target_label (str, optional): Label of target symbol. Defaults to "target". Returns: - reshaped_data (np.ndarray): inquiry data of shape (Channels, Inquiries, Samples) - labels (np.ndarray): integer label for each inquiry. With `trials_per_inquiry=K`, - a label of [0, K-1] indicates the position of `target_label`, or label of [0 ... 0] indicates - `target_label` was not present. - reshaped_trigger_timing (List[List[int]]): For each inquiry, a list of the sample index where each trial - begins, accounting for the prestim buffer that may have been added to the front of each inquiry. + Tuple[np.ndarray, np.ndarray, List[List[float]]]: + - reshaped_data: Inquiry data of shape (Channels, Inquiries, Samples) + - labels: Integer label for each inquiry + - reshaped_trigger_timing: For each inquiry, a list of the sample index where each trial begins """ if channel_map: # Remove the channels that we are not interested in - channels_to_remove = [idx for idx, value in enumerate(channel_map) if value == 0] + channels_to_remove = [idx for idx, + value in enumerate(channel_map) if value == 0] eeg_data = np.delete(eeg_data, channels_to_remove, axis=0) n_inquiry = len(timing_info) // trials_per_inquiry @@ -155,15 +185,18 @@ def __call__(self, prestimulus_samples = int(prestimulus_length * sample_rate) # triggers in seconds are mapped to triggers in number of samples. - triggers = list(map(lambda x: int((x + offset) * sample_rate), timing_info)) + triggers = list( + map(lambda x: int((x + offset) * sample_rate), timing_info)) # First, find the longest inquiry in this experiment # We'll add or remove a few samples from all other inquiries, to match this length def get_inquiry_len(inq_trigs): return inq_trigs[-1] - inq_trigs[0] - longest_inquiry = max(grouper(triggers, trials_per_inquiry, fillvalue='x'), key=lambda xy: get_inquiry_len(xy)) - num_samples_per_inq = get_inquiry_len(longest_inquiry) + trial_duration_samples + longest_inquiry = max(grouper( + triggers, trials_per_inquiry, fillvalue='x'), key=lambda xy: get_inquiry_len(xy)) + num_samples_per_inq = get_inquiry_len( + longest_inquiry) + trial_duration_samples buffer_samples = int(transformation_buffer * sample_rate) # Label for every inquiry @@ -172,7 +205,8 @@ def get_inquiry_len(inq_trigs): ) # maybe this can be configurable? return either class indexes or labels ('nontarget' etc) reshaped_data, reshaped_trigger_timing = [], [] for inquiry_idx, trials_within_inquiry in enumerate( - grouper(zip(trial_targetness_label, triggers), trials_per_inquiry, fillvalue='x') + grouper(zip(trial_targetness_label, triggers), + trials_per_inquiry, fillvalue='x') ): first_trigger = trials_within_inquiry[0][1] @@ -183,7 +217,8 @@ def get_inquiry_len(inq_trigs): # If prestimulus buffer is used, we add it here so that trigger timings will # still line up with trial onset - trial_triggers.append((trigger - first_trigger) + prestimulus_samples) + trial_triggers.append( + (trigger - first_trigger) + prestimulus_samples) reshaped_trigger_timing.append(trial_triggers) start = first_trigger - prestimulus_samples stop = first_trigger + num_samples_per_inq + buffer_samples @@ -197,29 +232,19 @@ def extract_trials( samples_per_trial: int, inquiry_timing: List[List[int]], prestimulus_samples: int = 0) -> np.ndarray: - """Extract Trials. - - After using the InquiryReshaper, it may be necessary to further extract the trials for processing. - Using the number of samples and inquiry timing, the data is reshaped from Channels, Inquiry, Samples to - Channels, Trials, Samples. These should match with the trials extracted from the TrialReshaper given the same - slicing parameters. - - Parameters - ---------- - inquiries : np.ndarray - shape (Channels, Inquiries, Samples) - samples_per_trial : int - number of samples per trial - inquiry_timing : List[List[int]] - For each inquiry, a list of the sample index where each trial begins - prestimulus_samples : int, optional - Number of samples to move the start of each trial in each inquiry, by default 0. - This is useful if wanting to use baseline intervals before the trial onset, along with the trial data. - - Returns - ------- - np.ndarray - shape (Channels, Trials, Samples) + """Extract trials from inquiry data. + + Args: + inquiries (np.ndarray): Shape (Channels, Inquiries, Samples). + samples_per_trial (int): Number of samples per trial. + inquiry_timing (List[List[int]]): For each inquiry, a list of the sample index where each trial begins. + prestimulus_samples (int, optional): Number of samples to move the start of each trial. Defaults to 0. + + Returns: + np.ndarray: Shape (Channels, Trials, Samples). + + Raises: + BciPyCoreException: If index is out of bounds when extracting trials. """ new_trials = [] num_inquiries = inquiries.shape[1] @@ -241,6 +266,8 @@ def extract_trials( class GazeReshaper: + """Reshapes gaze trajectory data and labels for inquiries in BCI experiments.""" + def __call__(self, inq_start_times: List[float], target_symbols: List[str], @@ -253,36 +280,21 @@ def __call__(self, ) -> Tuple[dict, list, List[str]]: """Extract gaze trajectory data and labels. - Different from the EEG, gaze inquiry windows start with the first highlighted symbol and end with the - last highlighted symbol in the inquiry. Each inquiry has a length of (trial duration x num of trials) - seconds. Labels are provided in 'target_symbols'. It returns a Dict, where keys are the target symbols - and the values are inquiries (appended in order of appearance) where the corresponding target symbol is - prompted. - - Optional outputs: - reshape_data is the list of data reshaped into (Inquiries, Channels, Samples), where inquirires are - appended in chronological order. - labels returns the list of target symbols in each inquiry. - - Parameters - ---------- - inq_start_times (List[float]): Timestamp of each event in seconds - target_symbols (List[str]): Prompted symbol in each inquiry - gaze_data (np.ndarray): shape (channels, samples) eye tracking data - sample_rate (int): sample rate of eye tracker data - stimulus_duration (float): duration of flash time (in seconds) for each trial - num_stimuli_per_inquiry (int): number of stimuli in each inquiry (default: 10) - symbol_set (List[str]): list of all symbols for the task - channel_map (List[int], optional): Describes which channels to include or discard. - Defaults to None; all channels will be used. - - Returns - ------- - data_by_targets (dict): Dictionary where keys consist of the symbol set, and values - the appended inquiries for each symbol. dict[Key] = (np.ndarray) of shape (Channels, Samples) - - reshaped_data (List[float]) [optional]: inquiry data of shape (Inquiries, Channels, Samples) - labels (List[str]) [optional] : Target symbol in each inquiry. + Args: + inq_start_times (List[float]): Timestamp of each event in seconds. + target_symbols (List[str]): Prompted symbol in each inquiry. + gaze_data (np.ndarray): Shape (channels, samples) eye tracking data. + sample_rate (int): Sample rate of eye tracker data. + stimulus_duration (float): Duration of flash time (in seconds) for each trial. + num_stimuli_per_inquiry (int): Number of stimuli in each inquiry. + symbol_set (List[str], optional): List of all symbols for the task. Defaults to alphabet(). + channel_map (List[int], optional): Describes which channels to include or discard. Defaults to None. + + Returns: + Tuple[dict, list, List[str]]: + - data_by_targets: Dictionary where keys are the symbol set, and values are the appended inquiries for each symbol. + - reshaped_data: Inquiry data of shape (Inquiries, Channels, Samples). + - labels: Target symbol in each inquiry. """ # Find the timestamp value closest to (& greater than) inq_start_times. # Lsl timestamps are the last row in the gaze_data @@ -307,10 +319,13 @@ def __call__(self, for symbol in symbol_set: data_by_targets_dict[symbol] = [] - buffer = stimulus_duration / 5 # seconds, buffer for each inquiry + buffer = 0.5 # seconds, buffer for each inquiry # NOTE: This buffer is used to account for the screen downtime between each stimulus. - # There is a "duty cycle" of 80% for the stimuli, so we add a buffer of 20% of the stimulus length - window_length = (stimulus_duration + buffer) * num_stimuli_per_inquiry # in seconds + # A better way of handling this buffer would be subtracting the flash time of the + # second symbol from the first symbol, which gives a more accurate representation of + # "stimulus duration". + window_length = (stimulus_duration + buffer) * \ + num_stimuli_per_inquiry # in seconds reshaped_data = [] # Merge the inquiries if they have the same target letter: @@ -329,13 +344,14 @@ def __call__(self, return data_by_targets_dict, reshaped_data, labels def centralize_all_data(self, data: np.ndarray, symbol_pos: np.ndarray) -> np.ndarray: - """ Using the symbol locations in matrix, centralize all data (in Tobii units). - This data will only be used in certain model types. + """Centralize all data using symbol locations in matrix (Tobii units). + Args: - data (np.ndarray): Data in shape of num_samples x num_dimensions - symbol_pos (np.ndarray(float)): Array of the current symbol posiiton in Tobii units + data (np.ndarray): Data in shape of num_samples x num_dimensions. + symbol_pos (np.ndarray): Array of the current symbol position in Tobii units. + Returns: - new_data (np.ndarray): Centralized data in shape of num_samples x num_dimensions + np.ndarray: Centralized data in shape of num_samples x num_dimensions. """ new_data = np.copy(data) for i in range(len(data)): @@ -345,6 +361,8 @@ def centralize_all_data(self, data: np.ndarray, symbol_pos: np.ndarray) -> np.nd class TrialReshaper(Reshaper): + """Reshapes EEG data, timing, and labels for individual trials in BCI experiments.""" + def __call__(self, trial_targetness_label: list, timing_info: list, @@ -357,28 +375,26 @@ def __call__(self, target_label: str = "target") -> Tuple[np.ndarray, np.ndarray]: """Extract trial data and labels. - Parameters - ---------- - trial_targetness_label (list): labels each trial as "target", "non-target", "first_pres_target", etc - timing_info (list): Timestamp of each event in seconds - eeg_data (np.ndarray): shape (channels, samples) preprocessed EEG data - sample_rate (int): sample rate of preprocessed EEG data - trials_per_inquiry (int, optional): unused, kept here for consistent interface with `inquiry_reshaper` - offset (float, optional): Any calculated or hypothesized offsets in timings. - Defaults to 0. - channel_map (List, optional): Describes which channels to include or discard. - Defaults to None; all channels will be used. - poststimulus_length (float, optional): [description]. Defaults to 0.5. - target_label (str): label of target symbol. Defaults to "target" - - Returns - ------- - trial_data (np.ndarray): shape (channels, trials, samples) reshaped data - labels (np.ndarray): integer label for each trial + Args: + trial_targetness_label (list): Labels each trial as "target", "non-target", etc. + timing_info (list): Timestamp of each event in seconds. + eeg_data (np.ndarray): Shape (channels, samples) preprocessed EEG data. + sample_rate (int): Sample rate of preprocessed EEG data. + offset (float, optional): Any calculated or hypothesized offsets in timings. Defaults to 0. + channel_map (List, optional): Describes which channels to include or discard. Defaults to None. + poststimulus_length (float, optional): Time in seconds needed after the last trial. Defaults to 0.5. + prestimulus_length (float, optional): Time in seconds needed before the first trial. Defaults to 0.0. + target_label (str, optional): Label of target symbol. Defaults to "target". + + Returns: + Tuple[np.ndarray, np.ndarray]: + - trial_data: Reshaped data of shape (channels, trials, samples) + - labels: Integer label for each trial """ # Remove the channels that we are not interested in if channel_map: - channels_to_remove = [idx for idx, value in enumerate(channel_map) if value == 0] + channels_to_remove = [idx for idx, + value in enumerate(channel_map) if value == 0] eeg_data = np.delete(eeg_data, channels_to_remove, axis=0) # Number of samples we are interested per trial @@ -386,7 +402,8 @@ def __call__(self, prestim_samples = int(prestimulus_length * sample_rate) # triggers in seconds are mapped to triggers in number of samples. - triggers = list(map(lambda x: int((x + offset) * sample_rate), timing_info)) + triggers = list( + map(lambda x: int((x + offset) * sample_rate), timing_info)) # Label for every trial in 0 or 1 targetness_labels = np.zeros(len(triggers), dtype=np.longlong) @@ -396,13 +413,22 @@ def __call__(self, targetness_labels[trial_idx] = 1 # For every channel append filtered channel data to trials - reshaped_trials.append(eeg_data[:, trigger - prestim_samples: trigger + poststim_samples]) + reshaped_trials.append( + eeg_data[:, trigger - prestim_samples: trigger + poststim_samples]) return np.stack(reshaped_trials, 1), targetness_labels def update_inquiry_timing(timing: List[List[int]], downsample: int) -> List[List[int]]: - """Update inquiry timing to reflect downsampling.""" + """Update inquiry timing to reflect downsampling. + + Args: + timing (List[List[int]]): Original timing values for each inquiry. + downsample (int): Downsampling factor. + + Returns: + List[List[int]]: Updated timing values for each inquiry. + """ for i, inquiry in enumerate(timing): for j, time in enumerate(inquiry): timing[i][j] = int(time // downsample) @@ -417,14 +443,24 @@ def mne_epochs(mne_data: RawArray, baseline: Optional[Tuple[Any, float]] = None, reject_by_annotation: bool = False, preload: bool = False) -> Epochs: - """MNE Epochs. + """Create MNE Epochs from a RawArray and trigger information. - Using an MNE RawArray, reshape the data given trigger information. If two labels present [0, 1], - each may be accessed by numbered order. Ex. first_class = epochs['1'], second_class = epochs['2'] + Args: + mne_data (RawArray): MNE RawArray object. + trial_length (float): Length of each trial in seconds. + trigger_timing (Optional[List[float]], optional): List of trigger times. Defaults to None. + trigger_labels (Optional[List[int]], optional): List of trigger labels. Defaults to None. + baseline (Optional[Tuple[Any, float]], optional): Baseline interval. Defaults to None. + reject_by_annotation (bool, optional): Whether to reject epochs by annotation. Defaults to False. + preload (bool, optional): Whether to preload the data. Defaults to False. + + Returns: + Epochs: MNE Epochs object. """ old_annotations = mne_data.annotations if trigger_timing and trigger_labels: - new_annotations = Annotations(trigger_timing, [trial_length] * len(trigger_timing), trigger_labels) + new_annotations = Annotations( + trigger_timing, [trial_length] * len(trigger_timing), trigger_labels) all_annotations = new_annotations + old_annotations else: all_annotations = old_annotations @@ -446,15 +482,20 @@ def mne_epochs(mne_data: RawArray, baseline=baseline, tmax=trial_length, tmin=tmin, - proj=False, # apply SSP projection to data. Defaults to True in Epochs. + # apply SSP projection to data. Defaults to True in Epochs. + proj=False, reject_by_annotation=reject_by_annotation, preload=preload) def alphabetize(stimuli: List[str]) -> List[str]: - """Alphabetize. + """Return a list of sorted stimuli by alphabet. - Given a list of string stimuli, return a list of sorted stimuli by alphabet. + Args: + stimuli (List[str]): List of string stimuli. + + Returns: + List[str]: Alphabetically sorted list of stimuli. """ return sorted(stimuli, key=lambda x: re.sub(r'[^a-zA-Z0-9 \n\.]', 'ZZ', x).lower()) @@ -466,23 +507,20 @@ def inq_generator(query: List[str], stim_jitter: float = 0, stim_order: StimuliOrder = StimuliOrder.RANDOM, is_txt: bool = True) -> InquirySchedule: - """Given the query set, prepares the stimuli, color and timing - - Parameters - ---------- - query(list[str]): list of queries to be shown - timing(list[float]): Task specific timing for generator - color(list[str]): Task specific color for generator - First element is the target, second element is the fixation - Observe that [-1] element represents the trial information - Return - ------ - schedule_inq(tuple( - samples[list[list[str]]]: list of inquiries - timing(list[list[float]]): list of timings - color(list(list[str])): list of colors)): scheduled inquiries - """ + """Prepare the stimuli, color, and timing for a set of inquiries. + Args: + query (List[str]): List of queries to be shown. + timing (List[float], optional): Task specific timing for generator. Defaults to [1, 0.2]. + color (List[str], optional): Task specific color for generator. Defaults to ['red', 'white']. + inquiry_count (int, optional): Number of inquiries to generate. Defaults to 1. + stim_jitter (float, optional): Jitter to apply to stimulus timing. Defaults to 0. + stim_order (StimuliOrder, optional): Ordering of stimuli. Defaults to StimuliOrder.RANDOM. + is_txt (bool, optional): Whether the stimuli are text. Defaults to True. + + Returns: + InquirySchedule: Scheduled inquiries with samples, timing, and color. + """ if stim_order == StimuliOrder.ALPHABETICAL: query = alphabetize(query) else: @@ -493,18 +531,14 @@ def inq_generator(query: List[str], # Init some lists to construct our stimuli with samples, times, colors = [], [], [] for _ in range(inquiry_count): - # append a fixation cross. if not text, append path to image fixation sample = [get_fixation(is_txt)] - # construct the sample from the query sample += [i for i in query] samples.append(sample) - times.append([timing[i] for i in range(len(timing) - 1)]) base_timing = timing[-1] times[-1] += jittered_timing(base_timing, stim_jitter, stim_length) - # append colors colors.append([color[i] for i in range(len(color) - 1)] + [color[-1]] * stim_length) @@ -515,33 +549,26 @@ def best_selection(selection_elements: list, val: list, len_query: int, always_included: Optional[List[str]] = None) -> list: - """Best Selection. - - Given set of elements and a value function over the set, picks the len_query - number of elements with the best value. - - Parameters - ---------- - selection_elements(list[str]): the set of elements - val(list[float]): values for the corresponding elements - len_query(int): number of elements to be picked from the set - always_included(list[str]): subset of elements that should always be - included in the result. Defaults to None. - Return - ------ - best_selection(list[str]): elements from selection_elements with the best values - """ + """Pick the len_query number of elements with the best value. + Args: + selection_elements (list): The set of elements. + val (list): Values for the corresponding elements. + len_query (int): Number of elements to be picked from the set. + always_included (Optional[List[str]], optional): Subset of elements that should always be included. Defaults to None. + + Returns: + list: Elements from selection_elements with the best values. + """ always_included = always_included or [] # pick the top n items sorted by value in decreasing order elem_val = dict(zip(selection_elements, val)) - best = sorted(selection_elements, key=elem_val.get, reverse=True)[0:len_query] - + best = sorted(selection_elements, key=elem_val.get, + reverse=True)[0:len_query] replacements = [ item for item in always_included if item not in best and item in selection_elements ][0:len_query] - if replacements: best[-len(replacements):] = replacements return best @@ -556,67 +583,49 @@ def best_case_rsvp_inq_gen(alp: list, stim_order: StimuliOrder = StimuliOrder.RANDOM, is_txt: bool = True, inq_constants: Optional[List[str]] = None) -> InquirySchedule: - """Best Case RSVP Inquiry Generation. - - Generates RSVPKeyboard inquiry by picking n-most likely letters. - - Parameters - ---------- - alp(list[str]): alphabet (can be arbitrary) - session_stimuli(ndarray[float]): quantifier metric for query selection - dim(session_stimuli) = card(alp)! - timing(list[float]): Task specific timing for generator - color(list[str]): Task specific color for generator - First element is the target, second element is the fixation - Observe that [-1] element represents the trial information - inquiry_count(int): number of random stimuli to be created - stim_per_inquiry(int): number of trials in a inquiry - stim_order(StimuliOrder): ordering of stimuli in the inquiry - inq_constants(list[str]): list of letters that should always be - included in every inquiry. If provided, must be alp items. - Return - ------ - schedule_inq(tuple( - samples[list[list[str]]]: list of inquiries - timing(list[list[float]]): list of timings - color(list(list[str])): list of colors)): scheduled inquiries - """ + """Generate RSVPKeyboard inquiry by picking n-most likely letters. + + Args: + alp (list): Alphabet (can be arbitrary). + session_stimuli (np.ndarray): Quantifier metric for query selection. + timing (List[float], optional): Task specific timing for generator. Defaults to [1, 0.2]. + color (List[str], optional): Task specific color for generator. Defaults to ['red', 'white']. + stim_number (int, optional): Number of random stimuli to be created. Defaults to 1. + stim_length (int, optional): Number of trials in an inquiry. Defaults to 10. + stim_order (StimuliOrder, optional): Ordering of stimuli. Defaults to StimuliOrder.RANDOM. + is_txt (bool, optional): Whether the stimuli are text. Defaults to True. + inq_constants (Optional[List[str]], optional): Letters that should always be included. Defaults to None. + Returns: + InquirySchedule: Scheduled inquiries with samples, timing, and color. + """ if len(alp) != len(session_stimuli): raise BciPyCoreException(( f'Missing information about alphabet.' f'len(alp):{len(alp)} and len(session_stimuli):{len(session_stimuli)} should be same!')) - if inq_constants and not set(inq_constants).issubset(alp): raise BciPyCoreException('Inquiry constants must be alphabet items.') - # query for the best selection query = best_selection( alp, session_stimuli, stim_length, inq_constants) - if stim_order == StimuliOrder.ALPHABETICAL: query = alphabetize(query) else: random.shuffle(query) - # Init some lists to construct our stimuli with samples, times, colors = [], [], [] for _ in range(stim_number): - # append a fixation cross. if not text, append path to image fixation sample = [get_fixation(is_txt)] - # construct the sample from the query sample += [i for i in query] samples.append(sample) - # append timing times.append([timing[i] for i in range(len(timing) - 1)] + [timing[-1]] * stim_length) - # append colors colors.append([color[i] for i in range(len(color) - 1)] + [color[-1]] * stim_length) @@ -634,37 +643,22 @@ def generate_calibration_inquiries( target_positions: TargetPositions = TargetPositions.RANDOM, percentage_without_target: int = 0, is_txt: bool = True) -> InquirySchedule: - """ - Generates inquiries with target letters in all possible positions. - - This function attempts to display all symbols as targets an equal number of - times when stim_order is RANDOM. When the stim_order is ALPHABETICAL there - is much more variation in the counts (target distribution takes priority) - and some symbols may not appear as targets depending on the inquiry_count. - The frequency that each symbol is displayed as a nontarget should follow a - uniform distribution. - - Parameters - ---------- - alp(list[str]): stimuli - timing(list[float]): Task specific timing for generator. - [target, fixation, stimuli] - jitter(int): jitter for stimuli timing. If None, no jitter is applied. - color(list[str]): Task specific color for generator - [target, fixation, stimuli] - inquiry_count(int): number of inquiries in a calibration - stim_per_inquiry(int): number of stimuli in each inquiry - stim_order(StimuliOrder): ordering of stimuli in the inquiry - target_positions(TargetPositions): positioning of targets to select for the inquiries - percentage_without_target(int): percentage of inquiries for which target letter flashed is not in inquiry - is_txt(bool): whether the stimuli type is text. False would be an image stimuli. - - Return - ------ - schedule_inq(tuple( - samples[list[list[str]]]: list of inquiries - timing(list[list[float]]): list of timings - color(list(list[str])): list of colors)): scheduled inquiries + """Generate inquiries with target letters in all possible positions. + + Args: + alp (List[str]): Stimuli. + timing (Optional[List[float]], optional): Task specific timing for generator. Defaults to None. + jitter (Optional[int], optional): Jitter for stimuli timing. Defaults to None. + color (Optional[List[str]], optional): Task specific color for generator. Defaults to None. + inquiry_count (int, optional): Number of inquiries in a calibration. Defaults to 100. + stim_per_inquiry (int, optional): Number of stimuli in each inquiry. Defaults to 10. + stim_order (StimuliOrder, optional): Ordering of stimuli. Defaults to StimuliOrder.RANDOM. + target_positions (TargetPositions, optional): Positioning of targets. Defaults to TargetPositions.RANDOM. + percentage_without_target (int, optional): Percentage of inquiries without a target. Defaults to 0. + is_txt (bool, optional): Whether the stimuli type is text. Defaults to True. + + Returns: + InquirySchedule: Scheduled inquiries with samples, timing, and color. """ if timing is None: timing = [0.5, 1, 0.2] @@ -675,7 +669,6 @@ def generate_calibration_inquiries( ) == 3, "timing must include values for [target, fixation, stimuli]" time_target, time_fixation, time_stim = timing fixation = get_fixation(is_txt) - target_indexes = generate_target_positions(inquiry_count, stim_per_inquiry, percentage_without_target, target_positions) @@ -697,15 +690,12 @@ def generate_calibration_inquiries( next_targets=targets, last_target=target) samples.append([target, fixation, *inquiry]) - times = [[ time_target, time_fixation, *generate_inquiry_stim_timing(time_stim, stim_per_inquiry, jitter) ] for _ in range(inquiry_count)] - inquiry_colors = color[0:2] + [color[-1]] * stim_per_inquiry colors = [inquiry_colors for _ in range(inquiry_count)] - return InquirySchedule(samples, times, colors) @@ -714,9 +704,11 @@ def inquiry_target_counts(inquiries: List[List[str]], """Count the number of times each symbol was presented as a target. Args: - inquiries - list of inquiries where each inquiry is structured as - [target, fixation, *stim] - symbols - list of all possible symbols + inquiries (List[List[str]]): List of inquiries where each inquiry is structured as [target, fixation, *stim]. + symbols (List[str]): List of all possible symbols. + + Returns: + dict: Dictionary mapping each symbol to its target count. """ target_presentations = [inq[0] for inq in inquiries if inq[0] in inq[2:]] counter = dict.fromkeys(symbols, 0) @@ -727,7 +719,15 @@ def inquiry_target_counts(inquiries: List[List[str]], def inquiry_nontarget_counts(inquiries: List[List[str]], symbols: List[str]) -> dict: - """Count the number of times each symbol was presented as a nontarget.""" + """Count the number of times each symbol was presented as a nontarget. + + Args: + inquiries (List[List[str]]): List of inquiries. + symbols (List[str]): List of all possible symbols. + + Returns: + dict: Dictionary mapping each symbol to its nontarget count. + """ counter = dict.fromkeys(symbols, 0) for inq in inquiries: target, _fixation, *stimuli = inq @@ -739,16 +739,20 @@ def inquiry_nontarget_counts(inquiries: List[List[str]], def inquiry_stats(inquiries: List[List[str]], symbols: List[str]) -> Dict[str, Dict[str, float]]: - """Descriptive stats for the number of times each target and nontarget - symbol is shown in the inquiries""" + """Descriptive stats for the number of times each target and nontarget symbol is shown in the inquiries. + + Args: + inquiries (List[List[str]]): List of inquiries. + symbols (List[str]): List of all possible symbols. + Returns: + Dict[str, Dict[str, float]]: Dictionary with stats for target and nontarget symbols. + """ target_stats = dict( Series(Counter(inquiry_target_counts(inquiries, symbols))).describe()) - nontarget_stats = dict( Series(Counter(inquiry_nontarget_counts(inquiries, symbols))).describe()) - return { 'target_symbols': target_stats, 'nontarget_symbols': nontarget_stats @@ -759,15 +763,15 @@ def generate_inquiries(symbols: List[str], inquiry_count: int, stim_per_inquiry: int, stim_order: StimuliOrder) -> List[List[str]]: """Generate a list of inquiries. For each inquiry no symbols are repeated. - Inquiries do not include the target or fixation. Symbols should be - distributed uniformly across inquiries. Args: + symbols (List[str]): Values from which to select. + inquiry_count (int): Total number of inquiries to generate. + stim_per_inquiry (int): Length of each inquiry. + stim_order (StimuliOrder): Ordering of results. - symbols - values from which to select - inquiry_count - total number of inquiries to generate - stim_per_inquiry - length of each inquiry - stim_order - ordering of results + Returns: + List[List[str]]: List of generated inquiries. """ return [ generate_inquiry(symbols=symbols, @@ -778,13 +782,15 @@ def generate_inquiries(symbols: List[str], inquiry_count: int, def generate_inquiry(symbols: List[str], length: int, stim_order: StimuliOrder) -> List[str]: - """Generate an inquiry from the list of symbols. No symbols are repeated - in the output list. Output does not include the target or fixation. + """Generate an inquiry from the list of symbols. No symbols are repeated in the output list. Args: - symbols - values from which to select - length - number of items in the return list - stim_order - ordering of results + symbols (List[str]): Values from which to select. + length (int): Number of items in the return list. + stim_order (StimuliOrder): Ordering of results. + + Returns: + List[str]: Generated inquiry. """ inquiry = random.sample(symbols, k=length) if stim_order == StimuliOrder.ALPHABETICAL: @@ -797,20 +803,17 @@ def inquiry_target(inquiry: List[str], symbols: List[str], next_targets: Optional[List[str]] = None, last_target: Optional[str] = None) -> str: - """Returns the target for the given inquiry. If the optional - target position is not provided a target will randomly be selected from - the list of symbols and will not be in the inquiry. + """Returns the target for the given inquiry. Args: - inquiry - list of symbols to be presented - target_position - optional position within the list of the target sym - symbols - used if position is not provided to select a random symbol - as the target. - next_targets - list of targets from which to select - last_target - target from the previous inquiry; used to avoid selecting - the same target consecutively. - - Returns target symbol + inquiry (List[str]): List of symbols to be presented. + target_position (Optional[int]): Optional position within the list of the target symbol. + symbols (List[str]): Used if position is not provided to select a random symbol as the target. + next_targets (Optional[List[str]], optional): List of targets from which to select. Defaults to None. + last_target (Optional[str], optional): Target from the previous inquiry. Defaults to None. + + Returns: + str: Target symbol. """ if target_position is None: return random.choice(list(set(symbols) - set(inquiry))) @@ -851,11 +854,12 @@ def generate_inquiry_stim_timing(time_stim: float, length: int, """Generate stimuli timing values for a given inquiry. Args: - time_stim: seconds to display each stimuli - length: Number of timings to generate - jitter: whether the timing should be jittered. + time_stim (float): Seconds to display each stimulus. + length (int): Number of timings to generate. + jitter (bool): Whether the timing should be jittered. - Returns list of times (in seconds) + Returns: + List[float]: List of times (in seconds). """ if jitter: return jittered_timing(time_stim, jitter, length) @@ -865,10 +869,15 @@ def generate_inquiry_stim_timing(time_stim: float, length: int, def jittered_timing(time: float, jitter: float, stim_count: int) -> List[float]: - """Jittered timing. + """Generate a list of jittered timing values for stimuli. + + Args: + time (float): Base time for each stimulus. + jitter (float): Jitter to apply. + stim_count (int): Number of stimuli. - Using a base time and a jitter, generate a list (with length stim_count) of - timing that is uniformly distributed. + Returns: + List[float]: List of jittered timing values. """ assert time > jitter, ( f'Jitter timing [{jitter}] must be less than stimuli timing =[{time}] in the inquiry.' @@ -880,15 +889,14 @@ def jittered_timing(time: float, jitter: float, def compute_counts(inquiry_count: int, percentage_without_target: int) -> Tuple[int, int]: - """Determine the number of inquiries that should display targets and the - number that should not. + """Determine the number of inquiries that should display targets and the number that should not. Args: - inquiry_count: Number of inquiries in calibration - percentage_without_target: percentage of inquiries for which - target letter flashed is not in inquiry + inquiry_count (int): Number of inquiries in calibration. + percentage_without_target (int): Percentage of inquiries without a target. - Returns tuple of (target_count, no_target_count) + Returns: + Tuple[int, int]: Tuple of (target_count, no_target_count). """ no_target_count = int(inquiry_count * (percentage_without_target / 100)) target_count = inquiry_count - no_target_count @@ -898,17 +906,16 @@ def compute_counts(inquiry_count: int, def generate_target_positions(inquiry_count: int, stim_per_inquiry: int, percentage_without_target: int, distribution: TargetPositions) -> List[int]: - """ - Generates target positions distributed according to the provided parameter. + """Generate target positions distributed according to the provided parameter. Args: - inquiry_count: Number of inquiries in calibration - stim_per_inquiry: Number of stimuli in each inquiry - percentage_without_target: percentage of inquiries for which - target letter flashed is not in inquiry - distribution: specifies how targets should be distributed + inquiry_count (int): Number of inquiries in calibration. + stim_per_inquiry (int): Number of stimuli in each inquiry. + percentage_without_target (int): Percentage of inquiries without a target. + distribution (TargetPositions): Specifies how targets should be distributed. - Returns list of indexes + Returns: + List[int]: List of indexes for target positions. """ if distribution is TargetPositions.DISTRIBUTED: return distributed_target_positions(inquiry_count, stim_per_inquiry, @@ -919,65 +926,51 @@ def generate_target_positions(inquiry_count: int, stim_per_inquiry: int, def distributed_target_positions(inquiry_count: int, stim_per_inquiry: int, percentage_without_target: int) -> list: - """Distributed Target Positions. - - Generates evenly distributed target positions, including target letter - not flashed at all, and shuffles them. + """Generate evenly distributed target positions, including target letter not flashed at all, and shuffle them. Args: - inquiry_count(int): Number of inquiries in calibration - stim_per_inquiry(int): Number of stimuli in each inquiry - percentage_without_target(int): percentage of inquiries for which - target letter flashed is not in inquiry + inquiry_count (int): Number of inquiries in calibration. + stim_per_inquiry (int): Number of stimuli in each inquiry. + percentage_without_target (int): Percentage of inquiries without a target. - Return distributed_target_positions(list): targets: array of target - indexes to be chosen + Returns: + list: Targets array of target indexes to be chosen. """ - targets = [] - # find number of target and no_target inquiries target_count, no_target_count = compute_counts(inquiry_count, percentage_without_target) - # find number each target position is repeated, and remaining number num_pos = (int)(target_count / stim_per_inquiry) num_rem_pos = (target_count % stim_per_inquiry) - # add correct number of None's for nontarget inquiries targets = [NO_TARGET_INDEX] * no_target_count - # add distributed list of target positions targets.extend(list(range(stim_per_inquiry)) * num_pos) - # pick leftover positions randomly rem_pos = list(range(stim_per_inquiry)) random.shuffle(rem_pos) rem_pos = rem_pos[0:num_rem_pos] targets.extend(rem_pos) - # shuffle targets random.shuffle(targets) - return targets def random_target_positions(inquiry_count: int, stim_per_inquiry: int, percentage_without_target: int) -> list: - """Generates randomly distributed target positions, including target letter - not flashed at all, and shuffles them. + """Generate randomly distributed target positions, including target letter not flashed at all, and shuffle them. Args: - inquiry_count(int): Number of inquiries in calibration - stim_per_inquiry(int): Number of stimuli in each inquiry - percentage_without_target(int): percentage of inquiries for which - target letter flashed is not in inquiry + inquiry_count (int): Number of inquiries in calibration. + stim_per_inquiry (int): Number of stimuli in each inquiry. + percentage_without_target (int): Percentage of inquiries without a target. - Return list of target indexes to be chosen + Returns: + list: List of target indexes to be chosen. """ target_count, no_target_count = compute_counts(inquiry_count, percentage_without_target) - target_indexes = [NO_TARGET_INDEX] * no_target_count target_indexes.extend( random.choices(range(stim_per_inquiry), k=target_count)) @@ -987,20 +980,18 @@ def random_target_positions(inquiry_count: int, stim_per_inquiry: int, def generate_targets(symbols: List[str], inquiry_count: int, percentage_without_target: int) -> List[str]: - """Generates list of target symbols. Generates an equal number of each - target. The resulting list may be less than the inquiry_count. Used for - sampling without replacement to get approximately equal numbers of each - target. + """Generate a list of target symbols for calibration inquiries. Args: - symbols: - inquiry_count: number of inquiries in calibration - percentage_without_target: percentage of inquiries for which - target letter flashed is not in inquiry + symbols (List[str]): List of possible symbols. + inquiry_count (int): Number of inquiries in calibration. + percentage_without_target (int): Percentage of inquiries without a target. + + Returns: + List[str]: List of target symbols. """ target_count, no_target_count = compute_counts(inquiry_count, percentage_without_target) - # each symbol should appear at least once symbol_count = int(target_count / len(symbols)) or 1 targets = symbols * symbol_count @@ -1009,19 +1000,13 @@ def generate_targets(symbols: List[str], inquiry_count: int, def target_index(inquiry: List[str]) -> Optional[int]: - """Given an inquiry, return the index of the target within the choices and - None if the target is not included as a choice. - - Parameters - ---------- - inquiry - list of [target, fixation, *choices] - - >>> inquiry = ['T', '+', 'G', 'J', 'K', 'L', 'M', 'Q', 'T', 'V', 'X', '<'] - >>> target_index(inquiry) - 6 - >>> inquiry = ['A', '+', 'G', 'J', 'K', 'L', 'M', 'Q', 'T', 'V', 'X', '<'] - >>> target_index(inquiry) - None + """Return the index of the target within the choices, or None if not present. + + Args: + inquiry (List[str]): List of [target, fixation, *choices]. + + Returns: + Optional[int]: Index of the target in choices, or None if not present. """ assert len(inquiry) > 3, "Not enough choices" target, _fixation, *choices = inquiry @@ -1032,19 +1017,15 @@ def target_index(inquiry: List[str]) -> Optional[int]: def get_task_info(experiment_length: int, task_color: str) -> Tuple[List[str], List[str]]: - """Get Task Info. + """Generate fixed RSVPKeyboard task text and color information for display. - Generates fixed RSVPKeyboard task text and color information for - display. Args: - experiment_length(int): Number of inquiries for the experiment - task_color(str): Task information display color + experiment_length (int): Number of inquiries for the experiment. + task_color (str): Task information display color. - Return get_task_info((tuple): task_text: array of task text to display - task_color: array of colors for the task text - ) + Returns: + Tuple[List[str], List[str]]: Tuple of task text and color arrays. """ - # Do list comprehensions to get the arrays for the task we need. task_text_list = ['%s/%s' % (stim + 1, experiment_length) for stim in range(experiment_length)] @@ -1054,11 +1035,16 @@ def get_task_info(experiment_length: int, task_color: str) -> Tuple[List[str], L def resize_image(image_path: str, screen_size: tuple, sti_height: float) -> Tuple[float, float]: - """Resize Image. + """Return the width and height that a given image should be displayed at given the screen size and stimuli height. + + Args: + image_path (str): Path to the image file. + screen_size (tuple): Screen size as (width, height). + sti_height (float): Desired stimuli height. - Returns the width and height that a given image should be displayed at - given the screen size, size of the original image, and stimuli height - parameter""" + Returns: + Tuple[float, float]: Width and height for displaying the image. + """ # Retrieve image width and height with Image.open(image_path) as pillow_image: image_width, image_height = pillow_image.size @@ -1091,43 +1077,35 @@ def play_sound(sound_file_path: str, experiment_clock=None, trigger_name: Optional[str] = None, timing: list = []) -> list: - """Play Sound. - - Using soundevice and soundfile, play a sound giving options to buffer times between - loading sound into memory and after playing. If desired, marker writers or list based - timing with psychopy clocks may be passed and sound timing returned. - - - PARAMETERS - ---------- - :param: sound_file_path - :param: dtype: type of sound ex. float32. - :param: track_timing: whether or not to track timing of sound playin - :param: sound_callback: trigger based callback (see MarkerWriter and NullMarkerWriter) - :param: sound_load_buffer_time: time to wait after loading file before playing - :param: experiment_clock: psychopy clock to get time of sound stimuli - :param: trigger_name: name of the sound trigger - :param: timing: list of triggers in the form of trigger name, trigger timing - :resp: timing - """ + """Play a sound file and optionally track timing and triggers. + + Args: + sound_file_path (str): Path to the sound file. + dtype (str, optional): Type of sound (e.g., 'float32'). Defaults to 'float32'. + track_timing (bool, optional): Whether to track timing of sound playing. Defaults to False. + sound_callback (optional): Callback for sound triggers. Defaults to None. + sound_load_buffer_time (float, optional): Time to wait after loading file before playing. Defaults to 0.5. + experiment_clock (optional): Clock to get time of sound stimuli. Defaults to None. + trigger_name (Optional[str], optional): Name of the sound trigger. Defaults to None. + timing (list, optional): List of triggers in the form of trigger name, trigger timing. Defaults to []. + Returns: + list: Timing information for sound triggers. + """ try: # load in the sound file and wait some time before playing data, fs = sf.read(sound_file_path, dtype=dtype) core.wait(sound_load_buffer_time) - except Exception as e: error_message = f'Sound file could not be found or initialized. \n Exception={e}' log.exception(error_message) raise BciPyCoreException(error_message) - # if timing is wanted, get trigger timing for this sound stimuli if track_timing: # if there is a timing callback for sound, evoke it if sound_callback is not None: sound_callback(experiment_clock, trigger_name) timing.append([trigger_name, experiment_clock.getTime()]) - # play our loaded sound and wait for some time before it's finished # NOTE: there is a measurable delay for calling sd.play. (~ 0.1 seconds; # which I believe happens prior to the sound playing). @@ -1139,15 +1117,13 @@ def play_sound(sound_file_path: str, def soundfiles(directory: str) -> Iterator[str]: - """Creates a generator that cycles through sound files (.wav) in a - directory and returns the path to next sound file on each iteration. + """Return an iterator cycling through .wav files in a directory. + + Args: + directory (str): Path to the directory containing .wav files. - Parameters: - ----------- - directory - path to the directory which contains .wav files Returns: - -------- - iterator that infinitely cycles through the filenames. + Iterator[str]: Iterator that infinitely cycles through the filenames. """ if not path.isdir(directory): error_message = f'Invalid directory=[{directory}] for sound files.' @@ -1159,9 +1135,13 @@ def soundfiles(directory: str) -> Iterator[str]: def get_fixation(is_txt: bool) -> str: - """Get Fixation. + """Return the correct stimulus fixation given the type (text or image). + + Args: + is_txt (bool): Whether the fixation is text or image. - Return the correct stimulus fixation given the type (text or image). + Returns: + str: Fixation stimulus (text or image path). """ if is_txt: return DEFAULT_TEXT_FIXATION diff --git a/bcipy/core/symbols.py b/bcipy/core/symbols.py new file mode 100644 index 000000000..1b642e4fe --- /dev/null +++ b/bcipy/core/symbols.py @@ -0,0 +1,99 @@ +"""Defines helper methods and variables related to input symbols""" +import os +from string import ascii_uppercase +from typing import Any, Callable, List, Optional + +SPACE_CHAR = '_' +BACKSPACE_CHAR = '<' + + +def alphabet(parameters: Optional[Any] = None, include_path: bool = True, + backspace: str = BACKSPACE_CHAR, space: str = SPACE_CHAR) -> List[str]: + """Standardizes and returns the alphabet symbols used in BciPy. + + The symbols can either be text (uppercase ASCII letters, backspace, and space) + or paths to image files, depending on the `parameters` and `is_txt_stim` setting. + + Args: + parameters (Optional[Any], optional): A dictionary-like object containing configuration + parameters, specifically 'is_txt_stim' and 'path_to_presentation_images'. + Defaults to None. + include_path (bool, optional): If True and image stimuli are used, returns full paths to images. + If False, returns just the image filenames without extensions. Defaults to True. + backspace (str, optional): The character representing backspace. Defaults to `BACKSPACE_CHAR`. + space (str, optional): The character representing space. Defaults to `SPACE_CHAR`. + + Returns: + List[str]: A list of alphabet symbols (either letters or image paths). + """ + if parameters and not parameters['is_txt_stim']: + # construct an array of paths to images + path = parameters['path_to_presentation_images'] + stimulus_array: List[str] = [] + for stimulus_filename in sorted(os.listdir(path)): + # PLUS.png is reserved for the fixation symbol + if stimulus_filename.endswith( + '.png') and not stimulus_filename.endswith('PLUS.png'): + if include_path: + img = os.path.join(path, stimulus_filename) + else: + img = os.path.splitext(stimulus_filename)[0] + stimulus_array.append(img) + return stimulus_array + + return list(ascii_uppercase) + [backspace, space] + + +def qwerty_order(is_txt_stim: bool = True, + space: str = SPACE_CHAR, + backspace: str = BACKSPACE_CHAR) -> Callable[[str], int]: + """Returns a function that can be used to sort alphabet symbols in QWERTY order. + + Note that sorting only works for text stimuli. + + Args: + is_txt_stim (bool, optional): If True, indicates text stimuli. Defaults to True. + space (str, optional): The character representing space. Defaults to `SPACE_CHAR`. + backspace (str, optional): The character representing backspace. Defaults to `BACKSPACE_CHAR`. + + Returns: + Callable[[str], int]: A function that takes a symbol string and returns its QWERTY index. + + Raises: + NotImplementedError: If `is_txt_stim` is False, as QWERTY ordering is not implemented for images. + """ + if not is_txt_stim: + raise NotImplementedError('QWERTY ordering not implemented for images') + + row1 = "QWERTYUIOP" + row2 = f"ASDFGHJKL{backspace}" + row3 = f" ZXCV{space}BNM " + return f"{row1}{row2}{row3}".index + + +def frequency_order( + is_txt_stim: bool = True, + space: str = SPACE_CHAR, + backspace: str = BACKSPACE_CHAR) -> Callable[[str], int]: + """Returns a function that can be used to sort alphabet symbols by frequency of use in English." + + Note that sorting only works for text stimuli. + + Args: + is_txt_stim (bool, optional): If True, indicates text stimuli. Defaults to True. + space (str, optional): The character representing space. Defaults to `SPACE_CHAR`. + backspace (str, optional): The character representing backspace. Defaults to `BACKSPACE_CHAR`. + + Returns: + Callable[[str], int]: A function that takes a symbol string and returns its frequency order index. + + Raises: + NotImplementedError: If `is_txt_stim` is False, as frequency ordering is not implemented for images. + """ + if not is_txt_stim: + raise NotImplementedError( + 'Frequency ordering not implemented for images') + return f"ETAOINSHRDLCUMWFGYPBVKJXQZ{backspace}{space}".index + + +DEFAULT_SYMBOL_SET = alphabet() diff --git a/bcipy/helpers/tests/resources/mock_session/parameters.json b/bcipy/core/tests/resources/mock_session/parameters.json similarity index 96% rename from bcipy/helpers/tests/resources/mock_session/parameters.json rename to bcipy/core/tests/resources/mock_session/parameters.json index 9331fe714..99b99a237 100644 --- a/bcipy/helpers/tests/resources/mock_session/parameters.json +++ b/bcipy/core/tests/resources/mock_session/parameters.json @@ -680,7 +680,7 @@ "recommended": [ "UNIFORM", "CAUSAL", - "KENLM", + "NGRAM", "MIXTURE", "ORACLE" ], diff --git a/bcipy/helpers/tests/resources/mock_session/session.csv b/bcipy/core/tests/resources/mock_session/session.csv similarity index 100% rename from bcipy/helpers/tests/resources/mock_session/session.csv rename to bcipy/core/tests/resources/mock_session/session.csv diff --git a/bcipy/helpers/tests/resources/mock_session/session.json b/bcipy/core/tests/resources/mock_session/session.json similarity index 100% rename from bcipy/helpers/tests/resources/mock_session/session.json rename to bcipy/core/tests/resources/mock_session/session.json diff --git a/bcipy/helpers/tests/test_list.py b/bcipy/core/tests/test_list.py similarity index 54% rename from bcipy/helpers/tests/test_list.py rename to bcipy/core/tests/test_list.py index 5fcc397cb..8759b2795 100644 --- a/bcipy/helpers/tests/test_list.py +++ b/bcipy/core/tests/test_list.py @@ -1,6 +1,8 @@ """Tests for list processing utilities""" import unittest -from bcipy.helpers.list import destutter, grouper + +from bcipy.core.list import (destutter, expanded, find_index, grouper, + pairwise, swapped) class TestListUtilities(unittest.TestCase): @@ -48,7 +50,8 @@ def test_grouper_incomplete_ignore(self): for resp, exp in zip(response, expected): self.assertEqual(resp, exp) - def test_grouper_incomplete_value_error_unsupported_incompelte_mode_defined(self): + def test_grouper_incomplete_value_error_unsupported_incompelte_mode_defined( + self): iterable = 'ABCDEFG' chunk_size = 2 incomplete = 'not_defined' @@ -56,6 +59,46 @@ def test_grouper_incomplete_value_error_unsupported_incompelte_mode_defined(self with self.assertRaises(ValueError): grouper(iterable, chunk_size, incomplete=incomplete) + def test_find_index(self): + """Test find index of item""" + self.assertEqual(2, find_index([1, 2, 3, 4], 3)) + + def test_find_index_using_key(self): + """Find index using the key arg""" + item1 = dict(a=10, b=10) + item2 = dict(a=10, b=20) + item3 = dict(a=20, b=10) + item4 = dict(a=20, b=20) + self.assertEqual( + 1, + find_index([item1, item2, item3, item4], + match_item=20, + key=lambda item: item['b'])) + + def test_find_index_matching_predicate(self): + """Find the index of the first item matching a predicate""" + values = [5, 7, 9, 12] + self.assertEqual(1, find_index(values, match_item=lambda val: val > 6)) + + def test_swapped(self): + """Test swapped function.""" + self.assertEqual([1, 2, 3, 4, 5], swapped([1, 2, 3, 4, 5], 0, 0)) + self.assertEqual([1, 4, 3, 2, 5], swapped([1, 2, 3, 4, 5], 1, 3)) + self.assertEqual([1, 2, 3, 4, 5], swapped([1, 2, 3, 4, 5], 4, 4)) + self.assertEqual([1, 2, 3, 4, 5], swapped([5, 2, 3, 4, 1], 0, 4)) + + def test_expanded(self): + """Test expanded function.""" + self.assertEqual([1, 2, 3, 3, 3], expanded([1, 2, 3], length=5)) + + def test_pairwise(self): + """Test pairwise iterator""" + iterable = 'ABCDEFG' + response = pairwise(iterable) + expected = [('A', 'B'), ('B', 'C'), ('C', 'D'), + ('D', 'E'), ('E', 'F'), ('F', 'G')] + self.assertListEqual(expected, list(response)) + if __name__ == '__main__': unittest.main() diff --git a/bcipy/helpers/tests/test_parameters.py b/bcipy/core/tests/test_parameters.py similarity index 99% rename from bcipy/helpers/tests/test_parameters.py rename to bcipy/core/tests/test_parameters.py index 58b0acbd9..7a70a9a60 100644 --- a/bcipy/helpers/tests/test_parameters.py +++ b/bcipy/core/tests/test_parameters.py @@ -6,7 +6,7 @@ from pathlib import Path from bcipy.config import DEFAULT_PARAMETERS_PATH -from bcipy.helpers.parameters import Parameters, parse_range +from bcipy.core.parameters import Parameters, parse_range class TestParameters(unittest.TestCase): diff --git a/bcipy/helpers/tests/test_raw_data.py b/bcipy/core/tests/test_raw_data.py similarity index 90% rename from bcipy/helpers/tests/test_raw_data.py rename to bcipy/core/tests/test_raw_data.py index 12fc67bb5..2de57891e 100644 --- a/bcipy/helpers/tests/test_raw_data.py +++ b/bcipy/core/tests/test_raw_data.py @@ -7,12 +7,12 @@ import numpy as np import pandas as pd +from mockito import any, mock, unstub, verify, when -from mockito import any, mock, when, verify, unstub - +from bcipy.core.raw_data import (RawData, RawDataReader, RawDataWriter, + get_1020_channel_map, get_1020_channels, load, + sample_data, settings, write) from bcipy.exceptions import BciPyCoreException -from bcipy.helpers.raw_data import (RawData, RawDataReader, RawDataWriter, - load, sample_data, settings, write) class TestRawData(unittest.TestCase): @@ -312,7 +312,8 @@ def test_data_by_channel_applies_transformation(self): transform = mock() # note data here should be returned as a nd.array. for mocking we don't care as much - when(RawData).apply_transform(any(), transform).thenReturn((data, self.sample_rate)) + when(RawData).apply_transform( + any(), transform).thenReturn((data, self.sample_rate)) resp, fs = data.by_channel(transform=transform) self.assertEqual(self.sample_rate, fs) @@ -369,13 +370,36 @@ def test_data_by_channel_map_applies_transformation(self): transform = mock() expected_output, expected_fs = data.by_channel() # note data here should be returned as a nd.array. for mocking we don't care as much - when(RawData).by_channel(transform).thenReturn((expected_output, expected_fs)) - _, channels, fs = data.by_channel_map(channel_map=channel_map, transform=transform) + when(RawData).by_channel(transform).thenReturn( + (expected_output, expected_fs)) + _, channels, fs = data.by_channel_map( + channel_map=channel_map, transform=transform) self.assertEqual(expected_fs, fs) self.assertEqual(expected_channels, channels) verify(RawData, times=1).by_channel(transform) +class Test1020(unittest.TestCase): + """Tests for 10-20 channel mapping functions.""" + + def test_get_1020_channels(self): + """Tests that the 10-20 channel map is correctly generated.""" + channels = get_1020_channels() + self.assertEqual(27, len(channels)) + self.assertTrue(isinstance(channels[0], str)) + + def test_get_1020_channel_map(self): + """Tests that the 10-20 channel map is correctly generated.""" + # all but the last channel are valid 10-20 channels + channels = ['Fp1', 'Fp2', 'F3', 'F4', 'C3', + 'C4', 'P3', 'P4', 'O1', 'invalid'] + channel_map = get_1020_channel_map(channels) + self.assertEqual(10, len(channel_map)) + self.assertEqual(0, channel_map[-1]) + for i in range(len(channels) - 1): + self.assertEqual(1, channel_map[i]) + + if __name__ == '__main__': unittest.main() diff --git a/bcipy/helpers/tests/test_report.py b/bcipy/core/tests/test_report.py similarity index 90% rename from bcipy/helpers/tests/test_report.py rename to bcipy/core/tests/test_report.py index 3d28833d4..a181d8c7f 100644 --- a/bcipy/helpers/tests/test_report.py +++ b/bcipy/core/tests/test_report.py @@ -1,15 +1,15 @@ import os +import shutil +import tempfile import unittest from unittest.mock import patch -import tempfile -import shutil import matplotlib.pyplot as plt import numpy as np -from reportlab.platypus import Paragraph, Image -from reportlab.platypus import Flowable, KeepTogether +from reportlab.platypus import Flowable, Image, KeepTogether, Paragraph -from bcipy.helpers.report import Report, SessionReportSection, ReportSection, SignalReportSection +from bcipy.core.report import (Report, ReportSection, SessionReportSection, + SignalReportSection) class TestReport(unittest.TestCase): @@ -61,7 +61,8 @@ def test_add_section(self): self.assertEqual(report.sections, [report_section]) another_report_section = SessionReportSection(summary=summary) report.add(another_report_section) - self.assertEqual(report.sections, [report_section, another_report_section]) + self.assertEqual(report.sections, [ + report_section, another_report_section]) def test_save(self): report = Report(self.temp_dir) @@ -69,12 +70,14 @@ def test_save(self): report_section = SessionReportSection(summary) report.add(report_section) report.save() - self.assertTrue(os.path.exists(os.path.join(self.temp_dir, report.name))) + self.assertTrue(os.path.exists( + os.path.join(self.temp_dir, report.name))) def test_save_no_sections(self): report = Report(self.temp_dir) report.save() - self.assertTrue(os.path.exists(os.path.join(self.temp_dir, report.name))) + self.assertTrue(os.path.exists( + os.path.join(self.temp_dir, report.name))) def test_complile_adds_section_and_header(self): report = Report(self.temp_dir) @@ -90,7 +93,7 @@ def test_complile_adds_section_and_header(self): self.assertEqual(len(report.elements), 2) def test_create_header_is_called_once_compile(self): - with patch('bcipy.helpers.report.Report._construct_report_header') as mock_construct_header: + with patch('bcipy.core.report.Report._construct_report_header') as mock_construct_header: report = Report(self.temp_dir) summary = { 'session': 'session_name', diff --git a/bcipy/helpers/tests/test_session.py b/bcipy/core/tests/test_session.py similarity index 95% rename from bcipy/helpers/tests/test_session.py rename to bcipy/core/tests/test_session.py index 0554fffe7..28f42cb31 100644 --- a/bcipy/helpers/tests/test_session.py +++ b/bcipy/core/tests/test_session.py @@ -8,7 +8,7 @@ from pathlib import Path from bcipy.config import SESSION_DATA_FILENAME -from bcipy.helpers.session import read_session, session_csv, session_data +from bcipy.core.session import read_session, session_csv, session_data class TestSessionHelper(unittest.TestCase): diff --git a/bcipy/helpers/tests/test_stimuli.py b/bcipy/core/tests/test_stimuli.py similarity index 95% rename from bcipy/helpers/tests/test_stimuli.py rename to bcipy/core/tests/test_stimuli.py index 2c1dc5b2f..5f53a289d 100644 --- a/bcipy/helpers/tests/test_stimuli.py +++ b/bcipy/core/tests/test_stimuli.py @@ -9,19 +9,18 @@ from mockito import any, mock, unstub, verify, when from psychopy import core +from bcipy.core.stimuli import (DEFAULT_FIXATION_PATH, InquiryReshaper, + StimuliOrder, TargetPositions, TrialReshaper, + alphabetize, best_case_rsvp_inq_gen, + best_selection, distributed_target_positions, + generate_calibration_inquiries, + generate_inquiry, generate_targets, + get_fixation, inquiry_nontarget_counts, + inquiry_target, inquiry_target_counts, + jittered_timing, play_sound, + random_target_positions, soundfiles, + target_index, update_inquiry_timing) from bcipy.exceptions import BciPyCoreException -from bcipy.helpers.stimuli import (DEFAULT_FIXATION_PATH, InquiryReshaper, - StimuliOrder, TargetPositions, - TrialReshaper, alphabetize, - best_case_rsvp_inq_gen, best_selection, - distributed_target_positions, - generate_calibration_inquiries, - generate_inquiry, generate_targets, - get_fixation, inquiry_nontarget_counts, - inquiry_target, inquiry_target_counts, - jittered_timing, play_sound, - random_target_positions, soundfiles, - target_index, update_inquiry_timing) MOCK_FS = 44100 @@ -501,11 +500,13 @@ def test_random_target_positions_all_nontargets(self): def test_generate_targets(self): """Test target generation""" symbols = ['A', 'B', 'C', 'D'] - targets = generate_targets(symbols, inquiry_count=9, percentage_without_target=0) + targets = generate_targets( + symbols, inquiry_count=9, percentage_without_target=0) self.assertEqual(len(targets), 8) self.assertTrue(all(val == 2 for val in Counter(targets).values())) - targets = generate_targets(symbols, inquiry_count=9, percentage_without_target=50) + targets = generate_targets( + symbols, inquiry_count=9, percentage_without_target=50) self.assertEqual(len(targets), 4) self.assertTrue(all(val == 1 for val in Counter(targets).values())) @@ -537,7 +538,8 @@ def test_inquiry_target_with_none_position(self): target = inquiry_target(inquiry, None, symbols, next_targets) self.assertTrue(target not in inquiry) self.assertTrue(target in symbols) - self.assertSequenceEqual(inquiry, ['C', 'A', 'F', 'E'], 'inquiry should not have changed') + self.assertSequenceEqual( + inquiry, ['C', 'A', 'F', 'E'], 'inquiry should not have changed') def test_inquiry_target_missing(self): """Test inquiry target where none of the next_targets are present in @@ -551,8 +553,10 @@ def test_inquiry_target_missing(self): next_targets=next_targets) self.assertTrue(target in inquiry) self.assertTrue(target not in next_targets) - self.assertSequenceEqual(inquiry, ['C', 'A', 'F', 'E'], 'inquiry should not have changed') - self.assertSequenceEqual(next_targets, ['Q', 'D'], 'next_targets should not have changed') + self.assertSequenceEqual( + inquiry, ['C', 'A', 'F', 'E'], 'inquiry should not have changed') + self.assertSequenceEqual( + next_targets, ['Q', 'D'], 'next_targets should not have changed') def test_inquiry_target_no_targets(self): """Test inquiry_target when no next_targets are provided""" @@ -563,8 +567,10 @@ def test_inquiry_target_no_targets(self): target_position=0, symbols=symbols, next_targets=next_targets) - self.assertEqual(target, 'C', 'should have used the target_position to get the target') - self.assertSequenceEqual(inquiry, ['C', 'A', 'F', 'E'], 'inquiry should not have changed') + self.assertEqual( + target, 'C', 'should have used the target_position to get the target') + self.assertSequenceEqual( + inquiry, ['C', 'A', 'F', 'E'], 'inquiry should not have changed') def test_inquiry_target_last_target(self): """Test inquiry target behavior.""" @@ -777,7 +783,8 @@ def test_best_case_inq_gen_is_random(self): is_txt=True, inq_constants=['<']) samps.add(tuple(samples[0])) - self.assertTrue(len(samps) > 1, '`best_case_rsvp_inq_gen` Should produce random results') + self.assertTrue( + len(samps) > 1, '`best_case_rsvp_inq_gen` Should produce random results') class TestJitteredTiming(unittest.TestCase): @@ -895,7 +902,8 @@ def test_trial_reshaper_with_no_channel_map(self): poststimulus_length=trial_length_s ) trial_length_samples = int(sample_rate * trial_length_s) - expected_shape = (self.channel_number, len(self.target_info), trial_length_samples) + expected_shape = (self.channel_number, len( + self.target_info), trial_length_samples) self.assertTrue(np.all(labels == [1, 0, 0])) self.assertTrue(reshaped_trials.shape == expected_shape) @@ -973,7 +981,8 @@ def test_inquiry_reshaper_with_no_channel_map(self): channel_map=None, poststimulus_length=self.trial_length ) - expected_shape = (self.n_channel, self.n_inquiry, self.samples_per_inquiry) + expected_shape = (self.n_channel, self.n_inquiry, + self.samples_per_inquiry) self.assertTrue(reshaped_data.shape == expected_shape) self.assertTrue(np.all(labels == self.true_labels)) diff --git a/bcipy/helpers/tests/test_symbols.py b/bcipy/core/tests/test_symbols.py similarity index 95% rename from bcipy/helpers/tests/test_symbols.py rename to bcipy/core/tests/test_symbols.py index 8fda98230..f3cfce7a0 100644 --- a/bcipy/helpers/tests/test_symbols.py +++ b/bcipy/core/tests/test_symbols.py @@ -1,6 +1,6 @@ import unittest -from bcipy.helpers.symbols import alphabet +from bcipy.core.symbols import alphabet class TestAlphabet(unittest.TestCase): diff --git a/bcipy/helpers/tests/test_triggers.py b/bcipy/core/tests/test_triggers.py similarity index 94% rename from bcipy/helpers/tests/test_triggers.py rename to bcipy/core/tests/test_triggers.py index 478015733..9f33fd0b1 100644 --- a/bcipy/helpers/tests/test_triggers.py +++ b/bcipy/core/tests/test_triggers.py @@ -5,14 +5,13 @@ import psychopy from mockito import any, mock, unstub, verify, when +from bcipy.core.triggers import (FlushFrequency, Trigger, TriggerHandler, + TriggerType, _calibration_trigger, + apply_offsets, exclude_types, + find_starting_offset, offset_device, + offset_label, read, read_data, + starting_offsets_by_device, trigger_decoder) from bcipy.exceptions import BciPyCoreException -from bcipy.helpers.triggers import (FlushFrequency, Trigger, TriggerHandler, - TriggerType, _calibration_trigger, - apply_offsets, exclude_types, - find_starting_offset, offset_device, - offset_label, read, read_data, - starting_offsets_by_device, - trigger_decoder) class TestCalibrationTrigger(unittest.TestCase): @@ -171,8 +170,10 @@ def setUp(self, mock_file): self.flush = FlushFrequency.END self.file = f'{self.path_name}/{self.file_name}.txt' # with patch('builtins.open', mock_open(read_data='data')) as _: - self.handler = TriggerHandler(self.path_name, self.file_name, self.flush) - self.mock_file.assert_called_once_with(self.file, 'w+', encoding=self.handler.encoding) + self.handler = TriggerHandler( + self.path_name, self.file_name, self.flush) + self.mock_file.assert_called_once_with( + self.file, 'w+', encoding=self.handler.encoding) def tearDown(self): unstub() @@ -180,7 +181,8 @@ def tearDown(self): def test_file_exist_exception(self): with open(self.file, 'w+', encoding=self.handler.encoding) as _: with self.assertRaises(Exception): - TriggerHandler(self.path_name, self.file_name, FlushFrequency.END) + TriggerHandler(self.path_name, self.file_name, + FlushFrequency.END) os.remove(self.file) def test_add_triggers_returns_list_of_triggers(self): @@ -205,7 +207,7 @@ def test_add_triggers_calls_write_when_flush_every(self): verify(self.handler, times=1).write() - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_load_returns_list_of_triggers(self, path_exists_mock): """Test static load method""" path_exists_mock.returnValue = True @@ -217,7 +219,7 @@ def test_load_returns_list_of_triggers(self, path_exists_mock): response = self.handler.load('test_path_not_real.txt') self.assertEqual(response[0], trg) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_load_applies_offset(self, path_exists_mock): """Test that static load method applies offsets""" path_exists_mock.returnValue = True @@ -228,7 +230,7 @@ def test_load_applies_offset(self, path_exists_mock): response = self.handler.load('test_path_not_real.txt', offset=1) self.assertEqual(response[0].time, 2.5) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_load_exclusion(self, path_exists_mock): """Test that static load can exclude trigger types""" path_exists_mock.returnValue = True @@ -241,7 +243,7 @@ def test_load_exclusion(self, path_exists_mock): exclusion=[TriggerType.NONTARGET]) self.assertEqual(response[0], fixation_trg) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_read_data(self, path_exists_mock): """Test that trigger data is correctly read.""" trg_data = '''starting_offset offset 3.47 @@ -263,7 +265,7 @@ def test_read_data(self, path_exists_mock): self.assertEqual(triggers[1].time, 6.15) self.assertEqual(offset, 3.47) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_read_data_bad_format(self, path_exists_mock): """Test that exception is thrown when trigger type doesn't exist.""" trg_data = '''start_offset offset @@ -278,7 +280,7 @@ def test_read_data_bad_format(self, path_exists_mock): self.assertIn("line 1", ctx.exception.message) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_read_data_bad_trigger_type(self, path_exists_mock): """Test that exception is thrown when trigger type doesn't exist.""" trg_data = '''start_offset offset 3.47 @@ -293,7 +295,7 @@ def test_read_data_bad_trigger_type(self, path_exists_mock): self.assertIn("line 3", ctx.exception.message) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_read_data_bad_timestamp(self, path_exists_mock): """Test that exception is thrown when timestamp can't be converted.""" trg_data = '''starting_offset offset 3.47 @@ -309,7 +311,7 @@ def test_read_data_bad_timestamp(self, path_exists_mock): self.assertIn("line 2", ctx.exception.message) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_read_data_unicode(self, path_exists_mock): """Test that trigger data is correctly read.""" trg_data = '''starting_offset offset 3.47 @@ -391,7 +393,7 @@ def test_read_data_exception(self): with self.assertRaises(BciPyCoreException): read_data(trg_data.split('\n')) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_read_from_file(self, path_exists_mock): """Test reading triggers from a file""" trg_data = '''starting_offset offset 3.47 @@ -479,7 +481,8 @@ def test_starting_offsets_by_device_defaults(self): """Test default values""" triggers = read_data('''J prompt 6.15 + fixation 8.11'''.split('\n')) - offsets = starting_offsets_by_device(triggers, device_types=['EEG', 'EYETRACKER']) + offsets = starting_offsets_by_device( + triggers, device_types=['EEG', 'EYETRACKER']) self.assertEqual(len(offsets), 2) self.assertEqual(offsets['EEG'].time, 0.0) self.assertEqual(offsets['EYETRACKER'].time, 0.0) @@ -540,7 +543,7 @@ def test_exclude_types(self): all(trg.type in [TriggerType.NONTARGET, TriggerType.TARGET] for trg in filtered)) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_trigger_decoder_defaults(self, path_exists_mock): """Test trigger decoder""" trg_data = '''starting_offset offset -3.47 @@ -566,7 +569,7 @@ def test_trigger_decoder_defaults(self, path_exists_mock): self.assertAlmostEqual(times[0], 5.11) self.assertAlmostEqual(times[-1], 7.83) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_trigger_decoder_with_device(self, path_exists_mock): """Test trigger decoder""" trg_data = '''starting_offset offset -3.47 @@ -593,7 +596,7 @@ def test_trigger_decoder_with_device(self, path_exists_mock): self.assertAlmostEqual(times[0], 4.13) self.assertAlmostEqual(times[-1], 6.85) - @patch('bcipy.helpers.triggers.os.path.exists') + @patch('bcipy.core.triggers.os.path.exists') def test_trigger_decoder_without_starting_offset(self, path_exists_mock): """Test trigger decoder""" trg_data = '''starting_offset offset -3.47 diff --git a/bcipy/core/triggers.py b/bcipy/core/triggers.py new file mode 100644 index 000000000..95363f820 --- /dev/null +++ b/bcipy/core/triggers.py @@ -0,0 +1,682 @@ +"""Trigger utilities for BciPy core. + +This module provides classes and functions for managing triggers and calibration events in BciPy experiments. +""" + +import logging +import os +from enum import Enum +from typing import Callable, Dict, Iterable, List, NamedTuple, Optional, Tuple + +from psychopy import core, visual + +from bcipy.config import DEFAULT_ENCODING, SESSION_LOG_FILENAME +from bcipy.core.parameters import Parameters +from bcipy.core.stimuli import resize_image +from bcipy.exceptions import BciPyCoreException +from bcipy.helpers.clock import Clock + +log = logging.getLogger(SESSION_LOG_FILENAME) + +NONE_VALUES = ['0', '0.0'] + +CALIBRATION_IMAGE_PATH = 'bcipy/static/images/testing/white.png' +MOCK_TRIGGER_DATA = '''starting_offset offset -3635340.451487373 +P prompt 3635343.155564679 ++ fixation 3635344.159978495 +O nontarget 3635344.663714144 +Z nontarget 3635344.917679911 +B nontarget 3635345.172036632 +N nontarget 3635345.425718764 +K nontarget 3635345.679572615 +U nontarget 3635345.932683132 +J nontarget 3635346.186251469 +P target 3635346.439412578 +_ nontarget 3635346.692164597 +T nontarget 3635346.946281828 +daq_sample_offset system 293.6437802789733 +''' + + +class CalibrationType(Enum): + """Calibration Type. + + Enum to define the supported calibration trigger types. + """ + TEXT = 'text' + IMAGE = 'image' + + @classmethod + def list(cls) -> List[str]: + """Returns all enum values as a list. + + Returns: + List[str]: List of all enum values. + """ + return list(map(lambda c: c.value, cls)) + + +class TriggerCallback: + """Callback handler for trigger events. + + Attributes: + timing (Optional[Tuple[str, float]]): Timing information for the trigger. + first_time (bool): Flag indicating if this is the first trigger. + """ + timing: Optional[Tuple[str, float]] = None + first_time: bool = True + + def callback(self, clock: Clock, stimuli: str) -> None: + """Callback function for trigger events. + + Args: + clock (Clock): Clock instance for timing. + stimuli (str): Stimulus identifier. + """ + if self.first_time: + self.timing = (stimuli, clock.getTime()) + self.first_time = False + + def reset(self) -> None: + """Reset the callback state.""" + self.timing = None + self.first_time = True + + +def _calibration_trigger( + experiment_clock: Clock, + trigger_type: str = CalibrationType.TEXT.value, + trigger_name: str = 'calibration', + trigger_time: float = 1, + display: Optional[visual.Window] = None, + on_trigger: Optional[Callable[[str], None]] = None +) -> Tuple[str, float]: + """Calibration Trigger. + + Outputs triggers for the purpose of calibrating data and stimuli. + This is an ongoing difficulty between OS, DAQ devices and stimuli type. This + code aims to operationalize the approach to finding the correct DAQ samples in + relation to our trigger code. + + Args: + experiment_clock (Clock): Clock with getTime() method, which is used in the code + to report timing of stimuli. + trigger_type (str): Type of trigger that is desired (text, image, etc). + trigger_name (str): Name of the trigger used for callbacks / labeling. + trigger_time (float): Time to display the trigger. Can also be used as a buffer. + display (Optional[visual.Window]): A window that can display stimuli. Currently, a Psychopy window. + on_trigger (Optional[Callable[[str], None]]): Optional callback; if present gets called + when the calibration trigger is fired; accepts a single parameter for the timing information. + + Returns: + Tuple[str, float]: Timing values for the calibration triggers to be written to trigger file or + used to calculate offsets. + + Raises: + BciPyCoreException: If trigger type is invalid or display is required but not provided. + """ + trigger_callback = TriggerCallback() + + # catch invalid trigger types + if trigger_type not in CalibrationType.list(): + msg = f'Trigger type=[{trigger_type}] not implemented' + log.exception(msg) + raise BciPyCoreException(msg) + + if not display: + msg = f'Calibration type=[{trigger_type}] requires a display' + log.exception(msg) + raise BciPyCoreException(msg) + + if trigger_type == CalibrationType.IMAGE.value: + calibration_box = visual.ImageStim( + win=display, + image=CALIBRATION_IMAGE_PATH, + pos=(-.5, -.5), + mask=None, + ori=0.0) + calibration_box.size = resize_image( + CALIBRATION_IMAGE_PATH, display.size, 0.75) + + display.callOnFlip(trigger_callback.callback, + experiment_clock, trigger_name) + if on_trigger is not None: + display.callOnFlip(on_trigger, trigger_name) + + calibration_box.draw() + display.flip() + + elif trigger_type == CalibrationType.TEXT.value: + calibration_text = visual.TextStim(display, text='') + + display.callOnFlip(trigger_callback.callback, experiment_clock, + trigger_name) + if on_trigger is not None: + display.callOnFlip(on_trigger, trigger_name) + + calibration_text.draw() + display.flip() + + core.wait(trigger_time) + if trigger_callback.timing is None: + log.warning(f'No trigger found for [{trigger_name}]') + return trigger_name, 0.0 + return trigger_callback.timing + + +def trigger_durations(params: Parameters) -> Dict[str, float]: + """Get duration for each type of trigger given in seconds. + + Args: + params (Parameters): Parameters containing timing information. + + Returns: + Dict[str, float]: Dictionary mapping trigger types to their durations in seconds. + """ + return { + 'offset': 0.0, + 'preview': params['preview_inquiry_length'], + 'fixation': params['time_fixation'], + 'prompt': params['time_prompt'], + 'nontarget': params['time_flash'], + 'target': params['time_flash'] + } + + +class TriggerType(Enum): + """Enum for the primary types of Triggers.""" + + NONTARGET = "nontarget" + TARGET = "target" + FIXATION = "fixation" + PROMPT = "prompt" + SYSTEM = "system" + OFFSET = "offset" + EVENT = "event" + PREVIEW = "preview" + ARTIFACT = "artifact" + + @classmethod + def list(cls) -> List[str]: + """Returns all enum values as a list. + + Returns: + List[str]: List of all enum values. + """ + return list(map(lambda c: c.value, cls)) + + @classmethod + def pre_fixation(cls) -> List['TriggerType']: + """Returns the subset of TriggerTypes that occur before and including + the FIXATION trigger. + + Returns: + List[TriggerType]: List of trigger types that occur before fixation. + """ + return [ + TriggerType.FIXATION, TriggerType.PROMPT, TriggerType.SYSTEM, + TriggerType.OFFSET + ] + + def __str__(self) -> str: + """String representation of the trigger type. + + Returns: + str: String representation of the trigger type. + """ + return f'{self.value}' + + +class Trigger(NamedTuple): + """Object that encompasses data for a single trigger instance. + + Attributes: + label (str): Label for the trigger. + type (TriggerType): Type of the trigger. + time (float): Timestamp of the trigger. + """ + + label: str + type: TriggerType + time: float + + def __repr__(self) -> str: + """String representation of the trigger. + + Returns: + str: String representation of the trigger. + """ + return f'Trigger: label=[{self.label}] type=[{self.type}] time=[{self.time}]' + + def with_offset(self, offset: float) -> 'Trigger': + """Construct a copy of this Trigger with the offset adjusted. + + Args: + offset (float): Offset to apply to the trigger time. + + Returns: + Trigger: New trigger instance with adjusted time. + """ + return Trigger(self.label, self.type, self.time + offset) + + @classmethod + def from_list(cls, lst: List[str]) -> 'Trigger': + """Constructs a Trigger from a serialized representation. + + Args: + lst (List[str]): Serialized representation [label, type, stamp]. + + Returns: + Trigger: New trigger instance. + + Raises: + AssertionError: If input list does not have exactly 3 elements. + """ + assert len(lst) == 3, "Input must have a label, type, and stamp" + return cls(lst[0], TriggerType(lst[1]), float(lst[2])) + + +class FlushFrequency(Enum): + """Enum that defines how often list of Triggers will be written and dumped.""" + + EVERY = "flush after every trigger addition" + END = "flush at end of session" + + +def read_data(lines: Iterable[str]) -> List[Trigger]: + """Read raw trigger data from the given source. + + Args: + lines (Iterable[str]): Iterable object where each item is a str with data for a single + trigger. + + Returns: + List[Trigger]: List of all Triggers in the data. + + Raises: + BciPyCoreException: If there is an error reading a trigger from any line. + """ + triggers = [] + for i, line in enumerate(lines): + try: + trg = Trigger.from_list(line.split()) + triggers.append(trg) + except (AssertionError, ValueError) as trg_error: + raise BciPyCoreException( + f'Error reading trigger from line {i+1}: {trg_error}' + ) from trg_error + return triggers + + +def offset_label(device_type: Optional[str] = None, prefix: str = 'starting_offset') -> str: + """Compute the offset label for the given device. + + Args: + device_type (Optional[str]): Type of device. If None or 'EEG', returns default prefix. + prefix (str): Prefix for the offset label. Defaults to 'starting_offset'. + + Returns: + str: Offset label for the device. + """ + if not device_type or device_type == 'EEG': + return prefix + return f"{prefix}_{device_type}" + + +def offset_device(label: str, prefix: str = 'starting_offset') -> str: + """Given a label, determine the device type. + + Args: + label (str): Label to parse. + prefix (str): Expected prefix of the label. Defaults to 'starting_offset'. + + Returns: + str: Device type extracted from the label. + + Raises: + AssertionError: If label does not start with the given prefix. + """ + assert label.startswith( + prefix), "Label must start with the given prefix" + try: + idx = label.index('_', len(prefix)) + return label[idx + 1:] + except ValueError: + return 'EEG' + + +def starting_offsets_by_device( + triggers: List[Trigger], + device_types: Optional[List[str]] = None +) -> Dict[str, Trigger]: + """Returns a dict of starting_offset triggers keyed by device type. + + Args: + triggers (List[Trigger]): List of triggers to search through. + device_types (Optional[List[str]]): List of device types to include in the result. + If provided, an entry is created for each one, using a default offset of 0.0 + if a match is not found. + + Returns: + Dict[str, Trigger]: Dictionary mapping device types to their offset triggers. + """ + offset_triggers = {} + for trg in triggers: + if trg.type == TriggerType.OFFSET: + device_type = offset_device(trg.label) + offset_triggers[device_type] = trg + + if device_types: + data = {} + for device_type in device_types: + data[device_type] = offset_triggers.get( + device_type, + Trigger(offset_label(device_type), TriggerType.OFFSET, 0.0)) + return data + return offset_triggers + + +def find_starting_offset( + triggers: List[Trigger], + device_type: Optional[str] = None +) -> Trigger: + """Given a list of raw trigger data, determine the starting offset for the + given device. The returned trigger has the timestamp of the first sample + recorded for the device. + + Args: + triggers (List[Trigger]): List of trigger data; should include Triggers of + TriggerType.OFFSET. + device_type (Optional[str]): Each device will generally have a different offset. This + parameter is used to determine which trigger to use. If not given + the EEG offset will be used by default. Ex. 'EYETRACKER'. + + Returns: + Trigger: The Trigger for the first matching offset for the given device, or a + Trigger with offset of 0.0 if a matching offset was not found. + """ + label = offset_label(device_type) + for trg in triggers: + if trg.type == TriggerType.OFFSET and trg.label == label: + return trg + log.info(f"Offset not found (device_type: {device_type}); using 0.0") + return Trigger(label, TriggerType.OFFSET, 0.0) + + +def read(path: str) -> List[Trigger]: + """Read all Triggers from the given text file. + + Args: + path (str): Trigger (.txt) file to read. + + Returns: + List[Trigger]: List of triggers read from the file. + + Raises: + FileNotFoundError: If the file does not exist or is not a .txt file. + """ + if not path.endswith('.txt') or not os.path.exists(path): + raise FileNotFoundError( + f'Valid triggers .txt file not found at [{path}].') + with open(path, encoding=DEFAULT_ENCODING) as raw_txt: + triggers = read_data(raw_txt) + return triggers + + +def apply_offsets( + triggers: List[Trigger], + starting_offset: Trigger, + static_offset: float = 0.0 +) -> List[Trigger]: + """Returns a list of triggers with timestamps adjusted relative to the + device start time. Offset triggers are filtered out if present. + + Args: + triggers (List[Trigger]): List of triggers to adjust. + starting_offset (Trigger): Offset from the device start time. + static_offset (float): The measured static system offset. + + Returns: + List[Trigger]: List of triggers with timestamps relative to the starting_offset. + """ + total_offset = starting_offset.time + static_offset + return [ + trg.with_offset(total_offset) for trg in triggers + if trg.type != TriggerType.OFFSET + ] + + +def exclude_types( + triggers: List[Trigger], + types: Optional[List[TriggerType]] = None +) -> List[Trigger]: + """Filter the list of triggers to exclude the provided types. + + Args: + triggers (List[Trigger]): List of triggers to filter. + types (Optional[List[TriggerType]]): List of trigger types to exclude. + + Returns: + List[Trigger]: Filtered list of triggers. + """ + if not types: + return triggers + return [trg for trg in triggers if trg.type not in types] + + +class TriggerHandler: + """Class that contains methods to work with Triggers, including adding and + writing triggers and loading triggers from a txt file. + + Attributes: + encoding (str): File encoding to use. + path (str): Path to the trigger file. + file_name (str): Name of the trigger file. + flush (FlushFrequency): Frequency at which to flush triggers to file. + triggers (List[Trigger]): List of triggers being handled. + file_path (str): Full path to the trigger file. + file (TextIO): File handle for the trigger file. + """ + + encoding = DEFAULT_ENCODING + + def __init__( + self, + path: str, + file_name: str, + flush: FlushFrequency + ) -> None: + """Initialize the TriggerHandler. + + Args: + path (str): Path to the trigger file. + file_name (str): Name of the trigger file. + flush (FlushFrequency): Frequency at which to flush triggers to file. + + Raises: + Exception: If the file already exists. + """ + self.path = path + self.file_name = f'{file_name}.txt' if not file_name.endswith( + '.txt') else file_name + self.flush = flush + self.triggers: List[Trigger] = [] + self.file_path = f'{self.path}/{self.file_name}' + self.flush = flush + + if os.path.exists(self.file_name): + raise Exception(f"[{self.file_name}] already exists, any writing " + "will overwrite data in the existing file.") + + self.file = open(self.file_path, 'w+', encoding=self.encoding) + + def close(self) -> None: + """Close the trigger file and ensure all data is written.""" + self.write() + self.file.close() + + def write(self) -> None: + """Writes current Triggers in self.triggers[] to .txt file in self.file_name. + File writes in the format "label, targetness, time". + """ + for trigger in self.triggers: + self.file.write( + f'{trigger.label} {trigger.type.value} {trigger.time}\n') + + self.triggers = [] + + @staticmethod + def read_text_file(path: str) -> Tuple[List[Trigger], float]: + """Read Triggers from the given text file. + + Args: + path (str): Trigger (.txt) file to read. + + Returns: + Tuple[List[Trigger], float]: List of triggers and offset time. + """ + triggers = read(path) + offset = find_starting_offset(triggers) + triggers = exclude_types(triggers, [TriggerType.SYSTEM]) + return triggers, offset.time + + @staticmethod + def load( + path: str, + offset: float = 0.0, + exclusion: Optional[List[TriggerType]] = None, + device_type: Optional[str] = None + ) -> List[Trigger]: + """Loads a list of triggers from a .txt of triggers. + + Args: + path (str): Name or file path of .txt trigger file to be loaded. + Input string must include file extension (.txt). + offset (float): If desired, time offset for all loaded triggers, + positive number for adding time, negative number for subtracting time. + exclusion (Optional[List[TriggerType]]): If desired, list of TriggerType's + to be removed from the loaded trigger list. + device_type (Optional[str]): If specified looks for the starting_offset for + a given device; default is to use the EEG offset. + + Returns: + List[Trigger]: List of Triggers from loaded .txt file with desired modifications. + """ + excluded_types = exclusion or [] + triggers = read(path) + starting_offset = find_starting_offset(triggers, device_type) + return apply_offsets(exclude_types(triggers, excluded_types), + starting_offset, + static_offset=offset) + + def add_triggers(self, triggers: List[Trigger]) -> List[Trigger]: + """Adds provided list of Triggers to self.triggers. + + Args: + triggers (List[Trigger]): List of Trigger objects to be added to the + handler's list of Triggers (self.triggers). + + Returns: + List[Trigger]: Returns list of Triggers currently part of Handler. + """ + self.triggers.extend(triggers) + + if self.flush is FlushFrequency.EVERY: + self.write() + + return self.triggers + + +def convert_timing_triggers( + timing: List[Tuple[str, float]], + target_stimuli: str, + trigger_type: Callable +) -> List[Trigger]: + """Convert Stimuli Times to Triggers. + + Using the stimuli presentation times provided by the display, convert them into BciPy Triggers. + + Args: + timing (List[Tuple[str, float]]): List of (symbol, time) tuples. + target_stimuli (str): Target stimulus identifier. + trigger_type (Callable): Function to determine trigger type. + + Returns: + List[Trigger]: List of converted triggers. + """ + return [ + Trigger(symbol, trigger_type(symbol, target_stimuli, i), time) + for i, (symbol, time) in enumerate(timing) + ] + + +def load_triggers( + trigger_path: str, + remove_pre_fixation: bool = True, + offset: float = 0.0, + exclusion: Optional[List[TriggerType]] = None, + device_type: Optional[str] = None, + apply_starting_offset: bool = True +) -> List[Trigger]: + """Trigger Decoder. + + Given a path to trigger data, this method loads valid Triggers. + + Args: + trigger_path (str): Path to triggers file. + remove_pre_fixation (bool): Boolean to determine whether any stimuli before a fixation + system should be removed. + offset (float): Static offset value to apply to triggers. + exclusion (Optional[List[TriggerType]]): Any TriggerTypes to be filtered from data returned. + device_type (Optional[str]): Used to determine which starting_offset value to use; if + a 'starting_offset' trigger is found it will be applied. + apply_starting_offset (bool): If False, does not apply the starting offset for + the given device_type. + + Returns: + List[Trigger]: List of processed triggers. + """ + excluded_types = exclusion or [] + excluded_types += TriggerType.pre_fixation() if remove_pre_fixation else [ + TriggerType.SYSTEM + ] + + triggers = read(trigger_path) + starting_offset = Trigger('', TriggerType.OFFSET, 0.0) + if apply_starting_offset: + starting_offset = find_starting_offset(triggers, device_type) + + filtered = exclude_types(triggers, excluded_types) + corrected = apply_offsets(filtered, starting_offset, static_offset=offset) + return corrected + + +def trigger_decoder( + trigger_path: str, + remove_pre_fixation: bool = True, + offset: float = 0.0, + exclusion: Optional[List[TriggerType]] = None, + device_type: Optional[str] = None, + apply_starting_offset: bool = True +) -> Tuple[List[str], List[float], List[str]]: + """Trigger Decoder. + + Given a path to trigger data, this method loads valid Triggers and returns their type, timing and label. + + Args: + trigger_path (str): Path to triggers file. + remove_pre_fixation (bool): Boolean to determine whether any stimuli before a fixation + system should be removed. + offset (float): Static offset value to apply to triggers. + exclusion (Optional[List[TriggerType]]): Any TriggerTypes to be filtered from data returned. + device_type (Optional[str]): Used to determine which starting_offset value to use; if + a 'starting_offset' trigger is found it will be applied. + apply_starting_offset (bool): If False, does not apply the starting offset for + the given device_type. + + Returns: + Tuple[List[str], List[float], List[str]]: Tuple containing trigger types, timings, and labels. + """ + triggers = load_triggers(trigger_path, remove_pre_fixation, offset, + exclusion, device_type, apply_starting_offset) + + labels, types, times = zip(*triggers) + return list(map(str, types)), list(times), list(labels) diff --git a/bcipy/demo/bci_main_demo.py b/bcipy/demo/bci_main_demo.py index 4e3c0adb3..f776b7b30 100644 --- a/bcipy/demo/bci_main_demo.py +++ b/bcipy/demo/bci_main_demo.py @@ -1,9 +1,11 @@ -from bcipy.main import bci_main from bcipy.config import DEFAULT_PARAMETERS_PATH +from bcipy.main import bci_main -parameter_location = DEFAULT_PARAMETERS_PATH # Path to a valid BciPy parameters file +# Path to a valid BciPy parameters file +parameter_location = DEFAULT_PARAMETERS_PATH user = 'test_demo_user' # User ID -experiment_id = 'default' # This will run two tasks: RSVP Calibration and Matrix Calibration +# This will run two tasks: RSVP Calibration and Matrix Calibration +experiment_id = 'default' alert = False # Set to True to alert user when tasks are complete visualize = False # Set to True to visualize data at the end of a task fake_data = True # Set to True to use fake acquisition data during the session diff --git a/bcipy/display/README.md b/bcipy/display/README.md index f09c5fea0..5df034936 100644 --- a/bcipy/display/README.md +++ b/bcipy/display/README.md @@ -1,22 +1,160 @@ # Display Module -The Display module defines the visual presentation logic needed for any tasks in BciPy. Most displays take in a large number of user-configured parameters (including text size and font) and handle - passing back timestamps from their stimuli presentations for classification. - -### Structure -`display` - `main`: Initializes a display window and contains useful display objects - `paradigm`: top level module holding all bcipy related display objects - `rsvp`: RSVP related display objects and functions. - `mode`: defines task specific displays - `matrix`: matrix related display objects and functions. Currently, only single character presentation is available. - `mode`: defines task specific displays - `tests`: tests for display module - `demo`: demo code for the display module - -### Guidelines - -- Add new modes in their own submodule -- Inherit base classes defined in display.py where possible -- Test timing between your code and the devices you're using - - consult psychopy (or other display codebase) for best practices for your OS +The Display module is a core component of BciPy that handles all visual presentation logic for BCI tasks. It provides a flexible and configurable framework for creating and managing visual stimuli, with precise timing control and synchronization capabilities. Please note that the VEPDisplay is still in progress. Please use with discretion! + +## Structure + +The module is organized into several key components: + +- `main/`: Core display initialization and window management +- `paradigm/`: BCI paradigm-specific display implementations + - `rsvp/`: RSVP Keyboard display components + - `matrix/`: Matrix Speller display components + - `vep/`: *WIP* Visual Evoked Potetinal display components. +- `components/`: Reusable display components +- `tests/`: Unit and integration tests +- `demo/`: Example implementations and usage + +## Core Concepts + +### Display System + +The display system is built on several key abstractions: + +#### 1. Display Base Class + +The base `Display` class provides core functionality for all displays. It is defined in `main.py`. + +- Window management and initialization +- Stimulus presentation timing +- Task bar and information display +- Trigger handling and calibration + +#### 2. Stimuli Properties + +Configure visual properties of stimuli: + +```python +from bcipy.display import StimuliProperties + +properties = StimuliProperties( + stim_font='Arial', + stim_height=32, + stim_pos=(0, 0) +) +``` + +#### 3. Information Properties + +Manage task information display: + +```python +from bcipy.display import InformationProperties + +info = InformationProperties( + info_color='white', + info_text="Task Progress", + info_font='Consolas', + info_height=24, + info_pos=(0, 0) +) +``` + +### Key Features + +#### Window Management + +- PsychoPy window initialization +- Screen resolution handling +- Fullscreen/windowed modes +- Refresh rate synchronization + +#### Stimulus Presentation + +- Precise timing control +- Animation and transitions +- Trigger synchronization +- Event logging + +#### Task Display + +- Progress tracking +- User feedback +- Custom UI elements +- Dynamic updates + +#### Layout System + +- Flexible positioning +- Responsive design +- Component alignment +- Screen space optimization + +## Supported Paradigms + +### RSVP Keyboard + +The RSVP Keyboard is an EEG-based typing system that presents symbols sequentially at a single location. Users select symbols by attending to their target and eliciting a P300 response. + +Key features: + +- Single-location presentation +- Temporal separation of stimuli +- P300-based selection +- Configurable timing + +### Matrix Speller + +The Matrix Speller presents symbols in a grid layout, highlighting subsets of symbols to elicit P300 responses for selection. + +Key features: + +- Grid-based layout +- P300-based selection +- Configurable matrix size + +## Development Guidelines + +1. **Adding New Paradigms** + - Create a new submodule in `paradigm/` + - Inherit from base `Display` class + - Implement required interface methods + - Add comprehensive tests + +2. **Timing Considerations** + - Test timing with actual hardware + - Account for refresh rate variations + - Log timing events for analysis + - Use PsychoPy's timing functions + +3. **Best Practices** + - Follow PsychoPy guidelines + - Document timing parameters + - Include example configurations + - Add unit tests for timing + +## References + +1. RSVP Keyboard: + +```text +Orhan, U., et al. (2012). RSVP Keyboard: An EEG Based Typing Interface. +IEEE International Conference on Acoustics, Speech, and Signal Processing. +``` + +1. Matrix Speller: + +```text +Farwell, L. A., & Donchin, E. (1988). Talking off the top of your head: +toward a mental prosthesis utilizing event-related brain potentials. +Electroencephalography and clinical Neurophysiology, 70(6), 510-523. +``` + +## Support + +For issues, questions, or contributions: + +- Open an issue on GitHub +- Check existing documentation +- Review test examples +- Consult the demo implementations diff --git a/bcipy/display/__init__.py b/bcipy/display/__init__.py index 58bbf82eb..99506545c 100644 --- a/bcipy/display/__init__.py +++ b/bcipy/display/__init__.py @@ -4,13 +4,9 @@ `from bcipy.display import init_display_window` vs. `from bcipy.display.main import init_display_window` """ from bcipy.config import BCIPY_LOGO_PATH -from .main import ( - Display, - InformationProperties, - init_display_window, - StimuliProperties, - VEPStimuliProperties -) + +from .main import (Display, InformationProperties, StimuliProperties, + VEPStimuliProperties, init_display_window) __all__ = [ 'Display', diff --git a/bcipy/display/components/button_press_handler.py b/bcipy/display/components/button_press_handler.py index 3a087f74d..42563a362 100644 --- a/bcipy/display/components/button_press_handler.py +++ b/bcipy/display/components/button_press_handler.py @@ -1,6 +1,11 @@ -"""Handles button press interactions""" +"""Handles button press interactions. + +This module provides classes for handling button press events in the BciPy system. +It includes abstract base classes and concrete implementations for different types +of button press handling strategies. +""" from abc import ABC, abstractmethod -from typing import List, Optional, Type +from typing import Any, List, Optional, Type from psychopy import event from psychopy.core import CountdownTimer @@ -10,100 +15,178 @@ class ButtonPressHandler(ABC): - """Handles button press events.""" - - def __init__(self, - max_wait: float, - key_input: str, - clock: Optional[Clock] = None, - timer: Type[CountdownTimer] = CountdownTimer): - """ - Parameters - ---------- - wait_length - maximum number of seconds to wait for a key press - key_input - key that we are listening for. - clock - clock used to associate the key event with a timestamp + """Handles button press events. + + This is an abstract base class that defines the interface for handling button press + events. It provides functionality for waiting for and processing button presses + within a specified time window. + + Attributes: + max_wait (float): Maximum number of seconds to wait for a key press. + key_input (str): Key that we are listening for. + clock (Clock): Clock used to associate the key event with a timestamp. + response (Optional[List]): List containing the latest response information. + _timer (Optional[CountdownTimer]): Timer for tracking wait period. + make_timer (Type[CountdownTimer]): Factory for creating timer instances. + """ + + def __init__( + self, + max_wait: float, + key_input: str, + clock: Optional[Clock] = None, + timer: Type[CountdownTimer] = CountdownTimer + ) -> None: + """Initialize the ButtonPressHandler. + + Args: + max_wait (float): Maximum number of seconds to wait for a key press. + key_input (str): Key that we are listening for. + clock (Optional[Clock]): Clock used to associate the key event with a timestamp. + If None, a new Clock instance will be created. + timer (Type[CountdownTimer]): Factory for creating timer instances. + Defaults to CountdownTimer. """ self.max_wait = max_wait self.key_input = key_input self.clock = clock or Clock() - self.response: Optional[List] = None + self.response: Optional[List[Any]] = None self._timer: Optional[CountdownTimer] = None self.make_timer = timer @property def response_label(self) -> Optional[str]: - """Label for the latest button press""" + """Get the label for the latest button press. + + Returns: + Optional[str]: The label of the latest button press, or None if no response. + """ return self.response[0] if self.response else None @property def response_timestamp(self) -> Optional[float]: - """Timestamp for the latest button response""" + """Get the timestamp for the latest button response. + + Returns: + Optional[float]: The timestamp of the latest button press, or None if no response. + """ return self.response[1] if self.response else None def _reset(self) -> None: - """Reset any existing events and timers.""" + """Reset any existing events and timers. + + This method clears any existing keyboard events, resets the timer, + and clears the current response. + """ self._timer = self.make_timer(self.max_wait) self.response = None event.clearEvents(eventType='keyboard') self._timer.reset() def await_response(self) -> None: - """Wait for a button response for a maximum number of seconds. Wait - period could end early if the class determines that some other - criteria have been met (such as an acceptable response).""" + """Wait for a button response for a maximum number of seconds. + Wait period could end early if the class determines that some other + criteria have been met (such as an acceptable response). + """ self._reset() while self._should_keep_waiting() and self._within_wait_period(): self._check_key_press() def has_response(self) -> bool: - """Whether a response has been provided""" + """Check whether a response has been provided. + + Returns: + bool: True if a response has been provided, False otherwise. + """ return self.response is not None def _check_key_press(self) -> None: - """Check for any key press events and set the latest as the response.""" + """Check for any key press events and set the latest as the response. + + This method updates the response attribute with the latest key press + information if a valid key press is detected. + """ self.response = get_key_press( key_list=[self.key_input], clock=self.clock, ) def _within_wait_period(self) -> bool: - """Check that we are within the allotted time for a response.""" + """Check that we are within the allotted time for a response. + + Returns: + bool: True if we are still within the wait period, False otherwise. + """ return (self._timer is not None) and (self._timer.getTime() > 0) def _should_keep_waiting(self) -> bool: - """Check that we should keep waiting for responses.""" + """Check that we should keep waiting for responses. + + Returns: + bool: True if we should continue waiting, False otherwise. + """ return not self.has_response() @abstractmethod def accept_result(self) -> bool: - """Should the result of a button press be affirmative""" + """Determine if the result of a button press should be affirmative. + + Returns: + bool: True if the result should be considered affirmative, False otherwise. + """ + pass class AcceptButtonPressHandler(ButtonPressHandler): - """ButtonPressHandler where a matching button press indicates an affirmative result.""" + """ButtonPressHandler where a matching button press indicates an affirmative result. + + This handler considers a button press as an affirmative response. + """ def accept_result(self) -> bool: - """Should the result of a button press be affirmative""" + """Determine if the result of a button press should be affirmative. + + Returns: + bool: True if a response has been provided, False otherwise. + """ return self.has_response() class RejectButtonPressHandler(ButtonPressHandler): - """ButtonPressHandler where a matching button press indicates a rejection.""" + """ButtonPressHandler where a matching button press indicates a rejection. + + This handler considers a button press as a rejection response. + """ def accept_result(self) -> bool: - """Should the result of a button press be affirmative""" + """Determine if the result of a button press should be affirmative. + + Returns: + bool: True if no response has been provided, False otherwise. + """ return not self.has_response() class PreviewOnlyButtonPressHandler(ButtonPressHandler): - """ButtonPressHandler that waits for the entire span of the configured max_wait.""" + """ButtonPressHandler that waits for the entire span of the configured max_wait. + + This handler always waits for the full duration regardless of button presses. + """ def _should_keep_waiting(self) -> bool: + """Check that we should keep waiting for responses. + + Returns: + bool: Always returns True to ensure full wait duration. + """ return True def accept_result(self) -> bool: - """Should the result of a button press be affirmative""" + """Determine if the result of a button press should be affirmative. + + Returns: + bool: Always returns True. + """ return True diff --git a/bcipy/display/components/layout.py b/bcipy/display/components/layout.py index e0887a79f..0c6fa86cb 100644 --- a/bcipy/display/components/layout.py +++ b/bcipy/display/components/layout.py @@ -1,11 +1,21 @@ # mypy: disable-error-code="override" -"""Defines common functionality for GUI layouts.""" +"""Defines common functionality for GUI layouts. + +This module provides classes and functions for managing layout and positioning +of GUI elements in the BciPy system. It includes utilities for alignment, +scaling, and positioning of components within containers. +""" from enum import Enum from typing import List, Optional, Protocol, Tuple class Container(Protocol): - """Protocol for an enclosing container with units and size.""" + """Protocol for an enclosing container with units and size. + + Attributes: + size (Tuple[float, float]): Size of the container as (width, height). + units (str): Units used for measurements (e.g., 'norm', 'height'). + """ size: Tuple[float, float] units: str @@ -18,7 +28,11 @@ class Container(Protocol): class Alignment(Enum): - """Specifies how elements should be aligned spatially""" + """Specifies how elements should be aligned spatially. + + This enum defines the possible alignment options for positioning elements + within a container. + """ CENTERED = 1 LEFT = 2 RIGHT = 3 @@ -26,49 +40,104 @@ class Alignment(Enum): BOTTOM = 5 @classmethod - def horizontal(cls): - """Subset used for horizontal alignment""" + def horizontal(cls) -> List['Alignment']: + """Get subset used for horizontal alignment. + + Returns: + List[Alignment]: List of horizontal alignment options. + """ return [Alignment.CENTERED, Alignment.LEFT, Alignment.RIGHT] @classmethod - def vertical(cls): - """Subset used for vertical alignment""" + def vertical(cls) -> List['Alignment']: + """Get subset used for vertical alignment. + + Returns: + List[Alignment]: List of vertical alignment options. + """ return [Alignment.CENTERED, Alignment.TOP, Alignment.BOTTOM] # Positioning functions def above(y_coordinate: float, amount: float) -> float: - """Returns a new y_coordinate value that is above the provided value - by the given amount.""" + """Returns a new y_coordinate value that is above the provided value. + + Args: + y_coordinate (float): Base y-coordinate. + amount (float): Distance to move upward. + + Returns: + float: New y-coordinate value. + + Raises: + AssertionError: If amount is negative. + """ assert amount >= 0, 'Amount must be positive' return y_coordinate + amount def below(y_coordinate: float, amount: float) -> float: - """Returns a new y_coordinate value that is below the provided value - by the given amount.""" + """Returns a new y_coordinate value that is below the provided value. + + Args: + y_coordinate (float): Base y-coordinate. + amount (float): Distance to move downward. + + Returns: + float: New y-coordinate value. + + Raises: + AssertionError: If amount is negative. + """ assert amount >= 0, 'Amount must be positive' return y_coordinate - amount def right_of(x_coordinate: float, amount: float) -> float: - """Returns a new x_coordinate value that is to the right of the - provided value by the given amount.""" + """Returns a new x_coordinate value that is to the right of the provided value. + + Args: + x_coordinate (float): Base x-coordinate. + amount (float): Distance to move right. + + Returns: + float: New x-coordinate value. + + Raises: + AssertionError: If amount is negative. + """ assert amount >= 0, 'Amount must be positive' return x_coordinate + amount def left_of(x_coordinate: float, amount: float) -> float: - """Returns a new x_coordinate value that is to the left of the - provided value by the given amount.""" + """Returns a new x_coordinate value that is to the left of the provided value. + + Args: + x_coordinate (float): Base x-coordinate. + amount (float): Distance to move left. + + Returns: + float: New x-coordinate value. + + Raises: + AssertionError: If amount is negative. + """ assert amount >= 0, 'Amount must be positive' return x_coordinate - amount def envelope(pos: Tuple[float, float], size: Tuple[float, float]) -> List[Tuple[float, float]]: - """Compute the vertices for the envelope of a shape centered at pos with - the given size.""" + """Compute the vertices for the envelope of a shape. + + Args: + pos (Tuple[float, float]): Center position of the shape. + size (Tuple[float, float]): Size of the shape as (width, height). + + Returns: + List[Tuple[float, float]]: List of vertices defining the shape's envelope. + """ width, height = size half_w = width / 2 half_h = height / 2 @@ -81,8 +150,16 @@ def envelope(pos: Tuple[float, float], def scaled_size(height: float, window_size: Tuple[float, float], units: str = 'norm') -> Tuple[float, float]: - """Scales the provided height value to reflect the aspect ratio of a - visual.Window. Used for creating squared stimulus. Returns (w,h) tuple""" + """Scales the provided height value to reflect the aspect ratio of a window. + + Args: + height (float): Height value to scale. + window_size (Tuple[float, float]): Window dimensions as (width, height). + units (str): Units to use for scaling. Defaults to 'norm'. + + Returns: + Tuple[float, float]: Scaled size as (width, height). + """ if units == 'height': width = height return (width, height) @@ -95,8 +172,16 @@ def scaled_size(height: float, def scaled_height(width: float, window_size: Tuple[float, float], units: str = 'norm') -> float: - """Given a width, find the equivalent height scaled to the aspect ratio of - a window with the given size""" + """Given a width, find the equivalent height scaled to the aspect ratio. + + Args: + width (float): Width value to scale. + window_size (Tuple[float, float]): Window dimensions as (width, height). + units (str): Units to use for scaling. Defaults to 'norm'. + + Returns: + float: Scaled height value. + """ if units == 'height': return width win_width, win_height = window_size @@ -105,24 +190,56 @@ def scaled_height(width: float, def scaled_width(height: float, window_size: Tuple[float, float], - units: str = 'norm'): - """Given a height, find the equivalent width scaled to the aspect ratio of - a window with the given size""" + units: str = 'norm') -> float: + """Given a height, find the equivalent width scaled to the aspect ratio. + + Args: + height (float): Height value to scale. + window_size (Tuple[float, float]): Window dimensions as (width, height). + units (str): Units to use for scaling. Defaults to 'norm'. + + Returns: + float: Scaled width value. + """ width, _height = scaled_size(height, window_size, units) return width class Layout(Container): """Class with methods for positioning elements within a parent container. + + This class provides functionality for managing the layout and positioning + of GUI elements within a container, including methods for resizing and + alignment. + + Attributes: + units (str): Units used for measurements (e.g., 'norm', 'height'). + parent (Optional[Container]): Parent container if any. + top (float): Top boundary position. + left (float): Left boundary position. + bottom (float): Bottom boundary position. + right (float): Right boundary position. """ - def __init__(self, - parent: Optional[Container] = None, - left: float = DEFAULT_LEFT, - top: float = DEFAULT_TOP, - right: float = DEFAULT_RIGHT, - bottom: float = DEFAULT_BOTTOM, - units: str = "norm"): + def __init__( + self, + parent: Optional[Container] = None, + left: float = DEFAULT_LEFT, + top: float = DEFAULT_TOP, + right: float = DEFAULT_RIGHT, + bottom: float = DEFAULT_BOTTOM, + units: str = "norm" + ) -> None: + """Initialize the Layout. + + Args: + parent (Optional[Container]): Parent container. Defaults to None. + left (float): Left boundary position. Defaults to DEFAULT_LEFT. + top (float): Top boundary position. Defaults to DEFAULT_TOP. + right (float): Right boundary position. Defaults to DEFAULT_RIGHT. + bottom (float): Bottom boundary position. Defaults to DEFAULT_BOTTOM. + units (str): Units to use. Defaults to "norm". + """ self.units: str = units self.parent = parent self.top = top @@ -131,8 +248,12 @@ def __init__(self, self.right = right self.check_invariants() - def check_invariants(self): - """Check that all invariants hold true.""" + def check_invariants(self) -> None: + """Check that all invariants hold true. + + Raises: + AssertionError: If any invariant is violated. + """ # https://psychopy.org/general/units.html#units assert self.units in ['height', 'norm'], "Units must be 'height' or 'norm'" @@ -162,8 +283,17 @@ def check_invariants(self): 1], "Height must be greater than 0 and fit within the parent height." def scaled_size(self, height: float) -> Tuple[float, float]: - """Returns the (w,h) value scaled to reflect the aspect ratio of a - visual.Window. Used for creating squared stimulus""" + """Returns the (w,h) value scaled to reflect the aspect ratio. + + Args: + height (float): Height value to scale. + + Returns: + Tuple[float, float]: Scaled size as (width, height). + + Raises: + AssertionError: If parent is not configured. + """ if self.units == 'height': width = height return (width, height) @@ -172,52 +302,92 @@ def scaled_size(self, height: float) -> Tuple[float, float]: @property def size(self) -> Tuple[float, float]: - """Layout size.""" + """Get the layout size. + + Returns: + Tuple[float, float]: Size as (width, height). + """ return (self.width, self.height) @property def width(self) -> float: - """Width in norm units of this component.""" + """Get the width in norm units of this component. + + Returns: + float: Width value. + """ return self.right - self.left @property def height(self) -> float: - """Height in norm units of this component.""" + """Get the height in norm units of this component. + + Returns: + float: Height value. + """ return self.top - self.bottom @property def left_top(self) -> Tuple[float, float]: - """Top left position""" + """Get the top left position. + + Returns: + Tuple[float, float]: Position as (x, y). + """ return (self.left, self.top) @property def right_bottom(self) -> Tuple[float, float]: - """Bottom right position""" + """Get the bottom right position. + + Returns: + Tuple[float, float]: Position as (x, y). + """ return (self.right, self.bottom) @property def horizontal_middle(self) -> float: - """x-axis value in norm units for the midpoint of this component""" + """Get the x-axis value for the midpoint of this component. + + Returns: + float: X-coordinate of the midpoint. + """ return (self.left + self.right) / 2 @property def vertical_middle(self) -> float: - """x-axis value in norm units for the midpoint of this component.""" + """Get the y-axis value for the midpoint of this component. + + Returns: + float: Y-coordinate of the midpoint. + """ return (self.top + self.bottom) / 2 @property def center(self) -> Tuple[float, float]: - """Center point of the component in norm units. Returns a (x,y) tuple.""" + """Get the center point of the component. + + Returns: + Tuple[float, float]: Center position as (x, y). + """ return (self.horizontal_middle, self.vertical_middle) @property def left_middle(self) -> Tuple[float, float]: - """Point centered on the left-most edge.""" + """Get the point centered on the left-most edge. + + Returns: + Tuple[float, float]: Position as (x, y). + """ return (self.left, self.vertical_middle) @property def right_middle(self) -> Tuple[float, float]: - """Point centered on the right-most edge.""" + """Get the point centered on the right-most edge. + + Returns: + Tuple[float, float]: Position as (x, y). + """ return (self.right, self.vertical_middle) def resize_width(self, @@ -225,10 +395,13 @@ def resize_width(self, alignment: Alignment = Alignment.CENTERED) -> None: """Adjust the width of the current layout. - Parameters - ---------- - width_pct - percentage of the current width - alignment - specifies how the remaining width should be aligned. + Args: + width_pct (float): Percentage of the current width. + alignment (Alignment): Specifies how the remaining width should be aligned. + Defaults to Alignment.CENTERED. + + Raises: + AssertionError: If width_pct is not positive or alignment is invalid. """ assert 0 < width_pct, 'width_pct must be greater than 0' assert alignment in Alignment.horizontal() @@ -256,10 +429,13 @@ def resize_height(self, alignment: Alignment = Alignment.CENTERED) -> None: """Adjust the height of the current layout. - Parameters - ---------- - height_pct - percentage of the current width - alignment - specifies how the remaining width should be aligned. + Args: + height_pct (float): Percentage of the current height. + alignment (Alignment): Specifies how the remaining height should be aligned. + Defaults to Alignment.CENTERED. + + Raises: + AssertionError: If height_pct is not positive or alignment is invalid. """ assert 0 < height_pct, 'height_pct must be greater than 0' assert alignment in Alignment.vertical() @@ -286,12 +462,14 @@ def resize_height(self, # Factory functions def at_top(parent: Container, height: float) -> Layout: - """Constructs a layout of a given height that spans the full width of the - window and is positioned at the top. + """Constructs a layout of a given height that spans the full width of the window. - Parameters - ---------- - height - value in 'norm' units + Args: + parent (Container): Parent container. + height (float): Height value in 'norm' units. + + Returns: + Layout: New layout instance positioned at the top. """ top = DEFAULT_TOP return Layout(parent=parent, @@ -302,8 +480,15 @@ def at_top(parent: Container, height: float) -> Layout: def at_bottom(parent: Container, height: float) -> Layout: - """Constructs a layout of a given height that spans the full width of the - window and is positioned at the bottom""" + """Constructs a layout of a given height that spans the full width of the window. + + Args: + parent (Container): Parent container. + height (float): Height value in 'norm' units. + + Returns: + Layout: New layout instance positioned at the bottom. + """ bottom = DEFAULT_BOTTOM return Layout(parent=parent, left=DEFAULT_LEFT, @@ -315,17 +500,17 @@ def at_bottom(parent: Container, height: float) -> Layout: def centered(parent: Optional[Container] = None, width_pct: float = 1.0, height_pct: float = 1.0) -> Layout: - """Constructs a layout that is centered on the screen. Default size is - fullscreen but optional parameters can be used to adjust the width and - height. - - Parameters - ---------- - parent - optional parent - width_pct - optional; sets the width to a given percentage of - fullscreen. - height_pct - optional; sets the height to a given percentage of - fullscreen. + """Constructs a layout that is centered on the screen. + + Args: + parent (Optional[Container]): Optional parent container. + width_pct (float): Optional; sets the width to a given percentage of fullscreen. + Defaults to 1.0. + height_pct (float): Optional; sets the height to a given percentage of fullscreen. + Defaults to 1.0. + + Returns: + Layout: New centered layout instance. """ container = Layout(parent=parent) container.resize_width(width_pct, alignment=Alignment.CENTERED) @@ -334,8 +519,14 @@ def centered(parent: Optional[Container] = None, def from_envelope(verts: List[Tuple[float, float]]) -> Layout: - """Constructs a layout from a list of vertices which comprise a shape's - envelope.""" + """Constructs a layout from a list of vertices which comprise a shape's envelope. + + Args: + verts (List[Tuple[float, float]]): List of vertices defining the shape's envelope. + + Returns: + Layout: New layout instance based on the envelope. + """ x_coords, y_coords = zip(*verts) return Layout(left=min(x_coords), top=max(y_coords), @@ -344,13 +535,19 @@ def from_envelope(verts: List[Tuple[float, float]]) -> Layout: def height_units(window_size: Tuple[float, float]) -> Layout: - """Constructs a layout with height units using the given Window - dimensions + """Constructs a layout with height units using the given Window dimensions. + + Args: + window_size (Tuple[float, float]): Window dimensions as (width, height). + + Returns: + Layout: New layout instance using height units. - for an aspect ratio of 4:3 - 4 widths / 3 height = 1.333 - 1.333 / 2 = 0.667 - so, left is -0.667 and right is 0.667 + Note: + For an aspect ratio of 4:3: + 4 widths / 3 height = 1.333 + 1.333 / 2 = 0.667 + so, left is -0.667 and right is 0.667 """ win_width, win_height = window_size right = (win_width / win_height) / 2 diff --git a/bcipy/display/components/task_bar.py b/bcipy/display/components/task_bar.py index 654acd859..4ade5574f 100644 --- a/bcipy/display/components/task_bar.py +++ b/bcipy/display/components/task_bar.py @@ -1,6 +1,11 @@ -"""Task bar component""" +"""Task bar component. -from typing import Dict, List, Optional +This module provides components for displaying task-related information in a task window. +It includes base task bar functionality and specialized implementations for different +types of tasks like calibration and copy phrase tasks. +""" + +from typing import Any, Dict, List, Optional from psychopy import visual from psychopy.visual.basevisual import BaseVisualStim @@ -9,27 +14,43 @@ class TaskBar: - """Component for displaying task-related information in a task window. The - component elements are positioned at the top of the window. - - Parameters - ---------- - win - visual.Window on which to render elements - colors - Ordered list of colors to apply to task stimuli - font - Font to apply to all task stimuli - height - Height of all task text stimuli - text - Task text to apply to stimuli - padding - used in conjunction with the text height to compute the - overall height of the task bar. + """Component for displaying task-related information in a task window. + + The component elements are positioned at the top of the window. + + Attributes: + win (visual.Window): Window on which to render elements. + colors (List[str]): Ordered list of colors to apply to task stimuli. + font (str): Font to apply to all task stimuli. + height (float): Height of all task text stimuli. + padding (float): Padding used in conjunction with text height to compute + the overall height of the task bar. + text (str): Task text to apply to stimuli. + layout (layout.Layout): Layout manager for positioning elements. + stim (Dict[str, BaseVisualStim]): Dictionary of visual stimuli. """ - def __init__(self, - win: visual.Window, - colors: Optional[List[str]] = None, - font: str = 'Courier New', - height: float = 0.1, - text: str = '', - padding: Optional[float] = None): + def __init__( + self, + win: visual.Window, + colors: Optional[List[str]] = None, + font: str = 'Courier New', + height: float = 0.1, + text: str = '', + padding: Optional[float] = None + ) -> None: + """Initialize the TaskBar. + + Args: + win (visual.Window): Window on which to render elements. + colors (Optional[List[str]]): Ordered list of colors to apply to task stimuli. + Defaults to ['white']. + font (str): Font to apply to all task stimuli. Defaults to 'Courier New'. + height (float): Height of all task text stimuli. Defaults to 0.1. + text (str): Task text to apply to stimuli. Defaults to ''. + padding (Optional[float]): Padding used in conjunction with text height. + If None, defaults to height/2. + """ self.win = win self.colors = colors or ['white'] self.font = font @@ -41,35 +62,50 @@ def __init__(self, @property def height_pct(self) -> float: - """Percentage of the total window that the task bar occupies. + """Get the percentage of the total window that the task bar occupies. - Returns - ------- - percentage ; value will be between 0 and 1. + Returns: + float: Percentage value between 0 and 1. """ win_layout = layout.Layout(self.win) return self.compute_height() / win_layout.height - def compute_height(self): - """Computes the component height using the provided config.""" + def compute_height(self) -> float: + """Compute the component height using the provided config. + + Returns: + float: Total height of the task bar. + """ return self.height + self.padding def init_stim(self) -> Dict[str, BaseVisualStim]: - """Initialize the stimuli elements.""" + """Initialize the stimuli elements. + + Returns: + Dict[str, BaseVisualStim]: Dictionary of initialized visual stimuli. + """ task = self.text_stim() return {'task_text': task, 'border': self.border_stim()} - def draw(self): + def draw(self) -> None: """Draw the task bar elements.""" for _key, stim in self.stim.items(): stim.draw() - def update(self, text: str = ''): - """Update the task bar to display the given text.""" + def update(self, text: str = '') -> None: + """Update the task bar to display the given text. + + Args: + text (str): New text to display. Defaults to ''. + """ self.stim['task_text'].text = text def border_stim(self) -> visual.Line: - """Create the task bar outline""" + """Create the task bar outline. + + Returns: + visual.Line: Line stimulus representing the task bar border. + """ # pylint: disable=not-callable return visual.Line( win=self.win, @@ -79,15 +115,26 @@ def border_stim(self) -> visual.Line: lineColor=self.colors[0]) def text_stim(self, **kwargs) -> visual.TextStim: - """Constructs a TextStim. Uses the config to set default properties - which may be overridden by providing keyword args. - """ + """Construct a TextStim with default properties. + + Uses the config to set default properties which may be overridden by + providing keyword args. + + Args: + **kwargs: Additional properties to override defaults. + Returns: + visual.TextStim: Configured text stimulus. + """ props = {**self.default_text_props(), **kwargs} return visual.TextStim(**props) - def default_text_props(self) -> dict: - """Default properties for constructing a TextStim.""" + def default_text_props(self) -> Dict[str, Any]: + """Get default properties for constructing a TextStim. + + Returns: + Dict[str, Any]: Dictionary of default text stimulus properties. + """ return { 'win': self.win, 'text': self.text, @@ -100,82 +147,125 @@ def default_text_props(self) -> dict: class CalibrationTaskBar(TaskBar): - """Task bar for Calibration tasks. Displays the count of inquiries. - - Parameters - ---------- - win - visual.Window on which to render elements - inquiry_count - total number of inquiries to display - current_index - index of the current inquiry - **config - display config (colors, font, height) + """Task bar for Calibration tasks. + + Displays the count of inquiries in the format "current/total". + + Attributes: + inquiry_count (int): Total number of inquiries to display. + current_index (int): Index of the current inquiry. """ - def __init__(self, - win: visual.Window, - inquiry_count: int, - current_index: int = 1, - **config): + def __init__( + self, + win: visual.Window, + inquiry_count: int, + current_index: int = 1, + **config: Any + ) -> None: + """Initialize the CalibrationTaskBar. + + Args: + win (visual.Window): Window on which to render elements. + inquiry_count (int): Total number of inquiries to display. + current_index (int): Index of the current inquiry. Defaults to 1. + **config: Additional display configuration (colors, font, height). + """ self.inquiry_count = inquiry_count self.current_index = current_index super().__init__(win, **config) def init_stim(self) -> Dict[str, BaseVisualStim]: - """Initialize the stimuli elements.""" + """Initialize the stimuli elements. - task = self.text_stim(text=self.displayed_text(), - pos=self.layout.left_middle, - anchorHoriz='left', - alignText='left') + Returns: + Dict[str, BaseVisualStim]: Dictionary of initialized visual stimuli. + """ + task = self.text_stim( + text=self.displayed_text(), + pos=self.layout.left_middle, + anchorHoriz='left', + alignText='left' + ) return {'task_text': task, 'border': self.border_stim()} - def update(self, text: str = ''): - """Update the displayed text""" + def update(self, text: str = '') -> None: + """Update the displayed text. + + Args: + text (str): Unused parameter. Defaults to ''. + """ self.current_index += 1 self.stim['task_text'].text = self.displayed_text() def displayed_text(self) -> str: - """Text to display. Computed from the current_index and inquiry_count. Ex. '2/100'""" + """Get the text to display. + + Returns: + str: Text in the format "current/total" (e.g., "2/100"). + """ return f" {self.current_index}/{self.inquiry_count}" class CopyPhraseTaskBar(TaskBar): - """Task bar for the Copy Phrase Task - - Parameters - ---------- - win - visual.Window on which to render elements - task_text - text for the participant to spell - spelled_text - text that has already been spelled - **config - display config (colors, font, height) + """Task bar for the Copy Phrase Task. + + Displays both the target text and the currently spelled text. + + Attributes: + task_text (str): Text for the participant to spell. + spelled_text (str): Text that has already been spelled. """ - def __init__(self, - win: visual.Window, - task_text: str = '', - spelled_text: str = '', - **config): + def __init__( + self, + win: visual.Window, + task_text: str = '', + spelled_text: str = '', + **config: Any + ) -> None: + """Initialize the CopyPhraseTaskBar. + + Args: + win (visual.Window): Window on which to render elements. + task_text (str): Text for the participant to spell. Defaults to ''. + spelled_text (str): Text that has already been spelled. Defaults to ''. + **config: Additional display configuration (colors, font, height). + """ self.task_text = task_text self.spelled_text = spelled_text super().__init__(win, **config) - def compute_height(self): - """Computes the component height using the provided config.""" - # height is doubled to account for task_text and spelled_text being on - # separate lines. + def compute_height(self) -> float: + """Compute the component height using the provided config. + + Height is doubled to account for task_text and spelled_text being on + separate lines. + + Returns: + float: Total height of the task bar. + """ return (self.height * 2) + self.padding def init_stim(self) -> Dict[str, BaseVisualStim]: - """Initialize the stimuli elements.""" - - task = self.text_stim(text=self.task_text, - pos=self.layout.center, - anchorVert='bottom') + """Initialize the stimuli elements. - spelled = self.text_stim(text=self.displayed_text(), - pos=self.layout.center, - color=self.colors[-1], - anchorVert='top') + Returns: + Dict[str, BaseVisualStim]: Dictionary of initialized visual stimuli. + """ + task = self.text_stim( + text=self.task_text, + pos=self.layout.center, + anchorVert='bottom' + ) + + spelled = self.text_stim( + text=self.displayed_text(), + pos=self.layout.center, + color=self.colors[-1], + anchorVert='top' + ) return { 'task_text': task, @@ -183,13 +273,21 @@ def init_stim(self) -> Dict[str, BaseVisualStim]: 'border': self.border_stim() } - def update(self, text: str = ''): - """Update the task bar to display the given text.""" + def update(self, text: str = '') -> None: + """Update the task bar to display the given text. + + Args: + text (str): New spelled text to display. Defaults to ''. + """ self.spelled_text = text self.stim['spelled_text'].text = self.displayed_text() - def displayed_text(self): - """Spelled text padded for alignment.""" + def displayed_text(self) -> str: + """Get the spelled text padded for alignment. + + Returns: + str: Spelled text padded with spaces to match task_text length. + """ diff = len(self.task_text) - len(self.spelled_text) if (diff > 0): return self.spelled_text + (' ' * diff) diff --git a/bcipy/display/demo/components/demo_layouts.py b/bcipy/display/demo/components/demo_layouts.py index 08521c73f..5c944f2e0 100644 --- a/bcipy/display/demo/components/demo_layouts.py +++ b/bcipy/display/demo/components/demo_layouts.py @@ -10,12 +10,12 @@ from psychopy.visual.rect import Rect from psychopy.visual.shape import ShapeStim +from bcipy.core.symbols import alphabet from bcipy.display.components.layout import (Layout, at_top, centered, envelope, height_units, scaled_size) from bcipy.display.paradigm.matrix.layout import symbol_positions from bcipy.display.paradigm.vep.layout import BoxConfiguration, checkerboard -from bcipy.helpers.symbols import alphabet def make_window(): @@ -267,7 +267,8 @@ def demo_matrix_positions(win: visual.Window): symbols = alphabet() norm_layout = centered(parent=win, width_pct=0.7, height_pct=0.75) - positions = symbol_positions(norm_layout, symbol_set=symbols, rows=5, columns=6) + positions = symbol_positions( + norm_layout, symbol_set=symbols, rows=5, columns=6) for sym, pos in zip(symbols, positions): stim = visual.TextStim(win, diff --git a/bcipy/display/demo/matrix/demo_calibration_matrix.py b/bcipy/display/demo/matrix/demo_calibration_matrix.py index 3e737644d..839a69554 100644 --- a/bcipy/display/demo/matrix/demo_calibration_matrix.py +++ b/bcipy/display/demo/matrix/demo_calibration_matrix.py @@ -35,7 +35,8 @@ win = init_display_window(window_parameters) win.recordFrameIntervals = False -task_bar = CalibrationTaskBar(win, inquiry_count=4, current_index=0, font='Arial') +task_bar = CalibrationTaskBar( + win, inquiry_count=4, current_index=0, font='Arial') preview_config = PreviewParams(show_preview_inquiry=True, preview_inquiry_length=2, preview_inquiry_key_input='return', diff --git a/bcipy/display/demo/vep/demo_calibration_vep.py b/bcipy/display/demo/vep/demo_calibration_vep.py index c0a53b4ea..69bd54829 100644 --- a/bcipy/display/demo/vep/demo_calibration_vep.py +++ b/bcipy/display/demo/vep/demo_calibration_vep.py @@ -11,7 +11,7 @@ from bcipy.display.paradigm.vep.display import VEPDisplay from bcipy.display.paradigm.vep.layout import BoxConfiguration from bcipy.helpers.clock import Clock -from bcipy.helpers.system_utils import get_screen_info +from bcipy.helpers.utils import get_screen_info root = logging.getLogger() root.setLevel(logging.DEBUG) diff --git a/bcipy/display/main.py b/bcipy/display/main.py index bb8edd33f..859093aa6 100644 --- a/bcipy/display/main.py +++ b/bcipy/display/main.py @@ -1,7 +1,13 @@ +"""Main display module. + +This module provides the core display functionality for BciPy, including base classes +and utilities for creating and managing visual stimuli in BCI paradigms. +""" + # mypy: disable-error-code="assignment,empty-body" from abc import ABC, abstractmethod from enum import Enum -from typing import Any, List, NamedTuple, Optional, Tuple, Type, Union +from typing import Any, Dict, List, NamedTuple, Optional, Tuple, Type, Union from psychopy import visual @@ -9,13 +15,26 @@ AcceptButtonPressHandler, ButtonPressHandler, PreviewOnlyButtonPressHandler, RejectButtonPressHandler) from bcipy.helpers.clock import Clock -from bcipy.helpers.system_utils import get_screen_info +from bcipy.helpers.utils import get_screen_info class Display(ABC): - """Display. - - Base class for BciPy displays. This defines the logic necessary for task executions that require a display. + """Base class for BciPy displays. + + This abstract class defines the core interface and functionality necessary for + task executions that require a display. It provides methods for stimulus + presentation, timing control, and task management. + + Attributes: + window (visual.Window): PsychoPy window for display. + timing_clock (Clock): Clock for timing control. + experiment_clock (Clock): Clock for experiment timing. + stimuli_inquiry (List[str]): List of stimuli to present. + stimuli_colors (List[str]): List of colors for each stimulus. + stimuli_timing (List[float]): List of presentation durations. + task (Any): Task-related information. + info_text (List[Any]): Information text to display. + first_stim_time (float): Time of first stimulus presentation. """ window: visual.Window = None @@ -30,107 +49,142 @@ class Display(ABC): @abstractmethod def do_inquiry(self) -> List[Tuple[str, float]]: - """Do inquiry. + """Perform an inquiry of stimuli. Animates an inquiry of stimuli and returns a list of stimuli trigger timing. + + Returns: + List[Tuple[str, float]]: List of (stimulus, timing) pairs. """ ... @abstractmethod - def wait_screen(self, *args, **kwargs) -> None: - """Wait Screen. + def wait_screen(self, *args: Any, **kwargs: Any) -> None: + """Display a wait screen. Define what happens on the screen when a user pauses a session. + + Args: + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. """ ... @abstractmethod - def update_task_bar(self, *args, **kwargs) -> None: - """Update Task. + def update_task_bar(self, *args: Any, **kwargs: Any) -> None: + """Update task bar display. + + Update any taskbar-related display items not related to the inquiry. + Example: stimuli count 1/200. - Update any taskbar-related display items not related to the inquiry. Ex. stimuli count 1/200. + Args: + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. """ ... - def schedule_to(self, stimuli: list, timing: list, colors: list) -> None: - """Schedule To. + def schedule_to(self, stimuli: List[str], timing: List[float], colors: List[str]) -> None: + """Schedule stimuli elements. Schedule stimuli elements (works as a buffer) before calling do_inquiry. + + Args: + stimuli (List[str]): List of stimuli to present. + timing (List[float]): List of presentation durations. + colors (List[str]): List of colors for each stimulus. """ ... def draw_static(self) -> None: - """Draw Static. + """Draw static elements. Displays task information not related to the inquiry. """ ... - def preview_inquiry(self, *args, **kwargs) -> List[float]: - """Preview Inquiry. + def preview_inquiry(self, *args: Any, **kwargs: Any) -> List[float]: + """Preview an inquiry before presentation. + + Display an inquiry or instruction beforehand to the user. This should be called + before do_inquiry. This can be used to determine if the desired stimuli is present + before displaying them more laboriously or prompting users before the inquiry. + + Note: + All stimuli elements (stimuli, timing, colors) must be set on the display + before calling this method. This implies something like schedule_to is called. - Display an inquiry or instruction beforehand to the user. This should be called before do_inquiry. - This can be used to determine if the desired stimuli is present before displaying them more laboriusly - or prompting users before the inquiry. - All stimuli elements (stimuli, timing, colors) must be set on the display before calling this method. - This implies, something like schedule_to is called. + Args: + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + + Returns: + List[float]: List of timing information for the preview. """ ... -def init_display_window(parameters): - """ - Init Display Window. +def init_display_window(parameters: Dict[str, Any]) -> visual.Window: + """Initialize the main display window. - Function to Initialize main display window - needed for all later stimuli presentation. + Function to initialize main display window needed for all later stimuli presentation. See Psychopy official documentation for more information and working demos: http://www.psychopy.org/api/visual/window.html - """ - # Check is full_screen mode is set and get necessary values - if parameters['full_screen']: + Args: + parameters (Dict[str, Any]): Dictionary containing window configuration parameters. + Returns: + visual.Window: Initialized PsychoPy window for display. + """ + # Check if full_screen mode is set and get necessary values + if parameters['full_screen']: # set window attributes based on resolution screen_info = get_screen_info() window_height = screen_info.height window_width = screen_info.width - - # set full screen mode to true (removes os dock, explorer etc.) full_screen = True - - # otherwise, get user defined window attributes else: - # set window attributes directly from parameters file window_height = parameters['window_height'] window_width = parameters['window_width'] - - # make sure full screen is set to false full_screen = False # Initialize PsychoPy Window for Main Display of Stimuli display_window = visual.Window( - size=[window_width, - window_height], + size=[window_width, window_height], screen=parameters['stim_screen'], allowGUI=False, useFBO=False, fullscr=full_screen, allowStencil=False, monitor='mainMonitor', - winType='pyglet', units='norm', waitBlanking=False, + winType='pyglet', + units='norm', + waitBlanking=False, color=parameters['background_color']) - # Return display window to caller return display_window class StimuliProperties: - """"Stimuli Properties. - - An encapsulation of properties relevant to core stimuli presentation in a paradigm. + """Encapsulation of properties for core stimuli presentation. + + This class manages the properties and configuration for presenting stimuli + in a paradigm, including text and image-based stimuli. + + Attributes: + stim_font (str): Font to use for text stimuli. + stim_pos (Union[Tuple[float, float], List[Tuple[float, float]]]): Position(s) for stimuli. + stim_height (float): Height of stimuli. + stim_inquiry (List[str]): List of stimuli to present. + stim_colors (List[str]): List of colors for each stimulus. + stim_timing (List[float]): List of presentation durations. + is_txt_stim (bool): Whether stimuli are text-based. + stim_length (int): Number of stimuli. + sti (Optional[Union[visual.TextStim, visual.ImageStim]]): Stimulus object. + prompt_time (Optional[float]): Time to display target prompt. + layout (Optional[str]): Layout of stimuli (e.g., 'ALPHABET' or 'QWERTY'). """ def __init__( @@ -143,20 +197,19 @@ def __init__( stim_timing: Optional[List[float]] = None, is_txt_stim: bool = True, prompt_time: Optional[float] = None, - layout: Optional[str] = None): - """Initialize Stimuli Parameters. - - stim_font(List[str]): Ordered list of colors to apply to information stimuli - stim_pos(Tuple[float, float]): Position on window where the stimuli will be presented - or a list of positions (ex. for matrix displays) - stim_height(float): Height of all stimuli - stim_inquiry(List[str]): Ordered list of text to build stimuli with - stim_colors(List[str]): Ordered list of colors to apply to stimuli - stim_timing(List[float]): Ordered list of timing to apply to an inquiry using the stimuli - is_txt_stim(bool): Whether or not this is a text based stimuli (False implies image based) - prompt_time(float): Time to display target prompt for at the beginning of inquiry - layout(str): Layout of stimuli on the screen (ex. 'ALPHABET' or 'QWERTY'). - This is only used for matrix displays. + layout: Optional[str] = None) -> None: + """Initialize Stimuli Properties. + + Args: + stim_font (str): Font to use for text stimuli. + stim_pos (Union[Tuple[float, float], List[Tuple[float, float]]]): Position(s) for stimuli. + stim_height (float): Height of stimuli. + stim_inquiry (Optional[List[str]]): List of stimuli to present. Defaults to None. + stim_colors (Optional[List[str]]): List of colors for each stimulus. Defaults to None. + stim_timing (Optional[List[float]]): List of presentation durations. Defaults to None. + is_txt_stim (bool): Whether stimuli are text-based. Defaults to True. + prompt_time (Optional[float]): Time to display target prompt. Defaults to None. + layout (Optional[str]): Layout of stimuli. Defaults to None. """ self.stim_font = stim_font self.stim_pos = stim_pos @@ -171,11 +224,17 @@ def __init__( self.layout = layout def build_init_stimuli(self, window: visual.Window) -> Union[visual.TextStim, visual.ImageStim]: - """"Build Initial Stimuli. + """Build initial stimulus object. This method constructs the stimuli object which can be updated later. This is more - performant than creating a new stimuli each call. It can create either an image or text stimuli - based on the boolean self.is_txt_stim. + performant than creating a new stimuli each call. It can create either an image or + text stimuli based on the boolean self.is_txt_stim. + + Args: + window (visual.Window): PsychoPy window for display. + + Returns: + Union[visual.TextStim, visual.ImageStim]: The created stimulus object. """ if self.is_txt_stim: self.sti = visual.TextStim( @@ -185,8 +244,10 @@ def build_init_stimuli(self, window: visual.Window) -> Union[visual.TextStim, vi text='', font=self.stim_font, pos=self.stim_pos, - wrapWidth=None, colorSpace='rgb', - opacity=1, depth=-6.0) + wrapWidth=None, + colorSpace='rgb', + opacity=1, + depth=-6.0) else: self.sti = visual.ImageStim( win=window, @@ -198,10 +259,18 @@ def build_init_stimuli(self, window: visual.Window) -> Union[visual.TextStim, vi class InformationProperties: - """"Information Properties. - - An encapsulation of properties relevant to task information presentation in an RSVP paradigm. This could be - messaging relevant to feedback or static text to remain on screen not related to task tracking. + """Encapsulation of properties for task information presentation. + + This class manages the properties and configuration for displaying task-related + information, feedback, and static text in an RSVP paradigm. + + Attributes: + info_color (List[str]): List of colors for information text. + info_text (List[str]): List of information text to display. + info_font (List[str]): List of fonts for information text. + info_pos (List[Tuple[float, float]]): List of positions for information text. + info_height (List[float]): List of heights for information text. + text_stim (List[visual.TextStim]): List of text stimulus objects. """ def __init__( @@ -210,14 +279,15 @@ def __init__( info_text: List[str], info_font: List[str], info_pos: List[Tuple[float, float]], - info_height: List[float]): - """Initialize Information Parameters. - - info_color(List[str]): Ordered list of colors to apply to information stimuli - info_text(List[str]): Ordered list of text to apply to information stimuli - info_font(List[str]): Ordered list of font to apply to information stimuli - info_pos(Tuple[float, float]): Position on window where the Information stimuli will be presented - info_height(List[float]): Ordered list of height of Information stimuli + info_height: List[float]) -> None: + """Initialize Information Properties. + + Args: + info_color (List[str]): List of colors for information text. + info_text (List[str]): List of information text to display. + info_font (List[str]): List of fonts for information text. + info_pos (List[Tuple[float, float]]): List of positions for information text. + info_height (List[float]): List of heights for information text. """ self.info_color = info_color self.info_text = info_text @@ -226,9 +296,15 @@ def __init__( self.info_height = info_height def build_info_text(self, window: visual.Window) -> List[visual.TextStim]: - """"Build Information Text. + """Build information text stimuli. Constructs a list of Information stimuli to display. + + Args: + window (visual.Window): PsychoPy window for display. + + Returns: + List[visual.TextStim]: List of text stimulus objects. """ self.text_stim = [] for idx in range(len(self.info_text)): @@ -239,24 +315,39 @@ def build_info_text(self, window: visual.Window) -> List[visual.TextStim]: text=self.info_text[idx], font=self.info_font[idx], pos=self.info_pos[idx], - wrapWidth=None, colorSpace='rgb', - opacity=1, depth=-6.0)) + wrapWidth=None, + colorSpace='rgb', + opacity=1, + depth=-6.0)) return self.text_stim class ButtonPressMode(Enum): - """Represents the possible meanings for a button press (when using an Inquiry Preview.)""" + """Represents the possible meanings for a button press. + + Used when implementing Inquiry Preview functionality to determine the + action to take based on user input. + """ NOTHING = 0 ACCEPT = 1 REJECT = 2 class PreviewParams(NamedTuple): - """Parameters relevant for the Inquiry Preview functionality. - - Create from an existing Parameters instance using: - >>> parameters.instantiate(PreviewParams) + """Parameters for Inquiry Preview functionality. + + This class defines the configuration parameters needed for the Inquiry Preview + feature, which allows users to preview stimuli before presentation. + + Attributes: + show_preview_inquiry (bool): Whether to show preview. + preview_inquiry_length (float): Duration of preview. + preview_inquiry_key_input (str): Key to use for preview input. + preview_inquiry_progress_method (int): Method for handling preview progress. + preview_inquiry_isi (float): Inter-stimulus interval for preview. + preview_box_text_size (float): Text size for preview box. """ + show_preview_inquiry: bool preview_inquiry_length: float preview_inquiry_key_input: str @@ -265,14 +356,25 @@ class PreviewParams(NamedTuple): preview_box_text_size: float @property - def button_press_mode(self): - """Mode indicated by the inquiry progress method.""" + def button_press_mode(self) -> ButtonPressMode: + """Get the button press mode from the progress method. + + Returns: + ButtonPressMode: The mode indicated by the progress method. + """ return ButtonPressMode(self.preview_inquiry_progress_method) def get_button_handler_class( mode: ButtonPressMode) -> Type[ButtonPressHandler]: - """Get the appropriate handler constructor for the given button press mode.""" + """Get the appropriate button handler class for the given mode. + + Args: + mode (ButtonPressMode): The button press mode to handle. + + Returns: + Type[ButtonPressHandler]: The appropriate handler class. + """ mapping = { ButtonPressMode.NOTHING: PreviewOnlyButtonPressHandler, ButtonPressMode.ACCEPT: AcceptButtonPressHandler, @@ -283,7 +385,15 @@ def get_button_handler_class( def init_preview_button_handler(params: PreviewParams, experiment_clock: Clock) -> ButtonPressHandler: - """"Returns a button press handler for inquiry preview.""" + """Initialize a button press handler for inquiry preview. + + Args: + params (PreviewParams): Preview configuration parameters. + experiment_clock (Clock): Clock for experiment timing. + + Returns: + ButtonPressHandler: Configured button press handler. + """ make_handler = get_button_handler_class(params.button_press_mode) return make_handler(max_wait=params.preview_inquiry_length, key_input=params.preview_inquiry_key_input, @@ -291,6 +401,14 @@ def init_preview_button_handler(params: PreviewParams, class VEPStimuliProperties(StimuliProperties): + """Properties for VEP (Visual Evoked Potential) stimuli. + + This class extends StimuliProperties to provide specific functionality + for VEP-based paradigms. + + Attributes: + animation_seconds (float): Duration of animation. + """ def __init__(self, stim_font: str, @@ -300,12 +418,18 @@ def __init__(self, stim_color: List[str], inquiry: List[List[Any]], stim_length: int = 1, - animation_seconds: float = 1.0): - """Initialize VEP Stimuli Parameters. - stim_color(List[str]): Ordered list of colors to apply to VEP stimuli - stim_font(str): Font to apply to all VEP stimuli - stim_pos(List[Tuple[float, float]]): Position on the screen where to present to VEP text - stim_height(float): Height of all VEP text stimuli + animation_seconds: float = 1.0) -> None: + """Initialize VEP Stimuli Properties. + + Args: + stim_font (str): Font to use for text stimuli. + stim_pos (List[Tuple[float, float]]): Positions for stimuli. + stim_height (float): Height of stimuli. + timing (List[float]): List of presentation durations. + stim_color (List[str]): List of colors for each stimulus. + inquiry (List[List[Any]]): List of inquiry stimuli. + stim_length (int, optional): Number of stimuli. Defaults to 1. + animation_seconds (float, optional): Duration of animation. Defaults to 1.0. """ # static properties self.stim_font = stim_font @@ -317,11 +441,15 @@ def __init__(self, # dynamic property. List of length 3. 1. prompt; 2. fixation; 3. inquiry self.stim_timing = timing - # dynamic properties, must be a a list of lists where each list is a different box + # dynamic properties, must be a list of lists where each list is a different box self.stim_colors = stim_color self.stim_inquiry = inquiry self.animation_seconds = animation_seconds def build_init_stimuli(self, window: visual.Window) -> None: - """"Build Initial Stimuli.""" + """Build initial VEP stimuli. + + Args: + window (visual.Window): PsychoPy window for display. + """ ... diff --git a/bcipy/display/paradigm/matrix/README.md b/bcipy/display/paradigm/matrix/README.md index 0fbdf4a89..efbb7d6de 100644 --- a/bcipy/display/paradigm/matrix/README.md +++ b/bcipy/display/paradigm/matrix/README.md @@ -6,7 +6,7 @@ The matrix display presents a list of symbols in a grid format. Grid items are e A matrix display needs a psychopy Window, core.Clock, and configuration for the stimuli (StimuliProperties), task_bar (TaskBar), and information elements (InformationProperties). -``` +```python from psychopy import core import bcipy.display.components.layout as layout @@ -45,7 +45,7 @@ The number of rows and columns can be specified by using the provided parameters When using a task, the `matrix_rows` and `matrix_columns` parameters are used for customization. -``` +```python matrix_display = MatrixDisplay(win, experiment_clock, stim_properties, @@ -55,14 +55,13 @@ matrix_display = MatrixDisplay(win, columns=7) ``` - ## Layout Symbol positions are calculated when the display is initialized. The grid will be centered within the window. By default the grid will take up 75% of the width, and 80% of the height, or whichever is smaller depending on the aspect ratio of your monitor. These values can be adjusted by provided a width_pct and height_pct parameter. When using a task, the `matrix_width` parameter is used for customization. -``` +```python # determine matrix height based on the size of the task_bar matrix_height_pct = 1 - (2 * task_bar.height_pct) matrix_display = MatrixDisplay(win, @@ -93,9 +92,9 @@ You may need to do some trial and error to determine the best matrix configurati For tasks which use the matrix display, the following parameters are recommended: -``` +```python time_fixation: 2 stim_height: 0.17 task_height: 0.1 task_padding: 0.05 -``` \ No newline at end of file +``` diff --git a/bcipy/display/paradigm/matrix/__init__.py b/bcipy/display/paradigm/matrix/__init__.py index 98a0ee95e..88307e03c 100644 --- a/bcipy/display/paradigm/matrix/__init__.py +++ b/bcipy/display/paradigm/matrix/__init__.py @@ -1,6 +1,4 @@ -from .display import ( - MatrixDisplay -) +from .display import MatrixDisplay __all__ = [ 'MatrixDisplay' diff --git a/bcipy/display/paradigm/matrix/display.py b/bcipy/display/paradigm/matrix/display.py index f05f2b3e2..52432c969 100644 --- a/bcipy/display/paradigm/matrix/display.py +++ b/bcipy/display/paradigm/matrix/display.py @@ -1,25 +1,37 @@ -"""Display for presenting stimuli in a grid.""" +"""Display for presenting stimuli in a grid. + +This module provides functionality for displaying and managing matrix-style stimuli +presentations, commonly used in BCI paradigms. It handles the layout, timing, and +animation of stimuli in a grid format. +""" + import logging -from typing import Dict, List, NamedTuple, Optional, Tuple +from typing import Callable, Dict, List, NamedTuple, Optional, Tuple from psychopy import core, visual import bcipy.display.components.layout as layout from bcipy.config import MATRIX_IMAGE_FILENAME, SESSION_LOG_FILENAME +from bcipy.core.stimuli import resize_image +from bcipy.core.symbols import alphabet, frequency_order, qwerty_order +from bcipy.core.triggers import _calibration_trigger from bcipy.display import (BCIPY_LOGO_PATH, Display, InformationProperties, StimuliProperties) from bcipy.display.components.task_bar import TaskBar from bcipy.display.main import PreviewParams, init_preview_button_handler from bcipy.display.paradigm.matrix.layout import symbol_positions -from bcipy.helpers.stimuli import resize_image -from bcipy.helpers.symbols import alphabet, frequency_order, qwerty_order -from bcipy.helpers.triggers import _calibration_trigger logger = logging.getLogger(SESSION_LOG_FILENAME) class SymbolDuration(NamedTuple): - """Represents a symbol and its associated duration to display""" + """Represents a symbol and its associated duration to display. + + Attributes: + symbol (str): The symbol to display. + duration (float): Duration in seconds to display the symbol. + color (str): Color to display the symbol in. Defaults to 'white'. + """ symbol: str duration: float color: str = 'white' @@ -30,59 +42,82 @@ class MatrixDisplay(Display): Animates display objects in matrix grid common to any Matrix task. - NOTE: The following are recommended parameter values for matrix experiments: - - time_fixation: 2 - stim_pos_x: -0.6 - stim_pos_y: 0.4 - stim_height: 0.17 + Attributes: + window (visual.Window): PsychoPy window for display. + stimuli_inquiry (List[str]): List of stimuli to present. + stimuli_timing (List[float]): List of timing values for each stimulus. + stimuli_colors (List[str]): List of colors for each stimulus. + stimuli_font (str): Font to use for text stimuli. + symbol_set (Optional[List[str]]): Set of symbols to display. + sort_order (Callable[[str], int]): Function to determine symbol order. + grid_stimuli_height (float): Height of grid stimuli. + positions (Dict[int, Tuple[float, float]]): Positions for each symbol. + grid_color (str): Default color for grid elements. + start_opacity (float): Initial opacity for grid elements. + highlight_opacity (float): Opacity for highlighted elements. + full_grid_opacity (float): Opacity for full grid display. + first_run (bool): Whether this is the first run. + first_stim_time (Optional[float]): Time of first stimulus. + trigger_type (str): Type of trigger to use. + _timing (List[Tuple[str, float]]): List of timing information. + experiment_clock (core.Clock): Clock for timing. + task_bar (TaskBar): Task bar component. + info_text (List[visual.TextStim]): Information text components. + stim_registry (Dict[str, visual.TextStim]): Registry of stimuli. + should_prompt_target (bool): Whether to prompt for target. + preview_params (Optional[PreviewParams]): Preview configuration. + preview_button_handler (Optional[Any]): Handler for preview buttons. + preview_accepted (bool): Whether preview was accepted. + + Note: + The following are recommended parameter values for matrix experiments: + - time_fixation: 2 + - stim_pos_x: -0.6 + - stim_pos_y: 0.4 + - stim_height: 0.17 """ - def __init__(self, - window: visual.Window, - experiment_clock: core.Clock, - stimuli: StimuliProperties, - task_bar: TaskBar, - info: InformationProperties, - rows: int = 5, - columns: int = 6, - width_pct: float = 0.75, - height_pct: float = 0.8, - trigger_type: str = 'text', - symbol_set: Optional[List[str]] = alphabet(), - should_prompt_target: bool = True, - preview_config: Optional[PreviewParams] = None): + def __init__( + self, + window: visual.Window, + experiment_clock: core.Clock, + stimuli: StimuliProperties, + task_bar: TaskBar, + info: InformationProperties, + rows: int = 5, + columns: int = 6, + width_pct: float = 0.75, + height_pct: float = 0.8, + trigger_type: str = 'text', + symbol_set: Optional[List[str]] = alphabet(), + should_prompt_target: bool = True, + preview_config: Optional[PreviewParams] = None + ) -> None: """Initialize Matrix display parameters and objects. - PARAMETERS: - ---------- - # Experiment - window(visual.Window): PsychoPy Window - experiment_clock(core.Clock): Clock used to timestamp display onsets - - # Stimuli - stimuli(StimuliProperties): attributes used for inquiries - - # Task - task_bar(TaskBar): used for task tracking. Ex. 1/100 - - # Info - info(InformationProperties): attributes to display informational stimuli alongside task and inquiry stimuli. - - 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. - symbol_set default = none : subset of stimuli to be highlighted during an inquiry - should_prompt_target(bool): when True prompts for the target symbol. Assumes that this is - the first symbol of each inquiry. For example: [target, fixation, *stim]. - sort_order - optional function to define the position index for each - symbol. Using a custom function it is possible to skip a position. - preview_config - optional configuration for previewing inquiries + Args: + window (visual.Window): PsychoPy Window. + experiment_clock (core.Clock): Clock used to timestamp display onsets. + stimuli (StimuliProperties): Attributes used for inquiries. + task_bar (TaskBar): Used for task tracking. Ex. 1/100. + info (InformationProperties): Attributes to display informational stimuli. + rows (int): Number of rows in the matrix. Defaults to 5. + columns (int): Number of columns in the matrix. Defaults to 6. + width_pct (float): Width percentage of the display. Defaults to 0.75. + height_pct (float): Height percentage of the display. Defaults to 0.8. + trigger_type (str): Defines the calibration trigger type. Defaults to 'text'. + symbol_set (Optional[List[str]]): Subset of stimuli to be highlighted. + Defaults to alphabet(). + should_prompt_target (bool): When True prompts for the target symbol. + Defaults to True. + preview_config (Optional[PreviewParams]): Configuration for previewing inquiries. + Defaults to None. """ self.window = window - self.stimuli_inquiry = [] - self.stimuli_timing = [] - self.stimuli_colors = [] + self.stimuli_inquiry: List[str] = [] + self.stimuli_timing: List[float] = [] + self.stimuli_colors: List[str] = [] self.stimuli_font = stimuli.stim_font assert stimuli.is_txt_stim, "Matrix display is a text only display" @@ -92,9 +127,11 @@ def __init__(self, # Set position and parameters for grid of alphabet self.grid_stimuli_height = stimuli.stim_height - display_container = layout.centered(parent=window, - width_pct=width_pct, - height_pct=height_pct) + display_container = layout.centered( + parent=window, + width_pct=width_pct, + height_pct=height_pct + ) self.positions = symbol_positions( display_container, rows, columns, symbol_set) @@ -107,7 +144,7 @@ def __init__(self, self.first_run = True self.first_stim_time = None self.trigger_type = trigger_type - self._timing = [] + self._timing: List[Tuple[str, float]] = [] self.experiment_clock = experiment_clock @@ -127,10 +164,23 @@ def __init__(self, ) logger.info(f"Matrix center position: {display_container.center}") - def build_sort_order(self, stimuli: StimuliProperties) -> List[str]: - """Build the symbol set for the display.""" + def build_sort_order(self, stimuli: StimuliProperties) -> Callable[[str], int]: + """Build the symbol set for the display. + + Args: + stimuli (StimuliProperties): Properties containing layout information. + + Returns: + Callable[[str], int]: Function that returns the index for a given symbol. + + Raises: + ValueError: If layout or symbol set is not recognized. + """ if stimuli.layout == 'ALP': - return self.symbol_set.index + if self.symbol_set: + return self.symbol_set.index + else: + raise ValueError('Symbol set not defined') elif stimuli.layout == 'QWERTY': logger.info('Using QWERTY layout') return qwerty_order() @@ -142,7 +192,14 @@ def build_sort_order(self, stimuli: StimuliProperties) -> List[str]: @property def stim_positions(self) -> Dict[str, Tuple[float, float]]: - """Returns a dict with the position for each stim""" + """Get positions for each stimulus. + + Returns: + Dict[str, Tuple[float, float]]: Dictionary mapping symbols to positions. + + Raises: + AssertionError: If stim_registry is not initialized. + """ assert self.stim_registry, "stim_registry not yet initialized" return { sym: tuple(stim.pos) @@ -151,13 +208,18 @@ def stim_positions(self) -> Dict[str, Tuple[float, float]]: @property def preview_enabled(self) -> bool: - """Should the inquiry preview be enabled.""" - return self.preview_params and self.preview_params.show_preview_inquiry + """Check if inquiry preview should be enabled. + + Returns: + bool: True if preview is enabled, False otherwise. + """ + return bool(self.preview_params and self.preview_params.show_preview_inquiry) def capture_grid_screenshot(self, file_path: str) -> None: - """Capture Grid Screenshot. + """Capture a screenshot of the current display. - Capture a screenshot of the current display and save it to the specified filename. + Args: + file_path (str): Path where to save the screenshot. """ # draw the grid and flip the window self.draw_grid(opacity=self.full_grid_opacity) @@ -171,13 +233,17 @@ def capture_grid_screenshot(self, file_path: str) -> None: capture.save(f'{file_path}/{MATRIX_IMAGE_FILENAME}') self.task_bar.current_index = tmp_task_bar - def schedule_to(self, stimuli: list, timing: list, colors: list) -> None: + def schedule_to(self, stimuli: List[str], timing: List[float], colors: Optional[List[str]] = None) -> None: """Schedule stimuli elements (works as a buffer). Args: - stimuli(list[string]): list of stimuli text / name - timing(list[float]): list of timings of stimuli - colors(list[string]): list of colors + stimuli (List[str]): List of stimuli text / name. + timing (List[float]): List of timings of stimuli. + colors (Optional[List[str]]): List of colors. Defaults to None. + + Raises: + AssertionError: If lengths of stimuli and timing don't match, + or if colors are provided but lengths don't match. """ assert len(stimuli) == len( timing), "each stimuli must have a timing value" @@ -191,27 +257,36 @@ def schedule_to(self, stimuli: list, timing: list, colors: list) -> None: self.stimuli_colors = [self.grid_color] * len(stimuli) def symbol_durations(self) -> List[SymbolDuration]: - """Symbols associated with their duration for the currently configured - stimuli_inquiry.""" + """Get symbols associated with their duration for the currently configured stimuli_inquiry. + + Returns: + List[SymbolDuration]: List of symbol durations. + """ return [ SymbolDuration(*sti) for sti in zip( self.stimuli_inquiry, self.stimuli_timing, self.stimuli_colors) ] - def add_timing(self, stimuli: str, stamp: Optional[float] = None): + def add_timing(self, stimuli: str, stamp: Optional[float] = None) -> None: """Add a new timing entry using the stimuli as a label. - Useful as a callback function to register a marker at the time it is - first displayed.""" + Args: + stimuli (str): Label for the timing entry. + stamp (Optional[float]): Timestamp. If None, uses current time. + """ stamp = stamp or self.experiment_clock.getTime() self._timing.append((stimuli, stamp)) - def reset_timing(self): + def reset_timing(self) -> None: """Reset the trigger timing.""" self._timing = [] def do_inquiry(self) -> List[Tuple[str, float]]: - """Animates an inquiry of stimuli and returns a list of stimuli trigger timing.""" + """Animate an inquiry of stimuli and return timing information. + + Returns: + List[Tuple[str, float]]: List of stimuli trigger timing. + """ self.preview_accepted = True self.reset_timing() symbol_durations = self.symbol_durations() @@ -234,36 +309,44 @@ def do_inquiry(self) -> List[Tuple[str, float]]: return self._timing def build_grid(self) -> Dict[str, visual.TextStim]: - """Build the text stimuli to populate the grid.""" + """Build the text stimuli to populate the grid. + Returns: + Dict[str, visual.TextStim]: Dictionary mapping symbols to text stimuli. + """ grid = {} - for sym in self.symbol_set: - pos_index = self.sort_order(sym) - pos = self.positions[pos_index] - grid[sym] = visual.TextStim(win=self.window, - font=self.stimuli_font, - text=sym, - color=self.grid_color, - opacity=self.start_opacity, - pos=pos, - height=self.grid_stimuli_height) + if self.symbol_set: + for sym in self.symbol_set: + pos_index = self.sort_order(sym) + pos = self.positions[pos_index] + grid[sym] = visual.TextStim( + win=self.window, + font=self.stimuli_font, + text=sym, + color=self.grid_color, + opacity=self.start_opacity, + pos=pos, + height=self.grid_stimuli_height + ) return grid - def draw_grid(self, - opacity: float = 1, - color: Optional[str] = 'white', - highlight: Optional[List[str]] = None, - highlight_color: Optional[str] = None): + def draw_grid( + self, + opacity: float = 1, + color: Optional[str] = 'white', + highlight: Optional[List[str]] = None, + highlight_color: Optional[str] = None + ) -> None: """Draw the grid. - Parameters - ---------- - opacity - opacity for each item in the matrix - color - optional color for each item in the matrix - highlight - optional list of stim labels to be highlighted - (rendered using the highlight_opacity). - highlight_color - optional color to use for rendering the - highlighted stim. + Args: + opacity (float): Opacity for each item in the matrix. Defaults to 1. + color (Optional[str]): Optional color for each item in the matrix. + Defaults to 'white'. + highlight (Optional[List[str]]): Optional list of stim labels to be highlighted. + Defaults to None. + highlight_color (Optional[str]): Optional color to use for rendering the + highlighted stim. Defaults to None. """ for symbol, stim in self.stim_registry.items(): should_highlight = highlight and (symbol in highlight) @@ -273,32 +356,32 @@ def draw_grid(self, if highlight_color and should_highlight else color) stim.draw() - def prompt_target(self, target: SymbolDuration) -> float: - """Present the target for the configured length of time. Records the - stimuli timing information. + def prompt_target(self, target: SymbolDuration) -> None: + """Present the target for the configured length of time. - Parameters - ---------- - target - (symbol, duration) tuple + Args: + target (SymbolDuration): Target symbol and its duration. """ # register any timing and marker callbacks self.window.callOnFlip(self.add_timing, target.symbol) - self.draw(grid_opacity=self.start_opacity, - duration=target.duration, - highlight=[target.symbol], - highlight_color=target.color) + self.draw( + grid_opacity=self.start_opacity, + duration=target.duration, + highlight=[target.symbol], + highlight_color=target.color + ) def preview_inquiry(self, stimuli: List[SymbolDuration]) -> bool: - """"Preview the inquiry and handle any button presses. - Parameters - ---------- - stimuli - list of stimuli to highlight (will be flashed in next inquiry) - - Returns - ------- - boolean indicating whether the participant would like to proceed - with the inquiry (True) or reject the inquiry (False) and - go on to the next one. + """Preview the inquiry and handle any button presses. + + Args: + stimuli (List[SymbolDuration]): List of stimuli to highlight. + + Returns: + bool: True if participant wants to proceed, False to reject. + + Raises: + AssertionError: If preview is not enabled or button handler not initialized. """ assert self.preview_enabled, "Preview feature not enabled." assert self.preview_button_handler, "Button handler must be initialized" @@ -312,90 +395,115 @@ def preview_inquiry(self, stimuli: List[SymbolDuration]) -> bool: if handler.has_response(): self.add_timing(handler.response_label, handler.response_timestamp) - self.draw(grid_opacity=self.start_opacity, - duration=self.preview_params.preview_inquiry_isi) + if self.preview_params: + self.draw( + grid_opacity=self.start_opacity, + duration=self.preview_params.preview_inquiry_isi + ) return handler.accept_result() def draw_preview(self, stimuli: List[SymbolDuration]) -> None: - """Draw the inquiry preview by highlighting all of the symbols in the - list.""" - self.draw(grid_opacity=self.start_opacity, - highlight=[stim.symbol for stim in stimuli]) - - def draw(self, - grid_opacity: float, - grid_color: Optional[str] = None, - duration: Optional[float] = None, - highlight: Optional[List[str]] = None, - highlight_color: Optional[str] = None): + """Draw the inquiry preview by highlighting all of the symbols in the list. + + Args: + stimuli (List[SymbolDuration]): List of stimuli to highlight. + """ + self.draw( + grid_opacity=self.start_opacity, + highlight=[stim.symbol for stim in stimuli] + ) + + def draw( + self, + grid_opacity: float, + grid_color: Optional[str] = None, + duration: Optional[float] = None, + highlight: Optional[List[str]] = None, + highlight_color: Optional[str] = None + ) -> None: """Draw all screen elements and flip the window. - Parameters - ---------- - grid_opacity - opacity value to use on all grid symbols - grid_color - optional color to use for all grid symbols - duration - optional seconds to wait after flipping the window. - highlight - optional list of symbols to highlight in the grid. - highlight_color - optional color to use for rendering the - highlighted stim. + Args: + grid_opacity (float): Opacity value to use on all grid symbols. + grid_color (Optional[str]): Optional color to use for all grid symbols. + Defaults to None. + duration (Optional[float]): Optional seconds to wait after flipping the window. + Defaults to None. + highlight (Optional[List[str]]): Optional list of symbols to highlight in the grid. + Defaults to None. + highlight_color (Optional[str]): Optional color to use for rendering the + highlighted stim. Defaults to None. """ - self.draw_grid(opacity=grid_opacity, - color=grid_color or self.grid_color, - highlight=highlight, - highlight_color=highlight_color) + self.draw_grid( + opacity=grid_opacity, + color=grid_color or self.grid_color, + highlight=highlight, + highlight_color=highlight_color + ) self.draw_components() self.window.flip() if duration: core.wait(duration) - def animate_scp(self, fixation: SymbolDuration, - stimuli: List[SymbolDuration]) -> None: + def animate_scp(self, fixation: SymbolDuration, stimuli: List[SymbolDuration]) -> None: """Animate the given stimuli using single character presentation. - Flashes each stimuli in stimuli_inquiry for their respective flash - times and records the timing information. + Args: + fixation (SymbolDuration): Fixation symbol and duration. + stimuli (List[SymbolDuration]): List of stimuli to animate. """ - # Flashing the grid at full opacity is considered fixation. self.window.callOnFlip(self.add_timing, fixation.symbol) - self.draw(grid_opacity=self.full_grid_opacity, - grid_color=(fixation.color if self.should_prompt_target else - self.grid_color), - duration=fixation.duration / 2) - self.draw(grid_opacity=self.start_opacity, - duration=fixation.duration / 2) + self.draw( + grid_opacity=self.full_grid_opacity, + grid_color=(fixation.color if self.should_prompt_target else + self.grid_color), + duration=fixation.duration / 2 + ) + self.draw( + grid_opacity=self.start_opacity, + duration=fixation.duration / 2 + ) for stim in stimuli: self.window.callOnFlip(self.add_timing, stim.symbol) - self.draw(grid_opacity=self.start_opacity, - duration=stim.duration, - highlight=[stim.symbol], - highlight_color=stim.color) + self.draw( + grid_opacity=self.start_opacity, + duration=stim.duration, + highlight=[stim.symbol], + highlight_color=stim.color + ) self.draw(self.start_opacity) def wait_screen(self, message: str, message_color: str) -> None: - """Wait Screen. + """Display a wait screen with a message. - Define what happens on the screen when a user pauses a session. + Args: + message (str): Message to display. + message_color (str): Color of the message. """ self.draw_components() # Construct the wait message - wait_message = visual.TextStim(win=self.window, - font=self.stimuli_font, - text=message, - height=.1, - color=message_color, - pos=(0, -.5), - wrapWidth=2) + wait_message = visual.TextStim( + win=self.window, + font=self.stimuli_font, + text=message, + height=.1, + color=message_color, + pos=(0, -.5), + wrapWidth=2 + ) # try adding the BciPy logo to the wait screen try: - wait_logo = visual.ImageStim(self.window, - image=BCIPY_LOGO_PATH, - pos=(0, .25), - mask=None, - ori=0.0) + wait_logo = visual.ImageStim( + self.window, + image=BCIPY_LOGO_PATH, + pos=(0, .25), + mask=None, + ori=0.0 + ) wait_logo.size = resize_image(BCIPY_LOGO_PATH, self.window.size, 1) wait_logo.draw() @@ -422,29 +530,29 @@ def draw_components(self) -> None: info.draw() def update_task_bar(self, text: str = '') -> None: - """Update Task. - - Update any task related display items not related to the inquiry. Ex. stimuli count 1/200. + """Update task related display items. - PARAMETERS: - - text: text for task + Args: + text (str): Text for task. Defaults to ''. """ if self.task_bar: self.task_bar.update(text) def _trigger_pulse(self) -> None: - """Trigger Pulse. + """Send a calibration trigger pulse. This method uses a calibration trigger to determine any functional - offsets needed for operation with this display. By setting the first_stim_time and searching for the - same stimuli output to the marker stream, the offsets between these proceses can be reconciled at the - beginning of an experiment. If drift is detected in your experiment, more frequent pulses and offset - correction may be required. + offsets needed for operation with this display. By setting the first_stim_time + and searching for the same stimuli output to the marker stream, the offsets + between these processes can be reconciled at the beginning of an experiment. + If drift is detected in your experiment, more frequent pulses and offset + correction may be required. """ - calibration_time = _calibration_trigger(self.experiment_clock, - trigger_type=self.trigger_type, - display=self.window) + calibration_time = _calibration_trigger( + self.experiment_clock, + trigger_type=self.trigger_type, + display=self.window + ) # set the first stim time if not present and first_run to False if not self.first_stim_time: diff --git a/bcipy/display/paradigm/matrix/layout.py b/bcipy/display/paradigm/matrix/layout.py index 994642bf4..8267a3354 100644 --- a/bcipy/display/paradigm/matrix/layout.py +++ b/bcipy/display/paradigm/matrix/layout.py @@ -1,4 +1,10 @@ -"""Functions for calculating matrix layouts""" +"""Functions for calculating matrix layouts. + +This module provides functionality for calculating and managing the layout of symbols +in a matrix-style grid format, commonly used in BCI paradigms. It handles the +positioning and spacing of elements based on window dimensions and layout requirements. +""" + from typing import List, Optional, Tuple from bcipy.display.components.layout import (Layout, above, below, left_of, @@ -6,26 +12,35 @@ scaled_width) -def symbol_positions(container: Layout, - rows: int, - columns: int, - symbol_set: List[str], - max_spacing: Optional[float] = None) -> List[Tuple[float, float]]: - """Compute the positions for arranging a number of symbols in a grid - layout. +def symbol_positions( + container: Layout, + rows: int, + columns: int, + symbol_set: List[str], + max_spacing: Optional[float] = None +) -> List[Tuple[float, float]]: + """Compute the positions for arranging a number of symbols in a grid layout. + + This function calculates the positions for placing symbols in a grid format, + taking into account window dimensions, aspect ratio, and spacing requirements. + The grid is centered in the container and positions are returned in row-major order. - Parameters - ---------- - container - container in which the grid should be placed; must have a + Args: + container (Layout): Container in which the grid should be placed; must have a visual.Window parent, which is used to determine the aspect ratio. - rows - number of rows in the grid - columns - number of columns in the grid - symbol_set - list of symbols to place in the grid - max_spacing - optional max spacing (in layout units) in the height - direction; width will be normalized to this value if provided - Returns - ------- - list of (x,y) tuples with (rows * columns) positions in row,col order + rows (int): Number of rows in the grid. + columns (int): Number of columns in the grid. + symbol_set (List[str]): List of symbols to place in the grid. + max_spacing (Optional[float]): Optional max spacing (in layout units) in the height + direction; width will be normalized to this value if provided. Defaults to None. + + Returns: + List[Tuple[float, float]]: List of (x,y) tuples with (rows * columns) positions + in row-major order. + + Raises: + AssertionError: If container has no parent, if rows or columns are less than 1, + or if there are not enough positions for all symbols. """ assert container.parent, "Container must have a parent" assert rows >= 1 and columns >= 1, "There must be at least one row and one column" diff --git a/bcipy/display/paradigm/rsvp/__init__.py b/bcipy/display/paradigm/rsvp/__init__.py index 82283e37c..9423f249d 100644 --- a/bcipy/display/paradigm/rsvp/__init__.py +++ b/bcipy/display/paradigm/rsvp/__init__.py @@ -1,6 +1,4 @@ -from .display import ( - RSVPDisplay -) +from .display import RSVPDisplay __all__ = [ 'RSVPDisplay' diff --git a/bcipy/display/paradigm/rsvp/display.py b/bcipy/display/paradigm/rsvp/display.py index 2a696b12d..2c075edad 100644 --- a/bcipy/display/paradigm/rsvp/display.py +++ b/bcipy/display/paradigm/rsvp/display.py @@ -1,30 +1,69 @@ +"""RSVP display module. + +This module provides the base RSVP (Rapid Serial Visual Presentation) display implementation +which handles the visual presentation of stimuli during RSVP tasks. It provides core functionality +for stimulus presentation, timing control, and inquiry management. +""" + import logging import os.path as path -from typing import List, Optional, Tuple +from typing import Any, Callable, Dict, List, Optional, Tuple, Union from psychopy import core, visual +from bcipy.core.stimuli import resize_image +from bcipy.core.symbols import SPACE_CHAR +from bcipy.core.triggers import TriggerCallback, _calibration_trigger from bcipy.display import (BCIPY_LOGO_PATH, Display, InformationProperties, StimuliProperties) from bcipy.display.components.task_bar import TaskBar from bcipy.display.main import PreviewParams, init_preview_button_handler from bcipy.helpers.clock import Clock -from bcipy.helpers.stimuli import resize_image -from bcipy.helpers.symbols import SPACE_CHAR -from bcipy.helpers.system_utils import get_screen_info -from bcipy.helpers.triggers import TriggerCallback, _calibration_trigger +from bcipy.helpers.utils import get_screen_info class RSVPDisplay(Display): """RSVP Display Object for inquiry Presentation. - Animates display objects common to any RSVP task. + Animates display objects common to any RSVP task. Handles stimulus presentation, + timing control, and inquiry management for RSVP-based BCI paradigms. + + Attributes: + window (visual.Window): PsychoPy window for display. + window_size (Tuple[float, float]): Size of the display window. + refresh_rate (float): Display refresh rate. + stimuli_inquiry (List[str]): List of stimuli to present. + stimuli_colors (List[str]): List of colors for each stimulus. + stimuli_timing (List[float]): List of presentation durations. + stimuli_font (str): Font to use for text stimuli. + textbox_font (str): Font to use for text boxes. + stimuli_height (float): Height of stimuli. + stimuli_pos (Tuple[float, float]): Position of stimuli. + is_txt_stim (bool): Whether stimuli are text-based. + stim_length (int): Length of stimulus list. + full_screen (bool): Whether display is fullscreen. + preview_params (Optional[PreviewParams]): Preview configuration. + preview_button_handler (Optional[Any]): Handler for preview buttons. + preview_accepted (bool): Whether preview was accepted. + staticPeriod (core.StaticPeriod): Clock for static timing. + first_run (bool): Whether this is the first run. + first_stim_time (Optional[float]): Time of first stimulus. + trigger_type (str): Type of trigger to use. + trigger_callback (TriggerCallback): Callback for triggers. + experiment_clock (Clock): Clock for experiment timing. + first_stim_callback (Callable): Callback for first stimulus. + size_list_sti (List[float]): List of stimulus sizes. + space_char (str): Character to use for spaces. + task_bar (TaskBar): Task bar component. + info (InformationProperties): Information display properties. + info_text (List[visual.TextStim]): Text stimuli for information. + sti (List[visual.TextStim]): Initial stimuli objects. """ def __init__( self, window: visual.Window, - static_clock, + static_clock: core.StaticPeriod, experiment_clock: Clock, stimuli: StimuliProperties, task_bar: TaskBar, @@ -32,34 +71,21 @@ def __init__( preview_config: Optional[PreviewParams] = None, trigger_type: str = 'image', space_char: str = SPACE_CHAR, - full_screen: bool = False): + full_screen: bool = False) -> None: """Initialize RSVP display parameters and objects. - PARAMETERS: - ---------- - # Experiment - window(visual.Window): PsychoPy Window - static_clock(core.MonotonicClock): Used to schedule static periods of display time - experiment_clock(Clock): Clock used to timestamp display onsets - - # Stimuli - stimuli(StimuliProperties): attributes used for inquiries - - # Task - task_bar(TaskBar): used for task tracking. Ex. 1/100 - - # Info - info(InformationProperties): attributes to display informational stimuli alongside task and inquiry stimuli. - - # Preview Inquiry - preview_config(PreviewParams) Optional: parameters used to specify the behavior for displaying a preview - of upcoming stimuli defined via self.stimuli(StimuliProperties). If None a preview is not displayed. - - 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. + Args: + window (visual.Window): PsychoPy Window for display. + static_clock (core.StaticPeriod): Used to schedule static periods of display time. + experiment_clock (Clock): Clock used to timestamp display onsets. + stimuli (StimuliProperties): Attributes used for inquiries. + task_bar (TaskBar): Used for task tracking. Ex. 1/100. + info (InformationProperties): Attributes to display informational stimuli. + preview_config (Optional[PreviewParams]): Parameters for preview functionality. + If None, preview is not displayed. + trigger_type (str, optional): Defines the calibration trigger type. Defaults to 'image'. + space_char (str, optional): Character to use for spaces. Defaults to SPACE_CHAR. + full_screen (bool, optional): Whether window is fullscreen. Defaults to False. """ self.window = window self.window_size = self.window.size # [w, h] @@ -67,14 +93,12 @@ def __init__( self.logger = logging.getLogger(__name__) - # Stimuli parameters, these are set on display in order to allow - # easy updating after definition + # Stimuli parameters self.stimuli_inquiry = stimuli.stim_inquiry 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.textbox_font = 'Consolas' # Avoid TextBox2 font bug self.stimuli_height = stimuli.stim_height self.stimuli_pos = stimuli.stim_pos self.is_txt_stim = stimuli.is_txt_stim @@ -97,9 +121,9 @@ def __init__( self.experiment_clock = experiment_clock # Callback used on presentation of first stimulus. - self.first_stim_callback = lambda _sti: None - self.size_list_sti = [] # TODO force initial size definition - self.space_char = space_char # TODO remove and force task to define + self.first_stim_callback: Callable = lambda _sti: None + self.size_list_sti: List[float] = [] + self.space_char = space_char self.task_bar = task_bar @@ -112,10 +136,14 @@ def __init__( @property def preview_enabled(self) -> bool: - """Should the inquiry preview be enabled.""" - return self.preview_params and self.preview_params.show_preview_inquiry + """Check if inquiry preview should be enabled. + + Returns: + bool: True if preview is enabled and configured, False otherwise. + """ + return bool(self.preview_params and self.preview_params.show_preview_inquiry) - def draw_static(self): + def draw_static(self) -> None: """Draw static elements in a stimulus.""" if self.task_bar: self.task_bar.draw() @@ -125,13 +153,13 @@ def draw_static(self): def schedule_to(self, stimuli: Optional[List[str]] = None, timing: Optional[List[float]] = None, - colors: Optional[List[str]] = None): + colors: Optional[List[str]] = None) -> None: """Schedule stimuli elements (works as a buffer). Args: - stimuli(list[string]): list of stimuli text / name - timing(list[float]): list of timings of stimuli - colors(list[string]): list of colors + stimuli (Optional[List[str]]): List of stimuli text/name. + timing (Optional[List[float]]): List of timings of stimuli. + colors (Optional[List[str]]): List of colors. """ self.stimuli_inquiry = stimuli or [] self.stimuli_timing = timing or [] @@ -139,104 +167,93 @@ def schedule_to(self, @property def preview_index(self) -> int: - """Index within an inquiry at which the inquiry preview should be displayed. + """Get index within an inquiry at which the preview should be displayed. For calibration, we should display it after the target prompt (index = 1). For copy phrase there is no target prompt so it should display before the - rest of the inquiry.""" + rest of the inquiry. + + Returns: + int: The index at which to display the preview. + """ return 1 def do_inquiry(self) -> List[Tuple[str, float]]: - """Do inquiry. + """Perform an inquiry of flashing letters to achieve RSVP. - Animates an inquiry of flashing letters to achieve RSVP. - - - RETURNS: - -------- - timing(list[float]): list of timings of stimuli presented in the inquiry + Returns: + List[Tuple[str, float]]: List of timings of stimuli presented in the inquiry. """ - - # init an array for timing information timing: List[Tuple[str, float]] = [] self.preview_accepted = True if self.first_run: self._trigger_pulse() - # generate a inquiry (list of stimuli with meta information) inquiry = self._generate_inquiry() - # do the inquiry for idx, stim_props in enumerate(inquiry): - - # If this is the start of an inquiry and a callback registered for first_stim_callback evoke it if idx == 0 and callable(self.first_stim_callback): self.first_stim_callback(stim_props['sti']) - # If previewing the inquiry during calibration, do so after the first stimulus if self.preview_enabled and idx == self.preview_index: self.preview_accepted = self.preview_inquiry(timing) if not self.preview_accepted: break - # Reset the timing clock to start presenting self.window.callOnFlip( self.trigger_callback.callback, self.experiment_clock, stim_props['sti_label']) - # Draw stimulus for n frames stim_props['sti'].draw() self.draw_static() self.window.flip() core.wait(stim_props['time_to_present']) - # append timing information timing.append(self.trigger_callback.timing) - self.trigger_callback.reset() - # draw in static and flip once more self.draw_static() self.window.flip() return timing def _trigger_pulse(self) -> None: - """Trigger Pulse. + """Send a calibration trigger pulse. - This method uses a calibration trigger to determine any functional - offsets needed for operation with this display. By setting the first_stim_time and searching for the - same stimuli output to the marker stream, the offsets between these proceses can be reconciled at the - beginning of an experiment. If drift is detected in your experiment, more frequent pulses and offset - correction may be required. + Uses a calibration trigger to determine any functional offsets needed for + operation with this display. Sets first_stim_time and searches for the same + stimuli output to the marker stream to reconcile timing offsets. """ calibration_time = _calibration_trigger( self.experiment_clock, trigger_type=self.trigger_type, display=self.window) - # set the first stim time if not present and first_run to False if not self.first_stim_time: self.first_stim_time = calibration_time[-1] self.first_run = False def preview_inquiry(self, timing: List[Tuple[str, float]]) -> bool: - """Preview Inquiry. + """Preview the inquiry before presentation. Given an inquiry defined to be presented via do_inquiry(), present the full inquiry - to the user and allow input on whether the intended letter is present or not before - going through the rapid serial visual presention. + to the user and allow input on whether the intended letter is present or not before + going through the rapid serial visual presentation. + + Args: + timing (List[Tuple[str, float]]): List to which timing information should be appended. - Parameters: - timing - list to which all timing information should be appended. Returns: - - A boolean describing whether to present the inquiry (True) or - generate another (False). + bool: True if inquiry should be presented, False if a new one should be generated. + + Raises: + AssertionError: If preview is not enabled or button handler is not initialized. """ assert self.preview_enabled, "Preview feature not enabled." assert self.preview_button_handler, "Button handler must be initialized" + assert self.preview_params is not None, "Preview parameters must be set" handler = self.preview_button_handler self.window.callOnFlip( @@ -257,19 +274,26 @@ def preview_inquiry(self, timing: List[Tuple[str, float]]) -> bool: return handler.accept_result() - def draw_preview(self): - """Generate and draw the inquiry preview""" + def draw_preview(self) -> None: + """Generate and draw the inquiry preview.""" content = self._generate_inquiry_preview() content.draw() self.draw_static() self.window.flip() def _generate_inquiry_preview(self) -> visual.TextBox2: - """Generate Inquiry Preview. + """Generate the inquiry preview box. - Using the self.stimuli_inquiry list, construct a preview box to display to the user. This method - assumes the presence of a fixation (+). + Using the self.stimuli_inquiry list, construct a preview box to display to the user. + Assumes the presence of a fixation (+). + + Returns: + visual.TextBox2: The preview text box. + + Raises: + AssertionError: If preview parameters are not set. """ + assert self.preview_params is not None, "Preview parameters must be set" text = ' '.join(self.stimuli_inquiry).split('+ ')[1] return self._create_stimulus( @@ -280,10 +304,11 @@ def _generate_inquiry_preview(self) -> visual.TextBox2: mode='textbox', align_text='left') - def _generate_inquiry(self) -> list: - """Generate inquiry. + def _generate_inquiry(self) -> List[Dict[str, Any]]: + """Generate stimuli for next RSVP inquiry. - Generate stimuli for next RSVP inquiry. [A + A, C, Q, D] + Returns: + List[Dict[str, Any]]: List of stimulus properties for the inquiry. """ stim_info = [] for idx, stim in enumerate(self.stimuli_inquiry): @@ -291,13 +316,9 @@ def _generate_inquiry(self) -> list: current_stim['time_to_present'] = self.stimuli_timing[idx] - # check if stimulus needs to use a non-default size - if self.size_list_sti: - this_stimuli_size = self.size_list_sti[idx] - else: - this_stimuli_size = self.stimuli_height + this_stimuli_size = (self.size_list_sti[idx] if self.size_list_sti + else self.stimuli_height) - # Set the Stimuli attrs if stim.endswith('.png'): current_stim['sti'] = self._create_stimulus( mode='image', @@ -309,32 +330,27 @@ def _generate_inquiry(self) -> list: current_stim['sti_label'] = path.splitext( path.basename(stim))[0] else: - # text stimulus - current_stim['sti'] = self._create_stimulus(mode='text', height=this_stimuli_size) + current_stim['sti'] = self._create_stimulus( + mode='text', height=this_stimuli_size) txt = stim - # customize presentation of space char. current_stim['sti'].text = txt if txt != SPACE_CHAR else self.space_char current_stim['sti'].color = self.stimuli_colors[idx] current_stim['sti_label'] = txt - # test whether the word will be too big for the screen text_width = current_stim['sti'].boundingBox[0] if text_width > self.window.size[0]: screen_info = get_screen_info() monitor_width = screen_info.width monitor_height = screen_info.height text_height = current_stim['sti'].boundingBox[1] - # If we are in full-screen, text size in Psychopy norm units - # is monitor width/monitor height if self.window.size[0] == monitor_width: new_text_width = monitor_width / monitor_height else: - # If not, text width is calculated relative to both - # monitor size and window size new_text_width = ( self.window.size[1] / monitor_height) * ( monitor_width / monitor_height) - new_text_height = (text_height * new_text_width) / text_width + new_text_height = ( + text_height * new_text_width) / text_width current_stim['sti'].height = new_text_height stim_info.append(current_stim) return stim_info @@ -342,22 +358,22 @@ def _generate_inquiry(self) -> list: def update_task_bar(self, text: Optional[str] = None) -> None: """Update task state. - Removes letters or appends to the right. Args: - text(string): new text for task state + text (Optional[str]): New text for task state. """ if self.task_bar: self.task_bar.update(text) def wait_screen(self, message: str, message_color: str) -> None: - """Wait Screen. + """Display a wait screen with message and optional logo. Args: - message(string): message to be displayed while waiting - message_color(string): color of the message to be displayed - """ + message (str): Message to be displayed while waiting. + message_color (str): Color of the message to be displayed. - # Construct the wait message + Raises: + Exception: If the logo image cannot be loaded. + """ wait_message = visual.TextStim(win=self.window, font=self.stimuli_font, text=message, @@ -369,7 +385,6 @@ def wait_screen(self, message: str, message_color: str) -> None: opacity=1, depth=-6.0) - # try adding the BciPy logo to the wait screen try: wait_logo = visual.ImageStim( self.window, @@ -384,27 +399,41 @@ def wait_screen(self, message: str, message_color: str) -> None: wait_logo.draw() except Exception as e: - self.logger.exception(f'Cannot load logo image from path=[{BCIPY_LOGO_PATH}]') + self.logger.exception( + f'Cannot load logo image from path=[{BCIPY_LOGO_PATH}]') raise e - # Draw and flip the screen. wait_message.draw() self.window.flip() def _create_stimulus( self, - height: int, + height: float, mode: str = 'text', - stimulus='+', - color='white', - stimuli_position=None, - align_text='center', - units=None, - wrap_width=None, - border=False): - """Create Stimulus. - - Returns a TextStim, ImageStim or TextBox object. + stimulus: str = '+', + color: str = 'white', + stimuli_position: Optional[Tuple[float, float]] = None, + align_text: str = 'center', + units: Optional[str] = None, + wrap_width: Optional[float] = None, + border: bool = False) -> Union[visual.TextStim, visual.ImageStim, visual.TextBox2]: + """Create a stimulus object. + + Args: + height (float): Height of the stimulus. + mode (str, optional): Type of stimulus ('text', 'image', or 'textbox'). + Defaults to 'text'. + stimulus (str, optional): Content of the stimulus. Defaults to '+'. + color (str, optional): Color of the stimulus. Defaults to 'white'. + stimuli_position (Optional[Tuple[float, float]], optional): Position of the stimulus. + Defaults to None. + align_text (str, optional): Text alignment. Defaults to 'center'. + units (Optional[str], optional): Units for size/position. Defaults to None. + wrap_width (Optional[float], optional): Width for text wrapping. Defaults to None. + border (bool, optional): Whether to show border. Defaults to False. + + Returns: + Union[visual.TextStim, visual.ImageStim, visual.TextBox2]: The created stimulus object. """ if not stimuli_position: stimuli_position = self.stimuli_pos @@ -448,3 +477,6 @@ def _create_stimulus( alignment=align_text, editable=False, ) + else: + raise ValueError( + f'RSVPDisplay asked to create a stimulus type=[{mode}] that is not supported.') diff --git a/bcipy/display/paradigm/rsvp/mode/calibration.py b/bcipy/display/paradigm/rsvp/mode/calibration.py index df261ddef..c1efd1c95 100644 --- a/bcipy/display/paradigm/rsvp/mode/calibration.py +++ b/bcipy/display/paradigm/rsvp/mode/calibration.py @@ -1,22 +1,59 @@ +"""RSVP calibration display module. + +This module provides the RSVP calibration display implementation which handles the visual +presentation of stimuli during calibration tasks. It extends the base RSVP display with +calibration-specific functionality. +""" +from typing import Optional + +from psychopy import core, visual + +from bcipy.core.symbols import SPACE_CHAR +from bcipy.display import InformationProperties, StimuliProperties +from bcipy.display.components.task_bar import TaskBar +from bcipy.display.main import PreviewParams from bcipy.display.paradigm.rsvp.display import RSVPDisplay -from bcipy.helpers.symbols import SPACE_CHAR class CalibrationDisplay(RSVPDisplay): - """Calibration Display.""" + """Calibration Display for RSVP paradigm. + + This class extends the RSVPDisplay to provide calibration-specific functionality. + It handles the visual presentation of stimuli during calibration tasks, including + preview functionality and timing control. + + Attributes: + preview_index (int): Index within an inquiry at which the inquiry preview + should be displayed. For calibration, this is set to 1 (after target prompt). + """ def __init__(self, - window, - static_clock, - experiment_clock, - stimuli, - task_bar, - info, - trigger_type='image', - preview_config=None, - space_char=SPACE_CHAR, - full_screen=False): + window: visual.Window, + static_clock: core.StaticPeriod, + experiment_clock: core.Clock, + stimuli: StimuliProperties, + task_bar: TaskBar, + info: InformationProperties, + trigger_type: str = 'image', + preview_config: Optional[PreviewParams] = None, + space_char: str = SPACE_CHAR, + full_screen: bool = False) -> None: + """Initialize the RSVP calibration display. + Args: + window (visual.Window): PsychoPy window for display. + static_clock (core.StaticPeriod): Clock for static timing. + experiment_clock (core.Clock): Clock for experiment timing. + stimuli (StimuliProperties): Properties for stimulus presentation. + task_bar (TaskBar): Task bar component for progress display. + info (InformationProperties): Properties for information display. + trigger_type (str, optional): Type of trigger to use. Defaults to 'image'. + preview_config (Optional[PreviewParams], optional): Configuration for preview + functionality. Defaults to None. + space_char (str, optional): Character to use for spaces. Defaults to SPACE_CHAR. + full_screen (bool, optional): Whether to display in fullscreen mode. + Defaults to False. + """ super().__init__(window, static_clock, experiment_clock, @@ -33,5 +70,8 @@ def preview_index(self) -> int: """Index within an inquiry at which the inquiry preview should be displayed. For calibration, we should display it after the target prompt (index = 1). + + Returns: + int: The index at which to display the preview (1 for calibration). """ return 1 diff --git a/bcipy/display/paradigm/rsvp/mode/copy_phrase.py b/bcipy/display/paradigm/rsvp/mode/copy_phrase.py index 051a14557..a516484fc 100644 --- a/bcipy/display/paradigm/rsvp/mode/copy_phrase.py +++ b/bcipy/display/paradigm/rsvp/mode/copy_phrase.py @@ -1,42 +1,72 @@ -from psychopy import visual +"""RSVP copy phrase display module. -from bcipy.display.paradigm.rsvp.display import BCIPY_LOGO_PATH, RSVPDisplay -from bcipy.helpers.stimuli import resize_image -from bcipy.helpers.symbols import SPACE_CHAR - -"""Note: +This module provides the RSVP copy phrase display implementation which handles the visual +presentation of stimuli during copy phrase tasks. It extends the base RSVP display with +copy phrase-specific functionality. -RSVP Tasks are RSVPDisplay objects with different structure. They share -the tasks and the essential elements and stimuli. However, layout, length of -stimuli list, update procedures and colors are different. Therefore each -mode should be separated from each other carefully. -Functions: - update_task_state: update task information of the module +Note: + RSVP Tasks are RSVPDisplay objects with different structure. They share + the tasks and the essential elements and stimuli. However, layout, length of + stimuli list, update procedures and colors are different. Therefore each + mode should be separated from each other carefully. """ +from typing import Optional + +from psychopy import core, visual + +from bcipy.core.stimuli import resize_image +from bcipy.core.symbols import SPACE_CHAR +from bcipy.display import InformationProperties, StimuliProperties +from bcipy.display.components.task_bar import TaskBar +from bcipy.display.main import PreviewParams +from bcipy.display.paradigm.rsvp.display import BCIPY_LOGO_PATH, RSVPDisplay + class CopyPhraseDisplay(RSVPDisplay): - """ Copy Phrase display object of RSVP + """Copy Phrase display object of RSVP. + + This class extends the RSVPDisplay to provide copy phrase-specific functionality. + It handles the visual presentation of stimuli during copy phrase tasks, including + preview functionality and wait screen display. - Custom attributes: - static_task_text(str): target text for the user to attempt to spell - static_task_color(str): target text color for the user to attempt to spell + Attributes: + starting_spelled_text (str): Initial text that has been spelled. + static_task_text (str): Target text for the user to attempt to spell. + static_task_color (str): Target text color for the user to attempt to spell. """ def __init__( self, - window, - clock, - experiment_clock, - stimuli, - task_bar, - info, - starting_spelled_text='', - trigger_type='image', - space_char=SPACE_CHAR, - preview_config=None, - full_screen=False): - """ Initializes Copy Phrase Task Objects """ + window: visual.Window, + clock: core.Clock, + experiment_clock: core.Clock, + stimuli: StimuliProperties, + task_bar: TaskBar, + info: InformationProperties, + starting_spelled_text: str = '', + trigger_type: str = 'image', + space_char: str = SPACE_CHAR, + preview_config: Optional[PreviewParams] = None, + full_screen: bool = False) -> None: + """Initialize Copy Phrase Task Objects. + + Args: + window (visual.Window): PsychoPy window for display. + clock (core.Clock): Clock for timing. + experiment_clock (core.Clock): Clock for experiment timing. + stimuli (StimuliProperties): Properties for stimulus presentation. + task_bar (TaskBar): Task bar component for progress display. + info (InformationProperties): Properties for information display. + starting_spelled_text (str, optional): Initial text that has been spelled. + Defaults to ''. + trigger_type (str, optional): Type of trigger to use. Defaults to 'image'. + space_char (str, optional): Character to use for spaces. Defaults to SPACE_CHAR. + preview_config (Optional[PreviewParams], optional): Configuration for preview + functionality. Defaults to None. + full_screen (bool, optional): Whether to display in fullscreen mode. + Defaults to False. + """ self.starting_spelled_text = starting_spelled_text super().__init__(window, @@ -56,17 +86,22 @@ def preview_index(self) -> int: For copy phrase there is no target prompt so it should display before the fixation. + + Returns: + int: The index at which to display the preview (0 for copy phrase). """ return 0 def wait_screen(self, message: str, message_color: str) -> None: - """Wait Screen. + """Display a wait screen with a message and optional logo. Args: - message(string): message to be displayed while waiting - message_color(string): color of the message to be displayed - """ + message (str): Message to be displayed while waiting. + message_color (str): Color of the message to be displayed. + Raises: + Exception: If the logo image cannot be loaded. + """ self.draw_static() # Construct the wait message @@ -96,7 +131,8 @@ def wait_screen(self, message: str, message_color: str) -> None: wait_logo.draw() except Exception as e: - self.logger.exception(f'Cannot load logo image from path=[{BCIPY_LOGO_PATH}]') + self.logger.exception( + f'Cannot load logo image from path=[{BCIPY_LOGO_PATH}]') raise e # Draw and flip the screen. diff --git a/bcipy/display/paradigm/vep/display.py b/bcipy/display/paradigm/vep/display.py index f3fb0afeb..6f80dfcc3 100644 --- a/bcipy/display/paradigm/vep/display.py +++ b/bcipy/display/paradigm/vep/display.py @@ -6,6 +6,10 @@ from psychopy import core, visual # type: ignore import bcipy.display.components.layout as layout +from bcipy.core.list import expanded +from bcipy.core.stimuli import resize_image +from bcipy.core.symbols import alphabet +from bcipy.core.triggers import _calibration_trigger from bcipy.display import (BCIPY_LOGO_PATH, Display, InformationProperties, VEPStimuliProperties) from bcipy.display.components.layout import scaled_size @@ -17,10 +21,6 @@ from bcipy.display.paradigm.vep.layout import BoxConfiguration, animation_path from bcipy.display.paradigm.vep.vep_stim import VEPStim from bcipy.helpers.clock import Clock -from bcipy.helpers.list import expanded -from bcipy.helpers.stimuli import resize_image -from bcipy.helpers.symbols import alphabet -from bcipy.helpers.triggers import _calibration_trigger class StimTime(NamedTuple): @@ -152,7 +152,8 @@ def check_configuration(self): def stim_properties(self) -> List[StimProps]: """Returns a tuple of (symbol, duration, and color) for each stimuli, including the target and fixation stim. Stimuli that represent VEP - boxes will have a list of symbols.""" + boxes will have a list of symbols. + """ stim_num = len(self.stimuli_inquiry) assert len(self.stimuli_colors ) == stim_num, "Each box should have its own color" @@ -221,7 +222,8 @@ def prompt_target(self, target - (symbol, duration, color) tuple """ assert isinstance(target.symbol, str), "Target must be a str" - self.logger.info(f"Target: {target.symbol} at index {target_box_index}") + self.logger.info( + f"Target: {target.symbol} at index {target_box_index}") # Show all symbols in the matrix at reduced opacity for sym in self.symbol_set: @@ -313,7 +315,8 @@ def animate_inquiry(self, stimuli: List[StimProps]) -> None: def set_stimuli_colors(self, stim_groups: List[StimProps]) -> None: """Update the colors of the stimuli associated with each symbol to - reflect which box it will be placed in.""" + reflect which box it will be placed in. + """ for group in stim_groups: for sym in group.symbol: self.sti[sym].color = group.color @@ -399,7 +402,8 @@ def add_timing(self, stimuli: str): """Add a new timing entry using the stimuli as a label. Useful as a callback function to register a marker at the time it is - first displayed.""" + first displayed. + """ self._timing.append(StimTime(stimuli, self.experiment_clock.getTime())) def reset_timing(self): @@ -461,8 +465,7 @@ def _trigger_pulse(self) -> None: def schedule_to(self, stimuli: List[List[Any]], timing: Optional[List[List[float]]] = None, colors: Optional[List[List[str]]] = None) -> None: - """Schedule stimuli elements (works as a buffer). - """ + """Schedule stimuli elements (works as a buffer).""" self.stimuli_inquiry = stimuli # type: ignore assert timing is None or timing == self.stimuli_timing, "Timing values must match pre-configured values" assert colors is None or colors == self.stimuli_colors, "Colors must match the pre-configured values" @@ -503,8 +506,7 @@ def _reset_text_boxes(self) -> None: text_box.borderWidth = self.box_border_width def _set_inquiry(self, stimuli: List[StimProps]) -> List[visual.TextBox2]: - """Set the correct inquiry text for each text boxes. - """ + """Set the correct inquiry text for each text boxes.""" for i, sti in enumerate(stimuli): box = self.text_boxes[i] text = ' '.join(sti.symbol) diff --git a/bcipy/display/tests/components/test_layout.py b/bcipy/display/tests/components/test_layout.py index 846c589c1..d0432d90f 100644 --- a/bcipy/display/tests/components/test_layout.py +++ b/bcipy/display/tests/components/test_layout.py @@ -189,7 +189,8 @@ def test_scaled_size(self): msg="Width should be proportional to the window aspect") self.assertEqual( - scaled_size(height=0.2, window_size=(800, 500), units='height'), (0.2, 0.2), + scaled_size(height=0.2, window_size=( + 800, 500), units='height'), (0.2, 0.2), msg="Width should be the same in 'height' units") def test_scaled_height(self): diff --git a/bcipy/display/tests/components/test_task_bar.py b/bcipy/display/tests/components/test_task_bar.py index 94f5183d7..6ec210b77 100644 --- a/bcipy/display/tests/components/test_task_bar.py +++ b/bcipy/display/tests/components/test_task_bar.py @@ -1,7 +1,9 @@ """Task bar component tests""" import unittest -from unittest.mock import patch, Mock -from bcipy.display.components.task_bar import TaskBar, CalibrationTaskBar, CopyPhraseTaskBar +from unittest.mock import Mock, patch + +from bcipy.display.components.task_bar import (CalibrationTaskBar, + CopyPhraseTaskBar, TaskBar) class TestTaskBar(unittest.TestCase): diff --git a/bcipy/display/tests/test_display.py b/bcipy/display/tests/test_display.py index 4fd9eec49..ab9d6337c 100644 --- a/bcipy/display/tests/test_display.py +++ b/bcipy/display/tests/test_display.py @@ -1,7 +1,8 @@ import unittest -from mockito import any, mock, when, unstub import psychopy +from mockito import any, mock, unstub, when + from bcipy.display.main import init_display_window diff --git a/bcipy/exceptions.py b/bcipy/exceptions.py index e58bb1615..7b6161389 100644 --- a/bcipy/exceptions.py +++ b/bcipy/exceptions.py @@ -1,104 +1,171 @@ +"""Custom exceptions for the BciPy package. + +This module contains all custom exceptions used throughout the BciPy application. +Each exception is designed to provide specific error information for different +components of the system. +""" +from typing import Any + class BciPyCoreException(Exception): - """BciPy Core Exception. + """Base exception class for BciPy-specific errors. - Thrown when an error occurs specific to BciPy core concepts. + Args: + message: A descriptive message explaining the error. + errors: Optional additional error information. + + Attributes: + message: The error message. + errors: Additional error details, if any. """ - def __init__(self, message, errors=None): + def __init__(self, message: str, errors: Any = None) -> None: super().__init__(message) self.message = message self.errors = errors class SignalException(BciPyCoreException): - """ - Signal Exception. + """Exception raised for errors in the signal processing module. - Thrown when signal module encounters an error. + This exception is raised when the signal module encounters errors during + processing or analysis of signal data. + + Args: + message: A descriptive message explaining the signal processing error. + errors: Optional additional error information. """ - def __init__(self, message, errors=None): + def __init__(self, message: str, errors: Any = None) -> None: super().__init__(message) self.errors = errors class FieldException(BciPyCoreException): - """Field Exception. + """Exception raised for errors related to experimental fields. + + This exception is raised when there are issues with field definitions, + validation, or processing in experiments. - Thrown when there is an exception relating to experimental fields. + Args: + message: A descriptive message explaining the field-related error. + errors: Optional additional error information. """ ... class ExperimentException(BciPyCoreException): - """Experiment Exception. + """Exception raised for errors related to experiment execution. + + This exception is raised when there are issues with experiment setup, + execution, or validation. - Thrown when there is an exception relating to experiments. + Args: + message: A descriptive message explaining the experiment-related error. + errors: Optional additional error information. """ ... class UnregisteredExperimentException(ExperimentException): - """Unregistered Experiment. + """Exception raised when attempting to use an unregistered experiment. - Thrown when experiment is not registered in the provided experiment path. - """ + This exception is raised when trying to access or execute an experiment + that has not been registered in the provided experiment path. + Args: + message: A descriptive message explaining which experiment was not found. + errors: Optional additional error information. + """ ... class UnregisteredFieldException(FieldException): - """Unregistered Field. + """Exception raised when attempting to use an unregistered field. - Thrown when field is not registered in the provided field path. - """ + This exception is raised when trying to access a field that has not been + registered in the provided field path. + Args: + message: A descriptive message explaining which field was not found. + errors: Optional additional error information. + """ ... class InvalidExperimentException(ExperimentException): - """Invalid Experiment Exception. + """Exception raised when experiment data is in an invalid format. - Thrown when providing experiment data in the incorrect format. - """ + This exception is raised when experiment configuration or data does not + meet the required format specifications. + Args: + message: A descriptive message explaining the format error. + errors: Optional additional error information. + """ ... class InvalidFieldException(FieldException): - """Invalid Field Exception. + """Exception raised when field data is in an invalid format. - Thrown when providing field data in the incorrect format. - """ + This exception is raised when field configuration or data does not + meet the required format specifications. + Args: + message: A descriptive message explaining the format error. + errors: Optional additional error information. + """ ... -class UnsupportedResponseType(BciPyCoreException): - """Unsupported ResponseType +class TaskConfigurationException(BciPyCoreException): + """Exception raised when task configuration is invalid. + + This exception is raised when attempting to run a task with invalid + or incompatible configuration settings. - Thrown when attempting to set the response type of a language model to an - unsupported value.""" + Args: + message: A descriptive message explaining the configuration error. + errors: Optional additional error information. + """ ... -class TaskConfigurationException(BciPyCoreException): - """Task Configuration Exception. +class KenLMInstallationException(BciPyCoreException): + """Exception raised when KenLM module is not properly installed. + + This exception is raised when attempting to use KenLM functionality + without having the required module installed. - Thrown when attempting to run a task with invalid configurations""" + Args: + message: A descriptive message explaining the installation issue. + errors: Optional additional error information. + """ ... -class InvalidLanguageModelException(BciPyCoreException): - """Invalid Language Model Exception. +class InvalidSymbolSetException(BciPyCoreException): + """Exception raised when symbol set is not properly configured. + + This exception is raised when attempting to query a language model for + predictions without properly configuring the symbol set. - Thrown when attempting to load a language model from an invalid path""" + Args: + message: A descriptive message explaining the symbol set error. + errors: Optional additional error information. + """ ... -class KenLMInstallationException(BciPyCoreException): - """KenLM Installation Exception. +class LanguageModelNameInUseException(BciPyCoreException): + """Exception raised when attempting to register a duplicate language model. + + This exception is raised when trying to register a language model type + with a name that is already in use. - Thrown when attempting to import kenlm without installing the module""" + Args: + message: A descriptive message explaining the naming conflict. + errors: Optional additional error information. + """ ... diff --git a/bcipy/feedback/README.md b/bcipy/feedback/README.md new file mode 100644 index 000000000..59b2761a8 --- /dev/null +++ b/bcipy/feedback/README.md @@ -0,0 +1,134 @@ +# BciPy Feedback Module + +The feedback module provides a flexible framework for implementing real-time feedback mechanisms in BCI experiments. It supports both visual and auditory feedback, allowing researchers to create customized feedback paradigms for their specific needs. + +## Overview + +Feedback in BCI systems is crucial for providing users with information about their brain activity in real-time. This module implements a robust feedback system that can be easily extended and customized for different experimental paradigms. + +## Core Components + +### Base Classes + +- `Feedback`: Abstract base class that defines the interface for all feedback mechanisms + - Provides common functionality for feedback administration + - Defines abstract methods that must be implemented by subclasses + - Manages feedback type registration and logging + +### Feedback Types + +The module supports two main types of feedback: + +1. **Visual Feedback** (`VisualFeedback`) + - Displays text or image stimuli on screen + - Supports customizable positioning, timing, and appearance + - Provides precise timing control for stimulus presentation + - Features: + - Text and image stimulus support + - Configurable font, size, and color + - Position control + - Timing synchronization + +2. **Auditory Feedback** (`AuditoryFeedback`) + - Plays sound stimuli through the system's audio output + - Supports various audio formats and sampling rates + - Provides timing control for audio presentation + - Features: + - Sound playback + - Configurable audio parameters + - Timing synchronization + +## Usage Examples + +### Visual Feedback + +```python +from bcipy.feedback.visual.visual_feedback import VisualFeedback +from psychopy import visual +from bcipy.helpers.clock import Clock + +# Initialize display window +window = visual.Window(size=[800, 600]) + +# Configure parameters +parameters = { + 'feedback_font': 'Arial', + 'feedback_stim_height': 0.1, + 'feedback_pos_x': 0, + 'feedback_pos_y': 0, + 'feedback_duration': 1.0, + 'feedback_color': 'white' +} + +# Create feedback instance +clock = Clock() +feedback = VisualFeedback(window, parameters, clock) + +# Administer feedback +timing = feedback.administer("Hello World", StimuliType.TEXT) +``` + +### Auditory Feedback + +```python +from bcipy.feedback.sound.auditory_feedback import AuditoryFeedback +from psychopy import core +import numpy as np + +# Configure parameters +parameters = { + 'sound_buffer_time': 1.0 +} + +# Create feedback instance +clock = core.Clock() +feedback = AuditoryFeedback(parameters, clock) + +# Generate a simple tone +fs = 44100 # sampling frequency +t = np.linspace(0, 1, fs) # 1 second duration +sound = np.sin(2 * np.pi * 440 * t) # 440 Hz sine wave + +# Administer feedback +timing = feedback.administer(sound, fs) +``` + +## Configuration + +Both feedback types can be configured through a parameters dictionary. Common parameters include: + +- Timing parameters (duration, intervals) +- Display parameters (position, size, color) +- Stimulus-specific parameters (font, audio format) + +## Timing Control + +The feedback module provides precise timing control through: + +- Clock synchronization +- Timestamp recording +- Buffer time management + +## Extending the Module + +To create a new feedback type: + +1. Create a new class inheriting from `Feedback` +2. Implement the required abstract methods: + - `configure()` + - `administer()` +3. Register the new feedback type in `FeedbackType` enum + +## Best Practices + +1. Always use the provided timing mechanisms for synchronization +2. Handle exceptions appropriately in feedback administration +3. Clean up resources after feedback presentation +4. Use appropriate buffer times for smooth presentation +5. Test feedback timing in your specific experimental setup + +## References + +- PsychoPy documentation for visual stimulus presentation +- SoundDevice documentation for audio playback +- BciPy documentation for integration with other modules diff --git a/bcipy/feedback/demo/demo_sound_feedback.py b/bcipy/feedback/demo/demo_sound_feedback.py index c4ae5b4b3..52caeb7bb 100644 --- a/bcipy/feedback/demo/demo_sound_feedback.py +++ b/bcipy/feedback/demo/demo_sound_feedback.py @@ -4,7 +4,7 @@ from bcipy.config import DEFAULT_PARAMETERS_PATH from bcipy.feedback.sound.auditory_feedback import AuditoryFeedback from bcipy.helpers.clock import Clock -from bcipy.helpers.load import load_json_parameters +from bcipy.io.load import load_json_parameters # Load a parameters file parameters = load_json_parameters(DEFAULT_PARAMETERS_PATH, value_cast=True) diff --git a/bcipy/feedback/demo/demo_visual_feedback.py b/bcipy/feedback/demo/demo_visual_feedback.py index 625df1b39..626e29bee 100644 --- a/bcipy/feedback/demo/demo_visual_feedback.py +++ b/bcipy/feedback/demo/demo_visual_feedback.py @@ -2,7 +2,7 @@ from bcipy.display import init_display_window from bcipy.feedback.visual.visual_feedback import VisualFeedback from bcipy.helpers.clock import Clock -from bcipy.helpers.load import load_json_parameters +from bcipy.io.load import load_json_parameters # Load a parameters file parameters = load_json_parameters(DEFAULT_PARAMETERS_PATH, value_cast=True) diff --git a/bcipy/feedback/feedback.py b/bcipy/feedback/feedback.py index 8496371b8..e21795fb6 100644 --- a/bcipy/feedback/feedback.py +++ b/bcipy/feedback/feedback.py @@ -1,25 +1,98 @@ +# mypy: disable-error-code=override +"""Feedback module. + +This module provides the base feedback functionality for BciPy, including abstract +classes and utilities for creating and managing different types of feedback +mechanisms (sound, visual, etc.). +""" + import logging +from abc import ABC, abstractmethod +from enum import Enum +from typing import Any, List + from bcipy.config import SESSION_LOG_FILENAME -REGISTERED_FEEDBACK_TYPES = ['sound', 'visual'] +class FeedbackType(Enum): + """Enumeration of feedback types supported by BciPy (Visual, Audio).""" + + VIS = 'Visual' + AUD = 'Audio' + + @classmethod + def list(cls) -> List[str]: + """Return a list of all available feedback types. + + Returns: + List[str]: List of feedback type values + """ + return [feedback_type.value for feedback_type in cls] + + +class StimuliType(Enum): + """Enumeration of stimuli types supported by BciPy (Text, Image).""" + + TEXT = 'Text' + IMAGE = 'Image' -class Feedback: - """Feedback.""" + @classmethod + def list(cls) -> List[str]: + """Return a list of all available stimuli types. - def __init__(self, feedback_type): + Returns: + List[str]: List of stimuli type values + """ + return [stimuli_type.value for stimuli_type in cls] + + +class Feedback(ABC): + """Abstract base class for feedback mechanisms. + + This class defines the interface for different types of feedback in BciPy, + such as sound and visual feedback. It provides methods for configuration + and administration of feedback. + + Attributes: + feedback_type (str): Type of feedback (e.g., 'sound', 'visual'). + logger (logging.Logger): Logger instance for feedback-related events. + """ + + def __init__(self, feedback_type: FeedbackType) -> None: + """Initialize Feedback. + + Args: + feedback_type (str): Type of feedback to be administered. + """ super(Feedback, self).__init__() self.feedback_type = feedback_type self.logger = logging.getLogger(SESSION_LOG_FILENAME) - def configure(self): - raise NotImplementedError() + @abstractmethod + def administer(self, *args: Any, **kwargs: Any) -> None: + """Administer feedback. + + This method should be implemented by subclasses to deliver the actual + feedback to the user. - def administer(self, *args, **kwargs): - raise NotImplementedError() + Args: + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + """ + ... - def _type(self): + def _type(self) -> FeedbackType: + """Get the feedback type. + + Returns: + str: The type of feedback being administered. + """ return self.feedback_type - def _available_modes(self): - return REGISTERED_FEEDBACK_TYPES + def _available_modes(self) -> List[str]: + """Get available feedback modes. + + Returns: + List[str]: List of registered feedback types. + """ + return FeedbackType.list() diff --git a/bcipy/feedback/sound/auditory_feedback.py b/bcipy/feedback/sound/auditory_feedback.py index 4d3aa06d6..1d74fd404 100644 --- a/bcipy/feedback/sound/auditory_feedback.py +++ b/bcipy/feedback/sound/auditory_feedback.py @@ -1,15 +1,41 @@ -from bcipy.feedback.feedback import Feedback -from psychopy import core +# mypy: disable-error-code=override +"""Auditory feedback module. + +This module provides auditory feedback functionality for BciPy, implementing +sound-based feedback mechanisms using sounddevice for audio playback. +""" + +from typing import Any, Dict, List, Optional, Union + import sounddevice as sd +from psychopy import core + +from bcipy.feedback.feedback import Feedback, FeedbackType class AuditoryFeedback(Feedback): - """Auditory Feedback.""" + """Auditory feedback implementation. - def __init__(self, parameters, clock): + This class provides sound-based feedback functionality, allowing for + the playback of audio stimuli with precise timing control. + Attributes: + feedback_type (FeedbackType): Type of feedback (AUD). + parameters (Dict[str, Any]): Configuration parameters for feedback. + sound_buffer_time (float): Buffer time for sound playback. + feedback_timestamp_label (str): Label for feedback timing. + clock (core.Clock): Clock for timing control. + """ + + def __init__(self, parameters: Dict[str, Any], clock: core.Clock) -> None: + """Initialize Auditory Feedback. + + Args: + parameters (Dict[str, Any]): Configuration parameters for feedback. + clock (core.Clock): Clock instance for timing control. + """ # Register Feedback Type - self.feedback_type = 'Auditory Feedback' + self.feedback_type = FeedbackType.AUD super(AuditoryFeedback, self).__init__(self.feedback_type) @@ -22,7 +48,22 @@ def __init__(self, parameters, clock): # Clock self.clock = clock - def administer(self, sound, fs, assertion=None): + def administer(self, sound: Union[List[float], List[List[float]]], fs: int, + assertion: Optional[Any] = None) -> List[List[Union[str, float]]]: + """Administer auditory feedback. + + Plays the provided sound and records the timing of the feedback. + + Args: + sound (Union[List[float], List[List[float]]]): Sound data to play. + fs (int): Sampling frequency of the sound. + assertion (Optional[Any]): Optional assertion to check before playing. + Currently not used. + + Returns: + List[List[Union[str, float]]]: List containing timing information + in the format [[label, timestamp]]. + """ timing = [] if assertion: diff --git a/bcipy/feedback/tests/sound/test_sound_feedback.py b/bcipy/feedback/tests/sound/test_sound_feedback.py index 08c2ca3a5..f4a6bd2b0 100644 --- a/bcipy/feedback/tests/sound/test_sound_feedback.py +++ b/bcipy/feedback/tests/sound/test_sound_feedback.py @@ -1,11 +1,10 @@ import unittest -from mockito import mock, when, unstub +import sounddevice as sd +from mockito import mock, unstub, when from bcipy.feedback.sound.auditory_feedback import AuditoryFeedback -import sounddevice as sd - class TestSoundFeedback(unittest.TestCase): @@ -31,7 +30,7 @@ def tearDown(self): def test_feedback_type(self): feedback_type = self.auditory_feedback._type() - self.assertEqual(feedback_type, 'Auditory Feedback') + self.assertEqual(feedback_type.value, 'Audio') def test_feedback_administer_sound(self): timestamp = 100 @@ -40,7 +39,8 @@ def test_feedback_administer_sound(self): self.sound, self.fs) self.assertTrue(isinstance(resp, list)) - self.assertEqual(resp[0], [self.auditory_feedback.feedback_timestamp_label, timestamp]) + self.assertEqual( + resp[0], [self.auditory_feedback.feedback_timestamp_label, timestamp]) if __name__ == '__main__': diff --git a/bcipy/feedback/tests/visual/test_visual_feedback.py b/bcipy/feedback/tests/visual/test_visual_feedback.py index 390896ee4..bd7b1de1f 100644 --- a/bcipy/feedback/tests/visual/test_visual_feedback.py +++ b/bcipy/feedback/tests/visual/test_visual_feedback.py @@ -4,7 +4,7 @@ from mockito import (any, mock, unstub, verify, verifyNoUnwantedInteractions, verifyStubbedInvocationsAreUsed, when) -from bcipy.feedback.visual.visual_feedback import FeedbackType, VisualFeedback +from bcipy.feedback.visual.visual_feedback import StimuliType, VisualFeedback from bcipy.helpers.clock import Clock @@ -39,7 +39,7 @@ def tearDown(self): def test_feedback_type(self): feedback_type = self.visual_feedback._type() - self.assertEqual(feedback_type, 'Visual Feedback') + self.assertEqual(feedback_type.value, 'Visual') def test_construct_stimulus_image(self): image_mock = mock() @@ -52,13 +52,14 @@ def test_construct_stimulus_image(self): ori=any() ).thenReturn(image_mock) # mock the resize behavior for the image - when(self.visual_feedback)._resize_image(any(), any(), any()).thenReturn() + when(self.visual_feedback)._resize_image( + any(), any(), any()).thenReturn() response = self.visual_feedback._construct_stimulus( 'test_stim.png', (0, 0), None, - FeedbackType.IMAGE, + StimuliType.IMAGE, ) self.assertEqual(response, image_mock) @@ -78,7 +79,7 @@ def test_construct_stimulus_text(self): stimulus, (0, 0), None, - FeedbackType.TEXT, + StimuliType.TEXT, ) self.assertEqual(response, text_mock) @@ -88,7 +89,8 @@ def test_show_stimuli(self): when(stimuli_mock).draw().thenReturn(None) when(self.display).flip().thenReturn(None) - response = self.visual_feedback._show_stimuli(stimuli_mock) # TODO assertion + response = self.visual_feedback._show_stimuli( + stimuli_mock) # TODO assertion verify(stimuli_mock, times=1).draw() verify(self.display, times=1).flip() @@ -100,10 +102,12 @@ def test_administer_default(self): stimulus, self.visual_feedback.pos_stim, self.visual_feedback.color, - FeedbackType.TEXT + StimuliType.TEXT ).thenReturn(stimulus) - when(self.visual_feedback)._show_stimuli(stimulus).thenReturn(timestamp) - when(psychopy.core).wait(self.visual_feedback.feedback_length).thenReturn() + when(self.visual_feedback)._show_stimuli( + stimulus).thenReturn(timestamp) + when(psychopy.core).wait( + self.visual_feedback.feedback_length).thenReturn() response = self.visual_feedback.administer(stimulus) expected = [timestamp] self.assertEqual(response, expected) diff --git a/bcipy/feedback/visual/visual_feedback.py b/bcipy/feedback/visual/visual_feedback.py index 95e70f44e..ad27fae0c 100644 --- a/bcipy/feedback/visual/visual_feedback.py +++ b/bcipy/feedback/visual/visual_feedback.py @@ -1,26 +1,47 @@ -# mypy: disable-error-code="return-value" -from enum import Enum +# mypy: disable-error-code="override,return-value" +"""Visual feedback module. + +This module provides visual feedback functionality for BciPy, implementing +visual-based feedback mechanisms using PsychoPy for stimulus presentation. +""" +from typing import Any, Dict, List, Tuple, Union from psychopy import core, visual -from typing import Tuple, List, Union -from bcipy.feedback.feedback import Feedback +from bcipy.core.stimuli import resize_image +from bcipy.feedback.feedback import Feedback, FeedbackType, StimuliType from bcipy.helpers.clock import Clock -from bcipy.helpers.stimuli import resize_image - - -class FeedbackType(Enum): - TEXT = 'TEXT' - IMAGE = 'IMAGE' class VisualFeedback(Feedback): - """Visual Feedback.""" - - def __init__(self, display: visual.Window, parameters: dict, clock: Clock) -> None: - + """Visual feedback implementation. + + This class provides visual feedback functionality, allowing for the presentation + of text and image stimuli with precise timing control. + + Attributes: + feedback_type (FeedbackType): Type of feedback (VIS). + display (visual.Window): PsychoPy window for display. + parameters (Dict[str, Any]): Configuration parameters for feedback. + font_stim (str): Font to use for text stimuli. + height_stim (int): Height of stimuli. + pos_stim (Tuple[float, float]): Position for stimuli presentation. + feedback_length (float): Duration of feedback presentation. + color (str): Color of the feedback stimulus. + clock (Clock): Clock for timing control. + feedback_timestamp_label (str): Label for feedback timing. + """ + + def __init__(self, display: visual.Window, parameters: Dict[str, Any], clock: Clock) -> None: + """Initialize Visual Feedback. + + Args: + display (visual.Window): PsychoPy window for display. + parameters (Dict[str, Any]): Configuration parameters for feedback. + clock (Clock): Clock instance for timing control. + """ # Register Feedback Type - self.feedback_type = 'Visual Feedback' + self.feedback_type = FeedbackType.VIS super(VisualFeedback, self).__init__(self.feedback_type) @@ -47,13 +68,23 @@ def __init__(self, display: visual.Window, parameters: dict, clock: Clock) -> No def administer( self, stimulus: str, - stimuli_type=FeedbackType.TEXT) -> List[Tuple[str, float]]: - """Administer. + stimuli_type: StimuliType = StimuliType.TEXT) -> List[Tuple[str, float]]: + """Administer visual feedback. - Administer visual feedback. Timing information from parameters, - current feedback given by stimulus. - """ + Presents visual feedback stimulus and records timing information. + + Args: + stimulus (str): The stimulus to present (text or image path). + stimuli_type (StimuliType, optional): Type of stimulus to present. + Defaults to StimuliType.TEXT. + + Returns: + List[Tuple[str, float]]: List containing timing information + in the format [(label, timestamp)]. + Raises: + ValueError: If an unsupported stimulus type is provided. + """ stim = self._construct_stimulus( stimulus, self.pos_stim, @@ -61,14 +92,21 @@ def administer( stimuli_type) time = self._show_stimuli(stim) - core.wait(self.feedback_length) return [time] def _show_stimuli(self, stimulus: Union[visual.TargetStim, visual.ImageStim]) -> Tuple[str, float]: + """Show the stimulus and record timing. + + Args: + stimulus (Union[visual.TargetStim, visual.ImageStim]): The stimulus to present. + + Returns: + Tuple[str, float]: Timing information in the format (label, timestamp). + """ stimulus.draw() - time = [self.feedback_timestamp_label, self.clock.getTime()] # TODO: use callback for better precision + time = [self.feedback_timestamp_label, self.clock.getTime()] self.display.flip() return time @@ -77,6 +115,16 @@ def _resize_image( stimulus: str, display_size: Tuple[float, float], stimuli_height: int) -> Tuple[float, float]: + """Resize an image stimulus to fit the display. + + Args: + stimulus (str): Path to the image file. + display_size (Tuple[float, float]): Size of the display window. + stimuli_height (int): Desired height of the stimulus. + + Returns: + Tuple[float, float]: New size of the image (width, height). + """ return resize_image( stimulus, display_size, stimuli_height) @@ -85,8 +133,24 @@ def _construct_stimulus( stimulus: str, pos: Tuple[float, float], fill_color: str, - stimuli_type: FeedbackType) -> Union[visual.TargetStim, visual.ImageStim]: - if stimuli_type == FeedbackType.IMAGE: + stimuli_type: StimuliType) -> Union[visual.TargetStim, visual.ImageStim]: + """Construct a visual stimulus. + + Creates either a text or image stimulus based on the provided type. + + Args: + stimulus (str): The stimulus content (text or image path). + pos (Tuple[float, float]): Position for the stimulus. + fill_color (str): Color for text stimuli. + stimuli_type (StimuliType): Type of stimulus to create. + + Returns: + Union[visual.TargetStim, visual.ImageStim]: The created stimulus object. + + Raises: + ValueError: If an unsupported stimulus type is provided. + """ + if stimuli_type == StimuliType.IMAGE: image_stim = visual.ImageStim( win=self.display, image=stimulus, @@ -96,7 +160,7 @@ def _construct_stimulus( image_stim.size = self._resize_image( stimulus, self.display.size, self.height_stim) return image_stim - if stimuli_type == FeedbackType.TEXT: + if stimuli_type == StimuliType.TEXT: return visual.TextStim( win=self.display, font=self.font_stim, @@ -104,3 +168,5 @@ def _construct_stimulus( height=self.height_stim, pos=pos, color=fill_color) + raise ValueError( + f'VisualFeedback asked to create a stimulus type=[{stimuli_type}] that is not supported.') diff --git a/bcipy/gui/BCInterface.py b/bcipy/gui/BCInterface.py index bfacafad4..ca097fcd9 100644 --- a/bcipy/gui/BCInterface.py +++ b/bcipy/gui/BCInterface.py @@ -1,7 +1,14 @@ +"""BCInterface module. + +This module provides the main graphical user interface for BciPy experiments, +including task execution, parameter management, and offline analysis capabilities. +""" + import logging import subprocess import sys -from typing import List +from dataclasses import dataclass +from typing import Any, Callable, Dict, List, Optional, Tuple from bcipy.config import (BCIPY_ROOT, DEFAULT_PARAMETERS_PATH, PROTOCOL_LOG_FILENAME, STATIC_IMAGES_PATH) @@ -9,120 +16,198 @@ AlertResponse, BCIGui, app, contains_special_characters, contains_whitespaces, invalid_length) -from bcipy.helpers.load import (copy_parameters, load_experiments, - load_json_parameters, load_users) +from bcipy.io.load import (copy_parameters, load_experiments, + load_json_parameters, load_users) from bcipy.task import TaskRegistry logger = logging.getLogger(PROTOCOL_LOG_FILENAME) +@dataclass +class UIConfig: + """Configuration for UI elements. + + Attributes: + padding (int): Padding value for UI elements. + btn_height (int): Height of buttons. + btn_width (int): Width of buttons. + font (str): Font family for UI elements. + static_font_size (int): Font size for static text. + """ + padding: int = 20 + btn_height: int = 40 + btn_width: int = 100 + font: str = 'Courier New' + static_font_size: int = 16 + + +@dataclass +class UserConfig: + """Configuration for user-related settings. + + Attributes: + max_length (int): Maximum length for user IDs. + min_length (int): Minimum length for user IDs. + default_text (str): Default text for input fields. + """ + max_length: int = 25 + min_length: int = 1 + default_text: str = '...' + + class BCInterface(BCIGui): """BCI Interface. - Main interface for execution of BciPy experiments and tasks. Additionally, quick access to parameter - editing and loading, and offline analysis execution. + Main interface for execution of BciPy experiments and tasks. Provides quick access to parameter + editing and loading, and offline analysis execution. + + Attributes: + tasks (List[str]): List of available tasks from TaskRegistry. + ui_config (UIConfig): UI configuration settings. + user_config (UserConfig): User-related configuration settings. + parameter_location (str): Path to parameters file. + parameters (Dict[str, Any]): Loaded parameters. + user_input (Optional[Any]): User input field. + experiment_input (Optional[Any]): Experiment input field. + task_input (Optional[Any]): Task input field. + user (Optional[str]): Selected user. + experiment (Optional[str]): Selected experiment. + task (Optional[str]): Selected task. + users (List[str]): List of available users. + disable (bool): Flag to prevent double-clicking. + task_start_timeout (int): Timeout for task start. + button_timeout (int): Timeout for button actions. + autoclose (bool): Whether to auto-close after task completion. + alert (bool): Whether to show alerts. + user_id_validations (List[Tuple[Callable[[str], bool], str]]): User ID validation rules. """ tasks = TaskRegistry().list() + ui_config = UIConfig() + user_config = UserConfig() - default_text = '...' - padding = 20 - btn_height = 40 - btn_width = 100 - max_length = 25 - min_length = 1 - timeout = 3 - font = 'Courier New' + def __init__(self, *args: Any, **kwargs: Any) -> None: + """Initialize the BCInterface. - def __init__(self, *args, **kwargs): + Args: + *args: Positional arguments passed to BCIGui. + **kwargs: Keyword arguments passed to BCIGui. + """ super(BCInterface, self).__init__(*args, **kwargs) self.parameter_location = DEFAULT_PARAMETERS_PATH + self.parameters = load_json_parameters( + self.parameter_location, value_cast=True) - self.parameters = load_json_parameters(self.parameter_location, - value_cast=True) - - # These are set in the build_inputs and represent text inputs from the user + # Input fields self.user_input = None self.experiment_input = None self.task_input = None - # These represent the current user, experiment, and task selected in the gui + # Selected values self.user = None self.experiment = None self.task = None + self.users: List[str] = [] - # user names available in the dropdown menu - self.users = [] - - # setup a timer to prevent double clicking in gui + # UI state self.disable = False self.timer.timeout.connect(self._disable_action) - - self.task_start_timeout = self.timeout - self.button_timeout = self.timeout - + self.task_start_timeout = 3 + self.button_timeout = 3 self.autoclose = False self.alert = True - self.static_font_size = 16 - self.user_id_validations = [ - (invalid_length(min=self.min_length, max=self.max_length), - f'User ID must contain between {self.min_length} and {self.max_length} alphanumeric characters.'), + # Initialize user ID validations + self.user_id_validations = self._init_user_validations() + + # Load tasks + self.tasks = TaskRegistry().list() + if not self.tasks: + logger.warning("No tasks found in TaskRegistry") + + def _init_user_validations(self) -> List[Tuple[Callable[[str], bool], str]]: + """Initialize user ID validation rules. + + Returns: + List[Tuple[Callable[[str], bool], str]]: List of validation rules and error messages. + """ + return [ + (invalid_length(min=self.user_config.min_length, max=self.user_config.max_length), + f'User ID must contain between {self.user_config.min_length} and {self.user_config.max_length} alphanumeric characters.'), (contains_whitespaces, 'User ID cannot contain white spaces'), (contains_special_characters, 'User ID cannot contain special characters') ] def build_buttons(self) -> None: - """Build Buttons. - - Build all buttons necessary for the UI. Define their action on click using the named argument action. - """ - + """Build all buttons for the UI.""" + self._build_action_buttons() + self._build_start_button() + self._build_create_experiment_button() + + def _build_action_buttons(self) -> None: + """Build the action buttons (Load, Edit, Train).""" + # Load button self.add_button( - message='Load', position=[self.padding, 450], - size=[self.btn_width, self.btn_height], background_color='Plum', + message='Load', + position=[self.ui_config.padding, 450], + size=[self.ui_config.btn_width, self.ui_config.btn_height], + background_color='Plum', text_color='black', - font_family=self.font, + font_family=self.ui_config.font, action=self.select_parameters) + # Edit button self.add_button( - message='Edit', position=[self.padding + self.btn_width + 10, 450], - size=[self.btn_width, self.btn_height], background_color='LightCoral', + message='Edit', + position=[self.ui_config.padding + + self.ui_config.btn_width + 10, 450], + size=[self.ui_config.btn_width, self.ui_config.btn_height], + background_color='LightCoral', text_color='black', - font_family=self.font, + font_family=self.ui_config.font, action=self.edit_parameters) - btn_auc_x = self.padding + (self.btn_width * 2) + 20 + # Train button + btn_auc_x = self.ui_config.padding + \ + (self.ui_config.btn_width * 2) + 20 self.add_button( - message='Train', position=(btn_auc_x, 450), - size=(self.btn_width, self.btn_height), background_color='LightSeaGreen', + message='Train', + position=(btn_auc_x, 450), + size=(self.ui_config.btn_width, self.ui_config.btn_height), + background_color='LightSeaGreen', text_color='black', - font_family=self.font, + font_family=self.ui_config.font, action=self.offline_analysis) - btn_start_width = self.btn_width * 2 + 10 - btn_start_x = self.width - (self.padding + btn_start_width) + def _build_start_button(self) -> None: + """Build the Start Session button.""" + btn_start_width = self.ui_config.btn_width * 2 + 10 + btn_start_x = self.width - (self.ui_config.padding + btn_start_width) self.add_button( - message='Start Session', position=[btn_start_x, 440], - size=[btn_start_width, self.btn_height + 10], + message='Start Session', + position=[btn_start_x, 440], + size=[btn_start_width, self.ui_config.btn_height + 10], background_color='green', action=self.start_experiment, text_color='white', - font_family=self.font) + font_family=self.ui_config.font) + def _build_create_experiment_button(self) -> None: + """Build the Create Experiment button.""" self.add_button( message='+', - position=[self.width - self.padding - 200, 260], - size=[35, self.btn_height - 10], + position=[self.width - self.ui_config.padding - 200, 260], + size=[35, self.ui_config.btn_height - 10], background_color='green', action=self.create_experiment, text_color='white' ) def create_experiment(self) -> None: - """Create Experiment. + """Launch the experiment registry. - Launch the experiment registry which will be used to add new experiments for selection in the GUI. + Opens the experiment registry interface for adding new experiments + to the GUI selection. """ if not self.action_disabled(): subprocess.call( @@ -131,339 +216,384 @@ def create_experiment(self) -> None: self.update_experiment_list() - def update_user_list(self, refresh=True) -> None: - """Updates the user_input combo box with a list of user ids based on the - data directory configured in the current parameters.""" - # if refresh is True, then we need to clear the list and add the default text - if refresh: - self.user_input.clear() - self.user_input.addItem(BCInterface.default_text) - - # load the users from the data directory and check if they have already been added to the dropdown - users = load_users(self.parameters['data_save_loc']) - for user in users: - if user not in self.users: - self.user_input.addItem(user) - self.users.append(user) - - def update_experiment_list(self) -> None: - """Updates the experiment_input combo box with a list of experiments based on the - data directory configured in the current parameters.""" - - self.experiment_input.clear() - self.experiment_input.addItem(BCInterface.default_text) - self.experiment_input.addItems(self.load_experiments()) - - def update_task_list(self) -> None: - """Updates the task_input combo box with a list of tasks ids based on what - is available in the Task Registry""" - - self.task_input.clear() - self.task_input.addItem(BCInterface.default_text) - self.task_input.addItems(self.tasks) - def build_inputs(self) -> None: - """Build Inputs. - - Build all inputs needed for BCInterface. - """ + """Build all input fields for the interface.""" input_x = 170 input_y = 160 - self.user_input = self.add_combobox( - position=[input_x, input_y], - size=[280, 25], - items=[], - editable=True, - background_color='white', - text_color='black') + # User input + self.user_input = self._build_combobox( + position=[input_x, input_y], + editable=True) self.update_user_list() + # Experiment input input_y += 100 - self.experiment_input = self.add_combobox( + self.experiment_input = self._build_combobox( position=[input_x, input_y], - size=[280, 25], - items=[], - editable=False, - background_color='white', - text_color='black') - + editable=False) self.update_experiment_list() + # Task input input_y += 100 - self.task_input = self.add_combobox( + self.task_input = self._build_combobox( position=[input_x, input_y], + editable=False) + self.update_task_list() + + def _build_combobox(self, position: List[int], editable: bool) -> Any: + """Build a combo box with standard styling. + + Args: + position (List[int]): Position coordinates [x, y]. + editable (bool): Whether the combo box is editable. + + Returns: + Any: The created combo box. + """ + combo = self.add_combobox( + position=position, size=[280, 25], - items=[], - editable=False, + items=[self.user_config.default_text], + editable=editable, background_color='white', text_color='black') - - self.update_task_list() + return combo def build_text(self) -> None: - """Build Text. - - Build all static text needed for the UI. - Positions are relative to the height / width of the UI defined in start_app. - """ + """Build all static text elements for the interface.""" + # Title self.add_static_textbox( text='BCInterface', position=[210, 0], size=[250, 50], background_color='black', text_color='white', - font_family=self.font, + font_family=self.ui_config.font, font_size=30) + # Labels text_x = 145 - self.add_static_textbox( - text='User', - position=[text_x, 105], - size=[200, 50], - background_color='black', - text_color='white', - font_family=self.font, - font_size=self.static_font_size) - self.add_static_textbox( - text='Experiment', - position=[text_x, 205], - size=[300, 50], - background_color='black', - font_family=self.font, - text_color='white', - font_size=self.static_font_size) - self.add_static_textbox( - text='Task', - position=[text_x, 305], - size=[300, 50], - background_color='black', - text_color='white', - font_family=self.font, - font_size=self.static_font_size) + labels = [ + ('User', 105), + ('Experiment', 205), + ('Task', 305) + ] - def build_images(self) -> None: - """Build Images. + for text, y_pos in labels: + self.add_static_textbox( + text=text, + position=[text_x, y_pos], + size=[300, 50], + background_color='black', + text_color='white', + font_family=self.ui_config.font, + font_size=self.ui_config.static_font_size) - Build add images needed for the UI. In this case, the OHSU and NEU logos. - """ + def build_images(self) -> None: + """Build all image elements for the interface.""" + # OHSU logo self.add_image( - path=f'{STATIC_IMAGES_PATH}/gui/ohsu.png', position=[self.padding, 0], size=100) + path=f'{STATIC_IMAGES_PATH}/gui/ohsu.png', + position=[self.ui_config.padding, 0], + size=100) + + # NEU logo self.add_image( - path=f'{STATIC_IMAGES_PATH}/gui/neu.png', position=[self.width - self.padding - 110, 0], size=100) + path=f'{STATIC_IMAGES_PATH}/gui/neu.png', + position=[self.width - self.ui_config.padding - 110, 0], + size=100) def build_assets(self) -> None: - """Build Assets. - - Define the assets to build in the UI. - """ + """Build all UI assets.""" self.build_buttons() self.build_inputs() self.build_text() self.build_images() + def update_user_list(self, refresh: bool = True) -> None: + """Update the user input combo box with available users. + + Args: + refresh (bool): Whether to clear the list before updating. + """ + if refresh and self.user_input: + self.user_input.clear() + self.user_input.addItem(self.user_config.default_text) + + users = load_users(self.parameters['data_save_loc']) + for user in users: + if user not in self.users and self.user_input: + self.user_input.addItem(user) + self.users.append(user) + + def update_experiment_list(self) -> None: + """Update the experiment input combo box with available experiments.""" + if self.experiment_input: + self.experiment_input.clear() + self.experiment_input.addItem(self.user_config.default_text) + experiments = self.load_experiments() + if experiments: + self.experiment_input.addItems(experiments) + + def update_task_list(self) -> None: + """Update the task input combo box with available tasks.""" + if self.task_input: + self.task_input.clear() + self.task_input.addItem(self.user_config.default_text) + if self.tasks: + self.task_input.addItems(self.tasks) + def set_parameter_location(self, path: str) -> None: - """Sets the parameter_location to the given path. Reloads the parameters - and updates any GUI widgets that are populated based on these params.""" + """Set the parameter file location and update the interface. + + Args: + path (str): Path to the parameters file. + """ self.parameter_location = path - self.parameters = load_json_parameters(self.parameter_location, - value_cast=True) + self.parameters = load_json_parameters( + self.parameter_location, value_cast=True) self.update_user_list(refresh=False) def select_parameters(self) -> None: - """Select Parameters. + """Open a dialog to select the parameters configuration file.""" + response = self.get_filename_dialog( + message='Select parameters file', + file_type='JSON files (*.json)') + + if not response: + return + + self.set_parameter_location(response) + self._handle_outdated_parameters() + + def _handle_outdated_parameters(self) -> None: + """Handle outdated parameter files by prompting for updates.""" + default_parameters = load_json_parameters( + DEFAULT_PARAMETERS_PATH, value_cast=True) + if not self.parameters.add_missing_items(default_parameters): + return + + save_response = self.throw_alert_message( + title='BciPy Alert', + message='The selected parameters file is out of date. ' + 'Would you like to update it with the latest options?', + message_type=AlertMessageType.INFO, + message_response=AlertMessageResponse.OCE) + + if save_response == AlertResponse.OK.value: + self.parameters.save() - Opens a dialog to select the parameters.json configuration to use. - """ + def edit_parameters(self) -> None: + """Open the parameter editor.""" + if self.action_disabled(): + return - response = self.get_filename_dialog(message='Select parameters file', - file_type='JSON files (*.json)') - if response: - self.set_parameter_location(response) - # If outdated, prompt to merge with the current defaults - default_parameters = load_json_parameters(DEFAULT_PARAMETERS_PATH, - value_cast=True) - if self.parameters.add_missing_items(default_parameters): - save_response = self.throw_alert_message( - title='BciPy Alert', - message='The selected parameters file is out of date.' - 'Would you like to update it with the latest options?', - message_type=AlertMessageType.INFO, - message_response=AlertMessageResponse.OCE) + if self.parameter_location == DEFAULT_PARAMETERS_PATH: + if not self._handle_default_parameters(): + return - if save_response == AlertResponse.OK.value: - self.parameters.save() + self._launch_parameter_editor() - def edit_parameters(self) -> None: - """Edit Parameters. + def _handle_default_parameters(self) -> bool: + """Handle editing of default parameters. - Prompts for a parameters.json file to use. If the default parameters are selected, a copy is used. - Note that any edits to the parameters file will not be applied to this GUI until the parameters - are reloaded. + Returns: + bool: True if should continue with editing, False otherwise. """ - if not self.action_disabled(): - if self.parameter_location == DEFAULT_PARAMETERS_PATH: - # Don't allow the user to overwrite the defaults - response = self.throw_alert_message( - title='BciPy Alert', - message='The default parameters.json cannot be overridden. A copy will be used.', - message_type=AlertMessageType.INFO, - message_response=AlertMessageResponse.OCE) - - if response == AlertResponse.OK.value: - self.parameter_location = copy_parameters() - else: - return None + response = self.throw_alert_message( + title='BciPy Alert', + message='The default parameters.json cannot be overridden. A copy will be used.', + message_type=AlertMessageType.INFO, + message_response=AlertMessageResponse.OCE) + + if response == AlertResponse.OK.value: + self.parameter_location = copy_parameters() + return True + return False - output = subprocess.check_output( - f'bcipy-params -p "{self.parameter_location}"', - shell=True) - if output: - self.parameter_location = output.decode().strip() + def _launch_parameter_editor(self) -> None: + """Launch the parameter editor process.""" + output = subprocess.check_output( + f'bcipy-params -p "{self.parameter_location}"', + shell=True) + if output: + self.parameter_location = output.decode().strip() def check_input(self) -> bool: - """Check Input. + """Check if all required input fields are valid. - Checks to make sure user has input all required fields. + Returns: + bool: True if all inputs are valid, False otherwise. """ + self._update_current_selections() - # Update based on current inputs - self.user = self.user_input.currentText() - self.experiment = self.experiment_input.currentText() - self.task = self.task_input.currentText() - - # Check the set values are different than defaults try: if not self.check_user_id(): return False - if self.experiment == BCInterface.default_text and self.task == BCInterface.default_text: - self.throw_alert_message( - title='BciPy Alert', - message='Please select an Experiment or Task for execution', - message_type=AlertMessageType.INFO, - message_response=AlertMessageResponse.OTE) - return False - if self.experiment != BCInterface.default_text and self.task != BCInterface.default_text: - self.throw_alert_message( - title='BciPy Alert', - message='Please select only an Experiment or Task', - message_type=AlertMessageType.INFO, - message_response=AlertMessageResponse.OTE) + if not self._validate_experiment_task_selection(): return False + except Exception as e: + self._show_error_alert(str(e)) + return False + + return True + + def _update_current_selections(self) -> None: + """Update current selections from input fields.""" + if self.user_input: + self.user = self.user_input.currentText() + if self.experiment_input: + self.experiment = self.experiment_input.currentText() + if self.task_input: + self.task = self.task_input.currentText() + + def _validate_experiment_task_selection(self) -> bool: + """Validate experiment and task selections. + + Returns: + bool: True if selections are valid, False otherwise. + """ + if self.experiment == self.user_config.default_text and self.task == self.user_config.default_text: self.throw_alert_message( title='BciPy Alert', - message=f'Error, {e}', - message_type=AlertMessageType.CRIT, + message='Please select an Experiment or Task for execution', + message_type=AlertMessageType.INFO, message_response=AlertMessageResponse.OTE) return False + + if self.experiment != self.user_config.default_text and self.task != self.user_config.default_text: + self.throw_alert_message( + title='BciPy Alert', + message='Please select only an Experiment or Task', + message_type=AlertMessageType.INFO, + message_response=AlertMessageResponse.OTE) + return False + return True - def check_user_id(self) -> bool: - """Check User ID + def _show_error_alert(self, error_message: str) -> None: + """Show an error alert message. - User ID must meet the following requirements: + Args: + error_message (str): The error message to display. + """ + self.throw_alert_message( + title='BciPy Alert', + message=f'Error, {error_message}', + message_type=AlertMessageType.CRIT, + message_response=AlertMessageResponse.OTE) - 1. Maximum length of self.max_length alphanumeric characters - 2. Minimum length of at least self.min_length alphanumeric character - 3. No special characters - 4. No spaces + def check_user_id(self) -> bool: + """Validate the user ID against defined requirements. + + Returns: + bool: True if user ID is valid, False otherwise. """ - # Check the user id set is different than the default text - if self.user == BCInterface.default_text: + if not self.user or self.user == self.user_config.default_text: self.throw_alert_message( title='BciPy Alert', message='Please input a User ID', message_type=AlertMessageType.INFO, message_response=AlertMessageResponse.OTE) return False - # Loop over defined user validations and check for error conditions - for validator in self.user_id_validations: - (invalid, error_message) = validator - if invalid(self.user): + + for validator, error_message in self.user_id_validations: + if validator(str(self.user)): # Ensure user is treated as string self.throw_alert_message( title='BciPy Alert', message=error_message, message_type=AlertMessageType.INFO, - message_response=AlertMessageResponse.OTE - ) + message_response=AlertMessageResponse.OTE) return False + return True def load_experiments(self) -> List[str]: - """Load experiments + """Load available experiments from the default experiment path. - Loads experiments registered in the DEFAULT_EXPERIMENT_PATH. + Returns: + List[str]: List of experiment names. """ return load_experiments().keys() def start_experiment(self) -> None: - """Start Experiment Session. + """Start an experiment session.""" + if not (self.check_input() and not self.action_disabled()): + return + + self._show_starting_alert() + cmd = self._build_experiment_command() + self._execute_experiment(cmd) + + def _show_starting_alert(self) -> None: + """Show the task starting alert.""" + self.throw_alert_message( + title='BciPy Alert', + message='Task Starting ...', + message_type=AlertMessageType.INFO, + message_response=AlertMessageResponse.OTE, + message_timeout=self.task_start_timeout) + + def _build_experiment_command(self) -> str: + """Build the experiment command. + + Returns: + str: The command to execute. + """ + if self.task != self.user_config.default_text: + cmd = f'bcipy -u "{self.user}" -t "{self.task}" -p "{self.parameter_location}"' + else: + cmd = f'bcipy -u "{self.user}" -e "{self.experiment}" -p "{self.parameter_location}"' + + if self.alert: + cmd += ' -a' + + return cmd + + def _execute_experiment(self, cmd: str) -> None: + """Execute the experiment command. - Using the inputs gathers, check for validity using the check_input method, then launch the experiment using a - command to bcipy main and subprocess. + Args: + cmd (str): The command to execute. """ - if self.check_input() and not self.action_disabled(): + output = subprocess.run(cmd, shell=True) + if output.returncode != 0: self.throw_alert_message( title='BciPy Alert', - message='Task Starting ...', - message_type=AlertMessageType.INFO, - message_response=AlertMessageResponse.OTE, - message_timeout=self.task_start_timeout) - if self.task != BCInterface.default_text: - cmd = ( - f'bcipy ' - f'-u "{self.user}" -t "{self.task}" -p "{self.parameter_location}"' - ) - else: - cmd = ( - f'bcipy ' - f'-u "{self.user}" -e "{self.experiment}" -p "{self.parameter_location}"' - ) - if self.alert: - cmd += ' -a' - output = subprocess.run(cmd, shell=True) - if output.returncode != 0: - self.throw_alert_message( - title='BciPy Alert', - message=f'Error: {output.stderr.decode()}', - message_type=AlertMessageType.CRIT, - message_response=AlertMessageResponse.OTE) + message=f'Error: {output.stderr.decode()}', + message_type=AlertMessageType.CRIT, + message_response=AlertMessageResponse.OTE) - if self.autoclose: - self.close() + if self.autoclose: + self.close() def offline_analysis(self) -> None: - """Offline Analysis. - - Run offline analysis as a script in a new process. - """ + """Run offline analysis in a new process.""" if not self.action_disabled(): cmd = f'bcipy-train --alert --p "{self.parameter_location}" -v -s' subprocess.Popen(cmd, shell=True) def action_disabled(self) -> bool: - """Action Disabled. - - Method to check whether another action can take place. If not disabled, it will allow the action and - start a timer that will disable actions until self.timeout (seconds) has occured. + """Check if actions are currently disabled. - Note: the timer is registed with the private method self._disable_action, which when self.timeout has - been reached, resets self.disable and corresponding timeouts. + Returns: + bool: True if actions are disabled, False otherwise. """ if self.disable: return True - else: - self.disable = True - # set the update time to every 500ms - self.timer.start(500) - return False + + self.disable = True + self.timer.start(500) + return False def _disable_action(self) -> bool: - """Disable Action. + """Handle action disabling timer. - A private method to register with a BCIGui.timer after setting self.button_timeout. + Returns: + bool: Current disabled state. """ if self.button_timeout > 0: self.disable = True @@ -472,12 +602,12 @@ def _disable_action(self) -> bool: self.timer.stop() self.disable = False - self.button_timeout = self.timeout + self.button_timeout = 3 return self.disable def start_app() -> None: - """Start BCIGui.""" + """Start the BCI interface application.""" bcipy_gui = app(sys.argv) ex = BCInterface( title='Brain Computer Interface', diff --git a/bcipy/gui/README.md b/bcipy/gui/README.md index bb05a1b32..063e79aff 100644 --- a/bcipy/gui/README.md +++ b/bcipy/gui/README.md @@ -1,33 +1,169 @@ -# RSVP Keyboard GUI -====================================== +# BciPy GUI Module -This module contains all GUI code used in BciPy. The base window class, BCIGui, is contained in gui_main.py, and contains methods for easily adding widgets to a given window. BCInterface.py launches the main GUI window. There are also interfaces for collecting and editing data (parameters and field data for experiments.) +The GUI module provides the graphical user interface components for BciPy, enabling users to interact with the BCI system through a user-friendly interface. This module is essential for running experiments, managing parameters, and controlling the BCI workflow. -## Dependencies -------------- -This project was written in wxPython version 4.0.4 and PyQt5 5.15.1. We are deprecating the wxPython UIs in future releases. +## Overview -## Project structure ---------------- -Name | Description -------------- | ------------- -BCInterface.py | Defines main GUI window. Selection of user, experiment and task. -gui_main.py | BCIGui containing methods for adding buttons, images, etc. to GUI window -parameters/params_form.py | Defines window for setting BCInterface parameters -experiments/ExperimentRegistry.py | GUI for creating new experiments to select in BCInterface. -experiments/FieldRegistry.py | GUI for creating new fields for experiment data collection. -experiments/ExperimentField.py | GUI for collecting a registered experiment's field data. +The GUI module consists of several key components: +1. **Main Interface (`BCInterface.py`)** + - Primary interface for running BCI experiments + - User management and experiment selection + - Parameter configuration and task execution + - Offline analysis capabilities -The folder 'bcipy/static/images/gui' contains images for the GUI. -Parameters loaded by BCInterface parameter definition form can be found in 'bcipy/parameters/parameters.json'. +2. **Base UI Components (`bciui.py`)** + - Core UI building blocks and utilities + - Common functionality for all BciPy interfaces + - Layout management and styling + - Dynamic list and item management -To run the GUI, do so from the root, as follows: +3. **Experiment Management** + - `ExperimentRegistry.py`: Interface for registering and managing experiments + - `ExperimentField.py`: Form for collecting experiment-specific data + - Field management and validation -`python bcipy/gui/BCInterface.py` +4. **Alert System (`alert.py`)** + - User notifications and confirmations + - Error handling and system messages -Contributors: +5. **Task Transitions (`intertask_gui.py`)** + - Progress tracking between tasks + - Experiment flow control + - User feedback during transitions -- Tab Memmott -- Matthew Lawhead -- Dani Smektala +## Getting Started + +### Running the GUI + +To start the BciPy GUI: + +```bash +python bcipy/gui/BCInterface.py +``` + +Or using Make (if installed): + +```bash +make bci-gui +``` + +### Basic Usage + +1. **User Management** + - Enter or select a user ID + - User IDs must be alphanumeric and meet length requirements + +2. **Experiment Selection** + - Choose between running a specific task or a complete experiment + - Tasks are individual BCI operations (e.g., calibration) + - Experiments are predefined sequences of tasks + +3. **Parameter Configuration** + - Load existing parameter files + - Edit parameters through the parameter editor + - Save custom configurations + +4. **Task Execution** + - Start sessions with selected configurations + - Monitor progress through the intertask interface + - View results and system feedback + +5. **Signal Viewer** + - Monitor real-time EEG signals during experiments + - View and analyze recorded data from previous sessions + - Toggle channel visibility and apply montages + - Control display duration and filtering options + - Pause/resume signal visualization + - Support for multiple monitor configurations + - See [Signal Viewer Documentation](gui/viewer/README.md) for more details + +## Key Features + +### Experiment Registry + +- Create and manage experiment protocols +- Define task sequences and parameters +- Configure experiment-specific fields +- Save and load experiment configurations + +### Parameter Management + +- Load default or custom parameter files +- Edit parameters through a user-friendly interface +- Save parameter configurations +- Validate parameter settings + +### Task Control + +- Start and stop BCI tasks +- Monitor task progress +- Handle transitions between tasks +- Manage experiment flow + +### User Interface + +- Clean, intuitive design +- Consistent styling across components +- Responsive feedback +- Error handling and notifications + +## Development + +### Adding New Components + +When extending the GUI: + +1. Inherit from `BCIUI` for new interfaces +2. Use the provided UI utilities and components +3. Follow the established styling guidelines +4. Implement proper error handling +5. Add appropriate documentation + +### Styling + +The GUI uses a consistent styling system: + +- CSS-based styling through `bcipy_stylesheet.css` +- Common UI elements and layouts +- Responsive design principles +- Accessibility considerations + +## Best Practices + +1. **Error Handling** + - Use the alert system for user notifications + - Validate inputs before processing + - Provide clear error messages + - Handle edge cases gracefully + +2. **User Experience** + - Maintain consistent interface behavior + - Provide clear feedback for actions + - Use appropriate timeouts and delays + - Implement proper state management + +3. **Performance** + - Minimize UI blocking operations + - Use appropriate threading for long operations + - Optimize resource usage + - Handle cleanup properly + +## Troubleshooting + +Common issues and solutions: + +1. **GUI Not Starting** + - Check Python and dependency versions + - Verify file permissions + - Check for conflicting processes + +2. **Parameter Issues** + - Validate parameter file format + - Check file paths and permissions + - Verify parameter values + +3. **Task Execution Problems** + - Check system requirements + - Verify device connections + - Review error logs diff --git a/bcipy/gui/alert.py b/bcipy/gui/alert.py index 91fec4c9e..23e1b8837 100644 --- a/bcipy/gui/alert.py +++ b/bcipy/gui/alert.py @@ -1,19 +1,36 @@ -"""GUI alert messages""" +"""GUI alert messages module. + +This module provides functionality for displaying alert messages and confirmation dialogs +in the BciPy GUI interface. It includes functions for user interaction through +standard dialog boxes with customizable options. +""" + # pylint: disable=no-name-in-module import sys +from typing import Optional + from PyQt6.QtWidgets import QApplication -from bcipy.gui.main import alert_message, AlertMessageType, AlertResponse, AlertMessageResponse + +from bcipy.gui.main import (AlertMessageResponse, AlertMessageType, + AlertResponse, alert_message) def confirm(message: str) -> bool: """Confirmation dialog which allows the user to select between a true and false. - Parameters - ---------- - message - alert to display - Returns - ------- - users selection : True for selecting Ok, False for Cancel. + This function displays a dialog box with OK and Cancel buttons, allowing the user + to confirm or cancel an action. The dialog is displayed using the system's native + dialog style. + + Args: + message (str): The alert message to display in the dialog box. + + Returns: + bool: True if the user clicked OK, False if the user clicked Cancel. + + Note: + This function creates a new QApplication instance if one doesn't exist, + and quits it after the dialog is closed. """ app = QApplication(sys.argv).instance() if not app: diff --git a/bcipy/gui/bciui.py b/bcipy/gui/bciui.py index b3c301832..c13fca87d 100644 --- a/bcipy/gui/bciui.py +++ b/bcipy/gui/bciui.py @@ -1,45 +1,71 @@ -from typing import Callable, Type +"""BCIUI module. + +This module provides the base UI components and utilities for building BciPy's +graphical user interfaces. It includes base classes for UI elements, dynamic +lists, and utility functions for common UI operations. +""" + +import sys +from typing import Any, Callable, Dict, List, Optional, Type + from PyQt6.QtCore import pyqtSignal -from PyQt6.QtWidgets import ( - QWidget, - QVBoxLayout, - QHBoxLayout, - QPushButton, - QScrollArea, - QLayout, - QSizePolicy, - QMessageBox, - QApplication, -) -from typing import Optional, List +from PyQt6.QtWidgets import (QApplication, QHBoxLayout, QLayout, QMessageBox, + QPushButton, QScrollArea, QSizePolicy, + QVBoxLayout, QWidget) + from bcipy.config import BCIPY_ROOT -import sys class BCIUI(QWidget): + """Base class for BciPy user interfaces. + + This class provides common functionality for all BciPy UI components, + including layout management, styling, and utility methods. + + Attributes: + contents (QVBoxLayout): Main vertical layout container. + center_content_vertically (bool): Whether to center content vertically. + """ + contents: QVBoxLayout center_content_vertically: bool = False def __init__(self, title: str = "BCIUI", default_width: int = 500, default_height: int = 600) -> None: + """Initialize the BCIUI base class. + + Args: + title (str): Window title. Defaults to "BCIUI". + default_width (int): Default window width. Defaults to 500. + default_height (int): Default window height. Defaults to 600. + """ super().__init__() self.resize(default_width, default_height) self.setWindowTitle(title) self.contents = QVBoxLayout() self.setLayout(self.contents) - def app(self): + def app(self) -> None: + """Initialize the application UI. + + This method should be overridden by subclasses to set up their specific UI elements. + """ ... def apply_stylesheet(self) -> None: + """Apply the BciPy stylesheet to the UI. + + Loads and applies the CSS stylesheet from the BciPy configuration. + """ stylesheet_path = f'{BCIPY_ROOT}/gui/bcipy_stylesheet.css' # TODO: move to config with open(stylesheet_path, "r") as f: stylesheet = f.read() self.setStyleSheet(stylesheet) def display(self) -> None: - # Push contents to the top of the window - """ - Display the UI window and apply the stylesheet. + """Display the UI window and apply the stylesheet. + + Initializes the UI, applies vertical centering if configured, + and shows the window. """ self.app() if not self.center_content_vertically: @@ -48,12 +74,13 @@ def display(self) -> None: self.show() def show_alert(self, alert_text: str) -> int: - """ - Shows an alert dialog with the specified text. + """Show an alert dialog with the specified text. + + Args: + alert_text (str): Text to display in the alert dialog. - PARAMETERS - ---------- - :param: alert_text: string text to display in the alert dialog. + Returns: + int: The result code from the message box. """ msg = QMessageBox() msg.setText(alert_text) @@ -62,6 +89,14 @@ def show_alert(self, alert_text: str) -> int: @staticmethod def centered(widget: QWidget) -> QHBoxLayout: + """Create a centered horizontal layout for a widget. + + Args: + widget (QWidget): Widget to center. + + Returns: + QHBoxLayout: Layout with the widget centered horizontally. + """ layout = QHBoxLayout() layout.addStretch() layout.addWidget(widget) @@ -70,6 +105,14 @@ def centered(widget: QWidget) -> QHBoxLayout: @staticmethod def make_list_scroll_area(widget: QWidget) -> QScrollArea: + """Create a scrollable area for a widget. + + Args: + widget (QWidget): Widget to make scrollable. + + Returns: + QScrollArea: Scrollable area containing the widget. + """ scroll_area = QScrollArea() scroll_area.setWidget(widget) scroll_area.setWidgetResizable(True) @@ -79,28 +122,25 @@ def make_list_scroll_area(widget: QWidget) -> QScrollArea: def make_toggle( on_button: QPushButton, off_button: QPushButton, - on_action: Optional[Callable] = lambda: None, - off_action: Optional[Callable] = lambda: None, + on_action: Callable = lambda: None, + off_action: Callable = lambda: None, ) -> None: - """ - Connects two buttons to toggle between eachother and call passed methods - - PARAMETERS - ---------- - :param: on_button: QPushButton to toggle on - :param: off_button: QPushButton to toggle off - :param: on_action: function to call when on_button is clicked - :param: off_action: function to call when off_button is clicked + """Connect two buttons to toggle between each other and call passed methods. + Args: + on_button (QPushButton): Button to toggle on. + off_button (QPushButton): Button to toggle off. + on_action Callable: Function to call when on_button is clicked. + off_action Callable: Function to call when off_button is clicked. """ off_button.hide() - def toggle_off(): + def toggle_off() -> None: on_button.hide() off_button.show() off_action() - def toggle_on(): + def toggle_on() -> None: on_button.show() off_button.hide() on_action() @@ -109,127 +149,176 @@ def toggle_on(): off_button.clicked.connect(toggle_on) def hide(self) -> None: - """Close the UI window""" + """Hide the UI window.""" self.hide() class SmallButton(QPushButton): - """A small button with a fixed size""" + """A small button with a fixed size. + + This button is styled with a specific CSS class and fixed size policy. + """ + + def __init__(self, *args: Any, **kwargs: Any) -> None: + """Initialize the small button. - def __init__(self, *args, **kwargs): + Args: + *args: Positional arguments passed to QPushButton. + **kwargs: Keyword arguments passed to QPushButton. + """ super().__init__(*args, **kwargs) self.setProperty("class", "small-button") self.setSizePolicy(QSizePolicy.Policy.Fixed, QSizePolicy.Policy.Fixed) class DynamicItem(QWidget): - """A widget that can be dynamically added and removed from the ui""" + """A widget that can be dynamically added and removed from the UI. + + This widget emits a signal when removed and can store arbitrary data. + + Attributes: + on_remove (pyqtSignal): Signal emitted when the item is removed. + data (Dict[str, Any]): Dictionary for storing arbitrary data. + """ on_remove: pyqtSignal = pyqtSignal() - data: dict = {} + data: Dict[str, Any] = {} def remove(self) -> None: - """Remove the widget from it's parent DynamicList, removing it from the UI and deleting it""" + """Remove the widget from its parent DynamicList. + + Emits the on_remove signal and triggers widget deletion. + """ self.on_remove.emit() class DynamicList(QWidget): - """A list of QWidgets that can be dynamically updated""" + """A list of QWidgets that can be dynamically updated. + + This widget manages a list of DynamicItems that can be added, removed, + and reordered. + + Attributes: + widgets (List[QWidget]): List of managed widgets. + """ widgets: List[QWidget] - def __init__(self, layout: Optional[QLayout] = None): + def __init__(self, layout: Optional[QLayout] = None) -> None: + """Initialize the dynamic list. + + Args: + layout (Optional[QLayout]): Layout to use. Defaults to QVBoxLayout. + """ super().__init__() if layout is None: layout = QVBoxLayout() self.setLayout(layout) self.widgets = [] - def __len__(self): + def __len__(self) -> int: + """Get the number of widgets in the list. + + Returns: + int: Number of widgets. + """ return len(self.widgets) def add_item(self, item: DynamicItem) -> None: - """ - Add a DynamicItem to the list. + """Add a DynamicItem to the list. - PARAMETERS - ---------- - :param: item: DynamicItem to add to the list. + Args: + item (DynamicItem): Item to add to the list. """ self.widgets.append(item) item.on_remove.connect(lambda: self.remove_item(item)) - self.layout().addWidget(item) + layout = self.layout() + if layout: + layout.addWidget(item) def move_item(self, item: DynamicItem, new_index: int) -> None: - """ - Move a DynamicItem to a new index in the list. + """Move a DynamicItem to a new index in the list. + + Args: + item (DynamicItem): Item to move. + new_index (int): New index for the item. - PARAMETERS - ---------- - :param: item: A reference to the DynamicItem in the list to be moved. - :param: new_index: int new index to move the item to. + Raises: + IndexError: If new_index is out of range. """ if new_index < 0 or new_index >= len(self): raise IndexError(f"Index out of range for length {len(self)}") self.widgets.pop(self.widgets.index(item)) self.widgets.insert(new_index, item) - self.layout().removeWidget(item) - self.layout().insertWidget(new_index, item) + layout = self.layout() + if layout: + layout.removeWidget(item) + layout.insertWidget(new_index, item) def index(self, item: DynamicItem) -> int: - """ - Get the index of a DynamicItem in the list. + """Get the index of a DynamicItem in the list. - PARAMETERS - ---------- - :param: item: A reference to the DynamicItem in the list to get the index of. + Args: + item (DynamicItem): Item to find the index of. - Returns - ------- - The index of the item in the list. + Returns: + int: Index of the item in the list. """ return self.widgets.index(item) def remove_item(self, item: DynamicItem) -> None: - """ - Remove a DynamicItem from the list. + """Remove a DynamicItem from the list. - PARAMETERS - ---------- - :param: item: A reference to the DynamicItem to remove from the list + Args: + item (DynamicItem): Item to remove. """ self.widgets.remove(item) - self.layout().removeWidget(item) + layout = self.layout() + if layout: + layout.removeWidget(item) item.deleteLater() def clear(self) -> None: - """Remove all items from the list""" + """Remove all items from the list.""" for widget in self.widgets: - self.layout().removeWidget(widget) + layout = self.layout() + if layout: + layout.removeWidget(widget) widget.deleteLater() self.widgets = [] - def list(self): - return [widget.data for widget in self.widgets] + def list(self) -> List[Dict[str, Any]]: + """Get a list of data dictionaries from all items. - def list_property(self, prop: str): + Returns: + List[Dict[str, Any]]: List of data dictionaries. """ - Get a list of values for a given property of each DynamicItem's data dictionary. + return [widget.data for widget in self.widgets] - PARAMETERS - ---------- - :param: prop: string property name to get the values of. + def list_property(self, prop: str) -> List[Any]: + """Get a list of values for a given property of each DynamicItem's data dictionary. - Returns - ------- - A list of values for the given property. + Args: + prop (str): Property name to get values for. + + Returns: + List[Any]: List of values for the given property. """ return [widget.data[prop] for widget in self.widgets] -def run_bciui(ui: Type[BCIUI], *args, **kwargs): - # add app to kwargs +def run_bciui(ui: Type[BCIUI], *args: Any, **kwargs: Any) -> int: + """Run a BCIUI instance. + + Args: + ui (Type[BCIUI]): BCIUI class to instantiate. + *args: Positional arguments for the UI class. + **kwargs: Keyword arguments for the UI class. + + Returns: + int: Application exit code. + """ app = QApplication(sys.argv).instance() if not app: app = QApplication(sys.argv) diff --git a/bcipy/gui/experiments/ExperimentField.py b/bcipy/gui/experiments/ExperimentField.py index 4ec1e51a0..7cde236b0 100644 --- a/bcipy/gui/experiments/ExperimentField.py +++ b/bcipy/gui/experiments/ExperimentField.py @@ -3,36 +3,21 @@ # pylint: disable=E0611 import sys - from typing import List from PyQt6.QtCore import Qt -from PyQt6.QtWidgets import ( - QHBoxLayout, - QPushButton, - QScrollArea, - QVBoxLayout, - QWidget, -) - -from bcipy.gui.main import ( - AlertMessageType, - AlertMessageResponse, - AlertResponse, - MessageBox, - app, - BoolInput, - DirectoryInput, - FileInput, - FloatInput, - FormInput, - IntegerInput, - TextInput, -) +from PyQt6.QtWidgets import (QHBoxLayout, QPushButton, QScrollArea, + QVBoxLayout, QWidget) + from bcipy.config import EXPERIMENT_DATA_FILENAME -from bcipy.helpers.validate import validate_experiment, validate_field_data_written -from bcipy.helpers.load import load_experiments, load_fields -from bcipy.helpers.save import save_experiment_field_data +from bcipy.gui.main import (AlertMessageResponse, AlertMessageType, + AlertResponse, BoolInput, DirectoryInput, + FileInput, FloatInput, FormInput, IntegerInput, + MessageBox, TextInput, app) +from bcipy.helpers.validate import (validate_experiment, + validate_field_data_written) +from bcipy.io.load import load_experiments, load_fields +from bcipy.io.save import save_experiment_field_data class ExperimentFieldCollection(QWidget): @@ -203,7 +188,8 @@ def build_save_data(self) -> None: ) def write_save_data(self) -> None: - save_experiment_field_data(self.save_data, self.save_path, self.file_name) + save_experiment_field_data( + self.save_data, self.save_path, self.file_name) self.throw_alert_message( title="Success", message=( @@ -234,7 +220,8 @@ def throw_alert_message( if message_response is AlertMessageResponse.OTE: msg.setStandardButtons(AlertResponse.OK.value) elif message_response is AlertMessageResponse.OCE: - msg.setStandardButtons(AlertResponse.OK.value | AlertResponse.CANCEL.value) + msg.setStandardButtons( + AlertResponse.OK.value | AlertResponse.CANCEL.value) return msg.exec() @@ -276,7 +263,8 @@ def initUI(self): vbox = QVBoxLayout() self.form_panel = QScrollArea() - self.form_panel.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOn) + self.form_panel.setVerticalScrollBarPolicy( + Qt.ScrollBarPolicy.ScrollBarAlwaysOn) self.form_panel.setHorizontalScrollBarPolicy( Qt.ScrollBarPolicy.ScrollBarAlwaysOff ) @@ -332,6 +320,7 @@ def start_experiment_field_collection_gui( def start_app() -> None: """Start Experiment Field Collection.""" import argparse + from bcipy.config import DEFAULT_EXPERIMENT_ID, EXPERIMENT_DATA_FILENAME parser = argparse.ArgumentParser() @@ -363,7 +352,8 @@ def start_app() -> None: ) args = parser.parse_args() - start_experiment_field_collection_gui(args.experiment, args.path, args.filename, args.validate) + start_experiment_field_collection_gui( + args.experiment, args.path, args.filename, args.validate) sys.exit() diff --git a/bcipy/gui/experiments/ExperimentRegistry.py b/bcipy/gui/experiments/ExperimentRegistry.py index b1bd74de5..99c122f1f 100644 --- a/bcipy/gui/experiments/ExperimentRegistry.py +++ b/bcipy/gui/experiments/ExperimentRegistry.py @@ -1,28 +1,19 @@ -from typing import List, Optional -from PyQt6.QtWidgets import ( - QComboBox, - QVBoxLayout, - QHBoxLayout, - QLabel, - QLineEdit, - QPushButton, - QScrollArea, -) -from bcipy.gui.bciui import BCIUI, DynamicItem, DynamicList, SmallButton, run_bciui -from bcipy.helpers.load import load_fields, load_experiments -from bcipy.helpers.save import save_experiment_data -from bcipy.config import ( - DEFAULT_ENCODING, - DEFAULT_EXPERIMENT_PATH, - DEFAULT_FIELD_PATH, - EXPERIMENT_FILENAME, - FIELD_FILENAME, - BCIPY_ROOT, -) -from bcipy.task.registry import TaskRegistry +import json import subprocess +from typing import List, Optional + +from PyQt6.QtWidgets import (QComboBox, QHBoxLayout, QLabel, QLineEdit, + QPushButton, QScrollArea, QVBoxLayout) + +from bcipy.config import (BCIPY_ROOT, DEFAULT_ENCODING, + DEFAULT_EXPERIMENT_PATH, DEFAULT_FIELD_PATH, + EXPERIMENT_FILENAME, FIELD_FILENAME) +from bcipy.gui.bciui import (BCIUI, DynamicItem, DynamicList, SmallButton, + run_bciui) +from bcipy.io.load import load_experiments, load_fields +from bcipy.io.save import save_experiment_data from bcipy.task.orchestrator.protocol import serialize_protocol -import json +from bcipy.task.registry import TaskRegistry class ExperimentRegistry(BCIUI): @@ -210,7 +201,8 @@ def create_experiment(self): for field in fields ] task_names = self.protocol_contents.list_property("task_name") - task_objects = [self.task_registry.get(task_name) for task_name in task_names] + task_objects = [self.task_registry.get( + task_name) for task_name in task_names] protocol = serialize_protocol(task_objects) existing_experiments[experiment_name] = { @@ -273,7 +265,8 @@ def add_field(): def add_task(): self.protocol_contents.add_item( - self.make_task_entry(self.experiment_protocol_input.currentText()) + self.make_task_entry( + self.experiment_protocol_input.currentText()) ) self.experiment_protocol_input = QComboBox() @@ -314,7 +307,8 @@ def add_task(): protocol_scroll_area = QScrollArea() self.protocol_contents = DynamicList() - protocol_scroll_area = BCIUI.make_list_scroll_area(self.protocol_contents) + protocol_scroll_area = BCIUI.make_list_scroll_area( + self.protocol_contents) label = QLabel("Protocol") label.setStyleSheet("color: black;") scroll_area_layout.addWidget(protocol_scroll_area) diff --git a/bcipy/gui/experiments/FieldRegistry.py b/bcipy/gui/experiments/FieldRegistry.py index 54cb4741f..3c23a9c24 100644 --- a/bcipy/gui/experiments/FieldRegistry.py +++ b/bcipy/gui/experiments/FieldRegistry.py @@ -1,9 +1,9 @@ import sys -from bcipy.gui.main import BCIGui, app, AlertMessageType, AlertMessageResponse from bcipy.config import DEFAULT_FIELD_PATH, FIELD_FILENAME -from bcipy.helpers.load import load_fields -from bcipy.helpers.save import save_field_data +from bcipy.gui.main import AlertMessageResponse, AlertMessageType, BCIGui, app +from bcipy.io.load import load_fields +from bcipy.io.save import save_field_data class FieldRegistry(BCIGui): diff --git a/bcipy/gui/experiments/demo/demo_experiment_field_collection.py b/bcipy/gui/experiments/demo/demo_experiment_field_collection.py index 438eea056..2f29acf25 100644 --- a/bcipy/gui/experiments/demo/demo_experiment_field_collection.py +++ b/bcipy/gui/experiments/demo/demo_experiment_field_collection.py @@ -1,6 +1,5 @@ -from bcipy.helpers.session import collect_experiment_field_data from bcipy.config import DEFAULT_EXPERIMENT_ID - +from bcipy.core.session import collect_experiment_field_data experiment_name = DEFAULT_EXPERIMENT_ID # this will save the data at the location you've run the demo from! diff --git a/bcipy/gui/file_dialog.py b/bcipy/gui/file_dialog.py index 715b223b9..6e71433db 100644 --- a/bcipy/gui/file_dialog.py +++ b/bcipy/gui/file_dialog.py @@ -1,42 +1,83 @@ +"""File dialog module. + +This module provides functionality for displaying file and directory selection +dialogs in the BciPy GUI interface. It includes classes and functions for handling +file and directory selection with customizable options and filters. +""" + # pylint: disable=no-name-in-module,missing-docstring,too-few-public-methods import sys from pathlib import Path +from typing import Optional, Tuple, Union from PyQt6 import QtGui +from PyQt6.QtCore import QRect from PyQt6.QtWidgets import QApplication, QFileDialog, QWidget +from bcipy.exceptions import BciPyCoreException from bcipy.preferences import preferences -DEFAULT_FILE_TYPES = "All Files (*)" +DEFAULT_FILE_TYPES: str = "All Files (*)" class FileDialog(QWidget): - """GUI window that prompts the user to select a file.""" + """GUI window that prompts the user to select a file or directory. + + This class provides a file dialog interface for selecting files and directories + in the BciPy GUI. It supports both file and directory selection with customizable + options and filters. + + Attributes: + title (str): Window title. + window_width (int): Window width in pixels. + window_height (int): Window height in pixels. + options (QFileDialog.Option): Dialog options. + """ - def __init__(self): + def __init__(self) -> None: + """Initialize the file dialog window. + + Sets up the window properties and centers it on the screen. + """ super().__init__() self.title = 'File Dialog' - self.width = 640 - self.height = 480 + self.window_width = 640 + self.window_height = 480 # Center on screen - self.resize(self.width, self.height) - frame_geom = self.frameGeometry() - frame_geom.moveCenter(QtGui.QGuiApplication.primaryScreen().availableGeometry().center()) - self.move(frame_geom.topLeft()) + self.resize(self.window_width, self.window_height) + self._center_window() # The native dialog may prevent the selection from closing after a # directory is selected. self.options = QFileDialog.Option.DontUseNativeDialog + def _center_window(self) -> None: + """Center the window on the primary screen. + + This method calculates the center position of the primary screen and + moves the window to that position. + """ + frame_geom = self.frameGeometry() + screen = QtGui.QGuiApplication.primaryScreen() + if screen: + center_point = screen.availableGeometry().center() + frame_geom.moveCenter(center_point) + self.move(frame_geom.topLeft()) + def ask_file(self, file_types: str = DEFAULT_FILE_TYPES, directory: str = "", prompt: str = "Select File") -> str: - """Opens a file dialog window. - Returns - ------- - path or None + """Open a file selection dialog window. + + Args: + file_types (str, optional): File type filters. Defaults to DEFAULT_FILE_TYPES. + directory (str, optional): Initial directory. Defaults to "". + prompt (str, optional): Dialog prompt message. Defaults to "Select File". + + Returns: + str: Selected file path or empty string if cancelled. """ filename, _ = QFileDialog.getOpenFileName(self, caption=prompt, @@ -46,11 +87,14 @@ def ask_file(self, return filename def ask_directory(self, directory: str = "", prompt: str = "Select Directory") -> str: - """Opens a dialog window to select a directory. + """Open a directory selection dialog window. + + Args: + directory (str, optional): Initial directory. Defaults to "". + prompt (str, optional): Dialog prompt message. Defaults to "Select Directory". - Returns - ------- - path or None + Returns: + str: Selected directory path or empty string if cancelled. """ return QFileDialog.getExistingDirectory(self, prompt, @@ -61,18 +105,27 @@ def ask_directory(self, directory: str = "", prompt: str = "Select Directory") - def ask_filename( file_types: str = DEFAULT_FILE_TYPES, directory: str = "", - prompt: str = "Select File") -> str: - """Prompt for a file. - - Parameters - ---------- - - file_types : optional file type filters; Examples: 'Text files (*.txt)' - or 'Image files (*.jpg *.gif)' or '*.csv;;*.pkl' - - directory : optional directory - - Returns - ------- - path to file or None if the user cancelled the dialog. + prompt: str = "Select File", + strict: bool = False) -> Union[str, BciPyCoreException]: + """Prompt for a file using a GUI. + + This function creates a file selection dialog and handles the user's selection. + It can optionally raise an exception if no file is selected. + + Args: + file_types (str, optional): File type filters. Examples: 'Text files (*.txt)' + or 'Image files (*.jpg *.gif)' or '*.csv;;*.pkl'. Defaults to DEFAULT_FILE_TYPES. + directory (str, optional): Initial directory. Defaults to "". + prompt (str, optional): Dialog prompt message. Defaults to "Select File". + strict (bool, optional): If True, raises an exception when no file is selected. + If False, returns an empty string. Defaults to False. + + Returns: + Union[str, BciPyCoreException]: Selected file path or empty string if cancelled. + Raises BciPyCoreException if strict=True and no file is selected. + + Note: + Updates the last_directory preference if a file is selected. """ app = QApplication(sys.argv) dialog = FileDialog() @@ -83,22 +136,34 @@ def ask_filename( path = Path(filename) if filename and path.is_file(): preferences.last_directory = str(path.parent) + app.quit() + return filename + + if strict: + raise BciPyCoreException('No file selected.') + + return '' - # Alternatively, we could use `app.closeAllWindows()` - app.quit() - return filename +def ask_directory(prompt: str = "Select Directory", strict: bool = False) -> Union[str, BciPyCoreException]: + """Prompt for a directory using a GUI. + This function creates a directory selection dialog and handles the user's selection. + It can optionally raise an exception if no directory is selected. -def ask_directory(prompt: str = "Select Directory") -> str: - """Prompt for a directory. + Args: + prompt (str, optional): Dialog prompt message. Defaults to "Select Directory". + strict (bool, optional): If True, raises an exception when no directory is selected. + If False, returns an empty string. Defaults to False. - Returns - ------- - path to directory or None if the user cancelled the dialog. + Returns: + Union[str, BciPyCoreException]: Selected directory path or empty string if cancelled. + Raises BciPyCoreException if strict=True and no directory is selected. + + Note: + Updates the last_directory preference if a directory is selected. """ app = QApplication(sys.argv) - dialog = FileDialog() directory = '' if preferences.last_directory: @@ -106,8 +171,10 @@ def ask_directory(prompt: str = "Select Directory") -> str: name = dialog.ask_directory(directory, prompt=prompt) if name and Path(name).is_dir(): preferences.last_directory = name + app.quit() + return name - # Alternatively, we could use `app.closeAllWindows()` - app.quit() + if strict: + raise BciPyCoreException('No directory selected.') - return name + return '' diff --git a/bcipy/gui/intertask_gui.py b/bcipy/gui/intertask_gui.py index 87e1a8e47..845338b09 100644 --- a/bcipy/gui/intertask_gui.py +++ b/bcipy/gui/intertask_gui.py @@ -1,20 +1,36 @@ +"""Intertask GUI module. + +This module provides a graphical user interface for managing task transitions +in BciPy experiments, showing progress and allowing users to control task flow. +""" + +import logging from typing import Callable, List -from PyQt6.QtWidgets import ( - QLabel, - QHBoxLayout, - QPushButton, - QProgressBar, - QApplication -) -from bcipy.gui.bciui import BCIUI, run_bciui +from PyQt6.QtWidgets import (QApplication, QHBoxLayout, QLabel, QProgressBar, + QPushButton) + from bcipy.config import SESSION_LOG_FILENAME -import logging +from bcipy.gui.bciui import BCIUI, run_bciui logger = logging.getLogger(SESSION_LOG_FILENAME) class IntertaskGUI(BCIUI): + """GUI for managing transitions between tasks in an experiment. + + This class provides a progress interface that shows the current task progress + and allows users to proceed to the next task or stop the experiment. + + Attributes: + action_name (str): Name of the action type. + tasks (List[str]): List of task names in the experiment. + current_task_index (int): Index of the current task. + next_task_name (str): Name of the next task to be executed. + total_tasks (int): Total number of tasks in the experiment. + task_progress (int): Current progress through the tasks. + callback (Callable): Function to call when stopping tasks. + """ action_name = "IntertaskAction" @@ -22,8 +38,15 @@ def __init__( self, next_task_index: int, tasks: List[str], - exit_callback: Callable, - ): + exit_callback: Callable[[], None], + ) -> None: + """Initialize the intertask GUI. + + Args: + next_task_index (int): Index of the next task to be executed. + tasks (List[str]): List of task names in the experiment. + exit_callback (Callable[[], None]): Function to call when stopping tasks. + """ self.tasks = tasks self.current_task_index = next_task_index self.next_task_name = tasks[self.current_task_index] @@ -33,7 +56,11 @@ def __init__( super().__init__("Progress", 800, 150) self.setProperty("class", "inter-task") - def app(self): + def app(self) -> None: + """Initialize and configure the GUI application. + + Sets up the progress display, next task information, and control buttons. + """ self.contents.addLayout(BCIUI.centered(QLabel("Experiment Progress"))) progress_container = QHBoxLayout() @@ -41,7 +68,8 @@ def app(self): QLabel(f"({self.task_progress}/{self.total_tasks})") ) self.progress = QProgressBar() - self.progress.setValue(int(self.task_progress / self.total_tasks * 100)) + self.progress.setValue( + int(self.task_progress / self.total_tasks * 100)) self.progress.setTextVisible(False) progress_container.addWidget(self.progress) self.contents.addLayout(progress_container) @@ -65,22 +93,36 @@ def app(self): self.next_button.clicked.connect(self.next) self.stop_button.clicked.connect(self.stop_tasks) - def stop_tasks(self): + def stop_tasks(self) -> None: + """Stop the current task execution. + + Calls the exit callback and quits the application. + """ # This should exit Task executions - logger.info(f"Stopping Tasks... user requested. Using callback: {self.callback}") + logger.info( + f"Stopping Tasks... user requested. Using callback: {self.callback}") self.callback() self.quit() logger.info("Tasks Stopped") - def next(self): + def next(self) -> None: + """Proceed to the next task. + + Logs the next task request and quits the application. + """ logger.info(f"Next Task=[{self.next_task_name}] requested") self.quit() - def quit(self): - QApplication.instance().quit() + def quit(self) -> None: + """Quit the application.""" + instance = QApplication.instance() + if instance: + instance.quit() if __name__ == "__main__": - tasks = ["RSVP Calibration", "IntertaskAction", "Matrix Calibration", "IntertaskAction"] + tasks = ["RSVP Calibration", "IntertaskAction", + "Matrix Calibration", "IntertaskAction"] - run_bciui(IntertaskGUI, tasks=tasks, next_task_index=1, exit_callback=lambda: print("Stopping orchestrator")) + run_bciui(IntertaskGUI, tasks=tasks, next_task_index=1, + exit_callback=lambda: print("Stopping orchestrator")) diff --git a/bcipy/gui/main.py b/bcipy/gui/main.py index b6455338c..3cdcfe7b1 100644 --- a/bcipy/gui/main.py +++ b/bcipy/gui/main.py @@ -1,3 +1,9 @@ +"""Main GUI module for BciPy. + +This module provides the core GUI components and utilities for the BciPy interface, +including form inputs, alerts, and window management. +""" + # pylint: disable=E0611 import logging import os @@ -5,16 +11,17 @@ import sys from decimal import Decimal from enum import Enum -from typing import Any, Callable, List, NamedTuple, Optional, Tuple, Union +from typing import (Any, Callable, List, NamedTuple, Optional, Tuple, Union, + cast) -from PyQt6.QtCore import Qt, QTimer, pyqtSlot +from PyQt6.QtCore import QObject, Qt, QTimer, pyqtSlot from PyQt6.QtGui import QFont, QPixmap, QShowEvent, QWheelEvent from PyQt6.QtWidgets import (QApplication, QCheckBox, QComboBox, QDoubleSpinBox, QFileDialog, QHBoxLayout, QLabel, QLineEdit, QMessageBox, QPushButton, QScrollArea, QSpinBox, QVBoxLayout, QWidget) -from bcipy.helpers.parameters import parse_range +from bcipy.core.parameters import parse_range def font(size: int = 16, font_family: str = 'Helvetica') -> QFont: @@ -22,7 +29,7 @@ def font(size: int = 16, font_family: str = 'Helvetica') -> QFont: return QFont(font_family, size, weight=0) -def invalid_length(min=1, max=25) -> bool: +def invalid_length(min=1, max=25) -> Callable[[str], bool]: """Invalid Length. Returns a function, which when passed a string will assert whether a string meets min/max conditions. @@ -35,7 +42,7 @@ def contains_whitespaces(string: str) -> bool: Checks for the presence of whitespace in a string. """ - return re.match(r'^(?=.*[\s])', string) + return bool(re.match(r'^(?=.*[\s])', string)) def contains_special_characters(string: str, @@ -48,7 +55,7 @@ def contains_special_characters(string: str, return bool(disallowed_chars.search(string)) -def static_text_control(parent, +def static_text_control(parent: Optional[QWidget], label: str, color: str = 'black', size: int = 16, @@ -57,7 +64,7 @@ def static_text_control(parent, creating labels and help components.""" static_text = QLabel(parent) static_text.setWordWrap(True) - static_text.setText(label) + static_text.setText(str(label)) static_text.setStyleSheet(f'color: {color};') static_text.setFont(font(size, font_family)) return static_text @@ -90,12 +97,11 @@ class PushButton(QPushButton): Custom Button to store unique identifiers which are required for coordinating events across multiple buttons.""" - id = None + id: Optional[int] = None - def get_id(self): + def get_id(self) -> int: if not self.id: raise Exception('No ID set on PushButton') - return self.id @@ -116,7 +122,7 @@ def __init__(self, options: List[str], selected_value: str, **kwargs): self.setText(selected_value) self.setEditable(True) - def setText(self, value: str): + def setText(self, value: str) -> None: """Sets the current index to the given value. If the value is not in the list of options it will be added.""" if value not in self.options: @@ -125,7 +131,7 @@ def setText(self, value: str): self.addItems(self.options) self.setCurrentIndex(self.options.index(value)) - def text(self): + def text(self) -> str: """Gets the currentText.""" return self.currentText() @@ -136,21 +142,20 @@ class MessageBox(QMessageBox): A custom QMessageBox implementation to provide timeout functionality to QMessageBoxes. """ - def __init__(self, *args, **kwargs): - QMessageBox.__init__(self, *args, **kwargs) + def __init__(self, *args: Any, **kwargs: Any): + super().__init__(*args, **kwargs) + self.timeout = 0.0 + self.current = 0.0 - self.timeout = 0 - self.current = 0 - - def showEvent(self, event: QShowEvent) -> None: + def showEvent(self, event: Optional[QShowEvent]) -> None: """showEvent. If a timeout greater than zero is defined, set a QTimer to call self.close after the defined timeout. """ if self.timeout > 0: # timeout is in seconds (multiply by 1000 to get ms) - QTimer().singleShot(self.timeout * 1000, self.close) - super(MessageBox, self).showEvent(event) + QTimer().singleShot(int(self.timeout * 1000.0), self.close) + super().showEvent(event) def setTimeout(self, timeout: float) -> None: """setTimeout. @@ -224,11 +229,11 @@ def __init__(self, value: str, help_tip: Optional[str] = None, options: Optional[List[str]] = None, - editable: bool = True, + editable: Optional[bool] = True, help_size: int = 12, help_color: str = 'darkgray', should_display: bool = True): - super(FormInput, self).__init__() + super().__init__() self.label = label self.help_tip = help_tip @@ -245,9 +250,9 @@ def __init__(self, if not should_display: self.hide() - def eventFilter(self, source, event): + def eventFilter(self, source: Optional[QObject], event: Any) -> bool: """Event filter that suppresses the scroll wheel event.""" - if (event.type() == QWheelEvent and source is self.control): + if (isinstance(event, QWheelEvent) and source is self.control): return True return False @@ -255,7 +260,7 @@ def init_label(self) -> QWidget: """Initialize the label widget.""" return static_text_control(None, label=self.label, size=16) - def init_help(self, font_size: int, color: str) -> QWidget: + def init_help(self, font_size: int, color: str) -> Optional[QWidget]: """Initialize the help text widget.""" if self.help_tip and self.label != self.help_tip: return static_text_control(None, @@ -264,23 +269,25 @@ def init_help(self, font_size: int, color: str) -> QWidget: color=color) return None - def init_control(self, value) -> QWidget: + def init_control(self, value: Any) -> QWidget: """Initialize the form control widget. Parameter: --------- value - initial value """ # Default is a text input - return QLineEdit(value) + return QLineEdit(str(value)) - def init_editable(self, value: bool) -> QWidget: + def init_editable(self, value: Optional[bool]) -> Optional[QWidget]: "Override. Another checkbox is needed for editable" + if value is None: + return None editable_checkbox = QCheckBox("Editable") editable_checkbox.setChecked(value) editable_checkbox.setFont(font(size=12)) return editable_checkbox - def init_layout(self): + def init_layout(self) -> None: """Initialize the layout by adding the label, help, and control widgets.""" self.vbox = QVBoxLayout() if self.label_widget: @@ -294,7 +301,7 @@ def init_layout(self): self.vbox.addWidget(self.separator()) self.setLayout(self.vbox) - def separator(self): + def separator(self) -> QWidget: """Creates a separator line.""" line = QLabel() line.setFixedHeight(1) @@ -305,16 +312,20 @@ def value(self) -> str: """Returns the value associated with the form input.""" if self.control: return self.control.text() - return None + return "" def is_editable(self) -> bool: """Returns whether the input is editable.""" - return self.editable_widget.isChecked() + if self.editable_widget: + return self.editable_widget.isChecked() + return False @property def editable(self) -> bool: """Returns whether the input is editable.""" - return True if self.editable_widget.isChecked() else False + if self.editable_widget: + return self.editable_widget.isChecked() + return False def cast_value(self) -> Any: """Returns the value associated with the form input, cast to the correct type. @@ -330,20 +341,20 @@ def matches(self, term: str) -> bool: self.help_tip and text in self.help_tip.lower()) or text in self.value().lower() - def show(self): + def show(self) -> None: """Show this widget, and all child widgets.""" if self.should_display: for widget in self.widgets(): if widget: widget.setVisible(True) - def hide(self): + def hide(self) -> None: """Hide this widget, and all child widgets.""" for widget in self.widgets(): if widget: widget.setVisible(False) - def widgets(self) -> List[QWidget]: + def widgets(self) -> List[Optional[QWidget]]: """Returns a list of self and child widgets. List may contain None values.""" return [self.label_widget, self.help_tip_widget, self.control, self] @@ -358,20 +369,21 @@ class IntegerInput(FormInput): value - initial value. """ - def __init__(self, **kwargs): - super(IntegerInput, self).__init__(**kwargs) + def __init__(self, **kwargs: Any): + super().__init__(**kwargs) - def init_control(self, value): + def init_control(self, value: Any) -> QWidget: """Override FormInput to create a spinbox.""" spin_box = QSpinBox() spin_box.setMinimum(-100000) spin_box.setMaximum(100000) - spin_box.wheelEvent = lambda event: None # disable scroll wheel + # Disable scroll wheel by overriding the event handler + spin_box.wheelEvent = lambda e: None # type: ignore if value: spin_box.setValue(int(value)) return spin_box - def cast_value(self) -> str: + def cast_value(self) -> Optional[int]: """Override FormInput to return an integer value.""" if self.control: return int(self.control.text()) @@ -388,13 +400,14 @@ class FloatInputProperties(NamedTuple): step: float = 0.1 -def float_input_properties(value: str) -> FloatInputProperties: +def float_input_properties(value: float) -> FloatInputProperties: """Given a string representation of a float value, determine suitable properties for the float component used to input or update this value. """ # Determine from the component if there is a reasonable min or max constraint dec = Decimal(str(value)) _sign, _digits, exponent = dec.as_tuple() + exponent = int(exponent) if exponent > 0: return FloatInputProperties() return FloatInputProperties(decimals=abs(exponent), step=10**exponent) @@ -410,29 +423,30 @@ class FloatInput(FormInput): value - initial value. """ - def __init__(self, **kwargs): - super(FloatInput, self).__init__(**kwargs) + def __init__(self, **kwargs: Any): + super().__init__(**kwargs) - def init_control(self, value): + def init_control(self, value: Any) -> QWidget: """Override FormInput to create a spinbox.""" spin_box = QDoubleSpinBox() # Make a reasonable guess about precision and step size based on the initial value. - props = float_input_properties(value) + props = float_input_properties(float(value)) spin_box.setMinimum(props.min) spin_box.setMaximum(props.max) spin_box.setDecimals(props.decimals) spin_box.setSingleStep(props.step) spin_box.setValue(float(value)) - spin_box.wheelEvent = lambda event: None # disable scroll wheel + # Disable scroll wheel by overriding the event handler + spin_box.wheelEvent = lambda e: None # type: ignore return spin_box def cast_value(self) -> float: """Override FormInput to return as a float.""" if self.control: return float(self.control.text()) - return None + return 0.0 class BoolInput(FormInput): @@ -445,10 +459,10 @@ class BoolInput(FormInput): value - initial value. """ - def __init__(self, **kwargs): - super(BoolInput, self).__init__(**kwargs) + def __init__(self, **kwargs: Any): + super().__init__(**kwargs) - def init_control(self, value): + def init_control(self, value: Any) -> QWidget: """Override to create a checkbox.""" ctl = QCheckBox(f'Enable {self.label}') ctl.setChecked(value == 'true') @@ -466,7 +480,7 @@ class RangeInput(FormInput): from the starting value and list of recommended if provided. """ - def init_control(self, value) -> QWidget: + def init_control(self, value: Any) -> QWidget: """Initialize the form control widget. Parameter: @@ -489,14 +503,16 @@ class SelectionInput(FormInput): help_font_size - font size for the help text. help_color - color of the help text.""" - def __init__(self, **kwargs): + def __init__(self, **kwargs: Any): assert isinstance(kwargs['options'], list), f"options are required for {kwargs['label']}" - super(SelectionInput, self).__init__(**kwargs) + super().__init__(**kwargs) - def init_control(self, value) -> QWidget: + def init_control(self, value: Any) -> QWidget: """Override to create a Combobox.""" - return ComboBox(self.options, value) + if not self.options: + raise ValueError(f"options are required for {self.label}") + return ComboBox(self.options, str(value)) class TextInput(FormInput): @@ -510,8 +526,8 @@ class TextInput(FormInput): help_font_size - font size for the help text. help_color - color of the help text.""" - def __init__(self, **kwargs): - super(TextInput, self).__init__(**kwargs) + def __init__(self, **kwargs: Any): + super().__init__(**kwargs) class FileInput(FormInput): @@ -527,15 +543,15 @@ class FileInput(FormInput): help_color - color of the help text. """ - def __init__(self, **kwargs): - super(FileInput, self).__init__(**kwargs) + def __init__(self, **kwargs: Any): + super().__init__(**kwargs) - def init_control(self, value) -> QWidget: + def init_control(self, value: Any) -> QWidget: """Override to create either a selection list or text field depending on whether there are recommended values.""" if isinstance(self.options, list): - return ComboBox(self.options, value) - return QLineEdit(value) + return ComboBox(self.options, str(value)) + return QLineEdit(str(value)) def init_button(self) -> QWidget: """Creates a Button to initiate the file/directory dialog.""" @@ -575,7 +591,7 @@ def init_layout(self) -> None: self.vbox.addWidget(self.separator()) self.setLayout(self.vbox) - def widgets(self) -> List[QWidget]: + def widgets(self) -> List[Optional[QWidget]]: """Override to include button.""" return super().widgets() + [self.button] @@ -593,7 +609,7 @@ class DirectoryInput(FileInput): help_color - color of the help text. """ - def prompt_path(self): + def prompt_path(self) -> str: """Override to prompt for a directory.""" return QFileDialog.getExistingDirectory(caption='Select a path') @@ -612,7 +628,7 @@ def __init__(self, label_low: str = "Low:", label_high="High:", size=14): - super(RangeWidget, self).__init__() + super().__init__() self.low, self.high = parse_range(value) self.input_min = None @@ -658,7 +674,8 @@ def float_input(self, value: float) -> QWidget: spin_box.setDecimals(props.decimals) spin_box.setSingleStep(props.step) spin_box.setValue(value) - spin_box.wheelEvent = lambda event: None # disable scroll wheel + # Disable scroll wheel by overriding the event handler + spin_box.wheelEvent = lambda e: None # type: ignore return spin_box def int_input(self, value: int) -> QWidget: @@ -669,12 +686,13 @@ def int_input(self, value: int) -> QWidget: -100000 if self.input_min is None else self.input_min) spin_box.setMaximum( 100000 if self.input_max is None else self.input_max) - spin_box.wheelEvent = lambda event: None # disable scroll wheel + # Disable scroll wheel by overriding the event handler + spin_box.wheelEvent = lambda e: None # type: ignore if value: spin_box.setValue(value) return spin_box - def text(self): + def text(self) -> str: """Text value""" low = self.low_input.text() or self.low high = self.high_input.text() or self.high @@ -698,8 +716,8 @@ class SearchInput(QWidget): contents of the text box. """ - def __init__(self, on_search, font_size: int = 12): - super(SearchInput, self).__init__() + def __init__(self, on_search: Callable[[str], None], font_size: int = 12): + super().__init__() self.on_search = on_search @@ -735,21 +753,21 @@ class BCIGui(QWidget): def __init__(self, title: str, width: int, height: int, background_color: str): - super(BCIGui, self).__init__() + super().__init__() logging.basicConfig(level=logging.INFO, format='%(name)s - %(levelname)s - %(message)s') self.logger = logging - self.buttons = [] - self.input_text = [] - self.static_text = [] - self.images = [] - self.comboboxes = [] - self.widgets = [] + self.buttons: List[PushButton] = [] + self.input_text: List[QLineEdit] = [] + self.static_text: List[QLabel] = [] + self.images: List[QLabel] = [] + self.comboboxes: List[QComboBox] = [] + self.widgets: List[QWidget] = [] # set main window properties self.background_color = background_color - self.window = QWidget() + self._window = QWidget() self.vbox = QVBoxLayout() self.setStyleSheet(f'background-color: {self.background_color};') @@ -758,12 +776,12 @@ def __init__(self, title: str, width: int, height: int, self.title = title # determines height/width of window - self.width = width - self.height = height + self._width = width + self._height = height self.setWindowTitle(self.title) - self.setFixedWidth(self.width) - self.setFixedHeight(self.height) + self.setFixedWidth(self._width) + self.setFixedHeight(self._height) self.setLayout(self.vbox) self.create_main_window() @@ -774,9 +792,9 @@ def create_main_window(self) -> None: Construct the main window for display of assets. """ self.window_layout = QHBoxLayout() - self.window.setStyleSheet( + self._window.setStyleSheet( f'background-color: {self.background_color};') - self.window_layout.addWidget(self.window) + self.window_layout.addWidget(self._window) self.vbox.addLayout(self.window_layout) def add_widget(self, widget: QWidget) -> None: @@ -846,9 +864,11 @@ def default_button_clicked(self) -> None: The default action for buttons if none are registed. """ - sender = self.sender() - self.logger.debug(sender.text() + ' was pressed') - self.logger.debug(sender.get_id()) + sender = cast(QObject, self.sender()) + if sender: + self.logger.debug(sender.text() + ' was pressed') + if isinstance(sender, PushButton): + self.logger.debug(sender.get_id()) def add_button(self, message: str, @@ -860,7 +880,7 @@ def add_button(self, font_family: str = 'Times', action: Optional[Callable] = None) -> PushButton: """Add Button.""" - btn = PushButton(message, self.window) + btn = PushButton(message, self._window) btn.id = id btn.move(position[0], position[1]) btn.resize(size[0], size[1]) @@ -886,7 +906,7 @@ def add_combobox(self, editable=False) -> QComboBox: """Add combobox.""" - combobox = QComboBox(self.window) + combobox = QComboBox(self._window) combobox.move(position[0], position[1]) combobox.resize(size[0], size[1]) @@ -908,7 +928,7 @@ def add_combobox(self, def add_image(self, path: str, position: list, size: int) -> QLabel: """Add Image.""" if os.path.isfile(path): - labelImage = QLabel(self.window) + labelImage = QLabel(self._window) pixmap = QPixmap(path) # ensures the new label size will scale the image itself labelImage.setScaledContents(True) @@ -918,10 +938,10 @@ def add_image(self, path: str, position: list, size: int) -> QLabel: if width > height: new_width = size - new_height = size * height / width + new_height = int(size * height / width) else: new_height = size - new_width = size * width / height + new_width = int(size * width / height) labelImage.resize(new_width, new_height) labelImage.move(position[0], position[1]) @@ -941,7 +961,7 @@ def add_static_textbox(self, wrap_text=False) -> QLabel: """Add Static Text.""" - static_text = QLabel(self.window) + static_text = QLabel(self._window) static_text.setText(text) if wrap_text: static_text.setWordWrap(True) @@ -959,7 +979,7 @@ def add_static_textbox(self, def add_text_input(self, position: list, size: list) -> QLineEdit: """Add Text Input.""" - textbox = QLineEdit(self.window) + textbox = QLineEdit(self._window) textbox.move(position[0], position[1]) textbox.resize(size[0], size[1]) @@ -972,7 +992,7 @@ def throw_alert_message( message: str, message_type: AlertMessageType = AlertMessageType.INFO, message_response: AlertMessageResponse = AlertMessageResponse.OTE, - message_timeout: float = 0) -> MessageBox: + message_timeout: float = 0) -> int: """Throw Alert Message.""" msg = alert_message(message, title=title, @@ -986,7 +1006,7 @@ def get_filename_dialog(self, file_type: str = 'All Files (*)', location: str = "") -> str: """Get Filename Dialog.""" - file_name, _ = QFileDialog.getOpenFileName(self.window, message, + file_name, _ = QFileDialog.getOpenFileName(self._window, message, location, file_type) return file_name @@ -1005,8 +1025,8 @@ def __init__(self, title: Optional[str] = None): super().__init__() - self.height = height - self.width = width + self._height = height + self._width = width self.background_color = background_color self.setStyleSheet(f'background-color: {self.background_color}') @@ -1015,11 +1035,13 @@ def __init__(self, # create the scrollable are self.frame = QScrollArea() - self.frame.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOn) - self.frame.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff) + self.frame.setVerticalScrollBarPolicy( + Qt.ScrollBarPolicy.ScrollBarAlwaysOn) + self.frame.setHorizontalScrollBarPolicy( + Qt.ScrollBarPolicy.ScrollBarAlwaysOff) self.frame.setWidgetResizable(True) - self.frame.setFixedWidth(self.width) - self.setFixedHeight(self.height) + self.frame.setFixedWidth(self._width) + self.setFixedHeight(self._height) # if a widget is provided, add it to the scrollable frame if widget: @@ -1074,11 +1096,11 @@ class LineItems(QWidget): def __init__(self, items: List[dict], width: str): super().__init__() - self.width = width + self._width = int(width) self.items = items self.vbox = QVBoxLayout() - self.setFixedWidth(self.width) + self.setFixedWidth(self._width) # construct the line items as widgets added to the layout self.construct_line_items() @@ -1117,13 +1139,12 @@ def construct_line_items(self) -> None: self.vbox.addLayout(layout) -def app(args) -> QApplication: +def app(args: List[str]) -> QApplication: """Main app registry. Passes args from main and initializes the app """ - - bci_app = QApplication(args).instance() + bci_app = QApplication.instance() if not bci_app: return QApplication(args) return bci_app @@ -1133,8 +1154,8 @@ def start_app() -> None: """Start BCIGui.""" bcipy_gui = app(sys.argv) ex = BCIGui(title='BCI GUI', - height=650, - width=650, + height=500, + width=500, background_color='white') ex.show_gui() sys.exit(bcipy_gui.exec()) diff --git a/bcipy/gui/parameters/params_form.py b/bcipy/gui/parameters/params_form.py index 4c243f76f..2b227a5c4 100644 --- a/bcipy/gui/parameters/params_form.py +++ b/bcipy/gui/parameters/params_form.py @@ -11,10 +11,10 @@ QPushButton, QScrollArea, QVBoxLayout, QWidget) from bcipy.config import BCIPY_ROOT, DEFAULT_PARAMETERS_PATH +from bcipy.core.parameters import Parameters, changes_from_default from bcipy.gui.main import (BoolInput, DirectoryInput, FileInput, FloatInput, FormInput, IntegerInput, RangeInput, SearchInput, SelectionInput, TextInput, static_text_control) -from bcipy.helpers.parameters import Parameters, changes_from_default class ParamsForm(QWidget): @@ -250,8 +250,10 @@ def __init__(self, json_file: str): self.layout = QVBoxLayout() self.changes_area = QScrollArea() - self.changes_area.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOn) - self.changes_area.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff) + self.changes_area.setVerticalScrollBarPolicy( + Qt.ScrollBarPolicy.ScrollBarAlwaysOn) + self.changes_area.setHorizontalScrollBarPolicy( + Qt.ScrollBarPolicy.ScrollBarAlwaysOff) self.changes_area.setWidgetResizable(True) self.changes_area.setWidget(self.change_items) self.changes_area.setVisible(not self.collapsed) @@ -334,8 +336,10 @@ def initUI(self): vbox.addLayout(self.changes_panel) self.form_panel = QScrollArea() - self.form_panel.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOn) - self.form_panel.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff) + self.form_panel.setVerticalScrollBarPolicy( + Qt.ScrollBarPolicy.ScrollBarAlwaysOn) + self.form_panel.setHorizontalScrollBarPolicy( + Qt.ScrollBarPolicy.ScrollBarAlwaysOff) self.form_panel.setWidgetResizable(True) self.form_panel.setFixedWidth(self.size[0]) self.form_panel.setWidget(self.form) diff --git a/bcipy/gui/tests/viewer/test_gui_main.py b/bcipy/gui/tests/viewer/test_gui_main.py index c4d0ff5d1..163e02591 100644 --- a/bcipy/gui/tests/viewer/test_gui_main.py +++ b/bcipy/gui/tests/viewer/test_gui_main.py @@ -1,5 +1,6 @@ import unittest -from bcipy.gui.main import float_input_properties, FloatInputProperties + +from bcipy.gui.main import FloatInputProperties, float_input_properties class TestFloatInputProperties(unittest.TestCase): diff --git a/bcipy/gui/tests/viewer/test_ring_buffer.py b/bcipy/gui/tests/viewer/test_ring_buffer.py index 1e7364cb4..0c30f2a80 100644 --- a/bcipy/gui/tests/viewer/test_ring_buffer.py +++ b/bcipy/gui/tests/viewer/test_ring_buffer.py @@ -1,5 +1,6 @@ """Tests for the RingBuffer data structure""" import unittest + from bcipy.gui.viewer.ring_buffer import RingBuffer diff --git a/bcipy/gui/viewer/data_source/data_source.py b/bcipy/gui/viewer/data_source/data_source.py index b89ec6c2c..03eba3e3f 100644 --- a/bcipy/gui/viewer/data_source/data_source.py +++ b/bcipy/gui/viewer/data_source/data_source.py @@ -1,5 +1,5 @@ -from queue import Queue, Empty import itertools as it +from queue import Empty, Queue class DataSource: diff --git a/bcipy/gui/viewer/data_source/file_streamer.py b/bcipy/gui/viewer/data_source/file_streamer.py index ff6d33c7d..b90c177d5 100644 --- a/bcipy/gui/viewer/data_source/file_streamer.py +++ b/bcipy/gui/viewer/data_source/file_streamer.py @@ -1,9 +1,10 @@ """Streams file data for the viewer""" import logging import time + from bcipy.acquisition.util import StoppableThread from bcipy.config import SESSION_LOG_FILENAME -from bcipy.helpers.raw_data import RawDataReader +from bcipy.core.raw_data import RawDataReader log = logging.getLogger(SESSION_LOG_FILENAME) diff --git a/bcipy/gui/viewer/data_viewer.py b/bcipy/gui/viewer/data_viewer.py index 820c93866..1c96116d7 100644 --- a/bcipy/gui/viewer/data_viewer.py +++ b/bcipy/gui/viewer/data_viewer.py @@ -4,30 +4,29 @@ from queue import Queue from typing import Callable, Dict, List, Optional, Tuple -from PyQt6.QtCore import Qt, QTimer # pylint: disable=no-name-in-module -from PyQt6.QtWidgets import (QApplication, QCheckBox, QComboBox, QHBoxLayout, - QLabel, QPushButton, QSpinBox, QVBoxLayout, - QWidget) - import matplotlib import matplotlib.ticker as ticker import numpy as np -matplotlib.use('Qt5Agg') from matplotlib.backends.backend_qtagg import FigureCanvasQTAgg as FigureCanvas from matplotlib.figure import Figure - +from PyQt6.QtCore import Qt, QTimer # pylint: disable=no-name-in-module +from PyQt6.QtWidgets import (QApplication, QCheckBox, QComboBox, QHBoxLayout, + QLabel, QPushButton, QSpinBox, QVBoxLayout, + QWidget) from bcipy.acquisition.devices import DeviceSpec from bcipy.acquisition.util import StoppableProcess +from bcipy.core.parameters import DEFAULT_PARAMETERS_PATH, Parameters +from bcipy.core.raw_data import settings from bcipy.gui.main import static_text_control from bcipy.gui.viewer.data_source.data_source import QueueDataSource from bcipy.gui.viewer.data_source.file_streamer import FileStreamer from bcipy.gui.viewer.data_source.lsl_data_source import LslDataSource from bcipy.gui.viewer.ring_buffer import RingBuffer -from bcipy.helpers.parameters import DEFAULT_PARAMETERS_PATH, Parameters -from bcipy.helpers.raw_data import settings from bcipy.signal.process.transform import Downsample, get_default_transform +matplotlib.use('Qt5Agg') + def filters( sample_rate_hz: float, parameters: Parameters @@ -93,14 +92,14 @@ class FixedHeightHBox(QWidget): def __init__(self, height: int = 30): super().__init__() - self.layout = QHBoxLayout() + self.layout = QHBoxLayout() # type: ignore self.layout.setContentsMargins(0, 0, 0, 0) self.setLayout(self.layout) self.setFixedHeight(height) def addWidget(self, widget: QWidget): """Add the given widget to the layout""" - self.layout.addWidget(widget) + self.layout.addWidget(widget) # type: ignore class ChannelControls(QWidget): @@ -631,7 +630,7 @@ def file_data(path: str """ # read metadata name, freq, channels = settings(path) - queue = Queue() + queue: Queue = Queue() streamer = FileStreamer(path, queue) data_source = QueueDataSource(queue) device_spec = DeviceSpec(name=name, channels=channels, sample_rate=freq) @@ -640,7 +639,7 @@ def file_data(path: str return (data_source, device_spec, streamer) -def main(data_file: str, +def main(data_file: Optional[str], seconds: int, refresh: int, yscale: int, @@ -677,7 +676,7 @@ def main(data_file: str, display_monitor = non_primary_screens[0] monitor = display_monitor.geometry() else: - monitor = app.primaryScreen().geometry() + monitor = app.primaryScreen().geometry() # type: ignore # increase height to 90% of monitor height and preserve aspect ratio. new_height = int(monitor.height() * 0.9) diff --git a/bcipy/gui/viewer/ring_buffer.py b/bcipy/gui/viewer/ring_buffer.py index 3bb5433d4..bac5cea37 100644 --- a/bcipy/gui/viewer/ring_buffer.py +++ b/bcipy/gui/viewer/ring_buffer.py @@ -1,35 +1,71 @@ -"""Defines a RingBuffer with a fixed size; when full additional elements -overwrite the oldest items in the data structure. +"""Ring buffer implementation for efficient data storage and retrieval. + +This module defines a RingBuffer class that implements a fixed-size circular buffer. +When the buffer is full, new elements overwrite the oldest items in the data structure. Adapted from Python Cookbook by David Ascher, Alex Martelli https://www.oreilly.com/library/view/python-cookbook/0596001673/ch05s19.html """ +from typing import Any, List, Optional, TypeVar + +T = TypeVar('T') + class RingBuffer: - """Data structure with a fixed size; when full additional elements - overwrite the oldest items in the data structure. - - Parameters - ---------- - size_max - max size of the buffer - pre_allocated - whether to create all values on initialization - empty_value - if pre_allocated, empty_value is used to set the - values with no data. + """A fixed-size circular buffer implementation. + + This class implements a ring buffer (circular buffer) with a fixed maximum size. + When the buffer is full, new elements overwrite the oldest items in the data structure. + + Attributes: + empty_value (Any): Value used to represent empty slots in the buffer. + max (int): Maximum size of the buffer. + data (List[Any]): Internal storage for buffer elements. + cur (int): Current position in the buffer. + full (bool): Whether the buffer is full. + pre_allocated (bool): Whether the buffer was pre-allocated with empty values. + + Args: + size_max (int): Maximum size of the buffer. + pre_allocated (bool, optional): Whether to create all values on initialization. + Defaults to False. + empty_value (Any, optional): If pre_allocated, this value is used to set the + values with no data. Defaults to None. + + Raises: + AssertionError: If size_max is not greater than 0. """ def __init__(self, size_max: int, pre_allocated: bool = False, - empty_value=None): + empty_value: Optional[Any] = None) -> None: + """Initialize the ring buffer. + + Args: + size_max (int): Maximum size of the buffer. + pre_allocated (bool, optional): Whether to create all values on initialization. + Defaults to False. + empty_value (Any, optional): If pre_allocated, this value is used to set the + values with no data. Defaults to None. + + Raises: + AssertionError: If size_max is not greater than 0. + """ assert size_max > 0 self.empty_value = empty_value self.max = size_max - self.data = [empty_value] * size_max if pre_allocated else [] + self.data: List[Any] = [empty_value] * \ + size_max if pre_allocated else [] self.cur = 0 self.full = False self.pre_allocated = pre_allocated - def append(self, item): - """Add an element to the buffer, overwriting if full.""" + def append(self, item: Any) -> None: + """Add an element to the buffer, overwriting if full. + + Args: + item (Any): The item to add to the buffer. + """ if self.full or self.pre_allocated: # overwrite self.data[self.cur] = item @@ -39,11 +75,20 @@ def append(self, item): self.full = self.cur == self.max - 1 self.cur = (self.cur + 1) % self.max - def get(self): - """Return a list of elements from the oldest to the newest.""" + def get(self) -> List[Any]: + """Return a list of elements from the oldest to the newest. + + Returns: + List[Any]: List of elements in chronological order. + """ if self.full: return self.data[self.cur:] + self.data[:self.cur] return self.data - def is_empty(self): + def is_empty(self) -> bool: + """Check if the buffer is empty. + + Returns: + bool: True if the buffer is empty or contains only empty values. + """ return len(self.data) == 0 or self.data[0] == self.empty_value diff --git a/bcipy/helpers/README.md b/bcipy/helpers/README.md index bca1658a5..08ddcc922 100644 --- a/bcipy/helpers/README.md +++ b/bcipy/helpers/README.md @@ -6,174 +6,9 @@ Modules necessary for BciPy system operation. These range from system utilities - `acquisition`: helper methods for working with the acquisition module. Initializes EEG acquisition given parameters - `clock`: clocks that provides high resolution timestamps -- `convert`: functionality for converting the bcipy raw data output to other formats (currently, EDF) - `copy_phrase_wrapper`: basic copy phrase task duty cycle wrapper. Coordinates activities around evidence management, decision-making, generation of inquiries, etc -- `exceptions`: BciPy core internal exceptions - `language_model`: helper methods for working with the language module -- `list`: utility methods for list processing -- `load`: methods for loading most BciPy data. For loading of triggers, see triggers.py -- `parameters`: module for functionality related to system configuration via the parameters.json file -- `raw_data`: functionality for reading and writing raw signal data -- `report`: methods for generating BciPy PDF reports -- `save`: methods for saving BciPy data in supported formats. For saving of triggers, see triggers.py -- `session`: methods for managing and parsing session.json data -- `stimuli`: methods for generating stimuli and inquiries for presentation -- `symbols`: methods for working with symbols and symbol lists. Ex. Alphabet, QWERTY, etc. -- `system_utils`: utilities for extracting git version, system information and handling of logging +- `utils`: utilities for extracting git version, system information and handling of logging - `task`: common task methods and utilities, including Trial and InquiryReshaper. -- `triggers`: methods and data classes defining BciPy internal triggering - `validate`: methods for validating experiments and fields - `visualization`: method for visualizing EEG data collected in BciPy. Used in offline_analysis.py. - - -## Triggers - -Triggers consist of a label, type and a timestamp. These are what is used to align events both in real-time and after a session for further processing or model training. During operation of a BciPy task, Triggers are generated when display or other events of interest occur. These are timestamped using a monotonic clock (See helpers/clock.py). - -A new Trigger may defined as follows: -```python -from bcipy.helpers.triggers import Trigger, TriggerType - -# label can be any utf-8 compliant string -nontarget_trigger = Trigger('nontarget_label', TriggerType.NONTARGET, 1.0111) -``` - -### Trigger Types - -The supported internal trigger types are as follows: - -```python -NONTARGET = "nontarget" -TARGET = "target" -FIXATION = "fixation" -PROMPT = "prompt" -SYSTEM = "system" -OFFSET = "offset" -EVENT = "event" -PREVIEW = "preview" -``` - -### TriggerHandler - -You can use the BciPy TriggerHandler to read and write any Triggers! - -### Writing - -You will need three pieces of information to create a new handler for writing: - -1. path where trigger data should be written -2. name of the trigger file without extension -3. a defined FlushFrequency. This sets how often the handler should write the data. Incrementally (FlushFrequency.EVERY) or at session end (FlushFrequency.END). - -```python -from bcipy.helpers.triggers import TriggerHandler, FlushFrequency - -path_to_trigger_save_location = '.' -trigger_file_name = 'triggers' # BciPy will add the correct extension. Currently, .txt is used. -flush = FlushFrequency.END - -handler = TriggerHandler(path_to_trigger_save_location, trigger_file_name, flush) - -triggers = [ - Trigger('test_trigger', TriggerType.SYSTEM, 1.0111), - Trigger('target', TriggerType.TARGET, 2), - Trigger('nontarget', TriggerType.NONTARGET, 3), -] - -handler.add_triggers(triggers) -handler.close() # this will call write one final time on any triggers added since last flush -``` - - -### Loading - -To load a BciPy triggers.txt file, the TriggerHandler load method can be used. Because it is a staticmethod, the class does not need to be initialized before the load method is used. - -```python -from bcipy.helpers.triggers import TriggerHandler - -path_to_trigger_save_location = './triggers.txt' - -triggers = TriggerHandler.load(path_to_trigger_save_location) -# it will load in data like this: -# [Trigger: label=[starting_offset] type=[offset] time=[-13149613.488788936], Trigger: label=[x] type=[prompt] time=[4.96745322458446]] -``` - -Alternately, you can pass offset and exclusion as keyword arguments to modify the behavior of `TriggerHandler.load`. Offset will add time to every timestamp loaded. Use this to correct any static system offsets! The default value for offset is 0.0. Exclusions can be used to pre-filter any unwanted Triggers, such as SYSTEM. - -```python -from bcipy.helpers.triggers import TriggerHandler - -path_to_trigger_save_location = './triggers.txt' - -# exclude system triggers -triggers = TriggerHandler.load(path_to_trigger_save_location, exclusion=[TriggerType.SYSTEM]) - -# apply a 2 second offset to all timestamps loaded -triggers = TriggerHandler.load(path_to_trigger_save_location, offset=2.0) -``` - -### Trigger File Format - -Triggers as written from BciPy tasks are assumed to have the following structure, - -1. A single trigger is written per line with three columns (label type timestamp). -2. If a clock offset is present and subsequent triggers should be corrected, it may be written with the trigger type `offset`. The value of that Trigger will be added to any timestamp values written in the file. When using various clocks that don't start at zero, this can be used to align the data to similar t=0. If time should be subtracted, write a negative value as demonstrated below for both offset values. BciPy will only apply the first instance of offset, but will return all Triggers and the additional offsets may be applied as desired. In the example below, only starting_offset would be applied to all other triggers; another_offset would be returned. -3. Only a valid TriggerType may be read. - -``` -starting_offset offset -3421.2852307 -another_offset offset -2 -N prompt 3490.3607581 -+ fixation 3491.3668763 -Y nontarget 3491.8722132 -P nontarget 3492.0780858 -J nontarget 3492.2839911 -F nontarget 3492.4900032 -D nontarget 3492.6959695 -K nontarget 3492.9021379 -X nontarget 3493.1079959 -< nontarget 3493.3139829 -M nontarget 3493.5198677 -N target 3493.7257014 -X prompt 3495.4642608 -+ fixation 3496.4697921 -Z nontarget 3496.9749562 -``` - -### Multiple Devices - -When multiple devices are in use, each device should provide its own starting_offset trigger. The trigger time should be the timestamp associated with the first sample in the data for that device. - -```python -from bcipy.helpers.triggers import Trigger, TriggerType, offset_label - -# label can be any utf-8 compliant string -eeg_offset = Trigger(offset_label(device_type='EEG'), TriggerType.OFFSET, -3400.0) -eyetracker_offset = Trigger(offset_label(device_type='EYETRACKER'), TriggerType.OFFSET, -3450.0) -``` - -After adding other triggers, the resulting file will look something like: - -``` -starting_offset offset -3400.0 -starting_offset_EYETRACKER offset -3450.0 -N prompt 3490.3607581 -+ fixation 3491.3668763 -Y nontarget 3491.8722132 -... -``` - -Triggers can then be loaded with timestamps relative to a device's start. - -```python -from bcipy.helpers.triggers import trigger_decoder, TriggerType - -types, times, labels = trigger_decoder('triggers.txt', device_type='EEG') -# types == ['prompt', 'fixation', 'prompt'] -# times == [90.36075810000011, 91.36687630000006, 91.8722131999998] -# labels == ['N', '+', 'Y'] - -_, times, _ = trigger_decoder('triggers.txt', device_type='EYETRACKER') -# times == [40.36075810000011, 41.36687630000006, 41.872213199999806] -``` diff --git a/bcipy/helpers/acquisition.py b/bcipy/helpers/acquisition.py index 2e60ded8d..5851d3faf 100644 --- a/bcipy/helpers/acquisition.py +++ b/bcipy/helpers/acquisition.py @@ -14,7 +14,7 @@ from bcipy.config import BCIPY_ROOT from bcipy.config import DEFAULT_DEVICE_SPEC_FILENAME as spec_name from bcipy.config import RAW_DATA_FILENAME, SESSION_LOG_FILENAME -from bcipy.helpers.save import save_device_specs +from bcipy.io.save import save_device_specs logger = logging.getLogger(SESSION_LOG_FILENAME) @@ -66,7 +66,8 @@ def init_acquisition( device_spec = init_device(content_type, device_name, status) raw_data_name = raw_data_filename(device_spec) - client = init_lsl_client(parameters, device_spec, save_folder, raw_data_name) + client = init_lsl_client( + parameters, device_spec, save_folder, raw_data_name) manager.add_client(client) manager.start_acquisition() @@ -115,7 +116,8 @@ def init_device(content_type: str, spec = preconfigured_device(device_name, strict=True) else: discovered_spec = discover_device_spec(content_type) - configured_spec = preconfigured_device(discovered_spec.name, strict=False) + configured_spec = preconfigured_device( + discovered_spec.name, strict=False) spec = configured_spec or discovered_spec if status_override is not None: spec.status = status_override @@ -190,11 +192,13 @@ def init_lsl_client(parameters: dict, raw_data_file_name: Optional[str] = None): """Initialize a client that acquires data from LabStreamingLayer.""" - data_buffer_seconds = round(max_inquiry_duration(parameters)) - logger.info( - f"Setting an acquisition buffer for {device_spec.name} of {data_buffer_seconds} seconds" - ) - return LslAcquisitionClient(max_buffer_len=data_buffer_seconds, + max_len = 100 + if device_spec.sample_rate > 0: + max_len = round(max_inquiry_duration(parameters)) + logger.info( + f"Setting an acquisition buffer for {device_spec.name} of {max_len} seconds" + ) + return LslAcquisitionClient(max_buffer_len=max_len, device_spec=device_spec, save_directory=save_folder, raw_data_file_name=raw_data_file_name) @@ -333,7 +337,8 @@ def is_stream_type_active(stream_type: StreamType) -> bool: """Check if the provided stream type is active. A stream type's status, if provided, will be used to make the determinition. - If missing, the status of a matching pre-configured device will be used.""" + If missing, the status of a matching pre-configured device will be used. + """ content_type, device_name, status = stream_type if status: return status == DeviceStatus.ACTIVE diff --git a/bcipy/helpers/clock.py b/bcipy/helpers/clock.py index 251bb0f0e..7088c724b 100644 --- a/bcipy/helpers/clock.py +++ b/bcipy/helpers/clock.py @@ -1,6 +1,7 @@ """Functionality related to clocks to keep track of time in experiments.""" from typing import Callable + from pylsl import local_clock diff --git a/bcipy/helpers/convert.py b/bcipy/helpers/convert.py deleted file mode 100644 index 4367dc8cd..000000000 --- a/bcipy/helpers/convert.py +++ /dev/null @@ -1,593 +0,0 @@ -# mypy: disable-error-code="no-redef" -"""Functionality for converting the bcipy raw data output to other formats""" -import logging -import os -import tarfile -from pathlib import Path -from typing import Dict, List, Optional, Tuple, Union - -import mne -import numpy as np -from mne.io import RawArray -from pyedflib import FILETYPE_BDFPLUS, FILETYPE_EDFPLUS, EdfWriter -from tqdm import tqdm - -from bcipy.acquisition.devices import preconfigured_device -from bcipy.config import (DEFAULT_PARAMETERS_FILENAME, RAW_DATA_FILENAME, - TRIGGER_FILENAME, SESSION_LOG_FILENAME) -from bcipy.helpers.load import load_json_parameters, load_raw_data -from bcipy.helpers.raw_data import RawData -from bcipy.helpers.triggers import trigger_decoder, trigger_durations -from bcipy.signal.process import Composition, get_default_transform - -logger = logging.getLogger(SESSION_LOG_FILENAME) - -FILE_LENGTH_LIMIT = 150 - - -def convert_to_edf(data_dir: str, - edf_path: Optional[str] = None, - overwrite: bool = False, - write_targetness: bool = False, - use_event_durations: bool = False, - remove_pre_fixation: bool = False, - pre_filter: bool = False) -> str: - """ Converts BciPy data to the EDF+ filetype using pyEDFlib. - - See https://www.edfplus.info/ for more detailed information about the edf specification. - See https://www.teuniz.net/edfbrowser/ for a free EDF/BDF viewer. - - Parameters - ---------- - data_dir - directory which contains the data to be converted. This location must contain: - 1. a parameter file. - 2. a raw_data.csv file. - 3. a trigger.txt file. - edf_path - optional; path to write converted data; defaults to writing a file named raw_data.edf in the data_dir. - Must end in .edf. - overwrite - If True, the destination file (if it exists) will be overwritten. If False (default), an error will - be raised if the file exists. - write_targetness - If True, and targetness information is available, write that instead of the stimuli markers. - False by default. - use_event_durations - optional; if True assigns a duration to each event. - remove_pre_fixation - optional; if True removes the non-inquiry based markers from the trigger data. - pre_filter - optional; if True, apply the default filter to the data using to loaded parameters file. - - Returns - ------- - Path to new edf file - """ - if not edf_path: - edf_path = str(Path(data_dir, f'{RAW_DATA_FILENAME}.edf').resolve()) - if not edf_path.endswith('.edf'): - raise ValueError(f'edf_path=[{edf_path}] must end in .edf') - - data, channels, fs, events, annotation_channels, filt = pyedf_convert( - data_dir, - write_targetness=write_targetness, - use_event_durations=use_event_durations, - remove_pre_fixation=remove_pre_fixation, - pre_filter=pre_filter) - - return write_pyedf( - edf_path, - data, - channels, - fs, - events, - FILETYPE_EDFPLUS, - overwrite, - annotation_channels, - filt) - - -def convert_to_bdf(data_dir: str, - bdf_path: Optional[str] = None, - overwrite: bool = False, - write_targetness: bool = False, - use_event_durations: bool = False, - remove_pre_fixation: bool = False, - pre_filter: bool = False) -> Union[Path, str]: - """ Converts BciPy data to the BDF+ filetype using pyEDFlib. - - See https://www.biosemi.com/faq/file_format.htm for more detailed information about the BDF specification. - See https://www.teuniz.net/edfbrowser/ for a free EDF/BDF viewer. - - Parameters - ---------- - data_dir - directory which contains the data to be converted. This location must contain: - 1. a parameter file. - 2. a raw_data.csv file. - 3. a trigger.txt file. - bdf_path - optional; path to write converted data; defaults to writing a file named raw_data.edf in the data_dir. - Must end in .edf. - overwrite - If True, the destination file (if it exists) will be overwritten. If False (default), an error will - be raised if the file exists. - write_targetness - If True, and targetness information is available, write that instead of the stimuli markers. - False by default. - use_event_durations - optional; if True assigns a duration to each event. - remove_pre_fixation - optional; if True removes the non-inquiry based markers from the trigger data. - pre_filter - optional; if True, apply the default filter to the data using to loaded parameters file. - - Returns - ------- - Path to new bdf file - """ - if not bdf_path: - bdf_path = str(Path(data_dir, f'{RAW_DATA_FILENAME}.bdf').resolve()) - if not bdf_path.endswith('.bdf'): - raise ValueError(f'bdf_path=[{bdf_path}] must end in .bdf') - - data, channels, fs, events, annotation_channels, filt = pyedf_convert( - data_dir, - write_targetness=write_targetness, - use_event_durations=use_event_durations, - remove_pre_fixation=remove_pre_fixation, - pre_filter=pre_filter) - - return write_pyedf( - bdf_path, - data, - channels, - fs, - events, - FILETYPE_BDFPLUS, - overwrite, - annotation_channels, - filt) - - -def pyedf_convert(data_dir: str, - write_targetness: bool = False, - use_event_durations: bool = False, - remove_pre_fixation: bool = False, - pre_filter: bool = False) -> Tuple[ - np.ndarray, - List[str], - int, - List[Tuple[float, float, str]], - int, - Union[bool, str]]: - """ Converts BciPy data to formats that can be used by pyEDFlib. - - Parameters - ---------- - - data_dir - directory which contains the data to be converted. This location must contain: - 1. a parameter file. - 2. a raw_data.csv file. - 3. a trigger.txt file. - write_targetness - If True, and targetness information is available, write that instead of the stimuli markers. - False by default. - use_event_durations - optional; if True assigns a duration to each event. - remove_pre_fixation - optional; if True removes the non-inquiry based markers from the trigger data. - pre_filter - optional; if True, apply the default filter to the data using to loaded parameters file. - - Returns - ------- - data - raw data - channels - list of channel names - fs - sampling rate - events - list of events - annotation_channels - number of annotation channels - pre_filter - False if no filter was applied, - otherwise a string of the filter parameters used to filter the data - """ - - params = load_json_parameters(str(Path(data_dir, DEFAULT_PARAMETERS_FILENAME)), - value_cast=True) - data = load_raw_data(str(Path(data_dir, f'{RAW_DATA_FILENAME}.csv'))) - fs = data.sample_rate - device_spec = preconfigured_device(data.daq_type) - if pre_filter: - default_transform = get_default_transform( - sample_rate_hz=data.sample_rate, - notch_freq_hz=params.get("notch_filter_frequency"), - bandpass_low=params.get("filter_low"), - bandpass_high=params.get("filter_high"), - bandpass_order=params.get("filter_order"), - downsample_factor=params.get("down_sampling_rate"), - ) - raw_data, fs = data.by_channel(transform=default_transform) - pre_filter: str = ( - f"HP:{params.get('filter_low')} LP:{params.get('filter_high')}" - f"N:{params.get('notch_filter_frequency')} D:{params.get('down_sampling_rate')} " - f"O:{params.get('filter_order')}") - else: - raw_data, _ = data.by_channel() - durations = trigger_durations(params) if use_event_durations else {} - static_offset = device_spec.static_offset - logger.info(f'Static offset: {static_offset}') - - trigger_type, trigger_timing, trigger_label = trigger_decoder( - str(Path(data_dir, TRIGGER_FILENAME)), - remove_pre_fixation=remove_pre_fixation, - offset=static_offset) - - # validate annotation parameters given data length and trigger count, up the annotation limit byt increasing - # annotation_channels if needed - annotation_channels = validate_annotations(len(raw_data[0]) / data.sample_rate, len(trigger_type)) - - triggers = compile_triggers( - trigger_label, trigger_type, trigger_timing, write_targetness) - - events = compile_annotations(triggers, durations) - - return raw_data, data.channels, fs, events, annotation_channels, pre_filter - - -def validate_annotations(record_time: float, trigger_count: int) -> int: - """Validate Annotations. - - Using the pyedflib library, it is recommended the number of triggers (or annotations) not exceed the recording - time in seconds. This may result in an unsuccessful export. The best workaround is to increase the number of - annotation channels. This function will return the number of annotation channels needed to export the triggers - successfully. The maximum number of annotation channels is 64 and it is not advised to use more than required - due to fize size restrictions. - - See https://github.com/holgern/pyedflib/issues/34 for more information. - """ - if trigger_count > record_time: - logger.warning( - f'\n*Warning* The number of triggers [{trigger_count}] exceeds recording time [{record_time}]. ') - annotation_channels = round(trigger_count / record_time) + 1 - logger.warning(f'\nIncreasing annotation channels to {annotation_channels} to compensate.') - return annotation_channels - return 1 - - -def compile_triggers(labels: List[str], targetness: List[str], timing: List[float], - write_targetness: bool) -> List[Tuple[str, str, float]]: - """Compile Triggers. - - Compile trigger information in a way that we edf conversion can easily digest. (label, targetness, timing). - If write targetness is true, use the targetness as a label. - """ - triggers = [] - i = 0 - for label in labels: - # if targetness information available and the flag set to true, write another trigger with target information - if write_targetness: - triggers.append((targetness[i], targetness[i], timing[i])) - else: - triggers.append((label, targetness[i], timing[i])) - i += 1 - return triggers - - -def write_pyedf(output_path: str, - raw_data: np.ndarray, - ch_names: List[str], - sample_rate: float, - events: List[Tuple[float, float, str]], - file_type: str = FILETYPE_EDFPLUS, - overwrite: bool = False, - annotation_channels: int = 1, - pre_filter: Union[bool, str] = False) -> str: - """ - Converts BciPy raw_data to the EDF+ or BDF+ filetype using pyEDFlib. - - Adapted from: https://github.com/holgern/pyedflib - - Parameters - ---------- - output_path - optional path to write converted data; defaults to writing - a file named raw.edf in the raw_data_dir. - raw_data - raw data with a row for each channel - ch_names - names of the channels - sample_rate - sample frequency - events - List[Tuple(onset_in_seconds: float, duration_in_seconds: float, description: str)] - overwrite - If True, the destination file (if it exists) will be overwritten. - If False (default), an error will be raised if the file exists. - annotation_channels - number of annotation channels to use - pre_filter - optional; if provided, add string of filters applied to channel data - - Returns - ------- - Path to new edf or bdf file - """ - if not overwrite and os.path.exists(output_path): - raise OSError(f'{output_path} already exists.') - - physical_min, physical_max = [raw_data.min(), raw_data.max()] - n_channels = len(raw_data) - - try: - writer = EdfWriter(output_path, n_channels=n_channels, file_type=file_type) - - channel_info = [] - data_list = [] - - for i in range(n_channels): - ch_dict = { - 'label': ch_names[i], - 'dimension': 'uV', - 'sample_frequency': sample_rate, - 'physical_min': physical_min, - 'physical_max': physical_max, - } - - if pre_filter: - ch_dict['prefilter'] = pre_filter - - channel_info.append(ch_dict) - data_list.append(raw_data[i]) - - if events: - writer.set_number_of_annotation_signals(annotation_channels) - for onset, duration, label in events: - writer.writeAnnotation(onset, duration, label) - - writer.setSignalHeaders(channel_info) - writer.writeSamples(data_list) - - except Exception as error: - logger.info(error) - raise error - finally: - writer.close() - return output_path - - -def compile_annotations(triggers: List[Tuple[str, str, float]], - durations: Dict[str, float] = {} - ) -> List[Tuple[float, float, str]]: - """Convert bcipy triggers to the format expected by pyedflib for writing annotations. - - Parameters - ---------- - triggers - trigger data in the format (symbol, targetness, stamp), - where stamp has been converted to acquisition clock units. - durations - optional map defining the duration (seconds) of each - trigger type. The default is to assign 0.0 seconds. - Returns - ------- - List[Tuple(onset_in_seconds, duration_in_seconds, description)] - """ - return [(timestamp, durations.get(targetness, 0.0), label) - for (label, targetness, timestamp) in triggers] - - -def compress(tar_file_name: str, members: List[str]) -> None: - """ - File compression and archiving. - - Adds files to a tar archive and compresses them using the gzip compression - format. - - Parameters - ---------- - tar_file_name (str): name of resulting compressed tar archive. Input string - can either include or not include file extension (.tar.gz), as this will - be checked. - members (List[str]): list of files and folders to be compressed into archive. - Each file or folder requires the relative file path and full file extension. - Individual file paths and names that are very long may throw an error - upon extraction, proceed with caution. - - Returns - ------- - None - """ - - for member in members: - # Checks if file exists - if not os.path.exists(member): - raise FileNotFoundError(f"This file or folder, '{member}', " - "does not exist!\nPlease rerun program") - # Checks for file names that may be too long. OS level restriction. - if len(member) > FILE_LENGTH_LIMIT: - logger.warning( - f'File length exceeds compression limit=[{FILE_LENGTH_LIMIT}]. ' - 'This may cause issues later with extraction. Please proceed at your own discretion.') - - full_tar_name = tar_name_checker(tar_file_name) - # Warns user that reopening tar archive that already exists will overwrite it - if os.path.exists(full_tar_name): - raise Exception(f"This tar archive=[{full_tar_name}] already exists, continuing will " - "overwrite anything in the existing archive.") - - # Opens file for gzip (gz) compressed writing (w) - # Uses default compression level 9 (highest compression, slowest speed) - with tarfile.open(full_tar_name, mode="w:gz") as tar: - # Sets progress bar through tqdm - progress = tqdm(members) - for member in progress: - # Adds file/folder to the tar file and compresses it - tar.add(member) - # Sets progress description of progress bar - progress.set_description(f"Compressing {member}") - - -def decompress(tar_file: str, path: str) -> None: - """ - Archive decompression and extraction. - - Takes .tar.gz archive, decompresses, and extracts its contents. Should only be - used with files created by compress() method. - - Parameters - ---------- - tar_file (str): name of .tar.gz archive to be decompressed. Input string - can either include or not include file extension (.tar.gz), as this will - be checked. - path (str): file path and name of folder for the extracted contents of the - archive. If only a name is entered, by default it will place the folder - in the current working directory. (ex. "extracted" creates a new folder - in the current directory and extracts the archive contents to it) - - Returns - ------- - None - """ - - full_tar_name = tar_name_checker(tar_file) - - # Checks if file exists - if not os.path.exists(full_tar_name): - raise FileNotFoundError(f"This file or folder, '{tar_file}', " - "does not exist!\nPlease rerun program") - - # Opens file for gzip (gz) compressed reading (r) - with tarfile.open(full_tar_name, mode="r:gz") as tar: - members = tar.getmembers() - - # Sets progress bar through tqdm - progress = tqdm(members) - for member in progress: - tar.extract(member, path=path) - # Sets progress description of progress bar - progress.set_description(f"Extracting {member.name}") - - -def archive_list(tar_file: str) -> List[str]: - """ - Returns contents of tar archive. - - Takes .tar.gz archive and returns a full list of its contents, including - folders, subfolders, and files, with their full relative paths and names. - - Parameters - ---------- - tar_file (str): name of desired .tar.gz archive. Input string can either - include or not include file extension (.tar.gz), as this will be checked. - - Returns - ------- - List[str] of all items in archive - """ - - full_tar_name = tar_name_checker(tar_file) - - # Checks if file exists - if not os.path.exists(full_tar_name): - raise FileNotFoundError(f"This file or folder, '{tar_file}', " - "does not exist!\nPlease rerun program") - - # Adds names of archive contents to list - with tarfile.open(full_tar_name, mode="r") as tar: - tar_list = tar.getnames() - return tar_list - - -def tar_name_checker(tar_file_name: str) -> str: - """ - Checks and modifies file name for tar archive. - - Helper method that takes a tar file name and checks it for the appropriate - file extension (".tar.gz" for now), returning it if it already does, and - adding the extension and then returning it if it does not. - - Parameters - ---------- - tar_file_name (str): name for archive being checked. - - Returns - ------- - String of properly formatted tar archive name - """ - - if tar_file_name.endswith('.tar.gz'): - return tar_file_name - return f'{tar_file_name}.tar.gz' - - -def convert_to_mne( - raw_data: RawData, - channel_map: Optional[List[int]] = None, - channel_types: Optional[List[str]] = None, - transform: Optional[Composition] = None, - montage: str = 'standard_1020', - volts: bool = False) -> RawArray: - """Convert to MNE. - - Returns BciPy RawData as an MNE RawArray. This assumes all channel names - are reflective of provided montage locations. - - Parameters - ---------- - raw_data - BciPy RawData object - channel_map - optional list of channels to include in the MNE RawArray [1, 0, 1, 0, 1, 0, 1, 0]. - 1 indicates the channel should be included, 0 indicates it should be excluded. - Must be the same length as the number of channels in the raw_data. - channel_types - list of channel types to include in the MNE RawArray. - If None, all channels will be assumed to be eeg. - See: https://mne.tools/stable/overview/implementation.html#supported-channel-types - transform - optional transform to apply to the data - montage - name of the channel location montage to use. - See https://mne.tools/dev/generated/mne.channels.make_standard_montage.html - volts - if True, assume data is already in volts. If false, assume data is in microvolts and convert to volts. - MNE expects data to be in volts. - See: https://mne.tools/dev/overview/implementation.html#internal-representation-units - """ - # if no channel map provided, assume all channels are included - if not channel_map: - channel_map = [1] * len(raw_data.channels) - - data, channels, fs = raw_data.by_channel_map(channel_map, transform) - - # if no channel types provided, assume all channels are eeg - if not channel_types: - channel_types = ['eeg'] * len(channels) - - # check that number of channel types matches number of channels in the case custom channel types are provided - assert len(channel_types) == len(channels), \ - f'Number of channel types ({len(channel_types)}) must match number of channels ({len(channels)})' - - info = mne.create_info(channels, fs, channel_types) - mne_data = RawArray(data, info) - ten_twenty_montage = mne.channels.make_standard_montage(montage) - mne_data.set_montage(ten_twenty_montage) - - # convert to volts if necessary (the default for many systems is microvolts) - if not volts: - mne_data = mne_data.apply_function(lambda x: x * 1e-6) - - return mne_data - - -def tobii_to_norm(tobii_units: Tuple[float, float]) -> Tuple[float, float]: - """Tobii to PsychoPy's 'norm' units. - - https://developer.tobiipro.com/commonconcepts/coordinatesystems.html - https://www.psychopy.org/general/units.html - - Tobii uses an Active Display Coordinate System. - The point (0, 0) denotes the upper left corner and (1, 1) the lower right corner of it. - - PsychoPy uses several coordinate systems, the normalized window unit is assumed here. - The point (0, 0) denotes the center of the screen and (-1, -1) the upper left corner - and (1, 1) the lower right corner. - - """ - # check that Tobii units are within the expected range - assert 0 <= tobii_units[0] <= 1, "Tobii x coordinate must be between 0 and 1" - assert 0 <= tobii_units[1] <= 1, "Tobii y coordinate must be between 0 and 1" - - # convert Tobii units to Psychopy units - norm_x = (tobii_units[0] - 0.5) * 2 - norm_y = (tobii_units[1] - 0.5) * 2 * -1 - return (norm_x, norm_y) - - -def norm_to_tobii(norm_units: Tuple[float, float]) -> Tuple[float, float]: - """PsychoPy's 'norm' units to Tobii. - - https://developer.tobiipro.com/commonconcepts/coordinatesystems.html - https://www.psychopy.org/general/units.html - - Tobii uses an Active Display Coordinate System. - The point (0, 0) denotes the upper left corner and (1, 1) the lower right corner of it. - - PsychoPy uses several coordinate systems, the normalized window unit is assumed here. - The point (0, 0) denotes the center of the screen and (-1, -1) the upper left corner - and (1, 1) the lower right corner. - """ - # check that the coordinates are within the bounds of the screen - assert norm_units[0] >= -1 and norm_units[0] <= 1, "X coordinate must be between -1 and 1" - assert norm_units[1] >= -1 and norm_units[1] <= 1, "Y coordinate must be between -1 and 1" - - # convert PsychoPy norm units to Tobii units - tobii_x = (norm_units[0] / 2) + 0.5 - tobii_y = ((norm_units[1] * -1) / 2) + 0.5 - return (tobii_x, tobii_y) diff --git a/bcipy/helpers/copy_phrase_wrapper.py b/bcipy/helpers/copy_phrase_wrapper.py index aa546948e..d30bf4ae6 100644 --- a/bcipy/helpers/copy_phrase_wrapper.py +++ b/bcipy/helpers/copy_phrase_wrapper.py @@ -6,11 +6,11 @@ import numpy as np from bcipy.config import SESSION_LOG_FILENAME +from bcipy.core.stimuli import InquirySchedule, StimuliOrder +from bcipy.core.symbols import BACKSPACE_CHAR from bcipy.exceptions import BciPyCoreException from bcipy.helpers.language_model import histogram, with_min_prob -from bcipy.helpers.stimuli import InquirySchedule, StimuliOrder -from bcipy.helpers.symbols import BACKSPACE_CHAR -from bcipy.language.main import LanguageModel +from bcipy.language.main import CharacterLanguageModel, LanguageModel from bcipy.task.control.criteria import (CriteriaEvaluator, MaxIterationsCriteria, MinIterationsCriteria, @@ -180,6 +180,9 @@ def letter_info(self, triggers: List[Tuple[str, float]], def initialize_series(self) -> Tuple[bool, InquirySchedule]: """If a decision is made initializes the next series.""" assert self.lmodel, "Language model must be initialized." + if not isinstance(self.lmodel, CharacterLanguageModel): + raise BciPyCoreException( + "Only character language models are currently supported.") try: # First, reset the history for this new series @@ -190,7 +193,7 @@ def initialize_series(self) -> Tuple[bool, InquirySchedule]: log.info(f"Querying language model: '{update}'") # update the lmodel and get back the priors - lm_letter_prior = self.lmodel.predict(list(update)) + lm_letter_prior = self.lmodel.predict_character(list(update)) if BACKSPACE_CHAR in self.alp: # Apply configured backspace probability. @@ -206,14 +209,15 @@ def initialize_series(self) -> Tuple[bool, InquirySchedule]: ] # display histogram of LM probabilities - log.info(histogram(lm_letter_prior)) + log.debug(histogram(lm_letter_prior)) # Try fusing the lmodel evidence try: prob_dist = self.conjugator.update_and_fuse( {EvidenceType.LM: np.array(prior)}) except Exception as fusion_error: - log.exception(f'Error fusing language model evidence!: {fusion_error}') + log.exception( + f'Error fusing language model evidence!: {fusion_error}') raise BciPyCoreException(fusion_error) from fusion_error # Get decision maker to give us back some decisions and stimuli diff --git a/bcipy/helpers/demo/demo_convert.py b/bcipy/helpers/demo/demo_convert.py deleted file mode 100644 index b15918021..000000000 --- a/bcipy/helpers/demo/demo_convert.py +++ /dev/null @@ -1,51 +0,0 @@ -"""Demonstrates converting BciPy data output to other EEG formats. - -To use at bcipy root, - - `python bcipy/helpers/demo/demo_convert.py -d "path://to/bcipy/data/folder"` -""" -from bcipy.helpers.convert import convert_to_edf, convert_to_bdf -from bcipy.helpers.load import load_experimental_data -from bcipy.helpers.visualization import plot_edf - - -if __name__ == '__main__': - import argparse - - parser = argparse.ArgumentParser() - parser.add_argument( - '-d', - '--directory', - help='Path to the directory with raw_data to be converted', - required=False) - parser.add_argument( - '-p', - '--plot', - help='whether to plot the resulting edf file', - required=False - ) - args = parser.parse_args() - - path = args.directory - if not path: - path = load_experimental_data() - - edf_path = convert_to_edf( - path, - use_event_durations=False, - write_targetness=True, - overwrite=True, - pre_filter=True) - - bdf_path = convert_to_bdf( - path, - use_event_durations=False, - write_targetness=True, - overwrite=True, - pre_filter=True) - - if args.plot: - plot_edf(edf_path) # comment if not in an iPython notebook to plot using MNE - - print(f"\nWrote edf file to {edf_path}") - print(f"\nWrote bdf file to {bdf_path}") diff --git a/bcipy/helpers/demo/demo_copy_phrase_wrapper.py b/bcipy/helpers/demo/demo_copy_phrase_wrapper.py deleted file mode 100644 index ca6fac117..000000000 --- a/bcipy/helpers/demo/demo_copy_phrase_wrapper.py +++ /dev/null @@ -1,57 +0,0 @@ -import numpy as np -from bcipy.acquisition.devices import preconfigured_device -from bcipy.helpers.copy_phrase_wrapper import CopyPhraseWrapper -from bcipy.helpers.symbols import alphabet -from bcipy.language.model.uniform import UniformLanguageModel -from bcipy.signal.model import PcaRdaKdeModel - -channel_map = [0] + [1] * 16 + [0, 0, 1, 1, 0, 1, 1, 1, 0] -dim_x = 5 -num_ch = len(channel_map) - -# Make up some distributions that data come from -mean_pos = .5 -var_pos = .5 -mean_neg = 0 -var_neg = .5 - - -def demo_copy_phrase_wrapper(): - # We need to train a dummy model - num_x_p = 100 - num_x_n = 900 - - x_p = mean_pos + var_pos * np.random.randn(num_ch, num_x_p, dim_x) - x_n = mean_neg + var_neg * np.random.randn(num_ch, num_x_n, dim_x) - y_p = [1] * num_x_p - y_n = [0] * num_x_n - - train_x = np.concatenate((x_p, x_n), 1) - train_y = np.concatenate((y_p, y_n), 0) - permutation = np.random.permutation(train_x.shape[1]) - train_x = train_x[:, permutation, :] - train_y = train_y[permutation] - - train_x = train_x[list(np.where(np.asarray(channel_map) == 1)[0]), :, :] - - model = PcaRdaKdeModel(k_folds=10) - model.fit(train_x, train_y) - - # Define task and operate - task_list = [('I_LOVE_COOKIES', 'I_LOVE_'), - ('THIS_IS_A_DEMO', 'THIS_IS_A_')] - - task = CopyPhraseWrapper(min_num_inq=1, - max_num_inq=25, - lmodel=UniformLanguageModel(), - device_spec=preconfigured_device('DSI-24'), - signal_model=model, - k=1, - alp=alphabet(), - task_list=task_list) - - print(task) - - -if __name__ == '__main__': - demo_copy_phrase_wrapper() diff --git a/bcipy/helpers/demo/demo_sound_card.py b/bcipy/helpers/demo/demo_sound_card.py deleted file mode 100644 index 5e0533531..000000000 --- a/bcipy/helpers/demo/demo_sound_card.py +++ /dev/null @@ -1,28 +0,0 @@ -'''demo for using sound device and sound file: - Taken from: https://python-sounddevice.readthedocs.io/en/0.2.1/examples.html -''' - -import argparse -import logging -log = logging.getLogger(__name__) -# To use, cd into helpers directory, run >> python demo/sound_card_demo.py "filename" -# Example: python demo/sound_card_demo.py "../static/sounds/chime.wav" - -parser = argparse.ArgumentParser(description=__doc__) -parser.add_argument("filename", help="audio file to be played back") -parser.add_argument("-d", "--device", type=int, help="device ID") -args = parser.parse_args() - -try: - import sounddevice as sd - import soundfile as sf - devices = sd.query_devices() - print(devices) - data, fs = sf.read(args.filename, dtype='float32') - sd.play(data, fs, device=args.device, blocking=True) - status = sd.get_status() - if status: - log.warning(str(status)) -except BaseException as e: - # This avoids printing the traceback, especially if Ctrl-C is used. - raise SystemExit(str(e)) diff --git a/bcipy/helpers/demo/demo_visualization.py b/bcipy/helpers/demo/demo_visualization.py index 078db292a..e4b264479 100644 --- a/bcipy/helpers/demo/demo_visualization.py +++ b/bcipy/helpers/demo/demo_visualization.py @@ -17,11 +17,11 @@ from bcipy.config import (DEFAULT_DEVICE_SPEC_FILENAME, DEFAULT_PARAMETERS_FILENAME, RAW_DATA_FILENAME, TRIGGER_FILENAME) +from bcipy.core.triggers import TriggerType, trigger_decoder from bcipy.helpers.acquisition import analysis_channels -from bcipy.helpers.load import (load_experimental_data, load_json_parameters, - load_raw_data) -from bcipy.helpers.triggers import TriggerType, trigger_decoder from bcipy.helpers.visualization import visualize_erp +from bcipy.io.load import (load_experimental_data, load_json_parameters, + load_raw_data) from bcipy.signal.process import get_default_transform if __name__ == '__main__': @@ -42,7 +42,10 @@ path = args.path if not path: - path = load_experimental_data() + path = load_experimental_data( + message="Select the folder containing the raw_data.csv, parameters.json and triggers.txt", + strict=True + ) parameters = load_json_parameters(f'{path}/{DEFAULT_PARAMETERS_FILENAME}', value_cast=True) @@ -83,7 +86,8 @@ trigger_targetness, trigger_timing, trigger_symbols = trigger_decoder( offset=static_offset, trigger_path=f"{path}/{TRIGGER_FILENAME}", - exclusion=[TriggerType.PREVIEW, TriggerType.EVENT, TriggerType.FIXATION], + exclusion=[TriggerType.PREVIEW, + TriggerType.EVENT, TriggerType.FIXATION], ) labels = [0 if label == 'nontarget' else 1 for label in trigger_targetness] diff --git a/bcipy/helpers/language_model.py b/bcipy/helpers/language_model.py index b1b77a05d..d91154817 100644 --- a/bcipy/helpers/language_model.py +++ b/bcipy/helpers/language_model.py @@ -1,35 +1,51 @@ """Helper functions for language model use.""" import inspect import math -from typing import Dict, List, Tuple +from typing import Callable, Dict, List, Tuple import numpy as np -from bcipy.helpers.symbols import alphabet -from bcipy.language.main import LanguageModel, ResponseType +from bcipy.core.symbols import alphabet +from bcipy.exceptions import LanguageModelNameInUseException +from bcipy.language.main import LanguageModel +from bcipy.language.model.causal import CausalLanguageModelAdapter +from bcipy.language.model.mixture import MixtureLanguageModelAdapter +from bcipy.language.model.ngram import NGramLanguageModelAdapter +from bcipy.language.model.oracle import OracleLanguageModel +from bcipy.language.model.uniform import UniformLanguageModel # pylint: disable=unused-import # flake8: noqa """Only imported models will be included in language_models_by_name""" # flake8: noqa -from bcipy.exceptions import InvalidLanguageModelException -from bcipy.language.model.causal import CausalLanguageModel -from bcipy.language.model.kenlm import KenLMLanguageModel -from bcipy.language.model.mixture import MixtureLanguageModel -from bcipy.language.model.oracle import OracleLanguageModel -from bcipy.language.model.uniform import UniformLanguageModel -from bcipy.language.model.unigram import UnigramLanguageModel + +VALID_LANGUAGE_MODELS: Dict[str, Callable[[], LanguageModel]] = { + "CAUSAL": CausalLanguageModelAdapter, + "NGRAM": NGramLanguageModelAdapter, + "MIXTURE": MixtureLanguageModelAdapter, + "ORACLE": OracleLanguageModel, + "UNIFORM": UniformLanguageModel +} -def language_models_by_name() -> Dict[str, LanguageModel]: +def language_models_by_name() -> Dict[str, Callable[[], LanguageModel]]: """Returns available language models indexed by name.""" - return {lm.name(): lm for lm in LanguageModel.__subclasses__()} + return VALID_LANGUAGE_MODELS + + +def register_language_model(name: str, lm_type: Callable[[], LanguageModel]) -> None: + if name in VALID_LANGUAGE_MODELS: + raise LanguageModelNameInUseException( + f"{name} is already registered as {VALID_LANGUAGE_MODELS[name]}.") + else: + VALID_LANGUAGE_MODELS[name] = lm_type def init_language_model(parameters: dict) -> LanguageModel: """ - Init Language Model configured in the parameters. + Init Language Model configured in the parameters. If no language model is + specified, a uniform language model is returned. Parameters ---------- @@ -49,9 +65,12 @@ def init_language_model(parameters: dict) -> LanguageModel: # select the relevant parameters into a dict. params = {key: parameters[key] for key in args & parameters.keys()} - return model(response_type=ResponseType.SYMBOL, - symbol_set=alphabet(parameters), - **params) + + lm = model(**params) + + lm.set_symbol_set(alphabet(parameters)) + + return lm def norm_domain(priors: List[Tuple[str, float]]) -> List[Tuple[str, float]]: diff --git a/bcipy/helpers/list.py b/bcipy/helpers/list.py deleted file mode 100644 index a4d4e7d2c..000000000 --- a/bcipy/helpers/list.py +++ /dev/null @@ -1,80 +0,0 @@ -"""Utility functions for list processing.""" -from itertools import zip_longest -from typing import Any, Callable, List, Optional, Union - - -def destutter(items: List[Any], key: Callable = lambda x: x) -> List: - """Removes sequential duplicates from a list. Retains the last item in the - sequence. Equality is determined using the provided key function. - - Parameters - ---------- - items - list of items with sequential duplicates - key - equality function - """ - deduped: List[Any] = [] - for item in items: - if len(deduped) == 0 or key(item) != key(deduped[-1]): - deduped.append(item) - else: - deduped[-1] = item - return deduped - - -def grouper(iterable, chunk_size, incomplete="fill", fillvalue=None): - "Collect data into non-overlapping fixed-length chunks or blocks" - # grouper('ABCDEFG', 3, fillvalue='x') --> ABC DEF Gxx - # grouper('ABCDEFG', 3, incomplete='ignore') --> ABC DEF - chunks = [iter(iterable)] * chunk_size - if incomplete == "fill": - if fillvalue: - return zip_longest(*chunks, fillvalue=fillvalue) - raise ValueError('fillvalue must be defined if using incomplete=fill') - if incomplete == "ignore": - return zip(*chunks) - - raise ValueError("Expected fill or ignore") - - -def find_index(iterable: List, - match_item: Union[Any, Callable], - key: Callable = lambda x: x) -> Optional[int]: - """Find the index of the first item in the iterable which matches.""" - for i, value in enumerate(iterable): - if callable(match_item): - result = match_item(value) - else: - result = key(value) == match_item - if result: - return i - return None - - -def swapped(lst: List[Any], index1: int, index2: int) -> List[Any]: - """Creates a copy of the provided list with elements at the given indices - swapped.""" - replacements = {index1: lst[index2], index2: lst[index1]} - return [replacements.get(i, val) for i, val in enumerate(lst)] - - -def expanded(lst: List[Any], - length: int, - fill: Union[Any, Callable] = lambda x: x[-1]) -> List[Any]: - """Creates a copy of the provided list expanded to the given length. By - default the last item is used as the fill item. - - Parameters - ---------- - lst - list of items to copy - length - expands list to this length - fill - optional; used to determine which element to use for - the fill, given the list. Defaults to the last element. - - >>> expand([1,2,3], length=5) - [1,2,3,3,3] - """ - times = length - len(lst) - if lst and times > 0: - item = fill(lst) if callable(fill) else fill - return lst + ([item] * times) - return lst diff --git a/bcipy/helpers/load.py b/bcipy/helpers/load.py deleted file mode 100644 index 22454c5bc..000000000 --- a/bcipy/helpers/load.py +++ /dev/null @@ -1,333 +0,0 @@ -# mypy: disable-error-code="arg-type, union-attr" -import json -import logging -import os -import pickle -from pathlib import Path -from shutil import copyfile -from time import localtime, strftime -from typing import List, Optional, Union - -from bcipy.config import (DEFAULT_ENCODING, DEFAULT_EXPERIMENT_PATH, - DEFAULT_FIELD_PATH, DEFAULT_PARAMETERS_PATH, - EXPERIMENT_FILENAME, FIELD_FILENAME, ROOT, - SIGNAL_MODEL_FILE_SUFFIX, SESSION_LOG_FILENAME) -from bcipy.gui.file_dialog import ask_directory, ask_filename -from bcipy.exceptions import (BciPyCoreException, - InvalidExperimentException) -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.raw_data import RawData -from bcipy.preferences import preferences -from bcipy.signal.model import SignalModel - -log = logging.getLogger(SESSION_LOG_FILENAME) - - -def copy_parameters(path: str = DEFAULT_PARAMETERS_PATH, - destination: Optional[str] = None) -> str: - """Creates a copy of the given configuration (parameters.json) to the - given directory and returns the path. - - Parameters: - ----------- - path: str - optional path of parameters file to copy; used default if not provided. - destination: str - optional destination directory; default is the same - directory as the default parameters. - Returns: - -------- - path to the new file. - """ - default_dir = str(Path(DEFAULT_PARAMETERS_PATH).parent) - - destination = default_dir if destination is None else destination - filename = strftime('parameters_%Y-%m-%d_%Hh%Mm%Ss.json', localtime()) - - path = str(Path(destination, filename)) - copyfile(DEFAULT_PARAMETERS_PATH, path) - return path - - -def load_experiments(path: str = f'{DEFAULT_EXPERIMENT_PATH}/{EXPERIMENT_FILENAME}') -> dict: - """Load Experiments. - - PARAMETERS - ---------- - :param: path: string path to the experiments file. - - Returns - ------- - A dictionary of experiments, with the following format: - { name: { fields : {name: '', required: bool, anonymize: bool}, summary: '' } } - - """ - with open(path, 'r', encoding=DEFAULT_ENCODING) as json_file: - return json.load(json_file) - - -def extract_mode(bcipy_data_directory: str) -> str: - """Extract Mode. - - This method extracts the task mode from a BciPy data save directory. This is important for - trigger conversions and extracting targeteness. - - *note*: this is not compatible with older versions of BciPy (pre 1.5.0) where - the tasks and modes were considered together using integers (1, 2, 3). - - PARAMETERS - ---------- - :param: bcipy_data_directory: string path to the data directory - """ - directory = bcipy_data_directory.lower() - if 'calibration' in directory: - return 'calibration' - elif 'copy' in directory: - return 'copy_phrase' - raise BciPyCoreException(f'No valid mode could be extracted from [{directory}]') - - -def load_fields(path: str = f'{DEFAULT_FIELD_PATH}/{FIELD_FILENAME}') -> dict: - """Load Fields. - - PARAMETERS - ---------- - :param: path: string path to the fields file. - - Returns - ------- - A dictionary of fields, with the following format: - { - "field_name": { - "help_text": "", - "type": "" - } - - """ - with open(path, 'r', encoding=DEFAULT_ENCODING) as json_file: - return json.load(json_file) - - -def load_experiment_fields(experiment: dict) -> list: - """Load Experiment Fields. - - { - 'fields': [{}, {}], - 'summary': '' - } - - Using the experiment dictionary, loop over the field keys and put them in a list. - """ - if isinstance(experiment, dict): - try: - return [name for field in experiment['fields'] for name in field.keys()] - except KeyError: - raise InvalidExperimentException( - 'Experiment is not formatted correctly. It should be passed as a dictionary with the fields and' - f' summary keys. Fields is a list of dictionaries. Summary is a string. \n experiment=[{experiment}]') - raise TypeError('Unsupported experiment type. It should be passed as a dictionary with the fields and summary keys') - - -def load_json_parameters(path: str, value_cast: bool = False) -> Parameters: - """Load JSON Parameters. - - Given a path to a json of parameters, convert to a dictionary and optionally - cast the type. - - Expects the following format: - "fake_data": { - "value": "true", - "section": "bci_config", - "name": "Fake Data Sessions", - "helpTip": "If true, fake data server used", - "recommended": "", - "editable": "true", - "type": "bool" - } - - PARAMETERS - ---------- - :param: path: string path to the parameters file. - :param: value_case: True/False cast values to specified type. - - Returns - ------- - a Parameters object that behaves like a dict. - """ - return Parameters(source=path, cast_values=value_cast) - - -def load_experimental_data() -> str: - filename = ask_directory() # show dialog box and return the path - if not filename: - raise BciPyCoreException('No file selected in GUI. Exiting...') - log.info("Loaded Experimental Data From: %s" % filename) - return filename - - -def load_signal_models(directory: Optional[str] = None) -> List[SignalModel]: - """Load all signal models in a given directory. - - Models are assumed to have been written using bcipy.helpers.save.save_model - function and should be serialized as pickled files. Note that reading - pickled files is a potential security concern so only load from trusted - directories. - - Args: - dirname (str, optional): Location of pretrained models. If not - provided the user will be prompted for a location. - """ - if not directory or Path(directory).is_file(): - directory = ask_directory() - - # update preferences - path = Path(directory) - preferences.signal_model_directory = str(path) - - models = [] - for file_path in path.glob(f"*{SIGNAL_MODEL_FILE_SUFFIX}"): - with open(file_path, "rb") as signal_file: - model = pickle.load(signal_file) - log.info(f"Loading model {model}") - models.append(model) - return models - - -def choose_signal_models(device_types: List[str]) -> List[SignalModel]: - """Prompt the user to load a signal model for each provided device. - - Parameters - ---------- - device_types - list of device content types (ex. 'EEG') - """ - return [ - model for model in map(choose_signal_model, set(device_types)) if model - ] - - -def load_signal_model(file_path: str) -> SignalModel: - """Load signal model from persisted file. - - Models are assumed to have been written using bcipy.helpers.save.save_model - function and should be serialized as pickled files. Note that reading - pickled files is a potential security concern so only load from trusted - directories.""" - - with open(file_path, "rb") as signal_file: - model = pickle.load(signal_file) - log.info(f"Loading model {model}") - return model - - -def choose_signal_model(device_type: str) -> Optional[SignalModel]: - """Present a file dialog prompting the user to select a signal model for - the given device. - - Parameters - ---------- - device_type - ex. 'EEG' or 'Eyetracker'; this should correspond with - the content_type of the DeviceSpec of the model. - """ - - file_path = ask_filename(file_types=f"*{SIGNAL_MODEL_FILE_SUFFIX}", - directory=preferences.signal_model_directory, - prompt=f"Select the {device_type} signal model") - - if file_path: - # update preferences - path = Path(file_path) - preferences.signal_model_directory = str(path) - return load_signal_model(str(path)) - return None - - -def choose_csv_file(filename: Optional[str] = None) -> Optional[str]: - """GUI prompt to select a csv file from the file system. - - Parameters - ---------- - - filename : optional filename to use; if provided the GUI is not shown. - - Returns - ------- - file name of selected file; throws an exception if the file is not a csv. - """ - if not filename: - filename = ask_filename('*.csv') - - # get the last part of the path to determine file type - file_name = filename.split('/')[-1] - - if 'csv' not in file_name: - raise TypeError( - 'File type unrecognized. Please use a supported csv type') - - return filename - - -def load_raw_data(filename: Union[Path, str]) -> RawData: - """Reads the data (.csv) file written by data acquisition. - - Parameters - ---------- - - filename : path to the serialized data (csv file) - - Returns - ------- - RawData object with data held in memory - """ - return RawData.load(filename) - - -def load_txt_data() -> str: - filename = ask_filename('*.txt') # show dialog box and return the path - file_name = filename.split('/')[-1] - - if 'txt' not in file_name: - raise TypeError( - 'File type unrecognized. Please use a supported text type') - - return filename - - -def load_users(data_save_loc: str) -> List[str]: - """Load Users. - - Loads user directory names below experiments from the data path defined and returns them as a list. - If the save data directory is not found, this method returns an empty list assuming no experiments - have been run yet. - """ - # build a saved users list, pull out the data save location from parameters - saved_users: List[str] = [] - - # check the directory is valid, if it is, set path as data save location - if os.path.isdir(data_save_loc): - path = data_save_loc - - # check the directory is valid after adding bcipy, if it is, set path as data save location - elif os.path.isdir(f'{ROOT}/{data_save_loc}'): - path = f'{ROOT}/{data_save_loc}' - - else: - log.info(f'User save data location not found at [{data_save_loc}]! Returning empty user list.') - return saved_users - - # grab all experiments in the directory and iterate over them to get the users - users = fast_scandir(path, return_path=True) - - for user in users: - if user not in saved_users: - saved_users.append(user.split('/')[-1]) - - return saved_users - - -def fast_scandir(directory_name: str, return_path: bool = True) -> List[str]: - """Fast Scan Directory. - - directory_name: name of the directory to be scanned - return_path: whether or not to return the scanned directories as a relative path or name. - False will return the directory name only. - """ - if return_path: - return [f.path for f in os.scandir(directory_name) if f.is_dir()] - - return [f.name for f in os.scandir(directory_name) if f.is_dir()] diff --git a/bcipy/helpers/offset.py b/bcipy/helpers/offset.py index 0858aadc3..c45ab8404 100644 --- a/bcipy/helpers/offset.py +++ b/bcipy/helpers/offset.py @@ -1,23 +1,17 @@ -from typing import Any, List, Tuple -from textwrap import wrap from pathlib import Path +from textwrap import wrap +from typing import Any, List, Tuple import matplotlib.pyplot as plt import numpy as np - from scipy.stats import normaltest -from bcipy.helpers.load import load_raw_data, ask_directory, load_json_parameters -from bcipy.helpers.raw_data import RawData -from bcipy.helpers.triggers import trigger_decoder, TriggerType - -from bcipy.config import ( - TRIGGER_FILENAME, - DIODE_TRIGGER, - RAW_DATA_FILENAME, - DEFAULT_TRIGGER_CHANNEL_NAME, - DEFAULT_PARAMETERS_FILENAME -) +from bcipy.config import (DEFAULT_PARAMETERS_FILENAME, + DEFAULT_TRIGGER_CHANNEL_NAME, DIODE_TRIGGER, + RAW_DATA_FILENAME, TRIGGER_FILENAME) +from bcipy.core.raw_data import RawData +from bcipy.core.triggers import TriggerType, trigger_decoder +from bcipy.io.load import ask_directory, load_json_parameters, load_raw_data def sample_to_seconds(sample_rate: float, sample: int) -> float: @@ -111,6 +105,7 @@ def calculate_latency(raw_data: RawData, if value < 1 and diode_enc: diode_enc = False + trigger_diodes_timestamps = [] # Plot triggers.txt data if present; vertical line for each value. if triggers: trigger_diodes_timestamps = [ @@ -159,7 +154,8 @@ def calculate_latency(raw_data: RawData, # if it's not normal, take the median if p_value < 0.05: - print(f'Non-normal distribution of diffs. p-value=[{p_value}] Consider using median for static offset.') + print( + f'Non-normal distribution of diffs. p-value=[{p_value}] Consider using median for static offset.') recommended_static = abs(np.median(diffs)) print( f'System recommended static offset median=[{recommended_static}]') @@ -193,7 +189,8 @@ def calculate_latency(raw_data: RawData, linewidth=0.5, color='cyan') - ax.plot(trg_box_x, trg_box_y, label=f'{diode_channel} (photodiode triggers)') + ax.plot(trg_box_x, trg_box_y, + label=f'{diode_channel} (photodiode triggers)') # Add labels for TRGs first_trg = trigger_diodes_timestamps[0] @@ -265,7 +262,8 @@ def sample_rate_diffs(raw_data: RawData) -> Tuple[int, float]: # get the count of all the samples and calculate the time recorded from the raw_data sample_time = raw_data.dataframe.shape[0] / raw_data.sample_rate - print(f'LSL Timestamp Sample Count: {lsl_sample_diff} EEG Sample Count: {sample_time}') + print( + f'LSL Timestamp Sample Count: {lsl_sample_diff} EEG Sample Count: {sample_time}') return lsl_sample_diff, sample_time @@ -340,10 +338,12 @@ def extract_data_latency_calculation( args = parser.parse_args() data_path = args.data_path if not data_path: - data_path = ask_directory() + data_path = ask_directory( + prompt="Please select a BciPy time test directory..", strict=True) # grab the stim length from the data directory parameters - stim_length = load_json_parameters(f'{data_path}/{DEFAULT_PARAMETERS_FILENAME}', value_cast=True)['stim_length'] + stim_length = load_json_parameters( + f'{data_path}/{DEFAULT_PARAMETERS_FILENAME}', value_cast=True)['stim_length'] raw_data, triggers, static_offset = extract_data_latency_calculation( data_path, diff --git a/bcipy/helpers/parameters.py b/bcipy/helpers/parameters.py deleted file mode 100644 index 3be5f3d48..000000000 --- a/bcipy/helpers/parameters.py +++ /dev/null @@ -1,336 +0,0 @@ -"""Module for functionality related to system configuration""" -from codecs import open as codecsopen -from collections import abc -from json import dump, load -from pathlib import Path -from re import fullmatch -from typing import Optional, Any, Dict, NamedTuple, Tuple - -from bcipy.config import DEFAULT_ENCODING, DEFAULT_PARAMETERS_PATH - - -class Parameter(NamedTuple): - """Represents a single parameter""" - value: Any - section: str - name: str - helpTip: str - recommended: list - editable: bool - type: str - - -class ParameterChange(NamedTuple): - """Represents a Parameter that has been modified from a different value.""" - parameter: Parameter - original_value: Any - - -def parse_range(range_str: str) -> Tuple: - """Parse the range description into a tuple of (low, high). - - If either value can be parsed as a float the resulting tuple will have - float values, otherwise they will be ints. - - Parameters - ---------- - range_str - range description formatted 'low:high' - - >>> parse_range("1:10") - (1, 10) - """ - assert ':' in range_str, "Invalid range format; values must be separated by ':'" - low, high = range_str.split(':') - int_pattern = "-?\\d+" - if fullmatch(int_pattern, low) and fullmatch(int_pattern, high): - low = int(low) - high = int(high) - else: - low = float(low) - high = float(high) - - assert low < high, "Low value must be less that the high value" - return (low, high) - - -def serialize_value(value_type: str, value: Any) -> str: - """Serialize the given value to a string. Serialized values should be able - to be cast using the conversions.""" - if value_type == 'bool': - return str(value).lower() - if value_type == 'range': - low, high = value - return f"{low}:{high}" - return str(value) - - -class Parameters(dict): - """Configuration parameters for BciPy. - - source: str - optional path to a JSON file. If file exists, data will be - loaded from here. Raises an exception unless the entries are dicts with - the required_keys. - - cast_values: bool - if True cast values to specified type; default is False. - """ - - def __init__(self, source: Optional[str] = None, cast_values: bool = False): - super().__init__() - self.source = source - self.cast_values = cast_values - - self.required_keys = set([ - 'value', 'section', 'name', 'helpTip', - 'recommended', 'editable', 'type' - ]) - self.conversions = { - 'int': int, - 'float': float, - 'bool': lambda val: val == 'true' or val is True, - 'str': str, - 'directorypath': str, - 'filepath': str, - 'range': parse_range - } - self.load_from_source() - - @classmethod - def from_cast_values(cls, **kwargs): - """Create a new Parameters object from cast values. This is useful - primarily for testing - - >>> Parameters.from_cast_values(time_prompt=1.0, fake_data=True) - """ - params = Parameters(source=None, cast_values=True) - for key, val in kwargs.items(): - value_type = type(val).__name__ - # Convert tuple to range - if value_type == 'tuple': - value_type = 'range' - value_str = serialize_value(value_type, val) - params.add_entry( - key, { - 'value': value_str, - 'section': '', - 'name': '', - 'helpTip': '', - 'recommended': '', - 'editable': '', - 'type': value_type - }) - return params - - @property - def supported_types(self) -> set: - """Supported types for casting values""" - return self.conversions.keys() - - def cast_value(self, entry: dict) -> Any: - """Takes an entry with a desired type and attempts to cast it to that type.""" - cast = self.conversions[entry['type']] - return cast(entry['value']) - - def serialized_value(self, value, entry_type) -> str: - """Convert a value back into its serialized form""" - serialized = str(value) - return serialized.lower() if entry_type == 'bool' else serialized - - def __getitem__(self, key) -> Any: - """Override to handle cast values""" - entry = self.get_entry(key) - if self.cast_values: - return self.cast_value(entry) - return entry - - def __setitem__(self, key, value) -> None: - """Override to handle cast values""" - if self.cast_values: - # Can only set values for existing entries when cast. - entry = self.get_entry(key) - entry['value'] = self.serialized_value(value, entry['type']) - else: - self.add_entry(key, value) - - def add_entry(self, key, value) -> None: - """Adds a configuration parameter.""" - self.check_valid_entry(key, value) - super().__setitem__(key, value) - - def get_entry(self, key) -> dict: - """Get the non-cast entry associated with the given key.""" - return super().__getitem__(key) - - def get(self, key, d=None) -> Any: - """Override to handle cast values""" - entry = super().get(key, d) - if self.cast_values and entry != d: - return self.cast_value(entry) - return entry - - def entries(self) -> list: - """Uncast items""" - return super().items() - - def items(self) -> list: - """Override to handle cast values""" - if self.cast_values: - return [(key, self.cast_value(entry)) - for key, entry in self.entries()] - return self.entries() - - def values(self) -> list: - """Override to handle cast values""" - vals = super().values() - if self.cast_values: - return [self.cast_value(entry) for entry in vals] - return vals - - def update(self, *args, **kwargs) -> None: - """Override to ensure update uses __setitem___""" - for key, value in dict(*args, **kwargs).items(): - self[key] = value - - def copy(self) -> 'Parameters': - """Override - """ - params = Parameters(source=None, cast_values=self.cast_values) - params.load(super().copy()) - return params - - def load(self, data: dict) -> None: - """Load values from a dict, validating entries (see check_valid_entry) and raising - an exception for invalid values. - - data: dict of configuration parameters. - """ - for name, entry in data.items(): - self.add_entry(name, entry) - - def load_from_source(self) -> None: - """Load data from the configured JSON file.""" - if self.source: - with codecsopen(self.source, 'r', - encoding=DEFAULT_ENCODING) as json_file: - data = load(json_file) - self.load(data) - - def check_valid_entry(self, entry_name: str, entry: dict) -> None: - """Checks if the given entry is valid. Raises an exception unless the entry is formatted: - - "fake_data": { - "value": "true", - "section": "bci_config", - "name": "Fake Data Sessions", - "helpTip": "If true, fake data server used", - "recommended": "", - "editable": true, - "type": "bool" - } - - entry_name : str - name of the configuration parameter - entry : dict - parameter properties - """ - if not isinstance(entry, abc.Mapping): - raise AttributeError(f"'{entry_name}' value must be a dict") - if set(entry.keys()) != self.required_keys: - raise Exception( - f"Incorrect format for key: {entry_name}; value must contain required keys" - ) - if entry['type'] not in self.supported_types: - raise Exception( - f"Type not supported for key: {entry_name}, type: {entry['type']}" - ) - if entry['type'] == "bool" and entry['value'] not in ['true', 'false']: - raise Exception( - f"Invalid value for key: {entry_name}. Must be either 'true' or 'false'" - ) - - def source_location(self) -> Tuple[Path, str]: - """Location of the source json data if source was provided. - - Returns Tuple(Path, filename: str) - """ - if self.source: - path = Path(self.source) - return (path.parent, path.name) - return (None, None) - - def save(self, directory: Optional[str] = None, name: Optional[str] = None) -> str: - """Save parameters to the given location - - directory: str - optional location to save; default is the source_directory. - name: str - optional name of new parameters file; default is the source filename. - - Returns the path of the saved file. - """ - if (not directory or not name) and not self.source: - raise AttributeError('name and directory parameters are required') - - source_directory, source_name = self.source_location() - location = directory if directory else source_directory - filename = name if name else source_name - path = Path(location, filename) - with open(path, 'w', encoding=DEFAULT_ENCODING) as json_file: - dump(dict(self.entries()), json_file, ensure_ascii=False, indent=2) - return str(path) - - def add_missing_items(self, parameters) -> bool: - """Given another Parameters instance, add any items that are not already - present. Existing items will not be updated. - - parameters: Parameters - object from which to add parameters. - - Returns bool indicating whether or not any new items were added. - """ - updated = False - existing_keys = self.keys() - for key, val in parameters.entries(): - if key not in existing_keys: - self.add_entry(key, val) - updated = True - return updated - - def diff(self, parameters) -> Dict[str, ParameterChange]: - """Lists the differences between this and another set of parameters. - A None original_value indicates a new parameter. - - Parameters - ---------- - parameters : Parameters - set of parameters for comparison; these - are considered the original values and the current set the - changed values. - """ - diffs = {} - - for key, param in self.entries(): - if key in parameters.keys(): - original = parameters.get_entry(key) - if self.cast_value(original) != self.cast_value(param): - diffs[key] = ParameterChange( - parameter=param, original_value=original['value']) - else: - diffs[key] = ParameterChange(parameter=param, - original_value=None) - return diffs - - def instantiate(self, named_tuple_class: NamedTuple) -> NamedTuple: - """Instantiate a namedtuple whose fields represent a subset of the - parameters.""" - vals = [ - self.cast_value(self.get_entry(key)) - for key in named_tuple_class._fields - ] - return named_tuple_class(*vals) - - -def changes_from_default(source: str) -> Dict[str, ParameterChange]: - """Determines which parameters have changed from the default params. - - Parameters - ---------- - source - path to the parameters json file that will be compared with - the default parameters. - """ - default = Parameters(source=DEFAULT_PARAMETERS_PATH, cast_values=True) - params = Parameters(source=source, cast_values=True) - return params.diff(default) diff --git a/bcipy/helpers/raw_data.py b/bcipy/helpers/raw_data.py deleted file mode 100644 index d94ac2174..000000000 --- a/bcipy/helpers/raw_data.py +++ /dev/null @@ -1,404 +0,0 @@ -"""Functionality for reading and writing raw signal data.""" -import csv -from io import TextIOWrapper -from typing import List, Optional, TextIO, Tuple, Union, Any - -import numpy as np -import pandas as pd - -from bcipy.config import DEFAULT_ENCODING -from bcipy.exceptions import BciPyCoreException -from bcipy.signal.generator.generator import gen_random_data -from bcipy.signal.process import Composition - -TIMESTAMP_COLUMN = 'timestamp' - - -class RawData: - """Represents the raw data format used by BciPy. Used primarily for loading - a raw data file into memory.""" - - def __init__(self, daq_type: str, sample_rate: int, columns: List[str]) -> None: - self.daq_type = daq_type - self.sample_rate = sample_rate - self.columns = columns - - self._dataframe: Optional[pd.DataFrame] = None - self._rows: List[Any] = [] - - @classmethod - def load(cls, filename: str): - """Constructs a RawData object by deserializing the given file. - All data will be read into memory. If you want to lazily read data one - record at a time, use a RawDataReader. - - Parameters - ---------- - - filename : path to the csv file to read - """ - return load(filename) - - @property - def rows(self) -> List[List]: - """Returns the data rows""" - return self._rows - - @rows.setter - def rows(self, value: Any) -> None: - self._rows = value - self._dataframe = None - - @property - def channels(self) -> List[str]: - """Compute the list of channels. Channels are the numeric columns - excluding the timestamp column.""" - - # Start data slice at 1 to remove the timestamp column. - return list(self.numeric_data.columns[1:]) - - @property - def numeric_data(self) -> pd.DataFrame: - """Data for columns with numeric data. This is usually comprised of the - timestamp column and device channels, excluding string triggers.""" - return self.dataframe.select_dtypes(exclude=['object']) - - @property - def channel_data(self) -> np.ndarray: - """Data for columns with numeric data, excluding the timestamp column.""" - numeric_data = self.numeric_data - - numeric_vals = numeric_data.values - numeric_column_count = numeric_vals.shape[1] - # Start data slice at 1 to remove the timestamp column. - return numeric_vals[:, 1:numeric_column_count].transpose() - - def by_channel(self, transform: Optional[Composition] = None) -> Tuple[np.ndarray, int]: - """Data organized by channel. - - Optionally, it can apply a BciPy Composition to the data before returning using the transform arg. - This will apply n tranformations to the data before returning. For an example Composition with - EEG preprocessing, see bcipy.signal.get_default_transform(). - - Returns - ---------- - data: C x N numpy array with samples where C is the number of channels and N - is number of time samples - fs: resulting sample rate if any transformations applied""" - - data = self.channel_data - fs = self.sample_rate - - if transform: - data, fs = self.apply_transform(data, transform) - - return data, fs - - def by_channel_map( - self, - channel_map: List[int], - transform: Optional[Composition] = None) -> Tuple[np.ndarray, List[str], int]: - """By Channel Map. - - Returns channels with columns removed if index in list (channel_map) is zero. The channel map must align - with the numeric channels read in as self.channels. We assume most trigger or other string columns are - removed, however some are numeric trigger columns from devices that will require filtering before returning - data. Other cases could be dropping bad channels before running further analyses. - - Optionally, it can apply a BciPy Composition to the data before returning using the transform arg. - This will apply n tranformations to the data before returning. For an example Composition with - EEG preprocessing, see bcipy.signal.get_default_transform(). - """ - data, fs = self.by_channel(transform) - channels_to_remove = [idx for idx, value in enumerate(channel_map) if value == 0] - data = np.delete(data, channels_to_remove, axis=0) - channels: List[str] = np.delete(self.channels, channels_to_remove, axis=0).tolist() - - return data, channels, fs - - def apply_transform(self, data: np.ndarray, transform: Composition) -> Tuple[np.ndarray, int]: - """Apply Transform. - - Using data provided as an np.ndarray, call the Composition with self.sample_rate to apply - transformations to the data. This will return the transformed data and resulting sample rate. - """ - return transform(data, self.sample_rate) - - @property - def dataframe(self) -> pd.DataFrame: - """Returns a dataframe of the row data.""" - if self._dataframe is None: - self._dataframe = pd.DataFrame(data=self.rows, - columns=self.columns) - return self._dataframe - - @property - def total_seconds(self) -> float: - """Total recorded seconds, defined as the diff between the first and - last timestamp.""" - frame = self.dataframe - col = 'lsl_timestamp' - return frame.iloc[-1][col] - frame.iloc[0][col] - - @property - def total_samples(self) -> int: - """Number of samples recorded.""" - return int(self.dataframe.iloc[-1]['timestamp']) - - def query(self, - start: Optional[float] = None, - stop: Optional[float] = None, - column: str = 'lsl_timestamp') -> pd.DataFrame: - """Query for a subset of data. - - Pararameters - ------------ - start - find records greater than or equal to this value - stop - find records less than or equal to this value - column - column to compare to the given start and stop values - - Returns - ------- - Dataframe for the given slice of data - """ - dataframe = self.dataframe - start = start or dataframe.iloc[0][column] - stop = stop or dataframe.iloc[-1][column] - mask = (dataframe[column] >= start) & (dataframe[column] <= stop) - return dataframe[mask] - - def append(self, row: list) -> None: - """Append the given row of data. - - Parameters - ---------- - - row : row of data - """ - assert len(row) == len(self.columns), "Wrong number of columns" - self._rows.append(row) - self._dataframe = None - - def __str__(self) -> str: - return f"RawData({self.daq_type})" - - def __repr__(self) -> str: - return f"RawData({self.daq_type})" - - -def maybe_float(val: Any) -> Union[float, Any]: - """Attempt to convert the given value to float. If conversion fails return - as is.""" - try: - return float(val) - except ValueError: - return val - - -class RawDataReader: - """Lazily reads raw data from a file. Intended to be used as a ContextManager - using Python's `with` keyword. - - Example usage: - - ``` - with RawDataReader(path) as reader: - print(f"Data from ${reader.daq_type}") - print(reader.columns) - for row in reader: - print(row) - ``` - - Parameters - ---------- - - file_path : path to the csv file - - convert_data : if True attempts to convert data values to floats; - default is False - """ - _file_obj: TextIOWrapper - - def __init__(self, file_path: str, convert_data: bool = False): - self.file_path = file_path - self.convert_data = convert_data - - def __enter__(self): - self._file_obj = open(self.file_path, mode="r", encoding=DEFAULT_ENCODING) - self.daq_type, self.sample_rate = read_metadata(self._file_obj) - self._reader = csv.reader(self._file_obj) - self.columns = next(self._reader) - return self - - def __exit__(self, *args, **kwargs): - """Exit the context manager. Close resources""" - if self._file_obj: - self._file_obj.close() - - def __iter__(self): - return self - - def __next__(self): - assert self._reader, "Reader must be initialized" - row = next(self._reader) - if self.convert_data: - return list(map(maybe_float, row)) - return row - - -class RawDataWriter: - """Writes a raw data file one row at a time without storing the records - in memory. Intended to be used as a ContextManager using Python's `with` - keyword. - - Example usage: - - ``` - with RawDataWriter(path, daq_type, sample_rate, columns) as writer: - for row in data: - writer.writerow(row) - ``` - - Parameters - ---------- - - file_path : path to the csv file - - daq_type : name of device - - sample_rate : sample frequency in Hz - - columns : list of column names - """ - _file_obj: TextIOWrapper - - def __init__(self, file_path: str, daq_type: str, sample_rate: float, - columns: List[str]) -> None: - self.file_path = file_path - self.daq_type = daq_type - self.sample_rate = sample_rate - self.columns = columns - - def __enter__(self): - """Enter the context manager. Initializes the underlying data file.""" - self._file_obj = open(self.file_path, - mode='w', - encoding=DEFAULT_ENCODING, - newline='') - # write metadata - self._file_obj.write(f"daq_type,{self.daq_type}\n") - self._file_obj.write(f"sample_rate,{self.sample_rate}\n") - - # If flush is missing the previous content may be appended at the end. - self._file_obj.flush() - - self._csv_writer = csv.writer(self._file_obj, delimiter=',') - self._csv_writer.writerow(self.columns) - - return self - - def __exit__(self, *args, **kwargs): - """Exit the context manager. Close resources""" - self._file_obj.close() - - def writerow(self, row: List) -> None: - assert self._csv_writer, "Writer must be initialized" - assert len(row) == len(self.columns), "Wrong number of columns" - self._csv_writer.writerow(row) - - def writerows(self, rows: List[List]) -> None: - for row in rows: - self.writerow(row) - - -def load(filename: str) -> RawData: - """Reads the file at the given path and initializes a RawData object. - All data will be read into memory. If you want to lazily read data one - record at a time, use a RawDataReader. - - Parameters - ---------- - - filename : path to the csv file to read - """ - # Loading all data from a csv is faster using pandas than using the - # RawDataReader. - try: - with open(filename, mode='r', encoding=DEFAULT_ENCODING) as file_obj: - daq_type, sample_rate = read_metadata(file_obj) - dataframe = pd.read_csv(file_obj) - data = RawData(daq_type, sample_rate, list(dataframe.columns)) - data.rows = dataframe.values.tolist() - return data - except FileNotFoundError: - raise BciPyCoreException(f"\nError loading BciPy RawData. Valid data not found at: {filename}") - - -def read_metadata(file_obj: TextIO) -> Tuple[str, int]: - """Reads the metadata from an open raw data file and retuns the result as - a tuple. Increments the reader. - - Parameters - ---------- - - file_obj : open TextIO object - - Returns - ------- - tuple of daq_type, sample_rate - """ - daq_type = next(file_obj).strip().split(',')[1] - sample_rate = int(float(next(file_obj).strip().split(",")[1])) - return daq_type, sample_rate - - -def write(data: RawData, filename: str): - """Write the given raw data file. - - Parameters - ---------- - - data : raw data object to write - - filename : path to destination file. - """ - with RawDataWriter(filename, data.daq_type, data.sample_rate, - data.columns) as writer: - for row in data.rows: - writer.writerow(row) - - -def settings(filename: str) -> Tuple[str, float, List[str]]: - """Read the daq settings from the given data file - - Parameters - ---------- - - filename : path to the raw data file (csv) - - Returns - ------- - tuple of (acquisition type, sample_rate, columns) - """ - - with RawDataReader(filename) as reader: - return reader.daq_type, reader.sample_rate, reader.columns - - -def sample_data(rows: int = 1000, - ch_names: List[str] = ['ch1', 'ch2', 'ch3'], - daq_type: str = 'SampleDevice', - sample_rate: int = 256, - triggers: List[Tuple[float, str]] = []) -> RawData: - """Creates sample data to be written as a raw_data.csv file. The resulting data has - a column for the timestamp, one for each channel, and a TRG column. - - - rows : number of sample rows to generate - - ch_names : list of channel names - - daq_type : metadata for the device name - - sample_rate : device sample rate in hz - - triggers : List of (timestamp, trigger_value) tuples to be inserted - in the data. - """ - channels = [name for name in ch_names if name != 'TRG'] - columns = [TIMESTAMP_COLUMN] + channels + ['TRG'] - trg_times = dict(triggers) - - data = RawData(daq_type, sample_rate, columns) - - for i in range(rows): - timestamp = i + 1 - channel_data = gen_random_data(low=-1000, - high=1000, - channel_count=len(channels)) - trg = trg_times.get(timestamp, '0.0') - data.append([timestamp] + channel_data + [trg]) - - return data diff --git a/bcipy/helpers/symbols.py b/bcipy/helpers/symbols.py deleted file mode 100644 index dca9feb4c..000000000 --- a/bcipy/helpers/symbols.py +++ /dev/null @@ -1,65 +0,0 @@ -"""Defines helper methods and variables related to input symbols""" -import os -from string import ascii_uppercase -from typing import Callable - -SPACE_CHAR = '_' -BACKSPACE_CHAR = '<' - - -def alphabet(parameters=None, include_path=True, backspace=BACKSPACE_CHAR, space=SPACE_CHAR): - """Alphabet. - - Function used to standardize the symbols we use as alphabet. - - Returns - ------- - array of letters. - """ - if parameters and not parameters['is_txt_stim']: - # construct an array of paths to images - path = parameters['path_to_presentation_images'] - stimulus_array = [] - for stimulus_filename in sorted(os.listdir(path)): - # PLUS.png is reserved for the fixation symbol - if stimulus_filename.endswith( - '.png') and not stimulus_filename.endswith('PLUS.png'): - if include_path: - img = os.path.join(path, stimulus_filename) - else: - img = os.path.splitext(stimulus_filename)[0] - stimulus_array.append(img) - return stimulus_array - - return list(ascii_uppercase) + [backspace, space] - - -def qwerty_order(is_txt_stim: bool = True, - space: str = SPACE_CHAR, - backspace: str = BACKSPACE_CHAR) -> Callable: - """Returns a function that can be used to sort the alphabet symbols - in QWERTY order. Note that sorting only works for text stim. - """ - if not is_txt_stim: - raise NotImplementedError('QWERTY ordering not implemented for images') - - row1 = "QWERTYUIOP" - row2 = f"ASDFGHJKL{backspace}" - row3 = f" ZXCV{space}BNM " - return f"{row1}{row2}{row3}".index - - -def frequency_order( - is_txt_stim: bool = True, - space: str = SPACE_CHAR, - backspace: str = BACKSPACE_CHAR) -> Callable: - """Returns a function that can be used to sort the alphabet symbols - in most frequently used order in the English language. - """ - if not is_txt_stim: - raise NotImplementedError( - 'Frequency ordering not implemented for images') - return f"ETAOINSHRDLCUMWFGYPBVKJXQZ{backspace}{space}".index - - -DEFAULT_SYMBOL_SET = alphabet() diff --git a/bcipy/helpers/task.py b/bcipy/helpers/task.py index 983dec8ec..e7ae64c84 100644 --- a/bcipy/helpers/task.py +++ b/bcipy/helpers/task.py @@ -8,9 +8,10 @@ from bcipy.acquisition.multimodal import ClientManager, ContentType from bcipy.acquisition.record import Record -from bcipy.config import MAX_PAUSE_SECONDS, SESSION_COMPLETE_MESSAGE, SESSION_LOG_FILENAME +from bcipy.config import (MAX_PAUSE_SECONDS, SESSION_COMPLETE_MESSAGE, + SESSION_LOG_FILENAME) +from bcipy.core.stimuli import get_fixation from bcipy.helpers.clock import Clock -from bcipy.helpers.stimuli import get_fixation from bcipy.task.exceptions import InsufficientDataException log = logging.getLogger(SESSION_LOG_FILENAME) @@ -155,7 +156,8 @@ def get_data_for_decision(inquiry_timing: List[Tuple[str, float]], for text, timing in inquiry_timing] # Define the amount of data required for any processing to occur. - data_limit = round((time2 - time1 + poststim) * daq.device_spec.sample_rate) + data_limit = round((time2 - time1 + poststim) * + daq.device_spec.sample_rate) log.info(f'Need {data_limit} records for processing') # Query for raw data @@ -251,7 +253,8 @@ def relative_triggers(inquiry_timing: List[Tuple[str, float]], def _float_val(col: Any) -> float: """Convert marker data to float values so we can put them in a typed np.array. The marker column has type float if it has a 0.0 - value, and would only have type str for a marker value.""" + value, and would only have type str for a marker value. + """ if isinstance(col, str): return 1.0 return float(col) @@ -349,7 +352,8 @@ def pause_on_wait_screen(window, message, color) -> bool: elapsed_seconds = time.time() - pause_start if elapsed_seconds >= MAX_PAUSE_SECONDS: - log.info(f"Pause exceeded the allowed time ({MAX_PAUSE_SECONDS} seconds). Ending task.") + log.info( + f"Pause exceeded the allowed time ({MAX_PAUSE_SECONDS} seconds). Ending task.") return False if keys[0] == 'escape': return False diff --git a/bcipy/helpers/tests/__init__.py b/bcipy/helpers/tests/__init__.py deleted file mode 100644 index aa3dec7fc..000000000 --- a/bcipy/helpers/tests/__init__.py +++ /dev/null @@ -1,3 +0,0 @@ -import sys -from os.path import dirname -sys.path.append(dirname(__file__)) diff --git a/bcipy/helpers/tests/test_acquisition.py b/bcipy/helpers/tests/test_acquisition.py index c72df3a46..3a9c2dddd 100644 --- a/bcipy/helpers/tests/test_acquisition.py +++ b/bcipy/helpers/tests/test_acquisition.py @@ -4,13 +4,13 @@ from bcipy.acquisition.devices import DeviceSpec, DeviceStatus from bcipy.config import DEFAULT_DEVICE_SPEC_FILENAME as spec_name +from bcipy.core.parameters import Parameters from bcipy.helpers.acquisition import (RAW_DATA_FILENAME, StreamType, active_content_types, init_acquisition, init_device, is_stream_type_active, max_inquiry_duration, parse_stream_type, raw_data_filename, server_spec, stream_types) -from bcipy.helpers.parameters import Parameters class TestAcquisition(unittest.TestCase): diff --git a/bcipy/helpers/tests/test_convert.py b/bcipy/helpers/tests/test_convert.py deleted file mode 100644 index 28aade773..000000000 --- a/bcipy/helpers/tests/test_convert.py +++ /dev/null @@ -1,683 +0,0 @@ -"""Tests for data conversion related functionality.""" -import os -import shutil -import tempfile -import unittest -import warnings -from pathlib import Path -from typing import Tuple, Union - -from mne.io import read_raw_bdf, read_raw_edf -from mockito import any as any_value -from mockito import mock, unstub, verify, verifyNoMoreInteractions, when - -import bcipy.acquisition.devices as devices -from bcipy.config import (DEFAULT_ENCODING, DEFAULT_PARAMETERS_FILENAME, - RAW_DATA_FILENAME, TRIGGER_FILENAME) -from bcipy.helpers import convert -from bcipy.helpers.convert import (archive_list, compress, convert_to_bdf, - convert_to_edf, convert_to_mne, decompress, - norm_to_tobii, pyedf_convert, tobii_to_norm) -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.raw_data import RawData, sample_data, write -from bcipy.helpers.triggers import MOCK_TRIGGER_DATA -from bcipy.signal.generator.generator import gen_random_data - - -def create_bcipy_session_artifacts( - write_dir: str, - channels: Union[int, list] = 3, - sample_rate: int = 300, - samples: int = 5000, - filter_settings: dict = { - 'filter_low': 0.5, - 'filter_high': 30, - 'filter_order': 5, - 'notch_filter_frequency': 60, - 'down_sampling_rate': 3 - }, -) -> Tuple[str, RawData, Parameters]: - """Write BciPy session artifacts to a temporary directory. - - This includes a raw data file, trigger file, and a parameters file. - """ - trg_data = MOCK_TRIGGER_DATA - if isinstance(channels, int): - channels = [f'ch{i}' for i in range(channels)] - data = sample_data(ch_names=channels, daq_type='SampleDevice', sample_rate=sample_rate, rows=samples) - devices.register(devices.DeviceSpec('SampleDevice', channels=channels, sample_rate=sample_rate)) - - with open(Path(write_dir, TRIGGER_FILENAME), 'w', encoding=DEFAULT_ENCODING) as trg_file: - trg_file.write(trg_data) - - write(data, Path(write_dir, f'{RAW_DATA_FILENAME}.csv')) - - params = Parameters.from_cast_values(raw_data_name=f'{RAW_DATA_FILENAME}.csv', - trigger_file_name=TRIGGER_FILENAME, - preview_inquiry_length=0.5, - time_fixation=0.5, - time_prompt=0.5, - time_flash=0.5, - # define filter settings - down_sampling_rate=filter_settings['down_sampling_rate'], - notch_filter_frequency=filter_settings['notch_filter_frequency'], - filter_high=filter_settings['filter_high'], - filter_low=filter_settings['filter_low'], - filter_order=filter_settings['filter_order']) - params.save(write_dir, DEFAULT_PARAMETERS_FILENAME) - return trg_data, data, params - - -class TestEDFConvert(unittest.TestCase): - """Tests for EDF data format conversions.""" - - def setUp(self): - self.temp_dir = tempfile.mkdtemp() - _, data, _ = create_bcipy_session_artifacts(self.temp_dir) - self.channels = data.channels - - def tearDown(self): - shutil.rmtree(self.temp_dir) - verifyNoMoreInteractions() - unstub() - - def test_convert_to_edf_defaults(self): - """Test default behavior""" - path = convert_to_edf(self.temp_dir) - self.assertTrue(os.path.exists(path)) - - with warnings.catch_warnings(): - warnings.simplefilter('ignore') - edf = read_raw_edf(path, preload=True) - - self.assertTrue(len(edf.get_data()) > 0) - - for ch_name in self.channels: - self.assertTrue(ch_name in edf.ch_names) - - def test_convert_to_edf_overwrite_false(self): - """Test overwriting fails""" - - convert_to_edf(self.temp_dir) - with self.assertRaises(OSError): - convert_to_edf(self.temp_dir, overwrite=False) - - def test_convert_to_edf_overwrite_true(self): - """Test that overwriting can be configured""" - - convert_to_edf(self.temp_dir) - convert_to_edf(self.temp_dir, overwrite=True) - - def test_convert_to_edf_with_custom_path(self): - """Test creating the EDF using a custom edf path""" - path = convert_to_edf(self.temp_dir, - edf_path=str(Path(self.temp_dir, 'mydata.edf').resolve())) - - self.assertEqual(Path(path).name, 'mydata.edf') - - def test_convert_to_edf_raises_value_error_with_invalid_edfpath(self): - """Test that an value error is raised when the edf path is invalid""" - edf_path = 'invalid.pdf' - with self.assertRaises(ValueError): - convert_to_edf(self.temp_dir, edf_path=edf_path) - - def test_convert_to_edf_with_write_targetness(self): - """Test creating the EDF using targetness for event annotations""" - path = convert_to_edf(self.temp_dir, - write_targetness=True) - - with warnings.catch_warnings(): - warnings.simplefilter('ignore') - edf = read_raw_edf(path, preload=True) - - self.assertTrue('target' in edf.annotations.description) - self.assertTrue('nontarget' in edf.annotations.description) - - def test_convert_to_edf_without_write_targetness(self): - """Test creating the EDF with labels as event annotations""" - path = convert_to_edf(self.temp_dir, - write_targetness=False) - - with warnings.catch_warnings(): - warnings.simplefilter('ignore') - edf = read_raw_edf(path, preload=True) - - self.assertNotIn('target', edf.annotations.description) - self.assertNotIn('nontarget', edf.annotations.description) - self.assertIn('+', edf.annotations.description) - - def test_convert_to_edf_with_pre_filter(self): - """Test creating the EDF with pre-filtering""" - - data = mock() - channels = mock() - fs = 100 - events = mock() - annotation_channels = 1 - return_path = mock() - when(convert).pyedf_convert( - any_value(str), - write_targetness=any_value(bool), - use_event_durations=any_value(bool), - remove_pre_fixation=any_value(bool), - pre_filter=True, - ).thenReturn(( - data, - channels, - fs, - events, - annotation_channels, - 'filter_settings' - )) - when(convert).write_pyedf( - any_value(str), - data, - channels, - fs, - events, - any_value(int), - any_value(bool), - annotation_channels, - any_value(str)).thenReturn(return_path) - path = convert_to_edf(self.temp_dir, - pre_filter=True) - - verify(convert, times=1).pyedf_convert( - any_value(str), - write_targetness=any_value(bool), - use_event_durations=any_value(bool), - remove_pre_fixation=any_value(bool), - pre_filter=True, - ) - verify(convert, times=1).write_pyedf( - any_value(str), - data, - channels, - fs, - events, - any_value(int), - any_value(bool), - annotation_channels, - any_value(str)) - self.assertEqual(path, return_path) - - -class TestBDFConvert(unittest.TestCase): - """Tests for BDF data format conversions.""" - - def setUp(self): - """Override; set up the needed path for load functions.""" - - self.temp_dir = tempfile.mkdtemp() - _, data, _ = create_bcipy_session_artifacts(self.temp_dir) - self.channels = data.channels - - def tearDown(self): - """Override""" - shutil.rmtree(self.temp_dir) - verifyNoMoreInteractions() - unstub() - - def test_convert_to_bdf_defaults(self): - """Test default convert to bdf behavior""" - path = convert_to_bdf(self.temp_dir) - self.assertTrue(os.path.exists(path)) - - with warnings.catch_warnings(): - warnings.simplefilter('ignore') - bdf = read_raw_bdf(path, preload=True) - - self.assertTrue(len(bdf.get_data()) > 0) - - for ch_name in self.channels: - self.assertTrue(ch_name in bdf.ch_names) - - def test_convert_to_bdf_overwrite_false(self): - """Test overwriting fails if not configured""" - - convert_to_bdf(self.temp_dir) - with self.assertRaises(OSError): - convert_to_bdf(self.temp_dir, overwrite=False) - - def test_convert_to_bdf_overwrite_true(self): - """Test that overwriting can be configured""" - - convert_to_bdf(self.temp_dir) - convert_to_bdf(self.temp_dir, overwrite=True) - - def test_convert_to_bdf_with_custom_path(self): - """Test creating the EDF using a custom edf path""" - path = convert_to_bdf(self.temp_dir, - bdf_path=str(Path(self.temp_dir, 'mydata.bdf').resolve())) - - self.assertEqual(Path(path).name, 'mydata.bdf') - - def test_convert_to_bdf_raises_value_error_with_invalid_edfpath(self): - """Test that a value error is raised with the bdf path is invalid""" - bdf_path = 'invalid.pdf' - with self.assertRaises(ValueError): - convert_to_bdf(self.temp_dir, bdf_path=bdf_path) - - def test_convert_to_bdf_with_write_targetness(self): - """Test creating the EDF using targetness for event annotations""" - path = convert_to_bdf(self.temp_dir, - write_targetness=True) - - with warnings.catch_warnings(): - warnings.simplefilter('ignore') - edf = read_raw_bdf(path, preload=True) - - self.assertIn('target', edf.annotations.description) - self.assertIn('nontarget', edf.annotations.description) - - def test_convert_to_bdf_without_write_targetness(self): - """Test creating the EDF with labels as event annotations""" - path = convert_to_bdf(self.temp_dir, - write_targetness=False) - - with warnings.catch_warnings(): - warnings.simplefilter('ignore') - edf = read_raw_bdf(path, preload=True) - - self.assertNotIn('target', edf.annotations.description) - self.assertNotIn('nontarget', edf.annotations.description) - self.assertIn('+', edf.annotations.description) - - def test_convert_to_bdf_with_pre_filter(self): - """Test creating the BDF with pre-filtering""" - - data = mock() - channels = mock() - fs = 100 - events = mock() - annotation_channels = 1 - return_path = mock() - when(convert).pyedf_convert( - any_value(str), - write_targetness=any_value(bool), - use_event_durations=any_value(bool), - remove_pre_fixation=any_value(bool), - pre_filter=True, - ).thenReturn(( - data, - channels, - fs, - events, - annotation_channels, - 'filter_settings' - )) - when(convert).write_pyedf( - any_value(str), - data, - channels, - fs, - events, - any_value(int), - any_value(bool), - annotation_channels, - any_value(str)).thenReturn(return_path) - path = convert_to_bdf(self.temp_dir, - pre_filter=True) - - verify(convert, times=1).pyedf_convert( - any_value(str), - write_targetness=any_value(bool), - use_event_durations=any_value(bool), - remove_pre_fixation=any_value(bool), - pre_filter=True, - ) - verify(convert, times=1).write_pyedf( - any_value(str), - data, - channels, - fs, - events, - any_value(int), - any_value(bool), - annotation_channels, - any_value(str)) - self.assertEqual(path, return_path) - - -class TestPyedfconvert(unittest.TestCase): - - def setUp(self) -> None: - self.temp_dir = tempfile.mkdtemp() - self.sample_rate = 300 - self.filter_settings = { - 'filter_low': 0.5, - 'filter_high': 30, - 'filter_order': 5, - 'notch_filter_frequency': 60, - 'down_sampling_rate': 3 - } - create_bcipy_session_artifacts( - self.temp_dir, - sample_rate=self.sample_rate, - filter_settings=self.filter_settings, - samples=10000) # sample number determines the annotation count, set it high here! - - def tearDown(self) -> None: - shutil.rmtree(self.temp_dir) - verifyNoMoreInteractions() - unstub() - - def test_pyedf_convert_defaults(self): - """Test the pyedf_convert function""" - data, channels, fs, events, annotation_channels, pre_filter = pyedf_convert( - self.temp_dir) - - self.assertTrue(len(data) > 0) - self.assertTrue(len(channels) > 0) - self.assertEqual(fs, self.sample_rate) - self.assertTrue(len(events) > 2) - # see the validate_annotations function for details on how this is calculated - self.assertEqual(annotation_channels, 1) - self.assertFalse(pre_filter) - - def test_pyedf_convert_with_pre_filter(self): - """Test the pyedf_convert function with pre-filtering""" - data, channels, fs, events, annotation_channels, pre_filter = pyedf_convert( - self.temp_dir, pre_filter=True) - - self.assertTrue(len(data) > 0) - self.assertTrue(len(channels) > 0) - self.assertEqual(fs, self.sample_rate / self.filter_settings['down_sampling_rate']) - self.assertTrue(len(events) > 2) - # see the validate_annotations function for details on how this is calculated - # with less samples, the number of annotation channels increases - self.assertEqual(annotation_channels, 2) - self.assertIsInstance(pre_filter, str) - - def test_pyedf_convert_with_write_targetness(self): - """Test the pyedf_convert function with targetness for event annotations""" - data, channels, fs, events, annotation_channels, _ = pyedf_convert( - self.temp_dir, write_targetness=True, remove_pre_fixation=True) - - self.assertTrue(len(data) > 0) - self.assertTrue(len(channels) > 0) - self.assertEqual(fs, self.sample_rate) - self.assertTrue(len(events) > 2) - # see the validate_annotations function for details on how this is calculated - self.assertEqual(annotation_channels, 1) - for event in events: - _, _, label = event - # in this case label and targetness should not be the same - self.assertTrue(label in ['target', 'nontarget']) - - def test_pyedf_convert_without_write_targetness(self): - """Test the pyedf_convert function with labels as event annotations""" - data, channels, fs, events, annotation_channels, _ = pyedf_convert( - self.temp_dir, write_targetness=False) - - self.assertTrue(len(data) > 0) - self.assertTrue(len(channels) > 0) - self.assertEqual(fs, self.sample_rate) - self.assertTrue(len(events) > 2) - # see the validate_annotations function for details on how this is calculated - self.assertEqual(annotation_channels, 1) - for event in events: - _, _, label = event - self.assertTrue(label not in ['target', 'nontarget']) - - def test_pyedf_convert_with_use_event_durations(self): - """Test the pyedf_convert function with event durations""" - data, channels, fs, events, annotation_channels, _ = pyedf_convert( - self.temp_dir, use_event_durations=True) - - self.assertTrue(len(data) > 0) - self.assertTrue(len(channels) > 0) - self.assertEqual(fs, self.sample_rate) - self.assertTrue(len(events) > 2) - # see the validate_annotations function for details on how this is calculated - self.assertEqual(annotation_channels, 1) - for _, duration, _ in events: - self.assertTrue(duration > 0) - - def test_pyedf_convert_without_use_event_durations(self): - """Test the pyedf_convert function without event durations""" - data, channels, fs, events, annotation_channels, _ = pyedf_convert( - self.temp_dir, use_event_durations=False) - - self.assertTrue(len(data) > 0) - self.assertTrue(len(channels) > 0) - self.assertEqual(fs, self.sample_rate) - self.assertTrue(len(events) > 2) - # see the validate_annotations function for details on how this is calculated - self.assertEqual(annotation_channels, 1) - for _, duration, _ in events: - self.assertEqual(duration, 0) - - def test_pyedf_convert_with_remove_pre_fixation(self): - """Test the pyedf_convert function with pre-fixation removal""" - data, channels, fs, events, annotation_channels, _ = pyedf_convert( - self.temp_dir, remove_pre_fixation=True) - - self.assertTrue(len(data) > 0) - self.assertTrue(len(channels) > 0) - self.assertEqual(fs, self.sample_rate) - self.assertTrue(len(events) > 2) - # see the validate_annotations function for details on how this is calculated - self.assertEqual(annotation_channels, 1) - for event in events: - self.assertNotIn('fixation', event) - self.assertNotIn('prompt', event) - - -class TestMNEConvert(unittest.TestCase): - """Test the convert_to_mne function, which converts bcipy RawData into an mne format""" - - def setUp(self): - """Set up the test case with a temporary directory and sample data""" - self.temp_dir = tempfile.mkdtemp() - self.sample_rate = 300 - self.filter_settings = { - 'filter_low': 0.5, - 'filter_high': 30, - 'filter_order': 5, - 'notch_filter_frequency': 60, - 'down_sampling_rate': 3 - } - self.channels = ['timestamp', 'O1', 'O2', 'Pz'] - self.raw_data = RawData('SampleDevice', self.sample_rate, self.channels) - devices.register(devices.DeviceSpec('SampleDevice', channels=self.channels, sample_rate=self.sample_rate)) - - # generate 100 random samples of data - for _ in range(0, 100): - channel_data = gen_random_data(low=-1000, - high=1000, - channel_count=len(self.channels)) - self.raw_data.append(channel_data) - - def tearDown(self): - """Remove the temporary directory and its contents after each test""" - shutil.rmtree(self.temp_dir) - - def test_convert_to_mne_defaults(self): - """Test the convert_to_mne function with default parameters""" - data = convert_to_mne(self.raw_data) - - self.assertTrue(len(data) > 0) - self.assertEqual(data.ch_names, self.channels[1:]) - self.assertEqual(data.info['sfreq'], self.sample_rate) - - def test_convert_to_mne_with_channel_map(self): - """Test the convert_to_mne function with channel mapping""" - # here we know only three channels are generated, using the channel map let's only use the last one - channel_map = [0, 0, 1] - data = convert_to_mne(self.raw_data, channel_map=channel_map) - - self.assertTrue(len(data) > 0) - self.assertTrue(len(data.ch_names) == 1) # this is the main assertion! - self.assertEqual(data.info['sfreq'], self.sample_rate) - - def test_convert_to_mne_with_channel_types(self): - """Test the convert_to_mne function with channel types""" - channel_types = ['eeg', 'eeg', 'seeg'] - data = convert_to_mne(self.raw_data, channel_types=channel_types) - - self.assertTrue(len(data) > 0) - self.assertEqual(data.ch_names, self.channels[1:]) - self.assertEqual(data.info['sfreq'], self.sample_rate) - self.assertTrue(data.get_channel_types()[2] == 'seeg') - - def test_convert_to_mne_with_transform(self): - """Test the convert_to_mne function with a transform""" - multiplier = 2 - - def transform(x, fs): - return x * multiplier, fs - - data = convert_to_mne(self.raw_data, transform=transform, volts=True) - - self.assertTrue(len(data) > 0) - self.assertEqual(data.ch_names, self.channels[1:]) - self.assertEqual(data.info['sfreq'], self.sample_rate) - - # apply the transform to the first data point and compare to data returned - expected_first_data_point = self.raw_data.channel_data[0][0] * multiplier - self.assertTrue(data.get_data()[0][0] == expected_first_data_point) - - def test_convert_to_mne_with_mv_conversion(self): - """Test the convert_to_mne function with a mv conversion""" - data = convert_to_mne(self.raw_data, volts=False) - - self.assertTrue(len(data) > 0) - self.assertEqual(data.ch_names, self.channels[1:]) - self.assertEqual(data.info['sfreq'], self.sample_rate) - - # apply the transform to the first data point and compare to data returned - expected_first_data_point = self.raw_data.channel_data[0][0] * 1e-6 - self.assertTrue(data.get_data()[0][0] == expected_first_data_point) - - def test_convert_to_mne_with_custom_montage(self): - """Test the convert_to_mne function with a custom montage""" - - # see https://mne.tools/stable/auto_tutorials/intro/40_sensor_locations.html - # for more information on montages and available defaults - montage_type = 'biosemi64' - data = convert_to_mne(self.raw_data, montage=montage_type) - - self.assertTrue(len(data) > 0) - self.assertEqual(data.ch_names, self.channels[1:]) - self.assertEqual(data.info['sfreq'], self.sample_rate) - - -class TestCompressionSupport(unittest.TestCase): - - def setUp(self): - self.dir_name = 'test/' - self.tar_file_name = 'test_file' - self.tar_file_full_name = f'{self.tar_file_name}.tar.gz' - self.test_file_name = 'test.text' - with open(self.test_file_name, 'w', encoding=DEFAULT_ENCODING) as fp: - pass - - def tearDown(self): - os.remove(self.test_file_name) - - if os.path.exists(self.tar_file_full_name): - os.remove(self.tar_file_full_name) - - def test_compression_writes_tar_gz_no_extension(self): - # Test with no extension on tar name - compress(self.tar_file_name, [self.test_file_name]) - # Assert correct file was written - self.assertTrue(os.path.exists(self.tar_file_full_name)) - - def test_compression_writes_tar_gz_with_extension(self): - # Test with extension on tar name - compress(self.tar_file_full_name, [self.test_file_name]) - # Assert correct file was written - self.assertTrue(os.path.exists(self.tar_file_full_name)) - - def test_decompression_extracts_file_no_extension(self): - # Test with no extension on tar name - compress(self.tar_file_name, [self.test_file_name]) - decompress(self.tar_file_name, ".") - self.assertTrue(os.path.exists(self.test_file_name)) - - def test_decompression_extracts_file_with_extension(self): - # Test with extension on tar name - compress(self.tar_file_name, [self.test_file_name]) - decompress(self.tar_file_full_name, ".") - self.assertTrue(os.path.exists(self.test_file_name)) - - def test_file_not_found_error_thrown_on_compression(self): - garbage_name = 'not_possible_to_exist.biz' - with self.assertRaises(FileNotFoundError): - compress(self.tar_file_name, [garbage_name]) - - def test_file_list_returns_compressed_file_name_no_extension(self): - # Test with no extension on tar name - compress(self.tar_file_name, [self.test_file_name]) - tar_list = archive_list(self.tar_file_name) - self.assertTrue(tar_list[0] == self.test_file_name) - - def test_file_list_returns_compressed_file_name_with_extension(self): - # Test with extension on tar name - compress(self.tar_file_name, [self.test_file_name]) - tar_list = archive_list(self.tar_file_full_name) - self.assertTrue(tar_list[0] == self.test_file_name) - - -class TestConvertTobii(unittest.TestCase): - - def test_tobii_to_norm(self): - """Test the tobii_to_norm function""" - tobii_data = (0.5, 0.5) # center of screen in tobii coordinates - excepted_norm_data = (0, 0) # center of screen in norm coordinates - norm_data = tobii_to_norm(tobii_data) - self.assertEqual(norm_data, excepted_norm_data) - - tobii_data = (0, 0) # top left of screen in tobii coordinates - excepted_norm_data = (-1, 1) # top left of screen in norm coordinates - norm_data = tobii_to_norm(tobii_data) - self.assertEqual(norm_data, excepted_norm_data) - - tobii_data = (1, 1) # bottom right of screen in tobii coordinates - excepted_norm_data = (1, -1) # bottom right of screen in norm coordinates - norm_data = tobii_to_norm(tobii_data) - self.assertEqual(norm_data, excepted_norm_data) - - def test_tobii_to_norm_raises_error_with_invalid_units(self): - """Test the tobii_to_norm function raises an error with invalid units""" - tobii_data = (-1, 1) # invalid tobii coordinates - with self.assertRaises(AssertionError): - tobii_to_norm(tobii_data) - - tobii_data = (1, 11) # invalid tobii coordinates - - with self.assertRaises(AssertionError): - tobii_to_norm(tobii_data) - - def test_norm_to_tobii(self): - """Test the norm_to_tobii function""" - norm_data = (0, 0) # center of screen in norm coordinates - excepted_tobii_data = (0.5, 0.5) # center of screen in tobii coordinates - tobii_data = norm_to_tobii(norm_data) - self.assertEqual(tobii_data, excepted_tobii_data) - - norm_data = (-1, 1) # top left of screen in norm coordinates - excepted_tobii_data = (0, 0) # top left of screen in tobii coordinates - tobii_data = norm_to_tobii(norm_data) - self.assertEqual(tobii_data, excepted_tobii_data) - - norm_data = (1, -1) # bottom right of screen in norm coordinates - excepted_tobii_data = (1, 1) # bottom right of screen in tobii coordinates - tobii_data = norm_to_tobii(norm_data) - self.assertEqual(tobii_data, excepted_tobii_data) - - def test_norm_to_tobii_raises_error_with_invalid_units(self): - """Test the norm_to_tobii function raises an error with invalid units""" - norm_data = (-1.1, 1) - with self.assertRaises(AssertionError): - norm_to_tobii(norm_data) - - norm_data = (1, 1.1) - with self.assertRaises(AssertionError): - norm_to_tobii(norm_data) - - -if __name__ == '__main__': - unittest.main() diff --git a/bcipy/helpers/tests/test_copy_phrase_wrapper.py b/bcipy/helpers/tests/test_copy_phrase_wrapper.py index f04066d5e..9bfc39af9 100644 --- a/bcipy/helpers/tests/test_copy_phrase_wrapper.py +++ b/bcipy/helpers/tests/test_copy_phrase_wrapper.py @@ -1,7 +1,7 @@ import unittest +from bcipy.core.symbols import DEFAULT_SYMBOL_SET from bcipy.helpers.copy_phrase_wrapper import CopyPhraseWrapper -from bcipy.helpers.symbols import alphabet from bcipy.language.model.uniform import UniformLanguageModel from bcipy.task.data import EvidenceType @@ -10,12 +10,11 @@ class TestCopyPhraseWrapper(unittest.TestCase): """Test CopyPhraseWrapper""" def test_valid_letters(self): - alp = alphabet() cp = CopyPhraseWrapper( min_num_inq=1, max_num_inq=50, lmodel=None, - alp=alp, + alp=DEFAULT_SYMBOL_SET, task_list=[("HELLO_WORLD", "HE")], is_txt_stim=True, evidence_names=[EvidenceType.LM, EvidenceType.ERP], @@ -104,13 +103,15 @@ def test_valid_letters(self): ["nontarget", "nontarget"]) def test_init_series(self): - alp = alphabet() + + lmodel = UniformLanguageModel() + lmodel.set_symbol_set(DEFAULT_SYMBOL_SET) copy_phrase_task = CopyPhraseWrapper( min_num_inq=1, max_num_inq=50, - lmodel=UniformLanguageModel(symbol_set=alp), - alp=alp, + lmodel=lmodel, + alp=DEFAULT_SYMBOL_SET, task_list=[("HELLO_WORLD", "HE")], is_txt_stim=True, evidence_names=[EvidenceType.LM, EvidenceType.ERP], diff --git a/bcipy/helpers/tests/test_language_model.py b/bcipy/helpers/tests/test_language_model.py index c3e367d6f..65c315c32 100644 --- a/bcipy/helpers/tests/test_language_model.py +++ b/bcipy/helpers/tests/test_language_model.py @@ -1,8 +1,8 @@ """Unit test for language model helper""" import unittest - from collections import Counter -from bcipy.helpers.language_model import norm_domain, with_min_prob, histogram + +from bcipy.helpers.language_model import histogram, norm_domain, with_min_prob class TestLanguageModelRelated(unittest.TestCase): diff --git a/bcipy/helpers/tests/test_offset.py b/bcipy/helpers/tests/test_offset.py index 58a240b95..4ed0944ae 100644 --- a/bcipy/helpers/tests/test_offset.py +++ b/bcipy/helpers/tests/test_offset.py @@ -1,25 +1,21 @@ -import unittest import shutil +import tempfile +import unittest import zipfile from pathlib import Path -import tempfile -import pytest +import pytest from matplotlib import pyplot as plt +from mockito import unstub, verify, when -from mockito import when, unstub, verify - -from bcipy.helpers.offset import ( - calculate_latency, - sample_to_seconds, - extract_data_latency_calculation, - sample_rate_diffs, - lsl_timestamp_diffs -) -from bcipy.helpers.load import load_raw_data -from bcipy.helpers.raw_data import RawData -from bcipy.helpers.triggers import trigger_decoder, TriggerType from bcipy.config import RAW_DATA_FILENAME, TRIGGER_FILENAME +from bcipy.core.raw_data import RawData +from bcipy.core.triggers import TriggerType, trigger_decoder +from bcipy.helpers.offset import (calculate_latency, + extract_data_latency_calculation, + lsl_timestamp_diffs, sample_rate_diffs, + sample_to_seconds) +from bcipy.io.load import load_raw_data pwd = Path(__file__).absolute().parent input_folder = pwd / "resources/mock_offset/time_test_data/" @@ -42,7 +38,8 @@ def setUp(self) -> None: remove_pre_fixation=False, exclusion=[TriggerType.FIXATION], device_type='EEG') - self.triggers = list(zip(trigger_label, trigger_targetness, trigger_time)) + self.triggers = list( + zip(trigger_label, trigger_targetness, trigger_time)) self.diode_channel = 'TRG' self.stim_number = 10 @@ -66,7 +63,8 @@ def test_sample_to_seconds_throws_error_on_zero_args(self): def test_extract_data_latency_calculation(self): static_offset = 0.0 recommend = False - resp = extract_data_latency_calculation(self.tmp_dir, recommend, static_offset) + resp = extract_data_latency_calculation( + self.tmp_dir, recommend, static_offset) self.assertIsInstance(resp[0], RawData) self.assertEqual(resp[1], self.triggers) self.assertEqual(resp[2], static_offset) @@ -74,7 +72,8 @@ def test_extract_data_latency_calculation(self): def test_extract_data_latency_calculation_resets_static_offset_on_recommend(self): static_offset = 1.0 recommend = True - resp = extract_data_latency_calculation(self.tmp_dir, recommend, static_offset) + resp = extract_data_latency_calculation( + self.tmp_dir, recommend, static_offset) self.assertIsInstance(resp[0], RawData) self.assertEqual(resp[1], self.triggers) self.assertNotEqual(resp[2], static_offset) diff --git a/bcipy/helpers/tests/test_system_utils.py b/bcipy/helpers/tests/test_system_utils.py index 29dfe9291..322d086e2 100644 --- a/bcipy/helpers/tests/test_system_utils.py +++ b/bcipy/helpers/tests/test_system_utils.py @@ -1,15 +1,13 @@ -import unittest -from bcipy.helpers.system_utils import ( - is_connected, - is_battery_powered, - is_screen_refresh_rate_low, - get_screen_info, - ScreenInfo, -) import socket +import unittest + import psutil +from mockito import any, mock, verify, when from pyglet import canvas -from mockito import any, when, mock, verify + +from bcipy.helpers.utils import (ScreenInfo, get_screen_info, + is_battery_powered, is_connected, + is_screen_refresh_rate_low) class TestSystemUtilsAlerts(unittest.TestCase): @@ -17,12 +15,14 @@ class TestSystemUtilsAlerts(unittest.TestCase): def test_is_connected_true(self): """Test that a computer connected to the internet returns True.""" mock_conn = mock() - when(socket).create_connection(address=any, timeout=any).thenReturn(mock_conn) + when(socket).create_connection( + address=any, timeout=any).thenReturn(mock_conn) self.assertTrue(is_connected()) def test_is_connected_false(self): """Test that a computer not connected to the internet returns False.""" - when(socket).create_connection(address=any, timeout=any).thenRaise(OSError) + when(socket).create_connection( + address=any, timeout=any).thenRaise(OSError) self.assertFalse(is_connected()) def test_is_battery_powered_true(self): diff --git a/bcipy/helpers/tests/test_validate.py b/bcipy/helpers/tests/test_validate.py index 0c7c6a8f6..47164370e 100644 --- a/bcipy/helpers/tests/test_validate.py +++ b/bcipy/helpers/tests/test_validate.py @@ -1,13 +1,11 @@ import unittest from bcipy.config import DEFAULT_EXPERIMENT_ID +from bcipy.exceptions import (InvalidExperimentException, + InvalidFieldException, + UnregisteredExperimentException, + UnregisteredFieldException) from bcipy.helpers.validate import validate_experiment, validate_experiments -from bcipy.exceptions import ( - InvalidExperimentException, - InvalidFieldException, - UnregisteredExperimentException, - UnregisteredFieldException, -) class TestValidateExperiment(unittest.TestCase): diff --git a/bcipy/helpers/tests/test_visualization.py b/bcipy/helpers/tests/test_visualization.py index e285a929d..5cb137e39 100644 --- a/bcipy/helpers/tests/test_visualization.py +++ b/bcipy/helpers/tests/test_visualization.py @@ -1,15 +1,15 @@ -import unittest -import tempfile import shutil +import tempfile +import unittest from pathlib import Path -from mockito import when, any, verify, unstub, mock +from mockito import any, mock, unstub, verify, when -from bcipy.helpers.visualization import visualize_session_data -from bcipy.helpers import visualization -from bcipy.helpers.raw_data import RawData -from bcipy.helpers.load import load_json_parameters from bcipy.config import DEFAULT_PARAMETERS_PATH +from bcipy.core.raw_data import RawData +from bcipy.helpers import visualization +from bcipy.helpers.visualization import visualize_session_data +from bcipy.io.load import load_json_parameters class TestVisualizeSessionData(unittest.TestCase): @@ -17,7 +17,8 @@ class TestVisualizeSessionData(unittest.TestCase): def setUp(self): self.tmp_dir = str(Path(tempfile.mkdtemp())) - self.parameters = load_json_parameters(DEFAULT_PARAMETERS_PATH, value_cast=True) + self.parameters = load_json_parameters( + DEFAULT_PARAMETERS_PATH, value_cast=True) self.raw_data_mock = mock() self.raw_data_mock.daq_type = 'DSI-24' self.raw_data_mock.sample_rate = 300 @@ -33,7 +34,8 @@ def test_visualize_session_data(self): trigger_label_mock = ['target', 'nontarget'] show = True when(RawData).load(any()).thenReturn(self.raw_data_mock) - when(visualization).analysis_channels(any(), any()).thenReturn(self.channel_map_mock) + when(visualization).analysis_channels( + any(), any()).thenReturn(self.channel_map_mock) when(visualization).trigger_decoder( offset=any(), trigger_path=any(), @@ -82,7 +84,8 @@ def test_visualize_session_data_with_no_valid_targets(self): trigger_label_mock = ['nontarget', 'nontarget'] show = False when(RawData).load(any()).thenReturn(self.raw_data_mock) - when(visualization).analysis_channels(any(), any()).thenReturn(self.channel_map_mock) + when(visualization).analysis_channels( + any(), any()).thenReturn(self.channel_map_mock) when(visualization).trigger_decoder( offset=any(), trigger_path=any(), @@ -100,7 +103,8 @@ def test_visualize_session_data_with_no_valid_nontargets(self): trigger_label_mock = ['target', 'target'] show = False when(RawData).load(any()).thenReturn(self.raw_data_mock) - when(visualization).analysis_channels(any(), any()).thenReturn(self.channel_map_mock) + when(visualization).analysis_channels( + any(), any()).thenReturn(self.channel_map_mock) when(visualization).trigger_decoder( offset=any(), trigger_path=any(), @@ -118,7 +122,8 @@ def test_visualize_session_data_with_invalid_timing(self): trigger_label_mock = ['target', 'nontarget'] show = False when(RawData).load(any()).thenReturn(self.raw_data_mock) - when(visualization).analysis_channels(any(), any()).thenReturn(self.channel_map_mock) + when(visualization).analysis_channels( + any(), any()).thenReturn(self.channel_map_mock) when(visualization).trigger_decoder( offset=any(), trigger_path=any(), diff --git a/bcipy/helpers/triggers.py b/bcipy/helpers/triggers.py deleted file mode 100644 index 47624ffc3..000000000 --- a/bcipy/helpers/triggers.py +++ /dev/null @@ -1,537 +0,0 @@ -import logging -import os -from enum import Enum -from typing import Callable, Dict, Iterable, List, NamedTuple, Optional, Tuple - -from psychopy import core, visual - -from bcipy.config import DEFAULT_ENCODING, SESSION_LOG_FILENAME -from bcipy.helpers.clock import Clock -from bcipy.exceptions import BciPyCoreException -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.stimuli import resize_image - -log = logging.getLogger(SESSION_LOG_FILENAME) - -NONE_VALUES = ['0', '0.0'] - -CALIBRATION_IMAGE_PATH = 'bcipy/static/images/testing/white.png' -MOCK_TRIGGER_DATA = '''starting_offset offset -3635340.451487373 -P prompt 3635343.155564679 -+ fixation 3635344.159978495 -O nontarget 3635344.663714144 -Z nontarget 3635344.917679911 -B nontarget 3635345.172036632 -N nontarget 3635345.425718764 -K nontarget 3635345.679572615 -U nontarget 3635345.932683132 -J nontarget 3635346.186251469 -P target 3635346.439412578 -_ nontarget 3635346.692164597 -T nontarget 3635346.946281828 -daq_sample_offset system 293.6437802789733 -''' - - -class CalibrationType(Enum): - """Calibration Type. - - Enum to define the supported calibration trigger types. - """ - TEXT = 'text' - IMAGE = 'image' - - @classmethod - def list(cls): - """Returns all enum values as a list""" - return list(map(lambda c: c.value, cls)) - - -class TriggerCallback: - timing: Optional[Tuple[str, float]] = None - first_time: bool = True - - def callback(self, clock: Clock, stimuli: str) -> None: - if self.first_time: - self.timing = (stimuli, clock.getTime()) - self.first_time = False - - def reset(self): - self.timing = None - self.first_time = True - - -def _calibration_trigger(experiment_clock: Clock, - trigger_type: str = CalibrationType.TEXT.value, - trigger_name: str = 'calibration', - trigger_time: float = 1, - display=None, - on_trigger=None) -> Tuple[str, float]: - """Calibration Trigger. - - Outputs triggers for the purpose of calibrating data and stimuli. - This is an ongoing difficulty between OS, DAQ devices and stimuli type. This - code aims to operationalize the approach to finding the correct DAQ samples in - relation to our trigger code. - - PARAMETERS - --------- - experiment_clock(clock): clock with getTime() method, which is used in the code - to report timing of stimuli - trigger_type(string): type of trigger that is desired (text, image, etc) - trigger_name(string): name of the trigger used for callbacks / labeling - trigger_time(float): time to display the trigger. Can also be used as a buffer. - display(DisplayWindow): a window that can display stimuli. Currently, a Psychopy window. - on_trigger(function): optional callback; if present gets called - when the calibration trigger is fired; accepts a single - parameter for the timing information. - Return: - timing(array): timing values for the calibration triggers to be written to trigger file or - used to calculate offsets. - """ - trigger_callback = TriggerCallback() - - # catch invalid trigger types - if trigger_type not in CalibrationType.list(): - msg = f'Trigger type=[{trigger_type}] not implemented' - log.exception(msg) - raise BciPyCoreException(msg) - - if not display: - msg = f'Calibration type=[{trigger_type}] requires a display' - log.exception(msg) - raise BciPyCoreException(msg) - - if trigger_type == CalibrationType.IMAGE.value: - calibration_box = visual.ImageStim( - win=display, - image=CALIBRATION_IMAGE_PATH, - pos=(-.5, -.5), - mask=None, - ori=0.0) - calibration_box.size = resize_image(CALIBRATION_IMAGE_PATH, display.size, 0.75) - - display.callOnFlip(trigger_callback.callback, experiment_clock, trigger_name) - if on_trigger is not None: - display.callOnFlip(on_trigger, trigger_name) - - calibration_box.draw() - display.flip() - - elif trigger_type == CalibrationType.TEXT.value: - calibration_text = visual.TextStim(display, text='') - - display.callOnFlip(trigger_callback.callback, experiment_clock, - trigger_name) - if on_trigger is not None: - display.callOnFlip(on_trigger, trigger_name) - - calibration_text.draw() - display.flip() - - core.wait(trigger_time) - if trigger_callback.timing is None: - log.warning(f'No trigger found for [{trigger_name}]') - return trigger_name, 0.0 - return trigger_callback.timing - - -def trigger_durations(params: Parameters) -> Dict[str, float]: - """Duration for each type of trigger given in seconds.""" - return { - 'offset': 0.0, - 'preview': params['preview_inquiry_length'], - 'fixation': params['time_fixation'], - 'prompt': params['time_prompt'], - 'nontarget': params['time_flash'], - 'target': params['time_flash'] - } - - -class TriggerType(Enum): - """ - Enum for the primary types of Triggers. - """ - - NONTARGET = "nontarget" - TARGET = "target" - FIXATION = "fixation" - PROMPT = "prompt" - SYSTEM = "system" - OFFSET = "offset" - EVENT = "event" - PREVIEW = "preview" - ARTIFACT = "artifact" - - @classmethod - def list(cls) -> List[str]: - """Returns all enum values as a list""" - return list(map(lambda c: c.value, cls)) - - @classmethod - def pre_fixation(cls) -> List['TriggerType']: - """Returns the subset of TriggerTypes that occur before and including - the FIXATION trigger.""" - return [ - TriggerType.FIXATION, TriggerType.PROMPT, TriggerType.SYSTEM, - TriggerType.OFFSET - ] - - def __str__(self) -> str: - return f'{self.value}' - - -class Trigger(NamedTuple): - """ - Object that encompasses data for a single trigger instance. - """ - - label: str - type: TriggerType - time: float - - def __repr__(self): - return f'Trigger: label=[{self.label}] type=[{self.type}] time=[{self.time}]' - - def with_offset(self, offset: float): - """Construct a copy of this Trigger with the offset adjusted.""" - return Trigger(self.label, self.type, self.time + offset) - - @classmethod - def from_list(cls, lst: List[str]): - """Constructs a Trigger from a serialized representation. - - Parameters - ---------- - lst - serialized representation [label, type, stamp] - """ - assert len(lst) == 3, "Input must have a label, type, and stamp" - return cls(lst[0], TriggerType(lst[1]), float(lst[2])) - - -class FlushFrequency(Enum): - """ - Enum that defines how often list of Triggers will be written and dumped. - """ - - EVERY = "flush after every trigger addition" - END = "flush at end of session" - - -def read_data(lines: Iterable[str]) -> List[Trigger]: - """Read raw trigger data from the given source. - - Parameters - ---------- - data - iterable object where each item is a str with data for a single - trigger. - - Returns - ------- - list of all Triggers in the data. - """ - triggers = [] - for i, line in enumerate(lines): - try: - trg = Trigger.from_list(line.split()) - triggers.append(trg) - except (AssertionError, ValueError) as trg_error: - raise BciPyCoreException( - f'Error reading trigger from line {i+1}: {trg_error}' - ) from trg_error - return triggers - - -def offset_label(device_type: Optional[str] = None, prefix: str = 'starting_offset') -> str: - """Compute the offset label for the given device. - """ - if not device_type or device_type == 'EEG': - return prefix - return f"{prefix}_{device_type}" - - -def offset_device(label: str, prefix: str = 'starting_offset') -> str: - """Given an label, determine the device type""" - assert label.startswith( - prefix), "Label must start with the given prefix" - try: - idx = label.index('_', len(prefix)) - return label[idx + 1:] - except ValueError: - return 'EEG' - - -def starting_offsets_by_device( - triggers: List[Trigger], - device_types: Optional[List[str]] = None) -> Dict[str, Trigger]: - """Returns a dict of starting_offset triggers keyed by device type. - - If device_types are provided, an entry is created for each one, using a - default offset of 0.0 if a match is not found. - """ - offset_triggers = {} - for trg in triggers: - if trg.type == TriggerType.OFFSET: - device_type = offset_device(trg.label) - offset_triggers[device_type] = trg - - if device_types: - data = {} - for device_type in device_types: - data[device_type] = offset_triggers.get( - device_type, - Trigger(offset_label(device_type), TriggerType.OFFSET, 0.0)) - return data - return offset_triggers - - -def find_starting_offset(triggers: List[Trigger], - device_type: Optional[str] = None) -> Trigger: - """Given a list of raw trigger data, determine the starting offset for the - given device. The returned trigger has the timestamp of the first sample - recorded for the device. - - If no device is provided the EEG offset will be used. If there are - no offset triggers in the given data a Trigger with offset of 0.0 will be - returned. - - Parameters - ---------- - triggers - list of trigger data; should include Triggers of - TriggerType.OFFSET - device_type - each device will generally have a different offset. This - parameter is used to determine which trigger to use. If not given - the EEG offset will be used by default. Ex. 'EYETRACKER' - Returns - ------- - The Trigger for the first matching offset for the given device, or a - Trigger with offset of 0.0 if a matching offset was not found. - """ - label = offset_label(device_type) - for trg in triggers: - if trg.type == TriggerType.OFFSET and trg.label == label: - return trg - log.info(f"Offset not found (device_type: {device_type}); using 0.0") - return Trigger(label, TriggerType.OFFSET, 0.0) - - -def read(path: str) -> List[Trigger]: - """Read all Triggers from the given text file. - - Parameters - ---------- - path - trigger (.txt) file to read - Returns - ------- - triggers - """ - if not path.endswith('.txt') or not os.path.exists(path): - raise FileNotFoundError( - f'Valid triggers .txt file not found at [{path}].') - with open(path, encoding=DEFAULT_ENCODING) as raw_txt: - triggers = read_data(raw_txt) - return triggers - - -def apply_offsets(triggers: List[Trigger], - starting_offset: Trigger, - static_offset: float = 0.0) -> List[Trigger]: - """Returns a list of triggers with timestamps adjusted relative to the - device start time. Offset triggers are filtered out if present. - - Parameters - ---------- - triggers - list of triggers - starting_offset - offset from the device start time. - static_offset - the measured static system offset - - Returns - ------- - a list of triggers with timestamps relative to the starting_offset - """ - total_offset = starting_offset.time + static_offset - return [ - trg.with_offset(total_offset) for trg in triggers - if trg.type != TriggerType.OFFSET - ] - - -def exclude_types(triggers: List[Trigger], - types: Optional[List[TriggerType]] = None) -> List[Trigger]: - """Filter the list of triggers to exclude the provided types""" - if not types: - return triggers - return [trg for trg in triggers if trg.type not in types] - - -class TriggerHandler: - """ - Class that contains methods to work with Triggers, including adding and - writing triggers and loading triggers from a txt file. - """ - - encoding = DEFAULT_ENCODING - - def __init__(self, - path: str, - file_name: str, - flush: FlushFrequency): - self.path = path - self.file_name = f'{file_name}.txt' if not file_name.endswith('.txt') else file_name - self.flush = flush - self.triggers: List[Trigger] = [] - self.file_path = f'{self.path}/{self.file_name}' - self.flush = flush - - if os.path.exists(self.file_name): - raise Exception(f"[{self.file_name}] already exists, any writing " - "will overwrite data in the existing file.") - - self.file = open(self.file_path, 'w+', encoding=self.encoding) - - def close(self) -> None: - """Close. - - Ensures all data is written and file is closed properly. - """ - self.write() - self.file.close() - - def write(self) -> None: - """ - Writes current Triggers in self.triggers[] to .txt file in self.file_name. - File writes in the format "label, targetness, time". - """ - - for trigger in self.triggers: - self.file.write(f'{trigger.label} {trigger.type.value} {trigger.time}\n') - - self.triggers = [] - - @staticmethod - def read_text_file(path: str) -> Tuple[List[Trigger], float]: - """Read Triggers from the given text file. - Parameters - ---------- - path - trigger (.txt) file to read - Returns - ------- - triggers, offset - """ - triggers = read(path) - offset = find_starting_offset(triggers) - triggers = exclude_types(triggers, [TriggerType.SYSTEM]) - return triggers, offset.time - - @staticmethod - def load(path: str, - offset: float = 0.0, - exclusion: Optional[List[TriggerType]] = None, - device_type: Optional[str] = None) -> List[Trigger]: - """ - Loads a list of triggers from a .txt of triggers. - - Exclusion based on type only (ex. exclusion=[TriggerType.Fixation]) - - 1. Checks if .txt file exists at path - 2. Loads the triggers data as a list of lists - 3. If offset provided, adds it to the time as float - 4. If exclusion provided, filters those triggers - 5. Casts all loaded and modified triggers to Trigger - 6. Returns as a List[Triggers] - - Parameters - ---------- - path (str): name or file path of .txt trigger file to be loaded. - Input string must include file extension (.txt). - offset (Optional float): if desired, time offset for all loaded triggers, - positive number for adding time, negative number for subtracting time. - exclusion (Optional List[TriggerType]): if desired, list of TriggerType's - to be removed from the loaded trigger list. - device_type : optional; if specified looks for the starting_offset for - a given device; default is to use the EEG offset. - - Returns - ------- - List of Triggers from loaded .txt file with desired modifications - """ - excluded_types = exclusion or [] - triggers = read(path) - starting_offset = find_starting_offset(triggers, device_type) - return apply_offsets(exclude_types(triggers, excluded_types), - starting_offset, - static_offset=offset) - - def add_triggers(self, triggers: List[Trigger]) -> List[Trigger]: - """ - Adds provided list of Triggers to self.triggers. - - Parameters - ---------- - triggers (List[Triggers]): list of Trigger objects to be added to the - handler's list of Triggers (self.triggers). - - Returns - ------- - Returns list of Triggers currently part of Handler - """ - self.triggers.extend(triggers) - - if self.flush is FlushFrequency.EVERY: - self.write() - - return self.triggers - - -def convert_timing_triggers(timing: List[Tuple[str, float]], target_stimuli: str, - trigger_type: Callable) -> List[Trigger]: - """Convert Stimuli Times to Triggers. - - Using the stimuli presentation times provided by the display, convert them into BciPy Triggers. - """ - return [ - Trigger(symbol, trigger_type(symbol, target_stimuli, i), time) - for i, (symbol, time) in enumerate(timing) - ] - - -def trigger_decoder( - trigger_path: str, - remove_pre_fixation: bool = True, - offset: float = 0.0, - exclusion: Optional[List[TriggerType]] = None, - device_type: Optional[str] = None, - apply_starting_offset: bool = True) -> Tuple[list, list, list]: - """Trigger Decoder. - - Given a path to trigger data, this method loads valid Triggers and returns their type, timing and label. - - Parameters - ---------- - trigger_path: path to triggers file - remove_pre_fixation: boolean to determine whether any stimuli before a fixation + system should be removed - offset: static offset value to apply to triggers. - exclusion: any TriggerTypes to be filtered from data returned - device_type: used to determine which starting_offset value to use; if - a 'starting_offset' trigger is found it will be applied. - apply_starting_offset: if False, does not apply the starting offset for - the given device_type. - Returns - ------- - tuple: trigger_type, trigger_timing, trigger_label - """ - excluded_types = exclusion or [] - excluded_types += TriggerType.pre_fixation() if remove_pre_fixation else [ - TriggerType.SYSTEM - ] - - triggers = read(trigger_path) - starting_offset = Trigger('', TriggerType.OFFSET, 0.0) - if apply_starting_offset: - starting_offset = find_starting_offset(triggers, device_type) - - filtered = exclude_types(triggers, excluded_types) - corrected = apply_offsets(filtered, starting_offset, static_offset=offset) - - labels, types, times = zip(*corrected) - return list(map(str, types)), list(times), list(labels) diff --git a/bcipy/helpers/system_utils.py b/bcipy/helpers/utils.py similarity index 97% rename from bcipy/helpers/system_utils.py rename to bcipy/helpers/utils.py index c423dde4a..98cbd8254 100644 --- a/bcipy/helpers/system_utils.py +++ b/bcipy/helpers/utils.py @@ -1,6 +1,7 @@ # mypy: disable-error-code="import-untyped" """Utilities for system information and general functionality that may be -shared across modules.""" +shared across modules. +""" import importlib import logging import os @@ -23,6 +24,7 @@ class ScreenInfo(NamedTuple): + """Screen information including width, height, and refresh rate.""" width: int height: int rate: float @@ -52,7 +54,8 @@ def is_battery_powered() -> bool: ------- True if the computer is currently running on battery power. This can impact the performance of hardware (ex. GPU) needed for BciPy operation by entering - power saving operations.""" + power saving operations. + """ return psutil.sensors_battery( ) and not psutil.sensors_battery().power_plugged @@ -79,7 +82,8 @@ def git_dir() -> Optional[str]: """Git Directory. Returns the root directory with the .git folder. If this source code - was not checked out from scm, answers None.""" + was not checked out from scm, answers None. + """ # Relative to current file; may need to be modified if method is moved. git_root = Path(os.path.abspath(__file__)).parent.parent.parent @@ -143,7 +147,7 @@ def get_screen_info(stim_screen: Optional[int] = None) -> ScreenInfo: Returns ------- ScreenInfo(width, height, rate) - """ + """ if stim_screen: screen = pyglet.canvas.get_display().get_screens()[stim_screen] else: @@ -285,7 +289,6 @@ def log_to_stdout(): """Set logging to stdout. Useful for demo scripts. https://stackoverflow.com/questions/14058453/making-python-loggers-output-all-messages-to-stdout-in-addition-to-log-file """ - root = logging.getLogger() root.setLevel(logging.DEBUG) @@ -309,7 +312,8 @@ def wrap(*args, **kwargs): time1 = time.perf_counter() response = func(*args, **kwargs) time2 = time.perf_counter() - log.info('{:s} method took {:0.4f}s to execute'.format(func.__name__, (time2 - time1))) + log.info('{:s} method took {:0.4f}s to execute'.format( + func.__name__, (time2 - time1))) return response return wrap diff --git a/bcipy/helpers/validate.py b/bcipy/helpers/validate.py index 7e6e75520..be71f37e7 100644 --- a/bcipy/helpers/validate.py +++ b/bcipy/helpers/validate.py @@ -1,17 +1,15 @@ import os -from bcipy.config import ( - DEFAULT_EXPERIMENT_PATH, - DEFAULT_FIELD_PATH, - EXPERIMENT_FILENAME, - FIELD_FILENAME) -from bcipy.helpers.load import load_experiments, load_fields -from bcipy.helpers.system_utils import is_battery_powered, is_connected, is_screen_refresh_rate_low -from bcipy.exceptions import (InvalidFieldException, - InvalidExperimentException, +from bcipy.config import (DEFAULT_EXPERIMENT_PATH, DEFAULT_FIELD_PATH, + EXPERIMENT_FILENAME, FIELD_FILENAME) +from bcipy.exceptions import (InvalidExperimentException, + InvalidFieldException, UnregisteredExperimentException, UnregisteredFieldException) from bcipy.gui.alert import confirm +from bcipy.helpers.utils import (is_battery_powered, is_connected, + is_screen_refresh_rate_low) +from bcipy.io.load import load_experiments, load_fields from bcipy.task.orchestrator.protocol import validate_protocol_string @@ -78,7 +76,8 @@ def _validate_experiment_fields(experiment_fields, fields): try: fields[field_name] except KeyError: - raise UnregisteredFieldException(f'Field [{field}] is not registered in [{fields}]') + raise UnregisteredFieldException( + f'Field [{field}] is not registered in [{fields}]') try: field[field_name]['required'] @@ -96,7 +95,8 @@ def validate_field_data_written(path: str, file_name: str) -> bool: experiment_data_path = f'{path}/{file_name}' if os.path.isfile(experiment_data_path): return True - raise InvalidFieldException(f'Experimental field data expected at path=[{experiment_data_path}] but not found.') + raise InvalidFieldException( + f'Experimental field data expected at path=[{experiment_data_path}] but not found.') def validate_experiments(experiments, fields) -> bool: diff --git a/bcipy/helpers/visualization.py b/bcipy/helpers/visualization.py index 8f4c14a3e..96ff982f4 100644 --- a/bcipy/helpers/visualization.py +++ b/bcipy/helpers/visualization.py @@ -9,25 +9,23 @@ import numpy as np import pandas as pd import seaborn as sns - from matplotlib.figure import Figure from matplotlib.patches import Ellipse from mne import Epochs -from mne.io import read_raw_edf from scipy import linalg import bcipy.acquisition.devices as devices from bcipy.config import (DEFAULT_DEVICE_SPEC_FILENAME, - DEFAULT_GAZE_IMAGE_PATH, RAW_DATA_FILENAME, - TRIGGER_FILENAME, SESSION_LOG_FILENAME, - DEFAULT_PARAMETERS_PATH) + DEFAULT_GAZE_IMAGE_PATH, DEFAULT_PARAMETERS_PATH, + RAW_DATA_FILENAME, SESSION_LOG_FILENAME, + TRIGGER_FILENAME) +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawData +from bcipy.core.stimuli import mne_epochs +from bcipy.core.triggers import TriggerType, trigger_decoder from bcipy.helpers.acquisition import analysis_channels -from bcipy.helpers.convert import convert_to_mne -from bcipy.helpers.load import choose_csv_file, load_raw_data, load_json_parameters -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.raw_data import RawData -from bcipy.helpers.stimuli import mne_epochs -from bcipy.helpers.triggers import TriggerType, trigger_decoder +from bcipy.io.convert import convert_to_mne +from bcipy.io.load import choose_csv_file, load_json_parameters, load_raw_data from bcipy.signal.process import (Composition, ERPTransformParams, get_default_transform) @@ -62,7 +60,7 @@ def visualize_erp( plot_topomaps: Optional[bool] = True, show: Optional[bool] = False, save_path: Optional[str] = None) -> List[Figure]: - """ Visualize ERP. + """Visualize ERP. Generates a comparative ERP figure following a task execution. Given a set of trailed data, and labels describing two classes (Nontarget=0 and Target=1), they are plotted and may be saved @@ -92,8 +90,10 @@ def visualize_erp( else: baseline = None - mne_data = convert_to_mne(raw_data, channel_map=channel_map, transform=transform) - epochs = mne_epochs(mne_data, trial_length, trigger_timing, trigger_labels, baseline=baseline) + mne_data = convert_to_mne( + raw_data, channel_map=channel_map, transform=transform) + epochs = mne_epochs(mne_data, trial_length, trigger_timing, + trigger_labels, baseline=baseline) # *Note* We assume, as described above, two trigger classes are defined for use in trigger_labels # (Nontarget=0 and Target=1). This will map into two corresponding MNE epochs whose indexing starts at 1. # Therefore, epochs['1'] == Nontarget and epochs['2'] == Target. @@ -104,10 +104,12 @@ def visualize_erp( if plot_topomaps: # make a list of equally spaced times to plot topomaps using the time window # defined in the task parameters - times = [round(trial_window[0] + i * (trial_window[1] - trial_window[0]) / 5, 1) for i in range(7)] + times = [round(trial_window[0] + i * (trial_window[1] - + trial_window[0]) / 5, 1) for i in range(7)] # clip any times that are out of bounds of the time window or zero - times = [time for time in times if trial_window[0] <= time <= trial_window[1] and time != 0] + times = [time for time in times if trial_window[0] + <= time <= trial_window[1] and time != 0] figs.extend(visualize_joint_average( epochs, ['Non-Target', 'Target'], @@ -152,7 +154,6 @@ def visualize_gaze( heatmap: Optional[bool]: Whether or not to plot the heatmap. Default: False raw_plot: Optional[bool]: Whether or not to plot the raw gaze data. Default: False """ - title = f'{data.daq_type} ' if heatmap: title += 'Heatmap ' @@ -164,12 +165,14 @@ def visualize_gaze( img = plt.imread(img_path) channels = data.channels - left_eye_channel_map = [1 if channel in left_keys else 0 for channel in channels] + left_eye_channel_map = [ + 1 if channel in left_keys else 0 for channel in channels] left_eye_data, _, _ = data.by_channel_map(left_eye_channel_map) left_eye_x = left_eye_data[0] left_eye_y = left_eye_data[1] - right_eye_channel_map = [1 if channel in right_keys else 0 for channel in channels] + right_eye_channel_map = [ + 1 if channel in right_keys else 0 for channel in channels] right_eye_data, _, _ = data.by_channel_map(right_eye_channel_map) right_eye_x = right_eye_data[0] right_eye_y = right_eye_data[1] @@ -222,7 +225,8 @@ def visualize_gaze( plt.title(f'{title}Plot') if save_path is not None: - plt.savefig(f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) + plt.savefig( + f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) if show: plt.show() @@ -339,7 +343,8 @@ def visualize_gaze_inquiries( plt.title(f'{title}Plot') if save_path is not None: - plt.savefig(f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) + plt.savefig( + f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) if show: plt.show() @@ -421,7 +426,8 @@ def visualize_pupil_size( plt.title(f'{title}Plot') if save_path is not None: - plt.savefig(f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) + plt.savefig( + f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) if show: plt.show() @@ -489,7 +495,8 @@ def visualize_centralized_data( plt.title(f'{title}Plot') if save_path is not None: - plt.savefig(f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) + plt.savefig( + f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) if show: plt.show() @@ -595,7 +602,8 @@ def visualize_results_all_symbols( # Plot an ellipse to show the Gaussian component angle = np.arctan(u[1] / u[0]) angle = 180.0 * angle / np.pi # convert to degrees - ell = Ellipse(mean, v[0], v[1], angle=180.0 + angle, color='navy') + ell = Ellipse(mean, v[0], v[1], + angle=180.0 + angle, color='navy') ell.set_clip_box(ax) ell.set_alpha(0.5) ax.add_artist(ell) @@ -608,7 +616,8 @@ def visualize_results_all_symbols( plt.title(f'{title}Plot') if save_path is not None: - plt.savefig(f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) + plt.savefig( + f"{save_path}/{title.lower().replace(' ', '_')}plot.png", dpi=fig.dpi) if show: plt.show() @@ -618,23 +627,6 @@ def visualize_results_all_symbols( return fig -def plot_edf(edf_path: str, auto_scale: Optional[bool] = False): - """Plot data from the raw edf file. Note: this works from an iPython - session but seems to throw errors when provided in a script. - - Parameters - ---------- - edf_path - full path to the generated edf file - auto_scale - optional; if True will scale the EEG data; this is - useful for fake (random) data but makes real data hard to read. - """ - edf = read_raw_edf(edf_path, preload=True) - if auto_scale: - edf.plot(scalings='auto') - else: - edf.plot() - - def visualize_csv_eeg_triggers(trigger_col: Optional[int] = None): """Visualize CSV EEG Triggers. @@ -674,7 +666,8 @@ def visualize_csv_eeg_triggers(trigger_col: Optional[int] = None): def visualize_joint_average( epochs: Tuple[Epochs], labels: List[str], - plot_joint_times: Optional[List[float]] = [-0.1, 0, 0.2, 0.3, 0.35, 0.4, 0.5], + plot_joint_times: Optional[List[float] + ] = [-0.1, 0, 0.2, 0.3, 0.35, 0.4, 0.5], save_path: Optional[str] = None, show: Optional[bool] = False) -> List[Figure]: """Visualize Joint Average. @@ -695,7 +688,8 @@ def visualize_joint_average( Returns: List of figures generated """ - assert len(epochs) == len(labels), "The number of epochs must match labels in Visualize Joint Average" + assert len(epochs) == len( + labels), "The number of epochs must match labels in Visualize Joint Average" figs = [] for i, label in enumerate(labels): @@ -759,12 +753,14 @@ def visualize_session_data( # extract all relevant parameters trial_window = parameters.get("trial_window") - raw_data = load_raw_data(str(Path(session_path, f'{RAW_DATA_FILENAME}.csv'))) + raw_data = load_raw_data( + str(Path(session_path, f'{RAW_DATA_FILENAME}.csv'))) channels = raw_data.channels sample_rate = raw_data.sample_rate daq_type = raw_data.daq_type - transform_params: ERPTransformParams = parameters.instantiate(ERPTransformParams) + transform_params: ERPTransformParams = parameters.instantiate( + ERPTransformParams) devices.load(Path(session_path, DEFAULT_DEVICE_SPEC_FILENAME)) device_spec = devices.preconfigured_device(daq_type) @@ -782,12 +778,14 @@ def visualize_session_data( trigger_targetness, trigger_timing, _ = trigger_decoder( offset=device_spec.static_offset, trigger_path=f"{session_path}/{TRIGGER_FILENAME}", - exclusion=[TriggerType.PREVIEW, TriggerType.EVENT, TriggerType.FIXATION], + exclusion=[TriggerType.PREVIEW, + TriggerType.EVENT, TriggerType.FIXATION], device_type='EEG', ) assert "nontarget" in trigger_targetness, "No nontarget triggers found." assert "target" in trigger_targetness, "No target triggers found." - assert len(trigger_targetness) == len(trigger_timing), "Trigger targetness and timing must be the same length." + assert len(trigger_targetness) == len( + trigger_timing), "Trigger targetness and timing must be the same length." labels = [0 if label == 'nontarget' else 1 for label in trigger_targetness] channel_map = analysis_channels(channels, device_spec) @@ -826,7 +824,8 @@ def visualize_gaze_accuracies(accuracy_dict: Dict[str, np.ndarray], ax.set_title(title + str(round(accuracy, 2))) if save_path is not None: - plt.savefig(f"{save_path}/{title.lower().replace(' ', '_').replace(':', '')}plot.png", dpi=fig.dpi) + plt.savefig( + f"{save_path}/{title.lower().replace(' ', '_').replace(':', '')}plot.png", dpi=fig.dpi) if show: plt.show() @@ -837,6 +836,9 @@ def visualize_gaze_accuracies(accuracy_dict: Dict[str, np.ndarray], def erp(): + """ERP Visualization CLI. + This function is used to visualize ERP data after a session. + """ import argparse parser = argparse.ArgumentParser(description='Visualize ERP data') diff --git a/bcipy/io/README.md b/bcipy/io/README.md new file mode 100644 index 000000000..0381ec7fa --- /dev/null +++ b/bcipy/io/README.md @@ -0,0 +1,7 @@ +# BciPy IO + +The BciPy IO module contains functionality for loading and saving data in various formats. This includes the ability to convert data to BIDS format, load and save raw data, and load and save triggers. + +- `convert`: functionality for converting the BciPy raw data output to other formats (currently, BrainVision and EDF), and for converting the raw data to BIDS format. +- `load`: methods for loading most BciPy data formats, including raw data and triggers. +- `save`: methods for saving BciPy data in supported formats. diff --git a/bcipy/io/__init__.py b/bcipy/io/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/bcipy/io/convert.py b/bcipy/io/convert.py new file mode 100644 index 000000000..baa88b583 --- /dev/null +++ b/bcipy/io/convert.py @@ -0,0 +1,556 @@ +# mypy: disable-error-code="no-redef" +"""Functionality for converting the bcipy raw data output to other formats""" +import glob +import logging +import os +import tarfile +from enum import Enum +from typing import List, Optional, Tuple + +import mne +from mne.io import RawArray +from mne_bids import (BIDSPath, find_matching_paths, get_entity_vals, + read_raw_bids, write_raw_bids) +from tqdm import tqdm + +from bcipy.acquisition.devices import preconfigured_device +from bcipy.config import (RAW_DATA_FILENAME, SESSION_LOG_FILENAME, + TRIGGER_FILENAME) +from bcipy.core.raw_data import RawData, get_1020_channel_map +from bcipy.core.triggers import trigger_decoder +from bcipy.io.load import load_raw_data +from bcipy.signal.process import Composition + +logger = logging.getLogger(SESSION_LOG_FILENAME) + +FILE_LENGTH_LIMIT = 150 + + +class ConvertFormat(Enum): + """Enumeration of supported data conversion formats for BciPy raw data output.""" + + BV = 'BrainVision' + EDF = 'EDF' + FIF = 'FIF' + EEGLAB = 'EEGLAB' + + def __str__(self): + """Return the string representation of the format.""" + return self.value + + @staticmethod + def all(): + """Return a list of all ConvertFormat enum members.""" + return [format for format in ConvertFormat] + + @staticmethod + def values(): + """Return a list of all ConvertFormat values as strings.""" + return [format.value for format in ConvertFormat] + + +def convert_to_bids( + data_dir: str, + participant_id: str, + session_id: str, + run_id: str, + output_dir: str, + task_name: Optional[str] = None, + line_frequency: float = 60, + format: ConvertFormat = ConvertFormat.BV, + label_duration: float = 0.5, + full_labels: bool = True) -> str: + """Convert to BIDS. + + Convert the raw data to the Brain Imaging Data Structure (BIDS) format. + The BIDS format is a standard for organizing and describing neuroimaging data. + See: https://bids.neuroimaging.io/. + + Currently, this function only supports EEG data. + + Parameters + ---------- + data_dir - path to the directory containing the raw data, triggers, and parameters + participant_id - the participant ID + session_id - the session ID + run_id - the run ID + output_dir - the directory to save the BIDS formatted data + task_name - the name of the task + line_frequency - the line frequency of the data (50 or 60 Hz) + format - the format to convert the data to (BrainVision, EDF, FIF, or EEGLAB) + label_duration - the duration of the trigger labels in seconds. Default is 0.5 seconds. + full_labels - if True, include the full trigger labels in the BIDS data. Default is True. If False, only include + the targetness labels (target/non-target). + + Returns + ------- + The path to the BIDS formatted data + """ + # validate the inputs before proceeding + if not os.path.exists(data_dir): + raise FileNotFoundError(f"Data directory={data_dir} does not exist") + if not os.path.exists(output_dir): + try: + os.mkdir(output_dir) + except OSError as e: + raise OSError( + f"Failed to create output directory={output_dir}") from e + if format not in ConvertFormat.all(): + raise ValueError(f"Unsupported format={format}") + if line_frequency not in [50, 60]: + raise ValueError("Line frequency must be 50 or 60 Hz") + + # create file paths for raw data, triggers, and parameters + raw_data_file = os.path.join(data_dir, f'{RAW_DATA_FILENAME}.csv') + trigger_file = os.path.join(data_dir, TRIGGER_FILENAME) + + # load the raw data and specifications for the device used to collect the data + raw_data = load_raw_data(raw_data_file) + channel_map = get_1020_channel_map(raw_data.channels) + device_spec = preconfigured_device(raw_data.daq_type) + volts = True if device_spec.channel_specs[0].units == 'volts' else False + + # load the triggers without removing any triggers other than system triggers (default) + trigger_targetness, trigger_timing, trigger_labels = trigger_decoder( + trigger_path=trigger_file, + offset=device_spec.static_offset, + device_type='EEG', + ) + + # convert the raw data to MNE format + mne_data = convert_to_mne(raw_data, volts=volts, channel_map=channel_map) + + # add the trigger annotations to the MNE data + targetness_annotations = mne.Annotations( + onset=trigger_timing, + duration=[label_duration] * len(trigger_timing), + description=trigger_targetness, + ) + + if full_labels: + label_annotations = mne.Annotations( + onset=trigger_timing, + duration=[label_duration] * len(trigger_timing), + description=trigger_labels, + ) + mne_data.set_annotations(targetness_annotations + label_annotations) + else: + mne_data.set_annotations(targetness_annotations) + # add the line frequency to the MNE data + mne_data.info["line_freq"] = line_frequency + + # create the BIDS path for the data + bids_path = BIDSPath( + subject=participant_id, + session=session_id, + task=task_name, + run=run_id, + datatype="eeg", + root=output_dir + ) + + # use the BIDS conversion function from MNE-BIDS + write_raw_bids( + mne_data, + bids_path, + format=format.value, + allow_preload=True, + overwrite=True) + + return bids_path.directory + + +def convert_eyetracking_to_bids( + raw_data_path, + output_dir, + participant_id, + session_id, + run_id, + task_name) -> str: + """Converts the raw eye tracking data to BIDS format. + + There is currently no standard for eye tracking data in BIDS. This function will write the raw eye tracking data + to a tsv file in a BIDS-style format. + + Parameters + ---------- + raw_data_path : str + Path to the raw eye tracking data + output_dir : str + Path to the output directory. + This should be where other BIDS formatted data is stored for the participant, session, and run. + participant_id : str + Participant ID, e.g. 'S01' + session_id : str + Session ID, e.g. '01' + run_id : str + Run ID, e.g. '01' + task_name : str + Task name. Example: 'RSVPCalibration' + + Returns + ------- + str + Path to the BIDS formatted eye tracking data + """ + # check that the raw data path exists + if not os.path.exists(raw_data_path): + raise FileNotFoundError( + f"Raw eye tracking data path={raw_data_path} does not exist") + + if not os.path.exists(output_dir): + raise FileNotFoundError( + f"Output directory={output_dir} does not exist") + + found_files = glob.glob(f"{raw_data_path}/eyetracker*.csv") + if len(found_files) == 0: + raise FileNotFoundError( + f"No raw eye tracking data found in directory={raw_data_path}") + if len(found_files) > 1: + raise ValueError( + f"Multiple raw eye tracking data files found in directory={raw_data_path}") + + eye_tracking_file = found_files[0] + logger.info(f"Found raw eye tracking data file={eye_tracking_file}") + + # load the raw eye tracking data + raw_data = load_raw_data(eye_tracking_file) + # get the data as a pandas DataFrame + data = raw_data.dataframe + + # make the et subdirectory + et_dir = os.path.join(output_dir, 'et') + os.makedirs(et_dir, exist_ok=True) + + # write the dataframe as a tsv file to the output directory + output_filename = f'sub-{participant_id}_ses-{session_id}_task-{task_name}_run-{run_id}_eyetracking.tsv' + output_path = os.path.join(et_dir, output_filename) + data.to_csv(output_path, sep='\t', index=False) + logger.info(f"Eye tracking data saved to {output_path}") + return output_path + + +def compress(tar_file_name: str, members: List[str]) -> None: + """ + File compression and archiving. + + Adds files to a tar archive and compresses them using the gzip compression + format. + + Parameters + ---------- + tar_file_name (str): name of resulting compressed tar archive. Input string + can either include or not include file extension (.tar.gz), as this will + be checked. + members (List[str]): list of files and folders to be compressed into archive. + Each file or folder requires the relative file path and full file extension. + Individual file paths and names that are very long may throw an error + upon extraction, proceed with caution. + + Returns + ------- + None + """ + + for member in members: + # Checks if file exists + if not os.path.exists(member): + raise FileNotFoundError(f"This file or folder, '{member}', " + "does not exist!\nPlease rerun program") + # Checks for file names that may be too long. OS level restriction. + if len(member) > FILE_LENGTH_LIMIT: + logger.warning( + f'File length exceeds compression limit=[{FILE_LENGTH_LIMIT}]. ' + 'This may cause issues later with extraction. Please proceed at your own discretion.') + + full_tar_name = tar_name_checker(tar_file_name) + # Warns user that reopening tar archive that already exists will overwrite it + if os.path.exists(full_tar_name): + raise Exception(f"This tar archive=[{full_tar_name}] already exists, continuing will " + "overwrite anything in the existing archive.") + + # Opens file for gzip (gz) compressed writing (w) + # Uses default compression level 9 (highest compression, slowest speed) + with tarfile.open(full_tar_name, mode="w:gz") as tar: + # Sets progress bar through tqdm + progress = tqdm(members) + for member in progress: + # Adds file/folder to the tar file and compresses it + tar.add(member) + # Sets progress description of progress bar + progress.set_description(f"Compressing {member}") + + +def decompress(tar_file: str, path: str) -> None: + """ + Archive decompression and extraction. + + Takes .tar.gz archive, decompresses, and extracts its contents. Should only be + used with files created by compress() method. + + Parameters + ---------- + tar_file (str): name of .tar.gz archive to be decompressed. Input string + can either include or not include file extension (.tar.gz), as this will + be checked. + path (str): file path and name of folder for the extracted contents of the + archive. If only a name is entered, by default it will place the folder + in the current working directory. (ex. "extracted" creates a new folder + in the current directory and extracts the archive contents to it) + + Returns + ------- + None + """ + + full_tar_name = tar_name_checker(tar_file) + + # Checks if file exists + if not os.path.exists(full_tar_name): + raise FileNotFoundError(f"This file or folder, '{tar_file}', " + "does not exist!\nPlease rerun program") + + # Opens file for gzip (gz) compressed reading (r) + with tarfile.open(full_tar_name, mode="r:gz") as tar: + members = tar.getmembers() + + # Sets progress bar through tqdm + progress = tqdm(members) + for member in progress: + tar.extract(member, path=path) + # Sets progress description of progress bar + progress.set_description(f"Extracting {member.name}") + + +def archive_list(tar_file: str) -> List[str]: + """ + Returns contents of tar archive. + + Takes .tar.gz archive and returns a full list of its contents, including + folders, subfolders, and files, with their full relative paths and names. + + Parameters + ---------- + tar_file (str): name of desired .tar.gz archive. Input string can either + include or not include file extension (.tar.gz), as this will be checked. + + Returns + ------- + List[str] of all items in archive + """ + + full_tar_name = tar_name_checker(tar_file) + + # Checks if file exists + if not os.path.exists(full_tar_name): + raise FileNotFoundError(f"This file or folder, '{tar_file}', " + "does not exist!\nPlease rerun program") + + # Adds names of archive contents to list + with tarfile.open(full_tar_name, mode="r") as tar: + tar_list = tar.getnames() + return tar_list + + +def tar_name_checker(tar_file_name: str) -> str: + """ + Checks and modifies file name for tar archive. + + Helper method that takes a tar file name and checks it for the appropriate + file extension (".tar.gz" for now), returning it if it already does, and + adding the extension and then returning it if it does not. + + Parameters + ---------- + tar_file_name (str): name for archive being checked. + + Returns + ------- + String of properly formatted tar archive name + """ + + if tar_file_name.endswith('.tar.gz'): + return tar_file_name + return f'{tar_file_name}.tar.gz' + + +def convert_to_mne( + raw_data: RawData, + channel_map: Optional[List[int]] = None, + channel_types: Optional[List[str]] = None, + transform: Optional[Composition] = None, + montage: str = 'standard_1020', + volts: bool = False, + remove_system_channels: bool = True) -> RawArray: + """Convert to MNE. + + Returns BciPy RawData as an MNE RawArray. This assumes all channel names + are reflective of provided montage locations. + + Parameters + ---------- + raw_data - BciPy RawData object + channel_map - optional list of channels to include in the MNE RawArray [1, 0, 1, 0, 1, 0, 1, 0]. + 1 indicates the channel should be included, 0 indicates it should be excluded. + Must be the same length as the number of channels in the raw_data. + channel_types - list of channel types to include in the MNE RawArray. + If None, all channels will be assumed to be eeg. + See: https://mne.tools/stable/overview/implementation.html#supported-channel-types + transform - optional transform to apply to the data + montage - name of the channel location montage to use. + See https://mne.tools/dev/generated/mne.channels.make_standard_montage.html + volts - if True, assume data is already in volts. If false, assume data is in microvolts and convert to volts. + MNE expects data to be in volts. + See: https://mne.tools/dev/overview/implementation.html#internal-representation-units + remove_system_channels - if True, exclude the system and trigger channels from the MNE RawArray + (last two channels in BciPy data). + + Returns + ------- + MNE RawArray + """ + # if no channel map provided, assume all channels are included + if not channel_map: + # if remove_system_channels is True, exclude the system and trigger channels (last two channels) + if remove_system_channels: + channel_map = [1] * (len(raw_data.channels) - 2) + # exclude the system and trigger channels + channel_map.extend([0, 0]) + else: + channel_map = [1] * len(raw_data.channels) + + data, channels, fs = raw_data.by_channel_map(channel_map, transform) + + # if no channel types provided, assume all channels are eeg + if not channel_types: + logger.warning( + "No channel types provided. Assuming all channels are EEG.") + channel_types = ['eeg'] * len(channels) + + # check that number of channel types matches number of channels in the case custom channel types are provided + assert len(channel_types) == len(channels), \ + f'Number of channel types ({len(channel_types)}) must match number of channels ({len(channels)})' + + info = mne.create_info(channels, fs, channel_types) + mne_data = RawArray(data, info) + ten_twenty_montage = mne.channels.make_standard_montage(montage) + mne_data.set_montage(ten_twenty_montage) + + # convert to volts if necessary (the default for many systems is microvolts) + if not volts: + mne_data = mne_data.apply_function(lambda x: x * 1e-6) + + return mne_data + + +def tobii_to_norm(tobii_units: Tuple[float, float]) -> Tuple[float, float]: + """Tobii to PsychoPy's 'norm' units. + + https://developer.tobiipro.com/commonconcepts/coordinatesystems.html + https://www.psychopy.org/general/units.html + + Tobii uses an Active Display Coordinate System. + The point (0, 0) denotes the upper left corner and (1, 1) the lower right corner of it. + + PsychoPy uses several coordinate systems, the normalized window unit is assumed here. + The point (0, 0) denotes the center of the screen and (-1, -1) the upper left corner + and (1, 1) the lower right corner. + + """ + # check that Tobii units are within the expected range + assert 0 <= tobii_units[0] <= 1, "Tobii x coordinate must be between 0 and 1" + assert 0 <= tobii_units[1] <= 1, "Tobii y coordinate must be between 0 and 1" + + # convert Tobii units to Psychopy units + norm_x = (tobii_units[0] - 0.5) * 2 + norm_y = (tobii_units[1] - 0.5) * 2 * -1 + return (norm_x, norm_y) + + +def norm_to_tobii(norm_units: Tuple[float, float]) -> Tuple[float, float]: + """PsychoPy's 'norm' units to Tobii. + + https://developer.tobiipro.com/commonconcepts/coordinatesystems.html + https://www.psychopy.org/general/units.html + + Tobii uses an Active Display Coordinate System. + The point (0, 0) denotes the upper left corner and (1, 1) the lower right corner of it. + + PsychoPy uses several coordinate systems, the normalized window unit is assumed here. + The point (0, 0) denotes the center of the screen and (-1, -1) the upper left corner + and (1, 1) the lower right corner. + """ + # check that the coordinates are within the bounds of the screen + assert norm_units[0] >= - \ + 1 and norm_units[0] <= 1, "X coordinate must be between -1 and 1" + assert norm_units[1] >= - \ + 1 and norm_units[1] <= 1, "Y coordinate must be between -1 and 1" + + # convert PsychoPy norm units to Tobii units + tobii_x = (norm_units[0] / 2) + 0.5 + tobii_y = ((norm_units[1] * -1) / 2) + 0.5 + return (tobii_x, tobii_y) + + +def BIDS_to_MNE( + bids_root_path: str, + task_name: Optional[str] = None) -> List[mne.io.Raw]: + """Convert BIDS data to MNE Raw object. + + Parameters + ---------- + bids_root_path : str + Path to the BIDS directory. + task_name : str, optional + Task name. Example: 'RSVPCalibration'. + + Returns + ------- + List[mne.io.Raw] + List of MNE Raw objects containing the BIDS data. + + Raises + ------ + FileNotFoundError + If the BIDS root path does not exist or no matching files are found. + ValueError + If the BIDS directory is invalid or contains unsupported data types. + """ + # Check if the BIDS root path exists + if not os.path.exists(bids_root_path): + raise FileNotFoundError( + f"BIDS root path '{bids_root_path}' does not exist.") + logger.info(f"Searching for BIDS data in '{bids_root_path}'...") + + # Get the sessions from the BIDS root path using the session label (e.g., 'ses' or 'session') + sessions = get_entity_vals(bids_root_path, 'session') + data_type = 'eeg' + extensions = ['.vhdr', '.edf', '.bdf'] # Supported file extensions + + bid_paths = find_matching_paths( + bids_root_path, + extensions=extensions, + sessions=sessions, + datatypes=data_type, + tasks=task_name, + ) + if not bid_paths: + raise FileNotFoundError( + f"No matching BIDS files found in '{bids_root_path}'.") + + raw_data = [] + for bid_path in bid_paths: + if task_name and bid_path.task != task_name: + logger.debug( + f"Skipping file '{bid_path}' due to task name [{task_name}] mismatch.") + continue + + logger.info(f"Reading BIDS file: {bid_path}") + + # Read the raw data from the BIDS path + raw = read_raw_bids(bid_path) + raw_data.append(raw) + + logger.info(f"Successfully loaded {len(raw_data)} BIDS files.") + + return raw_data diff --git a/bcipy/io/demo/demo_convert.py b/bcipy/io/demo/demo_convert.py new file mode 100644 index 000000000..5195b44d6 --- /dev/null +++ b/bcipy/io/demo/demo_convert.py @@ -0,0 +1,179 @@ +"""Demonstrates converting BciPy data output to other EEG formats. + +To use at bcipy root, + + `python bcipy/io/demo/demo_convert.py -d "path://to/bcipy/data/folder"` +""" +from pathlib import Path +from typing import List, Optional + +from bcipy.gui.file_dialog import ask_directory +from bcipy.io.convert import (ConvertFormat, convert_eyetracking_to_bids, + convert_to_bids) +from bcipy.io.load import BciPySessionTaskData, load_bcipy_data + +EXCLUDED_TASKS = ['Report', 'Offline', 'Intertask', 'BAD'] + + +def load_historical_bcipy_data(directory: str, experiment_id: str) -> List[BciPySessionTaskData]: + """Load the data from the given directory. + + The expected directory structure is: + + directory/ + user1/ + task_run/ + raw_data.csv + user2/ + task_run/ + raw_data.csv + """ + + data = Path(directory) + experiment_data = [] + for participant in data.iterdir(): + + # Skip files + if not participant.is_dir(): + continue + + # pull out the user id. This is the name of the folder + user_id = participant.name + + run_tasks = {} + for task_run in participant.iterdir(): + if not task_run.is_dir(): + continue + + extracted_task_paradigm = task_run.name.split('_')[1] + extracted_task_mode = task_run.name.split('_')[2] + if extracted_task_mode == 'Copy': + task_name = 'CopyPhrase' + extracted_task_time = task_run.name.split('_')[8] + else: + extracted_task_time = task_run.name.split('_')[7] + + # add the tasks to the list with the time as the key + run_tasks[extracted_task_time] = [ + task_run, f'{extracted_task_paradigm}{extracted_task_mode}'] + + # sort the tasks by time + sorted_tasks = sorted(run_tasks.items()) + # print(sorted_tasks) + for i, (_, task_info) in enumerate(sorted_tasks): + task_run, task_name = task_info + + session_data = BciPySessionTaskData( + path=task_run, + user_id=user_id, + experiment_id=experiment_id, + session_id=1, + run=i + 1, + task_name=task_name + ) + experiment_data.append(session_data) + return experiment_data + + +def convert_experiment_to_bids( + directory: str, + experiment_id: str, + format: ConvertFormat = ConvertFormat.BV, + output_dir: Optional[str] = None, + include_eye_tracker: bool = False) -> None: + """Converts the data in the study folder to BIDS format.""" + + # Use for data pre-2.0rc4 + experiment_data = load_historical_bcipy_data( + directory, + experiment_id=experiment_id) + + # Use for data post-2.0rc4 + experiment_data = load_bcipy_data( + directory, experiment_id, excluded_tasks=EXCLUDED_TASKS) + + if not output_dir: + output_dir = directory + + errors = [] + for data in experiment_data: + try: + bids_path = convert_to_bids( + data_dir=data.path, + participant_id=data.user_id, + session_id=data.session_id, + run_id=data.run, + task_name=data.task_name, + output_dir=f'{output_dir}/bids_{experiment_id}/', + format=format + ) + + if include_eye_tracker: + # Convert the eye tracker data + # The eye tracker data is in the same folder as the EEG data, but should be saved in a different folder + bids_path = Path(bids_path).parent + try: + convert_eyetracking_to_bids( + raw_data_path=data.path, + participant_id=data.user_id, + session_id=data.session_id, + run_id=data.run, + output_dir=bids_path, + task_name=data.task_name + ) + except Exception as e: + print( + f"Error converting eye tracker data for {data.path} - {e}") + errors.append( + f"Error converting eye tracker data for {data.path}") + + except Exception as e: + print(f"Error converting {data.path} - {e}") + errors.append(str(data.path)) + + print("--------------------") + if errors: + print(f"Errors converting the following data: {errors}") + + print( + f"\nData converted to BIDS format in {output_dir}/bids_{experiment_id}/") + print("--------------------") + + +if __name__ == '__main__': + import argparse + + parser = argparse.ArgumentParser() + parser.add_argument( + '-d', + '--directory', + help='Path to the directory with raw_data to be converted', + required=False) + parser.add_argument( + '-e', + '--experiment', + help='Experiment ID to convert', + default='BciPyDefaultExperiment', + ) + parser.add_argument( + '-et', + '--eye_tracker', + help='Include eye tracker data', + default=False, + action='store_true', + ) + + args = parser.parse_args() + + path = args.directory + if not path: + path = ask_directory( + "Select the directory with data to be converted", strict=True) + + # convert a study to BIDS format + convert_experiment_to_bids( + path, + args.experiment, + ConvertFormat.BV, + output_dir=".", + include_eye_tracker=args.eye_tracker) diff --git a/bcipy/io/demo/demo_load_BIDS.py b/bcipy/io/demo/demo_load_BIDS.py new file mode 100644 index 000000000..942e4a747 --- /dev/null +++ b/bcipy/io/demo/demo_load_BIDS.py @@ -0,0 +1,79 @@ +"""Demo script to load BIDS data into MNE format using BciPy. + +This script demonstrates how to load BIDS data using the BciPy library. This assumes that the data is +already in BIDS format (BV, EDF, or BDF, with the channels.tsv file) and that the BIDS directory is +structured correctly. + +The BIDS directory should contain a dataset_description.json file and a +participants.tsv file, along with the data files in the appropriate subdirectories. +""" + +import mne +from mne.viz import plot_compare_evokeds + +from bcipy.io.convert import BIDS_to_MNE +from bcipy.io.load import load_experimental_data + +# This script demonstrates how to load BIDS data using the BciPy library. This assumes that the data is +# already in BIDS format (BV, EDF, or BDF, with the channels.tsv file) and that the BIDS directory is +# structured correctly. The BIDS directory should contain a dataset_description.json file and a +# participants.tsv file, along with the data files in the appropriate subdirectories. +try: + path_to_bids = load_experimental_data() + + # Load BIDS data using MNE-Python and MNE-BIDS. This returns a list of raw data objects. + # The data is loaded from the BIDS directory specified in the path_to_bids variable. + # task_name = 'Calibration' # Specify the task name to load data for. + # This will filter the data to only include the specified task. + task_name = None # Set to None to load all tasks. + raw_data_files = BIDS_to_MNE(path_to_bids, task_name=task_name) + + # Get the first raw data object from the list. + raw_data = raw_data_files[0] + + # to see where the data is stored, you can use the following command: + # print(raw_data.filenames) + + # PLOT THE RAW DATA + raw_data.load_data() + raw_data.filter(1, 20) # Apply a bandpass filter to the data (1-20 Hz). + raw_data.plot() # + + # EPOCH THE DATA / CREATE ERPS + # epoch the data using the events from the raw data object. + # You can specify the event_id, tmin, tmax, and baseline parameters as needed. + events = mne.events_from_annotations( + raw_data, event_id={'nontarget': 0, 'target': 1}) + tmin = -0.2 + tmax = 0.8 + baseline = (None, None) # No baseline correction. + epochs = mne.Epochs( + raw_data, events[0], events[1], tmin, tmax, baseline=baseline, preload=True) + + # Grab the epochs for non-target and target events. + non_target_epochs = epochs['nontarget'] + target_epochs = epochs['target'] + + # Create evoked objects for non-target and target events. + non_target_evoked = non_target_epochs.average() + target_evoked = target_epochs.average() + + # PLOT THE EVOKED DATA + plot_compare_evokeds( + dict( + nontarget=non_target_evoked, + target=target_evoked), + title='Evoked Responses for Non-Target and Target Events', + show_sensors=True, + ci=0.95, + combine='mean', + invert_y=True) + target_evoked.plot_joint() + non_target_evoked.plot_joint() + +except Exception as e: + print(f"An error occurred: {e}") +finally: + print("Demo script completed.") + # This will pause the script execution and allow you to inspect the variables in the debugger. + breakpoint() diff --git a/bcipy/io/load.py b/bcipy/io/load.py new file mode 100644 index 000000000..8b4069426 --- /dev/null +++ b/bcipy/io/load.py @@ -0,0 +1,753 @@ +"""Module for loading BciPy data and configuration files. + +This module provides functions for loading various types of data used in BciPy, +including parameters, experiments, signal models, and session data. +""" + +# mypy: disable-error-code="arg-type, union-attr" +import json +import logging +import os +import pickle +from pathlib import Path +from shutil import copyfile +from time import localtime, strftime +from typing import List, Optional, Union + +from bcipy.config import (DEFAULT_ENCODING, DEFAULT_EXPERIMENT_PATH, + DEFAULT_FIELD_PATH, DEFAULT_PARAMETERS_PATH, + EXPERIMENT_FILENAME, FIELD_FILENAME, + SESSION_LOG_FILENAME, SIGNAL_MODEL_FILE_SUFFIX) +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawData +from bcipy.exceptions import BciPyCoreException, InvalidExperimentException +from bcipy.gui.file_dialog import ask_directory, ask_filename +from bcipy.preferences import preferences +from bcipy.signal.model import SignalModel + +log = logging.getLogger(SESSION_LOG_FILENAME) + + +def copy_parameters(path: str = DEFAULT_PARAMETERS_PATH, + destination: Optional[str] = None) -> str: + """Creates a copy of the given configuration (parameters.json) to the given directory. + + Args: + path: Optional path of parameters file to copy; uses default if not provided. + destination: Optional destination directory; default is the same directory + as the default parameters. + + Returns: + str: Path to the new file. + """ + default_dir = str(Path(DEFAULT_PARAMETERS_PATH).parent) + + destination = default_dir if destination is None else destination + filename = strftime('parameters_%Y-%m-%d_%Hh%Mm%Ss.json', localtime()) + + path = str(Path(destination, filename)) + copyfile(DEFAULT_PARAMETERS_PATH, path) + return path + + +def load_experiments(path: str = f'{DEFAULT_EXPERIMENT_PATH}/{EXPERIMENT_FILENAME}') -> dict: + """Load experiment configurations from a JSON file. + + Args: + path: Path to the experiments file. + + Returns: + dict: Dictionary of experiments with format: + { + name: { + fields: { + name: str, + required: bool, + anonymize: bool + }, + summary: str + } + } + """ + with open(path, 'r', encoding=DEFAULT_ENCODING) as json_file: + return json.load(json_file) + + +def extract_mode(bcipy_data_directory: str) -> str: + """Extract the task mode from a BciPy data save directory. + + This method extracts the task mode from a BciPy data save directory. This is important for + trigger conversions and extracting targetness. + + Note: + Not compatible with older versions of BciPy (pre 1.5.0) where + the tasks and modes were considered together using integers (1, 2, 3). + + Args: + bcipy_data_directory: Path to the data directory. + + Returns: + str: The extracted mode ('calibration' or 'copy_phrase'). + + Raises: + BciPyCoreException: If no valid mode could be extracted. + """ + directory = bcipy_data_directory.lower() + if 'calibration' in directory: + return 'calibration' + elif 'copy' in directory: + return 'copy_phrase' + raise BciPyCoreException( + f'No valid mode could be extracted from [{directory}]') + + +def load_fields(path: str = f'{DEFAULT_FIELD_PATH}/{FIELD_FILENAME}') -> dict: + """Load field definitions from a JSON file. + + Args: + path: Path to the fields file. + + Returns: + dict: Dictionary of fields with format: + { + "field_name": { + "help_text": str, + "type": str + } + } + """ + with open(path, 'r', encoding=DEFAULT_ENCODING) as json_file: + return json.load(json_file) + + +def load_experiment_fields(experiment: dict) -> list: + """Extract field names from an experiment configuration. + + Args: + experiment: Dictionary containing experiment configuration with format: + { + 'fields': [{field_dict}, {field_dict}], + 'summary': str + } + + Returns: + list: List of field names from the experiment configuration. + + Raises: + InvalidExperimentException: If experiment format is incorrect. + TypeError: If experiment is not a dictionary. + """ + if isinstance(experiment, dict): + try: + return [name for field in experiment['fields'] for name in field.keys()] + except KeyError: + raise InvalidExperimentException( + 'Experiment is not formatted correctly. It should be passed as a dictionary with the fields and' + f' summary keys. Fields is a list of dictionaries. Summary is a string. \n experiment=[{experiment}]') + raise TypeError( + 'Unsupported experiment type. It should be passed as a dictionary with the fields and summary keys') + + +def load_json_parameters(path: str, value_cast: bool = False) -> Parameters: + """Load and parse parameters from a JSON file. + + Args: + path: Path to the parameters file. + value_cast: Whether to cast values to their specified types. + + Returns: + Parameters: A Parameters object containing the loaded configuration. + + Note: + Expected JSON format: + { + "parameter_name": { + "value": str, + "section": str, + "name": str, + "helpTip": str, + "recommended": str, + "editable": str, + "type": str + } + } + """ + return Parameters(source=path, cast_values=value_cast) + + +def load_experimental_data(message='', strict=False) -> str: + """Show a dialog to select an experimental data directory. + + Args: + message: Optional prompt message for the dialog. + strict: Whether to enforce strict directory selection. + + Returns: + str: Path to the selected directory. + """ + filename = ask_directory(prompt=message, strict=strict) + log.info("Loaded Experimental Data From: %s" % filename) + return filename + + +def load_signal_models(directory: Optional[str] = None) -> List[SignalModel]: + """Load all signal models from a directory. + + Models are assumed to have been written using bcipy.helpers.save.save_model + function and should be serialized as pickled files. + + Args: + directory: Location of pretrained models. User will be prompted if not provided. + + Returns: + list: List of loaded SignalModel instances. + + Warning: + Reading pickled files is a potential security risk. Only load from trusted directories. + """ + if not directory or Path(directory).is_file(): + directory = ask_directory() + + # update preferences + path = Path(directory) + preferences.signal_model_directory = str(path) + + models = [] + for file_path in path.glob(f"*{SIGNAL_MODEL_FILE_SUFFIX}"): + with open(file_path, "rb") as signal_file: + model = pickle.load(signal_file) + log.info(f"Loading model {model}") + models.append(model) + return models + + +def choose_signal_models(device_types: List[str]) -> List[SignalModel]: + """Prompt the user to load a signal model for each provided device. + + Args: + device_types: List of device content types (e.g., 'EEG'). + + Returns: + list: List of selected SignalModel instances. + """ + return [ + model for model in map(choose_signal_model, set(device_types)) if model + ] + + +def load_signal_model(file_path: str) -> SignalModel: + """Load signal model from persisted file. + + Args: + file_path: Path to the model file. + + Returns: + SignalModel: The loaded signal model. + + Warning: + Reading pickled files is a potential security risk. Only load from trusted sources. + """ + with open(file_path, "rb") as signal_file: + model = pickle.load(signal_file) + log.info(f"Loading model {model}") + return model + + +def choose_signal_model(device_type: str) -> Optional[SignalModel]: + """Present a file dialog prompting the user to select a signal model. + + Args: + device_type: Device type (e.g., 'EEG' or 'Eyetracker') that should correspond + with the content_type of the DeviceSpec of the model. + + Returns: + Optional[SignalModel]: The selected signal model, or None if no selection made. + """ + file_path = ask_filename(file_types=f"*{SIGNAL_MODEL_FILE_SUFFIX}", + directory=preferences.signal_model_directory, + prompt=f"Select the {device_type} signal model") + + if file_path: + # update preferences + path = Path(file_path) + preferences.signal_model_directory = str(path) + return load_signal_model(str(path)) + return None + + +def choose_model_paths(device_types: List[str]) -> List[Path]: + """Select a model for each device and return a list of paths. + + Args: + device_types: List of device types to load models for. + + Returns: + list: List of paths to selected model files. + """ + return [ + ask_filename(file_types=f"*{SIGNAL_MODEL_FILE_SUFFIX}", + directory=preferences.signal_model_directory, + prompt=f"Select the {device_type} signal model") + for device_type in device_types + ] + + +def choose_csv_file(filename: Optional[str] = None) -> Optional[str]: + """GUI prompt to select a CSV file from the file system. + + Args: + filename: Optional filename to use; if provided the GUI is not shown. + + Returns: + Optional[str]: Path to selected file. + + Raises: + Exception: If the selected file is not a CSV file. + """ + if not filename: + filename = ask_filename('*.csv') + + # get the last part of the path to determine file type + file_name = filename.split('/')[-1] + + if 'csv' not in file_name: + raise Exception( + 'File type unrecognized. Please use a supported csv type') + + return filename + + +def load_raw_data(filename: Union[Path, str]) -> RawData: + """Read data from a CSV file written by data acquisition. + + Args: + filename: Path to the serialized data (CSV file). + + Returns: + RawData: Object containing the loaded data in memory. + """ + return RawData.load(filename) + + +def load_users(data_save_loc: str) -> List[str]: + """Load user directory names from the data path. + + Args: + data_save_loc: Path to the data directory. + + Returns: + list: List of user IDs found in the directory. Returns empty list if + directory not found (assuming no experiments have been run). + """ + try: + bcipy_data = BciPyCollection(data_directory=data_save_loc) + bcipy_data.load_users() + except FileNotFoundError: + return [] + return bcipy_data.users + + +def fast_scandir(directory_name: str, return_path: bool = True) -> List[str]: + """Quickly scan a directory for subdirectories. + + Args: + directory_name: Name of the directory to scan. + return_path: Whether to return full paths (True) or just names (False). + + Returns: + list: List of subdirectory paths or names. + """ + if return_path: + return [f.path for f in os.scandir(directory_name) if f.is_dir()] + + return [f.name for f in os.scandir(directory_name) if f.is_dir()] + + +class BciPySessionTaskData: + """Class representing data from a single BciPy task session. + + This class is used to store the path to the task data, as well as parameters + and other information about the task. + + Directory structure: + // + protocol.json + / + parameters.json + **task_data** + + Args: + path: Path to the session data. + user_id: ID of the user who performed the task. + experiment_id: ID of the experiment the task belongs to. + date_time: Optional timestamp of task execution. + date: Optional date of task execution. + task_name: Optional name of the executed task. + session_id: Session identifier number, defaults to 1. + run: Run number within the session, defaults to 1. + + Attributes: + user_id: ID of the user who performed the task. + experiment_id: ID of the experiment (with underscores removed). + session_id: Formatted session ID (zero-padded if < 10). + date_time: Timestamp of task execution. + date: Date of task execution. + run: Formatted run number (zero-padded if < 10). + path: Path to the session data. + task_name: Name of the executed task. + info: Dictionary containing all session information. + """ + + def __init__( + self, + path: str, + user_id: str, + experiment_id: str, + date_time: Optional[str] = None, + date: Optional[str] = None, + task_name: Optional[str] = None, + session_id: int = 1, + run: int = 1) -> None: + + self.user_id = user_id + self.experiment_id = experiment_id.replace('_', '') + self.session_id = f'0{str(session_id)}' if session_id < 10 else str( + session_id) + self.date_time = date_time + self.date = date + self.run = f'0{str(run)}' if run < 10 else str(run) + self.path = path + self.task_name = task_name + self.info = { + 'user_id': self.user_id, + 'experiment_id': self.experiment_id, + 'task_name': self.task_name, + 'session_id': self.session_id, + 'run': self.run, + 'date': self.date, + 'date_time': self.date_time, + 'path': self.path + } + + def __str__(self): + return f'BciPySessionTaskData: {self.info=}' + + def __repr__(self): + return f'BciPySessionTaskData: {self.info=}' + + +class BciPyCollection: + """Class for managing collections of BciPy session task data. + + This class is used to collect data from the data directory and filter based + on the provided filters. + + Args: + data_directory: Root directory containing BciPy data. + experiment_id_filter: Optional filter for specific experiments. + user_id_filter: Optional filter for specific users. + date_filter: Optional filter for specific dates. + date_time_filter: Optional filter for specific timestamps. + excluded_tasks: Optional list of task names to exclude. + anonymize: Whether to anonymize user data. + + Attributes: + data_directory: Root directory containing BciPy data. + experiment_id_filter: Filter for specific experiments. + user_id_filter: Filter for specific users. + date_filter: Filter for specific dates. + date_time_filter: Filter for specific timestamps. + excluded_tasks: List of task names to exclude. + anonymize: Whether to anonymize user data. + session_task_data: List of collected BciPySessionTaskData objects. + user_paths: List of paths to user directories. + date_paths: List of paths to date directories. + experiment_paths: List of paths to experiment directories. + date_time_paths: List of paths to datetime directories. + task_paths: List of paths to task directories. + """ + + def __init__( + self, + data_directory: str, + experiment_id_filter: Optional[str] = None, + user_id_filter: Optional[str] = None, + date_filter: Optional[str] = None, + date_time_filter: Optional[str] = None, + excluded_tasks: Optional[List[str]] = None, + anonymize: bool = False) -> None: + if not os.path.isdir(data_directory): + raise FileNotFoundError( + f'Data directory not found at [{data_directory}]') + self.data_directory = data_directory + + self.experiment_id_filter = experiment_id_filter + self.user_id_filter = user_id_filter + self.date_filter = date_filter + self.date_time_filter = date_time_filter + self.excluded_tasks = excluded_tasks + self.anonymize = anonymize + + # Initialize the data lists + self.session_task_data: List[BciPySessionTaskData] = [] + self.user_paths: List[str] = [] + self.date_paths: List[str] = [] + self.experiment_paths: List[str] = [] + self.date_time_paths: List[str] = [] + self.task_paths: List[str] = [] + + def __repr__(self): + return f'BciPyCollection: {self.data_directory=}' + + def __str__(self): + return f'BciPyCollection: {self.data_directory=}' + + @property + def users(self) -> List[str]: + """Get list of users in the collection. + + Returns: + list: List of user IDs. + """ + return [user.split('/')[-1] for user in self.user_paths] + + @property + def experiments(self) -> List[str]: + """Get list of unique experiments in the collection. + + Returns: + list: List of experiment IDs. + """ + experiments = [experiment.split('/')[-1] + for experiment in self.experiment_paths] + # remove duplicates from the list + return list(set(experiments)) + + @property + def dates(self) -> List[str]: + """Get list of unique dates in the collection. + + Returns: + list: List of dates. + """ + dates = [date.split('/')[-1] for date in self.date_paths] + # remove duplicates from the list + return list(set(dates)) + + @property + def date_times(self) -> List[str]: + """Get list of unique timestamps in the collection. + + Returns: + list: List of timestamps. + """ + date_times = [date_time.split('/')[-1] + for date_time in self.date_time_paths] + # remove duplicates from the list + return list(set(date_times)) + + @property + def tasks(self) -> List[str]: + """Get list of unique tasks in the collection. + + Returns: + list: List of task names. + """ + tasks = [task.task_name for task in self.session_task_data] + # remove duplicates from the list + return list(set(tasks)) + + def collect(self) -> List[BciPySessionTaskData]: + """Collect BciPy data from the data directory. + + Returns: + list: List of BciPySessionTaskData objects representing the experiment data. + """ + if not self.session_task_data: + self.load_tasks() + + # if anonymize is set, return the anonymized data. Make a map of user_id to anonymized id + if self.anonymize: + user_map = {} + user_id_increment = 1 + for task in self.session_task_data: + if task.user_id not in user_map: + user_map[task.user_id] = f'ID{user_id_increment}' + user_id_increment += 1 + task.user_id = user_map[task.user_id] + log.info(f"Anonymized user ids: {user_map}") + + return self.session_task_data + + def load_users(self) -> None: + """Load user paths from the data directory. + + Walks the data directory and sets the user paths. Filters by user ID if provided. + """ + user_paths = fast_scandir(self.data_directory, return_path=True) + if self.user_id_filter: + self.user_paths = [ + user for user in user_paths if self.user_id_filter in user] + else: + self.user_paths = user_paths + + def load_dates(self) -> None: + """Load date paths from the data directory. + + Walks the data directory and sets the date paths. Filters by date if provided. + """ + if not self.user_paths: + self.load_users() + + for user in self.user_paths: + data_paths = fast_scandir(user, return_path=True) + if self.date_filter: + self.date_paths.extend( + [data for data in data_paths if self.date_filter in data]) + else: + self.date_paths.extend(data_paths) + + def load_experiments(self) -> None: + """Load experiment paths from the data directory. + + Walks the data directory and sets the experiment paths. Filters by experiment ID if provided. + """ + if not self.date_paths: + self.load_dates() + + for date in self.date_paths: + experiment_paths = fast_scandir(date, return_path=True) + if self.experiment_id_filter: + self.experiment_paths.extend( + [data for data in experiment_paths if self.experiment_id_filter in data]) + else: + self.experiment_paths.extend(experiment_paths) + + def load_date_times(self) -> None: + """Load datetime paths from the data directory. + + Walks the data directory and sets the datetime paths. Filters by datetime if provided. + """ + if not self.experiment_paths: + self.load_experiments() + + for experiment in self.experiment_paths: + data_paths = fast_scandir(experiment, return_path=True) + if self.date_time_filter: + self.date_time_paths.extend( + [data for data in data_paths if self.date_time_filter in data]) + else: + self.date_time_paths.extend(data_paths) + + def sort_tasks(self, tasks: List[str]) -> List[str]: + """Sort tasks by their timestamp. + + Args: + tasks: List of task paths to sort. + + Returns: + list: Sorted list of task paths. + """ + return sorted(tasks, key=lambda x: x.split('_')[-1]) + + def load_tasks(self) -> None: + """Load task data from the data directory. + + Walks the data directory and sets the session_task_data representing the experiment data. + Excludes tasks that are in the excluded_tasks list. + """ + if not self.date_time_paths: + self.load_date_times() + + for date_time in self.date_time_paths: + tasks = fast_scandir(date_time, return_path=True) + run = 1 + tasks = self.sort_tasks(tasks) + for task in tasks: + task_path = Path(task) + task = task_path.parts[-1] + + # skip excluded tasks + for excluded_task in self.excluded_tasks: + if excluded_task in task: + log.info(f'Skipping excluded task [{task}]') + skip = True + break + else: + skip = False + + if skip: + continue + + user_id = task_path.parts[-5] + date = task_path.parts[-4] + experiment_id = task_path.parts[-3] + date_time = task_path.parts[-2] + task_name = task.split(date)[0].strip('_') + self.session_task_data.append( + BciPySessionTaskData( + path=task_path, + user_id=user_id, + date_time=date_time, + date=date, + experiment_id=experiment_id, + run=run, + task_name=task_name + ) + ) + run += 1 + + self.task_paths = [task.path for task in self.session_task_data] + + +def load_bcipy_data( + data_directory: str, + experiment_id: Optional[str] = None, + user_id: Optional[str] = None, + date: Optional[str] = None, + date_time: Optional[str] = None, + excluded_tasks: Optional[List[str]] = None, + anonymize: bool = False) -> List[BciPySessionTaskData]: + """Load BciPy data from a directory. + + Args: + data_directory: The BciPy data directory to walk. + experiment_id: Optional experiment ID to filter by. + user_id: Optional user ID to filter by. + date: Optional date to filter by. + date_time: Optional datetime to filter by. + excluded_tasks: Optional list of tasks to exclude. + anonymize: Whether to anonymize user IDs. + + Returns: + list: List of BciPySessionTaskData objects representing the experiment data. + + Note: + The BciPy data directory is structured as follows: + data/ + user_ids/ + dates/ + experiment_ids/ + datetimes/ + protocol.json + logs/ + tasks/ + raw_data.csv + triggers.txt + """ + if not excluded_tasks: + excluded_tasks = [] + + # add logs to the excluded tasks + excluded_tasks.append('logs') + + bcipy_data = BciPyCollection( + data_directory=data_directory, + experiment_id_filter=experiment_id, + user_id_filter=user_id, + date_filter=date, + date_time_filter=date_time, + excluded_tasks=excluded_tasks, + anonymize=anonymize + ) + return bcipy_data.collect() diff --git a/bcipy/helpers/save.py b/bcipy/io/save.py similarity index 83% rename from bcipy/helpers/save.py rename to bcipy/io/save.py index 98a232645..7578e6c01 100644 --- a/bcipy/helpers/save.py +++ b/bcipy/io/save.py @@ -9,13 +9,11 @@ from typing import Any, Dict, List, Tuple, Union from bcipy.acquisition.devices import DeviceSpec -from bcipy.config import (DEFAULT_ENCODING, - DEFAULT_EXPERIMENT_ID, +from bcipy.config import (DEFAULT_ENCODING, DEFAULT_EXPERIMENT_ID, DEFAULT_LM_PARAMETERS_FILENAME, DEFAULT_LM_PARAMETERS_PATH, DEFAULT_PARAMETERS_FILENAME, - SIGNAL_MODEL_FILE_SUFFIX, - STIMULI_POSITIONS_FILENAME) + SIGNAL_MODEL_FILE_SUFFIX, STIMULI_POSITIONS_FILENAME) from bcipy.signal.model.base_model import SignalModel @@ -40,6 +38,17 @@ def save_experiment_data( fields: dict, location: str, name: str) -> str: + """Save experiment data to a JSON file. + + Args: + experiments (dict): Experiment data to save. + fields (dict): Additional fields to save. + location (str): Directory to save the file. + name (str): Name of the file. + + Returns: + str: Path to the saved file. + """ return save_json_data(experiments, location, name) @@ -47,6 +56,16 @@ def save_field_data( fields: dict, location: str, name: str) -> str: + """Save field data to a JSON file. + + Args: + fields (dict): Field data to save. + location (str): Directory to save the file. + name (str): Name of the file. + + Returns: + str: Path to the saved file. + """ return save_json_data(fields, location, name) @@ -54,6 +73,16 @@ def save_experiment_field_data( data: dict, location: str, name: str) -> str: + """Save experiment field data to a JSON file. + + Args: + data (dict): Data to save. + location (str): Directory to save the file. + name (str): Name of the file. + + Returns: + str: Path to the saved file. + """ return save_json_data(data, location, name) @@ -97,7 +126,8 @@ def init_save_data_structure(data_save_path: str, copyfile(parameters, Path(save_directory, DEFAULT_PARAMETERS_FILENAME)) - copyfile(DEFAULT_LM_PARAMETERS_PATH, Path(save_directory, DEFAULT_LM_PARAMETERS_FILENAME)) + copyfile(DEFAULT_LM_PARAMETERS_PATH, Path( + save_directory, DEFAULT_LM_PARAMETERS_FILENAME)) return save_directory @@ -188,8 +218,8 @@ def save_stimuli_position_info( screen_info: Dict[str, Any]) -> str: """Save stimuli positions and screen info to `path` - stimuli_position_info: {'A': (0, 0)} - screen_info: {'screen_size_pixels': [1920, 1080], 'screen_refresh': 160} + stimuli_position_info: {'A': (0, 0)} + screen_info: {'screen_size_pixels': [1920, 1080], 'screen_refresh': 160} Parameters ---------- diff --git a/bcipy/io/tests/test_convert.py b/bcipy/io/tests/test_convert.py new file mode 100644 index 000000000..ec26682e1 --- /dev/null +++ b/bcipy/io/tests/test_convert.py @@ -0,0 +1,820 @@ +"""Tests for data conversion related functionality.""" +import os +import shutil +import tempfile +import unittest +from pathlib import Path +from typing import Tuple, Union +from unittest.mock import MagicMock, patch + +import mne + +import bcipy.acquisition.devices as devices +from bcipy.config import (DEFAULT_ENCODING, DEFAULT_PARAMETERS_FILENAME, + RAW_DATA_FILENAME, TRIGGER_FILENAME) +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawData, sample_data, write +from bcipy.core.triggers import MOCK_TRIGGER_DATA +from bcipy.io.convert import (BIDS_to_MNE, ConvertFormat, archive_list, + compress, convert_eyetracking_to_bids, + convert_to_bids, convert_to_mne, decompress, + norm_to_tobii, tobii_to_norm) +from bcipy.signal.generator.generator import gen_random_data + +CHANNEL_NAMES = [ + 'Fp1', 'Fp2', 'F3', 'F4', 'C3', 'C4', 'P3', 'P4', + 'O1', 'O2', 'F7', 'F8', 'T3', 'T4', 'T5', 'T6', 'Fz', 'Cz', 'Pz'] + + +def create_bcipy_session_artifacts( + write_dir: str, + channels: Union[int, list] = 3, + sample_rate: int = 300, + samples: int = 5000, + filter_settings: dict = { + 'filter_low': 0.5, + 'filter_high': 30, + 'filter_order': 5, + 'notch_filter_frequency': 60, + 'down_sampling_rate': 3 + }, +) -> Tuple[str, RawData, Parameters]: + """Write BciPy session artifacts to a temporary directory. + + This includes a raw data file, trigger file, and a parameters file. + """ + trg_data = MOCK_TRIGGER_DATA + if isinstance(channels, int): + + channels = [CHANNEL_NAMES[i] for i in range(channels)] + data = sample_data(ch_names=channels, daq_type='SampleDevice', + sample_rate=sample_rate, rows=samples) + devices.register(devices.DeviceSpec( + 'SampleDevice', channels=channels, sample_rate=sample_rate)) + + with open(Path(write_dir, TRIGGER_FILENAME), 'w', encoding=DEFAULT_ENCODING) as trg_file: + trg_file.write(trg_data) + + write(data, Path(write_dir, f'{RAW_DATA_FILENAME}.csv')) + + params = Parameters.from_cast_values(raw_data_name=f'{RAW_DATA_FILENAME}.csv', + trigger_file_name=TRIGGER_FILENAME, + preview_inquiry_length=0.5, + time_fixation=0.5, + time_prompt=0.5, + time_flash=0.5, + # define filter settings + down_sampling_rate=filter_settings['down_sampling_rate'], + notch_filter_frequency=filter_settings['notch_filter_frequency'], + filter_high=filter_settings['filter_high'], + filter_low=filter_settings['filter_low'], + filter_order=filter_settings['filter_order']) + params.save(write_dir, DEFAULT_PARAMETERS_FILENAME) + return trg_data, data, params + + +class TestBIDSConversion(unittest.TestCase): + + def setUp(self): + self.temp_dir = tempfile.mkdtemp() + self.trg_data, self.data, self.params = create_bcipy_session_artifacts( + self.temp_dir) + + def tearDown(self): + shutil.rmtree(self.temp_dir) + + def test_convert_to_bids_generates_bids_strucutre(self): + """Test the convert_to_bids function""" + response = convert_to_bids( + f"{self.temp_dir}", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + # Assert that the BIDS structure was created + self.assertTrue(os.path.exists(f"{self.temp_dir}")) + # Assert the session directory was created with eeg + self.assertTrue(os.path.exists(f"{self.temp_dir}/sub-01/ses-01/eeg/")) + # Assert the eeg file was created (default of BV format) + self.assertTrue(os.path.exists( + f"{self.temp_dir}/sub-01/ses-01/eeg/sub-01_ses-01_task-TestTask_run-01_eeg.vhdr")) + # Assert the events file was created + self.assertTrue(os.path.exists( + f"{self.temp_dir}/sub-01/ses-01/eeg/sub-01_ses-01_task-TestTask_run-01_events.tsv")) + # Assert the channels file was created + self.assertTrue(os.path.exists( + f"{self.temp_dir}/sub-01/ses-01/eeg/sub-01_ses-01_task-TestTask_run-01_channels.tsv")) + + def test_convert_to_bids_reflects_participant_id(self): + """Test the convert_to_bids function with a participant id""" + response = convert_to_bids( + f"{self.temp_dir}", + participant_id='100', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + self.assertTrue(os.path.exists(f"{self.temp_dir}/sub-100/")) + + def test_convert_to_bids_reflects_session_id(self): + """Test the convert_to_bids function with a session id""" + response = convert_to_bids( + f"{self.temp_dir}", + participant_id='01', + session_id='100', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + self.assertTrue(os.path.exists(f"{self.temp_dir}/sub-01/ses-100/")) + + def test_convert_to_bids_reflects_run_id(self): + """Test the convert_to_bids function with a run id""" + response = convert_to_bids( + f"{self.temp_dir}", + participant_id='01', + session_id='01', + run_id='100', + task_name='TestTask', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + self.assertTrue(os.path.exists( + f"{self.temp_dir}/sub-01/ses-01/eeg/sub-01_ses-01_task-TestTask_run-100_eeg.vhdr")) + + def test_convert_to_bids_reflects_task_name(self): + """Test the convert_to_bids function with a task name""" + response = convert_to_bids( + f"{self.temp_dir}", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTaskEtc', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + self.assertTrue(os.path.exists( + f"{self.temp_dir}/sub-01/ses-01/eeg/sub-01_ses-01_task-TestTaskEtc_run-01_eeg.vhdr")) + + def test_convert_to_bids_edf(self): + """Test the convert_to_bids function with edf format""" + response = convert_to_bids( + f"{self.temp_dir}", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + format=ConvertFormat.EDF + ) + + self.assertTrue(os.path.exists(response)) + # Assert that the BIDS structure was created + self.assertTrue(os.path.exists(f"{self.temp_dir}")) + # Assert the session directory was created with eeg + self.assertTrue(os.path.exists(f"{self.temp_dir}/sub-01/ses-01/eeg/")) + # Assert the eeg file was created (edf format) + self.assertTrue(os.path.exists( + f"{self.temp_dir}/sub-01/ses-01/eeg/sub-01_ses-01_task-TestTask_run-01_eeg.edf")) + # Assert the events file was created + self.assertTrue(os.path.exists( + f"{self.temp_dir}/sub-01/ses-01/eeg/sub-01_ses-01_task-TestTask_run-01_events.tsv")) + # Assert the channels file was created + self.assertTrue(os.path.exists( + f"{self.temp_dir}/sub-01/ses-01/eeg/sub-01_ses-01_task-TestTask_run-01_channels.tsv")) + + def test_convert_to_bids_raises_error_with_invalid_format(self): + """Test the convert_to_bids function raises an error with invalid format""" + with self.assertRaises(ValueError): + convert_to_bids( + f"{self.temp_dir}", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + format='invalid_format' + ) + + def test_convert_to_bids_raises_error_with_invalid_data_dir(self): + """Test the convert_to_bids function raises an error with invalid output directory""" + with self.assertRaises(FileNotFoundError): + convert_to_bids( + 'invalid_data_dir', + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir + ) + + def test_convert_to_bids_raises_error_with_invalid_line_freq(self): + """Test the convert_to_bids function raises an error with invalid line frequency""" + with self.assertRaises(ValueError): + convert_to_bids( + f"{self.temp_dir}", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + line_frequency=0 + ) + + +class TestMNEConvert(unittest.TestCase): + """Test the convert_to_mne function, which converts bcipy RawData into an mne format""" + + def setUp(self): + """Set up the test case with a temporary directory and sample data""" + self.temp_dir = tempfile.mkdtemp() + self.sample_rate = 300 + self.filter_settings = { + 'filter_low': 0.5, + 'filter_high': 30, + 'filter_order': 5, + 'notch_filter_frequency': 60, + 'down_sampling_rate': 3 + } + self.channels = ['timestamp', 'O1', 'O2', 'Pz', 'TRG', 'lsl_timestamp'] + self.raw_data = RawData( + 'SampleDevice', self.sample_rate, self.channels) + devices.register(devices.DeviceSpec( + 'SampleDevice', channels=self.channels, sample_rate=self.sample_rate)) + + # generate 100 random samples of data + for _ in range(0, 100): + channel_data = gen_random_data(low=-1000, + high=1000, + channel_count=len(self.channels)) + self.raw_data.append(channel_data) + + def tearDown(self): + """Remove the temporary directory and its contents after each test""" + shutil.rmtree(self.temp_dir) + + def test_convert_to_mne_defaults(self): + """Test the convert_to_mne function with default parameters""" + data = convert_to_mne(self.raw_data) + + self.assertTrue(len(data) > 0) + self.assertEqual(data.ch_names, self.channels[1:-2]) + self.assertEqual(data.info['sfreq'], self.sample_rate) + + def test_convert_to_mne_with_channel_map(self): + """Test the convert_to_mne function with channel mapping""" + # here we know only three channels are generated, using the channel map let's only use the last one + channel_map = [0, 0, 1, 0, 0] + data = convert_to_mne(self.raw_data, channel_map=channel_map) + + self.assertTrue(len(data) > 0) + self.assertTrue(len(data.ch_names) == 1) # this is the main assertion! + self.assertEqual(data.info['sfreq'], self.sample_rate) + + def test_convert_to_mne_with_remove_system_channels(self): + """Test the convert_to_mne function with system channels removed""" + data = convert_to_mne(self.raw_data, remove_system_channels=True) + + self.assertTrue(len(data) > 0) + self.assertEqual(data.ch_names, self.channels[1:-2]) + self.assertEqual(data.info['sfreq'], self.sample_rate) + + def test_convert_to_mne_without_remove_system_channels_throws_error(self): + """Test the convert_to_mne function with system channels removed raises an error. + + This is due to MNE requiring the channels be EEG. The system channels are not EEG. + """ + with self.assertRaises(ValueError): + data = convert_to_mne(self.raw_data, remove_system_channels=False) + + self.assertTrue(len(data) > 0) + self.assertEqual(data.ch_names, self.channels[1:]) + self.assertEqual(data.info['sfreq'], self.sample_rate) + + def test_convert_to_mne_with_channel_types(self): + """Test the convert_to_mne function with channel types""" + channel_types = ['eeg', 'eeg', 'seeg'] + data = convert_to_mne(self.raw_data, channel_types=channel_types) + + self.assertTrue(len(data) > 0) + self.assertEqual(data.ch_names, self.channels[1:-2]) + self.assertEqual(data.info['sfreq'], self.sample_rate) + self.assertTrue(data.get_channel_types()[2] == 'seeg') + + def test_convert_to_mne_with_transform(self): + """Test the convert_to_mne function with a transform""" + multiplier = 2 + + def transform(x, fs): + return x * multiplier, fs + + data = convert_to_mne(self.raw_data, transform=transform, volts=True) + + self.assertTrue(len(data) > 0) + self.assertEqual(data.ch_names, self.channels[1:-2]) + self.assertEqual(data.info['sfreq'], self.sample_rate) + + # apply the transform to the first data point and compare to data returned + expected_first_data_point = self.raw_data.channel_data[0][0] * multiplier + self.assertTrue(data.get_data()[0][0] == expected_first_data_point) + + def test_convert_to_mne_with_mv_conversion(self): + """Test the convert_to_mne function with a mv conversion""" + data = convert_to_mne(self.raw_data, volts=False) + + self.assertTrue(len(data) > 0) + self.assertEqual(data.ch_names, self.channels[1:-2]) + self.assertEqual(data.info['sfreq'], self.sample_rate) + + # apply the transform to the first data point and compare to data returned + expected_first_data_point = self.raw_data.channel_data[0][0] * 1e-6 + self.assertTrue(data.get_data()[0][0] == expected_first_data_point) + + def test_convert_to_mne_with_custom_montage(self): + """Test the convert_to_mne function with a custom montage""" + + # see https://mne.tools/stable/auto_tutorials/intro/40_sensor_locations.html + # for more information on montages and available defaults + montage_type = 'biosemi64' + data = convert_to_mne(self.raw_data, montage=montage_type) + + self.assertTrue(len(data) > 0) + self.assertEqual(data.ch_names, self.channels[1:-2]) + self.assertEqual(data.info['sfreq'], self.sample_rate) + + def test_convert_to_mne_with_custom_channel_types_length_mismatch(self): + """Test the convert_to_mne function raises an error when channel types length doesn't match channels""" + # Not enough channel types + channel_types = ['eeg', 'eeg'] # Only 2 types for 3 channels + + with self.assertRaises(AssertionError): + convert_to_mne(self.raw_data, channel_types=channel_types) + + +class TestCompressionSupport(unittest.TestCase): + + def setUp(self): + self.dir_name = 'test/' + self.tar_file_name = 'test_file' + self.tar_file_full_name = f'{self.tar_file_name}.tar.gz' + self.test_file_name = 'test.text' + with open(self.test_file_name, 'w', encoding=DEFAULT_ENCODING) as fp: + pass + + def tearDown(self): + os.remove(self.test_file_name) + + if os.path.exists(self.tar_file_full_name): + os.remove(self.tar_file_full_name) + + def test_compression_writes_tar_gz_no_extension(self): + # Test with no extension on tar name + compress(self.tar_file_name, [self.test_file_name]) + # Assert correct file was written + self.assertTrue(os.path.exists(self.tar_file_full_name)) + + def test_compression_writes_tar_gz_with_extension(self): + # Test with extension on tar name + compress(self.tar_file_full_name, [self.test_file_name]) + # Assert correct file was written + self.assertTrue(os.path.exists(self.tar_file_full_name)) + + def test_decompression_extracts_file_no_extension(self): + # Test with no extension on tar name + compress(self.tar_file_name, [self.test_file_name]) + decompress(self.tar_file_name, ".") + self.assertTrue(os.path.exists(self.test_file_name)) + + def test_decompression_extracts_file_with_extension(self): + # Test with extension on tar name + compress(self.tar_file_name, [self.test_file_name]) + decompress(self.tar_file_full_name, ".") + self.assertTrue(os.path.exists(self.test_file_name)) + + def test_file_not_found_error_thrown_on_compression(self): + garbage_name = 'not_possible_to_exist.biz' + with self.assertRaises(FileNotFoundError): + compress(self.tar_file_name, [garbage_name]) + + def test_file_list_returns_compressed_file_name_no_extension(self): + # Test with no extension on tar name + compress(self.tar_file_name, [self.test_file_name]) + tar_list = archive_list(self.tar_file_name) + self.assertTrue(tar_list[0] == self.test_file_name) + + def test_file_list_returns_compressed_file_name_with_extension(self): + # Test with extension on tar name + compress(self.tar_file_name, [self.test_file_name]) + tar_list = archive_list(self.tar_file_full_name) + self.assertTrue(tar_list[0] == self.test_file_name) + + +class TestConvertTobii(unittest.TestCase): + + def test_tobii_to_norm(self): + """Test the tobii_to_norm function""" + tobii_data = (0.5, 0.5) # center of screen in tobii coordinates + excepted_norm_data = (0, 0) # center of screen in norm coordinates + norm_data = tobii_to_norm(tobii_data) + self.assertEqual(norm_data, excepted_norm_data) + + tobii_data = (0, 0) # top left of screen in tobii coordinates + excepted_norm_data = (-1, 1) # top left of screen in norm coordinates + norm_data = tobii_to_norm(tobii_data) + self.assertEqual(norm_data, excepted_norm_data) + + tobii_data = (1, 1) # bottom right of screen in tobii coordinates + # bottom right of screen in norm coordinates + excepted_norm_data = (1, -1) + norm_data = tobii_to_norm(tobii_data) + self.assertEqual(norm_data, excepted_norm_data) + + def test_tobii_to_norm_raises_error_with_invalid_units(self): + """Test the tobii_to_norm function raises an error with invalid units""" + tobii_data = (-1, 1) # invalid tobii coordinates + with self.assertRaises(AssertionError): + tobii_to_norm(tobii_data) + + tobii_data = (1, 11) # invalid tobii coordinates + + with self.assertRaises(AssertionError): + tobii_to_norm(tobii_data) + + def test_norm_to_tobii(self): + """Test the norm_to_tobii function""" + norm_data = (0, 0) # center of screen in norm coordinates + # center of screen in tobii coordinates + excepted_tobii_data = (0.5, 0.5) + tobii_data = norm_to_tobii(norm_data) + self.assertEqual(tobii_data, excepted_tobii_data) + + norm_data = (-1, 1) # top left of screen in norm coordinates + excepted_tobii_data = (0, 0) # top left of screen in tobii coordinates + tobii_data = norm_to_tobii(norm_data) + self.assertEqual(tobii_data, excepted_tobii_data) + + norm_data = (1, -1) # bottom right of screen in norm coordinates + # bottom right of screen in tobii coordinates + excepted_tobii_data = (1, 1) + tobii_data = norm_to_tobii(norm_data) + self.assertEqual(tobii_data, excepted_tobii_data) + + def test_norm_to_tobii_raises_error_with_invalid_units(self): + """Test the norm_to_tobii function raises an error with invalid units""" + norm_data = (-1.1, 1) + with self.assertRaises(AssertionError): + norm_to_tobii(norm_data) + + norm_data = (1, 1.1) + with self.assertRaises(AssertionError): + norm_to_tobii(norm_data) + + +class TestConvertETBIDS(unittest.TestCase): + + def setUp(self): + self.temp_dir = tempfile.mkdtemp() + self.trg_data, self.data, self.params = create_bcipy_session_artifacts( + self.temp_dir, channels=3) + self.eyetracking_data = sample_data( + ch_names=[ + 'timestamp', + 'x', + 'y', + 'pupil'], + daq_type='Gaze', + sample_rate=60, + rows=5000) + devices.register(devices.DeviceSpec('Gaze', channels=[ + 'timestamp', 'x', 'y', 'pupil'], sample_rate=60)) + + write(self.eyetracking_data, Path(self.temp_dir, 'eyetracker.csv')) + + def tearDown(self): + shutil.rmtree(self.temp_dir) + + def test_convert_eyetracking_to_bids_generates_bids_strucutre(self): + """Test the convert_eyetracking_to_bids function""" + response = convert_eyetracking_to_bids( + f"{self.temp_dir}/", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + # Assert the session directory was created with et + self.assertTrue(os.path.exists(f"{self.temp_dir}/et/")) + # Assert the et tsv file was created with the correct name + self.assertTrue(os.path.exists( + f"{self.temp_dir}/et/sub-01_ses-01_task-TestTask_run-01_eyetracking.tsv")) + + def test_convert_eyetracking_to_bids_reflects_participant_id(self): + """Test the convert_eyetracking_to_bids function with a participant id""" + response = convert_eyetracking_to_bids( + f"{self.temp_dir}/", + participant_id='100', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + # Assert the et tsv file was created with the correct name + self.assertTrue(os.path.exists( + f"{self.temp_dir}/et/sub-100_ses-01_task-TestTask_run-01_eyetracking.tsv")) + + def test_convert_eyetracking_to_bids_reflects_session_id(self): + """Test the convert_eyetracking_to_bids function with a session id""" + response = convert_eyetracking_to_bids( + f"{self.temp_dir}/", + participant_id='01', + session_id='100', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + # Assert the et tsv file was created with the correct name + self.assertTrue(os.path.exists( + f"{self.temp_dir}/et/sub-01_ses-100_task-TestTask_run-01_eyetracking.tsv")) + + def test_convert_eyetracking_to_bids_reflects_run_id(self): + """Test the convert_eyetracking_to_bids function with a run id""" + response = convert_eyetracking_to_bids( + f"{self.temp_dir}/", + participant_id='01', + session_id='01', + run_id='100', + task_name='TestTask', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + # Assert the et tsv file was created with the correct name + self.assertTrue(os.path.exists( + f"{self.temp_dir}/et/sub-01_ses-01_task-TestTask_run-100_eyetracking.tsv")) + + def test_convert_eyetracking_to_bids_reflects_task_name(self): + """Test the convert_eyetracking_to_bids function with a task name""" + response = convert_eyetracking_to_bids( + f"{self.temp_dir}/", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTaskEtc', + output_dir=self.temp_dir, + ) + self.assertTrue(os.path.exists(response)) + # Assert the et tsv file was created with the correct name + self.assertTrue(os.path.exists( + f"{self.temp_dir}/et/sub-01_ses-01_task-TestTaskEtc_run-01_eyetracking.tsv")) + + def test_convert_et_raises_error_with_invalid_data_dir(self): + """Test the convert_eyetracking_to_bids function raises an error with invalid output directory""" + with self.assertRaises(FileNotFoundError): + convert_eyetracking_to_bids( + 'invalid_data_dir', + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir + ) + + def test_convert_et_raises_error_with_output_dir_not_exist(self): + """Test the convert_eyetracking_to_bids function raises an error with invalid output directory""" + with self.assertRaises(FileNotFoundError): + convert_eyetracking_to_bids( + f"{self.temp_dir}/", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir='invalid_output_dir' + ) + + def test_convert_et_raises_error_with_no_data_file(self): + """Test the convert_eyetracking_to_bids function raises an error with no data file""" + # remove the csv file + os.remove(f"{self.temp_dir}/eyetracker.csv") + with self.assertRaises(FileNotFoundError): + convert_eyetracking_to_bids( + f"{self.temp_dir}/", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + ) + + def test_convert_et_raises_error_with_multiple_data_files(self): + """Test the convert_eyetracking_to_bids function raises an error with multiple data files""" + # create a second data file + write(self.eyetracking_data, Path(self.temp_dir, 'eyetracker_2.csv')) + with self.assertRaises(ValueError): + convert_eyetracking_to_bids( + f"{self.temp_dir}/", + participant_id='01', + session_id='01', + run_id='01', + task_name='TestTask', + output_dir=self.temp_dir, + ) + + +class TestBIDSToMNE(unittest.TestCase): + """Tests for the BIDS_to_MNE function.""" + + @patch('bcipy.io.convert.os.path.exists') + @patch('bcipy.io.convert.get_entity_vals') + @patch('bcipy.io.convert.find_matching_paths') + @patch('bcipy.io.convert.read_raw_bids') + def test_successful_conversion(self, mock_read_raw_bids, mock_find_matching_paths, + mock_get_entity_vals, mock_path_exists): + """Test successful conversion from BIDS to MNE.""" + # Setup mocks + mock_path_exists.return_value = True + mock_get_entity_vals.return_value = ['01'] + + # Create mock BIDSPath objects + mock_bids_path1 = MagicMock() + mock_bids_path1.task = 'RSVPCalibration' + mock_bids_path2 = MagicMock() + mock_bids_path2.task = 'RSVPCalibration' + mock_find_matching_paths.return_value = [ + mock_bids_path1, mock_bids_path2] + + # Create mock Raw objects that read_raw_bids will return + mock_raw1 = MagicMock(spec=mne.io.Raw) + mock_raw2 = MagicMock(spec=mne.io.Raw) + mock_read_raw_bids.side_effect = [mock_raw1, mock_raw2] + + result = BIDS_to_MNE('/fake/bids/path', task_name='RSVPCalibration') + + self.assertEqual(len(result), 2) + self.assertIs(result[0], mock_raw1) + self.assertIs(result[1], mock_raw2) + mock_path_exists.assert_called_once_with('/fake/bids/path') + mock_get_entity_vals.assert_called_once_with( + '/fake/bids/path', 'session') + mock_find_matching_paths.assert_called_once() + self.assertEqual(mock_read_raw_bids.call_count, 2) + + @patch('bcipy.io.convert.os.path.exists') + def test_nonexistent_path(self, mock_path_exists): + """Test handling of non-existent BIDS path.""" + mock_path_exists.return_value = False + + with self.assertRaises(FileNotFoundError): + BIDS_to_MNE('/nonexistent/path') + + mock_path_exists.assert_called_once_with('/nonexistent/path') + + @patch('bcipy.io.convert.os.path.exists') + @patch('bcipy.io.convert.get_entity_vals') + @patch('bcipy.io.convert.find_matching_paths') + def test_no_matching_files(self, mock_find_matching_paths, mock_get_entity_vals, mock_path_exists): + """Test handling of no matching BIDS files.""" + mock_path_exists.return_value = True + mock_get_entity_vals.return_value = ['01'] + mock_find_matching_paths.return_value = [] + + with self.assertRaises(FileNotFoundError): + BIDS_to_MNE('/fake/bids/path') + + mock_path_exists.assert_called_once_with('/fake/bids/path') + mock_get_entity_vals.assert_called_once_with( + '/fake/bids/path', 'session') + mock_find_matching_paths.assert_called_once() + + @patch('bcipy.io.convert.os.path.exists') + @patch('bcipy.io.convert.get_entity_vals') + @patch('bcipy.io.convert.find_matching_paths') + @patch('bcipy.io.convert.read_raw_bids') + # Mock the logger to prevent actual logging during tests + @patch('bcipy.io.convert.logger') + def test_task_filtering(self, mock_logger, mock_read_raw_bids, mock_find_matching_paths, + mock_get_entity_vals, mock_path_exists): + """Test task name filtering.""" + # Setup mocks + mock_path_exists.return_value = True + mock_get_entity_vals.return_value = ['01'] + + # Create mock BIDSPath objects with different tasks + mock_bids_path1 = MagicMock() + mock_bids_path1.task = 'RSVPCalibration' + mock_bids_path2 = MagicMock() + mock_bids_path2.task = 'OtherTask' + mock_find_matching_paths.return_value = [ + mock_bids_path1, mock_bids_path2] + + # Create mock Raw object that read_raw_bids will return + mock_raw = MagicMock(spec=mne.io.Raw) + mock_read_raw_bids.return_value = mock_raw + + # Call function with specific task_name + result = BIDS_to_MNE('/fake/bids/path', task_name='RSVPCalibration') + + # Assertions + self.assertEqual(len(result), 1) + self.assertIs(result[0], mock_raw) + mock_read_raw_bids.assert_called_once_with(mock_bids_path1) + + @patch('bcipy.io.convert.os.path.exists') + @patch('bcipy.io.convert.get_entity_vals') + @patch('bcipy.io.convert.find_matching_paths') + @patch('bcipy.io.convert.read_raw_bids') + def test_multiple_sessions(self, mock_read_raw_bids, mock_find_matching_paths, + mock_get_entity_vals, mock_path_exists): + """Test handling multiple sessions.""" + # Setup mocks + mock_path_exists.return_value = True + mock_get_entity_vals.return_value = ['01', '02'] # Multiple sessions + + # Create mock BIDSPath objects for different sessions + mock_bids_path1 = MagicMock() + mock_bids_path1.task = 'RSVPCalibration' + mock_bids_path1.session = '01' + mock_bids_path2 = MagicMock() + mock_bids_path2.task = 'RSVPCalibration' + mock_bids_path2.session = '02' + mock_find_matching_paths.return_value = [ + mock_bids_path1, mock_bids_path2] + + # Create mock Raw objects + mock_raw1 = MagicMock(spec=mne.io.Raw) + mock_raw2 = MagicMock(spec=mne.io.Raw) + mock_read_raw_bids.side_effect = [mock_raw1, mock_raw2] + + result = BIDS_to_MNE('/fake/bids/path') + + self.assertEqual(len(result), 2) + mock_get_entity_vals.assert_called_once_with( + '/fake/bids/path', 'session') + self.assertEqual(mock_read_raw_bids.call_count, 2) + + @patch('bcipy.io.convert.os.path.exists') + @patch('bcipy.io.convert.get_entity_vals') + @patch('bcipy.io.convert.find_matching_paths') + @patch('bcipy.io.convert.read_raw_bids') + def test_extension_filtering(self, mock_read_raw_bids, mock_find_matching_paths, + mock_get_entity_vals, mock_path_exists): + """Test file extension filtering.""" + mock_path_exists.return_value = True + mock_get_entity_vals.return_value = ['01'] + + # Check that the function properly searches for supported extensions + mock_find_matching_paths.return_value = [] + + with self.assertRaises(FileNotFoundError): + BIDS_to_MNE('/fake/bids/path') + + # Verify extensions were specified in the find_matching_paths call + call_args = mock_find_matching_paths.call_args[1] + self.assertIn('extensions', call_args) + self.assertTrue(len(call_args['extensions']) > 0) + self.assertIn('.vhdr', call_args['extensions']) # BrainVision format + self.assertIn('.edf', call_args['extensions']) # EDF format + + @patch('bcipy.io.convert.os.path.exists') + @patch('bcipy.io.convert.get_entity_vals') + @patch('bcipy.io.convert.find_matching_paths') + @patch('bcipy.io.convert.read_raw_bids') + @patch('bcipy.io.convert.logger') + def test_debug_logging(self, mock_logger, mock_read_raw_bids, mock_find_matching_paths, + mock_get_entity_vals, mock_path_exists): + """Test debug logging when skipping files due to task name mismatch.""" + mock_path_exists.return_value = True + mock_get_entity_vals.return_value = ['01'] + + # Create mock BIDSPath objects with different tasks + mock_bids_path1 = MagicMock() + mock_bids_path1.task = 'RSVPCalibration' + mock_bids_path2 = MagicMock() + mock_bids_path2.task = 'OtherTask' + mock_find_matching_paths.return_value = [ + mock_bids_path1, mock_bids_path2] + + # Mock the debug logging method specifically + mock_logger.debug = MagicMock() + + # Create mock Raw object + mock_raw = MagicMock(spec=mne.io.Raw) + mock_read_raw_bids.return_value = mock_raw + + BIDS_to_MNE('/fake/bids/path', task_name='RSVPCalibration') + + # Check if debug was called for skipping a file + self.assertTrue(any('Skipping' in str(args) + for args, _ in mock_logger.debug.call_args_list)) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/helpers/tests/test_load.py b/bcipy/io/tests/test_load.py similarity index 59% rename from bcipy/helpers/tests/test_load.py rename to bcipy/io/tests/test_load.py index ceaaf6890..cdc4cd379 100644 --- a/bcipy/helpers/tests/test_load.py +++ b/bcipy/io/tests/test_load.py @@ -11,13 +11,14 @@ from bcipy.config import (DEFAULT_ENCODING, DEFAULT_EXPERIMENT_PATH, DEFAULT_FIELD_PATH, DEFAULT_PARAMETERS_PATH, EXPERIMENT_FILENAME, FIELD_FILENAME) +from bcipy.core.parameters import Parameters from bcipy.exceptions import BciPyCoreException, InvalidExperimentException -from bcipy.helpers.load import (choose_signal_model, choose_signal_models, - copy_parameters, extract_mode, - load_experiment_fields, load_experiments, - load_fields, load_json_parameters, - load_signal_model, load_users) -from bcipy.helpers.parameters import Parameters +from bcipy.io.load import (choose_signal_model, choose_signal_models, + copy_parameters, extract_mode, load_bcipy_data, + load_experiment_fields, load_experiments, + load_fields, load_json_parameters, + load_signal_model, load_users) +from bcipy.io.tests.test_convert import create_bcipy_session_artifacts MOCK_EXPERIMENT = { "test": { @@ -88,7 +89,8 @@ def tearDown(self): def test_load_experiments_calls_open_with_expected_default(self): with patch('builtins.open', mock_open(read_data='data')) as mock_file: load_experiments() - mock_file.assert_called_with(self.experiments_path, 'r', encoding=DEFAULT_ENCODING) + mock_file.assert_called_with( + self.experiments_path, 'r', encoding=DEFAULT_ENCODING) def test_load_experiments_throws_file_not_found_exception_with_invalid_path(self): with self.assertRaises(FileNotFoundError): @@ -111,7 +113,8 @@ def tearDown(self): def test_load_fields_calls_open_with_expected_default(self): with patch('builtins.open', mock_open(read_data='data')) as mock_file: load_fields() - mock_file.assert_called_with(self.fields_path, 'r', encoding=DEFAULT_ENCODING) + mock_file.assert_called_with( + self.fields_path, 'r', encoding=DEFAULT_ENCODING) def test_load_fields_throws_file_not_found_exception_with_invalid_path(self): with self.assertRaises(FileNotFoundError): @@ -213,8 +216,8 @@ def test_extract_mode_without_mode_defined(self): class TestModelLoad(unittest.TestCase): """Test loading one or more signal models""" - @patch("bcipy.helpers.load.pickle.load") - @patch("bcipy.helpers.load.open") + @patch("bcipy.io.load.pickle.load") + @patch("bcipy.io.load.open") def test_load_model(self, open_mock, pickle_mock): """Test loading a signal model""" @@ -222,9 +225,9 @@ def test_load_model(self, open_mock, pickle_mock): open_mock.assert_called_with("test-directory", 'rb') pickle_mock.assert_called_once() - @patch("bcipy.helpers.load.load_signal_model") - @patch("bcipy.helpers.load.ask_filename") - @patch("bcipy.helpers.load.preferences") + @patch("bcipy.io.load.load_signal_model") + @patch("bcipy.io.load.ask_filename") + @patch("bcipy.io.load.preferences") def test_choose_model(self, preferences_mock, ask_file_mock, load_signal_model_mock): """Test choosing a model""" @@ -245,9 +248,9 @@ def test_choose_model(self, preferences_mock, ask_file_mock, preferences_mock.signal_model_directory, msg="Should have updated the preferences") - @patch("bcipy.helpers.load.load_signal_model") - @patch("bcipy.helpers.load.ask_filename") - @patch("bcipy.helpers.load.preferences") + @patch("bcipy.io.load.load_signal_model") + @patch("bcipy.io.load.ask_filename") + @patch("bcipy.io.load.preferences") def test_choose_model_with_cancel(self, preferences_mock, ask_file_mock, load_signal_model_mock): """Test choosing a model""" @@ -268,7 +271,7 @@ def test_choose_model_with_cancel(self, preferences_mock, ask_file_mock, preferences_mock.signal_model_directory, msg="Should not have updated the preferences") - @patch("bcipy.helpers.load.choose_signal_model") + @patch("bcipy.io.load.choose_signal_model") def test_choose_signal_models(self, choose_signal_model_mock): """Test choosing signal models""" eeg_mock = Mock() @@ -278,7 +281,7 @@ def test_choose_signal_models(self, choose_signal_model_mock): models = choose_signal_models(['EEG', 'Eyetracker']) self.assertListEqual([eeg_mock, eyetracker_mock], models) - @patch("bcipy.helpers.load.choose_signal_model") + @patch("bcipy.io.load.choose_signal_model") def test_choose_signal_models_missing_model(self, choose_signal_model_mock): """Test choosing signal models""" @@ -290,5 +293,120 @@ def test_choose_signal_models_missing_model(self, self.assertListEqual([eyetracker_mock], models) +class TestLoadBciPyData(unittest.TestCase): + """data_directory/ + user_ids/ + dates/ + experiment_ids/ + datetimes/ + protocol.json + logs/ + tasks/ + *task_data*""" + + def setUp(self): + # make a temporary directory mimicking the structure of the data directory + self.data_dir = tempfile.mkdtemp() + self.user_ids = ['user1', 'user2'] + self.dates = ['2024-10-31', '2024-10-32'] + self.experiment_ids = ['experiment1', 'experiment2'] + self.datetimes = ['2024-10-31_15-01-05', '2024-10-32_15-01-07'] + self.tasks = ['task1', 'task2'] + + # create the directory structure + for user_id in self.user_ids: + user_dir = os.path.join(self.data_dir, user_id) + os.makedirs(user_dir) + for date in self.dates: + date_dir = os.path.join(user_dir, date) + os.makedirs(date_dir) + for experiment_id in self.experiment_ids: + experiment_dir = os.path.join(date_dir, experiment_id) + os.makedirs(experiment_dir) + for datetime in self.datetimes: + datetime_dir = os.path.join(experiment_dir, datetime) + os.makedirs(datetime_dir) + for task in self.tasks: + task_dir = os.path.join(datetime_dir, task) + os.makedirs(task_dir) + # create artificial files + create_bcipy_session_artifacts(task_dir) + + def tearDown(self): + shutil.rmtree(self.data_dir) + + def test_load_bcipy_data(self): + total_expected_files = len(self.user_ids) * len(self.dates) * len(self.experiment_ids) * \ + len(self.datetimes) * len(self.tasks) + response = load_bcipy_data(self.data_dir) + self.assertEqual(len(response), total_expected_files) + + def test_load_bcipy_data_with_invalid_directory(self): + with self.assertRaises(FileNotFoundError): + load_bcipy_data('') + + def test_load_bcipy_data_with_user_id_filter(self): + # pick one user id to filter + user_id = self.user_ids[0] + total_expected_files = len(self.dates) * len(self.experiment_ids) * \ + len(self.datetimes) * len(self.tasks) + response = load_bcipy_data(self.data_dir, user_id=user_id) + self.assertEqual(len(response), total_expected_files) + + def test_load_bcipy_data_with_task_filter(self): + excluded_task = [self.tasks[0]] + total_expected_files = len(self.user_ids) * len(self.dates) * len(self.experiment_ids) * \ + len(self.datetimes) * (len(self.tasks) - 1) + response = load_bcipy_data(self.data_dir, excluded_tasks=excluded_task) + self.assertEqual(len(response), total_expected_files) + + def test_load_bcipy_data_with_date_filter(self): + desired_date = self.dates[0] + + total_expected_files = len(self.user_ids) * (len(self.dates) - 1) * len(self.experiment_ids) * \ + len(self.datetimes) * len(self.tasks) + + response = load_bcipy_data(self.data_dir, date=desired_date) + self.assertEqual(len(response), total_expected_files) + # check that the date is in the response + dates = [file.date for file in response] + self.assertIn(desired_date, dates) + + def test_load_bcipy_data_with_experiment_id_filter(self): + desired_experiment_id = self.experiment_ids[0] + + total_expected_files = len(self.user_ids) * len(self.dates) * (len(self.experiment_ids) - 1) * \ + len(self.datetimes) * len(self.tasks) + response = load_bcipy_data( + self.data_dir, experiment_id=desired_experiment_id) + + self.assertEqual(len(response), total_expected_files) + experiments = [file.experiment_id for file in response] + # check that the experiment id is in the response + self.assertIn(desired_experiment_id, experiments) + self.assertNotIn(self.experiment_ids[1], experiments) + + def test_load_bcipy_data_with_datetime_filter(self): + desired_datetime = self.datetimes[0] + + total_expected_files = len(self.user_ids) * len(self.dates) * len(self.experiment_ids) * \ + (len(self.datetimes) - 1) * len(self.tasks) + response = load_bcipy_data(self.data_dir, date_time=desired_datetime) + + self.assertEqual(len(response), total_expected_files) + # check that the datetime is in the response + datetimes = [file.date_time for file in response] + self.assertIn(desired_datetime, datetimes) + self.assertNotIn(self.datetimes[1], datetimes) + + def test_load_bcipy_data_with_anonymize(self): + """Test that the user ids are not in the response when anonymize is True""" + response = load_bcipy_data(self.data_dir, anonymize=True) + + users = [file.user_id for file in response] + self.assertNotIn(self.user_ids[0], users) + self.assertNotIn(self.user_ids[1], users) + + if __name__ == '__main__': unittest.main() diff --git a/bcipy/helpers/tests/test_save.py b/bcipy/io/tests/test_save.py similarity index 83% rename from bcipy/helpers/tests/test_save.py rename to bcipy/io/tests/test_save.py index ba46b4a25..78b63fff5 100644 --- a/bcipy/helpers/tests/test_save.py +++ b/bcipy/io/tests/test_save.py @@ -1,18 +1,16 @@ +import json import os import shutil -import unittest import tempfile -import json +import unittest -from bcipy.config import ( - DEFAULT_PARAMETERS_PATH, - DEFAULT_PARAMETERS_FILENAME, - DEFAULT_EXPERIMENT_ID, - STIMULI_POSITIONS_FILENAME) -from bcipy.helpers import save -from bcipy.helpers.save import init_save_data_structure, save_stimuli_position_info from mockito import any, unstub, when +from bcipy.config import (DEFAULT_EXPERIMENT_ID, DEFAULT_PARAMETERS_FILENAME, + DEFAULT_PARAMETERS_PATH, STIMULI_POSITIONS_FILENAME) +from bcipy.io import save +from bcipy.io.save import init_save_data_structure, save_stimuli_position_info + class TestSave(unittest.TestCase): """This is Test Case for Saving BCI data.""" @@ -101,11 +99,14 @@ def tearDown(self): shutil.rmtree(self.save_directory) def test_save_stimuli_position_info_writes_json(self): - save_stimuli_position_info(self.stimuli_positions, self.save_directory, self.screen_info) - self.assertTrue(os.path.isfile(os.path.join(self.save_directory, self.filename))) + save_stimuli_position_info( + self.stimuli_positions, self.save_directory, self.screen_info) + self.assertTrue(os.path.isfile( + os.path.join(self.save_directory, self.filename))) def test_save_stimuli_position_info_writes_correct_json(self): - save_stimuli_position_info(self.stimuli_positions, self.save_directory, self.screen_info) + save_stimuli_position_info( + self.stimuli_positions, self.save_directory, self.screen_info) # load the json file with open(os.path.join(self.save_directory, self.filename)) as f: data = json.load(f) diff --git a/bcipy/language/README.md b/bcipy/language/README.md index 1438a7455..49d5c4703 100644 --- a/bcipy/language/README.md +++ b/bcipy/language/README.md @@ -1,6 +1,6 @@ # Language -BciPy Language module provides an interface for word and character level predictions. +BciPy Language module provides an interface for word and character level predictions. This module primarily relies upon the TextSlinger package (textslinger on PyPI) for its probability calculations. More information on this package can be found on our [GitHub repo](https://github.com/kdv123/textpredict) The core methods of any `LanguageModel` include: @@ -8,8 +8,6 @@ The core methods of any `LanguageModel` include: > `load` - load a pre-trained model given a path (currently BciPy does not support training language models!) -> `update` - update internal state of your model. - You may of course define other methods, however all integrated BciPy experiments using your model will require those to be defined! The language module has the following structure: @@ -30,23 +28,23 @@ The language module has the following structure: The UniformLanguageModel provides equal probabilities for all symbols in the symbol set. This model is useful for evaluating other aspects of the system, such as EEG signal quality, without any influence from a language model. -## KenLM Model -The KenLMLanguageModel utilizes a pretrained n-gram language model to generate probabilities for all symbols in the symbol set. N-gram models use frequencies of different character sequences to generate their predictions. Models trained on AAC-like data can be found [here](https://imagineville.org/software/lm/dec19_char/). For faster load times, it is recommended to use the binary models located at the bottom of the page. The default parameters file utilizes `lm_dec19_char_large_12gram.kenlm`. If you have issues accessing, please reach out to us on GitHub or via email at `cambi_support@googlegroups.com`. +## NGram Model + +The NGramLanguageModelAdapter utilizes a pretrained n-gram language model to generate probabilities for all symbols in the symbol set. N-gram models use frequencies of different character sequences to generate their predictions. Models trained on AAC-like data can be found [here](https://imagineville.org/software/lm/dec19_char/). For faster load times, it is recommended to use the binary models located at the bottom of the page. The default parameters file utilizes `lm_dec19_char_large_12gram.kenlm`. If you have issues accessing, please reach out to us on GitHub or via email at `cambi_support@googlegroups.com`. For models that import the kenlm module, this must be manually installed using `pip install kenlm==0.1 --global-option="max_order=12"`. ## Causal Model -The CausalLanguageModel class can use any causal language model from Huggingface, though it has only been tested with gpt2, facebook/opt, and distilgpt2 families of models. Causal language models predict the next token in a sequence of tokens. For the many of these models, byte-pair encoding (BPE) is used for tokenization. The main idea of BPE is to create a fixed-size vocabulary that contains common English subword units. Then a less common word would be broken down into several subword units in the vocabulary. For example, the tokenization of character sequence `peanut_butter_and_jel` would be: -> *['pe', 'anut', '_butter', '_and', '_j', 'el']* -Therefore, in order to generate a predictive distribution on the next character, we need to examine all the possibilities that could complete the final subword tokens in the input sequences. We must remove at least one token from the end of the context to allow the model the option of extending it, as opposed to only adding a new token. Removing more tokens allows the model more flexibility and may lead to better predictions, but at the cost of a higher prediction time. In this model we remove all of the subword tokens in the current (partially-typed) word to allow it the most flexibility. We then ask the model to estimate the likelihood of the next token and evaluate each token that matches our context. For efficiency, we only track a certain number of hypotheses at a time, known as the beam width, and each hypothesis until it surpasses the context. We can then store the likelihood for each final prediction in a list based on the character that directly follows the context. Once we have no more hypotheses to extend, we can sum the likelihoods stored for each character in our symbol set and normalize so they sum to 1, giving us our final distribution. +The CausalLanguageModelAdapter class can use any causal language model from Huggingface, though it has only been tested with gpt2, facebook/opt, and distilgpt2 families of models (including the domain-adapted figmtu/opt-350m-aac). Causal language models predict the next token in a sequence of tokens. For the many of these models, byte-pair encoding (BPE) is used for tokenization. The main idea of BPE is to create a fixed-size vocabulary that contains common English subword units. Then a less common word would be broken down into several subword units in the vocabulary. For example, the tokenization of character sequence `peanut_butter_and_jel` would be: +> *['pe', 'anut', '_butter', '_and', '_j', 'el']* +Therefore, in order to generate a predictive distribution on the next character, we need to examine all the possibilities that could complete the final subword tokens in the input sequences. We must remove at least one token from the end of the context to allow the model the option of extending it, as opposed to only adding a new token. Removing more tokens allows the model more flexibility and may lead to better predictions, but at the cost of a higher prediction time. In this model we remove all of the subword tokens in the current (partially-typed) word to allow it the most flexibility. We then ask the model to estimate the likelihood of the next token and evaluate each token that matches our context. For efficiency, we only track a certain number of hypotheses at a time, known as the beam width, and each hypothesis until it surpasses the context. We can then store the likelihood for each final prediction in a list based on the character that directly follows the context. Once we have no more hypotheses to extend, we can sum the likelihoods stored for each character in our symbol set and normalize so they sum to 1, giving us our final distribution. More details on this process can be found in our paper, [Adapting Large Language Models for Character-based Augmentative and Alternative Communication](https://arxiv.org/abs/2501.10582). ## Mixture Model -The MixtureLanguageModel class allows for the combination of two or more supported models. The selected models are mixed according to the provided weights, which can be tuned using the Bcipy/scripts/python/mixture_tuning.py script. It is not recommended to use more than one "heavy-weight" model with long prediction times (the CausalLanguageModel) since this model will query each component model and parallelization is not currently supported. - -# Contact Information -For language model related questions, please contact Dylan Gaines (dcgaines [[at](https://en.wikipedia.org/wiki/At_sign)] mtu.edu) or create an issue. +The MixtureLanguageModelAdapter class allows for the combination of two or more supported models. The selected models are mixed according to the provided weights. It is not recommended to use more than one "heavy-weight" model with long prediction times (the CausalLanguageModel) since this model will query each component model and parallelization is not currently supported. +## Contact Information +For language model related questions, please contact Dylan Gaines (dcgaines [[at](https://en.wikipedia.org/wiki/At_sign)] mtu.edu) or create a GitHub issue. diff --git a/bcipy/language/__init__.py b/bcipy/language/__init__.py index 73c549b39..6e3a3a19c 100644 --- a/bcipy/language/__init__.py +++ b/bcipy/language/__init__.py @@ -1,6 +1,7 @@ -from .main import LanguageModel, ResponseType +from .main import CharacterLanguageModel, LanguageModel, WordLanguageModel __all__ = [ "LanguageModel", - "ResponseType", + "CharacterLanguageModel", + "WordLanguageModel" ] diff --git a/bcipy/language/demo/demo_causal.py b/bcipy/language/demo/demo_causal.py index e73324a46..8d84bce98 100644 --- a/bcipy/language/demo/demo_causal.py +++ b/bcipy/language/demo/demo_causal.py @@ -1,26 +1,34 @@ -from bcipy.language.model.causal import CausalLanguageModel -from bcipy.helpers.symbols import alphabet -from bcipy.language.main import ResponseType - +from bcipy.core.symbols import DEFAULT_SYMBOL_SET +from bcipy.language.model.causal import CausalLanguageModelAdapter if __name__ == "__main__": - symbol_set = alphabet() - response_type = ResponseType.SYMBOL - lm = CausalLanguageModel(response_type, symbol_set, lang_model_name="gpt2") + lm = CausalLanguageModelAdapter(lang_model_name="figmtu/opt-350m-aac") + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + + print("Target sentence: does_it_make_sense\n") - next_char_pred = lm.state_update(list("does_it_make_sen")) - print(next_char_pred) + next_char_pred = lm.predict_character(list("does_it_make_sen")) + print("Context: does_it_make_sen") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("S") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("does_it_make_sens")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + next_char_pred = lm.predict_character(list("does_it_make_sens")) + print("Context: does_it_make_sens") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("E") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("does_it_make_sense")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + next_char_pred = lm.predict_character(list("does_it_make_sense")) + print("Context: does_it_make_sense") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("_") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("i_like_zebra")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + print("Target sentence: i_like_zebras\n") + + next_char_pred = lm.predict_character(list("i_like_zebra")) + print("Context: i_like_zebra") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("S") + 1 - print(correct_char_rank) + print(f"Correct character rank: {correct_char_rank}\n") diff --git a/bcipy/language/demo/demo_mixture.py b/bcipy/language/demo/demo_mixture.py index a7746153d..960e3f2cc 100644 --- a/bcipy/language/demo/demo_mixture.py +++ b/bcipy/language/demo/demo_mixture.py @@ -1,22 +1,35 @@ -from bcipy.language.model.mixture import MixtureLanguageModel -from bcipy.helpers.symbols import alphabet -from bcipy.language.main import ResponseType - +from bcipy.core.symbols import DEFAULT_SYMBOL_SET +from bcipy.language.model.mixture import MixtureLanguageModelAdapter if __name__ == "__main__": - symbol_set = alphabet() - response_type = ResponseType.SYMBOL - lm = MixtureLanguageModel(response_type, symbol_set) + # Load the default mixture model from lm_params.json + lm = MixtureLanguageModelAdapter() + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + + print("Target sentence: does_it_make_sense\n") - next_char_pred = lm.state_update(list("does_it_make_sen")) - print(next_char_pred) + next_char_pred = lm.predict_character(list("does_it_make_sen")) + print("Context: does_it_make_sen") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("S") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("does_it_make_sens")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + next_char_pred = lm.predict_character(list("does_it_make_sens")) + print("Context: does_it_make_sens") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("E") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("does_it_make_sense")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + next_char_pred = lm.predict_character(list("does_it_make_sense")) + print("Context: does_it_make_sense") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("_") + 1 - print(correct_char_rank) + print(f"Correct character rank: {correct_char_rank}\n") + + print("Target sentence: i_like_zebras\n") + + next_char_pred = lm.predict_character(list("i_like_zebra")) + print("Context: i_like_zebra") + print(f"Predictions: {next_char_pred}") + correct_char_rank = [c[0] for c in next_char_pred].index("S") + 1 + print(f"Correct character rank: {correct_char_rank}\n") diff --git a/bcipy/language/demo/demo_kenlm.py b/bcipy/language/demo/demo_ngram.py similarity index 68% rename from bcipy/language/demo/demo_kenlm.py rename to bcipy/language/demo/demo_ngram.py index d90421e42..e02867e3f 100644 --- a/bcipy/language/demo/demo_kenlm.py +++ b/bcipy/language/demo/demo_ngram.py @@ -1,10 +1,9 @@ # Basic sanity test of using KenLM to predict a sentence using a 12-gram character model. -from bcipy.language.model.kenlm import KenLMLanguageModel -from bcipy.helpers.symbols import alphabet -from bcipy.language.main import ResponseType from bcipy.config import LM_PATH +from bcipy.core.symbols import DEFAULT_SYMBOL_SET from bcipy.exceptions import KenLMInstallationException +from bcipy.language.model.ngram import NGramLanguageModelAdapter try: import kenlm @@ -16,6 +15,8 @@ if __name__ == "__main__": lm_path = f"{LM_PATH}/lm_dec19_char_12gram_1e-5_kenlm_probing.bin" + # Using KenLM directly + # Load a really pruned n-gram language model model = kenlm.LanguageModel(lm_path) @@ -56,7 +57,8 @@ # file zebras.txt: 1 sentences, 14 words, 0 OOVs # 0 zeroprobs, logprob= -15.2391 ppl= 10.374 ppl1= 12.260 sentence = "i l i k e z e b r a s ." - print(f"Sentence '{sentence}', logprob = {model.score(sentence, bos=True, eos=True):.4f}\n") + print( + f"Sentence '{sentence}', logprob = {model.score(sentence, bos=True, eos=True):.4f}\n") # Stateful query going one token at-a-time # We'll flip flop between two state objects, one is the input and the other is the output @@ -75,32 +77,44 @@ score = model.BaseScore(state, token, state2) else: score = model.BaseScore(state2, token, state) - print(f"p( {token} | {prev} ...) = {pow(10, score):.6f} [ {score:.6f} ]") + print( + f"p( {token} | {prev} ...) = {pow(10, score):.6f} [ {score:.6f} ]") accum += score prev = token print(f"sum logprob = {accum:.4f}") - symbol_set = alphabet() - response_type = ResponseType.SYMBOL - lm = KenLMLanguageModel(response_type, symbol_set, lm_path) + # Using the adapter and textslinger toolkit + lm = NGramLanguageModelAdapter(lm_path) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + + print("Target sentence: i_like_zebras\n") - next_char_pred = lm.state_update(list("i_like_z")) - print(next_char_pred) + next_char_pred = lm.predict_character(list("i_like_z")) + print("Context: i_like_z") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("E") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("i_lik")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + next_char_pred = lm.predict_character(list("i_lik")) + print("Context: i_lik") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("E") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("i_like_zebras")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + next_char_pred = lm.predict_character(list("i_like_zebras")) + print("Context: i_like_zebras") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("_") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + next_char_pred = lm.predict_character(list("")) + print("Context: ") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("I") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("i_like_zebra")) - print(next_char_pred) + print(f"Correct character rank: {correct_char_rank}\n") + + next_char_pred = lm.predict_character(list("i_like_zebra")) + print("Context: i_like_zebra") + print(f"Predictions: {next_char_pred}") correct_char_rank = [c[0] for c in next_char_pred].index("S") + 1 - print(correct_char_rank) + print(f"Correct character rank: {correct_char_rank}\n") diff --git a/bcipy/language/demo/demo_unigram.py b/bcipy/language/demo/demo_unigram.py deleted file mode 100644 index d1db94ee1..000000000 --- a/bcipy/language/demo/demo_unigram.py +++ /dev/null @@ -1,22 +0,0 @@ -from bcipy.language.model.unigram import UnigramLanguageModel -from bcipy.helpers.symbols import alphabet -from bcipy.language.main import ResponseType - - -if __name__ == "__main__": - symbol_set = alphabet() - response_type = ResponseType.SYMBOL - lm = UnigramLanguageModel(response_type, symbol_set) - - next_char_pred = lm.state_update(list("does_it_make_sen")) - print(next_char_pred) - correct_char_rank = [c[0] for c in next_char_pred].index("S") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("does_it_make_sens")) - print(next_char_pred) - correct_char_rank = [c[0] for c in next_char_pred].index("E") + 1 - print(correct_char_rank) - next_char_pred = lm.state_update(list("does_it_make_sense")) - print(next_char_pred) - correct_char_rank = [c[0] for c in next_char_pred].index("_") + 1 - print(correct_char_rank) diff --git a/bcipy/language/lms/unigram.json b/bcipy/language/lms/unigram.json deleted file mode 100644 index c5432973d..000000000 --- a/bcipy/language/lms/unigram.json +++ /dev/null @@ -1,30 +0,0 @@ -{ - "E": 0.0998, - "T": 0.096, - "O": 0.0946, - "I": 0.0835, - "A": 0.0774, - "N": 0.0554, - "SPACE_CHAR": 0.0523, - "H": 0.0504, - "S": 0.0435, - "L": 0.0408, - "R": 0.0387, - "U": 0.0379, - "D": 0.0358, - "Y": 0.0324, - "W": 0.0288, - "M": 0.0266, - "G": 0.0221, - "C": 0.018, - "K": 0.016, - "P": 0.0145, - "F": 0.0117, - "B": 0.0113, - "V": 0.0091, - "J": 0.0016, - "X": 0.0008, - "Z": 0.0005, - "Q": 0.0002, - "BACKSPACE_CHAR": 0.0 -} \ No newline at end of file diff --git a/bcipy/language/main.py b/bcipy/language/main.py index 8a1922338..37136a037 100644 --- a/bcipy/language/main.py +++ b/bcipy/language/main.py @@ -1,87 +1,50 @@ """Defines the language model base class.""" -from abc import ABC, abstractmethod -from enum import Enum -from typing import List, Optional, Tuple -import json +from abc import abstractmethod +from typing import List, Optional, Protocol, Tuple, Union, runtime_checkable -from bcipy.exceptions import UnsupportedResponseType -from bcipy.helpers.symbols import DEFAULT_SYMBOL_SET -from bcipy.config import DEFAULT_LM_PARAMETERS_PATH - -class ResponseType(Enum): - """Language model response type options.""" - SYMBOL = 'Symbol' - WORD = 'Word' - - def __str__(self): - return self.value - - -class LanguageModel(ABC): - """Parent class for Language Models.""" - - _response_type: ResponseType = None - symbol_set: List[str] = None - - def __init__(self, - response_type: Optional[ResponseType] = None, - symbol_set: Optional[List[str]] = None): - self.response_type = response_type or ResponseType.SYMBOL - self.symbol_set = symbol_set or DEFAULT_SYMBOL_SET - with open(DEFAULT_LM_PARAMETERS_PATH, 'r') as params_file: - self.parameters = json.load(params_file) - - @classmethod - def name(cls) -> str: - """Model name used for configuration""" - suffix = 'LanguageModel' - if cls.__name__.endswith(suffix): - return cls.__name__[0:-len(suffix)].upper() - return cls.__name__.upper() +class UsesSymbols(Protocol): + """A protocol for classes in which symbols can be set.""" + symbol_set: Optional[List[str]] = None @abstractmethod - def supported_response_types(self) -> List[ResponseType]: - """Returns a list of response types supported by this language model.""" + def set_symbol_set(self, symbol_set: List[str]) -> None: + """Updates the symbol set of the model. Must be called prior to prediction""" - @property - def response_type(self) -> ResponseType: - """Returns the current response type""" - return self._response_type - @response_type.setter - def response_type(self, value: ResponseType): - """Attempts to set the response type to the given value""" - if value not in self.supported_response_types(): - raise UnsupportedResponseType( - f"{value} responses are not supported by this model") - self._response_type = value +@runtime_checkable +class CharacterLanguageModel(UsesSymbols, Protocol): + """Protocol for BciPy Language models that predict characters.""" @abstractmethod - def predict(self, evidence: List[str]) -> List[Tuple]: + def predict_character(self, evidence: Union[str, + List[str]]) -> List[Tuple]: """ - Using the provided data, compute log likelihoods over the entire symbol set. + Using the provided data, compute the probability distribution over the entire symbol set. Args: - evidence - ['A', 'B'] + evidence - ['H', 'E'] Response: - probability - dependant on response type, a list of words or symbols with probability + probability - a list of symbols with probability """ - ... - @abstractmethod - def update(self) -> None: - """Update the model state""" - ... + +@runtime_checkable +class WordLanguageModel(UsesSymbols, Protocol): + """Protocol for BciPy Language models that predict words.""" @abstractmethod - def load(self) -> None: - """Restore model state from the provided checkpoint""" - ... + def predict_word(self, evidence: Union[str, List[str]], + num_predictions: int) -> List[Tuple]: + """ + Using the provided data, compute log likelihoods of word completions + in the symbol set. + Args: + evidence - ['H', 'E'] + + Response: + a list of words with associated log likelihoods + """ - def reset(self) -> None: - """Reset language model state""" - ... - def state_update(self, evidence: List[str]) -> List[Tuple]: - """Update state by predicting and updating""" +LanguageModel = Union[CharacterLanguageModel, WordLanguageModel] diff --git a/bcipy/language/model/adapter.py b/bcipy/language/model/adapter.py new file mode 100644 index 000000000..20814e6ba --- /dev/null +++ b/bcipy/language/model/adapter.py @@ -0,0 +1,69 @@ +"""Defines the language model adapter base class.""" +import json +from abc import ABC, abstractmethod +from typing import List, Optional, Tuple, Union + +from bcipy.config import DEFAULT_LM_PARAMETERS_PATH +from bcipy.core.symbols import BACKSPACE_CHAR, SPACE_CHAR +from bcipy.exceptions import InvalidSymbolSetException + + +class LanguageModelAdapter(ABC): + """Abstract base class for textslinger language model adapters.""" + + symbol_set: Optional[List[str]] = None + model = None + + def predict_character(self, evidence: Union[str, List[str]]) -> List[Tuple]: + """ + Using the provided data, compute the probability distribution over the entire symbol set. + Args: + evidence - ['H', 'E'] + + Response: + probability - a list of symbols with probability + """ + + if self.symbol_set is None: + raise InvalidSymbolSetException( + "symbol set must be set prior to requesting predictions.") + + assert self.model is not None, "language model does not exist!" + + context = "".join(evidence) + converted_context = context.replace(SPACE_CHAR, ' ') + + # TODO: If toolkit dependency is updated to >=1.0.0, this will need to change to predict_character() + next_char_pred = dict(self.model.predict(list(converted_context))) + + # Replace space with special space + if ' ' in next_char_pred: + next_char_pred[SPACE_CHAR] = next_char_pred[' '] + del next_char_pred[' '] + + # Add backspace, but return prob 0 from the lm + next_char_pred[BACKSPACE_CHAR] = 0.0 + + return list(sorted(next_char_pred.items(), + key=lambda item: item[1], reverse=True)) + + def _load_parameters(self) -> None: + with open(DEFAULT_LM_PARAMETERS_PATH, 'r', + encoding='utf8') as params_file: + self.parameters = json.load(params_file) + + @abstractmethod + def _load_model(self) -> None: + """Load the model itself using stored parameters""" + + def set_symbol_set(self, symbol_set: List[str]) -> None: + """Update the symbol set and call for the model to be loaded""" + + self.symbol_set = symbol_set + + # LM doesn't care about backspace, needs literal space + self.model_symbol_set = [ + ' ' if ch is SPACE_CHAR else ch for ch in self.symbol_set] + self.model_symbol_set.remove(BACKSPACE_CHAR) + + self._load_model() diff --git a/bcipy/language/model/causal.py b/bcipy/language/model/causal.py index 677215369..e76ca7b90 100644 --- a/bcipy/language/model/causal.py +++ b/bcipy/language/model/causal.py @@ -1,323 +1,73 @@ -from collections import Counter -import torch -from typing import Optional, List, Tuple -from transformers import AutoModelForCausalLM, AutoTokenizer -import itertools -import heapq +from typing import Optional -from bcipy.helpers.symbols import BACKSPACE_CHAR, SPACE_CHAR -from bcipy.language.main import LanguageModel, ResponseType - -from bcipy.exceptions import InvalidLanguageModelException - -from scipy.special import logsumexp -from scipy.special import softmax +from textslinger.causal import CausalLanguageModel from bcipy.config import LM_PATH +from bcipy.language.model.adapter import LanguageModelAdapter -class CausalLanguageModel(LanguageModel): - """Character language model based on a pre-trained causal model, GPT-2 by default.""" +class CausalLanguageModelAdapter(LanguageModelAdapter): + """Character language model based on a pre-trained causal model.""" def __init__(self, - response_type: ResponseType, - symbol_set: List[str], lang_model_name: Optional[str] = None, lm_path: Optional[str] = None, lm_device: str = "cpu", lm_left_context: str = "", + beam_width: Optional[int] = None, + fp16: bool = True, + mixed_case_context: bool = True, + case_simple: bool = True, + max_completed: Optional[int] = None, ): """ - Initialize instance variables and load the language model with given path + Initialize instance variables and load model parameters Args: - response_type - SYMBOL only - symbol_set - list of symbol strings lang_model_name - name of the Hugging Face casual language model to load - lm_path - load fine-tuned model from specified directory - lm_device - device to use for making predictions (cpu, mps, or cuda) - lm_left_context - text to condition start of sentence on + lm_path - load fine-tuned model from specified directory + lm_device - device to use for making predictions (cpu, mps, or cuda) + lm_left_context - text to condition start of sentence on + beam_width - how many hypotheses to keep during the search, None=off + fp16 - convert model to fp16 to save memory/compute on CUDA + mixed_case_context - use mixed case for language model left context + case_simple - simple fixing of left context case + max_completed - stop search once we reach this many completed hypotheses, None=don't prune """ - super().__init__(response_type=response_type, symbol_set=symbol_set) - self.model = None - self.tokenizer = None - self.vocab_size = 0 - self.valid_vocab = [] - self.vocab = {} - self.longest_token = 0 - self.index_to_word = {} - self.index_to_word_lower = {} - self.symbol_set_lower = None - self.device = lm_device - self.left_context = lm_left_context + + self._load_parameters() + + causal_params = self.parameters['causal'] + + self.beam_width = beam_width or int( + causal_params['beam_width']['value']) + self.max_completed = max_completed or int( + causal_params['max_completed']['value']) # We optionally load the model from a local directory, but if this is not # specified, we load a Hugging Face model - causal_params = self.parameters['causal'] self.model_name = lang_model_name or causal_params['model_name']['value'] local_model_path = lm_path or causal_params['model_path']['value'] self.model_dir = f"{LM_PATH}/{local_model_path}" if local_model_path != "" else self.model_name - # parameters for search - self.beam_width = 8 - self.batch_size = 8 - - # backoff to the previous space - self.token_backoff = -1 - - self.load() - - def supported_response_types(self) -> List[ResponseType]: - return [ResponseType.SYMBOL] - - def _build_vocab(self) -> None: - """ - Build a vocabulary table mapping token index to word strings - """ - - for i in range(self.vocab_size): - word = self.tokenizer.decode([i]) - word_lower = word.lower() - self.index_to_word[i] = word - self.index_to_word_lower[i] = word_lower - valid = True - for ch in word_lower: - # The space char is only valid once we convert spaces to the space char - if ch == SPACE_CHAR: - valid = False - break - if ch == ' ': - continue - elif ch not in self.symbol_set_lower: - valid = False - break - if valid: - self.valid_vocab += i, - length = len(word) - if length > self.longest_token: - self.longest_token = length - for j in range(length): - key = word_lower[0:j + 1].replace(' ', SPACE_CHAR) - if key not in self.vocab: - self.vocab[key] = [] - self.vocab[key] += i, - - # Get the index we use for the start or end pseudo-word - if self.left_context == "": - if "gpt2" in self.model_name: - self.left_context = "<|endoftext|>" - else: - self.left_context = "" - # Get token id(s) for the left context we condition all sentences on - self.left_context_tokens = self._encode(self.left_context) - - def _encode(self, text: str) -> List[int]: - tokens = self.tokenizer.encode(text) - if len(tokens) > 1 and self.model_name.startswith("facebook/opt"): - tokens = tokens[1:] - - return tokens - - def predict(self, evidence: List[str]) -> List[Tuple]: - """ - Given an evidence of typed string, predict the probability distribution of - the next symbol - Args: - evidence - a list of characters (typed by the user) - Response: - A list of symbols with probability - """ - - assert self.model is not None, "language model does not exist!" - - converted_context = "".join(evidence) - converted_context_lower = converted_context.lower() - - context = converted_context.replace(SPACE_CHAR, ' ') - context_lower = context.lower() - - # Index in the hypothesis string that is the next character after our context - target_pos = len(context_lower) - - # Remove token_backoff tokens from the end of the context - # If token_backoff is -1 or goes beyond a word boundary, then - # search from the last space character in the context - # If no space, then from the very beginning - tokens = self._encode(context_lower) - - # Look for the last space in the context, or -1 if no begin_text in context yet - pos = context_lower.rfind(" ") - if pos >= 0: - truncated_context = context_lower[0:pos] - truncated_tokens = self._encode(truncated_context) - # Insert the left context tokens at the start of the sequence - truncated_tokens[0:0] = self.left_context_tokens - else: - # Didn't find space so start inference with just the left context tokens - truncated_tokens = self.left_context_tokens - - if self.token_backoff == -1 or len(tokens) - self.token_backoff < len(truncated_tokens): - tokens = truncated_tokens - else: - tokens = tokens[:-self.token_backoff] - - # Build up the sequence text for the context - # Start after the left context tokens - sequence_text = "" - for i in range(len(self.left_context_tokens), len(tokens)): - sequence_text = sequence_text + self.index_to_word_lower[tokens[i]] - valid = [(0.0, tokens, sequence_text)] - heapq.heapify(valid) - - # Create a hash mapping each valid following character to a list of log probabilities - char_to_log_probs = {} - - while len(valid) > 0: - # Only work on the top hypotheses from the last round of extension - current = list(valid) - - # Add new extended hypotheses to this list - valid.clear() - - # Keep going until we have extended all hypotheses in the current set - while len(current) > 0: - current_batch = 0 - batch_tensors = [] - batch_sequences = [] - batch_likelihoods = [] - batch_seq_text = [] - while len(current) > 0 and current_batch < self.batch_size: - # Get the new sequence to work on - (current_likelihood, sequence, sequence_text) = current.pop(0) - batch_tensors += torch.tensor(sequence), - batch_sequences += sequence, - batch_likelihoods += current_likelihood, - batch_seq_text += sequence_text, - current_batch += 1 - - tokens_tensor = torch.stack(tuple(batch_tensors)).to(self.device) - - with torch.no_grad(): - logits = self.model(tokens_tensor).logits - log_probs = torch.log_softmax(logits[:, -1, :], dim=1).to("cpu") - - for j in range(current_batch): - sequence_text = batch_seq_text[j] - vocab = [] - extra_vocab = [] - - remaining_context = converted_context_lower[len(sequence_text):] - if len(remaining_context) == 0: - vocab = self.valid_vocab - else: - if remaining_context in self.vocab: - vocab = self.vocab[remaining_context] - for i in range(1, len(remaining_context)): - tokenization = self._encode(context_lower[len(sequence_text):len(sequence_text) + i]) - if len(tokenization) == 1: - extra_vocab += tokenization[0], - - # Create a list of token indexes that are a prefix of target text - # We go over all the integer IDs in the vocab and extra_vocab lists - for i in itertools.chain(vocab, extra_vocab): - hypo_str = sequence_text + self.index_to_word_lower[i] - hypo_seq = batch_sequences[j].copy() - hypo_seq += i, - - # Add the log prob of this token to the previous running total - # For some reason the float cast makes it run faster - likelihood = batch_likelihoods[j] + float(log_probs[j][i]) - # If we have extended to a space following the context, then that hypothesis gets to be done - # This takes a lot longer that just requiring extending beyond existing context - # Just require hypotheses to extend beyond the existing typed context - if len(hypo_str) > len(context): - ch = hypo_str[target_pos] - - # Create an empty list if we haven't seen this character before - if ch not in char_to_log_probs: - char_to_log_probs[ch] = [] - char_to_log_probs[ch] += likelihood, - - else: - hypo = (likelihood, hypo_seq, hypo_str) - if len(valid) < self.beam_width: - heapq.heappush(valid, hypo) - else: - heapq.heappushpop(valid, hypo) - - # Parallel array to symbol_set for storing the marginals - char_probs = [] - for ch in self.symbol_set_lower: - # Convert space to the underscore used in BciPy - if ch == SPACE_CHAR: - target_ch = ' ' - else: - target_ch = ch - - # Handle cases when symbols are never seen - if target_ch in char_to_log_probs: - char_probs += logsumexp(char_to_log_probs[target_ch]), - else: - char_probs += float("-inf"), - # Normalize to a distribution that sums to 1 - char_probs = softmax(char_probs) - - next_char_pred = Counter() - - for i, ch in enumerate(self.symbol_set_lower): - if ch is SPACE_CHAR: - next_char_pred[ch] = char_probs[i] - else: - next_char_pred[ch.upper()] = char_probs[i] - - next_char_pred[BACKSPACE_CHAR] = 0.0 - - return list(sorted(next_char_pred.items(), key=lambda item: item[1], reverse=True)) - - def update(self) -> None: - """Update the model state""" - ... - - def load(self) -> None: - """ - Load the language model and tokenizer, initialize class variables - """ - try: - self.tokenizer = AutoTokenizer.from_pretrained(self.model_name, use_fast=False) - except BaseException: - raise InvalidLanguageModelException(f"{self.model_name} is not a valid model identifier on HuggingFace.") - self.vocab_size = self.tokenizer.vocab_size - try: - self.model = AutoModelForCausalLM.from_pretrained(self.model_dir) - except BaseException: - raise InvalidLanguageModelException( - f"{self.model_dir} is not a valid local folder or model identifier on HuggingFace.") - - self.model.eval() - - self.model.to(self.device) - - self.symbol_set_lower = [] - for ch in self.symbol_set: - if ch is SPACE_CHAR: - self.symbol_set_lower.append(SPACE_CHAR) - elif ch is BACKSPACE_CHAR: - continue - else: - self.symbol_set_lower.append(ch.lower()) - - self._build_vocab() - - def state_update(self, evidence: List[str]) -> List[Tuple]: - """ - Wrapper method that takes in evidence text, and output probability distribution - of next character - Args: - evidence - a list of characters (typed by the user) - Response: - A list of symbol with probability - """ - next_char_pred = self.predict(evidence) - - return next_char_pred + self.lm_device = lm_device + self.lm_left_context = lm_left_context + self.fp16 = fp16 + self.mixed_case_context = mixed_case_context + self.case_simple = case_simple + + def _load_model(self) -> None: + """Load the model itself using stored parameters""" + + self.model = CausalLanguageModel( + symbol_set=self.model_symbol_set, + lang_model_name=self.model_name, + lm_path=self.model_dir, + lm_device=self.lm_device, + lm_left_context=self.lm_left_context, + beam_width=self.beam_width, + fp16=self.fp16, + mixed_case_context=self.mixed_case_context, + case_simple=self.case_simple, + max_completed=self.max_completed) diff --git a/bcipy/language/model/kenlm.py b/bcipy/language/model/kenlm.py deleted file mode 100644 index 1c95241e7..000000000 --- a/bcipy/language/model/kenlm.py +++ /dev/null @@ -1,137 +0,0 @@ -from collections import Counter -from typing import Optional, List, Tuple -from bcipy.helpers.symbols import BACKSPACE_CHAR, SPACE_CHAR -from bcipy.language.main import LanguageModel, ResponseType -from bcipy.exceptions import InvalidLanguageModelException, KenLMInstallationException -from bcipy.config import LM_PATH -try: - import kenlm -except BaseException: - raise KenLMInstallationException( - "Please install the requisite kenlm package:\n'pip install kenlm==0.1 --global-option=\"--max_order=12\"") -import numpy as np - - -class KenLMLanguageModel(LanguageModel): - """Character n-gram language model using the KenLM library for querying""" - - def __init__(self, response_type: ResponseType, symbol_set: List[str], lm_path: Optional[str] = None): - - super().__init__(response_type=response_type, symbol_set=symbol_set) - self.model = None - kenlm_params = self.parameters['kenlm'] - kenlm_model = kenlm_params['model_file']['value'] - self.lm_path = lm_path or f"{LM_PATH}/{kenlm_model}" - - self.load() - - def supported_response_types(self) -> List[ResponseType]: - return [ResponseType.SYMBOL] - - def predict(self, evidence: List[str]) -> List[Tuple]: - """ - Given an evidence of typed string, predict the probability distribution of - the next symbol - Args: - evidence - a list of characters (typed by the user) - Response: - A list of symbols with probability - """ - - # Do not modify the original parameter, could affect mixture model - context = evidence.copy() - - if len(context) > 11: - context = context[-11:] - - evidence_str = ''.join(context).lower() - - for i, ch in enumerate(context): - if ch == SPACE_CHAR: - context[i] = "" - - self.model.BeginSentenceWrite(self.state) - - # Update the state one token at a time based on evidence, alternate states - for i, token in enumerate(context): - if i % 2 == 0: - self.model.BaseScore(self.state, token.lower(), self.state2) - else: - self.model.BaseScore(self.state2, token.lower(), self.state) - - next_char_pred = None - - # Generate the probability distribution based on the final state - if len(context) % 2 == 0: - next_char_pred = self.prob_dist(self.state) - else: - next_char_pred = self.prob_dist(self.state2) - - return next_char_pred - - def update(self) -> None: - """Update the model state""" - ... - - def load(self) -> None: - """ - Load the language model, initialize state variables - Args: - path: language model file path - """ - - try: - self.model = kenlm.LanguageModel(self.lm_path) - except BaseException: - raise InvalidLanguageModelException( - f"A valid model path must be provided for the KenLMLanguageModel.\nPath{self.lm_path} is not valid.") - - self.state = kenlm.State() - self.state2 = kenlm.State() - - def state_update(self, evidence: List[str]) -> List[Tuple]: - """ - Wrapper method that takes in evidence text and outputs probability distribution - of next character - Args: - evidence - a list of characters (typed by the user) - Response: - A list of symbols with probabilities - """ - next_char_pred = self.predict(evidence) - - return next_char_pred - - def prob_dist(self, state: kenlm.State) -> List[Tuple]: - """ - Take in a state and generate the probability distribution of next character - Args: - state - the kenlm state updated with the evidence - Response: - A list of symbols with probability - """ - next_char_pred = Counter() - - temp_state = kenlm.State() - - for char in self.symbol_set: - # Backspace probability under the LM is 0 - if char == BACKSPACE_CHAR: - next - - score = 0.0 - - # Replace the space character with KenLM's token - if char == SPACE_CHAR: - score = self.model.BaseScore(state, '', temp_state) - else: - score = self.model.BaseScore(state, char.lower(), temp_state) - - # BaseScore returns log probs, convert by putting 10 to its power - next_char_pred[char] = pow(10, score) - - sum = np.sum(list(next_char_pred.values())) - for char in self.symbol_set: - next_char_pred[char] /= sum - - return list(sorted(next_char_pred.items(), key=lambda item: item[1], reverse=True)) diff --git a/bcipy/language/model/mixture.py b/bcipy/language/model/mixture.py index 2220c029a..29748c2a7 100644 --- a/bcipy/language/model/mixture.py +++ b/bcipy/language/model/mixture.py @@ -1,153 +1,46 @@ -from collections import Counter -from typing import Optional, Dict, List, Tuple -from math import isclose +from typing import Dict, List, Optional -from bcipy.language.main import LanguageModel, ResponseType +from textslinger.mixture import MixtureLanguageModel -from bcipy.exceptions import InvalidLanguageModelException +from bcipy.config import LM_PATH +from bcipy.language.model.adapter import LanguageModelAdapter -# pylint: disable=unused-import -# flake8: noqa -"""All supported models must be imported""" -from bcipy.language.model.causal import CausalLanguageModel -from bcipy.language.model.kenlm import KenLMLanguageModel -from bcipy.language.model.unigram import UnigramLanguageModel +class MixtureLanguageModelAdapter(LanguageModelAdapter): + """Character language model that mixes any combination of other models.""" -class MixtureLanguageModel(LanguageModel): - """ - Character language model that mixes any combination of other models - """ - - supported_lm_types = ["CAUSAL", "UNIGRAM", "KENLM"] - - @staticmethod - def language_models_by_name() -> Dict[str, LanguageModel]: - """Returns available language models indexed by name.""" - return {lm.name(): lm for lm in LanguageModel.__subclasses__()} - - @staticmethod - def validate_parameters(types: List[str], weights: List[float], params: List[Dict[str, str]]): - if params is not None: - if (types is None) or (len(types) != len(params)): - raise InvalidLanguageModelException("Length of parameters does not match length of types") - - if weights is not None: - if (types is None) or (len(types) != len(weights)): - raise InvalidLanguageModelException("Length of weights does not match length of types") - if not isclose(sum(weights), 1.0, abs_tol=1e-05): - raise InvalidLanguageModelException("Weights do not sum to 1") - - if types is not None: - if weights is None: - raise InvalidLanguageModelException("Model weights not provided") - if params is None: - raise InvalidLanguageModelException("Model parameters not provided") - if not all(x in MixtureLanguageModel.supported_lm_types for x in types): - raise InvalidLanguageModelException(f"Supported model types: {MixtureLanguageModel.supported_lm_types}") + supported_lm_types = MixtureLanguageModel.supported_lm_types def __init__(self, - response_type: ResponseType, - symbol_set: List[str], lm_types: Optional[List[str]] = None, lm_weights: Optional[List[float]] = None, lm_params: Optional[List[Dict[str, str]]] = None): """ - Initialize instance variables and load the language model with given path + Initialize instance variables and load parameters Args: - response_type - SYMBOL only - symbol_set - list of symbol strings lm_types - list of types of models to mix lm_weights - list of weights to use when mixing the models lm_params - list of dictionaries to pass as parameters for each model's instantiation """ - MixtureLanguageModel.validate_parameters(lm_types, lm_weights, lm_params) + MixtureLanguageModel.validate_parameters( + lm_types, lm_weights, lm_params) - super().__init__(response_type=response_type, symbol_set=symbol_set) - self.models = list() - self.response_type = response_type - self.symbol_set = symbol_set + self._load_parameters() mixture_params = self.parameters['mixture'] self.lm_types = lm_types or mixture_params['model_types']['value'] self.lm_weights = lm_weights or mixture_params['model_weights']['value'] self.lm_params = lm_params or mixture_params['model_params']['value'] - MixtureLanguageModel.validate_parameters(self.lm_types, self.lm_weights, self.lm_params) - - self.load() - - def supported_response_types(self) -> List[ResponseType]: - return [ResponseType.SYMBOL] - - @staticmethod - def interpolate_language_models(lms: List[Dict[str, float]], coeffs: List[float]) -> List[Tuple]: - """ - interpolate two or more language models - Args: - lms - output from the language models (a list of dicts with char as keys and prob as values) - coeffs - list of rescale coefficients, lms[0] will be scaled by coeffs[0] and so on - Response: - a list of (char, prob) tuples representing an interpolated language model - """ - combined_lm = Counter() - - for i, lm in enumerate(lms): - for char in lm: - combined_lm[char] += lm[char] * coeffs[i] - - return list(sorted(combined_lm.items(), key=lambda item: item[1], reverse=True)) - - def predict(self, evidence: List[str]) -> List[Tuple]: - """ - Given an evidence of typed string, predict the probability distribution of - the next symbol - Args: - evidence - a list of characters (typed by the user) - Response: - A list of symbols with probability - """ - - pred_list = list() - - # Generate predictions from each component language model - pred_list = [dict(model.predict(evidence)) for model in self.models] + for type, params in zip(self.lm_types, self.lm_params): + if type == "NGRAM": + params["lm_path"] = f"{LM_PATH}/{params['lm_path']}" - # Mix the component models - next_char_pred = MixtureLanguageModel.interpolate_language_models(pred_list, self.lm_weights) - - return next_char_pred - - def update(self) -> None: - """Update the model state""" - ... - - def load(self) -> None: - """ - Load the language models to be mixed - """ - - language_models = MixtureLanguageModel.language_models_by_name() - for lm_type, params in zip(self.lm_types, self.lm_params): - model = language_models[lm_type] - lm = None - try: - lm = model(self.response_type, self.symbol_set, **params) - except InvalidLanguageModelException as e: - raise InvalidLanguageModelException(f"Error in creation of model type {lm_type}: {e.message}") - - self.models.append(lm) - - def state_update(self, evidence: List[str]) -> List[Tuple]: - """ - Wrapper method that takes in evidence text, and output probability distribution - of next character - Args: - evidence - a list of characters (typed by the user) - Response: - A list of symbol with probability - """ - next_char_pred = self.predict(evidence) + MixtureLanguageModel.validate_parameters( + self.lm_types, self.lm_weights, self.lm_params) - return next_char_pred + def _load_model(self) -> None: + """Load the model itself using stored parameters""" + self.model = MixtureLanguageModel(self.model_symbol_set, self.lm_types, + self.lm_weights, self.lm_params) diff --git a/bcipy/language/model/ngram.py b/bcipy/language/model/ngram.py new file mode 100644 index 000000000..226860a4d --- /dev/null +++ b/bcipy/language/model/ngram.py @@ -0,0 +1,29 @@ +from typing import Optional + +from textslinger.ngram import NGramLanguageModel + +from bcipy.config import LM_PATH +from bcipy.language.model.adapter import LanguageModelAdapter + + +class NGramLanguageModelAdapter(LanguageModelAdapter): + """Character n-gram language model using the KenLM library for querying""" + + def __init__(self, + lm_path: Optional[str] = None): + """ + Initialize instance variables and load parameters + Args: + lm_path - location of local ngram model - loaded from parameters if None + """ + + self._load_parameters() + + ngram_params = self.parameters['ngram'] + ngram_model = ngram_params['model_file']['value'] + self.lm_path = lm_path or f"{LM_PATH}/{ngram_model}" + + def _load_model(self) -> None: + """Load the model itself using stored parameters""" + self.model = NGramLanguageModel(symbol_set=self.model_symbol_set, + lm_path=self.lm_path) diff --git a/bcipy/language/model/oracle.py b/bcipy/language/model/oracle.py index a23e4789e..e581f460c 100644 --- a/bcipy/language/model/oracle.py +++ b/bcipy/language/model/oracle.py @@ -5,17 +5,18 @@ import numpy as np from bcipy.config import SESSION_LOG_FILENAME -from bcipy.helpers.symbols import BACKSPACE_CHAR -from bcipy.language.main import LanguageModel, ResponseType +from bcipy.core.symbols import BACKSPACE_CHAR, DEFAULT_SYMBOL_SET +from bcipy.exceptions import InvalidSymbolSetException +from bcipy.language.main import CharacterLanguageModel from bcipy.language.model.uniform import equally_probable logger = logging.getLogger(SESSION_LOG_FILENAME) TARGET_BUMP_MIN = 0.0 -TARGET_BUMP_MAX = 0.95 +TARGET_BUMP_MAX = 1.0 -class OracleLanguageModel(LanguageModel): +class OracleLanguageModel(CharacterLanguageModel): """Language model which knows the target phrase the user is attempting to spell. @@ -28,25 +29,28 @@ class OracleLanguageModel(LanguageModel): Parameters ---------- - response_type - SYMBOL only - symbol_set - optional specify the symbol set, otherwise uses DEFAULT_SYMBOL_SET task_text - the phrase the user is attempting to spell (ex. 'HELLO_WORLD') target_bump - the amount by which the probability of the target letter is increased. """ def __init__(self, - response_type: Optional[ResponseType] = None, - symbol_set: Optional[List[str]] = None, - task_text: str = None, + task_text: Optional[str] = None, target_bump: float = 0.1): - super().__init__(response_type=response_type, symbol_set=symbol_set) + self.task_text = task_text self.target_bump = target_bump + + self.symbol_set = DEFAULT_SYMBOL_SET + logger.debug( f"Initialized OracleLanguageModel(task_text='{task_text}', target_bump={target_bump})" ) + def set_symbol_set(self, symbol_set: List[str]) -> None: + """Updates the symbol set of the model. Must be called prior to prediction""" + self.symbol_set = symbol_set + @property def task_text(self): """Get the task_text property""" @@ -70,10 +74,7 @@ def target_bump(self, value: float): assert TARGET_BUMP_MIN <= value <= TARGET_BUMP_MAX, msg self._target_bump = value - def supported_response_types(self) -> List[ResponseType]: - return [ResponseType.SYMBOL] - - def predict(self, evidence: Union[str, List[str]]) -> List[Tuple]: + def predict_character(self, evidence: Union[str, List[str]]) -> List[Tuple]: """ Using the provided data, compute probabilities over the entire symbol. set. @@ -86,29 +87,35 @@ def predict(self, evidence: Union[str, List[str]]) -> List[Tuple]: ------- list of (symbol, probability) tuples """ + + if not self.symbol_set: + raise InvalidSymbolSetException( + "symbol set must be set prior to requesting predictions.") + spelled_text = ''.join(evidence) - probs = equally_probable(self.symbol_set) - symbol_probs = list(zip(self.symbol_set, probs)) target = self._next_target(spelled_text) + symbol_probs = {} + if target: - sym = (target, probs[0] + self.target_bump) - updated_symbol_probs = with_min_prob(symbol_probs, sym) + # non-target prob = x = (1-b)/n where n is len(symbol_set) and b is target_bump + # target prob = x + b + non_target_prob = (1 - self.target_bump) / len(self.symbol_set) + for ch in self.symbol_set: + if ch == target: + symbol_probs[ch] = non_target_prob + self.target_bump + else: + symbol_probs[ch] = non_target_prob else: - updated_symbol_probs = symbol_probs - - return sorted(updated_symbol_probs, - key=lambda pair: self.symbol_set.index(pair[0])) + symbol_probs = dict( + zip(self.symbol_set, equally_probable(self.symbol_set))) - def update(self) -> None: - """Update the model state""" - - def load(self) -> None: - """Restore model state from the provided checkpoint""" + return sorted(symbol_probs.items(), + key=lambda item: item[1], + reverse=True) def _next_target(self, spelled_text: str) -> Optional[str]: - """Computes the next target letter based on the currently spelled_text. - """ + """Computes the next target letter based on the currently spelled_text.""" len_spelled = len(spelled_text) len_task = len(self.task_text) diff --git a/bcipy/language/model/uniform.py b/bcipy/language/model/uniform.py index 013735ba6..e2dc52e0c 100644 --- a/bcipy/language/model/uniform.py +++ b/bcipy/language/model/uniform.py @@ -1,30 +1,34 @@ """Uniform language model""" -from typing import Dict, List, Tuple, Union, Optional +from typing import Dict, List, Optional, Tuple, Union import numpy as np -from bcipy.language.main import LanguageModel, ResponseType +from bcipy.core.symbols import BACKSPACE_CHAR, DEFAULT_SYMBOL_SET +from bcipy.exceptions import InvalidSymbolSetException +from bcipy.language.main import CharacterLanguageModel -class UniformLanguageModel(LanguageModel): +class UniformLanguageModel(CharacterLanguageModel): """Language model in which probabilities for symbols are uniformly distributed. Parameters ---------- - response_type - SYMBOL only - symbol_set - optional specify the symbol set, otherwise uses DEFAULT_SYMBOL_SET + None """ - def __init__(self, - response_type: Optional[ResponseType] = None, - symbol_set: Optional[List[str]] = None): - super().__init__(response_type=response_type, symbol_set=symbol_set) + def __init__(self): + self.set_symbol_set(DEFAULT_SYMBOL_SET) - def supported_response_types(self) -> List[ResponseType]: - return [ResponseType.SYMBOL] + def set_symbol_set(self, symbol_set: List[str]) -> None: + """Updates the symbol set of the model. Must be called prior to prediction""" + self.symbol_set = symbol_set - def predict(self, evidence: Union[str, List[str]]) -> List[Tuple]: + self.model_symbol_set = [ch for ch in symbol_set] + if BACKSPACE_CHAR in symbol_set: + self.model_symbol_set.remove(BACKSPACE_CHAR) + + def predict_character(self, evidence: Union[str, List[str]]) -> List[Tuple]: """ Using the provided data, compute probabilities over the entire symbol. set. @@ -37,18 +41,19 @@ def predict(self, evidence: Union[str, List[str]]) -> List[Tuple]: ------- list of (symbol, probability) tuples """ - probs = equally_probable(self.symbol_set) - return list(zip(self.symbol_set, probs)) - def update(self) -> None: - """Update the model state""" + if not self.symbol_set: + raise InvalidSymbolSetException( + "symbol set must be set prior to requesting predictions.") - def load(self) -> None: - """Restore model state from the provided checkpoint""" + probs = equally_probable(self.model_symbol_set) + return list(zip(self.model_symbol_set, probs)) + [(BACKSPACE_CHAR, 0.0) + ] -def equally_probable(alphabet: List[str], - specified: Optional[Dict[str, float]] = None) -> List[float]: +def equally_probable( + alphabet: List[str], + specified: Optional[Dict[str, float]] = None) -> List[float]: """Returns a list of probabilities which correspond to the provided alphabet. Unless overridden by the specified values, all items will have the same probability. All probabilities sum to 1.0. diff --git a/bcipy/language/model/unigram.py b/bcipy/language/model/unigram.py deleted file mode 100644 index 9e61e213c..000000000 --- a/bcipy/language/model/unigram.py +++ /dev/null @@ -1,69 +0,0 @@ -from typing import Optional, List, Tuple -from bcipy.helpers.symbols import BACKSPACE_CHAR, SPACE_CHAR -from bcipy.language.main import LanguageModel, ResponseType -from bcipy.exceptions import InvalidLanguageModelException -import json -from bcipy.config import LM_PATH - - -class UnigramLanguageModel(LanguageModel): - """Character language model based on trained unigram weights""" - - def __init__(self, response_type: ResponseType, symbol_set: List[str], lm_path: Optional[str] = None): - - super().__init__(response_type=response_type, symbol_set=symbol_set) - self.model = None - self.lm_path = lm_path or f"{LM_PATH}/unigram.json" - - try: - with open(self.lm_path) as json_file: - self.unigram_lm = json.load(json_file) - except BaseException: - raise InvalidLanguageModelException("Unable to load Unigram model from file") - - self.unigram_lm[SPACE_CHAR] = self.unigram_lm.pop("SPACE_CHAR") - self.unigram_lm[BACKSPACE_CHAR] = self.unigram_lm.pop("BACKSPACE_CHAR") - - if not set(self.unigram_lm.keys()) == set(self.symbol_set): - raise InvalidLanguageModelException("Invalid unigram model symbol set!") - - self.unigram_lm = sorted(self.unigram_lm.items(), key=lambda item: item[1], reverse=True) - - self.load() - - def supported_response_types(self) -> List[ResponseType]: - return [ResponseType.SYMBOL] - - def predict(self, evidence: List[str]) -> List[Tuple]: - """ - Given an evidence of typed string, predict the probability distribution of - the next symbol - Args: - evidence - a list of characters (typed by the user) - Response: - A list of symbols with probability - """ - - return self.unigram_lm - - def update(self) -> None: - """Update the model state""" - ... - - def load(self) -> None: - """ - Load the language model and tokenizer, initialize class variables - Args: - path: language model file path, can be just "unigram" - """ - - def state_update(self, evidence: List[str]) -> List[Tuple]: - """ - Wrapper method that takes in evidence text, and output probability distribution - of next character - evidence does not matter for unigram model - Args: - evidence - a list of characters (typed by the user) - Response: - A list of symbol with probability - """ - return self.unigram_lm diff --git a/bcipy/language/sets/boston.tokenized b/bcipy/language/sets/boston.tokenized deleted file mode 100644 index c31f7da5d..000000000 --- a/bcipy/language/sets/boston.tokenized +++ /dev/null @@ -1,1341 +0,0 @@ -c a n y o u l i s t e n t o m e p l e a s e l o o k i n m y e y e s -i t s u d d e n l y b e c o m e s i m p o r t a n t -y o u k n o w s o m e t h i n g -w i l l y o u c a l l t h e m -i t h a p p e n s t o b e m y f a v o r i t e -i a m r e a l l y s o r r y -i e n j o y e d s e e i n g y o u t h a n k s -s o i s m i n e -w h a t d i d h e t h i n k a b o u t t h a t -w h e n i a m t i r e d -t h e s u n i s s h i n i n g -w h e n w i l l i s e e y o u n e x t -a l o n g t i m e a g o -i h a d a r e a l b u s y d a y -p l e a s e c o m e r i g h t b a c k -y o u a r e t h e g r e a t e s t k i d s i n t h e w o r l d -i w o u l d l i k e t o e a t s o m e f i s h -h o w l o n g d o e s i t t a k e -i w a s o n l y j o k i n g -w h a t -i s t i l l h a v e t o -t a l k t o y o u s o o n -i h a v e a l s -e x p l a i n t h a t t o m e -c a n i m u n c h o n s o m e n u t s -w h e n y o u c o m e b a c k -w h o c a l l e d -p l e a s e t u r n o n t h e t v -c a n w e g o t o t h e m o v i e s -y o u k n o w w h a t i m e a n -c a n y o u r e p e a t w h a t y o u j u s t s a i d -y o u c a n s a y t h a t a g a i n -s h o u l d i t a k e i t -i w o u l d l i k e t o h a v e s o m e y o g u r t a n d b e r r i e s -c a n y o u h e l p m e w i t h t h e c o m p u t e r -y o u b e t t e r h u r r y -c a n i h a v e a g l a s s o f w a t e r -i t f e e l s g r e a t -w e n e e d t o t h a v e t h e c o m p u t e r g u y f i x o u r c o m p u t e r -i a m r e a d y t o g o b a c k -y o u k n o w w h a t i t h i n k -i m i s s e d y o u -w h y d i d h e g o t h e r e -t u r n t h a t o n f o r m e -j u s t o n e c o m m e n t -i w a n t t o l a y o n m y s t o m a c h -h o w m u c h w i l l i t c o s t -c a n y o u h e l p m e t a k e a s h o w e r -t h a t w a s t h e v o i c e m a c h i n e t a l k i n g n o t m e -i h a v e a h e a d a c h e -c a n y o u h e l p m e p u t o n s o m e m a k e u p -c a n y o u k e e p m e c o m p a n y f o r a w h i l e -i w a n t t o w a t c h t h e n e w s -w h e n d o w e s t a r t -y o u w a n n a b e t -i w a s j u s t w o n d e r i n g -t h e w e a t h e r i s b e a u t i f u l t o d a y -t h a n k y o u f o r y o u r g o o d w i s h e s -p l e a s e h u r r y u p -i n e e d m o r e i n f o r m a t i o n -c a n y o u h e l p m e w a s h m y h a n d s -i t h i n k w e o u g h t t o d o t h a t -t h a t s j u s t g r e a t -h o w c a n i g e t a h o l d o f y o u -h e l p m e m o v e t h i s -y o u t h i n k s o -d o y o u k n o w h o w m u c h i l o v e y o u -h o w c a n i h e l p y o u -w h a t i s n e x t -b e f o r e y o u g o -i a l w a y s d o -y o u m i s s e d t h e b o a t -b e l i e v e m e i t i s -i j u s t r e m e m b e r e d -p l e a s e s i t d o w n -c a n w e t a l k -f o r a l l i k n o w -i t w o u l d b e m u c h e a s i e r -w o u l d y o u m i n d s p e l l i n g t h a t f o r m e -y o u c o u l d h e l p a l i t t l e -h o w l o n g -i c a n h a n d l e i t -u h h u h -t h i s i s a n t i c i p a t e d -g e t t h e h e l l a w a y f r o m m e -b l o w s t h a t t h e o r y t o h e l l -y o u m i s s e d t h e b o a t -i h a v e s o m e t h i n g t o s a y a b o u t t h a t -w o u l d y o u m a k e a p h o n e c a l l f o r m e -c a n y o u p l e a s e r e p e a t t h a t -y o u a l w a y s m a k e t h e t h i n g s i l i k e t o e a t -t h a n k f o r t h e r i d e -g o o d b y e -w h e n i f e e l l i k e i t -c o u l d i h a v e s o m e -w h a t d o y o u m e a n -i s t i l l h a v e t h e t i m e -t h e m o o n i s s o b r i g h t -w h a t h a v e y o u b e e n d o i n g -f o r a w h i l e -i t w a s s o g o o d -i l o v e i t -i s t h e r e a n y d o u b t -i o n l y e a t v e g e t a b l e s -c a n i h a v e a s p r i t z o f p e r f u m e -i n e e d t o s h a v e m y l e g s -w h e r e i s e v e r y o n e -i g u e s s i b e t t e r b e g o i n g g r e a t t o s e e y o u -t h i s i s a r e q u e s t -y o u k n o w h o w i t g o e s -w h a t c a n i h a v e t o e a t t h i s m o r n i n g -h o w o f t e n d o y o u d o t h i s -y o u a r e t h e b e s t p a r t n e r -g r e a t t o s e e y o u a g a i n -i t i s d i f f e r e n t a l r i g h t -i w a n t t o g e t m y e y e b r o w s w a x e d -i w a n t t o u s e t h e l a p t o p -c a n y o u s a v e t h i s f o r a n o t h e r t i m e -i h a v e a n i t c h o n m y h a n d -i t i s v e r y u n c o m f o r t a b l e w h e n i t c r a m p s -t h e y t o l d m e t h a t -i l i k e i t b e t t e r -w o u l d y o u s t a r t t h e s h o w e r -g i v e m e a b r e a k -h e l p m e o u t -c a n y o u o p e n t h e d o o r t o l e t t h e b r e e z e i n -i f e e l f r i g h t e n e d s o m e t i m e s -y e s y o u c a n -i g e t i t -i s t h e r e s o m e t h i n g w r o n g w i t h t h a t -i g u e s s n o t -d o w e h a v e a n y c h i p s -i c o u l d u s e y o u r i n p u t -a r e y o u c r a z y -i a m s o h a p p y t o b e a p a r t o f t o d a y -p l e a s e t u r n o n t h e h e a t -w o u l d a n y o n e l i k e t o p l a y a g a m e -w o u l d y o u l i k e m e t o h e l p p r e p a r e b r e a k f a s t -t u r n i t d o w n a l i t t l e b i t p l e a s e -s o l o n g -g e t h e l p n o w -m a y b e t h e y d o -l o o k s l i k e i t -n o t u s u a l l y b u t i n t h i s c a s e -i t w a s g o o d o f y o u t o c o m e t o d a y -g e t m e u p e a r l i e r -k i s s m y g r i t s -w h e r e d i d t h a t c o m e f r o m -o h d a r n -b e c a r e f u l -w i l l i t h u r t -i h a v e a s p e e c h p r o b l e m i u s e t h i s m a c h i n e t o t a l k -i s t h a t y o u r r e a l n a m e -i c h a n g e d m y m i n d -i a m n o t h u n g r y -h o w w o u l d y o u l i k e t o c e l e b r a t e o u r a n n i v e r s a r y -c o m e b a c k a g a i n s o o n -y o u c a n t r y b u t i d o u b t i t -i f e e l t h e s a m e w a y a b o u t i t -u n f o r t u n a t e l y y e s -t h e r e w a s s o m e t h i n g e l s e -t h i s w e e k e n d -i h a v e n e w s -w h a t a r e y o u r p l a n s f o r -a r e y o u c r a z y -t h a t w i l l b e f u n -n e v e r m i n d -h a v e a n i c e d a y -p l e a s e g e t o u t o f h e r e -i w i l l a l w a y s b e i n y o u r h e a r t -i t h i n k i m e s s e d i t u p -j u s t f o r a s h o r t w h i l e -c a n y o u d r y m y h a i r -u n b e l i e v a b l e -h a p p y a n n i v e r s a r y -t h i s i l l n e s s c a n r e a l l y g e t y o u d o w n -g i v e m e t h a t p l e a s e -d i d y o u k n o w t h a t -w h a t d o y o u t h i n k -n o w i t i s -h o w l o n g w i l l y o u b e g o n e -a r e y o u w o r k i n g t o m o r r o w -i w a n t o n e -i l i k e t o l i s t e n t o m u s i c -p l e a s e s c r a t c h l e f t -i h a d a g r e a t d a y -i w o u l d l i k e t o l i s t e n t o s o m e m u s i c -h o w a r e t h i n g s g o i n g f o r y o u -i n e e d s u c t i o n -i l i k e a l o t o f d i f f e r e n t s p o r t s -a r e y o u d o i n g a n y t h i n g s p e c i a l t o n i g h t -i r e a l l y l i k e t o t a l k a b o u t i t -y o u k n o w h o w i t w o r k s -i h o p e y o u c e l e b r a t e m a n y m o r e -c a n y o u h e l p m e r e o r d e r c h e c k s f o r m y c h e c k i n g a c c o u n t -i h a v e a l w a y s l i k e d t h a t p l a c e -h u h -i l i k e t o h a v e c o m p a n y c o m e t o v i s i t -w h a t k i n d i s i t -i w i l l t a l k t o y o u s o o n -w h o a r e y o u l o o k i n g f o r -l e a v e m e a l o n e -w h a t a b o u t y o u -w h a t d o y o u t h i n k a b o u t t h a t -p l e a s e s c r a t c h s o f t e r -c h a n g e t h e s u b j e c t -o n c e a g a i n -i u n d e r s t a n d t h a t -p l e a s e s t o p -f i n e h o w a r e y o u -c a n y o u h e l p m e b a l a n c e t h e a c c o u n t -i w a s s u p p o s e d t o -i h o p e e v e r y t h i n g t u r n s o u t o k a y -w h a t w e r e t h e y -d i d y o u h a v e a g o o d w e e k e n d -i t d e p e n d s -a l i t t l e m o r e -s t o p f i d g e t i n g -h o w h a v e y o u b e e n -w h a t a r e y o u t a l k i n g a b o u t -i h a d t o g o b a c k -s o m e t i m e s i f e e l n o o n e c a n u n d e r s t a n d w h a t i t f e e l s l i k e t o g o t h r o u g h t h i s -w h a t d o y o u t h i n k w e s h o u l d d o -i r e a l l y t r i e d -w h y d i d y o u g e t s o m a n y -e x c u s e m e -h a v e y o u e v e r h a d t h o s e -w h o a r e y o u t a l k i n g a b o u t -w o u l d y o u l i k e t o g o s o m e w h e r e o v e r n i g h t -p l e a s e m a k e t h i s a g a i n -w h a t a r e y o u t r y i n g t o d o -t h a t d e p e n d s -w h a t h a p p e n e d t h i s t i m e -i t c e r t a i n l y d i d -w o u l d y o u b e w i l l i n g t o t r y t o g o o n a v a c a t i o n -i n e v e r l i k e d t h e m -h o w n i c e t o m e e t y o u -s w e e t d r e a m s -h o w l o n g d o y o u t h i n k i t w i l l b e -i t h i n k y o u a r e w r o n g -t e l l m e a b o u t i t -w h o w a s t h a t -h o w i s y o u r d a y g o i n g s o f a r -c a n y o u h e l p t o c l e a n u p -w h e r e a r e t h e y -h o w c o m e -s h o w m e -i t h o u g h t s o -i c a m e e a r l y -t h a n k y o u -c a n y o u m a k e m e s o m e t h i n g t o e a t -c a n y o u h e l p m e m a k e a d e p o s i t i n t h e b a n k -b o n v o y a g e -a r e y o u d o i n g a n y t h i n g s p e c i a l t h i s w e e k e n d -t h a n k s f o r s t o p p i n g b y -i l i k e t o l o o k a t t h e s u n s e t -n o l o n g e r -i n e e d t o c a r e f o r f e m i n i n e i s s u e s c a n y o u h e l p m e -c o n g r a t u l a t i o n s o n y o u r g r a d u a t i o n -i t h i n k t h i s t a s t e s s o g o o d -t h a t w a s f u n -h a v e a s a f e f l i g h t -h o n e s t t o g o o d n e s s -i h a v e t h e c h o i c e -h e y g o o d l o o k i n g -d o y o u r e a l l y t h i n k s o -h o w a b o u t t h a t -w h e r e a r e y o u s i t t i n g -i k n o w i t -w h a t a r e y o u t r y i n g t o t e l l m e -w i l l y o u s t a y f o r a w h i l e -p l e a s e g e t m e s o m e -i r e a l l y n e e d t o t a l k w i t h y o u -i l i k e t o w a t c h s p o r t s o n t v -i f e e l l i k e i t -i w o u l d l i k e t o h a v e v e g e t a b l e s w i t h m y d i n n e r -m a y i g o w i t h y o u -i l i k e t h a t p l a c e -i w i s h t h e m l u c k -i n e e d a h a i r c u t -w o u l d y o u l i k e t o t a k e a r o a d t r i p -w h a t t i m e t o m o r r o w -p l e a s e b u t t o n m y s h i r t -g o o d n i g h t i h o p e y o u s l e e p w e l l -i m i g h t a s w e l l -i t s o u n d s g o o d t o m e -p l e a s e k e e p i n m i n d i a m a p e r s o n -t h a n k y o u f o r v i s i t i n g w i t h m e -o f c o u r s e -d o y o u l i k e y o u r k i n d o f w o r k -i a m g e t t i n g a l o n g -i s t h a t o k a y -w h a t a r e y o u w a i t i n g f o r -m o s t o f t h e t i m e -w e a r e s o g o o d t o g e t h e r -w i s h m e l u c k -o n e m o r e m i n u t e -w h a t a b e a u t i f u l d a y -c a n i g e t a n e w o n e -i n e e d t h e u r i n a l -i t i s t i m e t o l e a v e -w h a t t o o k y o u s o l o n g -p l e a s e r u b m y n e c k -i g e t s c a r e d t o d e a t h -i w o u l d l i k e t o h a v e s o m e r a i s i n s -i t w i l l b e a w h i l e -w e o u g h t t o t r y t h a t -i l i k e t o w a t c h t v -c a n y o u m a i l t h i s l e t t e r f o r m e -w i s h m e l u c k -y o u a r e m y b e s t f r i e n d -i t s t i l l h u r t s -h a v e a g r e a t t r i p -i t o l d y o u -i w a n t t o t a k e a s h o w e r -i h a v e s o m e t h i n g t o s a y a b o u t t h a t -i f e e l a n g r y -w h a t a r e y o u t r y i n g t o s a y t o m e -j u s t g r e a t -b o y a m i g l a d -p l e a s e h e l p m e g e t d r e s s e d -i a m n o t h u n g r y a n y m o r e -a m a z i n g -t o o f u n n y -i n e e d a p i l l o w -w h a t a m i d o i n g -w h a t a r e y o u g o i n g t o d o t o d a y -h o w d i d y o u k n o w -w h a t h a p p e n e d t o y o u -c a n y o u m a k e a n a d j u s t m e n t -w i l l y o u p r e p a r e d i n n e r -b o y d o i e v e r k n o w -h e l p m e p u t t h i s o n -i n e e d t h e b e d p a n -y o u a r e i n c o r r e c t -c a n y o u t u r n m e o v e r -i w o u l d l i k e y o u t o s e e y o u -i c a n h e a r a n d u n d e r s t a n d e v e r y t h i n g t h a t y o u a r e s a y i n g -i t t a k e s t i m e -h o w m u c h -i l i k e t h a t -a r e t h e y a n y g o o d -d i d y o u g e t m y m e s s a g e -b e f o r e i g o o n -c a n y o u t h i n k o f s o m e t h i n g i c a n d o t o k e e p b u s y -p l e a s e r u b m y s h o u l d e r s -y o u l o o k g r e a t -w h e r e w o u l d y o u l i k e t o g o f o r d i n n e r -w h i c h o n e i s i t -c o u l d b e b e t t e r -j u s t a m i n u t e l e t m e t h i n k a b o u t t h a t -d o y o u r e a l l y t h i n k s o -c h a n g e t h e s u b j e c t p l e a s e -l e t m e t e l l y o u w h a t i d i d -i k n o w -t h a n k y o u f o r b e i n g s u c h a g o o d f r i e n d -i l o v e y o u -w h a t c a n w e d o t o m a k e y o u r d a y m o r e s p e c i a l -a r e y o u o u t o f y o u r m i n d -c a n y o u t a k e m e t o t h e s t o r e -i a m l u c k y t o h a v e y o u i n m y l i f e -t e l l m e w h a t y o u t h i n k i s a i d -u n f o r t u n a t e l y -w e w i l l d o i t t o m o r r o w -i l o o k f o r w a r d t o t a l k i n g t o y o u s o o n -i h a v e a n i t c h o n m y b a c k -i w o u l d l i k e t o h a v e a s o d a -i w a n t a k i s s -m a y b e t o m o r r o w -i w i s h i c o u l d c h a n g e t h i n g s f o r y o u -p o o r t h i n g -i w a n t t o d o i t -a c c e p t m y d e c i s i o n -i d o n o t h a v e a n y i d e a -w h e n i t a l l t o o k p l a c e -s h o u l d i b e c o n c e r n e d -i l i k e t o g o t h e r e -y o u a r e t h e b e s t -t h i s i s a n e m e r g e n c y -s t o p t a l k i n g -h a v e a n i c e d a y -i c o u l d p r o b a b l y d o b e t t e r -i w a n t t o t a l k t o y o u a b o u t i t -c a n y o u w a s h m y h a i r -c a n y o u b e a t t h a t -d o e s a n y o n e w a n t t o g o f o r a w a l k -a r e y o u w o r k i n g t o d a y -d i d i t h u r t -i t w a s w r o n g -y o u k n o w w h a t i t t a k e s -y e s i a g r e e -i n e e d s o m e t o o t h p a s t e -t h e s t a r s a r e t w i n k l i n g -h o w a b o u t i f w e l i g h t a f i r e i n t h e f i r e p l a c e -w h a t d o y o u t h i n k o f i t -y o u c o u l d h a v e h e l p e d o u t a l i t t l e b i t -i w o u l d l i k e a p i e c e o f c a k e -i f i c o u l d i w o u l d -i g u e s s s o -i g a v e m y f i n a l w o r d -g i v e m e a c a l l i n a f e w m i n u t e s -w h a t t i m e a m i g o i n g -w e l l i t s u r e f e e l s l i k e i t -i n e e d m y h a i r t o b e e a s y t o c a r e f o r -w h a t d i d i t s a y -t h i s i s a n e m e r g e n c y -i n e e d t o h a v e m y w h e e l c h a i r f i x e d -t r y n o t t o b e s o s a d -w o u l d y o u g e t t h e m a i l -s t o p t h a t -a r e y o u s e r i o u s -t e l l m e m o r e -t h a t w o u l d b e a b i g h e l p -w h a t c a n i d o -i t l o o k s l i k e a b l i z z a r d -i t m i g h t w o r k -w h o s e t u r n i s i t t o w a l k t h e d o g -i f o r g o t a b o u t t h a t -c a n i t a k e t h e s e w i t h m e -d o y o u k n o w w h e r e i a m g o i n g -w h o s a i d s o -h e l p m e p u t o n m y p a n t s -g o b a c k t o b e d -a r e y o u b u s y -n o j o k e -p l e a s e l e t m e f i n i s h -c a n i h e l p -w h a t i s i t n o w -i w o u l d l i k e t o l i s t e n t o t h e i p o d -w h e n d o w e e a t -h o w d o y o u f e e l -i n e e d t o l a y d o w n -p u t t h a t h e r e -w h y n o t -h a p p y c h a n u k a h -p r e t t y u g l y h u h -i f o u n d i t -t h a t w o u l d b e g r e a t -w e a r e g o i n g -g o o d m o r n i n g -c a n w e p l a n o u r d a y f o r t o m o r r o w -w h a t a r e m y c h o i c e s -k e e p g o i n g -i a m f u l l -h e l l o -c a n i h a v e s o m e c h i p s a n d d i p -i w a n t t o s t a y -w a i t a m i n u t e -w h e r e d i d i g e t t h i s -i w a s o n t i m e -i g o t o w o r k -i w a s j u s t c u r i o u s -a t l u n c h -w h a t g r a d e a r e y o u i n -n o t m u c h a t a l l -w h a t d o y o u t h i n k i s a i d -s u r e i a m -i w a n t t o t r y a n e w h a i r c u t -w h a t o t h e r c h o i c e d o i h a v e -i g u e s s -m a y i s a y s o m e t h i n g -o n e n e v e r k n o w s -i h a t e t h i s l i f e -t h a n k s a l o t i t r e a l l y h e l p s -a l i t t l e b e t t e r -y o u a r e w r o n g a b o u t t h a t -f u c k l o u g e h r i g -w h o s a i d s o -a r e y o u s e r i o u s -w h e n -i t h i n k i a m r e a d y t o g o -h a n d m e t h a t p l e a s e -i s t h a t r i g h t -i u s e t h i s m a c h i n e t o c o m m u n i c a t e -i a m n o t h u n g r y a t a l l -w h a t a j e r k -h a v e a h e a r t -i w o u l d l i k e s o m e m o r e -i t t a k e s m e a l i t t l e l o n g e r t o a n s w e r p l e a s e b e p a t i e n t -p l e a s e h e l p m e w a s h m y h a n d s -w h e n y o u a r e h e r e -y o u m i s u n d e r s t o o d m e -w i l l i s e e y o u l a t e r -t u r n i t o v e r -a b s o l u t e l y r i d i c u l o u s -w h a t e l s e a m i g o i n g t o d o -w e h a v e t o w a i t -i a m s t a r v i n g -i f e e l t e r r i b l e t h a t y o u a r e s o u n h a p p y -w h a t s h o u l d w e d o f o r y o u r b i r t h d a y -i h a d a g r e a t t i m e -g o o d i d e a -p l e a s e h e l p m e w a s h m y f a c e -i t s o u n d s c o n f u s i n g -i h o p e i t i s -i a g r e e -i l o v e t o e a t t h i s -a r e w e s t i l l g o i n g -a n y t h i n g i c a n d o -t e l l m e a b o u t y o u r f a m i l y -i n e v e r l i k e d t h a t -i w a n t i t t o b e o v e r -e x c u s e m e f o r i n t e r r u p t i n g -i w a s o n l y k i d d i n g -o h m y g o d -t o o e a r l y f o r m e -c a n y o u u n d e r s t a n d m e o k a y -w h e n y o u g e t b a c k -g o o d b y e -c a n y o u t u r n o n t h e c o m p u t e r -y o u m e a n s o m u c h t o m e -c a n y o u w a i t a m o m e n t -i n e e d s o m e t h i n g t o d r i n k -w h o s e i s t h a t -i w a n t t o g o o n a d a t e -h i -i w o r r y a b o u t t h a t -c h a n g e t h e s u b j e c t -p l e a s e g e t m e m y c a s e -i w o u l d l i k e t o h a v e s o m e d e s s e r t n o w -p l e a s e b r u s h m y h a i r -a s s o o n a s p o s s i b l e -y o u m a k e m e s o h a p p y -o o o o p s -p l e a s e h e l p m e g e t r e a d y -t e l l m e w h a t y o u a r e d o i n g -i h e a r y o u -i w o u l d l i k e t o g o f o r a w a l k -w h e r e i s t h e r e s t r o o m -t h a t w a s n i c e o f h i m -i h a v e a g r e a t i d e a -p l e a s e c h a n g e t h e p o s i t i o n o f t h e b e d -t a l k t o y o u l a t e r -e a s y f o r y o u t o s a y -g o o d n i g h t i l o v e y o u -a r e y o u g e t t i n g r e a d y f o r b e d -i n e e d a t i s s u e -h o w m a n y m o r e -i t f e e l s g o o d -c a n y o u m a k e i t w a r m e r i n h e r e -i r e a l l y f e e l i c a n d o i t -h o w m u c h i s i t -g o o d n i g h t -i l i k e h e r -a l s s u c k s -y o u k n o w t h a t -w i l l y o u s t a y a n d h e l p m e f i n i s h t h i s -i h a t e i t -w i l l i s e e y o u n e x t -w o u l d y o u u n l o a d t h e g r o c e r i e s f r o m t h e c a r -i n e e d h e l p n o w -i t h i n k i a l r e a d y s a i d t h a t -i w o u l d l i k e t o g e t a m a n i c u r e -w h a t w e r e y o u t h i n k i n g -l e t m e s e e i t -p l e a s e o p e n t h e w i n d o w a n d g e t s o m e a i r i n h e r e -c a n y o u p l e a s e h o l d o n f o r a m o m e n t i h a v e a n o t h e r c a l l -i a g r e e w i t h y o u -w h e n w i l l y o u b e b a c k -i w i s h i c o u l d h e l p y o u -c a n y o u h e l p m e s h a v e -w e l l a n y t h i n g i s p o s s i b l e -w a i t f o r t h e r e s t o f t h e m -h a v e a g o o d d a y -y e s i c a n -i h a v e t o g e t g o i n g -i g o t h e o p p o s i t e w a y -i f e e l l i k e e a t i n g s o m e t h i n g s w e e t -i n e e d h e l p m o v i n g t h i s -i t h a s t o b e -g i v e m e a b r e a k -g o o d b y e -h o w a r e y o u d o i n g -d i d y o u h a v e a g o o d w e e k e n d -o v e r a n d o u t -w h a t h a p p e n e d a t s c h o o l t o d a y -w h a t d i d y o u d o o n t h e w e e k e n d -i w a n t t o h u r r y u p -i w o u l d l i k e t o h a v e s o m e b l u e b e r r i e s -i w i l l a l w a y s b e w i t h y o u -i l i k e t o w a t c h t h e c o o k i n g s h o w s o n t v -i k n o w t h a t -j u s t l o o k i n g -i n o t i c e d i t -e x c u s e m e m a y i s a y s o m e t h i n g -w e h a v e t o s t o p -c a n y o u b r i n g m e m y i p o d -i w o u l d l i k e t o c o m b m y h a i r -p l e a s e t a k e m e o u t s i d e -i w a s s o g l a d -h o w f a s t -w h a t e l s e i s o n -m u c h o b l i g e d -d o y o u k n o w w h y -c a n y o u h e l p m e g e t r e a d y f o r b e d -i a g r e e w i t h t h a t -i h a t e t o e a t t h i s -i m i s s t h e r h y t h m o f c o n v e r s a t i o n -t o o m u c h f o r m e -i f e e l s o r r y a b o u t t h a t -t a k e y o u r t i m e h a v e s o m e p a t i e n c e -p l e a s e c l o s e t h e w i n d o w -w h e r e d o y o u l i v e -a b s o l u t e l y n o t -t h a n k s f o r c a l l i n g -d o y o u t h i n k s o -h o w m u c h m o r e i s t h e r e -i w o u l d l i k e t o g e t a p e d i c u r e -w o u l d y o u l i k e t o w a t c h s o m e t v -p l e a s e f i n d o u t -p l e a s e p u t a p i l l o w b e t w e e n m y k n e e s -w h a t a r e y o u h e r e f o r -i w o n d e r i f i c o u l d g e t a n e w o n e -w h a t t i m e i s i t -i c a n u n d e r s t a n d y o u i t j u s t t a k e s m e l o n g e r t o a n s w e r -i w i l l t r y h a r d e r -t h a n k s f o r t e l l i n g m e -a s m u c h a s i c a n -i t w o u l d b e e a s i e r f o r y o u -w h a t h a v e y o u b e e n u p t o -p l e a s e c u t m y f i n g e r n a i l s -h o w d o y o u f e e l a b o u t t h a t -w h e n y o u f i n d o u t l e t m e k n o w -i w a n t t o b e t o g e t h e r f o r e v e r -c a n y o u h e l p m e -d o y o u w a n t m e t o h e l p y o u w i t h y o u r h o m e w o r k -d o y o u m i n d -i t h o u g h t y o u w e r e g o i n g t o -t h a t h e l p e d t r e m e n d o u s l y -g o o d -i t j u s t s e e m s t o a l w a y s h a p p e n l i k e t h a t -w h a t a r e y o u d o i n g t h i s s u m m e r -i m i s s h o l d i n g y o u -w h a t t i m e w o u l d i b e d o n e -w h o i s g o i n g t o d o t h e g r o c e r y s h o p p i n g -w h o s e t u r n i s i t t o w a s h t h e d i s h e s -i w o u l d r e a l l y l i k e t o d i s c u s s t h a t f u r t h e r -i h o p e t o s e e y o u a g a i n -i w a n t t o t a k e a b a t h -w h e r e s h o u l d i g o -p l e a s e s c r a t c h l o w e r -c o u l d y o u r e p e a t w h a t y o u s a i d -i c o u l d n e v e r h a v e d o n e t h i s w i t h o u t y o u r h e l p a n d s u p p o r t -i w o u l d l i k e t o h a v e a n o r a n g e -i a m s o g r a t e f u l f o r a l l y o u h a v e d o n e f o r m e -t h a n k y o u f o r h e l p i n g m e -i n a w h i l e -a r a t h e r r e f r e s h i n g o u t l o o k -s o m e t i m e s i j u s t n e e d t o f e e l s o r r y f o r m y s e l f -t h e r e u s e d t o b e -h o w a r e y o u -w h o p r o g r a m m e d t h i s v o i c e m a c h i n e -e i t h e r t o d a y o r t o m o r r o w -h o w c o u l d i b e m a d a t y o u -w h a t d i d y o u s a y -i w a n t t o l a y o n m y b a c k -s o m e o n e h e l p m e -i w a n t a h u g -w h a t d i d y o u d o t h i s m o r n i n g -c a n i h a v e s o m e m o r e p l e a s e -t h e r e i s n o r a i n i n t h e f o r e c a s t -d i d y o u u n d e r s t a n d -p l e a s e r e m o v e t h a t -i w o u l d l i k e t o h a v e a s n a c k -y o u r h e l p m e a n s s o m u c h t o m e -i c e r t a i n l y d i d -y e s i c a n d o t h a t -d o e s a n y o n e h a v e a n y i d e a s -p l e a s e t u r n o f f t h e l i g h t s -c o n g r a t u l a t i o n s o n y o u r w e d d i n g -i t h a p p e n e d a g a i n -i t i s v e r y i m p o r t a n t -f u c k a l s -i t i s j u s t y o u r i m a g i n a t i o n -i w o u l d l i k e t o p u t o n m y p a j a m a s -h a p p y n e w y e a r -d i d y o u d o t h e l a u n d r y -h e c a n d o i t -i t m i g h t w o r k o u t -i w o u l d l i k e t o h a v e d e s s e r t l a t e r -p l e a s e s c r a t c h r i g h t -y o u h e l p e d a l o t -i w o u l d l i k e t o b r u s h m y t e e t h -i n e e d s o m e h e l p w i t h t r y i n g t o f i g u r e o u t t h e b e s t w a y t o c o m m u n i c a t e w i t h y o u -p l e a s e m o v e t h e p i l l o w u n d e r m y n e c k -h e j u s t t o o k o f f -i r e a l l y l i k e c h o c o l a t e -h o w d o y o u k n o w -h o w d o t h e y k n o w -g e t h e l p n o w -p u t t h a t t h e r e -i n e e d h e l p p u t t i n g o n m y s h o e s -a c c e p t m y d e c i s i o n -w h a t i s y o u r s c h e d u l e -i w a s d o i n g e x c e l l e n t -i k n o w i t -m a y b e l a t e r -g i v e m e s o m e -a s c a r e f u l a s y o u c a n -w h a t a t u r k e y -h i h o w a r e t h i n g s g o i n g -i a g r e e -c a n i h a v e a s p o o n -i t m a k e s m e v e r y n e r v o u s -i r e a l l y g e t o f f o n i t -t h a t i s n o t f a i r -n o k i d d i n g -t h a n k y o u a n y w a y -t h e l a s t t i m e -i n e e d t o r e s t -n o i m e a n t s o m e t h i n g e l s e -a r e y o u r e a d y -w o w -c a n i h a v e s o m e m a y o n n a i s e o n m y s a n d w i c h -m a y i h a v e s o m e t h i n g t o e a t -m a k e s m e m a d -w h a t i s t h e n e x t p l a n -c a n y o u r e a d m e a b o o k -i f e e l g r e a t -t h i s i s d e l i c i o u s -s t o p w h a t y o u a r e d o i n g -i s u p p o s e s o -l e t m e a n s w e r -i w a s o n l y j o k i n g -w h a t c a u s e d i t -i n m y r o o m -t h i s i s d i f f e r e n t -i d i d o k a y -p e r f e c t -w i l l y o u b e t h e r e -c a n y o u p l e a s e p i c k t h a t u p o f f t h e f l o o r i d r o p p e d i t b y a c c i d e n t -d o y o u h a v e a n y b r o t h e r s o r s i s t e r s -i h o p e y o u f e e l b e t t e r -w o u l d y o u u n p a c k t h e g r o c e r i e s -y o u a r e t h e m o s t s p e c i a l p e r s o n -a n o t h e r r a i n y d a y -w h a t d i d y o u d o l a s t n i g h t -p l e a s e t u r n t h a t o f f f o r m e -h o w a b o u t y o u -r e a l l y -c a n i d o t h i s -i s h o u l d e x p l a i n -h i m o m -i t h i n k t h a t i s c o r r e c t -t e l l m e h o w m u c h -t h a n k s f o r v i s i t i n g -g o o d n i g h t -i b l e w i t -i n e e d a n a p p o i n t m e n t t o h a v e m y e y e b r o w s w a x e d -w o u l d y o u l i k e t o t r y t h e n e w r e s t a u r a n t -w h a t d o y o u t h i n k o f m y a r t i f i c i a l v o i c e -i w a s g o i n g t o -i n e e d a b l a n k e t -e x c e e d i n g l y g o o d -i w a s s o d i s a p p o i n t e d -w o u l d y o u m i n d i f i t a l k w h i l e y o u a r e i n t e r r u p t i n g -w h e n a r e w e l e a v i n g -i t h o u g h t i w a s t h r o u g h -i d i s a g r e e -j u s t p l a i n g o o d -a l o t o f f u n -i a m s o r r y -i a m s o h u n g r y -l a t e a t n i g h t -c a n y o u h e l p m e w i t h m y b r e a k f a s t -c a n i t a l k t o y o u -i w a n t t o k n o w w h a t i t i s -w h a t t i m e d o y o u t h i n k -h o w d o y o u k n o w -h o w l o n g a g o -i w a n t t o k n o w -b u t g u e s s w h a t -s s s s s s i w a s t r y i n g t o w h i s t l e -i w o u l d l i k e t o h e l p i f i c a n -i a m g e t t i n g i t -s e e y o u s o o n -i w o u l d r a t h e r e a t t h a t -i h a v e a n i t c h o n m y f o o t -w h a t t i m e w i l l y o u b e h o m e -i l i k e t o s e e t h e w a v e s i n t h e o c e a n -h o w a r e y o u -g o o d n i g h t s l e e p t i g h t -y o u g o a h e a d -p e r f e c t l y s a i d -h e l p -i d o u b t t h a t -i w i l l c a l l y o u s o o n -i w o n -d o i t -g e t o u t o f h e r e -a n o t h e r g o r g e o u s d a y -c e r t a i n l y -o h m y g o d -w h e n a r e t h e y c o m i n g -y o u a r e k i d d i n g -i t s o u n d s g o o d -y o u k n o w w h a t i t h i n k -p l e a s e t u r n o f f t h e t v -y o u h e l p e d a l o t -i s t h a t a y e s o r n o -i w o u l d l i k e s o m e p r e t z e l s -t h a n k t h e l o r d f o r s m a l l f a v o r s -i w i l l n o t -t h a t i s a m a z i n g -i a m t i r e d -w e w i l l g e t t o i t t o m o r r o w -c o n g r a t u l a t i o n s o n y o u r e n g a g e m e n t -y o u c a n d o i t -s a y t h a t a g a i n i m i s s e d t h a t -i h a v e n o t i c e d t h a t -i a m h e r e f o r y o u -w o u l d y o u l i k e t o g o t o s e e a s h o w -a r e y o u k i d d i n g m e -i t r u s t y o u -w o u l d y o u d o i t -j u s t a n s w e r m y q u e s t i o n -c a n y o u h e l p t o p u t t h e g r o c e r i e s a w a y -w h y a r e y o u c o n c e r n e d -w h a t d i d y o u c o m e w i t h -w h a t k i n d o f j o b d o y o u h a v e -h o w o l d a r e y o u -o v e r a n d o v e r a g a i n -i l i k e t o d o i t -m e r r y c h r i s t m a s -i m a y n o t g o b a c k -i t c o u l d h a v e b e e n -h o w d i d i t t u r n o u t -c a n y o u h e l p m e g e t d r i e d o f f -i g o o f e d -w o u l d y o u c o m e -i w i s h i k n e w w h a t h a p p e n e d -i s a i d i w a s -p l e a s e s c r a t c h h i g h e r -t h a t h u r t s -w h a t d o y o u h a v e t o d o -y o u a r e r i g h t a b o u t t h a t -y e a h -i w a n t t o g o -b e v e r y v e r y c a r e f u l -c a n i h a v e s o m e c h i c k e n -p l e a s e u s e c o n d i t i o n e r t o t a k e o u t t h e t a n g l e s i n m y h a i r -a r e y o u a l o n e -w h e r e d o y o u g o t o s c h o o l -e x p l a i n t h a t t o m e -w h e r e a r e y o u g o i n g -i l i k e t o g o o n c a r r i d e s -i w i l l s t i l l n e e d i t -a r e y o u g o i n g t o p r e p a r e d i n n e r -s o r r y t o k e e p p o p p i n g o f f -p l e a s e g e t m e m y h a n d b a g -i n e e d i t -h o w d a r e y o u -t h e r e w a s s o m e t h i n g e l s e i w a s g o i n g t o a s k y o u -i a m s o r r y t o h e a r t h a t -d i d y o u p a c k y o u r l u n c h -p l e a s e t u r n o n t h e l i g h t s -c a n y o u g e t t h e n e w s p a p e r f r o m o u t s i d e -i w a n t t o s h a r e t h e r e s t o f m y l i f e w i t h y o u -w h y w h a t d o y o u m e a n -n o b o d y t o l d m e t h a t -w h a t t h e n -d o y o u a g r e e -w i l l i b e a b l e t o g e t a n o t h e r o n e -p l e a s e w a i t f o r m e -d o y o u k n o w w h a t h e d i d -c a n i h a v e a t i s s u e -w h y a r e y o u h e r e -c o n g r a t u l a t i o n s o n t h e b i r t h o f y o u r b a b y -l e t m e s e e t h a t -p l e a s e w a i t u n t i l i f i n i s h w h a t i a m t r y i n g t o s a y -a r e y o u c o m i n g -h o w l o n g h a v e y o u b e e n d o i n g t h a t -h o w a b o u t i t -i t f r u s t r a t e s m e -i w i l l -w h e r e i s i t -i n e e d y o u t o c a l l t h e n u r s e -o k a y -i n e e d s o m e s o a p i n t h e s h o w e r -t h a t s h o u l d b e h a r d t o d o -i r e f u s e t h a t t r e a t m e n t -a l s a f f e c t s t h e b o d y i t d o e s n o t a f f e c t t h e m i n d -w h e r e w e r e y o u -p l e a s e b r u s h m y t e e t h -g u e s s w h a t i w a n t -d o y o u n e e d m e t o h e l p y o u -a r e y o u l i s t e n i n g t o m e -d o y o u n e e d m y h e l p t o e x p l a i n t h i s -o k a y g o r g e o u s -w e n e e d t o t a l k -i r e a l l y t r i e d -t a k e t h a t a w a y f r o m m e -p l e a s e t e l l m e i f y o u u n d e r s t a n d w h a t i a m s a y i n g -w a i t u n t i l t o m o r r o w -i r e m e m b e r t h e l a s t t i m e i d i d t h a t -p l e a s e t u r n t h a t o n f o r m e -t h a t m a k e s m e m a d -b o y t h a t f e e l s g o o d -i t s h o o k m e u p -y o u w i l l l o v e i t -h o w f a b u l o u s f o r y o u -i t i s n o t t h a t i m p o r t a n t -i w o u l d l i k e t o e a t a s t e a k -y o u a r e n o t g o i n g t o b e l i e v e t h i s -i a m d o i n g i t -i a m h a v i n g t h e b e s t t i m e -i r e a l l y l i k e t o e a t p i z z a -c a n i u s e i t -p l e a s e h e l p m e m o v e o v e r t h e r e -i a m a l l e r g i c t o i t -i h a v e a n i t c h -p l e a s e r e a d t o m e -t h a n k y o u f o r y o u r t h o u g h t f u l n e s s -e v e r y t h i n g b o t h e r s m e -c a n y o u p l a y a d v d -r e a d y a n d w a i t i n g -i w o u l d l i k e s o m e i c e c r e a m -i w a n t t o g o w i t h y o u -n o t v e r y g o o d t o d a y -w h e n w i l l y o u c o m e b a c k -w h a t t i m e -a l r i g h t -c o m e b a c k l a t e r -c o m e t a l k w i t h m e -m y f e e t a r e c o l d c a n i h a v e m y s l i p p e r s -w h y n o t d o i t r i g h t a w a y -w o u l d y o u h e l p m e w i t h m y c l o t h i n g p l e a s e -i s t h e r e a n y p i e -w o u l d y o u l i k e t o g o o u t s i d e -w h e n i w a n t t o -c a n i h a v e s o m e t h i n g e l s e -i n e e d m y g l a s s e s -y o u a r e a m a z i n g -p l e a s e s c r a t c h h a r d e r -c a n y o u c u t t h e f o o d f o r m e -c o m e r i g h t b a c k p l e a s e -i c a n f o l d t h e l a u n d r y -b o y a m i g l a d y o u c a l l e d -i w a n t t o t h a n k y o u -i w a s t r y i n g t o t e l l y o u -g o o d t o s e e y o u -i t w o r k s o n c e i n a w h i l e -h o w l o n g w i l l i t t a k e -i g r e a t l y a p p r e c i a t e t h a t -i w o u l d l i k e t o h a v e a b a n a n a -g o o d m o r n i n g -i l i k e t o g o t o t h e m o v i e s -j u s t t e l l t h e t r u t h -y o u h a v e t o w a i t -p a r d o n m e -i w a s j u s t k i d d i n g -h a p p y b i r t h d a y -a n o t h e r s n o w y d a y -w h e r e c a n i g e t i t -y o u c a n g i v e i t t o m e -n o t s o g o o d t o d a y -w h a t d o y o u w a n t t o d o -g r a b o n e o f t h o s e -b r i n g t h a t o v e r h e r e -a s u s u a l -p l e a s e k e e p i n m i n d i a m a h u m a n b e i n g -w a i t l e t m e r e p h r a s e t h a t -d i d y o u s t r a i g h t e n u p y o u r r o o m -s i t o v e r h e r e w i t h m e -m y f e e t a r e c o l d c a n i h a v e m y s l i p p e r s -d i d y o u s t a r t y o u r h o m e w o r k -y o u m a k e m y l i f e b e t t e r -i s u r e h o p e s o -i n e e d t o s h a v e -s o m e t h i n g l i k e t h a t -c a n y o u h e l p m e p l e a s e -d i d y o u s e e t h a t -h a v e a s a f e t r i p -w h a t d o e s t h a t m e a n -d o y o u u n d e r s t a n d m e -y o u r f r i e n d s h i p m e a n s s o m u c h t o m e -y o u c a n c o m e u p w i t h s o m e t h i n g b e t t e r -w h e r e -c o u l d y o u r e p e a t t h a t -c a n y o u t u r n t h e t v o n -i t h a p p e n s e v e r y s o o f t e n -a r e y o u p i c k i n g u p t h e k i d s -a r e y o u c o m f o r t a b l e -h o w f a s t c a n y o u d o i t -d o y o u u n d e r s t a n d m e -w h e n d o w e g o -c a n y o u h e l p m e w r i t e a c h e c k -s e e y o u l a t e r -i m i s s t a l k i n g t o y o u -w h a t c o u l d p o s s i b l y h a p p e n -i t h i n k h e i s k i n d o f c u t e -i t t o o k s o l o n g -s o m e t i m e s i j u s t w a n t t o s c r e a m -i a m g o i n g h o m e -t h a n k s a l o t -i t h i n k t h a t i s u n n e c e s s a r y -t h a t m a k e s m e l a u g h -i w o u l d l i k e t o h a v e a n i c e d t e a -i w a n t t o e a t n o w -i t h i n k i d i d i t w r o n g -a l l t h e t i m e -d o y o u k n o w w h e r e w e a r e g o i n g -i r e a l l y t r y -d o i t e l l y o u o f t e n e n o u g h h o w m u c h i l o v e y o u -c o m e t o t h i n k a b o u t i t -g u e s s w h a t -y o u a r e w r o n g -i c a n h e a r a n d u n d e r s t a n d e v e r y t h i n g y o u s a y -m a y i t a k e a m e s s a g e -h o w w i l l y o u k n o w -w h a t w e r e y o u a b o u t t o t e l l m e -m a y b e m a y b e n o t -p u t t h a t d o w n -w h e n i g e t d o n e -m a y i i n t e r r u p t y o u -i t r e a l l y h e l p s -d o y o u w a n t t h a t -i r e a l l y l i k e i t -t e l l m e a b o u t y o u r s e l f -y o u w o r k a l o t -i t h i n k y o u a r e r i g h t -w a n t t o b e t -i w o u l d l i k e a s a l a d -o u c h -o n c e i n a w h i l e -s o o n e r o r l a t e r -t h a n k y o u f o r j u s t b e i n g y o u -i g e t c r a n k y -w h a t a r e y o u g o i n g t o d o t o n i g h t -h o w w a s y o u r d a y a t s c h o o l -y o u b e t t e r c o m e -c o u l d y o u s p e a k u p a l i t t l e -c a l l m e b a c k w h e n y o u c a n -w i l l y o u d o m e a f a v o r -w h a t k i n d o f c o o k i e s d o y o u h a v e -l e t m e t e l l y o u w h y i w a s u p s e t -l i s t e n t o t h a t -a h n o w i s e e -c a n y o u d o i t r e a l q u i c k -i w o u l d l i k e a f e w c h e r r i e s -i f t i m e a l l o w s -n o t a n y m o r e -w h a t l u c k -i s h e g o n e -d o y o u w a n t m e t o t a k e c a r e o f t h a t -j u s t f i n e -i n e e d t o b e w i p e d -h i d a d -e x c u s e m e -c a n y o u g e t m e p i l l o w -h o w o f t e n c a n i g e t i t -i g u a r a n t e e i t -i e n j o y e d o u r p h o n e c a l l -c a n i a s k a f a v o r -c o m e t a l k w i t h m e -h o w d i d i t g o -n o t n o w -w h a t a r e y o u l o o k i n g f o r -c a n y o u b r i n g i n t h e m a i l -a n y p a r t i c u l a r r e a s o n -d o i h a v e e v e r y t h i n g -f o r g o o d -c a n i g i v e y o u m y f i n a l d e c i s i o n l a t e r -t h a t d o e s t h e t r i c k -i r e a l l y f e e l b a d -c a n y o u f i l l u p t h e c a r w i t h g a s -i t h i n k s o t o o -t e l l m e a b o u t y o u r d a y -y e s i w a s -i b e l i e v e w h a t y o u a r e s a y i n g -i w o u l d h a v e t o q u e s t i o n t h a t i d e a -g e t o u t o f h e r e -h o w a r e y o u t o d a y -w h e r e d o y o u w o r k -c a n w e m a k e p l a n s f o r t h e w e e k e n d -p l e a s e o p e n t h e w i n d o w -h e s o u n d s r e a l l y n i c e -w a t c h o u t -d o y o u h a v e t h e t i m e t o p l a y -d o y o u k n o w h o w m u c h i a p p r e c i a t e a l l y o u d o -c a n y o u h e l p m e m o v e -p r e t t y p l e a s e -i s t h e r e a n y t h i n g i c a n d o -w h e n i s i t s c h e d u l e d -i n e e d t o r e l a x -i n e e d t o e x p l a i n -w a t c h o u t -i w o u l d l i k e t o h a v e a p e a r -b e a t s m e -d i d y o u b r i n g t h e c l o t h e s t o t h e c l e a n e r s -i n e e d a m a s s a g e -t h a t s u r p r i s e s m e -t h a n k y o u v e r y m u c h -y o u a r e m y s o u l m a t e -c h a n g e t h e s u b j e c t p l e a s e -i h o p e i c a n c e l e b r a t e m a n y m o r e w i t h y o u -w h a t i s i t -d o e s a n y o n e w a n t t o g o t o t h e b e a c h -i w o u l d l i k e t o u s e s o m e m o u t h w a s h -t h a n k y o u f o r m a k i n g t h a t f o r m e -t h a n k g o d -w h a t h a p p e n s a f t e r w a r d s -y o u r e a l l y b e l i e v e t h a t -j u s t o n e m o r e t h i n g -h e l p m e p u t o n m y s o c k s -c a n y o u b e l i e v e t h a t -i n e e d a s h o w e r -g o o d t o t a l k t o y o u -c a n y o u h e l p m e g e t d r e s s e d -l e t m e t e l l y o u w h y -w h a t i s w r o n g -i h a v e a s p e e c h p r o b l e m i u s e a m a c h i n e t o t a l k p l e a s e b e p a t i e n t -p l e a s e c h a n g e t h e p o s i t i o n o f t h e c h a i r -b e f o r e d i n n e r -i w a n t t o k n o w w h a t i t i s -i w i l l b e r e a d y t o e a t i n a l i t t l e w h i l e -i s s h e c o m i n g -b e f o r e i g o -t h e r e i s n o t h i n g i c a n d o a b o u t i t -r e w i n d t h e t a p e p l e a s e -w h y -i p r o m i s e -a s f a s t a s i c a n -d o y o u w a n t t o v i s i t y o u r r e l a t i v e s -i f e e l t e r r i b l e -a m i r i g h t o r w r o n g -y o u k n o w t h e y d o -l o o s e n u p -c a n y o u t u r n o n t h e t v -i w o u l d l i k e t o h a v e a n a p p l e -p l e a s e k e e p i n m i n d i w a s v e r y h e a l t h y j u s t a s h o r t t i m e a g o -g e t a l i f e -n o w a y -w h a t d i d s h e s a y -c a n i t r y o n e -h o w a b o u t i f w e j u s t s t a y i n s i d e -i f e e l s a d -i f o r g o t -i h o p e e v e r y t h i n g w o r k s o u t -l e t m e g o -a r e y o u o k a y -h a v e f u n a t t h e p a r t y -i a m s o p r o u d o f y o u -i w i s h i c o u l d m a k e t h i n g s b e t t e r f o r y o u -y o u a r e s u c h a g o o d p e r s o n t o h e l p m e -k e e p g o i n g i n e e d a b r e a k -i w o n d e r -p l e a s e s t o p n a g g i n g -w h a t m o r e c o u l d i h a v e e v e r w a n t e d t h a n y o u -j u s t w a i t a n d f i n d o u t -e n j o y t h e p a r t y -i n e e d h e l p n o w -y o u r s u p p o r t m e a n s s o m u c h t o m e -c a n w e p l a n o u r d a y -c a n y o u m a k e a p o t o f c o f f e e -h o w w o u l d y o u f e e l -c a n i h a v e s o m e p i c k l e s -c a n y o u p l e a s e c o m b m y h a i r -i n e e d t o u s e t h e b a t h r o o m -n o t h a n k s -l e t m e -w h a t a n i d e a -y o u b e t t e r n o t -i n e e d t o b l o w m y n o s e -s h o u l d i m a k e t h a t p h o n e c a l l -e x c e l l e n t -i u s e a m a c h i n e t o h e l p m e t a l k -i t h a n k y o u f o r e v e r y t h i n g -y o u c o u l d n o t p o s s i b l y u n d e r s t a n d -w h a t h a p p e n e d -i w o u l d l i k e a c a n d y b a r -t h a t i s i n t e r e s t i n g -k i n d o f t i r e d -j u s t a m i n u t e -i f e e l l i k e e a t i n g s o m e t h i n g s a l t y -d o y o u h a v e a n y c h o c o l a t e -r e a l l y -i h a v e t o g o -h a v e y o u b e e n t h e r e -i b e l i e v e i t -w h a t w a s h e d o i n g -h o w d i d i d o -l e t m e t e l l y o u a b o u t i t -w o u l d y o u l i k e s o m e t h i n g t o d r i n k -d o y o u u n d e r s t a n d w h a t i m e a n -h e l p y o u r s e l f -w h a t a r e y o u d o i n g -t h e n w h a t a f t e r t h i s -l i s t e n t o m e -h a v e y o u h e a r d a n y t h i n g -i w o u l d d o s o m e t h i n g l i k e t h a t -a n y o n e s i t t i n g h e r e -h o w i s t h e w e a t h e r -n o b o d y s e e m s t o u n d e r s t a n d -p l e a s e -i m i g h t c h e c k t h a t o u t t o m o r r o w -i a m s o h a p p y t o h a v e y o u a s a f r i e n d -l o o k o u t w o r l d h e r e i c o m e -w h a t d o i d o n o w -a r e w e f i n i s h e d y e t -o f c o u r s e i d o -i l i k e i c e c r e a m -y o u s h o u l d h a v e t o l d m e -i s e e -i n e e d y o u t o c a l l m y f a m i l y -i h o p e y o u k n o w h o w m u c h i a p p r e c i a t e y o u -a r e y o u h u n g r y -i u s e d t o -t a k e t h a t a w a y -s i d e b y s i d e -f o r g e t a b o u t i t -i w a n t t o l a y o n m y r i g h t s i d e -w h a t i s t h a t -t o m o r r o w m o r n i n g -i t w a s n o g o o d -i w o u l d l i k e t o e a t s o m e p o t a t o e s -w e w i l l g e t t o i t l a t e r -t h a n k s f o r e v e r y t h i n g -d o e s t h a t m a k e s e n s e -i a l r e a d y d i d -i w i l l s e e y o u -i w a n t t o l a y o n m y l e f t s i d e -i h a v e a l s a n d i h a v e t r o u b l e s p e a k i n g -p l e a s e t u r n o f f t h e h e a t -w h e n w a s t h e l a s t t i m e t h a t h a p p e n e d -i w i s h i c o u l d m a k e i t e a s i e r -c a n y o u a n s w e r t h e p h o n e -h o w o l d a r e y o u -a r e y o u s i c k -d o y o u w a n t m e t o -s o w h a t -g o o d l u c k -t h i s i s a g r e a t p a r t y -h o w w a s y o u r w e e k e n d -d o y o u l i k e h i m -i w i s h y o u w e l l -c a n y o u t a k e o u t m y c o n t a c t l e n s e s -i l i k e t o l i s t e n t o m y i p o d -w e l l i t s u r e l o o k s l i k e i t -i n e e d a n a p k i n -i t h o u g h t i t w o u l d b e g o o d f o r m e -a n y m i n u t e n o w -w h a t d o y o u w a n t -w h a t a r e y o u h e r e f o r -t h i s i s g r e a t -m a k e s y o u w o n d e r -i w o u l d l i k e o t l a y f l a t -c a n y o u h e l p m e s e t u p m y i p a d -t h e r e y o u a r e -i e n j o y e d m y s e l f -i k n o w w h a t y o u m e a n -e n j o y y o u r v a c a t i o n -a b s o l u t e l y n o t -i k n o w w h y -c a n i a s k a f a v o r -i u n d e r s t a n d -w h a t k i n d o f s h o w s a r e o n -n o t h i n g w r o n g w i t h t h a t -p l e a s e b r i n g t h a t o v e r h e r e -t h i s i s a b i t t o o h o t -d i d y o u p u t y o u r c l o t h e s a w a y -w a s t h e r e s o m e t h i n g e l s e -i t h i n k n o t -i s i t a d e a l -t h e y d o t h e s t r a n g e s t t h i n g s -i l o v e y o u m o r e t h a n i c a n s a y -w h a t d o e s i t m a t t e r -c a n y o u h o l d t h i s -y o u b e t y o u r b r i t c h e s -y o u a r e a l l i c o u l d h a v e a s k e d f o r -i w o u l d l i k e t o h a v e a p i e c e o f f r u i t -w h a t d i d y o u m a k e a t s c h o o l t o d a y -i n e e d y o u r h e l p p i c k i n g t h a t u p -i c o u l d e a t t h i s e v e r y d a y -c a n y o u h e l p m e w a s h m y f a c e -c a r e f u l y o u a r e h u r t i n g m e -i f y o u w a n t t o -t h e y u s u a l l y d o -i w o u l d l i k e t o w a s h m y h a i r -i t h i n k t h i s i s p r e t t y g o o d -i r e a l l y d o -p l e a s e p u t a p i l l o w u n d e r m y a r m -i h o p e y o u k n o w h o w m u c h y o u m e a n t o m e -y o u n e v e r k n o w -t h a n k s f o r y o u r h e l p -m y h e a d h u r t s -d r i v e c a r e f u l l y -i s i t o k a y -w h o s e t u r n i s i t t o f e e d t h e c a t -h o w l o n g d i d i t t a k e -c a n i h a v e a b a c k r u b -t h i s t h i n g -n i c e t o t a l k t o y o u -p l e a s e s e t t h e t a b l e -i u s e t h i s m a c h i n e t o c o m m u n i c a t e -c a n y o u m a k e i t c o o l e r i n h e r e -y o u h a v e a g o o d d a y -w o u l d y o u -i h a v e n o i d e a -i n e v e r w a n t t o e a t t h a t a g a i n -i n e e d y o u -i t i s a b s o l u t e l y r i d i c u l o u s -a r e y o u g l a d -a l i t t l e m o r e o f t e n -h o w a r e y o u t h i s m o r n i n g -m a y i h a v e s o m e t h i n g t o d r i n k -w h a t a r e y o u g o i n g t o d o n e x t -i n e e d t o m o v e -w h a t t i m e i s i t -t u r n i t o f f p l e a s e -y o u b e t t e r b e l i e v e i t -w h y d i d t h e y g o t o a l l t h a t t r o u b l e -i j u s t w a n t e d t o f i n d o u t -i d o u b t i t -i w o u l d l i k e t o h a v e s o m e s o u p -g i v e m e a f e w m i n u t e s -y o u a r e r i g h t -i t i s i m p o r t a n t t o m e -i n e e d t o t a k e m y m e d i c i n e -o n c e i n a b l u e m o o n -h e l p m e u n d e r s t a n d t h a t -h e l p m e g e t d r e s s e d -a r e y o u e x c i t e d -w o u l d y o u l i k e t o g o w i t h m e -a b o u t a w e e k -n o w a y -i n e e d a n a p p o i n t m e n t w i t h t h e d e n t i s t -i f o r g o t t o m e n t i o n -g i v e m e a c a l l t o n i g h t -o n c e o r t w i c e -i f t h e r e i s t i m e -i w o u l d l i k e a c o o k i e -i w o u l d l i k e t o g e t a m a n i c u r e -n o n o n o -c a n y o u m o v e m e o v e r t h e r e -d o y o u h a v e a f a v o r i t e s p o r t -i w a n t t o s h o w y o u s o m e t h i n g -n o w a y -t h a n k s a l o t -n o t q u i t e y e t -w h e r e d o i g o diff --git a/bcipy/language/sets/boston_subset.tokenized b/bcipy/language/sets/boston_subset.tokenized deleted file mode 100644 index c621ffa22..000000000 --- a/bcipy/language/sets/boston_subset.tokenized +++ /dev/null @@ -1,20 +0,0 @@ -c a n y o u l i s t e n t o m e p l e a s e l o o k i n m y e y e s -i t s u d d e n l y b e c o m e s i m p o r t a n t -y o u k n o w s o m e t h i n g -w i l l y o u c a l l t h e m -i t h a p p e n s t o b e m y f a v o r i t e -i a m r e a l l y s o r r y -i e n j o y e d s e e i n g y o u t h a n k s -s o i s m i n e -w h a t d i d h e t h i n k a b o u t t h a t -w h e n i a m t i r e d -t h e s u n i s s h i n i n g -w h e n w i l l i s e e y o u n e x t -a l o n g t i m e a g o -i h a d a r e a l b u s y d a y -p l e a s e c o m e r i g h t b a c k -y o u a r e t h e g r e a t e s t k i d s i n t h e w o r l d -i w o u l d l i k e t o e a t s o m e f i s h -h o w l o n g d o e s i t t a k e -i w a s o n l y j o k i n g -w h a t \ No newline at end of file diff --git a/bcipy/language/tests/test_causal.py b/bcipy/language/tests/test_causal.py index b1d7ed191..c645ff6ae 100644 --- a/bcipy/language/tests/test_causal.py +++ b/bcipy/language/tests/test_causal.py @@ -1,117 +1,115 @@ """Tests for CAUSAL Language Model""" -import pytest import unittest from operator import itemgetter -from bcipy.exceptions import UnsupportedResponseType, InvalidLanguageModelException -from bcipy.helpers.symbols import alphabet, BACKSPACE_CHAR, SPACE_CHAR -from bcipy.language.model.causal import CausalLanguageModel -from bcipy.language.main import ResponseType +import pytest +from textslinger.exceptions import InvalidLanguageModelException + +from bcipy.core.symbols import BACKSPACE_CHAR, DEFAULT_SYMBOL_SET, SPACE_CHAR +from bcipy.exceptions import InvalidSymbolSetException +from bcipy.language.main import CharacterLanguageModel +from bcipy.language.model.causal import CausalLanguageModelAdapter @pytest.mark.slow -class TestCausalLanguageModel(unittest.TestCase): +class TestCausalLanguageModelAdapter(unittest.TestCase): """Tests for language model""" @classmethod def setUpClass(cls): - cls.gpt2_model = CausalLanguageModel(response_type=ResponseType.SYMBOL, - symbol_set=alphabet(), lang_model_name="gpt2") - cls.opt_model = CausalLanguageModel(response_type=ResponseType.SYMBOL, - symbol_set=alphabet(), lang_model_name="facebook/opt-125m") + cls.gpt2_model = CausalLanguageModelAdapter(lang_model_name="gpt2") + cls.gpt2_model.set_symbol_set(DEFAULT_SYMBOL_SET) + + cls.opt_model = CausalLanguageModelAdapter( + lang_model_name="facebook/opt-125m") + cls.opt_model.set_symbol_set(DEFAULT_SYMBOL_SET) @pytest.mark.slow def test_default_load(self): """Test loading model with parameters from json This test requires a valid lm_params.json file and all requisite models""" - lm = CausalLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet()) + lm = CausalLanguageModelAdapter() + lm.set_symbol_set(DEFAULT_SYMBOL_SET) def test_gpt2_init(self): """Test default parameters for GPT-2 model""" - self.assertEqual(self.gpt2_model.response_type, ResponseType.SYMBOL) - self.assertEqual(self.gpt2_model.symbol_set, alphabet()) - self.assertTrue( - ResponseType.SYMBOL in self.gpt2_model.supported_response_types()) - self.assertEqual(self.gpt2_model.left_context, "<|endoftext|>") - self.assertEqual(self.gpt2_model.device, "cpu") + self.assertEqual(self.gpt2_model.symbol_set, DEFAULT_SYMBOL_SET) + self.assertTrue(isinstance(self.gpt2_model, CharacterLanguageModel)) + self.assertEqual(self.gpt2_model.model.left_context, "<|endoftext|>") + self.assertEqual(self.gpt2_model.model.device, "cpu") def test_opt_init(self): """Test default parameters for Facebook OPT model""" - self.assertEqual(self.opt_model.response_type, ResponseType.SYMBOL) - self.assertEqual(self.opt_model.symbol_set, alphabet()) - self.assertTrue( - ResponseType.SYMBOL in self.opt_model.supported_response_types()) - self.assertEqual(self.opt_model.left_context, "") - self.assertEqual(self.opt_model.device, "cpu") - - def test_name(self): - """Test model name.""" - self.assertEqual("CAUSAL", CausalLanguageModel.name()) + self.assertEqual(self.opt_model.symbol_set, DEFAULT_SYMBOL_SET) + self.assertTrue(isinstance(self.opt_model, CharacterLanguageModel)) + self.assertEqual(self.opt_model.model.left_context, "") + self.assertEqual(self.opt_model.model.device, "cpu") - def test_unsupported_response_type(self): + def test_invalid_symbol_set(self): """Unsupported responses should raise an exception""" - with self.assertRaises(UnsupportedResponseType): - CausalLanguageModel(response_type=ResponseType.WORD, - symbol_set=alphabet(), lang_model_name="gpt2") + with self.assertRaises(InvalidSymbolSetException): + lm = CausalLanguageModelAdapter(lang_model_name="gpt2") + lm.predict_character("this_should_fail") def test_invalid_model_name(self): """Test that the proper exception is thrown if given an invalid lang_model_name""" with self.assertRaises(InvalidLanguageModelException): - CausalLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lang_model_name="phonymodel") + lm = CausalLanguageModelAdapter(lang_model_name="phonymodel") + lm.set_symbol_set(DEFAULT_SYMBOL_SET) def test_invalid_model_path(self): """Test that the proper exception is thrown if given an invalid lm_path""" with self.assertRaises(InvalidLanguageModelException): - CausalLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lang_model_name="gpt2", lm_path="./phonypath/") + lm = CausalLanguageModelAdapter( + lang_model_name="gpt2", lm_path="./phonypath/") + lm.set_symbol_set(DEFAULT_SYMBOL_SET) def test_non_mutable_evidence(self): """Test that the model does not change the evidence variable passed in. This could impact the mixture model if failed""" evidence = list("Test_test") evidence2 = list("Test_test") - self.gpt2_model.predict(evidence) + self.gpt2_model.predict_character(evidence) self.assertEqual(evidence, evidence2) - self.opt_model.predict(evidence) + self.opt_model.predict_character(evidence) self.assertEqual(evidence, evidence2) def test_gpt2_identical(self): """Ensure predictions are the same for subsequent queries with the same evidence.""" - query1 = self.gpt2_model.predict(list("evidenc")) - query2 = self.gpt2_model.predict(list("evidenc")) + query1 = self.gpt2_model.predict_character(list("evidenc")) + query2 = self.gpt2_model.predict_character(list("evidenc")) for ((sym1, prob1), (sym2, prob2)) in zip(query1, query2): self.assertAlmostEqual(prob1, prob2, places=5) self.assertEqual(sym1, sym2) def test_opt_identical(self): """Ensure predictions are the same for subsequent queries with the same evidence.""" - query1 = self.opt_model.predict(list("evidenc")) - query2 = self.opt_model.predict(list("evidenc")) + query1 = self.opt_model.predict_character(list("evidenc")) + query2 = self.opt_model.predict_character(list("evidenc")) for ((sym1, prob1), (sym2, prob2)) in zip(query1, query2): self.assertAlmostEqual(prob1, prob2, places=5) self.assertEqual(sym1, sym2) def test_gpt2_upper_lower_case(self): """Ensure predictions are the same for upper or lower case evidence.""" - lc = self.gpt2_model.predict(list("EVIDENC")) - uc = self.gpt2_model.predict(list("evidenc")) + lc = self.gpt2_model.predict_character(list("EVIDENC")) + uc = self.gpt2_model.predict_character(list("evidenc")) for ((l_sym, l_prob), (u_sym, u_prob)) in zip(lc, uc): self.assertAlmostEqual(l_prob, u_prob, places=5) self.assertEqual(l_sym, u_sym) def test_opt_upper_lower_case(self): """Ensure predictions are the same for upper or lower case evidence.""" - lc = self.opt_model.predict(list("EVIDENC")) - uc = self.opt_model.predict(list("evidenc")) + lc = self.opt_model.predict_character(list("EVIDENC")) + uc = self.opt_model.predict_character(list("evidenc")) for ((l_sym, l_prob), (u_sym, u_prob)) in zip(lc, uc): self.assertAlmostEqual(l_prob, u_prob, places=5) self.assertEqual(l_sym, u_sym) def test_gpt2_predict_start_of_word(self): """Test the gpt2 predict method with no prior evidence.""" - symbol_probs = self.gpt2_model.predict(evidence=[]) + symbol_probs = self.gpt2_model.predict_character(evidence=[]) probs = [prob for sym, prob in symbol_probs] self.assertTrue( @@ -126,7 +124,7 @@ def test_gpt2_predict_start_of_word(self): def test_opt_predict_start_of_word(self): """Test the Facebook opt predict method with no prior evidence.""" - symbol_probs = self.opt_model.predict(evidence=[]) + symbol_probs = self.opt_model.predict_character(evidence=[]) probs = [prob for sym, prob in symbol_probs] self.assertTrue( @@ -141,7 +139,7 @@ def test_opt_predict_start_of_word(self): def test_gpt2_predict_middle_of_word(self): """Test the predict method in the middle of a word with gpt2 model.""" - symbol_probs = self.gpt2_model.predict(evidence=list("TH")) + symbol_probs = self.gpt2_model.predict_character(evidence=list("TH")) probs = [prob for sym, prob in symbol_probs] self.assertTrue( @@ -159,7 +157,7 @@ def test_gpt2_predict_middle_of_word(self): def test_opt_predict_middle_of_word(self): """Test the predict method in the middle of a word with Facebook opt model.""" - symbol_probs = self.opt_model.predict(evidence=list("TH")) + symbol_probs = self.opt_model.predict_character(evidence=list("TH")) probs = [prob for sym, prob in symbol_probs] self.assertTrue( @@ -177,7 +175,8 @@ def test_opt_predict_middle_of_word(self): def test_gpt2_phrase(self): """Test that a phrase can be used for input with gpt2 model""" - symbol_probs = self.gpt2_model.predict(list("does_it_make_sen")) + symbol_probs = self.gpt2_model.predict_character( + list("does_it_make_sen")) most_likely_sym, _prob = sorted(symbol_probs, key=itemgetter(1), reverse=True)[0] @@ -185,7 +184,8 @@ def test_gpt2_phrase(self): def test_opt_phrase(self): """Test that a phrase can be used for input with Facebook opt model""" - symbol_probs = self.opt_model.predict(list("does_it_make_sen")) + symbol_probs = self.opt_model.predict_character( + list("does_it_make_sen")) most_likely_sym, _prob = sorted(symbol_probs, key=itemgetter(1), reverse=True)[0] @@ -193,30 +193,34 @@ def test_opt_phrase(self): def test_gpt2_multiple_spaces(self): """Test that the probability of space after a space is smaller than before the space""" - symbol_probs_before = self.gpt2_model.predict(list("the")) - symbol_probs_after = self.gpt2_model.predict(list("the_")) + symbol_probs_before = self.gpt2_model.predict_character(list("the")) + symbol_probs_after = self.gpt2_model.predict_character(list("the_")) space_prob_before = (dict(symbol_probs_before))[SPACE_CHAR] space_prob_after = (dict(symbol_probs_after))[SPACE_CHAR] self.assertTrue(space_prob_before > space_prob_after) def test_opt_multiple_spaces(self): """Test that the probability of space after a space is smaller than before the space""" - symbol_probs_before = self.opt_model.predict(list("the")) - symbol_probs_after = self.opt_model.predict(list("the_")) + symbol_probs_before = self.opt_model.predict_character(list("the")) + symbol_probs_after = self.opt_model.predict_character(list("the_")) space_prob_before = (dict(symbol_probs_before))[SPACE_CHAR] space_prob_after = (dict(symbol_probs_after))[SPACE_CHAR] self.assertTrue(space_prob_before > space_prob_after) def test_gpt2_nonzero_prob(self): """Test that all letters in the alphabet have nonzero probability except for backspace""" - symbol_probs = self.gpt2_model.predict(list("does_it_make_sens")) - prob_values = [item[1] for item in symbol_probs if item[0] != BACKSPACE_CHAR] + symbol_probs = self.gpt2_model.predict_character( + list("does_it_make_sens")) + prob_values = [item[1] + for item in symbol_probs if item[0] != BACKSPACE_CHAR] for value in prob_values: self.assertTrue(value > 0) def test_opt_nonzero_prob(self): """Test that all letters in the alphabet have nonzero probability except for backspace""" - symbol_probs = self.opt_model.predict(list("does_it_make_sens")) - prob_values = [item[1] for item in symbol_probs if item[0] != BACKSPACE_CHAR] + symbol_probs = self.opt_model.predict_character( + list("does_it_make_sens")) + prob_values = [item[1] + for item in symbol_probs if item[0] != BACKSPACE_CHAR] for value in prob_values: self.assertTrue(value > 0) diff --git a/bcipy/language/tests/test_mixture.py b/bcipy/language/tests/test_mixture.py index 53c160212..4fe0ecc7c 100644 --- a/bcipy/language/tests/test_mixture.py +++ b/bcipy/language/tests/test_mixture.py @@ -1,108 +1,111 @@ """Tests for MIXTURE Language Model""" -import pytest -import unittest import os +import unittest from operator import itemgetter -from bcipy.exceptions import UnsupportedResponseType, InvalidLanguageModelException -from bcipy.helpers.symbols import alphabet, BACKSPACE_CHAR, SPACE_CHAR -from bcipy.language.model.mixture import MixtureLanguageModel -from bcipy.language.main import ResponseType +import pytest +from textslinger.exceptions import InvalidLanguageModelException + +from bcipy.core.symbols import BACKSPACE_CHAR, DEFAULT_SYMBOL_SET, SPACE_CHAR +from bcipy.exceptions import InvalidSymbolSetException +from bcipy.language.main import CharacterLanguageModel +from bcipy.language.model.mixture import MixtureLanguageModelAdapter @pytest.mark.slow -class TestMixtureLanguageModel(unittest.TestCase): +class TestMixtureLanguageModelAdapter(unittest.TestCase): """Tests for language model""" @classmethod def setUpClass(cls): dirname = os.path.dirname(__file__) or '.' - cls.kenlm_path = f"{dirname}/resources/lm_dec19_char_tiny_12gram.kenlm" - cls.lm_params = [{"lm_path": cls.kenlm_path}, {"lang_model_name": "gpt2"}] - cls.lmodel = MixtureLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_types=["KENLM", "CAUSAL"], lm_weights=[0.5, 0.5], - lm_params=cls.lm_params) + cls.kenlm_path = "lm_dec19_char_tiny_12gram.kenlm" + print(cls.kenlm_path) + cls.lm_params = [{"lm_path": cls.kenlm_path}, + {"lang_model_name": "gpt2"}] + cls.lmodel = MixtureLanguageModelAdapter(lm_types=["NGRAM", "CAUSAL"], lm_weights=[0.5, 0.5], + lm_params=cls.lm_params) + cls.lmodel.set_symbol_set(DEFAULT_SYMBOL_SET) @pytest.mark.slow def test_default_load(self): """Test loading model with parameters from json This test requires a valid lm_params.json file and all referenced models""" - lm = MixtureLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet()) + lm = MixtureLanguageModelAdapter() + lm.set_symbol_set(DEFAULT_SYMBOL_SET) def test_init(self): """Test default parameters""" - self.assertEqual(self.lmodel.response_type, ResponseType.SYMBOL) - self.assertEqual(self.lmodel.symbol_set, alphabet()) - self.assertTrue( - ResponseType.SYMBOL in self.lmodel.supported_response_types()) + self.assertEqual(self.lmodel.symbol_set, DEFAULT_SYMBOL_SET) + self.assertTrue(isinstance(self.lmodel, CharacterLanguageModel)) - def test_name(self): - """Test model name.""" - self.assertEqual("MIXTURE", MixtureLanguageModel.name()) - - def test_unsupported_response_type(self): - """Unsupported responses should raise an exception""" - with self.assertRaises(UnsupportedResponseType): - MixtureLanguageModel(response_type=ResponseType.WORD, - symbol_set=alphabet()) + def test_invalid_symbol_set(self): + """Should raise an exception if predict is called without setting symbol set""" + with self.assertRaises(InvalidSymbolSetException): + lm = MixtureLanguageModelAdapter() + lm.predict_character("this_should_fail") def test_invalid_model_type(self): """Test that the proper exception is thrown if given an invalid lm_type""" with self.assertRaises(InvalidLanguageModelException): - MixtureLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_types=["PHONY", "CAUSAL"], lm_weights=[0.5, 0.5], - lm_params=[{}, {"lang_model_name": "gpt2"}]) + lm = MixtureLanguageModelAdapter(lm_types=["PHONY", "CAUSAL"], lm_weights=[0.5, 0.5], + lm_params=[{}, {"lang_model_name": "gpt2"}]) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + with self.assertRaises(InvalidLanguageModelException): - MixtureLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_types=["CAUSAL", "PHONY"], lm_weights=[0.5, 0.5], - lm_params=[{"lang_model_name": "gpt2"}, {}]) + lm = MixtureLanguageModelAdapter(lm_types=["CAUSAL", "PHONY"], lm_weights=[0.5, 0.5], + lm_params=[{"lang_model_name": "gpt2"}, {}]) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) def test_invalid_model_weights(self): """Test that the proper exception is thrown if given an improper number of lm_weights""" with self.assertRaises(InvalidLanguageModelException, msg="Exception not thrown when too few weights given"): - MixtureLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_types=["UNIGRAM", "CAUSAL"], lm_weights=[0.5], - lm_params=[{}, {"lang_model_name": "gpt2"}]) + lm = MixtureLanguageModelAdapter(lm_types=["NGRAM", "CAUSAL"], lm_weights=[0.5], + lm_params=[{"lm_path": self.kenlm_path}, {"lang_model_name": "gpt2"}]) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + with self.assertRaises(InvalidLanguageModelException, msg="Exception not thrown when no weights given"): - MixtureLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_types=["UNIGRAM", "CAUSAL"], lm_weights=None, - lm_params=[{}, {"lang_model_name": "gpt2"}]) + lm = MixtureLanguageModelAdapter(lm_types=["NGRAM", "CAUSAL"], lm_weights=None, + lm_params=[{"lm_path": self.kenlm_path}, {"lang_model_name": "gpt2"}]) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + with self.assertRaises(InvalidLanguageModelException, msg="Exception not thrown when too many weights given"): - MixtureLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_types=["UNIGRAM", "CAUSAL"], lm_weights=[0.2, 0.3, 0.5], - lm_params=[{}, {"lang_model_name": "gpt2"}]) + lm = MixtureLanguageModelAdapter(lm_types=["NGRAM", "CAUSAL"], lm_weights=[0.2, 0.3, 0.5], + lm_params=[{"lm_path": self.kenlm_path}, {"lang_model_name": "gpt2"}]) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + with self.assertRaises(InvalidLanguageModelException, msg="Exception not thrown when weights given do not \ sum to 1"): - MixtureLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_types=["UNIGRAM", "CAUSAL"], lm_weights=[0.5, 0.8], - lm_params=[{}, {"lang_model_name": "gpt2"}]) + lm = MixtureLanguageModelAdapter(lm_types=["NGRAM", "CAUSAL"], lm_weights=[0.5, 0.8], + lm_params=[{"lm_path": self.kenlm_path}, {"lang_model_name": "gpt2"}]) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) def test_non_mutable_evidence(self): """Test that the model does not change the evidence variable passed in.""" evidence = list("Test_test") evidence2 = list("Test_test") - self.lmodel.predict(evidence) + self.lmodel.predict_character(evidence) self.assertEqual(evidence, evidence2) def test_identical(self): """Ensure predictions are the same for subsequent queries with the same evidence.""" - query1 = self.lmodel.predict(list("evidenc")) - query2 = self.lmodel.predict(list("evidenc")) + query1 = self.lmodel.predict_character(list("evidenc")) + query2 = self.lmodel.predict_character(list("evidenc")) for ((sym1, prob1), (sym2, prob2)) in zip(query1, query2): self.assertAlmostEqual(prob1, prob2, places=5) self.assertEqual(sym1, sym2) def test_upper_lower_case(self): """Ensure predictions are the same for upper or lower case evidence.""" - lc = self.lmodel.predict(list("EVIDENC")) - uc = self.lmodel.predict(list("evidenc")) + lc = self.lmodel.predict_character(list("EVIDENC")) + uc = self.lmodel.predict_character(list("evidenc")) for ((l_sym, l_prob), (u_sym, u_prob)) in zip(lc, uc): self.assertAlmostEqual(l_prob, u_prob, places=5) self.assertEqual(l_sym, u_sym) def test_predict_start_of_word(self): """Test the predict method with no prior evidence.""" - symbol_probs = self.lmodel.predict(evidence=[]) + symbol_probs = self.lmodel.predict_character(evidence=[]) probs = [prob for sym, prob in symbol_probs] self.assertTrue( @@ -117,7 +120,7 @@ def test_predict_start_of_word(self): def test_predict_middle_of_word(self): """Test the predict method in the middle of a word.""" - symbol_probs = self.lmodel.predict(evidence=list("TH")) + symbol_probs = self.lmodel.predict_character(evidence=list("TH")) probs = [prob for sym, prob in symbol_probs] self.assertTrue( @@ -135,7 +138,7 @@ def test_predict_middle_of_word(self): def test_phrase(self): """Test that a phrase can be used for input""" - symbol_probs = self.lmodel.predict(list("does_it_make_sen")) + symbol_probs = self.lmodel.predict_character(list("does_it_make_sen")) most_likely_sym, _prob = sorted(symbol_probs, key=itemgetter(1), reverse=True)[0] @@ -143,15 +146,16 @@ def test_phrase(self): def test_multiple_spaces(self): """Test that the probability of space after a space is smaller than before the space""" - symbol_probs_before = self.lmodel.predict(list("the")) - symbol_probs_after = self.lmodel.predict(list("the_n")) + symbol_probs_before = self.lmodel.predict_character(list("the")) + symbol_probs_after = self.lmodel.predict_character(list("the_n")) space_prob_before = (dict(symbol_probs_before))[SPACE_CHAR] space_prob_after = (dict(symbol_probs_after))[SPACE_CHAR] self.assertTrue(space_prob_before > space_prob_after) def test_nonzero_prob(self): """Test that all letters in the alphabet have nonzero probability except for backspace""" - symbol_probs = self.lmodel.predict(list("does_it_make_sens")) - prob_values = [item[1] for item in symbol_probs if item[0] != BACKSPACE_CHAR] + symbol_probs = self.lmodel.predict_character(list("does_it_make_sens")) + prob_values = [item[1] + for item in symbol_probs if item[0] != BACKSPACE_CHAR] for value in prob_values: self.assertTrue(value > 0) diff --git a/bcipy/language/tests/test_kenlm.py b/bcipy/language/tests/test_ngram.py similarity index 64% rename from bcipy/language/tests/test_kenlm.py rename to bcipy/language/tests/test_ngram.py index a0cc4805b..b55ac6050 100644 --- a/bcipy/language/tests/test_kenlm.py +++ b/bcipy/language/tests/test_ngram.py @@ -1,82 +1,80 @@ -"""Tests for KENLM Language Model""" +"""Tests for NGRAM Language Model""" -import pytest -import unittest import os +import unittest from operator import itemgetter -from bcipy.exceptions import UnsupportedResponseType, InvalidLanguageModelException -from bcipy.helpers.symbols import alphabet, BACKSPACE_CHAR, SPACE_CHAR -from bcipy.language.model.kenlm import KenLMLanguageModel -from bcipy.language.main import ResponseType +import pytest +from textslinger.exceptions import InvalidLanguageModelException + +from bcipy.core.symbols import BACKSPACE_CHAR, DEFAULT_SYMBOL_SET, SPACE_CHAR +from bcipy.exceptions import InvalidSymbolSetException +from bcipy.language.main import CharacterLanguageModel +from bcipy.language.model.ngram import NGramLanguageModelAdapter @pytest.mark.slow -class TestKenLMLanguageModel(unittest.TestCase): +class TestNGramLanguageModelAdapter(unittest.TestCase): """Tests for language model""" + @classmethod def setUpClass(cls): dirname = os.path.dirname(__file__) or '.' cls.lm_path = f"{dirname}/resources/lm_dec19_char_tiny_12gram.kenlm" - cls.lmodel = KenLMLanguageModel(response_type=ResponseType.SYMBOL, - symbol_set=alphabet(), lm_path=cls.lm_path) + cls.lmodel = NGramLanguageModelAdapter(lm_path=cls.lm_path) + cls.lmodel.set_symbol_set(DEFAULT_SYMBOL_SET) @pytest.mark.slow def test_default_load(self): """Test loading model with parameters from json This test requires a valid lm_params.json file and all requisite models""" - lm = KenLMLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet()) + lm = NGramLanguageModelAdapter() + lm.set_symbol_set(DEFAULT_SYMBOL_SET) def test_init(self): """Test default parameters""" - self.assertEqual(self.lmodel.response_type, ResponseType.SYMBOL) - self.assertEqual(self.lmodel.symbol_set, alphabet()) - self.assertTrue( - ResponseType.SYMBOL in self.lmodel.supported_response_types()) - - def test_name(self): - """Test model name.""" - self.assertEqual("KENLM", KenLMLanguageModel.name()) + self.assertEqual(self.lmodel.symbol_set, DEFAULT_SYMBOL_SET) + self.assertTrue(isinstance(self.lmodel, CharacterLanguageModel)) - def test_unsupported_response_type(self): - """Unsupported responses should raise an exception""" - with self.assertRaises(UnsupportedResponseType): - KenLMLanguageModel(response_type=ResponseType.WORD, - symbol_set=alphabet(), lm_path=self.lm_path) + def test_invalid_symbol_set(self): + """Should raise an exception if predict is called without settting symbol set""" + with self.assertRaises(InvalidSymbolSetException): + lm = NGramLanguageModelAdapter(lm_path=self.lm_path) + lm.predict_character("this_should_fail") def test_invalid_model_path(self): """Test that the proper exception is thrown if given an invalid lm_path""" with self.assertRaises(InvalidLanguageModelException): - KenLMLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_path="phonymodel.txt") + lm = NGramLanguageModelAdapter(lm_path="phonymodel.txt") + lm.set_symbol_set(DEFAULT_SYMBOL_SET) def test_non_mutable_evidence(self): """Test that the model does not change the evidence variable passed in. This could impact the mixture model if failed""" evidence = list("Test_test") evidence2 = list("Test_test") - self.lmodel.predict(evidence) + self.lmodel.predict_character(evidence) self.assertEqual(evidence, evidence2) def test_identical(self): """Ensure predictions are the same for subsequent queries with the same evidence.""" - query1 = self.lmodel.predict(list("evidenc")) - query2 = self.lmodel.predict(list("evidenc")) + query1 = self.lmodel.predict_character(list("evidenc")) + query2 = self.lmodel.predict_character(list("evidenc")) for ((sym1, prob1), (sym2, prob2)) in zip(query1, query2): self.assertAlmostEqual(prob1, prob2, places=5) self.assertEqual(sym1, sym2) def test_upper_lower_case(self): """Ensure predictions are the same for upper or lower case evidence.""" - lc = self.lmodel.predict(list("EVIDENC")) - uc = self.lmodel.predict(list("evidenc")) + lc = self.lmodel.predict_character(list("EVIDENC")) + uc = self.lmodel.predict_character(list("evidenc")) for ((l_sym, l_prob), (u_sym, u_prob)) in zip(lc, uc): self.assertAlmostEqual(l_prob, u_prob, places=5) self.assertEqual(l_sym, u_sym) def test_predict_start_of_word(self): """Test the predict method with no prior evidence.""" - symbol_probs = self.lmodel.predict(evidence=[]) + symbol_probs = self.lmodel.predict_character(evidence=[]) probs = [prob for sym, prob in symbol_probs] self.assertTrue( @@ -91,7 +89,7 @@ def test_predict_start_of_word(self): def test_predict_middle_of_word(self): """Test the predict method in the middle of a word.""" - symbol_probs = self.lmodel.predict(evidence=list("TH")) + symbol_probs = self.lmodel.predict_character(evidence=list("TH")) probs = [prob for sym, prob in symbol_probs] self.assertTrue( @@ -109,7 +107,7 @@ def test_predict_middle_of_word(self): def test_phrase(self): """Test that a phrase can be used for input""" - symbol_probs = self.lmodel.predict(list("does_it_make_sen")) + symbol_probs = self.lmodel.predict_character(list("does_it_make_sen")) most_likely_sym, _prob = sorted(symbol_probs, key=itemgetter(1), reverse=True)[0] @@ -117,16 +115,18 @@ def test_phrase(self): def test_multiple_spaces(self): """Test that the probability of space after a space is smaller than before the space""" - symbol_probs_before = self.lmodel.predict(list("the")) - symbol_probs_after = self.lmodel.predict(list("the_")) + symbol_probs_before = self.lmodel.predict_character(list("the")) + symbol_probs_after = self.lmodel.predict_character(list("the_")) space_prob_before = (dict(symbol_probs_before))[SPACE_CHAR] space_prob_after = (dict(symbol_probs_after))[SPACE_CHAR] self.assertTrue(space_prob_before > space_prob_after) def test_nonzero_prob(self): """Test that all letters in the alphabet have nonzero probability except for backspace""" - symbol_probs = self.lmodel.predict(list("does_it_make_sens")) - prob_values = [item[1] for item in symbol_probs if item[0] != BACKSPACE_CHAR] + symbol_probs = self.lmodel.predict_character(list("does_it_make_sens")) + prob_values = [ + item[1] for item in symbol_probs if item[0] != BACKSPACE_CHAR + ] for value in prob_values: self.assertTrue(value > 0) diff --git a/bcipy/language/tests/test_oracle.py b/bcipy/language/tests/test_oracle.py index 69a2f7a2b..c5cb5489d 100644 --- a/bcipy/language/tests/test_oracle.py +++ b/bcipy/language/tests/test_oracle.py @@ -2,8 +2,10 @@ import unittest -from bcipy.language.model.oracle import (BACKSPACE_CHAR, OracleLanguageModel, - ResponseType) +from bcipy.core.symbols import BACKSPACE_CHAR, DEFAULT_SYMBOL_SET +from bcipy.exceptions import InvalidSymbolSetException +from bcipy.language.main import CharacterLanguageModel +from bcipy.language.model.oracle import OracleLanguageModel class TestOracleLanguageModel(unittest.TestCase): @@ -17,15 +19,25 @@ def test_init(self): def test_init_with_text(self): """Test with task_text provided""" lmodel = OracleLanguageModel(task_text="HELLO_WORLD") - self.assertEqual(lmodel.response_type, ResponseType.SYMBOL) + lmodel.set_symbol_set(DEFAULT_SYMBOL_SET) self.assertEqual( len(lmodel.symbol_set), 28, "Should be the alphabet plus the backspace and space chars") + self.assertTrue(isinstance(lmodel, CharacterLanguageModel)) + + def test_invalid_symbol_set(self): + """Should raise an exception if predict is called before settting the symbol set""" + lm = OracleLanguageModel(task_text="HELLO_WORLD") + lm.set_symbol_set([]) + with self.assertRaises(InvalidSymbolSetException): + lm.predict_character("this_should_fail") + def test_predict(self): """Test the predict method""" lm = OracleLanguageModel(task_text="HELLO_WORLD") - symbol_probs = lm.predict(evidence=[]) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + symbol_probs = lm.predict_character(evidence=[]) probs = [prob for sym, prob in symbol_probs] self.assertEqual(len(set(probs)), 2, @@ -38,12 +50,13 @@ def test_predict(self): "Target should have a higher value") self.assertAlmostEqual(lm.target_bump, probs_dict['H'] - probs_dict['A'], - places=1) + places=4) def test_predict_with_spelled_text(self): """Test predictions with previously spelled symbols""" lm = OracleLanguageModel(task_text="HELLO_WORLD") - symbol_probs = lm.predict(evidence=list("HELLO_")) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + symbol_probs = lm.predict_character(evidence=list("HELLO_")) probs = [prob for sym, prob in symbol_probs] self.assertEqual(len(set(probs)), 2, @@ -55,7 +68,8 @@ def test_predict_with_spelled_text(self): def test_predict_with_incorrectly_spelled_text(self): """Test predictions with incorrectly spelled prior.""" lm = OracleLanguageModel(task_text="HELLO_WORLD") - symbol_probs = lm.predict(evidence=list("HELP")) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + symbol_probs = lm.predict_character(evidence=list("HELP")) probs = [prob for sym, prob in symbol_probs] self.assertEqual(len(set(probs)), 2) @@ -66,29 +80,32 @@ def test_predict_with_incorrectly_spelled_text(self): def test_target_bump_parameter(self): """Test setting the target_bump parameter.""" lm = OracleLanguageModel(task_text="HELLO_WORLD", target_bump=0.2) - symbol_probs = lm.predict(evidence=[]) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + symbol_probs = lm.predict_character(evidence=[]) probs_dict = dict(symbol_probs) self.assertTrue(probs_dict['H'] > probs_dict['A'], "Target should have a higher value") self.assertAlmostEqual(0.2, probs_dict['H'] - probs_dict['A'], - places=1) + places=4) def test_setting_task_text_to_none(self): """Test that task_text is required""" lmodel = OracleLanguageModel(task_text="HELLO_WORLD") + lmodel.set_symbol_set(DEFAULT_SYMBOL_SET) with self.assertRaises(AssertionError): lmodel.task_text = None def test_updating_task_text(self): """Test updating the task_text property.""" lm = OracleLanguageModel(task_text="HELLO_WORLD", target_bump=0.2) - probs = dict(lm.predict(evidence=list("HELLO_"))) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) + probs = dict(lm.predict_character(evidence=list("HELLO_"))) self.assertTrue(probs['W'] > probs['T'], "Target should have a higher value") lm.task_text = "HELLO_THERE" - probs = dict(lm.predict(evidence=list("HELLO_"))) + probs = dict(lm.predict_character(evidence=list("HELLO_"))) self.assertTrue(probs['T'] > probs['W'], "Target should have a higher value") @@ -101,6 +118,7 @@ def test_target_bump_bounds(self): OracleLanguageModel(task_text="HI", target_bump=1.1) lm = OracleLanguageModel(task_text="HI", target_bump=0.0) + lm.set_symbol_set(DEFAULT_SYMBOL_SET) with self.assertRaises(AssertionError): lm.target_bump = -1.0 @@ -110,22 +128,23 @@ def test_target_bump_bounds(self): def test_evidence_exceeds_task(self): """Test probs when evidence exceeds task_text.""" lm = OracleLanguageModel(task_text="HELLO") + lm.set_symbol_set(DEFAULT_SYMBOL_SET) - probs = dict(lm.predict(evidence="HELL")) + probs = dict(lm.predict_character(evidence="HELL")) self.assertEqual(2, len(set(probs.values()))) self.assertEqual(max(probs.values()), probs['O']) - probs = dict(lm.predict(evidence="HELLO")) + probs = dict(lm.predict_character(evidence="HELLO")) self.assertEqual(1, len(set(probs.values()))) - probs = dict(lm.predict(evidence="HELLP")) + probs = dict(lm.predict_character(evidence="HELLP")) self.assertEqual(2, len(set(probs.values()))) self.assertEqual(max(probs.values()), probs[BACKSPACE_CHAR]) - probs = dict(lm.predict(evidence="HELLO_")) + probs = dict(lm.predict_character(evidence="HELLO_")) self.assertEqual(1, len(set(probs.values()))) - probs = dict(lm.predict(evidence="HELPED")) + probs = dict(lm.predict_character(evidence="HELPED")) self.assertEqual(2, len(set(probs.values()))) self.assertEqual(max(probs.values()), probs[BACKSPACE_CHAR]) diff --git a/bcipy/language/tests/test_uniform.py b/bcipy/language/tests/test_uniform.py index 8e8a4034a..7b4b6dca9 100644 --- a/bcipy/language/tests/test_uniform.py +++ b/bcipy/language/tests/test_uniform.py @@ -2,25 +2,42 @@ import unittest -from bcipy.language.model.uniform import (ResponseType, UniformLanguageModel, - equally_probable) +from bcipy.core.symbols import BACKSPACE_CHAR, DEFAULT_SYMBOL_SET +from bcipy.exceptions import InvalidSymbolSetException +from bcipy.language.main import CharacterLanguageModel +from bcipy.language.model.uniform import UniformLanguageModel, equally_probable class TestUniformLanguageModel(unittest.TestCase): """Tests for language model""" + @classmethod + def setUpClass(cls): + cls.lm = UniformLanguageModel() + cls.lm.set_symbol_set(DEFAULT_SYMBOL_SET) + def test_init(self): """Test default parameters""" lmodel = UniformLanguageModel() - self.assertEqual(lmodel.response_type, ResponseType.SYMBOL) + lmodel.set_symbol_set(DEFAULT_SYMBOL_SET) self.assertEqual( len(lmodel.symbol_set), 28, "Should be the alphabet plus the backspace and space chars") + self.assertTrue(isinstance(lmodel, CharacterLanguageModel)) + + def test_invalid_symbol_set(self): + """Should raise an exception if predict is called before setting a symbol set""" + lm = UniformLanguageModel() + lm.set_symbol_set([]) + with self.assertRaises(InvalidSymbolSetException): + lm.predict_character("this_should_fail") def test_predict(self): """Test the predict method""" - symbol_probs = UniformLanguageModel().predict(evidence=[]) - probs = [prob for sym, prob in symbol_probs] + symbol_probs = self.lm.predict_character(evidence=[]) + + # Backspace can be 0 + probs = [prob for sym, prob in symbol_probs if sym != BACKSPACE_CHAR] self.assertEqual(len(set(probs)), 1, "All values should be the same") self.assertTrue(0 < probs[0] < 1) diff --git a/bcipy/language/tests/test_unigram.py b/bcipy/language/tests/test_unigram.py deleted file mode 100644 index 7a07b002e..000000000 --- a/bcipy/language/tests/test_unigram.py +++ /dev/null @@ -1,114 +0,0 @@ -"""Tests for UNIGRAM Language Model""" - -import pytest -import unittest -import os - -from bcipy.exceptions import UnsupportedResponseType, InvalidLanguageModelException -from bcipy.helpers.symbols import alphabet, BACKSPACE_CHAR -from bcipy.language.model.unigram import UnigramLanguageModel -from bcipy.language.main import ResponseType - - -@pytest.mark.slow -class TestUnigramLanguageModel(unittest.TestCase): - """Tests for language model""" - @classmethod - def setUpClass(cls): - cls.lmodel = UnigramLanguageModel(response_type=ResponseType.SYMBOL, - symbol_set=alphabet()) - - def test_init(self): - """Test default parameters""" - self.assertEqual(self.lmodel.response_type, ResponseType.SYMBOL) - self.assertEqual(self.lmodel.symbol_set, alphabet()) - self.assertTrue( - ResponseType.SYMBOL in self.lmodel.supported_response_types()) - - def test_name(self): - """Test model name.""" - self.assertEqual("UNIGRAM", UnigramLanguageModel.name()) - - def test_unsupported_response_type(self): - """Unsupported responses should raise an exception""" - with self.assertRaises(UnsupportedResponseType): - UnigramLanguageModel(response_type=ResponseType.WORD, symbol_set=alphabet()) - - def test_invalid_model_path(self): - """Test that the proper exception is thrown if given an invalid lm_path""" - with self.assertRaises(InvalidLanguageModelException): - UnigramLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_path="phonymodel.txt") - - def test_invalid_model(self): - with self.assertRaises(InvalidLanguageModelException): - dirname = os.path.dirname(__file__) or '.' - lm_path = f"{dirname}/resources/invalid_unigram.json" - UnigramLanguageModel(response_type=ResponseType.SYMBOL, symbol_set=alphabet(), - lm_path=lm_path) - - def test_non_mutable_evidence(self): - """Test that the model does not change the evidence variable passed in. - This could impact the mixture model if failed""" - evidence = list("Test_test") - evidence2 = list("Test_test") - self.lmodel.predict(evidence) - self.assertEqual(evidence, evidence2) - - def test_identical_evidence(self): - """Ensure predictions are the same for subsequent queries with the same evidence.""" - query1 = self.lmodel.predict(list("evidenc")) - query2 = self.lmodel.predict(list("evidenc")) - for ((sym1, prob1), (sym2, prob2)) in zip(query1, query2): - self.assertAlmostEqual(prob1, prob2, places=5) - self.assertEqual(sym1, sym2) - - def test_identical_predictions(self): - """Ensure predictions are the same for subsequent queries with different evidence.""" - query1 = self.lmodel.predict(list("evi")) - query2 = self.lmodel.predict(list("evidenc")) - for ((sym1, prob1), (sym2, prob2)) in zip(query1, query2): - self.assertAlmostEqual(prob1, prob2, places=5) - self.assertEqual(sym1, sym2) - - def test_upper_lower_case(self): - """Ensure predictions are the same for upper or lower case evidence.""" - lc = self.lmodel.predict(list("EVIDENC")) - uc = self.lmodel.predict(list("evidenc")) - for ((l_sym, l_prob), (u_sym, u_prob)) in zip(lc, uc): - self.assertAlmostEqual(l_prob, u_prob, places=5) - self.assertEqual(l_sym, u_sym) - - def test_predict_start_of_word(self): - """Test the predict method with no prior evidence.""" - symbol_probs = self.lmodel.predict(evidence=[]) - probs = [prob for sym, prob in symbol_probs] - - self.assertTrue( - len(set(probs)) > 1, - "All values should not be the same probability") - # Consider whether the following assertion should be True - # backspace_prob = next(prob for sym, prob in probs if sym == BACKSPACE_CHAR) - # self.assertEqual(0, backspace_prob) - for prob in probs: - self.assertTrue(0 <= prob < 1) - self.assertAlmostEqual(sum(probs), 1, places=3) - - def test_predict_middle_of_word(self): - """Test the predict method in the middle of a word.""" - symbol_probs = self.lmodel.predict(evidence=list("TH")) - probs = [prob for sym, prob in symbol_probs] - - self.assertTrue( - len(set(probs)) > 1, - "All values should not be the same probability") - for prob in probs: - self.assertTrue(0 <= prob < 1) - self.assertAlmostEqual(sum(probs), 1, places=3) - - def test_nonzero_prob(self): - """Test that all letters in the alphabet have nonzero probability except for backspace""" - symbol_probs = self.lmodel.predict(list("does_it_make_sens")) - prob_values = [item[1] for item in symbol_probs if item[0] != BACKSPACE_CHAR] - for value in prob_values: - self.assertTrue(value > 0) diff --git a/bcipy/main.py b/bcipy/main.py index 8d7d47b97..310218495 100644 --- a/bcipy/main.py +++ b/bcipy/main.py @@ -1,3 +1,8 @@ +"""Main entry point for BciPy application. + +This module provides the main function to initialize and run a BCI task or experiment. +""" + import argparse import logging import multiprocessing @@ -5,8 +10,8 @@ from bcipy.config import CUSTOM_TASK_EXPERIMENT_ID, DEFAULT_PARAMETERS_PATH from bcipy.exceptions import BciPyCoreException -from bcipy.helpers.load import load_experiments, load_json_parameters from bcipy.helpers.validate import validate_bcipy_session, validate_experiment +from bcipy.io.load import load_experiments, load_json_parameters from bcipy.task import Task, TaskRegistry from bcipy.task.orchestrator import SessionOrchestrator from bcipy.task.orchestrator.protocol import parse_protocol @@ -22,32 +27,33 @@ def bci_main( visualize: bool = True, fake: bool = False, task: Optional[Type[Task]] = None) -> bool: - """BCI Main. + """Initialize and run a BCI task or experiment. - The BCI main function will initialize a save folder, construct needed information - and execute the task. This is the main connection between any UI and + The BCI main function initializes a save folder, constructs needed information + and executes the task. This is the main connection between any UI and running the app. - A Task or Experiment ID must be provided to run the task. If a task is provided, the experiment - ID will be ignored. - - It may also be invoked via tha command line. - Ex. `bcipy` this will default parameters, mode, user, and type. + Args: + parameter_location: Location of parameters file to use. + user: Name of the user. + experiment_id: Name of the experiment. If task is provided, this will be ignored. + alert: Whether to alert the user when the task is complete. + visualize: Whether to visualize data at the end of a task. + fake: Whether to use fake acquisition data during the session. If None, the + fake data will be determined by the parameters file. + task: Registered bcipy Task to execute. If None, the task will be determined by the + experiment protocol. - You can pass it those attributes with flags, if desired. - Ex. `bcipy --user "bci_user" --task "RSVP Calibration" + Returns: + bool: True if the task executed successfully, False otherwise. + Raises: + BciPyCoreException: If no experiment or task is provided. - Input: - parameter_location (str): location of parameters file to use - user (str): name of the user - experiment_id (str): Name of the experiment. If task is provided, this will be ignored. - alert (bool): whether to alert the user when the task is complete - visualize (bool): whether to visualize data at the end of a task - fake (bool): whether to use fake acquisition data during the session. If None, the - fake data will be determined by the parameters file. - task (Task): registered bcipy Task to execute. If None, the task will be determined by the - experiment protocol. + Examples: + Command line usage: + `bcipy` - uses default parameters, mode, user, and type + `bcipy --user "bci_user" --task "RSVP Calibration"` """ logger.info('Starting BciPy...') logger.info( @@ -104,11 +110,21 @@ def bci_main( return True -def bcipy_main() -> None: # pragma: no cover - """BciPy Main. +def bcipy_main() -> None: + """Command line interface for running BciPy experiments and tasks. + + This function provides a command line interface for running registered experiment + tasks in BciPy. It handles argument parsing and delegates execution to bci_main. + + Args: + None + + Returns: + None - Command line interface used for running a registered experiment task in BciPy. To see what - is available use the --help flag. + Note: + Use the --help flag to see available options. + Windows machines require multiprocessing support which is initialized here. """ # Needed for windows machines multiprocessing.freeze_support() diff --git a/bcipy/parameters/devices.json b/bcipy/parameters/devices.json index 63aca8295..9da3281e0 100644 --- a/bcipy/parameters/devices.json +++ b/bcipy/parameters/devices.json @@ -57,6 +57,25 @@ "status": "active", "static_offset": 0.1 }, + { + "name": "DSI-7", + "content_type": "EEG", + "channels": [ + { "name": "Pz", "label": "Pz", "units": "microvolts", "type": "EEG" }, + { "name": "F4", "label": "F4", "units": "microvolts", "type": "EEG" }, + { "name": "C4", "label": "C4", "units": "microvolts", "type": "EEG" }, + { "name": "P4", "label": "P4", "units": "microvolts", "type": "EEG" }, + { "name": "P3", "label": "P3", "units": "microvolts", "type": "EEG" }, + { "name": "C3", "label": "C3", "units": "microvolts", "type": "EEG" }, + { "name": "F3", "label": "F3", "units": "microvolts", "type": "EEG" }, + { "name": "TRG", "label": "TRG", "units": "microvolts", "type": "EEG" } + ], + "sample_rate": 300, + "description": "Wearable Sensing DSI-7", + "excluded_from_analysis": ["TRG"], + "status": "active", + "static_offset": 0.1 + }, { "name": "DSI-Flex", "content_type": "EEG", @@ -120,5 +139,17 @@ "excluded_from_analysis": ["device_ts", "system_ts", "left_pupil", "right_pupil"], "status": "active", "static_offset": 0.0 + }, + { + "name": "Switch", + "content_type": "MARKERS", + "channels": [ + { "name": "Marker", "label": "Marker" } + ], + "sample_rate": 0.0, + "description": "Switch used for button press inputs", + "excluded_from_analysis": [], + "status": "active", + "static_offset": 0.0 } ] \ No newline at end of file diff --git a/bcipy/parameters/lm_params.json b/bcipy/parameters/lm_params.json index a9871fc23..ddd81c5a7 100644 --- a/bcipy/parameters/lm_params.json +++ b/bcipy/parameters/lm_params.json @@ -1,21 +1,31 @@ { - "kenlm": { + "ngram": { "model_file": { "description": "Name of the pretrained model file", - "value": "lm_dec19_char_tiny_12gram.kenlm", + "value": "lm_dec19_char_large_12gram.kenlm", "type": "filepath" } }, "causal": { "model_name": { "description": "Name of the HuggingFace model to load. Required for the Causal model.", - "value": "facebook/opt-125m", + "value": "figmtu/opt-350m-aac", "type": "str" }, "model_path": { "description": "Pretrained model path, relative to causal.py directory. Blank if using HuggingFace model", "value": "", "type": "directorypath" + }, + "beam_width": { + "description": "Name of the HuggingFace model to load. Required for the Causal model.", + "value": "8", + "type": "int" + }, + "max_completed": { + "description": "stop search once we reach this many completed hypotheses, None=don't prune", + "value": "32000", + "type": "int" } }, "mixture": { @@ -23,7 +33,7 @@ "description": "Defines the types of models to be used by the mixture model.", "value": [ "CAUSAL", - "KENLM" + "NGRAM" ], "type": "List[str]" }, @@ -38,8 +48,8 @@ "model_params": { "description": "Defines the extra parameters of models to be used by the mixture model.", "value": [ - {}, - {} + {"lang_model_name": "figmtu/opt-350m-aac"}, + {"lm_path": "lm_dec19_char_large_12gram.kenlm"} ], "type": "List[Dict[str, str]]" } diff --git a/bcipy/parameters/parameters.json b/bcipy/parameters/parameters.json index 74a8b5697..790225272 100755 --- a/bcipy/parameters/parameters.json +++ b/bcipy/parameters/parameters.json @@ -568,7 +568,7 @@ "type": "str" }, "copy_phrases_location": { - "value": "bcipy/parameters/experiment/phrases.json", + "value": "", "section": "online_config", "name": "Copy Phrases Location", "helpTip": "Specifies a list of copy phrases to execute during Task Orchestration. If provided, any copy phrases in the protocol will be executed in order pulling task text and starting locations from the file.", @@ -790,10 +790,10 @@ "type": "str" }, "lm_backspace_prob": { - "value": "0.0", + "value": "0.035", "section": "lang_model_config", "name": "Backspace Probability", - "helpTip": "Specifies the minimum probability assigned to the backspace character in the language model. Possible value range: 0.0-1.0. Default: 0.0", + "helpTip": "Specifies the minimum probability assigned to the backspace character in the language model. Possible value range: 0.0-1.0. Default: 0.035", "recommended": "0.05", "editable": false, "type": "float" diff --git a/bcipy/preferences.py b/bcipy/preferences.py index 15963e3fb..cb80c8840 100644 --- a/bcipy/preferences.py +++ b/bcipy/preferences.py @@ -1,82 +1,126 @@ -"""Module for recording and loading application state and user preferences.""" +"""Module for recording and loading application state and user preferences. + +This module provides functionality for storing and retrieving user preferences +and application state between sessions using a JSON-based storage system. +""" import json from pathlib import Path -from typing import Optional, Any, Dict -from bcipy.config import DEFAULT_ENCODING, PREFERENCES_PATH, BCIPY_ROOT +from typing import Any, Dict, Optional, Type + +from bcipy.config import BCIPY_ROOT, DEFAULT_ENCODING, PREFERENCES_PATH class Pref: - """Preference descriptor. When a class attribute is initialized as a Pref, - values will be stored and retrieved from an 'entries' dict initialized in - the instance. + """A descriptor class for managing preferences. + + When a class attribute is initialized as a Pref, values will be stored and + retrieved from an 'entries' dict initialized in the instance. + For more information on descriptors, see: https://docs.python.org/3/howto/descriptor.html - Parameters - ---------- - default - default value assigned to the attribute. + Args: + default: Default value assigned to the attribute if not found in entries. """ - def __init__(self, default: Optional[Any] = None): + def __init__(self, default: Optional[Any] = None) -> None: self.default = default - self.name = None + self.name: Optional[str] = None - def __set_name__(self, owner, name): - """Called when the class assigns a Pref to a class attribute.""" + def __set_name__(self, owner: Type[Any], name: str) -> None: + """Assign the Pref descriptor to a class attribute. + + Args: + owner: The class that owns this descriptor. + name: The name of the attribute this descriptor is assigned to. + """ self.name = name - def __get__(self, instance, owner=None): - """Retrieve the value from the dict of entries.""" + def __get__(self, instance: Any, owner: Optional[Type[Any]] = None) -> Any: + """Return the value from the dict of entries. + + Args: + instance: The instance that this descriptor is accessed from. + owner: The class that owns this descriptor. + + Returns: + The value stored in entries or the default value. + """ + if instance is None: + return self return instance.entries.get(self.name, self.default) - def __set__(self, instance, value): - """Stores the given value in the entries dict keyed on the attribute - name.""" + def __set__(self, instance: Any, value: Any) -> None: + """Store the given value in the entries dict keyed on the attribute name. + + Args: + instance: The instance that this descriptor is accessed from. + value: The value to store in the entries dict. + """ instance.entries[self.name] = value instance.save() class Preferences: - """User preferences persisted to disk to retain application state between - work sessions. + """User preferences persisted to disk to retain application state between work sessions. - Parameters - ---------- - filename - optional file used for persisting entries. + This class manages user preferences by storing them in a JSON file on disk. It provides + methods for loading, saving, and accessing preference values. + + Attributes: + signal_model_directory: Directory containing signal models. + last_directory: Last accessed directory, defaults to BCIPY_ROOT. + + Args: + filename: Optional file used for persisting entries. """ signal_model_directory = Pref() last_directory = Pref(default=str(BCIPY_ROOT)) def __init__(self, filename: str = PREFERENCES_PATH) -> None: self.filename = filename - self.entries: Dict[Any, Any] = {} + self.entries: Dict[str, Any] = {} self.load() - def load(self): - """Load preference data from the persisted file.""" + def load(self) -> None: + """Load preference data from the persisted file. + + Reads the JSON file specified by self.filename and populates the entries + dictionary with the stored preferences. + """ if Path(self.filename).is_file(): with open(self.filename, 'r', encoding=DEFAULT_ENCODING) as json_file: for key, val in json.load(json_file).items(): self.entries[key] = val - def save(self): - """Write preferences to disk.""" + def save(self) -> None: + """Write preferences to disk. + + Saves the current entries dictionary to the JSON file specified by + self.filename. + """ with open(self.filename, 'w', encoding=DEFAULT_ENCODING) as json_file: json.dump(self.entries, json_file, ensure_ascii=False, indent=2) - def get(self, name: str): - """Get preference by name""" + def get(self, name: str) -> Optional[Any]: + """Get preference by name. + + Args: + name: Name of the preference to retrieve. + + Returns: + The preference value if found, None otherwise. + """ return self.entries.get(name, None) - def set(self, name: str, value: Any, persist: bool = True): + def set(self, name: str, value: Any, persist: bool = True) -> None: """Set a preference and save the result. - Parameters - ---------- - name - name of the preference - value - value associated with the given name - persist - flag indicating whether to immediately save the result. + Args: + name: Name of the preference. + value: Value associated with the given name. + persist: Flag indicating whether to immediately save the result. Default is True. """ self.entries[name] = value diff --git a/bcipy/signal/evaluate/artifact.py b/bcipy/signal/evaluate/artifact.py index f4bc7bde0..1d8f69a21 100644 --- a/bcipy/signal/evaluate/artifact.py +++ b/bcipy/signal/evaluate/artifact.py @@ -1,39 +1,31 @@ # mypy: disable-error-code="assignment,arg-type" +import logging import os from enum import Enum -from pathlib import Path -from typing import Union, List, Tuple, Optional from logging import getLogger -import logging +from pathlib import Path +from typing import List, Optional, Tuple, Union + +import mne +from mne import Annotations -from bcipy.config import ( - DEFAULT_PARAMETERS_FILENAME, - RAW_DATA_FILENAME, - TRIGGER_FILENAME, - DEFAULT_DEVICE_SPEC_FILENAME, - BCIPY_ROOT, - SESSION_LOG_FILENAME -) -from bcipy.helpers.acquisition import analysis_channels -from bcipy.helpers.load import ( - load_experimental_data, - load_json_parameters, - load_raw_data, -) -from bcipy.helpers.stimuli import mne_epochs -from bcipy.helpers.convert import convert_to_mne -from bcipy.helpers.raw_data import RawData -from bcipy.signal.process import get_default_transform -from bcipy.helpers.triggers import TriggerType, trigger_decoder import bcipy.acquisition.devices as devices from bcipy.acquisition.devices import DeviceSpec +from bcipy.config import (BCIPY_ROOT, DEFAULT_DEVICE_SPEC_FILENAME, + DEFAULT_PARAMETERS_FILENAME, RAW_DATA_FILENAME, + SESSION_LOG_FILENAME, TRIGGER_FILENAME) +from bcipy.core.raw_data import RawData +from bcipy.core.stimuli import mne_epochs +from bcipy.core.triggers import TriggerType, trigger_decoder +from bcipy.helpers.acquisition import analysis_channels +from bcipy.io.convert import convert_to_mne +from bcipy.io.load import (load_experimental_data, load_json_parameters, + load_raw_data) +from bcipy.signal.process import get_default_transform -import mne mne.set_log_level('WARNING') log = getLogger(SESSION_LOG_FILENAME) -from mne import Annotations - class DefaultArtifactParameters(Enum): """Default Artifact Parameters. @@ -189,7 +181,8 @@ def __init__( self.session_triggers = mne.Annotations( self.trigger_time, [self.trial_duration] * len(self.trigger_time), self.trigger_description) - assert len(device_spec.channel_specs) > 0, 'DeviceSpec used must have channels. None found.' + assert len( + device_spec.channel_specs) > 0, 'DeviceSpec used must have channels. None found.' self.units = device_spec.channel_specs[0].units log.info(f'Artifact detection using {self.units} units.') assert self.units in self.supported_units, \ @@ -202,7 +195,8 @@ def __init__( self.detect_eog = detect_eog self.semi_automatic = semi_automatic - log.info(f'Artifact detection with {self.detect_voltage=}, {self.detect_eog=}, {self.semi_automatic=}') + log.info( + f'Artifact detection with {self.detect_voltage=}, {self.detect_eog=}, {self.semi_automatic=}') self.save_path = save_path @@ -259,7 +253,8 @@ def label_artifacts( log.info(f'Bad channels detected: {bad_channels}') if voltage_annotations: - log.info(f'Voltage violation events found: {len(voltage_annotations)}') + log.info( + f'Voltage violation events found: {len(voltage_annotations)}') annotations += voltage_annotations self.voltage_annotations = voltage_annotations @@ -297,7 +292,8 @@ def save_artifacts(self, overwrite: bool = False) -> None: f'{self.save_path}/{DefaultArtifactParameters.ARTIFACT_LABELLED_FILENAME.value}', overwrite=overwrite) else: - log.info('Artifact cannot be saved, artifact analysis has been done yet.') + log.info( + 'Artifact cannot be saved, artifact analysis has been done yet.') def raw_data_to_mne(self, raw_data: RawData, volts: bool = False) -> mne.io.RawArray: """Convert the raw data to an MNE RawArray.""" @@ -352,8 +348,10 @@ def label_eog_events( log.info('No eye channels provided. Cannot detect EOG artifacts.') return None - log.info(f'Using blink threshold of {threshold} for channels {self.eye_channels}.') - eog_events = mne.preprocessing.find_eog_events(self.mne_data, ch_name=self.eye_channels, thresh=threshold) + log.info( + f'Using blink threshold of {threshold} for channels {self.eye_channels}.') + eog_events = mne.preprocessing.find_eog_events( + self.mne_data, ch_name=self.eye_channels, thresh=threshold) # eog_events = mne.preprocessing.ica_find_eog_events(raw) TODO compare to ICA if len(eog_events) > 0: @@ -361,7 +359,8 @@ def label_eog_events( onsets = eog_events[:, 0] / self.mne_data.info['sfreq'] - preblink durations = [postblink + preblink] * len(eog_events) descriptions = [label] * len(eog_events) - blink_annotations = mne.Annotations(onsets, durations, descriptions) + blink_annotations = mne.Annotations( + onsets, durations, descriptions) return blink_annotations, eog_events return None @@ -423,7 +422,8 @@ def label_voltage_events( bad_percent=self.percent_bad, peak=peak[0]) if len(peak_voltage_annotations) > 0: - log.info(f'Peak voltage events found: {len(peak_voltage_annotations)}') + log.info( + f'Peak voltage events found: {len(peak_voltage_annotations)}') onsets, durations, descriptions = self.concat_annotations( peak_voltage_annotations, pre_event, @@ -437,7 +437,8 @@ def label_voltage_events( flat_voltage_annotations, bad_channels2 = mne.preprocessing.annotate_amplitude( self.mne_data, min_duration=flat[1], bad_percent=self.percent_bad, flat=flat[0]) if len(flat_voltage_annotations) > 0: - log.info(f'Flat voltage events found: {len(flat_voltage_annotations)}') + log.info( + f'Flat voltage events found: {len(flat_voltage_annotations)}') onsets, durations, descriptions = self.concat_annotations( flat_voltage_annotations, pre_event, @@ -566,21 +567,24 @@ def write_mne_annotations( # if no path is provided, prompt for one using a GUI path = args.path if not path: - path = load_experimental_data() + path = load_experimental_data( + message='Select the directory with the sessions to analyze for artifacts', strict=True) positions = None for session in Path(path).iterdir(): # loop through the sessions, pausing after each one to allow for manual stopping if session.is_dir(): print(f'Processing {session}') - prompt = input('Hit enter to continue or type "skip" to skip processing: ') + prompt = input( + 'Hit enter to continue or type "skip" to skip processing: ') if prompt != 'skip': # load the parameters from the data directory parameters = load_json_parameters( f'{session}/{DEFAULT_PARAMETERS_FILENAME}', value_cast=True) # load the raw data from the data directory - raw_data = load_raw_data(str(Path(session, f'{RAW_DATA_FILENAME}.csv'))) + raw_data = load_raw_data( + str(Path(session, f'{RAW_DATA_FILENAME}.csv'))) type_amp = raw_data.daq_type # load the triggers @@ -588,7 +592,8 @@ def write_mne_annotations( trigger_type, trigger_timing, trigger_label = trigger_decoder( offset=0.1, trigger_path=f"{session}/{TRIGGER_FILENAME}", - exclusion=[TriggerType.PREVIEW, TriggerType.EVENT, TriggerType.FIXATION], + exclusion=[TriggerType.PREVIEW, + TriggerType.EVENT, TriggerType.FIXATION], ) triggers = (trigger_type, trigger_timing, trigger_label) else: diff --git a/bcipy/signal/evaluate/fusion.py b/bcipy/signal/evaluate/fusion.py index 6d91cddb5..ffeb71688 100644 --- a/bcipy/signal/evaluate/fusion.py +++ b/bcipy/signal/evaluate/fusion.py @@ -1,25 +1,24 @@ # mypy: disable-error-code="assignment,var-annotated" +import logging +from typing import List, Tuple + import numpy as np from sklearn.utils import resample -from typing import List, Tuple -import logging from tqdm import tqdm -from bcipy.config import (TRIGGER_FILENAME, SESSION_LOG_FILENAME) +from bcipy.acquisition.devices import DeviceSpec +from bcipy.config import SESSION_LOG_FILENAME, TRIGGER_FILENAME +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawData +from bcipy.core.stimuli import update_inquiry_timing +from bcipy.core.triggers import TriggerType, trigger_decoder from bcipy.helpers.acquisition import analysis_channels -from bcipy.helpers.raw_data import RawData -from bcipy.helpers.stimuli import update_inquiry_timing -from bcipy.helpers.triggers import TriggerType, trigger_decoder from bcipy.preferences import preferences -from bcipy.signal.model.base_model import SignalModelMetadata -from bcipy.signal.model.base_model import SignalModel +from bcipy.signal.model.base_model import SignalModel, SignalModelMetadata from bcipy.signal.model.gaussian_mixture import GaussianProcess from bcipy.signal.model.pca_rda_kde import PcaRdaKdeModel from bcipy.signal.process import (ERPTransformParams, extract_eye_info, filter_inquiries, get_default_transform) -from bcipy.acquisition.devices import DeviceSpec -from bcipy.helpers.parameters import Parameters - logger = logging.getLogger(SESSION_LOG_FILENAME) @@ -53,10 +52,12 @@ def calculate_eeg_gaze_fusion_acc( gaze_acc: accuracy of the gaze model only fusion_acc: accuracy of the fusion """ - logger.info(f"Calculating EEG [{eeg_model.name}] and Gaze [{gaze_model.name}] model fusion accuracy.") + logger.info( + f"Calculating EEG [{eeg_model.name}] and Gaze [{gaze_model.name}] model fusion accuracy.") # Extract relevant session information from parameters file trial_window = parameters.get("trial_window", (0.0, 0.5)) - window_length = trial_window[1] - trial_window[0] # eeg window length, in seconds + # eeg window length, in seconds + window_length = trial_window[1] - trial_window[0] prestim_length = parameters.get("prestim_length") trials_per_inquiry = parameters.get("stim_length") @@ -65,7 +66,8 @@ def calculate_eeg_gaze_fusion_acc( buffer = int(parameters.get("task_buffer_length") / 2) # Get signal filtering information - transform_params: ERPTransformParams = parameters.instantiate(ERPTransformParams) + transform_params: ERPTransformParams = parameters.instantiate( + ERPTransformParams) downsample_rate = transform_params.down_sampling_rate static_offset = device_spec_eeg.static_offset @@ -120,10 +122,12 @@ def calculate_eeg_gaze_fusion_acc( target_symbols = [trigger_symbols[idx] for idx, targetness in enumerate(trigger_targetness_gaze) if targetness == 'prompt'] total_len = trials_per_inquiry + 1 # inquiry length + the prompt symbol - inq_start = trigger_timing_gaze[1::total_len] # inquiry start times, exluding prompt and fixation + # inquiry start times, exluding prompt and fixation + inq_start = trigger_timing_gaze[1::total_len] # update the trigger timing list to account for the initial trial window - corrected_trigger_timing = [timing + trial_window[0] for timing in trigger_timing] + corrected_trigger_timing = [timing + trial_window[0] + for timing in trigger_timing] erp_data, _fs_eeg = eeg_data.by_channel() trajectory_data, _fs_eye = gaze_data.by_channel() @@ -154,18 +158,24 @@ def calculate_eeg_gaze_fusion_acc( ) # More EEG preprocessing: - eeg_inquiries, fs = filter_inquiries(eeg_inquiries, default_transform, eeg_sample_rate) - eeg_inquiry_timing = update_inquiry_timing(eeg_inquiry_timing, downsample_rate) + eeg_inquiries, fs = filter_inquiries( + eeg_inquiries, default_transform, eeg_sample_rate) + eeg_inquiry_timing = update_inquiry_timing( + eeg_inquiry_timing, downsample_rate) trial_duration_samples = int(window_length * fs) # More gaze preprocessing: - inquiry_length = gaze_inquiries_list[0].shape[1] # number of time samples in each inquiry + # number of time samples in each inquiry + inquiry_length = gaze_inquiries_list[0].shape[1] predefined_dimensions = 4 # left_x, left_y, right_x, right_y - preprocessed_gaze_data = np.zeros((len(gaze_inquiries_list), predefined_dimensions, inquiry_length)) + preprocessed_gaze_data = np.zeros( + (len(gaze_inquiries_list), predefined_dimensions, inquiry_length)) # Extract left_x, left_y, right_x, right_y for each inquiry for j in range(len(gaze_inquiries_list)): - left_eye, right_eye, _, _, _, _ = extract_eye_info(gaze_inquiries_list[j]) - preprocessed_gaze_data[j] = np.concatenate((left_eye.T, right_eye.T,), axis=0) + left_eye, right_eye, _, _, _, _ = extract_eye_info( + gaze_inquiries_list[j]) + preprocessed_gaze_data[j] = np.concatenate( + (left_eye.T, right_eye.T,), axis=0) preprocessed_gaze_dict = {i: [] for i in symbol_set} for i in symbol_set: @@ -173,8 +183,10 @@ def calculate_eeg_gaze_fusion_acc( if len(gaze_inquiries_dict[i]) == 0: continue for j in range(len(gaze_inquiries_dict[i])): - left_eye, right_eye, _, _, _, _ = extract_eye_info(gaze_inquiries_dict[i][j]) - preprocessed_gaze_dict[i].append((np.concatenate((left_eye.T, right_eye.T), axis=0))) + left_eye, right_eye, _, _, _, _ = extract_eye_info( + gaze_inquiries_dict[i][j]) + preprocessed_gaze_dict[i].append( + (np.concatenate((left_eye.T, right_eye.T), axis=0))) preprocessed_gaze_dict[i] = np.array(preprocessed_gaze_dict[i]) # Find the time averages for each symbol: @@ -196,12 +208,14 @@ def calculate_eeg_gaze_fusion_acc( preprocessed_gaze_dict[sym][j], temp)) # Delta_t = X_t - mu centralized_data_dict[sym] = np.array(centralized_data_dict[sym]) - time_average_per_symbol[sym] = np.mean(np.array(time_average_per_symbol[sym]), axis=0) + time_average_per_symbol[sym] = np.mean( + np.array(time_average_per_symbol[sym]), axis=0) # Take the time average of the gaze data: centralized_gaze_data = np.zeros_like(preprocessed_gaze_data) for i, (_, sym) in enumerate(zip(preprocessed_gaze_data, target_symbols)): - centralized_gaze_data[i] = gaze_model.subtract_mean(preprocessed_gaze_data[i], time_average_per_symbol[sym]) + centralized_gaze_data[i] = gaze_model.subtract_mean( + preprocessed_gaze_data[i], time_average_per_symbol[sym]) """ Calculate the accuracy of the fusion of EEG and Gaze models. Use the number of iterations to change bootstraping. @@ -218,10 +232,13 @@ def calculate_eeg_gaze_fusion_acc( bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt} [est. {remaining}][ela. {elapsed}]\n", colour='MAGENTA') for _progress in progress_bar: - progress_bar.set_description(f"Running iteration {_progress + 1}/{n_iterations}") + progress_bar.set_description( + f"Running iteration {_progress + 1}/{n_iterations}") # Pick a train and test dataset (that consists of non-train elements) until test dataset is not empty: - train_indices = resample(list(range(selection_length)), replace=True, n_samples=100) - test_indices = np.array([x for x in list(range(selection_length)) if x not in train_indices]) + train_indices = resample( + list(range(selection_length)), replace=True, n_samples=100) + test_indices = np.array( + [x for x in list(range(selection_length)) if x not in train_indices]) if len(test_indices) == 0: break @@ -255,12 +272,12 @@ def calculate_eeg_gaze_fusion_acc( # extract train and test indices for gaze data: centralized_gaze_data_train = centralized_gaze_data[train_indices] # gaze_train_labels = np.array([target_symbols[i] for i in train_indices]) - gaze_data_test = preprocessed_gaze_data[test_indices] # test set is NOT centralized + # test set is NOT centralized + gaze_data_test = preprocessed_gaze_data[test_indices] gaze_test_labels = np.array([target_symbols[i] for i in test_indices]) # generate a tuple that matches the index of the symbol with the symbol itself: symbol_to_index = {symbol: i for i, symbol in enumerate(symbol_set)} - # train and save the gaze model as a pkl file: reshaped_data = centralized_gaze_data_train.reshape( (len(centralized_gaze_data_train), inquiry_length * predefined_dimensions)) units = 1e4 @@ -285,14 +302,17 @@ def calculate_eeg_gaze_fusion_acc( except BaseException: # Singular matrix, using pseudo-inverse instead eps = 10e-3 # add a small value to the diagonal to make the matrix invertible - inv_cov_matrix = np.linalg.inv(cov_matrix + np.eye(len(cov_matrix)) * eps) + inv_cov_matrix = np.linalg.inv( + cov_matrix + np.eye(len(cov_matrix)) * eps) # inv_cov_matrix = np.linalg.pinv(cov_matrix + np.eye(len(cov_matrix))*eps) denominator_gaze = 0 # Given the test data, compute the log likelihood ratios for each symbol, # from eeg and gaze models: - eeg_log_likelihoods = np.zeros((len(gaze_data_test), (len(symbol_set)))) - gaze_log_likelihoods = np.zeros((len(gaze_data_test), (len(symbol_set)))) + eeg_log_likelihoods = np.zeros( + (len(gaze_data_test), (len(symbol_set)))) + gaze_log_likelihoods = np.zeros( + (len(gaze_data_test), (len(symbol_set)))) # Save the max posterior and the second max posterior for each test point: target_posteriors_gaze = np.zeros((len(gaze_data_test), 2)) @@ -308,23 +328,29 @@ def calculate_eeg_gaze_fusion_acc( for idx, sym in enumerate(symbol_set): # skip if there is no training example from the symbol if time_average_per_symbol[sym] == []: - gaze_log_likelihoods[test_idx, idx] = -100000 # set a very small value + gaze_log_likelihoods[test_idx, idx] = - \ + 100000 # set a very small value else: - central_data = gaze_model.subtract_mean(test_data, time_average_per_symbol[sym]) - flattened_data = central_data.reshape((inquiry_length * predefined_dimensions,)) + central_data = gaze_model.subtract_mean( + test_data, time_average_per_symbol[sym]) + flattened_data = central_data.reshape( + (inquiry_length * predefined_dimensions,)) flattened_data *= units diff = flattened_data - reshaped_mean diff_list.append(diff) - numerator = -np.dot(diff.T, np.dot(inv_cov_matrix, diff)) / 2 + numerator = - \ + np.dot(diff.T, np.dot(inv_cov_matrix, diff)) / 2 numerator_gaze_list.append(numerator) unnormalized_log_likelihood_gaze = numerator - denominator_gaze - gaze_log_likelihoods[test_idx, idx] = unnormalized_log_likelihood_gaze + gaze_log_likelihoods[test_idx, + idx] = unnormalized_log_likelihood_gaze normalized_posterior_gaze_only = np.exp( gaze_log_likelihoods[test_idx, :]) / np.sum(np.exp(gaze_log_likelihoods[test_idx, :])) # Find the max likelihood: max_like_gaze = np.argmax(normalized_posterior_gaze_only) - posterior_of_true_label_gaze = normalized_posterior_gaze_only[symbol_to_index[gaze_test_labels[test_idx]]] + posterior_of_true_label_gaze = normalized_posterior_gaze_only[ + symbol_to_index[gaze_test_labels[test_idx]]] top_competitor_gaze = np.sort(normalized_posterior_gaze_only)[-2] target_posteriors_gaze[test_idx, 0] = posterior_of_true_label_gaze target_posteriors_gaze[test_idx, 1] = top_competitor_gaze @@ -337,7 +363,8 @@ def calculate_eeg_gaze_fusion_acc( end = (test_idx + 1) * trials_per_inquiry eeg_tst_data = preprocessed_test_eeg[:, start:end, :] inq_sym = inquiry_symbols_test[start: end] - eeg_likelihood_ratios = eeg_model.compute_likelihood_ratio(eeg_tst_data, inq_sym, symbol_set) + eeg_likelihood_ratios = eeg_model.compute_likelihood_ratio( + eeg_tst_data, inq_sym, symbol_set) unnormalized_log_likelihood_eeg = np.log(eeg_likelihood_ratios) eeg_log_likelihoods[test_idx, :] = unnormalized_log_likelihood_eeg normalized_posterior_eeg_only = np.exp( @@ -345,7 +372,8 @@ def calculate_eeg_gaze_fusion_acc( max_like_eeg = np.argmax(normalized_posterior_eeg_only) top_competitor_eeg = np.sort(normalized_posterior_eeg_only)[-2] - posterior_of_true_label_eeg = normalized_posterior_eeg_only[symbol_to_index[gaze_test_labels[test_idx]]] + posterior_of_true_label_eeg = normalized_posterior_eeg_only[ + symbol_to_index[gaze_test_labels[test_idx]]] target_posteriors_eeg[test_idx, 0] = posterior_of_true_label_eeg target_posteriors_eeg[test_idx, 1] = top_competitor_eeg @@ -353,7 +381,8 @@ def calculate_eeg_gaze_fusion_acc( counter_eeg += 1 # Bayesian fusion update and decision making: - log_unnormalized_posterior = np.log(eeg_likelihood_ratios) + gaze_log_likelihoods[test_idx, :] + log_unnormalized_posterior = np.log( + eeg_likelihood_ratios) + gaze_log_likelihoods[test_idx, :] unnormalized_posterior = np.exp(log_unnormalized_posterior) denominator = np.sum(unnormalized_posterior) posterior = unnormalized_posterior / denominator # normalized posterior @@ -362,7 +391,8 @@ def calculate_eeg_gaze_fusion_acc( top_competitor_fusion = np.sort(log_posterior)[-2] posterior_of_true_label_fusion = posterior[symbol_to_index[gaze_test_labels[test_idx]]] - target_posteriors_fusion[test_idx, 0] = posterior_of_true_label_fusion + target_posteriors_fusion[test_idx, + 0] = posterior_of_true_label_fusion target_posteriors_fusion[test_idx, 1] = top_competitor_fusion if symbol_set[max_posterior] == gaze_test_labels[test_idx]: counter_fusion += 1 @@ -371,9 +401,12 @@ def calculate_eeg_gaze_fusion_acc( if posterior.any() == np.nan: break - eeg_acc_in_iteration = float("{:.3f}".format(counter_eeg / len(test_indices))) - gaze_acc_in_iteration = float("{:.3f}".format(counter_gaze / len(test_indices))) - fusion_acc_in_iteration = float("{:.3f}".format(counter_fusion / len(test_indices))) + eeg_acc_in_iteration = float( + "{:.3f}".format(counter_eeg / len(test_indices))) + gaze_acc_in_iteration = float( + "{:.3f}".format(counter_gaze / len(test_indices))) + fusion_acc_in_iteration = float( + "{:.3f}".format(counter_fusion / len(test_indices))) eeg_acc.append(eeg_acc_in_iteration) gaze_acc.append(gaze_acc_in_iteration) fusion_acc.append(fusion_acc_in_iteration) diff --git a/bcipy/signal/generator/generator.py b/bcipy/signal/generator/generator.py index b9f411cc0..efc76d1f0 100644 --- a/bcipy/signal/generator/generator.py +++ b/bcipy/signal/generator/generator.py @@ -1,6 +1,7 @@ -import numpy as np from typing import List +import numpy as np + def truncate_float(num: float, precision: int) -> float: """Truncate a float to a given precision.""" diff --git a/bcipy/signal/model/README.md b/bcipy/signal/model/README.md index 9f0abf2d4..a4189030d 100644 --- a/bcipy/signal/model/README.md +++ b/bcipy/signal/model/README.md @@ -62,7 +62,7 @@ These models may be trained and evalulated, but are still being integrated into *Note*: The gaze model is currently under development and is not yet fully implemented. -These models are used to update the posterior probability of stimuli viewed by a user based on gaze data. The gaze model uses a generative model to estimate the likelihood of the gaze data given the stimuli. There are several models implemented in this module, including a Gaussian Mixture Model (GMIndividual and GMCentralized) and Gaussian Process Model (GaussianProcess). When training data via offline analysis, if the data folder contains gaze data, the gaze model will be trained and saved to the output directory. +These models are used to update the posterior probability of stimuli viewed by a user based on gaze data. The gaze model uses a generative model to estimate the likelihood of the gaze data given the stimuli. There are several models implemented in this module, including a Gaussian Mixture Model (GMIndividual) and a Gaussian Process Model (GaussianProcess). When training data via offline analysis, if the data folder contains gaze data, the gaze model will be trained and saved to the output directory. ## Fusion Analyis diff --git a/bcipy/signal/model/__init__.py b/bcipy/signal/model/__init__.py index e4559f1b2..f65fe7c0d 100644 --- a/bcipy/signal/model/__init__.py +++ b/bcipy/signal/model/__init__.py @@ -1,16 +1,14 @@ -from bcipy.signal.model.base_model import SignalModel, ModelEvaluationReport +from bcipy.signal.model.base_model import ModelEvaluationReport, SignalModel +from bcipy.signal.model.gaussian_mixture.gaussian_mixture import ( + GaussianProcess, GMIndividual) from bcipy.signal.model.pca_rda_kde.pca_rda_kde import PcaRdaKdeModel from bcipy.signal.model.rda_kde.rda_kde import RdaKdeModel -from bcipy.signal.model.gaussian_mixture.gaussian_mixture import ( - GMIndividual, GMCentralized, GaussianProcess) - __all__ = [ "SignalModel", "PcaRdaKdeModel", "RdaKdeModel", 'GMIndividual', - 'GMCentralized', 'GaussianProcess', "ModelEvaluationReport", ] diff --git a/bcipy/signal/model/base_model.py b/bcipy/signal/model/base_model.py index af9f7028a..3f779b125 100644 --- a/bcipy/signal/model/base_model.py +++ b/bcipy/signal/model/base_model.py @@ -5,7 +5,7 @@ import numpy as np from bcipy.acquisition.devices import DeviceSpec -from bcipy.helpers.stimuli import Reshaper +from bcipy.core.stimuli import Reshaper from bcipy.signal.process import Composition diff --git a/bcipy/signal/model/classifier.py b/bcipy/signal/model/classifier.py index 61b629b10..c9df576d8 100644 --- a/bcipy/signal/model/classifier.py +++ b/bcipy/signal/model/classifier.py @@ -71,16 +71,20 @@ def fit(self, x, y, p=[]): # in order to make the ndarray readable from MATLAB side. There are # two arrays, [0] for the correctness, choose it # Class means - self.mean_i = [np.mean(x[np.where(y == i)[0]], axis=0) for i in self.class_i] + self.mean_i = [np.mean(x[np.where(y == i)[0]], axis=0) + for i in self.class_i] # Normalized x - norm_vec = [x[np.where(y == self.class_i[i])[0]] - self.mean_i[i] for i in range(len(self.class_i))] + norm_vec = [x[np.where(y == self.class_i[i])[0]] - self.mean_i[i] + for i in range(len(self.class_i))] # Outer product of data matrix, Xi'Xi for each class - self.S_i = [np.dot(np.transpose(norm_vec[i]), norm_vec[i]) for i in range(len(self.class_i))] + self.S_i = [np.dot(np.transpose(norm_vec[i]), norm_vec[i]) + for i in range(len(self.class_i))] # Sample covariances are calculated Si/Ni for each class - self.cov_i = [self.S_i[i] / self.N_i[i] for i in range(len(self.class_i))] + self.cov_i = [self.S_i[i] / self.N_i[i] + for i in range(len(self.class_i))] # Sample covariance of total data self.S = np.zeros((self.k, self.k)) @@ -90,7 +94,8 @@ def fit(self, x, y, p=[]): # Set priors if len(p) == 0: - prior = np.asarray([np.sum(y == self.class_i[i]) for i in range(len(self.class_i))], dtype=float) + prior = np.asarray([np.sum(y == self.class_i[i]) + for i in range(len(self.class_i))], dtype=float) self.prior_i = np.divide(prior, np.sum(prior)) else: self.prior_i = p @@ -110,13 +115,15 @@ def regularize(self, param): # TODO: what if no param passed? # Shrinked class covariances shr_cov_i = [ - ((1 - self.lam) * self.S_i[i] + self.lam * self.S) / ((1 - self.lam) * self.N_i[i] + self.lam * self.N) + ((1 - self.lam) * self.S_i[i] + self.lam * self.S) / + ((1 - self.lam) * self.N_i[i] + self.lam * self.N) for i in range(len(self.class_i)) ] # Regularized class covariances reg_cov_i = [ - ((1 - self.gam) * shr_cov_i[i] + self.gam / self.k * np.trace(shr_cov_i[i]) * np.eye(self.k)) + ((1 - self.gam) * shr_cov_i[i] + self.gam / + self.k * np.trace(shr_cov_i[i]) * np.eye(self.k)) for i in range(len(self.class_i)) ] @@ -156,7 +163,8 @@ def get_prob(self, x): # Every constant at the end of score calculation is omitted. # This is why we omit log det of class regularized covariances. - evidence = np.dot(zero_mean, np.dot(self.inv_reg_cov_i[i], zero_mean)) + evidence = np.dot(zero_mean, np.dot( + self.inv_reg_cov_i[i], zero_mean)) neg_log_l[s][i] = -0.5 * evidence + np.log(self.prior_i[i]) diff --git a/bcipy/signal/model/cross_validation.py b/bcipy/signal/model/cross_validation.py index 238229b0a..d29145113 100644 --- a/bcipy/signal/model/cross_validation.py +++ b/bcipy/signal/model/cross_validation.py @@ -1,17 +1,17 @@ -import numpy as np +import logging +import numpy as np import scipy.optimize from sklearn import metrics -from bcipy.config import SESSION_LOG_FILENAME -import logging +from bcipy.config import SESSION_LOG_FILENAME log = logging.getLogger(SESSION_LOG_FILENAME) def cost_cross_validation_auc(model, opt_el, x, y, param, k_folds=10, split='uniform'): - """ Minimize cost of the overall -AUC. + """Minimize cost of the overall -AUC. Cost function: given a particular architecture (model). Fits the parameters to the folds with leave one fold out procedure. Calculates scores for the validation fold. Concatenates all calculated scores @@ -31,7 +31,8 @@ def cost_cross_validation_auc(model, opt_el, x, y, param, k_folds=10, -auc(float): negative AUC value for current setup sc_h(ndarray[float]): scores computed for each validation fold y_valid_h(ndarray[int]): labels of the scores for each validation fold - y_valid_h[i] is basically the label for sc_h[i] """ + y_valid_h[i] is basically the label for sc_h[i] + """ num_samples = x.shape[1] fold_len = np.floor(float(num_samples) / k_folds) diff --git a/bcipy/signal/model/density_estimation.py b/bcipy/signal/model/density_estimation.py index 7e88442b9..28aa119be 100644 --- a/bcipy/signal/model/density_estimation.py +++ b/bcipy/signal/model/density_estimation.py @@ -17,11 +17,13 @@ class KernelDensityEstimate: """ def __init__(self, scores: Optional[np.array] = None, kernel="gaussian", num_cls=2): - bandwidth = 1.0 if scores is None else self._compute_bandwidth(scores, scores.shape[0]) + bandwidth = 1.0 if scores is None else self._compute_bandwidth( + scores, scores.shape[0]) self.logger = logging.getLogger(SESSION_LOG_FILENAME) self.logger.info(f"KDE. bandwidth={bandwidth}, kernel={kernel}") self.num_cls = num_cls - self.list_den_est = [KernelDensity(bandwidth=bandwidth, kernel=kernel) for _ in range(self.num_cls)] + self.list_den_est = [KernelDensity( + bandwidth=bandwidth, kernel=kernel) for _ in range(self.num_cls)] def _compute_bandwidth(self, scores: np.array, num_items: int): """Estimate bandwidth parameter using Silverman's rule of thumb. @@ -34,7 +36,8 @@ def _compute_bandwidth(self, scores: np.array, num_items: int): Returns: float: rule-of-thumb bandwidth parameter for KDE """ - bandwidth = 0.9 * min(np.std(scores), iqr(scores) / 1.34) * np.power(num_items, -0.2) + bandwidth = 0.9 * min(np.std(scores), iqr(scores) / + 1.34) * np.power(num_items, -0.2) return bandwidth def fit(self, x, y): @@ -61,7 +64,8 @@ def transform(self, x): Where N and c denotes number of samples and classes Returns: val(ndarray[float]): N x c log-likelihood array - respectively.""" + respectively. + """ # Calculate likelihoods for each density estimate val = [] diff --git a/bcipy/signal/model/dimensionality_reduction.py b/bcipy/signal/model/dimensionality_reduction.py index 288cc3da3..8ec52b868 100644 --- a/bcipy/signal/model/dimensionality_reduction.py +++ b/bcipy/signal/model/dimensionality_reduction.py @@ -1,6 +1,6 @@ import logging - from typing import Optional + import numpy as np from sklearn.decomposition import PCA @@ -28,9 +28,11 @@ class ChannelWisePrincipalComponentAnalysis: def __init__(self, n_components: Optional[float] = None, random_state: Optional[int] = None, num_ch: int = 1): self.num_ch = num_ch - self.list_pca = [PCA(n_components=n_components, random_state=random_state) for _ in range(self.num_ch)] + self.list_pca = [PCA(n_components=n_components, + random_state=random_state) for _ in range(self.num_ch)] self.logger = logging.getLogger(SESSION_LOG_FILENAME) - self.logger.info(f"PCA. n_components={n_components}, random_state={random_state}, num_ch={num_ch}") + self.logger.info( + f"PCA. n_components={n_components}, random_state={random_state}, num_ch={num_ch}") def fit(self, x: np.ndarray, y: Optional[np.ndarray] = None) -> None: """Fit PCA to each channel of data. diff --git a/bcipy/signal/model/gaussian_mixture/__init__.py b/bcipy/signal/model/gaussian_mixture/__init__.py index 9be2725f6..8999f632e 100644 --- a/bcipy/signal/model/gaussian_mixture/__init__.py +++ b/bcipy/signal/model/gaussian_mixture/__init__.py @@ -1,8 +1,7 @@ -from .gaussian_mixture import GMIndividual, GMCentralized, GaussianProcess, GazeModelResolver +from .gaussian_mixture import GaussianProcess, GazeModelResolver, GMIndividual __all__ = [ 'GMIndividual', - 'GMCentralized', 'GaussianProcess', 'GazeModelResolver' ] diff --git a/bcipy/signal/model/gaussian_mixture/gaussian_mixture.py b/bcipy/signal/model/gaussian_mixture/gaussian_mixture.py index 634e131b4..a585309c7 100644 --- a/bcipy/signal/model/gaussian_mixture/gaussian_mixture.py +++ b/bcipy/signal/model/gaussian_mixture/gaussian_mixture.py @@ -1,15 +1,17 @@ +import pickle +import warnings +from enum import Enum from pathlib import Path from typing import List -from enum import Enum - -from bcipy.helpers.stimuli import GazeReshaper -from bcipy.signal.model import SignalModel -from sklearn.mixture import GaussianMixture import numpy as np import scipy.stats as stats +from sklearn.mixture import GaussianMixture + +from bcipy.core.stimuli import GazeReshaper +from bcipy.exceptions import SignalException +from bcipy.signal.model import SignalModel -import warnings warnings.filterwarnings("ignore") # ignore DeprecationWarnings from tensorflow @@ -17,7 +19,6 @@ class GazeModelType(Enum): """Enum for gaze model types""" GAUSSIAN_PROCESS = "GaussianProcess" GM_INDIVIDUAL = "GMIndividual" - GM_CENTRALIZED = "GMCentralized" def __str__(self): return self.value @@ -31,8 +32,6 @@ def from_str(label: str): return GazeModelType.GAUSSIAN_PROCESS elif label == "GMIndividual": return GazeModelType.GM_INDIVIDUAL - elif label == "GMCentralized": - return GazeModelType.GM_CENTRALIZED else: raise ValueError(f"Model type {label} not recognized.") @@ -51,8 +50,6 @@ def resolve(model_type: str, *args, **kwargs) -> SignalModel: return GaussianProcess(*args, **kwargs) elif model_type == GazeModelType.GM_INDIVIDUAL: return GMIndividual(*args, **kwargs) - elif model_type == GazeModelType.GM_CENTRALIZED: - return GMCentralized(*args, **kwargs) else: raise ValueError( f"Model type {model_type} not able to resolve. Not registered in GazeModelResolver.") @@ -66,24 +63,77 @@ class GaussianProcess(SignalModel): def __init__(self, *args, **kwargs): self.ready_to_predict = False self.acc = None + self.time_average = None + self.centralized_data = None + self.model = None - def fit(self, training_data: np.ndarray): - ... + def fit(self, time_avg: np.ndarray, cent_data: np.ndarray): + """Fit the Gaussian Process model to the training data. + Args: + time_avg Dict[(np.ndarray)]: Time average for the symbols. + mean_data (np.ndarray): Sample average for the training data. + cov_data (np.ndarray): Covariance matrix for the training data. + """ + self.time_average = time_avg + self.centralized_data = cent_data + self.ready_to_predict = True + return self def evaluate(self, test_data: np.ndarray, test_labels: np.ndarray): ... + def evaluate_likelihood(self, data: np.ndarray, symbols: List[str], + symbol_set: List[str]) -> np.ndarray: + if not self.ready_to_predict: + raise SignalException( + "must use model.fit() before model.evaluate_likelihood()") + + gaze_log_likelihoods = np.zeros((len(symbol_set))) + # Clip the pre-saved centralized data to the length of our test data + cent_data = self.centralized_data[:, :, :data.shape[1]] + reshaped_data = cent_data.reshape( + (len(cent_data), data.shape[0] * data.shape[1])) + cov_matrix = np.cov(reshaped_data, rowvar=False) + reshaped_mean = np.mean(reshaped_data, axis=0) + eps = 10e-1 # add a small value to the diagonal to make the cov matrix invertible + inv_cov_matrix = np.linalg.inv( + cov_matrix + np.eye(len(cov_matrix)) * eps) + + for idx, sym in enumerate(symbol_set): + if self.time_average[sym] == []: + gaze_log_likelihoods[idx] = -100000 # set a very small value + else: + # Compute the likelihood of the data for each symbol + central_data = self.subtract_mean(data, self.time_average[sym]) + # flatten this data + flattened_data = np.reshape(central_data, (-1, )) + diff = flattened_data - reshaped_mean + numerator = -np.dot(diff.T, np.dot(inv_cov_matrix, diff)) / 2 + denominator = 0 + unnormalized_log_likelihood_gaze = numerator - denominator + gaze_log_likelihoods[idx] = unnormalized_log_likelihood_gaze + # Find the gaze_likelihoods for the symbols in the inquiry + gaze_likelihood = np.exp(gaze_log_likelihoods) + + return gaze_likelihood # used in multimodal update + def predict(self, test_data: np.ndarray, inquiry, symbol_set) -> np.ndarray: ... def predict_proba(self, test_data: np.ndarray) -> np.ndarray: ... - def save(self, path: Path): - ... + def save(self, path: Path) -> None: + """Save model weights (e.g. after training) to `path`""" + with open(path, "wb") as f: + pickle.dump(self.model, f) - def load(self, path: Path): - ... + def load(self, path: Path) -> SignalModel: + """Load pretrained model from `path`""" + with open(path, "rb") as f: + model = pickle.load(f) + + return model def centralize(self, data: np.ndarray, symbol_pos: np.ndarray) -> np.ndarray: """ Using the symbol locations in matrix, centralize all data (in Tobii units). @@ -132,7 +182,8 @@ def __init__(self, num_components=4, random_state=0, *args, **kwargs): self.ready_to_predict = False def fit(self, train_data: np.ndarray): - model = GaussianMixture(n_components=self.num_components, random_state=self.random_state, init_params='kmeans') + model = GaussianMixture(n_components=self.num_components, + random_state=self.random_state, init_params='kmeans') model.fit(train_data) self.model = model @@ -155,7 +206,8 @@ def evaluate(self, predictions, true_labels) -> np.ndarray: -------- accuracy_per_symbol: accuracy per symbol ''' - accuracy_per_symbol = np.sum(predictions == true_labels) / len(predictions) * 100 + accuracy_per_symbol = np.sum( + predictions == true_labels) / len(predictions) * 100 self.acc = accuracy_per_symbol return accuracy_per_symbol @@ -195,22 +247,8 @@ def predict_proba(self, test_data: np.ndarray) -> np.ndarray: ''' data_length, _ = test_data.shape - likelihoods = np.zeros((data_length, self.num_components), dtype=object) - - # Find the likelihoods by insterting the test data into the pdf of each component - for i in range(data_length): - for k in range(self.num_components): - mu = self.means[k] - sigma = self.covs[k] - - likelihoods[i, k] = stats.multivariate_normal.pdf(test_data[i], mu, sigma) - - return likelihoods - - def evaluate_likelihood(self, data: np.ndarray) -> np.ndarray: - data_length, _ = data.shape - - likelihoods = np.zeros((data_length, self.num_components), dtype=object) + likelihoods = np.zeros( + (data_length, self.num_components), dtype=object) # Find the likelihoods by insterting the test data into the pdf of each component for i in range(data_length): @@ -218,85 +256,20 @@ def evaluate_likelihood(self, data: np.ndarray) -> np.ndarray: mu = self.means[k] sigma = self.covs[k] - likelihoods[i, k] = stats.multivariate_normal.pdf(data[i], mu, sigma) + likelihoods[i, k] = stats.multivariate_normal.pdf( + test_data[i], mu, sigma) return likelihoods - def save(self, path: Path): - """Save model state to the provided checkpoint""" - ... - - def load(self, path: Path): - """Load model state from the provided checkpoint""" - ... - - -class GMCentralized(SignalModel): - '''Gaze model that uses all symbols to fit a single Gaussian ''' - reshaper = GazeReshaper() - name = "gaze_model_combined" - - def __init__(self, num_components=4, random_state=0, *args, **kwargs): - self.num_components = num_components # number of gaussians to fit - self.random_state = random_state - self.acc = None - self.means = None - self.covs = None - - self.ready_to_predict = False - - def fit(self, train_data: np.ndarray): - model = GaussianMixture(n_components=self.num_components, random_state=self.random_state, init_params='kmeans') - model.fit(train_data) - self.model = model - - self.means = model.means_ - self.covs = model.covariances_ - - self.ready_to_predict = True - return self - - def evaluate(self, predictions, true_labels) -> np.ndarray: - ''' - Compute performance characteristics on the provided test data and labels. - - Parameters: - ----------- - predictions: predicted labels for each test point per symbol - true_labels: true labels for each test point per symbol - Returns: - -------- - accuracy_per_symbol: accuracy per symbol - ''' - accuracy_per_symbol = np.sum(predictions == true_labels) / len(predictions) * 100 - self.acc = accuracy_per_symbol - return accuracy_per_symbol - - def predict(self, test_data: np.ndarray) -> np.ndarray: - ''' - Compute log-likelihood of each sample. - Predict the labels for the test data. - ''' - data_length, _ = test_data.shape - predictions = np.zeros(data_length, dtype=object) - likelihoods = self.model.predict_proba(test_data) - - for i in range(data_length): - # Find the argmax of the likelihoods to get the predictions - predictions[i] = np.argmax(likelihoods[i]) - - return predictions - - def predict_proba(self, test_data: np.ndarray) -> np.ndarray: - ''' - Compute log-likelihood of each sample. - Predict the labels for the test data. + def evaluate_likelihood(self, data: np.ndarray, symbols: List[str], + symbol_set: List[str]) -> np.ndarray: + if not self.ready_to_predict: + raise SignalException( + "must use model.fit() before model.evaluate_likelihood()") - test_data: - ''' - data_length, _ = test_data.shape - - likelihoods = np.zeros((data_length, self.num_components), dtype=object) + data_length, _ = data.shape + likelihoods = np.zeros( + (data_length, self.num_components), dtype=object) # Find the likelihoods by insterting the test data into the pdf of each component for i in range(data_length): @@ -304,42 +277,19 @@ def predict_proba(self, test_data: np.ndarray) -> np.ndarray: mu = self.means[k] sigma = self.covs[k] - likelihoods[i, k] = stats.multivariate_normal.pdf(test_data[i], mu, sigma) + likelihoods[i, k] = stats.multivariate_normal.pdf( + data[i], mu, sigma) return likelihoods - def calculate_acc(self, predictions: int, counter: int): - ''' - Compute model performance characteristics on the provided test data and labels. - - predictions: predicted labels for each test point per symbol - counter: true labels for each test point per symbol - ''' - accuracy_per_symbol = np.sum(predictions == counter) / len(predictions) * 100 + def save(self, path: Path) -> None: + """Save model weights (e.g. after training) to `path`""" + with open(path, "wb") as f: + pickle.dump(self.model, f) - return accuracy_per_symbol - - def save(self, path: Path): - """Save model state to the provided checkpoint""" - ... + def load(self, path: Path) -> SignalModel: + """Load pretrained model from `path`""" + with open(path, "rb") as f: + model = pickle.load(f) - def load(self, path: Path): - """Load model state from the provided checkpoint""" - ... - - def centralize(self, data: np.ndarray, symbol_pos: np.ndarray) -> np.ndarray: - """ Using the symbol locations in matrix, centralize all data (in Tobii units). - This data will only be used in certain model types. - Args: - data (np.ndarray): Data in shape of num_samples x num_dimensions - symbol_pos (np.ndarray(float)): Array of the current symbol posiiton in Tobii units - Returns: - new_data (np.ndarray): Centralized data in shape of num_samples x num_dimensions - """ - new_data = np.copy(data) - for i in range(len(data)): - # new_data[i] = data[i] - symbol_pos - new_data[:2, i] = data[:2, i] - symbol_pos - new_data[2:, i] = data[2:, i] - symbol_pos - - return new_data + return model diff --git a/bcipy/signal/model/offline_analysis.py b/bcipy/signal/model/offline_analysis.py index ab0b3f9da..2f6474547 100644 --- a/bcipy/signal/model/offline_analysis.py +++ b/bcipy/signal/model/offline_analysis.py @@ -1,42 +1,40 @@ # mypy: disable-error-code="attr-defined" -import json import logging import subprocess from pathlib import Path from typing import List import numpy as np - from sklearn.metrics import balanced_accuracy_score from sklearn.model_selection import train_test_split import bcipy.acquisition.devices as devices from bcipy.acquisition.devices import DeviceSpec -from bcipy.config import (DEFAULT_DEVICE_SPEC_FILENAME, - DEFAULT_PARAMETERS_PATH, DEFAULT_DEVICES_PATH, - TRIGGER_FILENAME, SESSION_LOG_FILENAME, - STIMULI_POSITIONS_FILENAME) -from bcipy.helpers.acquisition import analysis_channels, raw_data_filename -from bcipy.helpers.load import (load_experimental_data, load_json_parameters, - load_raw_data) +from bcipy.config import (DEFAULT_DEVICE_SPEC_FILENAME, DEFAULT_DEVICES_PATH, + DEFAULT_PARAMETERS_PATH, SESSION_LOG_FILENAME, + TRIGGER_FILENAME) +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawData +from bcipy.core.stimuli import update_inquiry_timing +from bcipy.core.symbols import alphabet +from bcipy.core.triggers import TriggerType, trigger_decoder from bcipy.gui.alert import confirm -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.save import save_model -from bcipy.helpers.stimuli import update_inquiry_timing -from bcipy.helpers.symbols import alphabet -from bcipy.helpers.system_utils import report_execution_time -from bcipy.helpers.triggers import TriggerType, trigger_decoder -from bcipy.helpers.raw_data import RawData +from bcipy.helpers.acquisition import analysis_channels, raw_data_filename +from bcipy.helpers.utils import report_execution_time +from bcipy.io.load import (load_experimental_data, load_json_parameters, + load_raw_data) +from bcipy.io.save import save_model from bcipy.preferences import preferences +from bcipy.signal.evaluate.fusion import calculate_eeg_gaze_fusion_acc from bcipy.signal.model.base_model import SignalModel, SignalModelMetadata -from bcipy.signal.model.gaussian_mixture import (GazeModelResolver) +from bcipy.signal.model.gaussian_mixture import GazeModelResolver from bcipy.signal.model.pca_rda_kde import PcaRdaKdeModel from bcipy.signal.process import (ERPTransformParams, extract_eye_info, filter_inquiries, get_default_transform) -from bcipy.signal.evaluate.fusion import calculate_eeg_gaze_fusion_acc log = logging.getLogger(SESSION_LOG_FILENAME) -logging.basicConfig(level=logging.INFO, format="[%(threadName)-9s][%(asctime)s][%(name)s][%(levelname)s]: %(message)s") +logging.basicConfig(level=logging.INFO, + format="[%(threadName)-9s][%(asctime)s][%(name)s][%(levelname)s]: %(message)s") def subset_data(data: np.ndarray, labels: np.ndarray, test_size: float, random_state: int = 0, swap_axes: bool = True): @@ -153,12 +151,14 @@ def analyze_erp( ) # update the trigger timing list to account for the initial trial window - corrected_trigger_timing = [timing + trial_window[0] for timing in trigger_timing] + corrected_trigger_timing = [timing + trial_window[0] + for timing in trigger_timing] # Channel map can be checked from raw_data.csv file or the devices.json located in the acquisition module # The timestamp column [0] is already excluded. channel_map = analysis_channels(channels, device_spec) - channels_used = [channels[i] for i, keep in enumerate(channel_map) if keep == 1] + channels_used = [channels[i] + for i, keep in enumerate(channel_map) if keep == 1] log.info(f'Channels used in analysis: {channels_used}') data, fs = erp_data.by_channel() @@ -178,7 +178,8 @@ def analyze_erp( inquiries, fs = filter_inquiries(inquiries, default_transform, sample_rate) inquiry_timing = update_inquiry_timing(inquiry_timing, downsample_rate) trial_duration_samples = int(window_length * fs) - data = model.reshaper.extract_trials(inquiries, trial_duration_samples, inquiry_timing) + data = model.reshaper.extract_trials( + inquiries, trial_duration_samples, inquiry_timing) # define the training classes using integers, where 0=nontargets/1=targets labels = inquiry_labels.flatten().tolist() @@ -199,7 +200,8 @@ def analyze_erp( try: # Using an 80/20 split, report on balanced accuracy if estimate_balanced_acc: - train_data, test_data, train_labels, test_labels = subset_data(data, labels, test_size=0.2) + train_data, test_data, train_labels, test_labels = subset_data( + data, labels, test_size=0.2) dummy_model = PcaRdaKdeModel(k_folds=k_folds) dummy_model.fit(train_data, train_labels) probs = dummy_model.predict_proba(test_data) @@ -212,7 +214,8 @@ def analyze_erp( except Exception as e: log.error(f"Error calculating balanced accuracy: {e}") - save_model(model, Path(data_folder, f"model_{device_spec.content_type.lower()}_{model.auc:0.4f}.pkl")) + save_model(model, Path( + data_folder, f"model_{device_spec.content_type.lower()}_{model.auc:0.4f}.pkl")) preferences.signal_model_directory = data_folder if save_figures or show_figures: @@ -234,7 +237,8 @@ def analyze_gaze( device_spec: DeviceSpec, data_folder: str, model_type: str = "GaussianProcess", - symbol_set: List[str] = alphabet()) -> SignalModel: + symbol_set: List[str] = alphabet(), + testing_acc: float = 0.0) -> SignalModel: """Analyze gaze data and return/save the gaze model. Extract relevant information from gaze data object. Extract timing information from trigger file. @@ -250,21 +254,26 @@ def analyze_gaze( parameters (Parameters): Parameters object retireved from parameters.json. device_spec (DeviceSpec): DeviceSpec object containing information about the device used. data_folder (str): Path to the folder containing the data to be analyzed. - model_type (str): Type of gaze model to be used. Options are: "GMIndividual", "GMCentralized", - or "GaussianProcess". + model_type (str): Type of gaze model to be used. Options are: "GMIndividual" or + "GaussianProcess". + symbol_set (List[str]): List of symbols to be used in the analysis. + testing_acc (float): Testing accuracy of the model. This is calculated during fusion analysis. + Imported to add to the metadata of the model. """ channels = gaze_data.channels type_amp = gaze_data.daq_type sample_rate = gaze_data.sample_rate flash_time = parameters.get("time_flash") # duration of each stimulus - stim_size = parameters.get("stim_length") # number of stimuli per inquiry + # number of stimuli per inquiry + stim_length = parameters.get("stim_length") log.info(f"Channels read from csv: {channels}") log.info(f"Device type: {type_amp}, fs={sample_rate}") channel_map = analysis_channels(channels, device_spec) - channels_used = [channels[i] for i, keep in enumerate(channel_map) if keep == 1] + channels_used = [channels[i] + for i, keep in enumerate(channel_map) if keep == 1] log.info(f'Channels used in analysis: {channels_used}') data, _fs = gaze_data.by_channel() @@ -286,10 +295,12 @@ def analyze_gaze( ) ''' Trigger_timing includes PROMPT and excludes FIXATION ''' - target_symbols = trigger_symbols[0::stim_size + 1] # target symbols are the PROMPT triggers + # target symbols are the PROMPT triggers + target_symbols = trigger_symbols[0::stim_length + 1] # Use trigger_timing to generate time windows for each letter flashing # Take every 10th trigger as the start point of timing. - inq_start = trigger_timing[1::stim_size + 1] # start of each inquiry (here we jump over prompts) + # start of each inquiry (here we jump over prompts) + inq_start = trigger_timing[1::stim_length + 1] # Extract the inquiries dictionary with keys as target symbols and values as inquiry windows: inquiries_dict, inquiries_list, _ = model.reshaper( @@ -298,18 +309,21 @@ def analyze_gaze( gaze_data=data, sample_rate=sample_rate, stimulus_duration=flash_time, - num_stimuli_per_inquiry=stim_size, + num_stimuli_per_inquiry=stim_length, symbol_set=symbol_set, ) # Apply preprocessing: - inquiry_length = inquiries_list[0].shape[1] # number of time samples in each inquiry + # number of time samples in each inquiry + inquiry_length = inquiries_list[0].shape[1] predefined_dimensions = 4 # left_x, left_y, right_x, right_y - preprocessed_array = np.zeros((len(inquiries_list), predefined_dimensions, inquiry_length)) + preprocessed_array = np.zeros( + (len(inquiries_list), predefined_dimensions, inquiry_length)) # Extract left_x, left_y, right_x, right_y for each inquiry for j in range(len(inquiries_list)): left_eye, right_eye, _, _, _, _ = extract_eye_info(inquiries_list[j]) - preprocessed_array[j] = np.concatenate((left_eye.T, right_eye.T,), axis=0) + preprocessed_array[j] = np.concatenate( + (left_eye.T, right_eye.T,), axis=0) preprocessed_data = {i: [] for i in symbol_set} for i in symbol_set: @@ -318,8 +332,10 @@ def analyze_gaze( continue for j in range(len(inquiries_dict[i])): - left_eye, right_eye, _, _, _, _ = extract_eye_info(inquiries_dict[i][j]) - preprocessed_data[i].append((np.concatenate((left_eye.T, right_eye.T), axis=0))) + left_eye, right_eye, _, _, _, _ = extract_eye_info( + inquiries_dict[i][j]) + preprocessed_data[i].append( + (np.concatenate((left_eye.T, right_eye.T), axis=0))) # Inquiries x All Dimensions (left_x, left_y, right_x, right_y) x Time preprocessed_data[i] = np.array(preprocessed_data[i]) @@ -345,16 +361,6 @@ def analyze_gaze( preprocessed_data[sym].shape[1])) model.fit(reshaped_data) - if model_type == "GMCentralized": - # Centralize the data using symbol positions and fit a single Gaussian. - # Load json file. - with open(f"{data_folder}/{STIMULI_POSITIONS_FILENAME}", 'r') as params_file: - symbol_positions = json.load(params_file) - - # Subtract the symbol positions from the data: - for j in range(len(preprocessed_data[sym])): - centralized_data[sym].append(model.centralize(preprocessed_data[sym][j], symbol_positions[sym])) - if model_type == "GaussianProcess": # Instead of centralizing, take the time average: for j in range(len(preprocessed_data[sym])): @@ -371,7 +377,8 @@ def analyze_gaze( # Split the data into train and test sets & fit the model: centralized_gaze_data = np.zeros_like(preprocessed_array) for i, (_, sym) in enumerate(zip(preprocessed_array, target_symbols)): - centralized_gaze_data[i] = model.subtract_mean(preprocessed_array[i], time_average[sym]) + centralized_gaze_data[i] = model.subtract_mean( + preprocessed_array[i], time_average[sym]) reshaped_data = centralized_gaze_data.reshape( (len(centralized_gaze_data), inquiry_length * predefined_dimensions)) @@ -388,26 +395,17 @@ def analyze_gaze( cov_matrix[l_ind, m_ind] = 0 reshaped_mean = np.mean(reshaped_data, axis=0) - # Save model parameters which are mean and covariance matrix - model.fit(reshaped_mean) - - if model_type == "GMCentralized": - # Fit the model parameters using the centralized data: - # flatten the dict to a np array: - cent_data = np.concatenate([centralized_data[sym] for sym in symbol_set], axis=0) - # Merge the first and third dimensions: - cent_data = cent_data.reshape((cent_data.shape[0] * cent_data.shape[2], cent_data.shape[1])) - - # cent_data = np.concatenate(centralized_data, axis=0) - model.fit(cent_data) + # Save model parameters which are time averages per symbol (time_average): Dict(np.array), + # and centralized data points (centralized_gaze_data): (np.array) of shape N_inquiries x N_dims x N_timesamples + model.fit(time_average, centralized_gaze_data) model.metadata = SignalModelMetadata(device_spec=device_spec, transform=None, - acc=model.acc) + acc=testing_acc) log.info("Training complete for Eyetracker model. Saving data...") save_model( model, - Path(data_folder, f"model_{device_spec.content_type.lower()}_{model.acc}.pkl")) + Path(data_folder, f"model_{device_spec.content_type.lower()}_{model.metadata.acc}.pkl")) return model @@ -454,7 +452,9 @@ def offline_analysis( """ assert parameters, "Parameters are required for offline analysis." if not data_folder: - data_folder = load_experimental_data() + data_folder = load_experimental_data( + message="Select the folder containing the data to be analyzed.", + strict=True) # Load default devices which are used for training the model with different channels, etc. devices_by_name = devices.load( @@ -467,7 +467,8 @@ def offline_analysis( if spec.is_active) active_raw_data_paths = (Path(data_folder, raw_data_filename(device_spec)) for device_spec in active_devices) - data_file_paths = [str(path) for path in active_raw_data_paths if path.exists()] + data_file_paths = [str(path) + for path in active_raw_data_paths if path.exists()] num_devices = len(data_file_paths) assert num_devices >= 1 and num_devices < 3, ( @@ -476,6 +477,7 @@ def offline_analysis( symbol_set = alphabet() fusion = False + avg_testing_acc_gaze = 0.0 if num_devices == 2: # Ensure there is an EEG and Eyetracker device fusion = True @@ -503,7 +505,10 @@ def offline_analysis( n_iterations=n_iterations, ) - log.info(f"EEG Accuracy: {eeg_acc}, Gaze Accuracy: {gaze_acc}, Fusion Accuracy: {fusion_acc}") + log.info( + f"EEG Accuracy: {eeg_acc}, Gaze Accuracy: {gaze_acc}, Fusion Accuracy: {fusion_acc}") + # The average gaze model accuracy: + avg_testing_acc_gaze = round(np.mean(gaze_acc), 3) # Ask the user if they want to proceed with full dataset model training models = [] @@ -530,7 +535,8 @@ def offline_analysis( parameters, device_spec, data_folder, - symbol_set=symbol_set) + symbol_set=symbol_set, + testing_acc=avg_testing_acc_gaze) models.append(et_model) if alert: @@ -568,9 +574,12 @@ def main(): "--parameters_file", default=DEFAULT_PARAMETERS_PATH, help="Path to the BciPy parameters file.") - parser.add_argument("-s", "--save_figures", action="store_true", help="Save figures after training.") - parser.add_argument("-v", "--show_figures", action="store_true", help="Show figures after training.") - parser.add_argument("-i", "--iterations", type=int, default=10, help="Number of iterations for fusion analysis.") + parser.add_argument("-s", "--save_figures", + action="store_true", help="Save figures after training.") + parser.add_argument("-v", "--show_figures", + action="store_true", help="Show figures after training.") + parser.add_argument("-i", "--iterations", type=int, default=10, + help="Number of iterations for fusion analysis.") parser.add_argument( "--alert", dest="alert", diff --git a/bcipy/signal/model/pca_rda_kde/pca_rda_kde.py b/bcipy/signal/model/pca_rda_kde/pca_rda_kde.py index 255ccc0c4..53815126a 100644 --- a/bcipy/signal/model/pca_rda_kde/pca_rda_kde.py +++ b/bcipy/signal/model/pca_rda_kde/pca_rda_kde.py @@ -4,8 +4,8 @@ import numpy as np +from bcipy.core.stimuli import InquiryReshaper from bcipy.exceptions import SignalException -from bcipy.helpers.stimuli import InquiryReshaper from bcipy.signal.model import ModelEvaluationReport, SignalModel from bcipy.signal.model.classifier import RegularizedDiscriminantAnalysis from bcipy.signal.model.cross_validation import (cost_cross_validation_auc, @@ -49,13 +49,15 @@ def fit(self, train_data: np.array, train_labels: np.array) -> SignalModel: """ model = Pipeline( [ - ChannelWisePrincipalComponentAnalysis(n_components=self.pca_n_components, num_ch=train_data.shape[0]), + ChannelWisePrincipalComponentAnalysis( + n_components=self.pca_n_components, num_ch=train_data.shape[0]), RegularizedDiscriminantAnalysis(), ] ) # Find the optimal gamma + lambda values - arg_cv = cross_validation(train_data, train_labels, model=model, k_folds=self.k_folds) + arg_cv = cross_validation( + train_data, train_labels, model=model, k_folds=self.k_folds) # Get the AUC using those optimized gamma + lambda rda_index = 1 # the index in the pipeline @@ -102,7 +104,8 @@ def evaluate(self, test_data: np.array, test_labels: np.array) -> ModelEvaluatio ModelEvaluationReport: stores AUC """ if not self.ready_to_predict: - raise SignalException("must use model.fit() before model.evaluate()") + raise SignalException( + "must use model.fit() before model.evaluate()") tmp_model = Pipeline([self.model.pipeline[0], self.model.pipeline[1]]) @@ -134,18 +137,22 @@ def compute_likelihood_ratio(self, data: np.array, inquiry: List[str], symbol_se """ if not self.ready_to_predict: - raise SignalException("must use model.fit() before model.predict()") + raise SignalException( + "must use model.fit() before model.predict()") # Evaluate likelihood probabilities for p(e|l=1) and p(e|l=0) log_likelihoods = self.model.transform(data) - subset_likelihood_ratios = np.exp(log_likelihoods[:, 1] - log_likelihoods[:, 0]) + subset_likelihood_ratios = np.exp( + log_likelihoods[:, 1] - log_likelihoods[:, 0]) # Restrict multiplicative updates to a reasonable range - subset_likelihood_ratios = np.clip(subset_likelihood_ratios, self.min, self.max) + subset_likelihood_ratios = np.clip( + subset_likelihood_ratios, self.min, self.max) # Apply likelihood ratios to entire symbol set. likelihood_ratios = np.ones(len(symbol_set)) for idx in range(len(subset_likelihood_ratios)): - likelihood_ratios[symbol_set.index(inquiry[idx])] *= subset_likelihood_ratios[idx] + likelihood_ratios[symbol_set.index( + inquiry[idx])] *= subset_likelihood_ratios[idx] return likelihood_ratios # used in multimodal update def compute_class_probabilities(self, data: np.ndarray) -> np.ndarray: @@ -156,7 +163,8 @@ def compute_class_probabilities(self, data: np.ndarray) -> np.ndarray: probability for the two labels. """ if not self.ready_to_predict: - raise SignalException("must use model.fit() before model.predict_proba()") + raise SignalException( + "must use model.fit() before model.predict_proba()") # Model originally produces p(eeg | label). We want p(label | eeg): # @@ -178,7 +186,8 @@ def evaluate_likelihood(self, data: np.ndarray) -> np.ndarray: p(e | l=1), p(e | l=0) """ if not self.ready_to_predict: - raise SignalException("must use model.fit() before model.predict_proba()") + raise SignalException( + "must use model.fit() before model.predict_proba()") log_scores_class_0 = self.model.transform(data)[:, 0] log_scores_class_1 = self.model.transform(data)[:, 1] @@ -191,7 +200,8 @@ def predict(self, data: np.ndarray) -> np.ndarray: predictions (np.ndarray): shape (num_items,) - the predicted label for each item. """ if not self.ready_to_predict: - raise SignalException("must use model.fit() before model.predict()") + raise SignalException( + "must use model.fit() before model.predict()") posterior = self.compute_class_probabilities(data) predictions = np.argmax(posterior, axis=1) @@ -205,7 +215,8 @@ def predict_proba(self, data: np.ndarray) -> np.ndarray: probability for the two labels. """ if not self.ready_to_predict: - raise SignalException("must use model.fit() before model.predict_proba()") + raise SignalException( + "must use model.fit() before model.predict_proba()") return self.compute_class_probabilities(data) diff --git a/bcipy/signal/model/pipeline.py b/bcipy/signal/model/pipeline.py index f89243f66..3ac6c79e1 100644 --- a/bcipy/signal/model/pipeline.py +++ b/bcipy/signal/model/pipeline.py @@ -36,7 +36,8 @@ def fit(self, x, y): y(ndarray[int]): of desired shape """ self.line_el = [x] for i in range(len(self.pipeline) - 1): - self.line_el.append(self.pipeline[i].fit_transform(self.line_el[i], y)) + self.line_el.append( + self.pipeline[i].fit_transform(self.line_el[i], y)) self.pipeline[-1].fit(self.line_el[-1], y) @@ -48,16 +49,18 @@ def fit_transform(self, x, y): self.line_el = [x] for i in range(len(self.pipeline) - 1): - self.line_el.append(self.pipeline[i].fit_transform(self.line_el[i], y)) + self.line_el.append( + self.pipeline[i].fit_transform(self.line_el[i], y)) arg = self.pipeline[-1].fit_transform(self.line_el[-1], y) return arg def transform(self, x): - """ Applies transform on all functions. Prior to using transform on + """Applies transform on all functions. Prior to using transform on pipeline, it should be trained. Args: - x(ndarray[float]): of desired shape """ + x(ndarray[float]): of desired shape + """ self.line_el = [x] for i in range(len(self.pipeline)): self.line_el.append(self.pipeline[i].transform(self.line_el[i])) diff --git a/bcipy/signal/model/rda_kde/rda_kde.py b/bcipy/signal/model/rda_kde/rda_kde.py index 6c716d569..ab0ff82a6 100644 --- a/bcipy/signal/model/rda_kde/rda_kde.py +++ b/bcipy/signal/model/rda_kde/rda_kde.py @@ -3,14 +3,16 @@ from typing import List import numpy as np + +from bcipy.core.stimuli import InquiryReshaper +from bcipy.exceptions import SignalException from bcipy.signal.model import ModelEvaluationReport, SignalModel from bcipy.signal.model.classifier import RegularizedDiscriminantAnalysis -from bcipy.signal.model.cross_validation import cost_cross_validation_auc, cross_validation +from bcipy.signal.model.cross_validation import (cost_cross_validation_auc, + cross_validation) from bcipy.signal.model.density_estimation import KernelDensityEstimate from bcipy.signal.model.dimensionality_reduction import MockPCA from bcipy.signal.model.pipeline import Pipeline -from bcipy.exceptions import SignalException -from bcipy.helpers.stimuli import InquiryReshaper class RdaKdeModel(SignalModel): @@ -41,7 +43,8 @@ def fit(self, train_data: np.array, train_labels: np.array) -> SignalModel: model = Pipeline([MockPCA(), RegularizedDiscriminantAnalysis()]) # Find the optimal gamma + lambda values - arg_cv = cross_validation(train_data, train_labels, model=model, k_folds=self.k_folds) + arg_cv = cross_validation( + train_data, train_labels, model=model, k_folds=self.k_folds) # Get the AUC using those optimized gamma + lambda rda_index = 1 # the index in the pipeline @@ -90,7 +93,8 @@ def evaluate(self, test_data: np.array, test_labels: np.array) -> ModelEvaluatio ModelEvaluationReport: stores AUC """ if not self._ready_to_predict: - raise SignalException("must use model.fit() before model.evaluate()") + raise SignalException( + "must use model.fit() before model.evaluate()") tmp_model = Pipeline([self.model.pipeline[0], self.model.pipeline[1]]) @@ -103,8 +107,7 @@ def evaluate(self, test_data: np.array, test_labels: np.array) -> ModelEvaluatio return ModelEvaluationReport(auc) def predict(self, data: np.array, inquiry: List[str], symbol_set: List[str]) -> np.array: - """ - For each trial in `data`, compute a likelihood ratio to update that symbol's probability. + """For each trial in `data`, compute a likelihood ratio to update that symbol's probability. Rather than just computing an update p(e|l=+) for the seen symbol and p(e|l=-) for all unseen symbols, we compute a likelihood ratio p(e | l=+) / p(e | l=-) to update the seen symbol, and all other symbols can receive a multiplicative update of 1. @@ -122,18 +125,22 @@ def predict(self, data: np.array, inquiry: List[str], symbol_set: List[str]) -> """ if not self._ready_to_predict: - raise SignalException("must use model.fit() before model.predict()") + raise SignalException( + "must use model.fit() before model.predict()") # Evaluate likelihood probabilities for p(e|l=1) and p(e|l=0) log_likelihoods = self.model.transform(data) - subset_likelihood_ratios = np.exp(log_likelihoods[:, 1] - log_likelihoods[:, 0]) + subset_likelihood_ratios = np.exp( + log_likelihoods[:, 1] - log_likelihoods[:, 0]) # Restrict multiplicative updates to a reasonable range - subset_likelihood_ratios = np.clip(subset_likelihood_ratios, self.min, self.max) + subset_likelihood_ratios = np.clip( + subset_likelihood_ratios, self.min, self.max) # Apply likelihood ratios to entire symbol set. likelihood_ratios = np.ones(len(symbol_set)) for idx in range(len(subset_likelihood_ratios)): - likelihood_ratios[symbol_set.index(inquiry[idx])] *= subset_likelihood_ratios[idx] + likelihood_ratios[symbol_set.index( + inquiry[idx])] *= subset_likelihood_ratios[idx] return likelihood_ratios def predict_proba(self, data: np.array) -> np.array: @@ -144,7 +151,8 @@ def predict_proba(self, data: np.array) -> np.array: probability for the two labels. """ if not self._ready_to_predict: - raise SignalException("must use model.fit() before model.predict_proba()") + raise SignalException( + "must use model.fit() before model.predict_proba()") # Model originally produces p(eeg | label). We want p(label | eeg): # diff --git a/bcipy/signal/model/switch_model.py b/bcipy/signal/model/switch_model.py new file mode 100644 index 000000000..4a2b64bff --- /dev/null +++ b/bcipy/signal/model/switch_model.py @@ -0,0 +1,75 @@ +"""Signal model for button presses.""" +from pathlib import Path +from typing import List + +import numpy as np + +from bcipy.core.stimuli import InquiryReshaper +from bcipy.signal.model.base_model import SignalModel +from bcipy.signal.model.inquiry_preview import compute_probs_after_preview + + +class SwitchModel(SignalModel): + """Signal model that classifies button presses. + + This is a demo model. The provided data should be comprised of ones and zeros, + where a 1 indicates a button press occurred. If a 1.0 occurs any time within + an inquiry, all symbols in the inquiry are supported and all non-inquiry symbols + are downgraded. Otherwise the opposite happens. See tests for + inquiry_preview.compute_probs_after_preview. + + Parameters + ---------- + error_prob - Specifies the probability of a button press error. + """ + + name = "SwitchModel" + reshaper: InquiryReshaper = InquiryReshaper() + + def __init__(self, error_prob: float = 0.05): + self.error_prob = error_prob + + def fit(self, training_data: np.ndarray, training_labels: np.ndarray): + """@override""" + return self + + def evaluate(self, test_data: np.ndarray, test_labels: np.ndarray): + """@override""" + + def predict(self, data: np.ndarray, inquiry: List[str], + symbol_set: List[str]) -> np.ndarray: + """@override""" + return np.ones(data.shape) + + def compute_likelihood_ratio(self, data: np.array, inquiry: List[str], + symbol_set: List[str]) -> np.array: + """For each trial in `data`, compute a likelihood ratio to update that symbol's probability. + + Args: + data (np.array): button press data data a single element of 0 or 1; shape (1,) + inquiry (List[str]): List describing the symbol shown in each trial. + symbol_set (List[str]): The set of all possible symbols. + + Returns: + np.array: multiplicative update term (likelihood ratios) for each symbol in the `symbol_set`. + """ + + proceed = np.any(data) + return compute_probs_after_preview(inquiry=inquiry, + symbol_set=symbol_set, + user_error_prob=self.error_prob, + proceed=proceed) + + def compute_class_probabilities(self, data: np.ndarray) -> np.ndarray: + """@override""" + return np.ones(0) + + def evaluate_likelihood(self, data: np.ndarray) -> np.ndarray: + """@override""" + return np.ones(0) + + def save(self, path: Path) -> None: + """@override""" + + def load(self, path: Path) -> None: + """@override""" diff --git a/bcipy/signal/process/__init__.py b/bcipy/signal/process/__init__.py index e2239aab0..0b3c62b41 100644 --- a/bcipy/signal/process/__init__.py +++ b/bcipy/signal/process/__init__.py @@ -1,8 +1,8 @@ +from bcipy.signal.process.extract_gaze import extract_eye_info from bcipy.signal.process.filter import filter_inquiries from bcipy.signal.process.transform import (Composition, Downsample, ERPTransformParams, get_default_transform) -from bcipy.signal.process.extract_gaze import extract_eye_info __all__ = [ "filter_inquiries", diff --git a/bcipy/signal/process/decomposition/cwt.py b/bcipy/signal/process/decomposition/cwt.py index 056c27333..72279c036 100644 --- a/bcipy/signal/process/decomposition/cwt.py +++ b/bcipy/signal/process/decomposition/cwt.py @@ -1,4 +1,5 @@ from typing import Tuple + import numpy as np import pywt @@ -25,7 +26,8 @@ def continuous_wavelet_transform( scales = pywt.central_frequency(wavelet) * fs / np.array(freq) all_coeffs = [] for trial in data: - coeffs, _ = pywt.cwt(trial, scales, wavelet) # shape == (scales, channels, time) + # shape == (scales, channels, time) + coeffs, _ = pywt.cwt(trial, scales, wavelet) all_coeffs.append(coeffs) final_data = np.stack(all_coeffs) diff --git a/bcipy/signal/process/decomposition/psd.py b/bcipy/signal/process/decomposition/psd.py index ddeda93da..bc326a218 100644 --- a/bcipy/signal/process/decomposition/psd.py +++ b/bcipy/signal/process/decomposition/psd.py @@ -1,12 +1,12 @@ +from enum import Enum +from typing import Tuple + import matplotlib.pyplot as plt -import seaborn as sns import numpy as np -from enum import Enum -from scipy.signal import welch -from scipy.integrate import simps +import seaborn as sns from mne.time_frequency import psd_array_multitaper - -from typing import Tuple +from scipy.integrate import simps +from scipy.signal import welch from bcipy.exceptions import SignalException diff --git a/bcipy/signal/process/extract_gaze.py b/bcipy/signal/process/extract_gaze.py index 77183565c..8516ce7ad 100644 --- a/bcipy/signal/process/extract_gaze.py +++ b/bcipy/signal/process/extract_gaze.py @@ -4,7 +4,7 @@ def extract_eye_info(data): - """"Rearrange the dimensions of gaze inquiry data and reshape it to num_channels x num_samples + """Rearrange the dimensions of gaze inquiry data and reshape it to num_channels x num_samples Extract Left and Right Eye info from data. Remove all blinks, do necessary preprocessing. The data is extracted according to the channel map: ['device_ts, 'system_ts', 'left_x', 'left_y', 'left_pupil', 'right_x', 'right_y', 'right_pupil'] @@ -16,7 +16,6 @@ def extract_eye_info(data): left_eye (np.ndarray), left_pupil (List(float)) right_eye (np.ndarray), right_pupil (List(float)) """ - # Extract samples from channels lx = data[2, :] ly = data[3, :] diff --git a/bcipy/signal/process/filter.py b/bcipy/signal/process/filter.py index daea1c95d..b58ad2100 100644 --- a/bcipy/signal/process/filter.py +++ b/bcipy/signal/process/filter.py @@ -21,7 +21,8 @@ class Bandpass: def __init__(self, lo, hi, sample_rate_hz, order=5): nyq = 0.5 * sample_rate_hz lo, hi = lo / nyq, hi / nyq - self.sos = butter(order, [lo, hi], analog=False, btype="band", output="sos") + self.sos = butter(order, [lo, hi], analog=False, + btype="band", output="sos") def __call__(self, data: np.ndarray, fs: int) -> Tuple[np.ndarray, int]: return sosfiltfilt(self.sos, data), fs @@ -38,7 +39,9 @@ def filter_inquiries(inquiries: np.ndarray, transform, sample_rate: int) -> Tupl old_shape = inquiries.shape # (Channels*Inquiry, Samples) inq_flatten = inquiries.reshape(-1, old_shape[-1]) - inq_flatten_filtered, transformed_sample_rate = transform(inq_flatten, sample_rate) + inq_flatten_filtered, transformed_sample_rate = transform( + inq_flatten, sample_rate) # (Channels, Inquiries, Samples) - inquiries = inq_flatten_filtered.reshape(*old_shape[:2], inq_flatten_filtered.shape[-1]) + inquiries = inq_flatten_filtered.reshape( + *old_shape[:2], inq_flatten_filtered.shape[-1]) return inquiries, transformed_sample_rate diff --git a/bcipy/signal/tests/evaluate/test_artifact.py b/bcipy/signal/tests/evaluate/test_artifact.py index 758dc535f..f89236a70 100644 --- a/bcipy/signal/tests/evaluate/test_artifact.py +++ b/bcipy/signal/tests/evaluate/test_artifact.py @@ -1,7 +1,10 @@ import unittest -from mockito import when, mock, unstub -from bcipy.signal.evaluate.artifact import ArtifactDetection, DefaultArtifactParameters, ArtifactType + +from mockito import mock, unstub, when + from bcipy.signal.evaluate import artifact +from bcipy.signal.evaluate.artifact import (ArtifactDetection, ArtifactType, + DefaultArtifactParameters) class TestArtifactDetection(unittest.TestCase): @@ -40,7 +43,8 @@ def tearDown(self) -> None: def test_artifact_detection_init(self): """Test the ArtifactDetection class.""" - ar = ArtifactDetection(raw_data=self.raw_data, parameters=self.parameters, device_spec=self.device_spec) + ar = ArtifactDetection( + raw_data=self.raw_data, parameters=self.parameters, device_spec=self.device_spec) self.assertIsInstance(ar, ArtifactDetection) self.assertFalse(ar.analysis_done) self.assertIsNone(ar.dropped) @@ -98,7 +102,8 @@ def test_artifact_detection_detect_artifacts(self): device_spec=self.device_spec) labels = [mock()] expected_label_response = f'{len(labels)} artifacts found in the data.' - when(ar).label_artifacts(extra_labels=ar.session_triggers).thenReturn(labels) + when(ar).label_artifacts( + extra_labels=ar.session_triggers).thenReturn(labels) response_labels, response_dropped = ar.detect_artifacts() self.assertEqual(response_labels, expected_label_response) self.assertEqual(response_dropped, 0) @@ -119,9 +124,12 @@ def test_artifact_type(self): def test_default_artifact_parameters(self): """Test the DefaultArtifactParameters class.""" - self.assertEqual(DefaultArtifactParameters.EOG_THRESHOLD.value, 5.5e-05) - self.assertEqual(DefaultArtifactParameters.VOlTAGE_LABEL_DURATION.value, 0.25) - self.assertEqual(DefaultArtifactParameters.ARTIFACT_LABELLED_FILENAME.value, 'artifacts.fif') + self.assertEqual( + DefaultArtifactParameters.EOG_THRESHOLD.value, 5.5e-05) + self.assertEqual( + DefaultArtifactParameters.VOlTAGE_LABEL_DURATION.value, 0.25) + self.assertEqual( + DefaultArtifactParameters.ARTIFACT_LABELLED_FILENAME.value, 'artifacts.fif') if __name__ == '__main__': diff --git a/bcipy/signal/tests/model/gaussian_mixture/test_gaussian_mixture.py b/bcipy/signal/tests/model/gaussian_mixture/test_gaussian_mixture.py index df373f282..41487b888 100644 --- a/bcipy/signal/tests/model/gaussian_mixture/test_gaussian_mixture.py +++ b/bcipy/signal/tests/model/gaussian_mixture/test_gaussian_mixture.py @@ -1,11 +1,8 @@ import unittest -from bcipy.signal.model.gaussian_mixture import ( - GaussianProcess, - GMCentralized, - GMIndividual, - GazeModelResolver -) +from bcipy.signal.model.gaussian_mixture import (GaussianProcess, + GazeModelResolver, + GMIndividual) class TestGazeModelResolver(unittest.TestCase): @@ -14,10 +11,6 @@ def test_resolve(self): response = GazeModelResolver.resolve('GaussianProcess') self.assertIsInstance(response, GaussianProcess) - def test_resolve_centralized(self): - response = GazeModelResolver.resolve('GMCentralized') - self.assertIsInstance(response, GMCentralized) - def test_resolve_individual(self): response = GazeModelResolver.resolve('GMIndividual') self.assertIsInstance(response, GMIndividual) @@ -33,10 +26,6 @@ def test_gaussian_process(self): model = GaussianProcess() self.assertIsInstance(model, GaussianProcess) - def test_centrailized(self): - model = GMCentralized() - self.assertIsInstance(model, GMCentralized) - def test_individual(self): model = GMIndividual() self.assertIsInstance(model, GMIndividual) diff --git a/bcipy/signal/tests/model/pca_rda_kde/test_pca_rda_kde.py b/bcipy/signal/tests/model/pca_rda_kde/test_pca_rda_kde.py index 51c62e145..0def715e4 100644 --- a/bcipy/signal/tests/model/pca_rda_kde/test_pca_rda_kde.py +++ b/bcipy/signal/tests/model/pca_rda_kde/test_pca_rda_kde.py @@ -8,10 +8,10 @@ import pytest from scipy.stats import norm +from bcipy.core.symbols import alphabet from bcipy.exceptions import SignalException -from bcipy.helpers.load import load_signal_models -from bcipy.helpers.save import save_model -from bcipy.helpers.symbols import alphabet +from bcipy.io.load import load_signal_models +from bcipy.io.save import save_model from bcipy.signal.model import ModelEvaluationReport, PcaRdaKdeModel from bcipy.signal.model.classifier import RegularizedDiscriminantAnalysis from bcipy.signal.model.cross_validation import cross_validation @@ -20,7 +20,8 @@ ChannelWisePrincipalComponentAnalysis from bcipy.signal.model.pipeline import Pipeline -expected_output_folder = Path(__file__).absolute().parent.parent / "unit_test_expected_output" +expected_output_folder = Path(__file__).absolute( +).parent.parent / "unit_test_expected_output" class ModelSetup(unittest.TestCase): @@ -37,8 +38,10 @@ def setUpClass(cls): # Generate Gaussian random data cls.pos_mean, cls.pos_std = 0, 0.5 cls.neg_mean, cls.neg_std = 1, 0.5 - x_pos = cls.pos_mean + cls.pos_std * np.random.randn(cls.num_channel, cls.num_x_pos, cls.dim_x) - x_neg = cls.neg_mean + cls.neg_std * np.random.randn(cls.num_channel, cls.num_x_neg, cls.dim_x) + x_pos = cls.pos_mean + cls.pos_std * \ + np.random.randn(cls.num_channel, cls.num_x_pos, cls.dim_x) + x_neg = cls.neg_mean + cls.neg_std * \ + np.random.randn(cls.num_channel, cls.num_x_neg, cls.dim_x) y_pos = np.ones(cls.num_x_pos) y_neg = np.zeros(cls.num_x_neg) @@ -76,7 +79,8 @@ def setUp(self): def test_pca(self): # .fit() then .transform() should match .fit_transform() - pca = ChannelWisePrincipalComponentAnalysis(n_components=0.9, num_ch=self.num_channel) + pca = ChannelWisePrincipalComponentAnalysis( + n_components=0.9, num_ch=self.num_channel) pca.fit(self.x) x_reduced = pca.transform(self.x) x_reduced_2 = pca.fit_transform(self.x) @@ -98,7 +102,8 @@ def test_kde_plot(self): """ # generate some dummy data n = 100 - x = np.concatenate((np.random.normal(0, 1, int(0.3 * n)), np.random.normal(5, 1, int(0.7 * n))))[:, np.newaxis] + x = np.concatenate((np.random.normal(0, 1, int(0.3 * n)), + np.random.normal(5, 1, int(0.7 * n))))[:, np.newaxis] # append 0 label to all data as we are interested in a single class case y = np.zeros(x.shape) @@ -107,17 +112,20 @@ def test_kde_plot(self): x_plot = np.linspace(-5, 10, 1000)[:, np.newaxis] # generate a dummy density function to sample data from - true_dens = 0.3 * norm(0, 1).pdf(x_plot[:, 0]) + 0.7 * norm(5, 1).pdf(x_plot[:, 0]) + true_dens = 0.3 * \ + norm(0, 1).pdf(x_plot[:, 0]) + 0.7 * norm(5, 1).pdf(x_plot[:, 0]) fig, ax = plt.subplots() - ax.fill(x_plot[:, 0], true_dens, fc="black", alpha=0.2, label="input distribution") + ax.fill(x_plot[:, 0], true_dens, fc="black", + alpha=0.2, label="input distribution") # try different kernels and show how the look like for kernel in ["gaussian", "tophat", "epanechnikov"]: kde = KernelDensityEstimate(kernel=kernel, scores=x, num_cls=1) kde.fit(x, y) log_dens = kde.list_den_est[0].score_samples(x_plot) - ax.plot(x_plot[:, 0], np.exp(log_dens), "-", label=f"kernel = '{kernel}'") + ax.plot(x_plot[:, 0], np.exp(log_dens), + "-", label=f"kernel = '{kernel}'") ax.plot(x[:, 0], -0.005 - 0.01 * np.random.random(x.shape[0]), "+k") @@ -126,7 +134,8 @@ def test_kde_plot(self): return fig def test_kde_values(self): - pca = ChannelWisePrincipalComponentAnalysis(n_components=0.9, num_ch=self.num_channel) + pca = ChannelWisePrincipalComponentAnalysis( + n_components=0.9, num_ch=self.num_channel) rda = RegularizedDiscriminantAnalysis() kde = KernelDensityEstimate() @@ -139,7 +148,8 @@ def test_kde_values(self): self.assertTrue(np.allclose(z, z_2)) # output values should be correct - expected = np.load(expected_output_folder / "test_kde_values.expected.npy") + expected = np.load(expected_output_folder / + "test_kde_values.expected.npy") self.assertTrue(np.allclose(z, expected)) def test_cv(self): @@ -150,7 +160,8 @@ def test_cv(self): before fitting it - it is not clear how sensitive this test is to changes in the code or input data, so this may be a weak test of cross_validation(). """ - pca = ChannelWisePrincipalComponentAnalysis(n_components=0.9, num_ch=self.num_channel) + pca = ChannelWisePrincipalComponentAnalysis( + n_components=0.9, num_ch=self.num_channel) rda = RegularizedDiscriminantAnalysis() pipeline = Pipeline([pca, rda]) @@ -160,7 +171,8 @@ def test_cv(self): self.assertAlmostEqual(gam, 0.1) def test_rda(self): - pca = ChannelWisePrincipalComponentAnalysis(n_components=0.9, num_ch=self.num_channel) + pca = ChannelWisePrincipalComponentAnalysis( + n_components=0.9, num_ch=self.num_channel) rda = RegularizedDiscriminantAnalysis() pipeline = Pipeline([pca, rda]) @@ -205,13 +217,17 @@ def test_fit_compute_likelihood_ratio(self): num_x_p = 1 num_x_n = 9 - x_test_pos = self.pos_mean + self.pos_std * np.random.randn(self.num_channel, num_x_p, self.dim_x) - x_test_neg = self.neg_mean + self.neg_std * np.random.randn(self.num_channel, num_x_n, self.dim_x) - x_test = np.concatenate((x_test_pos, x_test_neg), 1) # Target letter is first + x_test_pos = self.pos_mean + self.pos_std * \ + np.random.randn(self.num_channel, num_x_p, self.dim_x) + x_test_neg = self.neg_mean + self.neg_std * \ + np.random.randn(self.num_channel, num_x_n, self.dim_x) + # Target letter is first + x_test = np.concatenate((x_test_pos, x_test_neg), 1) letters = alp[10: 10 + num_x_p + num_x_n] # Target letter is K - lik_r = self.model.compute_likelihood_ratio(data=x_test, inquiry=letters, symbol_set=alp) + lik_r = self.model.compute_likelihood_ratio( + data=x_test, inquiry=letters, symbol_set=alp) fig, ax = plt.subplots() ax.plot(np.arange(len(alp)), lik_r, "ro") ax.set_xticks(np.arange(len(alp))) @@ -228,7 +244,8 @@ def test_save_load(self): symbol_set = alphabet() inquiry = symbol_set[:n_trial] data = np.random.randn(self.num_channel, n_trial, self.dim_x) - output_before = self.model.compute_likelihood_ratio(data=data, inquiry=inquiry, symbol_set=symbol_set) + output_before = self.model.compute_likelihood_ratio( + data=data, inquiry=inquiry, symbol_set=symbol_set) checkpoint_path = self.tmp_dir / "model.pkl" save_model(self.model, checkpoint_path) @@ -237,19 +254,22 @@ def test_save_load(self): self.assertEqual(1, len(loaded_models)) other_model = loaded_models[0] self.assertEqual(self.model.k_folds, other_model.k_folds) - output_after = other_model.compute_likelihood_ratio(data=data, inquiry=inquiry, symbol_set=symbol_set) + output_after = other_model.compute_likelihood_ratio( + data=data, inquiry=inquiry, symbol_set=symbol_set) self.assertTrue(np.allclose(output_before, output_after)) try: other_model.predict_proba(self.x) except Exception: - pytest.fail("Should be able to compute predict_proba after loading a model") + pytest.fail( + "Should be able to compute predict_proba after loading a model") def test_predict_before_fit(self): model = PcaRdaKdeModel(k_folds=10) with self.assertRaises(SignalException): - model.compute_likelihood_ratio(self.x, inquiry=["A"], symbol_set=alphabet()) + model.compute_likelihood_ratio( + self.x, inquiry=["A"], symbol_set=alphabet()) def test_evaluate_before_fit(self): model = PcaRdaKdeModel(k_folds=10) diff --git a/bcipy/signal/tests/model/rda_kde/test_rda_kde.py b/bcipy/signal/tests/model/rda_kde/test_rda_kde.py index c09e53e0c..c2b7b6177 100644 --- a/bcipy/signal/tests/model/rda_kde/test_rda_kde.py +++ b/bcipy/signal/tests/model/rda_kde/test_rda_kde.py @@ -8,16 +8,17 @@ import pytest from scipy.stats import norm -from bcipy.helpers.symbols import alphabet +from bcipy.core.symbols import alphabet +from bcipy.exceptions import SignalException from bcipy.signal.model import ModelEvaluationReport, RdaKdeModel from bcipy.signal.model.classifier import RegularizedDiscriminantAnalysis from bcipy.signal.model.cross_validation import cross_validation from bcipy.signal.model.density_estimation import KernelDensityEstimate from bcipy.signal.model.dimensionality_reduction import MockPCA from bcipy.signal.model.pipeline import Pipeline -from bcipy.exceptions import SignalException -expected_output_folder = Path(__file__).absolute().parent.parent / "unit_test_expected_output" +expected_output_folder = Path(__file__).absolute( +).parent.parent / "unit_test_expected_output" class ModelSetup(unittest.TestCase): @@ -34,8 +35,10 @@ def setUpClass(cls): # Generate Gaussian random data cls.pos_mean, cls.pos_std = 0, 0.5 cls.neg_mean, cls.neg_std = 1, 0.5 - x_pos = cls.pos_mean + cls.pos_std * np.random.randn(cls.num_channel, cls.num_x_pos, cls.dim_x) - x_neg = cls.neg_mean + cls.neg_std * np.random.randn(cls.num_channel, cls.num_x_neg, cls.dim_x) + x_pos = cls.pos_mean + cls.pos_std * \ + np.random.randn(cls.num_channel, cls.num_x_pos, cls.dim_x) + x_neg = cls.neg_mean + cls.neg_std * \ + np.random.randn(cls.num_channel, cls.num_x_neg, cls.dim_x) y_pos = np.ones(cls.num_x_pos) y_neg = np.zeros(cls.num_x_neg) @@ -78,7 +81,8 @@ def setUp(self): def test_kde_plot(self): # generate some dummy data n = 100 - x = np.concatenate((np.random.normal(0, 1, int(0.3 * n)), np.random.normal(5, 1, int(0.7 * n))))[:, np.newaxis] + x = np.concatenate((np.random.normal(0, 1, int(0.3 * n)), + np.random.normal(5, 1, int(0.7 * n))))[:, np.newaxis] # append 0 label to all data as we are interested in a single class case y = np.zeros(x.shape) @@ -87,17 +91,20 @@ def test_kde_plot(self): x_plot = np.linspace(-5, 10, 1000)[:, np.newaxis] # generate a dummy density function to sample data from - true_dens = 0.3 * norm(0, 1).pdf(x_plot[:, 0]) + 0.7 * norm(5, 1).pdf(x_plot[:, 0]) + true_dens = 0.3 * \ + norm(0, 1).pdf(x_plot[:, 0]) + 0.7 * norm(5, 1).pdf(x_plot[:, 0]) fig, ax = plt.subplots() - ax.fill(x_plot[:, 0], true_dens, fc="black", alpha=0.2, label="input distribution") + ax.fill(x_plot[:, 0], true_dens, fc="black", + alpha=0.2, label="input distribution") # try different kernels and show how the look like for kernel in ["gaussian", "tophat", "epanechnikov"]: kde = KernelDensityEstimate(kernel=kernel, scores=x, num_cls=1) kde.fit(x, y) log_dens = kde.list_den_est[0].score_samples(x_plot) - ax.plot(x_plot[:, 0], np.exp(log_dens), "-", label=f"kernel = '{kernel}'") + ax.plot(x_plot[:, 0], np.exp(log_dens), + "-", label=f"kernel = '{kernel}'") ax.plot(x[:, 0], -0.005 - 0.01 * np.random.random(x.shape[0]), "+k") @@ -177,13 +184,17 @@ def test_fit_predict(self): num_x_p = 1 num_x_n = 9 - x_test_pos = self.pos_mean + self.pos_std * np.random.randn(self.num_channel, num_x_p, self.dim_x) - x_test_neg = self.neg_mean + self.neg_std * np.random.randn(self.num_channel, num_x_n, self.dim_x) - x_test = np.concatenate((x_test_pos, x_test_neg), 1) # Target letter is first + x_test_pos = self.pos_mean + self.pos_std * \ + np.random.randn(self.num_channel, num_x_p, self.dim_x) + x_test_neg = self.neg_mean + self.neg_std * \ + np.random.randn(self.num_channel, num_x_n, self.dim_x) + # Target letter is first + x_test = np.concatenate((x_test_pos, x_test_neg), 1) letters = alp[10: 10 + num_x_p + num_x_n] # Target letter is K - lik_r = self.model.predict(data=x_test, inquiry=letters, symbol_set=alp) + lik_r = self.model.predict( + data=x_test, inquiry=letters, symbol_set=alp) fig, ax = plt.subplots() ax.plot(np.arange(len(alp)), lik_r, "ro") ax.set_xticks(np.arange(len(alp))) @@ -200,13 +211,15 @@ def test_save_load(self): symbol_set = alphabet() inquiry = symbol_set[:n_trial] data = np.random.randn(self.num_channel, n_trial, self.dim_x) - output_before = self.model.predict(data=data, inquiry=inquiry, symbol_set=symbol_set) + output_before = self.model.predict( + data=data, inquiry=inquiry, symbol_set=symbol_set) checkpoint_path = self.tmp_dir / "model.pkl" self.model.save(checkpoint_path) other_model = RdaKdeModel(k_folds=self.model.k_folds) other_model.load(checkpoint_path) - output_after = other_model.predict(data=data, inquiry=inquiry, symbol_set=symbol_set) + output_after = other_model.predict( + data=data, inquiry=inquiry, symbol_set=symbol_set) self.assertTrue(np.allclose(output_before, output_after)) diff --git a/bcipy/signal/tests/model/test_inquiry_preview.py b/bcipy/signal/tests/model/test_inquiry_preview.py index 9b506b160..2e2696079 100644 --- a/bcipy/signal/tests/model/test_inquiry_preview.py +++ b/bcipy/signal/tests/model/test_inquiry_preview.py @@ -1,40 +1,86 @@ import unittest +from string import ascii_uppercase + import numpy as np + from bcipy.signal.model.inquiry_preview import compute_probs_after_preview -from string import ascii_uppercase class TestInquiryPreview(unittest.TestCase): + """Test button press probabilities under various conditions.""" + def setUp(self): self.symbol_set = list(ascii_uppercase) + self.error_prob = 0.05 - def _test(self, inquiry_len, error_prob, user_likes: bool): - if user_likes: - p_shown = 1 - error_prob - p_not_shown = error_prob - else: - p_shown = error_prob - p_not_shown = 1 - error_prob - - inquiry = self.symbol_set[:inquiry_len] - results = compute_probs_after_preview(inquiry, self.symbol_set, error_prob, user_likes) + def test_user_likes_short_inquiry(self): + """Test short inquiry where user wants to proceed with the inquiry. + Should provide support for symbols in inquiry and downvote others.""" - expected = np.array(inquiry_len * [p_shown] + (len(self.symbol_set) - inquiry_len) * [p_not_shown]) + inquiry = ['A', 'B', 'C', 'D', 'E'] + user_likes = True + expected = [ + 0.95, 0.95, 0.95, 0.95, 0.95, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, + 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, + 0.05, 0.05, 0.05, 0.05 + ] + results = compute_probs_after_preview(inquiry, self.symbol_set, + self.error_prob, user_likes) self.assertTrue(np.allclose(results, expected)) - def test_user_likes_short_inquiry(self): - self._test(5, 0.95, True) - def test_user_likes_long_inquiry(self): - self._test(15, 0.95, True) + """Test long inquiry where user wants to proceed with the inquiry.""" + inquiry = [ + 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', + 'N', 'O' + ] + expected = [ + 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, + 0.95, 0.95, 0.95, 0.95, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, + 0.05, 0.05, 0.05, 0.05 + ] + results = compute_probs_after_preview(inquiry, + self.symbol_set, + self.error_prob, + proceed=True) + + self.assertTrue(np.allclose(results, expected)) def test_user_dislikes_short_inquiry(self): - self._test(5, 0.95, False) + """Test probabilities for short inquiry where user does not want to proceed. + Should downvote letters in the inquiry and upvote everything else.""" + + inquiry = ['A', 'B', 'C', 'D', 'E'] + expected = [ + 0.05, 0.05, 0.05, 0.05, 0.05, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, + 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, + 0.95, 0.95, 0.95, 0.95 + ] + results = compute_probs_after_preview(inquiry, + self.symbol_set, + self.error_prob, + proceed=False) + self.assertTrue(np.allclose(results, expected)) def test_user_dislikes_long_inquiry(self): - self._test(15, 0.95, False) + """Test probabilities for long inquiry where user does not want to proceed.""" + inquiry = [ + 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', + 'N', 'O' + ] + expected = [ + 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, + 0.05, 0.05, 0.05, 0.05, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, + 0.95, 0.95, 0.95, 0.95 + ] + results = compute_probs_after_preview(inquiry, + self.symbol_set, + self.error_prob, + proceed=False) + self.assertTrue(np.allclose(results, expected)) def test_invalid_error_prob(self): + """Test error probability out of range""" inquiry = self.symbol_set[:10] with self.assertRaises(ValueError): compute_probs_after_preview(inquiry, self.symbol_set, -0.01, True) diff --git a/bcipy/signal/tests/model/test_offline_analysis.py b/bcipy/signal/tests/model/test_offline_analysis.py index 5f0a8502c..bad8ad5cf 100644 --- a/bcipy/signal/tests/model/test_offline_analysis.py +++ b/bcipy/signal/tests/model/test_offline_analysis.py @@ -1,22 +1,25 @@ """Integration test of offline_analysis.py (slow)""" -import unittest -from pathlib import Path -import pytest +import gzip +import random +import re import shutil import tempfile -import re +import unittest +from pathlib import Path + import numpy as np -import random -import gzip +import pytest -from bcipy.config import RAW_DATA_FILENAME, DEFAULT_PARAMETERS_FILENAME, TRIGGER_FILENAME, DEFAULT_DEVICE_SPEC_FILENAME -from bcipy.helpers.load import load_json_parameters -from bcipy.signal.model import SignalModel +from bcipy.config import (DEFAULT_DEVICE_SPEC_FILENAME, + DEFAULT_PARAMETERS_FILENAME, RAW_DATA_FILENAME, + TRIGGER_FILENAME) +from bcipy.io.load import load_json_parameters from bcipy.signal.model.offline_analysis import offline_analysis pwd = Path(__file__).absolute().parent input_folder = pwd / "integration_test_input" -expected_output_folder = pwd / "integration_test_expected_output" # global for the purpose of pytest-mpl decorator +# global for the purpose of pytest-mpl decorator +expected_output_folder = pwd / "integration_test_expected_output" @pytest.mark.slow @@ -46,10 +49,13 @@ def setUpClass(cls): shutil.copyfileobj(f_source, f_dest) # copy the other required inputs into tmp_dir - shutil.copyfile(eeg_input_folder / TRIGGER_FILENAME, cls.tmp_dir / TRIGGER_FILENAME) - shutil.copyfile(eeg_input_folder / DEFAULT_DEVICE_SPEC_FILENAME, cls.tmp_dir / DEFAULT_DEVICE_SPEC_FILENAME) + shutil.copyfile(eeg_input_folder / TRIGGER_FILENAME, + cls.tmp_dir / TRIGGER_FILENAME) + shutil.copyfile(eeg_input_folder / DEFAULT_DEVICE_SPEC_FILENAME, + cls.tmp_dir / DEFAULT_DEVICE_SPEC_FILENAME) - params_path = pwd.parent.parent.parent / "parameters" / DEFAULT_PARAMETERS_FILENAME + params_path = pwd.parent.parent.parent / \ + "parameters" / DEFAULT_PARAMETERS_FILENAME cls.parameters = load_json_parameters(params_path, value_cast=True) models = offline_analysis( str(cls.tmp_dir), @@ -72,8 +78,10 @@ def get_auc(model_filename): return float(match[1]) def test_model_auc(self): - expected_auc = self.get_auc(list(expected_output_folder.glob("model_eeg_*.pkl"))[0].name) - found_auc = self.get_auc(list(self.tmp_dir.glob("model_eeg_*.pkl"))[0].name) + expected_auc = self.get_auc( + list(expected_output_folder.glob("model_eeg_*.pkl"))[0].name) + found_auc = self.get_auc( + list(self.tmp_dir.glob("model_eeg_*.pkl"))[0].name) self.assertAlmostEqual(expected_auc, found_auc, delta=0.005) def test_model_metadata_loads(self): @@ -109,14 +117,16 @@ def setUpClass(cls): shutil.copyfileobj(f_source, f_dest) # copy the other required inputs into tmp_dir - shutil.copyfile(eye_tracking_input_folder / TRIGGER_FILENAME, cls.tmp_dir / TRIGGER_FILENAME) + shutil.copyfile(eye_tracking_input_folder / + TRIGGER_FILENAME, cls.tmp_dir / TRIGGER_FILENAME) shutil.copyfile( eye_tracking_input_folder / DEFAULT_DEVICE_SPEC_FILENAME, cls.tmp_dir / DEFAULT_DEVICE_SPEC_FILENAME) - params_path = pwd.parent.parent.parent / "parameters" / DEFAULT_PARAMETERS_FILENAME + params_path = pwd.parent.parent.parent / \ + "parameters" / DEFAULT_PARAMETERS_FILENAME cls.parameters = load_json_parameters(params_path, value_cast=True) models = offline_analysis( str(cls.tmp_dir), @@ -142,8 +152,10 @@ def get_acc(model_filename): return float(match[1]) def test_model_acc(self): - expected_auc = self.get_acc(list(expected_output_folder.glob("model_eyetracker_*.pkl"))[0].name) - found_auc = self.get_acc(list(self.tmp_dir.glob("model_eyetracker_*.pkl"))[0].name) + expected_auc = self.get_acc( + list(expected_output_folder.glob("model_eyetracker_*.pkl"))[0].name) + found_auc = self.get_acc( + list(self.tmp_dir.glob("model_eyetracker_*.pkl"))[0].name) self.assertAlmostEqual(expected_auc, found_auc, delta=0.005) @@ -182,10 +194,13 @@ def setUpClass(cls): shutil.copyfileobj(f_source, f_dest) # copy the other required inputs into tmp_dir - shutil.copyfile(et_input_folder / TRIGGER_FILENAME, cls.tmp_dir / TRIGGER_FILENAME) - shutil.copyfile(fusion_input_folder / DEFAULT_DEVICE_SPEC_FILENAME, cls.tmp_dir / DEFAULT_DEVICE_SPEC_FILENAME) + shutil.copyfile(et_input_folder / TRIGGER_FILENAME, + cls.tmp_dir / TRIGGER_FILENAME) + shutil.copyfile(fusion_input_folder / DEFAULT_DEVICE_SPEC_FILENAME, + cls.tmp_dir / DEFAULT_DEVICE_SPEC_FILENAME) - params_path = pwd.parent.parent.parent / "parameters" / DEFAULT_PARAMETERS_FILENAME + params_path = pwd.parent.parent.parent / \ + "parameters" / DEFAULT_PARAMETERS_FILENAME cls.parameters = load_json_parameters(params_path, value_cast=True) models = offline_analysis( str(cls.tmp_dir), @@ -220,13 +235,17 @@ def get_auc(model_filename): return float(match[1]) def test_model_acc(self): - expected_auc = self.get_acc(list(self.output_folder.glob("model_eyetracker_*.pkl"))[0].name) - found_auc = self.get_acc(list(self.tmp_dir.glob("model_eyetracker_*.pkl"))[0].name) + expected_auc = self.get_acc( + list(self.output_folder.glob("model_eyetracker_*.pkl"))[0].name) + found_auc = self.get_acc( + list(self.tmp_dir.glob("model_eyetracker_*.pkl"))[0].name) self.assertAlmostEqual(expected_auc, found_auc, delta=0.005) def test_model_auc(self): - expected_auc = self.get_auc(list(self.output_folder.glob("model_eeg_*.pkl"))[0].name) - found_auc = self.get_auc(list(self.tmp_dir.glob("model_eeg_*.pkl"))[0].name) + expected_auc = self.get_auc( + list(self.output_folder.glob("model_eeg_*.pkl"))[0].name) + found_auc = self.get_auc( + list(self.tmp_dir.glob("model_eeg_*.pkl"))[0].name) self.assertAlmostEqual(expected_auc, found_auc, delta=0.005) diff --git a/bcipy/signal/tests/model/test_switch_model.py b/bcipy/signal/tests/model/test_switch_model.py new file mode 100644 index 000000000..7ae9943b9 --- /dev/null +++ b/bcipy/signal/tests/model/test_switch_model.py @@ -0,0 +1,71 @@ +"""Tests for Button Press Model""" +import unittest +from string import ascii_uppercase + +import numpy as np + +from bcipy.signal.model.switch_model import SwitchModel + + +class SwitchModelTest(unittest.TestCase): + """Tests for Switch Model.""" + + def setUp(self): + """Override; set up model.""" + self.model = SwitchModel() + self.symbol_set = list(ascii_uppercase) + + def test_all_positive_inquiry(self): + """Test model results when the data indicates that the inquiry should + be supported. All inquiry symbols have value of 1.0""" + inquiry = ['A', 'B', 'C', 'D', 'E'] + + expected = [ + 0.95, 0.95, 0.95, 0.95, 0.95, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, + 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, + 0.05, 0.05, 0.05, 0.05 + ] + results = self.model.compute_likelihood_ratio( + data=np.array([1.0, 1.0, 1.0, 1.0, 1.0]), + inquiry=inquiry, + symbol_set=self.symbol_set) + + self.assertTrue(np.allclose(results, expected)) + + def test_any_positive_inquiry(self): + """Test model results when the data indicates that the inquiry should + be supported. Some inquiry symbols have value of 1.0""" + inquiry = ['A', 'B', 'C', 'D', 'E'] + + expected = [ + 0.95, 0.95, 0.95, 0.95, 0.95, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, + 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, + 0.05, 0.05, 0.05, 0.05 + ] + results = self.model.compute_likelihood_ratio( + data=np.array([0.0, 1.0, 0.0, 0.0, 0.0]), + inquiry=inquiry, + symbol_set=self.symbol_set) + + self.assertTrue(np.allclose(results, expected)) + + def test_all_negative_inquiry(self): + """Test model results when the data indicates that the inquiry symbols + should be downgraded. All inquiry symbols have value of 0.0""" + inquiry = ['A', 'B', 'C', 'D', 'E'] + + expected = [ + 0.05, 0.05, 0.05, 0.05, 0.05, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, + 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, 0.95, + 0.95, 0.95, 0.95, 0.95 + ] + results = self.model.compute_likelihood_ratio( + data=np.array([0.0, 0.0, 0.0, 0.0, 0.0]), + inquiry=inquiry, + symbol_set=self.symbol_set) + + self.assertTrue(np.allclose(results, expected)) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/signal/tests/process/decomposition/resources/data.txt b/bcipy/signal/tests/process/decomposition/resources/data.txt deleted file mode 100644 index a0e031dfc..000000000 --- a/bcipy/signal/tests/process/decomposition/resources/data.txt +++ /dev/null @@ -1,3000 +0,0 @@ --31.140106818529 --29.307741130369 --27.702282955172 --24.823603667431 --19.734471382648 --17.468192604636 --16.524288084323 --15.436249764616 --13.459321158283 --9.690314296181 --7.307730549914 --8.545384193233 --11.804049880313 --16.310102779910 --20.104006874542 --21.868478624425 --17.557436342863 --10.063806086243 --5.038226597238 --1.185631607446 --0.587361308779 --0.961864470934 --1.789073380698 --6.129384837605 --8.641557776034 --6.205573570806 --6.692657213358 --12.213464085439 --15.764797460062 --20.123516002134 --27.929091718619 --36.505209574756 --41.478517637308 --43.718818126428 --45.025099911649 --44.323620651527 --41.311648607131 --33.783861483749 --25.403725927537 --15.696230341103 --4.702594566959 -5.355401722362 -15.613833823884 -23.062460090029 -28.096303307686 -30.940777856961 -30.644399684298 -26.519428522975 -23.085737909361 -20.213538043938 -19.272518585244 -24.617422754158 -32.579435447261 -35.725371077029 -29.088735703706 -18.344268950794 -11.493204512504 -8.252775851866 -6.840521104964 -9.632266473454 -16.607591569580 -20.997855793232 -16.795443551340 -9.602882275213 -3.110269688376 --0.340963517374 -4.841492623433 -14.760031447745 -21.630444392455 -21.351651923807 -19.234474249513 -21.003662095448 -25.441189705328 -31.832842966007 -36.523339386723 -33.053330197342 -24.123280547134 -13.369527805867 -4.503585690492 -0.907139057466 -2.540654127280 -8.745471700621 -10.656130158154 -5.623289380366 --0.094589863484 --3.273801325080 -0.793055052185 -7.296196855427 -17.824677755474 -33.200767249055 -34.907894737314 -22.957640141157 -9.278611769433 -4.182238673060 -6.752511645711 -5.972221857576 -8.281264944609 -13.155805076988 -10.025888754374 -1.687967347298 --4.223957792484 --2.493489446595 -2.279432153643 -8.922329645685 -20.961865550818 -26.244550696437 -21.649465055864 -13.981905522757 -3.612665791221 --3.499616385242 --2.869102882887 -4.952067314497 -13.048812285193 -13.074760665869 -11.095524145646 -7.313011618855 -3.309045210393 -3.551172851359 -6.923389720151 -15.419901078019 -21.622026278577 -20.824441042981 -17.426907956055 -15.051889453992 -15.636247877738 -16.078979934864 -19.151137894970 -25.894087875206 -32.114887781770 -33.529162537978 -28.892622920833 -21.461004390326 -14.642536984379 -7.438455023146 -2.605609508836 -3.410878515912 -7.083397931407 -7.468005585724 -3.230316968095 -2.328353415645 -6.799487081663 -14.800850750319 -23.756457363007 -30.548887444408 -30.205670487929 -28.066857560793 -25.742237773949 -19.058549260832 -8.865875041217 --1.883476836099 --6.534460711100 --7.099114527734 --7.563694896604 --10.382117320263 --17.602463642803 --25.352144820169 --29.968557737270 --31.639773503831 --28.336921109635 --20.330662868728 --10.179147662715 --3.310747982867 --1.292238354418 --4.196465879747 --11.592746034306 --20.183733148692 --28.200050410521 --29.866715509571 --23.804995807513 --17.444774168194 --12.475665287605 --6.965693391124 --0.461889722216 -4.067858831687 -3.903132962499 -2.763821415865 --0.273903347736 --5.301916633918 --10.180384149938 --11.741873093507 --9.950949339124 --8.934492775701 --8.885409860088 --11.492281572357 --13.310589417356 --14.714772063537 --15.280463772897 --16.001352212712 --16.110723415967 --8.854797639050 --4.355340228339 --4.227481559151 --0.222962228061 -1.970985641614 -0.540261882705 -0.265908995723 -1.948284834074 -1.281406353672 --2.890944518253 --3.956615370837 -0.205493791105 -8.212951739775 -12.522073826799 -12.501785233796 -14.970568883440 -12.206322108035 -9.041902232023 -8.320501241198 -6.367354532237 -6.586350682193 -4.947366614834 --0.324663767111 --6.941679178216 --11.179382121139 --9.981813044065 --8.768751635892 --9.408826859020 --9.279967876327 --8.557363034911 --10.388786673619 --13.812744336133 --12.362237077354 --10.579723017667 --9.799679389631 --10.217619575777 --12.789466057414 --12.876966271070 --11.625508811031 --11.009083883019 --8.867974917789 --4.874928792984 --3.163482919520 --4.064510174786 --6.915018112907 --12.535145856007 --18.044038868081 --20.833330055072 --19.094067191593 --16.126016969085 --13.243832184486 --11.228586021106 --14.207585515638 --16.296867139129 --12.693058250358 --7.089432732231 --1.749072916845 --1.066061463990 --3.707409785366 --6.083672136028 --8.576375994921 --7.460806678430 --6.132165169048 --4.886594233454 -0.042284746579 -8.458589812942 -12.549320251474 -6.467655571015 --4.867601846212 --14.386347104183 --19.854276615730 --23.420105644903 --25.485020939929 --23.755448224980 --19.213189224837 --16.953661993874 --17.170112725426 --18.709391222819 --19.920571893714 --17.948994762656 --11.546031006454 --3.688548406790 -2.587719707677 -6.433263867904 -6.886754539912 -6.724272713696 -4.199739966218 --0.327242076791 --2.517482332667 --5.797193236276 --5.786881383597 -2.292870121993 -7.464230447538 -6.407149252086 -2.209521117210 -2.010720985908 -3.328188861442 -0.747697891466 --3.415374972413 --4.679255608677 -4.228165589975 -11.213773114423 -11.863823512569 -15.744309634800 -18.577219595336 -17.022149916257 -12.306310189732 -9.548971430891 -8.195688720500 -5.573387861634 -3.838952232344 -1.831052330206 --0.583726978651 --1.292351424753 --3.353060814326 --2.505360322641 -0.285329178398 -3.033809498828 -8.908017819510 -13.694698027018 -17.085444129552 -20.885498173143 -23.153581308250 -21.056752318106 -15.154526784545 -10.157158397921 -6.532381355994 -4.927690861469 -6.604991318622 -7.810158390709 -5.253315090514 --2.610931125264 --13.115758466688 --21.972527083647 --27.678155572977 --31.271937715348 --35.479901988379 --35.886062595437 --33.816917642419 --31.304416772174 --27.601671332084 --27.117014105994 --27.539507224056 --25.080226272815 --22.291402458058 --17.373771324287 --11.379833108335 --9.078938162004 --13.610178351369 --21.534406832153 --25.221705323977 --25.925383250979 --24.353396825930 --20.951021144466 --18.151830613783 --14.806642704609 --13.771465376433 --17.562832506590 --20.761683718172 --18.273766425900 --12.229202180518 --8.687446763945 --8.588254958785 --9.968822067385 --14.092003831524 --20.715515324313 --28.007364425746 --32.452163886223 --31.684640541363 --27.165663468021 --19.786910599435 --10.347907786964 -1.227933753611 -11.460635725431 -15.458932927223 -18.544216516614 -26.687545846506 -36.311895306584 -40.966412464607 -43.097481870365 -48.004035172682 -51.230881339929 -48.897560460568 -47.345621322548 -47.516322813136 -50.030417554063 -51.688989893364 -51.895025965735 -51.047777370793 -45.936212707247 -39.692759424760 -35.770462509110 -34.111215254985 -32.662645316305 -29.824654745557 -26.395094646743 -22.520401092533 -16.782345902559 -11.641846563997 -9.103724936624 -10.388717286045 -12.169137420689 -13.086437232818 -16.401199906091 -17.146887956533 -14.487837565776 -14.904319690298 -20.670023760731 -25.104337229069 -27.827127450083 -32.566566189372 -34.637270206290 -29.854663533076 -20.253870120313 -13.761055226447 -16.291026527627 -19.574280226094 -20.652231339676 -24.628967501890 -25.174936960689 -18.093875873220 -10.607493000624 -7.737964271693 -5.850638874082 --0.313657711797 --7.462916609292 --10.853282374931 --13.654275808219 --18.661248110758 --24.196153952064 --26.831382336009 --27.638072569773 --28.382462985477 --24.930505468423 --19.198484450488 --14.547370347508 --12.552015498853 --12.966047665019 --13.460823782639 --13.668069419543 --14.278785360499 --16.968639224917 --18.727508476154 --16.286464860766 --12.137813384648 --8.994088851808 --5.861304593577 --4.961658574620 --7.174582165242 --11.288207471896 --12.402098849141 --7.583742732696 -0.184196692982 -6.884912421137 -10.499633307270 -10.731071826377 -7.017718580962 --0.267335098172 --9.207977856936 --14.554583265369 --15.961708212712 --12.042302297738 --4.279225327634 -4.616424553672 -11.161687918112 -11.898782921539 -10.754345104190 -8.376532429853 -5.503326507021 -6.161674987798 -9.781467443758 -13.350635478044 -13.401044149481 -11.182015589198 -8.826404724527 -10.789753459380 -11.972338686802 -8.682258131331 -7.492936924643 -6.284881149742 -6.472066060459 -8.036183138380 -9.924708742914 -14.976107598937 -18.141699844216 -15.080536501248 -6.110205416452 --2.808034296912 --7.294937462239 --7.132611225539 --1.908138954385 -6.702669394209 -16.797926244814 -19.821451029304 -9.994553762783 -4.137606856230 -5.758362817348 -9.339275495772 -8.829400539709 -4.608437018354 -7.863592621677 -7.931989530312 -2.682375290776 -1.442220013788 -1.262426106963 -2.106538279924 --1.967774295785 --9.326304850882 --16.169039939590 --24.405888021763 --24.722042539869 --20.471486489527 --14.658243737348 --8.602645031407 --6.359516278830 --3.943586733231 --5.512043682784 --8.942406691366 --9.747791230548 --9.420399660295 --8.281375698802 --8.672920135613 --12.806263218633 --20.968233623536 --30.481863797263 --36.575992247144 --39.697987348199 --37.580542106794 --33.710365287447 --34.204534562751 --39.149502604998 --41.066772080000 --35.054068787258 --27.142084175862 --19.871928131663 --12.491483501457 --11.516537729154 --18.636316243738 --27.230736016745 --31.209443769069 --28.423401873302 --20.600361572398 --10.670488081549 --4.015585769365 --5.712185639138 --14.736982049404 --23.665273340618 --26.729239698611 --24.945312820033 --20.595058749951 --14.267702194011 --8.385943188430 --4.776521707317 -2.203540466139 -10.464418296617 -15.282415862590 -17.656747428436 -17.784625330719 -16.424478254609 -15.719422782058 -16.904519504941 -16.824452204408 -14.756323316850 -11.945854761442 -7.675270996151 -4.661583386066 -3.445179580242 -1.516883723548 -0.046734361577 -1.122708854364 -3.682492121153 -1.577077681671 --3.634908010113 --5.103253571860 --6.393998222910 --8.270707942433 --7.120200326854 --4.999191222904 --5.390301542260 --5.973270256502 --3.028179703287 -2.397934908809 -6.575257804473 -8.389397142082 -7.429382877552 -3.654475822972 --3.453562962910 --8.430727534000 --9.114235803380 --8.898855601918 --5.976488875541 --1.925259053963 -5.186627283451 -10.154049117094 -7.836496802187 -7.777247736772 -10.733982218460 -13.454805379087 -17.921074539626 -21.154232711911 -27.223245115325 -34.195547069595 -35.909957082395 -36.282493144052 -33.061042661427 -26.818472861394 -19.185544802114 -15.614789795446 -14.248820066985 -11.424054198465 -13.533006405364 -17.871524708527 -19.336305335001 -19.733267854278 -21.605847807143 -28.532765843357 -31.477068278194 -27.484807602747 -24.622614743703 -26.470480512646 -27.115458519113 -19.839374565982 -15.751258437179 -16.379748053538 -15.882481500336 -18.604756126054 -26.827394253313 -34.423905248471 -36.629808737949 -36.526205344029 -30.823608055352 -18.828042438402 -9.435627734774 -7.663528616140 -12.073654764564 -17.216383248075 -23.243932434485 -28.082794727269 -25.649454270472 -16.938025682106 -6.486208692967 --0.386748482178 --5.317214596046 --8.258575961835 --11.930451082234 --17.820679885547 --24.972288696650 --32.263679408082 --36.842734941932 --38.690841419332 --36.271003291676 --34.101998561375 --33.368490357923 --33.786775037754 --39.857213582311 --43.381475705128 --40.402592342495 --34.997439842424 --27.871011683696 --20.177564202984 --12.652401736997 --8.220492549242 --4.302799123162 -0.617429149840 -2.189085267789 -0.200130408912 --4.422499792895 --8.900495881229 --10.558679041278 --7.616367212559 --2.090494062790 -1.874514406999 -3.204689528562 -1.109395642330 --3.842139226911 --7.102946047410 --6.377187782819 --4.288707760574 --2.534456270848 --3.790873851731 --7.880165614516 --13.702864751880 --20.856961719727 --26.499566675294 --28.362313730593 --24.156921867596 --17.604186040554 --13.724574463555 --13.270779054840 --15.013149909452 --16.470628513982 --19.145685777778 --20.003622013017 --20.036712999882 --23.124927001907 --22.860935093004 --23.031506719383 --25.011255795706 --25.265395458836 --25.298851082440 --18.661575043103 --13.306550097688 --13.987903006635 --10.231315765926 --6.642797656371 --6.069989652224 --8.774245287719 --10.018020413851 --8.157934302415 --9.727958583291 --10.117520568304 --10.593112707482 --13.752943013078 --16.530781000747 --18.452271558597 --14.737156464583 --13.541592407428 --15.022029787332 --10.478329059526 --6.565063725149 --6.540420898586 --10.580718132909 --14.894536694088 --14.874097981411 --14.934141307996 --14.015990125241 --9.327721051038 --5.267955354363 --4.579856005712 --6.943550358035 --10.309265795030 --12.945927258540 --13.654388708353 --11.928110514498 --7.368947721618 -0.694064034404 -9.566210021009 -12.284348692765 -8.450906773324 -4.247454572176 -1.370951253398 -0.177901052635 -0.072744986480 -1.977496947734 -6.817169736630 -13.800754705364 -18.067997828342 -18.149716942978 -20.188386989707 -22.520475564516 -22.930613213001 -25.239683985651 -29.006809461904 -32.369612930632 -32.692660398860 -31.058628549496 -26.081713658830 -16.776215716295 -9.797786962635 -5.990942246427 -4.093845984468 -3.407258749536 -4.766173158866 -4.719429282346 -2.009305397062 -1.872896764404 -4.218019823748 -8.216535792275 -13.246299807146 -19.897838445458 -28.035315658326 -32.906969316258 -33.293934845680 -33.289479893144 -34.673206617598 -37.483040787605 -40.922946109986 -43.636538177393 -44.310028152253 -41.409761665982 -36.087231869251 -30.454548175608 -26.821592772461 -28.310090374098 -30.370738808730 -28.030425398948 -22.221660436865 -19.613760512851 -21.151776952132 -22.311867698766 -21.673577510421 -18.138243196893 -15.923931748872 -13.529770732895 -5.513843383437 --1.810548346937 --7.717952280210 --13.361306088201 --15.069441474947 --12.341739814863 --4.415655756433 -0.784885300698 --0.007508571505 -1.339755617490 -4.424802280928 -5.597864023130 -6.107836627051 -10.280094840943 -17.677953688944 -22.374683500799 -24.131566745779 -25.360483295757 -24.959649667117 -23.899407548009 -20.104572298611 -15.784103655778 -11.120347072084 -3.146368987470 --1.962721536150 --4.251558531113 --6.917435838447 --9.932171268679 --11.501466034991 --11.986889553518 --13.849096662497 --14.092675176145 --13.051668268051 --7.816614510022 --4.285754445727 --7.644241697820 --11.480644771767 --16.125458445620 --19.497881079369 --18.638026279402 --15.123334539750 --9.421664864076 --3.614354896671 --0.032610246195 -0.272953988929 --4.830302684941 --9.717518621554 --11.855813131282 --13.113602403075 --11.068879492819 --5.637299373040 --2.637103797668 --3.054759421355 --5.596556643602 --9.819274657115 --13.620686017820 --15.563376114415 --15.036335219611 --14.542221949924 --14.303845240707 --16.692285286864 --17.877590894966 --18.890653574786 --20.955003037873 --20.349431936341 --17.746185196585 --13.056262513460 --5.318337675838 -3.967105626065 -6.802748614825 -0.683940019121 --2.491053322305 --1.435296674505 --2.284438023556 --5.546223144779 --9.904203872762 --11.922822738265 --13.220438694435 --14.432018729158 --13.129658139136 --9.093348164951 --4.441482900054 --0.364366219455 -0.175180375071 --5.827611299471 --14.761175965684 --21.675685121614 --26.440517158685 --28.221842042932 --27.408744942624 --25.068978505237 --20.307896956336 --18.988039403358 --16.724013373740 --11.612866008917 --11.623650749677 --12.894057651785 --13.628593534693 --11.528330076442 --7.216089437814 --10.464312824311 --11.294052100253 --5.224293066618 --3.988046388238 --5.955092596469 --3.906976526140 -4.760620016892 -10.900844825477 -10.285707414399 -9.964726131483 -9.395602628874 -8.948885055333 -8.660307110118 -10.518168035012 -15.718511261626 -18.551770035303 -18.788376539821 -16.386341833248 -11.729232205805 -6.497774000279 --0.145903083501 --4.414985741022 --9.633510702685 --16.557833813647 --15.123767127260 --8.368992574641 --5.868625066207 --5.139692007684 --0.615748972458 -4.979851863918 -10.286699236256 -16.518191680933 -19.238013901409 -15.672712129221 -9.343773254612 -3.136906229200 --1.915844802779 --6.374366991118 --6.634730315530 --1.148731064251 -4.747621614272 -8.020691877515 -6.924132722879 -5.207273525142 -4.738594135442 -2.328781562512 -2.563952509783 -5.720490657212 -9.170952549096 -12.192375780565 -11.709506122491 -11.394655509579 -10.755404709757 -9.550498357613 -11.152531156875 -13.723686002629 -18.322658359192 -23.199662385435 -25.828582054580 -28.196603687718 -27.267083661715 -25.989263034208 -24.906257590596 -24.297920812961 -25.599778585931 -23.370433260461 -18.851065200958 -13.920735167742 -10.221599943363 -6.964483752519 -4.574914249041 -1.480936609268 --3.141370601333 --5.801139146112 --6.576818171214 --3.932563924667 -1.047778262915 -5.683726622549 -12.515501805571 -17.356121839033 -19.128556463362 -19.927017404473 -17.311011728752 -14.788704401989 -13.957099188584 -11.724524774521 -9.520929894809 -10.000105620909 -7.418179340568 -0.506719687046 --5.382858555356 --8.175570732431 --9.597649418679 --10.477639518018 --10.398461413717 --6.679076354978 --0.353218192204 -4.606706143918 -7.856432399023 -8.957566890527 -6.584572859840 -6.372209919288 -6.348921693548 --0.098533808991 --7.612943955089 --13.782798122646 --13.466339082531 --10.725341270677 --14.176220139522 --15.430918673924 --15.031051339553 --17.163453804030 --19.393936440396 --20.051451971413 --18.372590489970 --20.059928743128 --22.987194079688 --25.273138981233 --30.924533981343 --35.777956130058 --41.986250234118 --44.544779479828 --45.329412164750 --45.717957667899 --40.627660875594 --35.953948319606 --33.725258263837 --37.259478094919 --41.417021688712 --36.626038044838 --25.510287847273 --13.723965825306 --2.493020203263 -3.323084686492 -1.344107487242 --4.695536302196 --12.385478791495 --20.184235445759 --22.496743161443 --16.675351204735 --6.236942528745 -2.390186331352 -6.079598791267 -8.923295395944 -7.089170276781 -0.473899909838 --4.303868526738 --8.536224172814 --11.195457073263 --13.743070372934 --16.901493866305 --14.903749526862 --11.117450598386 --9.935909160545 --7.673126931117 --3.676774884488 --0.982059954940 -0.935073964142 --0.893041374371 --5.098240719035 --10.164968802864 --14.202604322327 --12.355902222012 --7.970451558762 --2.793910054714 --1.000225596420 -2.567446005201 -5.496783000534 -2.262196954481 -2.593877980857 -3.614568819378 -4.651455677933 -6.393450335858 -4.445662659024 -5.169113560344 -8.624691207574 -12.490501606921 -13.518868074005 -8.972005839528 -1.101606680808 --6.119172964820 --7.255564606233 --2.093561198482 -4.876352307846 -11.145676778578 -15.225698992442 -12.587514907281 -5.164599690392 --3.280493863296 --7.983362352486 --10.675878689478 --13.520284396945 --13.687157307164 --10.311124098504 --8.648236628182 --11.277645200098 --12.748802248287 --13.346385250407 --11.087611021965 --6.896074235661 --7.113784065594 --4.714594250338 -2.187078120005 -4.750145512221 -2.382191120188 --2.112512115216 --0.950804601058 -1.865891019579 -1.824632225357 -2.812293544224 --0.273853377627 --4.840245620099 --8.025617189487 --8.725713370319 --5.531460572084 --4.565015150397 --2.364856759151 -3.433793962447 -8.534243254744 -12.673659726510 -13.619420351250 -14.428320886188 -13.089236750951 -6.592171574785 -6.949449830538 -14.753671539660 -23.670554433443 -28.293757348789 -26.061432892823 -23.192074562309 -22.963659068978 -26.240491095696 -28.562710336987 -28.523141264713 -28.198264153104 -25.380676108706 -18.945058629425 -6.400300502624 --6.114743269971 --11.264155464066 --8.917584248238 --2.657277552589 -3.922228586159 -10.122319637841 -15.927943056873 -18.992456304281 -18.026210486227 -18.612379445434 -17.411948350679 -15.036168151281 -14.526814271312 -16.995090028431 -21.627151791868 -21.796813888411 -16.902745195752 -11.277206005732 -6.916861055417 -1.524640585046 --3.597090404064 --4.029201565445 -0.290328757717 -6.890928717696 -14.290310330133 -17.464293641301 -15.528108417769 -11.791596805795 -11.715185023457 -14.081245914527 -15.443665285788 -19.326282744602 -20.291859009242 -18.451567438586 -17.031077730708 -13.752862078954 -13.218455399442 -16.234386790150 -16.488560871552 -14.658251400937 -15.254213152101 -15.916182713130 -13.411905343111 -11.395736760122 -15.722081728292 -21.113411958146 -20.003959100560 -14.473675579354 -10.583271356192 -10.548141871075 -10.415110659419 -12.763226122846 -14.265090406641 -13.528297986852 -13.102323973432 -10.990972172434 -8.018692983704 -6.364167872158 -8.040072542094 -9.421134015854 -9.279043370180 -7.917988949130 -7.099457516995 -9.999840299393 -12.582268806821 -10.554929578196 -10.421815555897 -11.683945247960 -13.194379084544 -14.663913261811 -11.124887864174 -12.694210234375 -14.658119069795 -14.412377848501 -15.871848160719 -15.229936966953 -19.317156703844 -23.022836865816 -24.965588568559 -28.029219248561 -28.102581062058 -27.884822043811 -21.484999591860 -13.501607272691 -9.536765889493 -6.521448394455 -10.181862261675 -10.763203539081 -1.965701874344 --9.440996601785 --13.953962956595 --8.209329677597 --3.839515004465 --2.398272572677 --6.122523453208 --15.090657164247 --21.472920413200 --25.913338830292 --27.156821870133 --21.598395535004 --13.147085216235 --7.929442830752 --10.751062134533 --17.465009957955 --23.026061088134 --26.825286855220 --27.988306726335 --28.820615367334 --30.184511453245 --31.946180790984 --33.545034719931 --33.897511594234 --37.409378347446 --43.409474453990 --49.699073931448 --53.502930216741 --52.733761746185 --52.704629780593 --54.150714179547 --56.198009072766 --58.787578865519 --59.611099426552 --58.087540050500 --55.358517532505 --54.575878496407 --53.230032323879 --47.222412771877 --42.344096834758 --38.448666656045 --35.575144318605 --36.888684472503 --40.696383013952 --44.296601791229 --45.014458610832 --43.896994485393 --43.217828050002 --41.664824195753 --40.462090471057 --42.943049662851 --46.172331944666 --45.992759320205 --41.448137178681 --32.667874486172 --21.468687687481 --11.416104834156 --3.463316213415 --0.162949627551 -0.598472665240 -0.936995856533 -3.503592162310 -8.181145902496 -11.610650967043 -12.333887479960 -10.943509458788 -10.334183570885 -10.387203839308 -12.092430509108 -15.014376086685 -16.045504045038 -11.690929429588 -8.207839751865 -14.517517237297 -31.593442361233 -44.204747125804 -48.024371631352 -49.494718653156 -51.082784112272 -52.448109796090 -54.307516864446 -55.911667927166 -53.079969438361 -51.063264467956 -49.798191081195 -50.105954522872 -46.984852050269 -38.126490917393 -30.352439274395 -26.057403008524 -27.312300342087 -32.717058459322 -35.578646459672 -34.339114071948 -31.123005443466 -32.622709739830 -37.105006577563 -36.105652295199 -33.662158167027 -31.646361089422 -26.829824001835 -19.020112478299 -13.141110067012 -7.875606063867 -3.165933764372 -2.329648653692 -3.737460767758 -7.036919830550 -8.758918616016 -5.587797786108 --0.200937160855 --8.181065505629 --14.542479543245 --13.135040260947 --5.471385192720 -0.980894389024 -1.263527064524 --1.080704261797 --4.268800340965 --8.363694294067 --9.972742729433 --7.944128026816 --4.406806444652 --1.765000127495 --1.455231537407 --1.963894452544 --2.851667872261 --4.190119999143 --2.782359827956 --2.379324023327 --4.925370527945 --4.394800605103 --4.507389524087 --4.015897809489 -0.137834571370 -2.857720547584 -4.997312548239 -3.147790483719 --1.381274136114 --4.523541922002 --6.269593850813 --6.536933945941 --7.337854138911 --4.959116894348 --1.127235801399 -0.494680041033 -3.081413257896 -7.098354500079 -9.301872648020 -5.770814703759 -1.159727995629 -0.101615031956 --2.049845675569 --4.014084681665 --2.381388644271 --1.954224735925 --3.795589471541 --6.532852579106 --11.678580452601 --17.122193308084 --19.135275457602 --17.968116104636 --15.680885842686 --13.020962214116 --10.012287656452 --4.548672148768 -0.109466067246 --0.268363955835 --1.512598547513 --4.023950952133 --10.009958940957 --15.662816361407 --20.519078676163 --22.033437329916 --22.264935157295 --21.796228107721 --19.397155265288 --20.418698692186 --22.849153005454 --24.118061715298 --19.858354084782 --7.944881690608 -1.259622432366 -8.095464043573 -13.108002590797 -13.623372227123 -13.893189847308 -12.550163711983 -11.735378970704 -8.693580229881 -5.415205461192 -5.321780352204 -0.829934532719 --6.346095915557 --12.574961295163 --10.598840998397 --2.124442814292 -4.098400205211 -9.384382699702 -9.522327045576 -2.724071640186 --8.593568286330 --21.370998331380 --26.876202053326 --26.711233190726 --19.355532081011 --9.148933647042 --1.928567786637 -4.434659192754 -8.593570209425 -9.875392394351 -5.329351843741 --2.041087935613 --3.844911299925 --2.748926916271 --3.202847579884 --2.936765528630 --0.043621829061 -2.672519497036 -2.499039362181 -1.313006579197 --0.466570055506 -0.389435895971 -1.986527373468 -2.904072825947 -4.147112966653 -3.414239177179 -1.006109280348 --3.282914345263 --12.299302892096 --21.252876072560 --20.905135543295 --12.818905241645 --4.606565764436 --0.099970225095 -0.308683100603 --2.212590474454 --7.708549351149 --14.264566237199 --17.465625178308 --18.427692501334 --19.155054076185 --17.778565979715 --15.861530011586 --15.659574423800 --18.395858990164 --19.699733021145 --20.019373012912 --21.100382437883 --20.702484863738 --21.133178089528 --20.849241937641 --20.302258855041 --18.065939586547 --13.356098433332 --9.744398128316 --4.828596433701 -0.245569646920 -4.483539894822 -9.457214600195 -16.176898425868 -25.776200369102 -32.256213830881 -34.667283211553 -33.302721048577 -26.891038397318 -16.315791755605 -3.743388323378 --2.037723883782 --4.743314174604 --4.064811979743 --2.738447237802 --0.984776350868 -4.488399233281 -5.715534871463 -10.997391448427 -17.531415105434 -20.183338314610 -22.787156820613 -24.069877158704 -25.760146446712 -27.809030282620 -19.065212160671 -5.992233544622 -0.552225298816 --0.900280177583 --3.568134702979 --10.392429833654 --15.348533897384 --18.778574930204 --18.852962669076 --14.186956292542 --9.617828210990 --4.997298902116 --0.908699147908 -4.350214101617 -6.834811300341 -2.830862141354 --0.902037367777 --0.059432255426 -4.131420697745 -7.674114063658 -12.557968990263 -21.102503430810 -25.660972867783 -25.664710971736 -24.812614161262 -23.406427381805 -23.620137496396 -26.495219904221 -32.656041691083 -35.919534885542 -31.495870841356 -21.621129479109 -11.015627685197 -1.814706137048 --0.779702436585 -6.234583481626 -12.224542521885 -14.281684216854 -17.118636106388 -19.195431791921 -15.664796304563 -5.088655593644 --7.564438275555 --12.191047966664 --15.301723318956 --21.505130670041 --26.936527998088 --32.418831036109 --36.732967763828 --39.312379072091 --41.600911678924 --42.083928233260 --40.179056109164 --39.614184596906 --35.774218140014 --28.974967668140 --25.166486064394 --22.558355264761 --20.804859831918 --20.661297924294 --15.731041761069 --5.810465342261 -2.649091565770 -11.748672514865 -22.215758982235 -30.076798951316 -37.039189307376 -44.189733214946 -51.641243272321 -56.506062091571 -51.348420506522 -41.623443920616 -32.753844528782 -25.377064379061 -19.089809079758 -11.928534235707 -7.869138294136 -9.124740846060 -11.412292651941 -13.809461545475 -21.352686192075 -29.628820611014 -33.317024819945 -33.242418304003 -30.083832700215 -26.445366325435 -23.983206681393 -21.193820833548 -16.439069255327 -11.603852089401 -6.754349623713 -7.411802204541 -11.974938942437 -15.582189374057 -21.830386054021 -27.205697621308 -30.664410018133 -27.912960990899 -25.822071515943 -31.165851228947 -33.134054071711 -31.909328745205 -30.044958332656 -26.488404789709 -21.184667212352 -9.038195192277 --4.459471468094 --16.983461319345 --23.243521647593 --18.721807121582 --9.490549097287 -1.099647451286 -2.742132788880 --3.441877523836 --10.639884863998 --21.428777024212 --28.089762943048 --28.744625023220 --25.970033132009 --22.812233968898 --23.250858003554 --22.604271221868 --18.798626258879 --12.487500011312 --6.971253657882 --4.942640833297 --4.977010466373 --5.637751819085 --4.470479196333 --0.593427691135 -1.265532103492 --0.093366900056 --3.483096947873 --8.229223478131 --11.551703337989 --17.961943671732 --23.459962681724 --22.229708435453 --19.218405647152 --18.805333572638 --20.743926343781 --21.886908792335 --22.040403441637 --24.721354005287 --26.152272042488 --22.610196289579 --17.449343618462 --13.919910399305 --14.124185912837 --11.856164647591 --9.121058597864 --10.306296899049 --11.511526172850 --11.364894305926 --8.269534759500 --7.244335159025 --4.732115068438 -2.281704361166 -5.183751675109 -7.688518309520 -12.248995859491 -18.313348527184 -22.273739209415 -18.227615618295 -10.688882507819 -3.004569927814 --4.347343827510 --9.798843203709 --11.009606175239 --9.507656379170 --9.056617020388 --8.214933055456 --6.409131183458 --5.648227016348 --2.657475895469 --0.748114469647 --2.354437093288 --5.269161494147 --13.330129905237 --24.303300856283 --33.044128217016 --40.465417077715 --43.299496345920 --39.171880765083 --34.239720648330 --29.550342042420 --22.772115944611 --17.687123858401 --18.536066081587 --20.357463917512 --17.476627044633 --11.898282391111 --9.255346013957 --9.312430404321 --7.557475306500 --6.295566116558 --8.580089002152 --10.433979304668 --5.853179705431 -4.736841903407 -11.739422301693 -17.702057587074 -25.936805632526 -30.797971536082 -31.149651390929 -28.710285074151 -27.307104207193 -21.829777635493 -13.041365756071 -10.040178158875 -11.500433351290 -15.513521697803 -21.556251594495 -27.316824763188 -32.948369154281 -34.819556434956 -35.613613668130 -34.078935860845 -29.893700825349 -26.499571926990 -24.714056943603 -24.516665952382 -21.962085807309 -19.616131283846 -18.258337978928 -14.169020642755 -4.325798310273 -0.279415961043 -0.656363368150 --1.613234928270 --2.906817735723 --3.480928586400 --6.377470072109 --10.472280520225 --14.629911787972 --18.433090616189 --20.905099827878 --22.411690860743 --22.472112199912 --25.977561237548 --33.679440081069 --42.543787253694 --50.237097505287 --51.955027075630 --43.633742595343 --32.645550357082 --26.323896060069 --23.039805660776 --20.679334553993 --14.644007271763 --10.939310473242 --11.363465656201 --13.176723417969 --18.849532902745 --27.510213912770 --34.710820674084 --34.925495598444 --30.066049680313 --25.085861362381 --20.199631917715 --18.139599569398 --16.217515809112 --14.442688584606 --11.197828070304 --1.819719668891 -7.946271678226 -15.142218859562 -18.918467000972 -19.196517418313 -18.394787298782 -18.939856707164 -24.214707363702 -31.785169207422 -39.345730635838 -44.664930035880 -45.629030615752 -44.251843302865 -41.892961389452 -37.618577294975 -32.945785088222 -32.574734288228 -32.194059614793 -26.937447783583 -20.448625846999 -15.264591965408 -10.764668199198 -10.792563751148 -13.227323164201 -15.068132786968 -17.852505244718 -16.230192101200 -10.899206987803 --0.094717762699 --13.408813107544 --19.323342911508 --21.412536097441 --20.299043404802 --19.404513367846 --18.376187311708 --15.525682452301 --19.624593950659 --25.474965994790 --27.333629143671 --25.208342470410 --23.028029659614 --22.797042149070 --21.323368768558 --21.006097050505 --18.663973888402 --10.659014221749 --4.328479078655 --1.998633125317 --0.875169669551 -1.022423501506 -3.641717085676 -3.111109169991 -2.269730644720 -0.509846412998 -1.762783487001 -2.753158965462 -1.358593069811 -2.580827105172 -2.576136116635 -1.187290282014 --1.226525523488 --3.731094779422 --7.051894495549 --8.267802931648 --5.075120636974 --0.912207131308 -4.753774932306 -14.016879351143 -20.612187024572 -21.842831680323 -18.950250215938 -15.717485995409 -13.170284365506 -11.508033299142 -8.673304196775 -7.606151171103 -11.569800080949 -11.660916047889 -9.281923457656 -6.470162468386 -1.827344791752 --2.883808949233 --5.752640230653 --6.418686789678 --4.989051513368 --3.300810827140 --4.251441446070 --8.256225997384 --15.268856647778 --20.439403024163 --20.147328739095 --18.863569002411 --16.415562668261 --16.507938233535 --20.408430690068 --26.169494325471 --32.155532545271 --35.203718120316 --37.029728827890 --38.893898616850 --39.120373579104 --34.152916703766 --26.496647114389 --16.705275679315 --10.046906959516 --4.229471591673 -2.415817183176 -12.563843124664 -26.816676040472 -36.853568376159 -37.304282762206 -28.908153656467 -20.577014479283 -14.815950681642 -11.331803274613 -11.681423941143 -14.968334228926 -16.512422044004 -14.771328235140 -10.209234799438 -9.788978463060 -13.220900443376 -18.124179888851 -25.565259839959 -34.445970097912 -43.366059656904 -49.702244200786 -52.956290759118 -49.356529838376 -45.195740123469 -44.718321931352 -39.987219417714 -32.370138364084 -24.860614033997 -20.997946371517 -21.043823753890 -12.653900922142 -1.822677015300 --5.245603397489 --9.810992020336 --9.259628678574 --7.547112914296 --3.524788537840 --0.602394268290 --3.033247986527 --2.913114487588 --3.868881485153 --6.787075865247 --11.958595262495 --17.786333165272 --17.615206084030 --18.428301254180 --18.527126977347 --14.779428730563 --8.019207071219 --2.754395003849 --2.463737191629 --3.992061576228 --6.696426757666 --7.654993964213 --5.186444644459 --2.749868940488 --0.922362803930 --4.188296299558 --10.085336855336 --11.686516272164 --12.208351114238 --9.307396733926 --3.821302310529 -1.734800836973 -6.808139512130 -8.353175043052 -4.275022671668 --2.784402182874 --6.113108194527 --3.907768738879 --0.894620862877 -2.401358163093 -5.233348179120 -4.126944560670 --2.599145012337 --14.306202637639 --20.765707169980 --20.032413418939 --15.771934319022 --7.799564808847 --4.288310716549 --9.234702300168 --21.717672858109 --32.295956812863 --32.900338882371 --28.704980529378 --23.056651884573 --15.706558436240 --9.262365831957 --5.880376157420 --8.478165921421 --12.265756248826 --12.890666643883 --13.287676030687 --12.720816135092 --15.727520645543 --20.284204211769 --20.614457005184 --19.872688543591 --20.359215782266 --22.080863252339 --19.219569325856 --10.372915158870 --2.700351503498 --0.704926847425 --2.987491337723 --3.056707359763 --2.376439400594 --0.847261483004 -4.760427651218 -12.767460198998 -22.519509827420 -30.825200145458 -37.769113391691 -40.100796286871 -34.751047733742 -27.034489382951 -19.842547536638 -15.671662314401 -15.659801793885 -17.114869857355 -22.858183409486 -25.228696957857 -22.169273358792 -26.792252453602 -32.373006900039 -33.539185062628 -33.692003669654 -35.650706757545 -39.337249415710 -34.345548250731 -27.516285582189 -25.524543803247 -25.886893217048 -25.770091306223 -27.761092005148 -35.951852830370 -41.154925776320 -41.417563670974 -44.290418878211 -45.078807290032 -44.794898285870 -46.724765449381 -50.110505838660 -54.267739723320 -52.320794948183 -49.963486663548 -47.639350398477 -39.526479124070 -27.849401180430 -18.625896826165 -14.832846941233 -13.018614939015 -10.929719276977 -4.452391303955 --8.514170012607 --21.798067236107 --29.402293263871 --30.671407016224 --28.336870362086 --26.154385416668 --27.076402828840 --28.811295840215 --32.614071072792 --39.022032871770 --42.534147631406 --41.469411275492 --39.759534304325 --39.787922289146 --40.076856637290 --39.943834604235 --39.154624120352 --36.494734187018 --31.547530939886 --27.452517187951 --23.758993852868 --21.005279782739 --22.142768884192 --25.388356078135 --25.188006479037 --21.818173478531 --18.611673421204 --17.394696025878 --18.917885326246 --19.110444899018 --21.610322386382 --26.586764174922 --26.883532951461 --21.984507625719 --14.827051567971 --9.617031584102 --10.136482238046 --14.004721069439 --15.060881296426 --15.409952209235 --16.105312648936 --15.923636894043 --14.944501007606 --11.391546881897 --8.033127977677 --4.208356246595 --0.480707479634 -3.107901840420 -9.169208723955 -15.132770890069 -22.334048822402 -28.667516728677 -28.627305451946 -23.388592228928 -15.601167311180 -8.767037533922 -4.865794237187 -1.009549442331 --1.759486997923 --6.190278919418 --12.935318004584 --16.533004139997 --18.391411394660 --19.727935638984 --17.869200074202 --15.162926743559 --16.663452443516 --23.458876703295 --28.734038240216 --27.531573331970 --28.845289982795 --33.784861732183 --36.922454048335 --37.488872622169 --33.108535631882 --30.412834094646 --29.060167505302 --24.463707586763 --22.880685409611 --21.929221988698 --22.609696570835 --19.972214977742 --10.918894081674 --3.334459164305 -4.113855713711 -9.320300767491 -11.030417018603 -7.479582727475 -2.739820681045 -1.006991786575 --3.257314697524 --8.849385986127 --9.934930017079 --7.708870642416 --6.852272241645 --8.577109121017 --9.136737618903 --8.402562443407 --8.003354779223 --5.203439964482 --0.597611645867 -4.941049382976 -10.322525567378 -14.130686678325 -18.752242759343 -25.721524954853 -32.895857581908 -38.526148806376 -38.885423745906 -34.674176882528 -30.971764838612 -28.343410185150 -26.259111274530 -24.598271900906 -26.555662035442 -29.356412681834 -32.093158699665 -34.009995074016 -32.387425329130 -31.390348261061 -31.728504384924 -31.825907904502 -29.371898786793 -23.310082069482 -18.825205073452 -15.719782922966 -11.970662023959 -12.113330724906 -17.689568110855 -21.663613187993 -17.779488103287 -11.786949578976 -7.743129772341 -6.349893350284 -7.344866533464 -11.704617192565 -18.082294700442 -20.901075764778 -16.550455719845 -5.214291441337 --7.737924607726 --15.951472649378 --19.405272969139 --20.518502290698 --16.973345661827 --8.623474751369 --0.288973018646 -6.160646868544 -9.868731868890 -11.014085079902 -8.926064927129 -3.959531148723 --1.841238238331 --10.178170640258 --18.610347068296 --21.873015630959 --19.243778250759 --14.840285616115 --9.912094125636 --7.573970645827 --8.403793699065 --8.492975874288 --7.236937461441 --5.316534734227 --5.215193759453 --5.234614421885 --1.794294449013 -2.102215117234 -5.298077029823 -10.441191643338 -13.849870856625 -15.848451466789 -14.013693791337 -10.808529900578 -11.309024136863 -10.734571689525 -11.448630885170 -11.155788474437 -7.223665249380 -6.224492310008 -4.862732559413 -5.288215790513 -6.297475991503 -3.773486062102 -3.901492898437 -4.721384326004 -4.589831697795 --3.131138881397 --14.982577013765 --17.712018777766 --19.817361384824 --23.957947577288 --25.247411294768 --27.077869329456 --29.450040701465 --31.542310958061 --29.668307608201 --25.975405734965 --22.246904414577 --16.160930531309 --13.736881400751 --18.535506354449 --26.522185236560 --29.797252585491 --29.279334191248 --25.174124285418 --18.248557009824 --14.221495478307 --15.601179442449 --19.386737495272 --21.373619921985 --21.088889805273 --20.428639717365 --20.773421956004 --21.837512986259 --23.911272613249 --24.693330362013 --23.857808740721 --25.238364711106 --27.819712699786 --29.597245357687 --25.604432823712 --19.479730175065 --20.148030286645 --19.251087736717 --14.532935089147 --12.300939307044 --13.067086182083 --13.395769273510 --9.380713520476 --2.116595596424 -2.536728871402 -2.923070090730 -1.020464824190 -0.384879528429 -0.497355922663 -0.459065398916 -2.150517010943 -4.033666819796 -4.358462564527 -3.212078603750 -2.563550205386 -1.248703695899 --0.772102294945 --0.651052473802 -1.532789812101 -5.231048398280 -7.177609018755 -6.583664842775 -5.227545900408 -4.451426799925 -5.201188205290 -8.936909613729 -15.691116510293 -23.935106017494 -30.235081088143 -36.575562676706 -42.799245191342 -46.100068521523 -45.239872402172 -43.732350784945 -44.219336795073 -43.359745885634 -43.538260722420 -46.063577354838 -48.653423369624 -50.782594994232 -49.113094545802 -46.123898671139 -45.838496009366 -41.592617023421 -33.993488395498 -27.491626793630 -25.219898585975 -29.399007586210 -27.830985968623 -22.087742043932 -20.278089784404 -17.776742014331 -12.436090413028 -4.692437179284 -4.672650185679 -9.595923675288 -11.607420883569 -17.897758283171 -20.774808165215 -15.335795691121 -5.034702105686 --5.325808861715 --10.530657814473 --15.128688439152 --18.542998961204 --18.717003110706 --19.580496694509 --22.707434581529 --24.507647967270 --22.263959692162 --22.064835242700 --24.980861535976 --26.958243768095 --25.859002746377 --21.518360940888 --20.960801450054 --21.611629783625 --21.724491893939 --22.643643665770 --25.208976117093 --27.139249241935 --22.744367569465 --15.642572341337 --11.632625103480 --10.978757758712 --8.621458208204 --4.518359422011 --0.932773140185 -5.259159705586 -12.499437267858 -12.481907259529 -4.802712748234 --3.674584551492 --7.298650038886 --5.374186000259 --2.973288638157 --3.588980940656 --4.502496103810 --8.634658562314 --13.358295284122 --15.450012781673 --12.844439294026 --4.666135930676 -1.763968494673 -6.924842121264 -9.798182872978 -7.917827369243 -2.326515457466 --3.455518801479 --6.360226850552 --9.522464874797 --11.760958946488 --12.495827673377 --11.917928545868 --10.382004274451 --7.814673159564 --2.617391369672 -1.495527377107 -1.402434405511 --0.690515988388 --5.013053494209 --10.061737493303 --9.375029731421 --4.907455527430 --1.254914489393 -0.304608484196 -1.815462120722 -2.685426667624 -2.237628215775 -4.020248525364 -6.839476959101 -9.727899375333 -10.982355801321 -11.988908694922 -13.110085637997 -12.731314325833 -12.668549441660 -10.143181740232 -4.927279309937 -3.287368992054 -2.500437785531 -0.846978737354 -4.044859114972 -11.408867605620 -22.852805603352 -30.186047434066 -31.166347854640 -34.051851083789 -34.411720162138 -31.352297220597 -28.683057261208 -25.917268775899 -26.575935139770 -27.807454781421 -28.752147635953 -29.165110473879 -28.274335037183 -28.079048198992 -19.810694787319 -7.264318474359 --3.266780782132 --7.919932908266 --3.288370664985 --0.052923828720 --0.194515931508 --1.706896166077 --6.235470149650 --10.434306447328 --14.570231386974 --15.434722589828 --12.728861426320 --10.698593790081 --9.425217431638 --13.343961152944 --19.415416662387 --23.635185596402 --23.096202532476 --22.106172116408 --22.930370132594 --18.843047303796 --16.301767609787 --22.436600729462 --27.947957267595 --22.937030631893 --9.342134147233 -4.864436644541 -15.098475788391 -18.182199667273 -13.439842484298 -5.455157380054 --3.757520377635 --7.653415743716 --2.437286072920 -4.266692907578 -8.108211698729 -8.842281791387 -4.612578982489 --1.980681019073 --7.839906791226 --10.281109463706 --10.642304225724 --9.448852888978 --7.700093711729 --4.148777732382 -1.422973272971 -4.894032889435 -6.378121529728 -3.829895961912 -2.653961439075 -4.138927616894 -2.971507705541 --1.138733161664 --4.902952359117 --6.891093507837 --8.827573472885 --11.456009798683 --11.790224227949 --12.052545581067 --11.648314756011 --8.476276728119 --2.618735244853 -4.208146792284 -7.515790843819 -9.395744336716 -8.913684597502 -4.224748111283 --3.458490017351 --7.664667740808 --10.268714971838 --13.937335430436 --16.580123231677 --17.109159071790 --14.904579900330 --12.952531157501 --9.583539520091 --5.387137417850 --2.359314328297 --4.136538189578 --7.154523952488 --6.293695557768 --6.512103082805 --10.186973869875 --10.170318442720 --6.614527200069 --3.302440493152 --2.659540738137 --4.068345819601 --0.081129763593 -2.917340262770 -1.540539733121 -1.784670744478 -2.308169244120 -0.883697294466 -0.468640660457 -4.128814624254 -9.305792311915 -13.300885349038 -15.028173817414 -13.362577043465 -10.432848390723 -5.481643563108 -2.037517917615 -6.251363179591 -8.760147782808 -8.767640334573 -9.909844154508 -10.187809683182 -9.019073285939 -3.106809793477 --3.767578866704 --3.971774789119 -0.079330493769 -2.708686038211 -0.260722412847 --6.638016035301 --10.912800648792 --13.741413152648 --13.070261790837 --9.212725599620 --3.939726781185 -3.998920134077 -6.858594617732 -1.321050797012 --7.385499386324 --13.814238150441 --17.592625110840 --20.969162073572 --20.583873846003 --17.507203306004 --13.196230883484 --3.904123406779 -5.590575253347 -11.055536372383 -12.562286576533 -11.332552144147 -10.404148799303 -9.420082487146 -7.478829599196 -8.685175974302 -9.903021868374 -7.495802475544 -2.793183648835 --1.103815363193 --1.308463921814 --1.596409454580 --1.935943989257 -0.831990928018 -1.500053675818 --4.006980441178 --11.803814271035 --19.088087446572 --19.545119258736 --12.375639095539 --4.348741451993 -0.212347286322 -3.085820652521 -4.175660735629 -2.450485166947 -2.006242530732 -6.784986869898 -16.652908065683 -27.067270543772 -31.360882556286 -25.091903281908 -14.722770650336 -6.422431321452 --1.602808700072 --10.566194360234 --14.767857823603 --10.982598199844 --7.541605084942 --9.264166149629 --10.879466380243 --11.138434506672 --11.829524889462 --11.801025257874 --11.396291711366 --8.616849092983 --5.811053901183 --4.027691759490 --3.785292352531 --4.838093772943 --2.644195895175 --0.012407789449 --0.656938152997 --5.131930430368 --12.402274374461 --17.478029873802 --21.462645113543 --24.262819018201 --22.906455714308 --20.286669887468 --19.049992108579 --19.400070222373 --19.601638615838 --21.463683400005 --25.653178807088 --25.366031040190 --24.081041553826 --29.591576592029 --37.435072126299 --40.696911587212 --39.316523445174 --42.693256680190 --47.962996687037 --47.148055059471 --42.124463755598 --32.689666941919 --19.243918427916 --3.339694412775 -6.056687251339 -5.724567603263 -3.175046966847 --2.650400654514 --9.480605050735 --14.094344623957 --13.605955007423 --4.132213838295 -6.919608830888 -18.519317015561 -28.739448816115 -30.304190303952 -27.585098832718 -24.866340465724 -22.452349994474 -23.307526620007 -27.190152345114 -32.160365915817 -36.749585270843 -41.403603405101 -49.340408245247 -55.662280552744 -54.214114748767 -52.207347600791 -51.707666120505 -49.216983241565 -45.712094823043 -43.578586026069 -41.660405085668 -37.682923670156 -34.379713168610 -30.681909553599 -28.430470520529 -29.038707256866 -27.509714389089 -25.503232073161 -25.624397185328 -25.997776599975 -25.556785320870 -23.701853907051 -17.837308071954 -9.847211942360 -1.022661194846 --6.208010569477 --8.876731449151 --6.005978591844 --0.601873895332 -4.685345007630 -9.387754238862 -12.868054603215 -15.504477180654 -13.432804037681 -9.387272484015 -6.012081674784 -4.085238029634 -2.598019597013 --1.031683730040 --3.497422356726 --5.464775607050 --7.737362859228 --7.750219291254 --6.427393893664 --5.520622106109 --4.514425030049 --2.955888584891 --1.471784385178 --0.375941953851 --0.876096476191 --3.364755359588 --2.995226651627 --1.138976381089 --3.765198953310 --3.549085580685 --3.837241245023 --7.835603992743 --11.424946045464 --16.832516583576 --17.463157512701 --18.698446781745 --20.301073936896 --15.366539138719 --9.090520317686 --7.252030219500 --11.751251545546 --14.988767862965 --14.093609510078 --9.311034392832 -1.943967216594 -12.382937780543 -14.574879089394 -7.553167125207 --3.053680910202 --8.450814936726 --11.838988938631 --11.573202282562 --5.736810124455 --1.822401252783 --4.451818588289 --11.426403595352 --21.413288040531 --33.270585518269 --42.118718110678 --45.299004458406 --45.443301236335 --46.017545546878 --46.136945679833 --41.752029578248 --33.758753994782 --26.157849823192 --22.778183933835 --18.966638235060 --12.436654312955 --9.124582957436 --8.094168870912 --3.506705572103 -0.701582240659 -2.255787160254 -6.018527514525 -10.067109321645 -12.577030789844 -13.195944846939 -12.736738569987 -11.329080014185 -6.319864429368 -0.697382245212 --0.925533915663 --2.601386219339 --3.362798666430 --1.970216824825 -0.546194116283 -5.042726358522 -4.494945272879 -4.328295411697 -8.926607070439 -13.504491930003 -14.187892428220 -10.555627461731 -9.227229912322 -12.152509624471 -15.878140695131 -19.369914910341 -26.172745594295 -35.215314257924 -40.664024737822 -41.752769447694 -42.347453617518 -44.414202626787 -42.932021985211 -35.463168709810 -31.595544735452 -33.611467589328 -35.344888712431 -33.317597362735 -31.400519203186 -32.301869440118 -31.144514407702 -28.577427296520 -27.580652697882 -30.642798379089 -36.520427067423 -39.015595890271 -37.279747616107 -33.283898334837 -29.878005897358 -27.691052224478 -25.232336176644 -21.529378504706 -18.006988161984 -14.880325019181 -15.054648621264 -15.206085437610 -7.775796104874 -5.412352204385 -11.686882033558 -17.923124478427 -18.508737322726 -13.506316927559 -11.174006315361 -4.630621923061 --5.549308623934 --9.269718734558 --9.975706145115 --8.604500275259 --7.238083220420 --3.698837862785 --1.415394277298 --7.844290591516 --14.264797579231 --19.995715094216 --24.988692651760 --29.135772321556 --31.816254268666 --28.796760223199 --25.226230925556 --22.228703097670 --17.670423992479 --16.076865609931 --19.754502527818 --27.132558993135 --34.497006245754 --38.733548381788 --40.338311484188 --35.105397750046 --30.179691063319 --33.405382458496 --40.756810238359 --47.398417983715 --48.078876861460 --49.162102282222 --49.566160881259 --45.675338137305 --45.037168090836 --49.601830695760 --54.460676295213 --53.429766915071 --51.197602338523 --51.594186621251 --48.658831164476 --40.682913990009 --32.490956404604 --24.493706706906 --18.772938534554 --16.258410258177 --12.642418348574 --5.998923110707 -3.731866684222 -4.629209499617 --2.213051215598 --6.376366595155 --11.447489850605 --16.510991323023 --14.244689368293 --6.122991298700 -1.501305947488 -2.309573276687 -0.885772008849 -3.146180314872 -2.161448425351 --0.131895292480 -1.789000995499 -3.404192571141 -4.577738119789 -7.356811094872 -9.114764157023 -7.681485137500 -2.726708743288 -1.417503982882 -6.917988576656 -8.693728522311 -3.613521473877 -0.153219909057 -1.006109982794 -5.065555653222 -9.288760431119 -13.253191242730 -18.006236677949 -19.127402813245 -13.945187155300 -4.270769471727 --1.211728991760 --1.123279712428 --1.175123462996 --2.426736044839 --4.388100599949 --4.840029308501 --0.294264791107 -5.522152157724 -10.889251535888 -13.259124612407 -12.416554626907 -7.893260127361 -1.032138068364 --3.765831658221 --7.181118589043 --5.889795148378 -1.793103782332 -11.449434359424 -21.278249104464 -27.554709450135 -28.990924097438 -31.798524496223 -31.684534047173 -27.911258888297 -23.221615760861 -20.426970258760 -20.860602151401 -21.040786813660 -22.333112953986 -20.908602132732 -16.629109576594 -13.054659550218 -12.670354025701 -15.152121380371 -13.593833558017 -12.516508980991 -17.471527380144 -19.822503570959 -18.515973875552 -14.903804379169 -11.622167996123 -10.284071168303 -8.384205924416 -6.197550565890 -2.812889597479 --1.680432930870 --6.218089172981 --7.111132362704 --5.966586275400 --7.557733992120 --9.705084423691 --11.207157503826 --14.465368375242 --17.038423035182 --16.653137381208 --11.870578685686 --7.442880862072 --5.404895012122 --5.272413539997 --6.599326901586 --9.501115320055 --13.053430619192 --12.787364196190 --9.307911117339 --5.676240780619 --1.334110455001 -2.476546304646 -1.961858445120 --2.874590095317 --5.453019013578 --5.606643349828 --6.983218195044 --8.094978456355 --7.503657202897 --6.739321979188 --6.630232118648 --4.778178281893 --2.183146378992 --1.680857447479 --3.990257994524 --6.239385903623 --5.226594652636 -0.094842092749 -6.908730709679 -9.498997546216 -9.811564736049 -10.082627953766 -8.703664979074 -4.548484273353 -0.234728781592 --2.421067593087 --4.389745422244 --3.594722688858 --2.788740851628 --5.611935270059 --7.481728828265 --4.992648308883 --0.895196293189 -1.014560435240 --1.161539054867 --4.661020646880 --7.602120554450 --8.776741381466 --9.430733795010 --9.533635790452 --9.210657221026 --9.754541524225 --13.062802259416 --20.484476857623 --27.741813281091 --30.526902140197 --27.270828441966 --22.494095543505 --14.419342282265 --6.266834585591 --4.154811737502 --5.358676302737 --9.012456419051 --5.923641144819 -3.128530872478 -11.964518334133 -23.272774828298 -30.504414158208 -33.791162209664 -32.569193436147 -29.305814248842 -28.572269071212 -22.615105189271 diff --git a/bcipy/signal/tests/process/decomposition/test_decomposition.py b/bcipy/signal/tests/process/decomposition/test_decomposition.py deleted file mode 100644 index 6f6adf887..000000000 --- a/bcipy/signal/tests/process/decomposition/test_decomposition.py +++ /dev/null @@ -1,101 +0,0 @@ -import unittest - -from bcipy.config import BCIPY_ROOT -from bcipy.exceptions import SignalException -from bcipy.signal.process.decomposition import continuous_wavelet_transform -from bcipy.signal.process.decomposition.psd import power_spectral_density, PSD_TYPE -import numpy as np - - -class TestDecomposition(unittest.TestCase): - - def setUp(self) -> None: - self.fs = 100 - data = np.loadtxt(f'{BCIPY_ROOT}/signal/tests/process/decomposition/resources/data.txt') - np.arange(data.size) / self.fs - self.data = data - self.band = (8, 12) - - def test_cwt(self): - # create test data to pass to cwt - # test data should be 3d array of shape (trials, channels, time) - data = np.random.rand(10, 2, 1000) - freq = 8 - fs = 100 - wavelet = "cmor1.5-1.0" - data, scales = continuous_wavelet_transform(data, freq, fs, wavelet) - self.assertEqual(data.shape, (10, 2, 1000)) - self.assertEqual(scales, fs / freq) - - def test_cwt_with_bad_wavelet(self): - data = np.random.rand(10, 2, 1000) - freq = 8 - fs = 100 - wavelet = "bad_wavelet" - with self.assertRaises(ValueError): - continuous_wavelet_transform(data, freq, fs, wavelet) - - def test_psd_relative(self): - response = power_spectral_density( - self.data, - self.band, - sampling_rate=self.fs, - relative=True, - plot=False) - - self.assertIsInstance(response, float) - self.assertTrue(0 <= response <= 1) - - def test_psd_welch(self): - response = power_spectral_density( - self.data, - self.band, - sampling_rate=self.fs, - method=PSD_TYPE.WELCH, - plot=False) - - self.assertIsInstance(response, float) - - def test_psd_multitaper(self): - response = power_spectral_density( - self.data, - self.band, - sampling_rate=self.fs, - method=PSD_TYPE.MULTITAPER, - plot=False) - - self.assertIsInstance(response, float) - - def test_psd_bad_method(self): - with self.assertRaises(SignalException): - power_spectral_density( - self.data, - self.band, - sampling_rate=self.fs, - method="bad_method", - plot=False) - - def test_psd_bad_band(self): - # create test data to pass to psd low band > high band - band = (12, 8) - - with self.assertRaises(IndexError): - power_spectral_density( - self.data, - band, - sampling_rate=self.fs, - plot=False) - - def test_psd_bad_data(self): - data = np.random.rand(10, 2, 1000) # no frequency dimension - - with self.assertRaises(IndexError): - power_spectral_density( - data, - self.band, - sampling_rate=self.fs, - plot=False) - - -if __name__ == '__main__': - unittest.main() diff --git a/bcipy/signal/tests/process/test_downsample.py b/bcipy/signal/tests/process/test_downsample.py index 39c008528..ce6529cdf 100644 --- a/bcipy/signal/tests/process/test_downsample.py +++ b/bcipy/signal/tests/process/test_downsample.py @@ -1,7 +1,9 @@ -from bcipy.signal.process import Downsample -import numpy as np import unittest +import numpy as np + +from bcipy.signal.process import Downsample + class TestDownsample(unittest.TestCase): """Test downsample functionality""" diff --git a/bcipy/simulator/README.md b/bcipy/simulator/README.md index e3854a46c..fb5c5ed24 100644 --- a/bcipy/simulator/README.md +++ b/bcipy/simulator/README.md @@ -1,6 +1,6 @@ -## RSVP Simulator +# BciPy Simulator -### Overview +## Overview This Simulator module aims to automate experimentation by sampling EEG data from prior sessions and running given models in a task loop, thus simulating a live session. @@ -8,43 +8,59 @@ This Simulator module aims to automate experimentation by sampling EEG data from `main.py` is the entry point for program. After following `BciPy` readme steps for setup, run the module from terminal: -``` -(venv) $ python bcipy/simulator -h -usage: simulator [-h] -d DATA_FOLDER [-g GLOB_PATTERN] -m MODEL_PATH -p PARAMETERS [-n N] +```bash +(venv) $ bcipy-sim -h +usage: bcipy-sim [-h] [-i] [--gui] [-d DATA_FOLDER] [-m MODEL_PATH] [-p PARAMETERS] [-n N] [-s SAMPLER] [-o OUTPUT] optional arguments: -h, --help show this help message and exit + -i, --interactive Use interactive command line for selecting simulator inputs + --gui Use interactive GUI for selecting simulator inputs -d DATA_FOLDER, --data_folder DATA_FOLDER - Raw data folders to be processed. - -g GLOB_PATTERN, --glob_pattern GLOB_PATTERN - glob pattern to select a subset of data folders Ex. "*RSVP_Copy_Phrase*" + Raw data folders to be processed. Multiple values can be provided, or a single parent folder. -m MODEL_PATH, --model_path MODEL_PATH - Signal models to be used + Signal models to be used. Multiple models can be provided. -p PARAMETERS, --parameters PARAMETERS Parameter File to be used -n N Number of times to run the simulation + -s SAMPLER, --sampler SAMPLER + Sampling strategy + --sampler_args SAMPLER_ARGS + Sampler args structured as a JSON string. + -o OUTPUT, --output OUTPUT + Sim output path + -v, --verbose Verbose mode for more detailed logging. ``` For example, -`$ python bcipy/simulator -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5` + +`$ bcipy-sim -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5` #### Program Args -- `d` : the data wrapper folder argument is necessary. This folder is expected to contain 1 or more session folders. Each session folder should contain - _raw_data.csv_, _triggers.txt_, _parameters.json_. These files will be used to construct a data pool from which simulator will sample EEG and other device responses. The parameters file in each data folder will be used to check compatibility with the simulation/model parameters. -- `g` : optional glob filter that can be used to select a subset of data within the wrapper directory. - - Ex. `"*Matrix_Copy*Jan_2024*"` will select all data for all Matrix Copy Phrase sessions recorded in January of 2024 (assuming the BciPy folder naming convention). - - Glob patterns can also include nested directories (ex. `"*/*Matrix_Copy*"`). +- `i` : Interactive command line interface. Provide this flag by itself to be prompted for each parameter. +- `gui`: A graphical user interface for configuring a simulation. This mode will output the command line arguments which can be used to repeat the simulation. +- `d` : Raw data folders to be processed. Data folders should contain EEG responses to Copy Phrase tasks. Each session data folder should contain + _raw_data.csv_, _triggers.txt_, _parameters.json_.These files will be used to construct a data pool from which simulator will sample EEG. The parameters file in each data folder will be used to check compatibility with the simulation/model parameters. - `p` : path to the parameters.json file used to run the simulation. These parameters will be applied to all raw_data files when loading. This file can specify various aspects of the simulation, including the language model to be used, the text to be spelled, etc. Timing-related parameters should generally match the parameters file used for training the signal model(s). -- `m`: all pickle (.pkl) files in this directory will be loaded as signal models. +- `m`: Path to a pickled (.pkl) signal model. One or more models can be provided. +- `n`: Number of simulation runs +- `o`: Output directory for all simulation artifacts. +- `s`: Sampling strategy to use; by default the TargetNonTargetSampler is used. The value provided should be the class name of a Sampler. +- `sampler_args`: Arguments to pass in to the selected Sampler. Some samplers can be customized with further parameters. These should be structured as a JSON dictionary mapping keys to values. For example: `--sampler_args='{"inquiry_end": 4}'` +- `-v` or `--verbose`: Execute the simulation in verbose mode for more detailed logging. Useful for debugging. #### Sim Output Details -Output folders are generally located in the `simulator/generated` directory. Each simulation will create a new directory. The directory name will be prefixed with `SIM` and will include the current date and time. +Output folders are generally located in the `data/simulator` directory, but can be configured per simulation. Each simulation will create a new directory. The directory name will be prefixed with `SIM` and will include the current date and time (E.G -- "SIM_%m-%d-%Y_%H_%M_%S") + +At the top level of the output directory, the following files are created: - `parameters.json` captures params used for the simulation. -- `sim.log` is a log file for the simulation +- `sim.log` is a log file for the overall simulation; metrics will be output here. +- `summary_data.json` summarizes session data from each of the runs into a single data structure. +- `metrics.png` boxplots for several metrics summarizing all simulation runs. A directory is created for each simulation run. The directory contents are similar to the session output in a normal bcipy task. Each run directory contains: @@ -54,20 +70,167 @@ A directory is created for each simulation run. The directory contents are simil ## Main Components -* Task - a simulation task to be run (ex. RSVP Copy Phrase) -* TaskRunner - runs one or more iterations of a simulation -* TaskFactory - constructs the hierarchy of objects needed for the simulation. -* DataEngine - loads data to be used in a simulation and provides an API to query for data. -* DataProcessor - used by the DataEngine to pre-process data. Pre-processed data can be classified by a signal model. -* Sampler - strategy for sampling data from the data pool stored in the DataEngine. +- Task - a simulation task to be run (ex. RSVP Copy Phrase) +- TaskRunner - runs one or more iterations of a simulation +- TaskFactory - constructs the hierarchy of objects needed for the simulation. +- DataEngine - loads data to be used in a simulation and provides an API to query for data. +- DataProcessor - used by the DataEngine to pre-process data. Pre-processed data can be classified by a signal model. +- Sampler - strategy for sampling data from the data pool stored in the DataEngine. ## Device Support The simulator is structured to support evidence from multiple devices (multimodal). However, it currently only includes processing for EEG device data. To provide support for models trained on data from other devices (ex. Gaze), a `RawDataProcessor` must be added for that device. The Processor pre-processes data collected from that device and prepares it for sampling. A `RawDataProcessor` is matched up to a given signal model using that model's metadata (metadata.device_spec.content_type). See the `data_process` module for more details. +## Parameters + +The parameters file is used to configure various aspects of the of the simulation. Timing-related parameters should generally match the parameters file used for training the signal model(s). Following are some specific parameters that you may want to modify, depending on the goals of a particular simulation: + +- `task_text` - the text to spell. +- `lang_model_type` - language model to use in the simulation. +- `summarize_session` - if set to true a session.xlsx summary will be generated for each simulation run. + +### Stoppage Criteria + +Parameters which define task stoppage criteria are important to ensure that the simulation runs to completion without getting stuck in an infinite loop. The values for these parameters may also affect analysis of results. + +- `min_inq_len` - Specifies the minimum number of inquiries to present before making a decision in copy/spelling tasks. +- `max_inq_len` - maximum number of inquiries to display before stopping the task. +- `max_selections` - The maximum number of selections for copy/spelling tasks. The task will end if this number is reached. +- `max_incorrect` - The maximum number of consecutive incorrect selections for copy/spelling tasks. The task will end if this number is reached. +- `max_inq_per_series` - Specifies the maximum number of inquiries to present before making a decision in copy/spelling tasks + +## GUI + +A simulation can be started using a graphical user interface. + +`$ bcipy-sim --gui` + +This provides a way to explore the file system when providing the parameters.json file, simulation model, and input data sources. After all required inputs have been provided the user can initiate the simulation from the GUI interface. The command line used to run the simulation are output to the console prior to the run making it easier to start subsequent simulations with the same set of arguments. + +## Replay Session + +The simulator also includes a Task for replaying a recorded session using a different signal model. This is used for testing if changes to a model result in more easily differentiated signals. + +This functionality currently has a different entry point. + +```bash +(venv) $ bcipy-replay -h +usage: bcipy-replay [-h] [-d DATA_FOLDER] -m MODEL_PATH [-p PARAMETERS] [-o OUTPUT] + +optional arguments: + -h, --help show this help message and exit + -d DATA_FOLDER, --data_folder DATA_FOLDER + Raw data folders to be processed. Multiple values can be provided, or a single parent folder. + -m MODEL_PATH, --model_path MODEL_PATH + Signal model to be used. + -p PARAMETERS, --parameters PARAMETERS + Parameter File to be used + -o OUTPUT, --output OUTPUT + Sim output path +``` + ## Current Limitations -* Only provides EEG support -* Only one sampler maybe provided for all devices. Ideally we should support a different sampling strategy for each device. -* Only Copy Phrase is currently supported. -* Metrics are collected per run, but not summarized across all runs. \ No newline at end of file +- Only one sampler maybe provided for all devices. Ideally we should support a different sampling strategy for each device. +- Only Copy Phrase is currently supported. + +## Group Demo + +A group simulation demo is provided in the `demo` directory. This demo includes the ability to run a simulation across multiple users, phrases, and language_models. The demo is run using the following command while in a virtual environment with the bcipy package installed: + +```bash +python bcipy/simulator/demo/demo_group_simulation.py +``` + +See the demo file for more details on how to configure the simulation. + +## Multimodal + +The `switch_data_processor` and `switch_model` are used to demonstrate a multimodal simulations using a button/switch as an example. To run a simulation with these inputs, you will need to perform the following steps: + +1. Ensure that the devices.json file has an entry for a switch + +```json +{ + "name": "Switch", + "content_type": "MARKERS", + "channels": [ + { "name": "Marker", "label": "Marker" } + ], + "sample_rate": 0.0, + "description": "Switch used for button press inputs", + "excluded_from_analysis": [], + "status": "active", + "static_offset": 0.0 +} +``` + +1. Ensure that the switch signal model can be loaded or create a switch signal model. To create a new one: + +```python +from pathlib import Path +from bcipy.acquisition.devices import preconfigured_device +from bcipy.io.save import save_model +from bcipy.signal.model.base_model import SignalModelMetadata +from bcipy.signal.model.switch_model import SwitchModel + +dirname = "" # TODO: enter the directory +model = SwitchModel() + +# name should match devices.json spec. Alternatively, use bcipy.acquisition.datastream.mock.switch.switch_device() + +device = preconfigured_device("Switch") +model.metadata = SignalModelMetadata(device_spec=device, evidence_type="BTN", transform=None) +save_model(model, Path(dirname, "switch_model.pkl")) +``` + +1. Set the appropriate simulation parameters in the parameters.json file. + + - set the `acq_mode` parameter to 'EEG+MARKERS'. + - ensure that `preview_inquiry_progress_method` parameter is set to '1' or '2'. + - You may also want to set the `summarize_session` parameter to `true` to see how the evidences get combined during decision-making. + +2. Ensure that the data directories have a raw data file (csv) for markers in addition to the EEG data. If your data does not have marker data, you can extract this from the triggers.txt file using the script `bcipy.simulator.util.generate_marker_data`. If the task was run with Inquiry Preview, the script can use the button press events recoreded in the trigger file. Otherwise you can use the `--mock` flag along with a parameters file to mock what a raw data file would look like if the user pressed the button according to the configured button press mode. + + ```bash + $ python -m bcipy.simulator.util.generate_marker_data -h + usage: generate_marker_data.py [-h] [-m] [-p PARAMETERS] data_folder + + Create raw marker data for a given session. + + positional arguments: + data_folder Data directory (must contain triggers.txt file) + + optional arguments: + -h, --help show this help message and exit + -m, --mock Mock data; use when button presses are not recorded in trigger file. + -p PARAMETERS, --parameters PARAMETERS + Optional parameters file to use when mocking data. + ``` + +3. Run a simulation. + + - Set the simulation parameters for both the EEG and the Button models (.pkl files). + - Use the InquirySampler + +Run with verbose mode and inspect the detailed run logs to ensure that the evidence is being sampled correctly. + +### Expected Behavior + +Along with the 'eeg' evidence, the output session.json (and session.xlsx) should record 'btn' evidence for each inquiry. These evidences should be fused +to provide the 'likelihood' values. + +For inquiries in which the target is shown: + +- evidence values for symbols in the inquiry should be boosted relative to non-inquiry symbols (default values are 0.95 for boosted and 0.05 for degraded). + +For inquiries in which the target not shown: + +- evidence values for symbols in inquiry should be degraded + +Note that the progress method (`preview_inquiry_progress_method` parameter) doesn't matter if it is set to "press to accept" or "press to skip", since the SwitchDataProcessor interprets this and outputs a 1.0 for inquiries that should be supported and 0.0 for those that shouldn't. + +### Multimodal Limitations + +- A `preview_inquiry_progress_method` of 0 is currently not supported and an exception will be thrown. Ideally, all inquiries should get an evidence value of 1.0 (no change) with this mode. +- Button evidence only works correctly with the InquirySampler. This is due to all trials in the same inquiry receiving the same value. diff --git a/bcipy/simulator/data/data_engine.py b/bcipy/simulator/data/data_engine.py index fe591db85..23ab816cc 100644 --- a/bcipy/simulator/data/data_engine.py +++ b/bcipy/simulator/data/data_engine.py @@ -2,52 +2,20 @@ import logging from abc import ABC, abstractmethod from pathlib import Path -from typing import Any, List, NamedTuple, Union +from typing import Any, List, NamedTuple, get_args, get_origin -import numpy as np import pandas as pd +from bcipy.core.parameters import Parameters from bcipy.exceptions import TaskConfigurationException -from bcipy.helpers.parameters import Parameters -from bcipy.simulator.data import data_process from bcipy.simulator.data.data_process import (ExtractedExperimentData, RawDataProcessor) +from bcipy.simulator.data.trial import Trial, convert_trials from bcipy.simulator.util.artifact import TOP_LEVEL_LOGGER_NAME log = logging.getLogger(TOP_LEVEL_LOGGER_NAME) -class Trial(NamedTuple): - """Data for a given trial (a symbol within an Inquiry). - - Attrs - ----- - source - directory of the data source - inquiry_n - starts at 0; does not reset at each series - inquiry_pos - starts at 1; position in which the symbol was presented - symbol - alphabet symbol that was presented - target - 1 or 0 indicating a boolean of whether this was a target symbol - eeg - EEG data associated with this trial - """ - source: str - inquiry_n: int - inquiry_pos: int - symbol: str - target: int - eeg: np.ndarray # Channels by Samples ; ndarray.shape = (channel_n, sample_n) - - def __str__(self): - fields = [ - f"source='{self.source}'", f"inquiry_n={self.inquiry_n}", - f"inquiry_pos={self.inquiry_pos}", f"symbol='{self.symbol}'", - f"target={self.target}", f"eeg={self.eeg.shape}" - ] - return f"Trial({', '.join(fields)})" - - def __repr__(self): - return str(self) - - class QueryFilter(NamedTuple): """Provides an API used to query a data engine for data.""" field: str @@ -57,8 +25,18 @@ class QueryFilter(NamedTuple): def is_valid(self) -> bool: """Check if the filter is valid.""" # pylint: disable=no-member - return self.field in Trial._fields and self.operator in self.valid_operators and isinstance( - self.value, Trial.__annotations__[self.field]) + field_type = Trial.__annotations__[self.field] + + # can't check isinstance of a subscriptable type, such as Optional. + origin = get_origin(field_type) + if origin: + options = get_args(field_type) + is_correct_type = any(isinstance(self.value, ftype) + for ftype in options) + else: + is_correct_type = isinstance(self.value, field_type) + + return self.field in Trial._fields and self.operator in self.valid_operators and is_correct_type @property def valid_operators(self) -> List[str]: @@ -69,7 +47,8 @@ def valid_operators(self) -> List[str]: class DataEngine(ABC): """Abstract class for an object that loads data from one or more sources, processes the data using a provided processor, and provides an interface - for querying the processed data.""" + for querying the processed data. + """ def load(self): """Load data from sources.""" @@ -85,31 +64,6 @@ def query(self, """Query the data.""" -def convert_trials(data_source: ExtractedExperimentData) -> List[Trial]: - """Convert extracted data from a single data source to a list of Trials.""" - trials = [] - symbols_by_inquiry = data_source.symbols_by_inquiry - labels_by_inquiry = data_source.labels_by_inquiry - - for i, inquiry_eeg in enumerate(data_source.trials_by_inquiry): - # iterate through each inquiry - inquiry_symbols = symbols_by_inquiry[i] - inquiry_labels = labels_by_inquiry[i] - - for sym_i, symbol in enumerate(inquiry_symbols): - # iterate through each symbol in the inquiry - eeg_samples = [channel[sym_i] - for channel in inquiry_eeg] # (channel_n, sample_n) - trials.append( - Trial(source=data_source.source_dir, - inquiry_n=i, - inquiry_pos=sym_i + 1, - symbol=symbol, - target=inquiry_labels[sym_i], - eeg=np.array(eeg_samples))) - return trials - - class RawDataEngine(DataEngine): """ Object that loads in list of session data folders and transforms data into @@ -122,8 +76,7 @@ def __init__(self, source_dirs: List[str], parameters: Parameters, self.parameters: Parameters = parameters self.data_processor = data_processor - self.data: List[Union[ExtractedExperimentData, - data_process.ExtractedExperimentData]] = [] + self.data: List[ExtractedExperimentData] = [] self._trials_df = pd.DataFrame() self.load() @@ -183,7 +136,7 @@ def query(self, for filt in filters), "Filters must all be valid" assert samples >= 1, "Insufficient number of samples requested" - expr = 'and '.join([self.query_condition(filt) for filt in filters]) + expr = ' and '.join([self.query_condition(filt) for filt in filters]) filtered_data = self._trials_df.query(expr) if filtered_data is None or len(filtered_data) < samples: raise TaskConfigurationException( diff --git a/bcipy/simulator/data/data_process.py b/bcipy/simulator/data/data_process.py index d56445cc8..85bbe2a46 100644 --- a/bcipy/simulator/data/data_process.py +++ b/bcipy/simulator/data/data_process.py @@ -1,12 +1,13 @@ """This module defines functionality related to pre-processing simulation data. Processed data can be subsequently sampled and provided to a SignalModel -for classification.""" +for classification. +""" import logging as logger from abc import abstractmethod from dataclasses import dataclass from pathlib import Path -from typing import List, NamedTuple, Optional, Tuple, Type +from typing import List, NamedTuple, Optional, Tuple import numpy as np @@ -15,13 +16,13 @@ from bcipy.acquisition.multimodal import ContentType from bcipy.config import (DEFAULT_DEVICE_SPEC_FILENAME, DEFAULT_PARAMETERS_FILENAME, TRIGGER_FILENAME) +from bcipy.core.list import grouper +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawData +from bcipy.core.stimuli import update_inquiry_timing +from bcipy.core.triggers import Trigger, TriggerType, trigger_decoder from bcipy.helpers.acquisition import analysis_channels, raw_data_filename -from bcipy.helpers.list import grouper -from bcipy.helpers.load import load_json_parameters, load_raw_data -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.raw_data import RawData -from bcipy.helpers.stimuli import update_inquiry_timing -from bcipy.helpers.triggers import TriggerType, trigger_decoder +from bcipy.io.load import load_json_parameters, load_raw_data from bcipy.signal.model.base_model import SignalModel from bcipy.signal.process import (ERPTransformParams, filter_inquiries, get_default_transform) @@ -73,22 +74,33 @@ def load_device_data(data_folder: str, class DecodedTriggers(NamedTuple): """Extracted properties after decoding the triggers.txt file and applying - the necessary offsets and corrections.""" + the necessary offsets and corrections. + """ targetness: List[str] # TriggerType times: List[float] symbols: List[str] # symbol corrected_times: List[float] + @property + def triggers(self) -> List[Trigger]: + """List of triggers""" + return [ + Trigger(label=self.symbols[i], + type=TriggerType(self.targetness[i]), + time=self.corrected_times[i]) + for i in range(len(self.symbols)) + ] + @dataclass() class ExtractedExperimentData: """Data from an acquisition device after reshaping and filtering.""" + source_dir: str inquiries: np.ndarray trials: np.ndarray labels: List inquiry_timing: List - decoded_triggers: DecodedTriggers trials_per_inquiry: int @@ -129,18 +141,17 @@ class TimingParams(NamedTuple): @property def trials_per_inquiry(self) -> int: - """Alias for stim_length""" + """Alias for stim_length.""" return self.stim_length @property def buffer(self) -> float: - """The task buffer length defines the min time between two inquiries - We use half of that time here to buffer during transforms""" + """The task buffer length defines the min time between two inquiries. We use half of that time here to buffer during transforms.""" return self.task_buffer_length / 2 @property def window_length(self) -> float: - """window (in seconds) of data collection after each stimulus presentation""" + """window (in seconds) of data collection after each stimulus presentation.""" start, end = self.trial_window return end - start @@ -213,7 +224,7 @@ def consumes(self) -> ContentType: @property def produces(self) -> EvidenceType: - """Type of evidence that is output""" + """Type of evidence that is output.""" raise NotImplementedError @property @@ -228,12 +239,13 @@ def model_device(self) -> DeviceSpec: @property def reshaper(self): - """data reshaper""" + """data reshaper.""" return self.model.reshaper def check_model_compatibility(self, model: SignalModel) -> None: """Check that the given model is compatible with this processor. - Checked on initialization.""" + Checked on initialization. + """ assert model.metadata, "Metadata missing from signal model." assert ContentType( model.metadata.device_spec.content_type @@ -249,10 +261,9 @@ def check_data_compatibility(self, data_device: DeviceSpec, data_timing_params): raise IncompatibleParameters( "Timing parameters are not compatible") - if data_device.static_offset == devices.DEFAULT_STATIC_OFFSET: log.warning(' '.join([ - f"Using the default static offset to decode triggers for {data_device.name}.", + f"Using the default static offset [{devices.DEFAULT_STATIC_OFFSET}] for {data_device.name}.", "Please make sure the correct offset is included in the devices.json file." ])) @@ -267,8 +278,7 @@ def process(self, data_folder: str, parameters - parameters.json file for the calibration session used to train the model / run the simulation. """ - raw_data, device_spec = load_device_data(data_folder, - self.content_type.name) + raw_data, device_spec = self.load_device_data(data_folder, parameters) data_parameters = load_json_parameters( f"{data_folder}/{DEFAULT_PARAMETERS_FILENAME}", value_cast=True) @@ -279,9 +289,8 @@ def process(self, data_folder: str, sim_timing_params=timing_params, data_timing_params=data_parameters.instantiate(TimingParams)) - decoded_triggers = decode_triggers(data_folder, timing_params, - device_spec.static_offset, - self.excluded_triggers()) + decoded_triggers = self.decode_triggers(data_folder, parameters, + device_spec.static_offset) reshaped_data = self.reshape_data(raw_data, decoded_triggers, timing_params) @@ -300,6 +309,20 @@ def process(self, data_folder: str, decoded_triggers=decoded_triggers, trials_per_inquiry=timing_params.trials_per_inquiry) + def load_device_data(self, data_folder: str, + parameters: Parameters) -> Tuple[RawData, DeviceSpec]: + """Load the device data.""" + return load_device_data(data_folder, self.content_type.name) + + def decode_triggers(self, + data_folder: str, + parameters: Parameters, + device_offset: float = 0.0) -> DecodedTriggers: + """Decode the triggers.txt file in the given directory.""" + timing_params = parameters.instantiate(TimingParams) + return decode_triggers(data_folder, timing_params, device_offset, + self.excluded_triggers()) + @abstractmethod def reshape_data(self, raw_data: RawData, decoded_triggers: DecodedTriggers, @@ -330,26 +353,26 @@ def extract_trials(self, filtered_reshaped_data: ReshapedData, raise NotImplementedError def excluded_triggers(self): - """Trigger types to exclude when decoding""" + """Trigger types to exclude when decoding.""" return [TriggerType.PREVIEW, TriggerType.EVENT, TriggerType.FIXATION] def devices_compatible(self, model_device: DeviceSpec, data_device: DeviceSpec) -> bool: """Check compatibility between the device on which the model was trained - and the device used for data collection.""" - + and the device used for data collection. + """ # TODO: check analysis channels? return model_device.sample_rate == data_device.sample_rate def parameters_compatible(self, sim_timing_params: TimingParams, data_timing_params: TimingParams) -> bool: - """Check compatibility between the parameters used for simulation and - those used for data collection.""" + """Check compatibility between the parameters used for simulation and those used for data collection.""" return sim_timing_params.time_flash == data_timing_params.time_flash -class EegRawDataProcessor(RawDataProcessor): +class EEGRawDataProcessor(RawDataProcessor): """RawDataProcessor that processes EEG data.""" + consumes = ContentType.EEG produces = EvidenceType.ERP @@ -417,7 +440,7 @@ def extract_trials(self, filtered_reshaped_data: ReshapedData, def get_transform(self, transform_params: ERPTransformParams, data_sample_rate: int) -> Composition: - """"Get the transform used for filtering the data.""" + """Get the transform used for filtering the data.""" return get_default_transform( sample_rate_hz=data_sample_rate, notch_freq_hz=transform_params.notch_filter_frequency, @@ -426,52 +449,3 @@ def get_transform(self, transform_params: ERPTransformParams, bandpass_order=transform_params.filter_order, downsample_factor=transform_params.down_sampling_rate, ) - - -# Module functions for matching a model to the correct processor. -def get_processor( - data_source: ContentType, - evidence_type: Optional[EvidenceType] = None -) -> Type[RawDataProcessor]: - """Returns the matching processor class. - - Parameters - ---------- - data_source - type of data that the processor should consume - evidence_type - type of evidence that the processor should produce. - """ - matches = [ - cls for cls in RawDataProcessor.__subclasses__() - if cls.consumes == data_source and ( - evidence_type is None or cls.produces == evidence_type) - ] - if matches: - return matches[0] - else: - msg = f"Data processor not found for {data_source.name}" - if evidence_type: - msg += f" -> {evidence_type.name}" - raise Exception(msg) - - -def find_data_processor(model: SignalModel) -> Type[RawDataProcessor]: - """Get the DataProcessor appropriate for the given model.""" - content_type = ContentType(model.metadata.device_spec.content_type) - # Metadata may provide an EvidenceType with a model so the same data source can - # be used to produce multiple types of evidence (ex. alpha) - evidence_type = None - model_output = model.metadata.evidence_type - if model_output: - try: - evidence_type = EvidenceType(model_output.upper()) - except ValueError: - logger.error(f"Unsupported evidence type: {model_output}") - - return get_processor(content_type, evidence_type) - - -def init_data_processor(signal_model: SignalModel) -> RawDataProcessor: - """Find an DataProcessor that matches the given signal_model and - initialize it.""" - processor_class = find_data_processor(signal_model) - return processor_class(signal_model) diff --git a/bcipy/simulator/data/processor_registry.py b/bcipy/simulator/data/processor_registry.py new file mode 100644 index 000000000..92e45b596 --- /dev/null +++ b/bcipy/simulator/data/processor_registry.py @@ -0,0 +1,74 @@ +"""Registry for data processors.""" +import logging as logger +from typing import List, Optional, Type + +from bcipy.acquisition.multimodal import ContentType +from bcipy.signal.model.base_model import SignalModel +# flake8: noqa +from bcipy.simulator.data.data_process import (EEGRawDataProcessor, + RawDataProcessor) +from bcipy.simulator.data.switch_data_processor import SwitchDataProcessor +from bcipy.task.data import EvidenceType + +log = logger.getLogger(__name__) + +PROCESSOR_TYPES = [EEGRawDataProcessor, SwitchDataProcessor] + + +def get_processors() -> List[Type[RawDataProcessor]]: + """Returns a list of all available raw data processors.""" + return PROCESSOR_TYPES + + +def register_processor(processor_type: Type[RawDataProcessor]) -> None: + """Register a new data processor to be used in a simulation.""" + if not processor_type in PROCESSOR_TYPES: + PROCESSOR_TYPES.append(processor_type) + + +# Module functions for matching a model to the correct processor. +def get_processor( + data_source: ContentType, + evidence_type: Optional[EvidenceType] = None +) -> Type[RawDataProcessor]: + """Returns the matching processor class. + + Parameters + ---------- + data_source - type of data that the processor should consume + evidence_type - type of evidence that the processor should produce. + """ + matches = [ + cls for cls in PROCESSOR_TYPES if cls.consumes == data_source and ( + evidence_type is None or cls.produces == evidence_type) + ] + if matches: + return matches[0] + else: + msg = f"Data processor not found for {data_source.name}" + if evidence_type: + msg += f" -> {evidence_type.name}" + raise Exception(msg) + + +def find_data_processor(model: SignalModel) -> Type[RawDataProcessor]: + """Get the DataProcessor appropriate for the given model.""" + content_type = ContentType(model.metadata.device_spec.content_type) + # Metadata may provide an EvidenceType with a model so the same data source can + # be used to produce multiple types of evidence (ex. alpha) + evidence_type = None + model_output = model.metadata.evidence_type + if model_output: + try: + evidence_type = EvidenceType(model_output.upper()) + except ValueError: + logger.error(f"Unsupported evidence type: {model_output}") + + return get_processor(content_type, evidence_type) + + +def init_data_processor(signal_model: SignalModel) -> RawDataProcessor: + """Find an DataProcessor that matches the given signal_model and + initialize it.""" + processor_class = find_data_processor(signal_model) + return processor_class(signal_model) diff --git a/bcipy/simulator/data/sampler/__init__.py b/bcipy/simulator/data/sampler/__init__.py new file mode 100644 index 000000000..8e8a9f048 --- /dev/null +++ b/bcipy/simulator/data/sampler/__init__.py @@ -0,0 +1,10 @@ +from bcipy.simulator.data.sampler.base_sampler import Sampler +from bcipy.simulator.data.sampler.inquiry_range_sampler import \ + InquiryRangeSampler +from bcipy.simulator.data.sampler.inquiry_sampler import InquirySampler +from bcipy.simulator.data.sampler.target_nontarget_sampler import \ + TargetNontargetSampler + +__all__ = [ + 'Sampler', 'InquirySampler', 'TargetNontargetSampler', 'InquiryRangeSampler' +] diff --git a/bcipy/simulator/data/sampler/base_sampler.py b/bcipy/simulator/data/sampler/base_sampler.py new file mode 100644 index 000000000..87af04e86 --- /dev/null +++ b/bcipy/simulator/data/sampler/base_sampler.py @@ -0,0 +1,92 @@ +from abc import ABC, abstractmethod +from typing import Callable, List, Tuple + +import numpy as np + +from bcipy.simulator.data.data_engine import RawDataEngine +from bcipy.simulator.data.trial import Trial +from bcipy.simulator.util.state import SimState + + +def default_reshaper(eeg_responses: List[np.ndarray]) -> np.ndarray: + """Default data reshaper. + + Returns + ------- + ndarray with shape (channel_n, trial_n, sample_n) + """ + + channels_eeg: List[List[np.ndarray]] = [ + [] for i in range(len(eeg_responses[0])) + ] + + for _i, trial_channels_eeg in enumerate(eeg_responses): + for c_i, channel_eeg in enumerate(trial_channels_eeg): + channels_eeg[c_i].append(channel_eeg) + + return np.array(channels_eeg) + + +def format_samples(sample_rows: List[Trial]) -> str: + """Returns a tabular representation of the sample rows.""" + return '\n'.join([str(row) for row in sample_rows]) + + +class Sampler(ABC): + """Represents a strategy for sampling signal model data from a DataEngine + comprised of signal data from one or more data collection sessions. + """ + + def __init__(self, data_engine: RawDataEngine): + self.data_engine: RawDataEngine = data_engine + self.model_input_reshaper: Callable = default_reshaper + + @abstractmethod + def sample(self, state: SimState) -> List[Trial]: + """ + Query the data engine for a list of trials corresponding to each + currently displayed symbol. + + Parameters + ---------- + state - specifies the target symbol and current inquiry (displayed symbols). + + Returns + ------- + a list of Trials with an item for each symbol in the current inquiry. + """ + raise NotImplementedError + + def sample_data(self, state: SimState) -> np.ndarray: + """ + Query for trials and reshape for signal model input according to the + provided reshaper. + + Return: + ndarray of shape (n_channel, n_trial, n_sample) + """ + trials = self.sample(state) + return self.reshaped(trials) + + def sample_with_context(self, + state: SimState) -> Tuple[np.ndarray, List[Trial]]: + """ + Returns + ------- + A tuple of the reshaped data (ndarray of shape (n_channel, n_trial, n_sample)) as + well as a list of Trial data (metadata and data not reshaped) for context. + """ + trials = self.sample(state) + data = self.reshaped(trials) + return data, trials + + def reshaped(self, sample_rows: List[Trial]) -> np.ndarray: + """Returns the queried trials reshaped into a format that a model can predict.""" + return self.model_input_reshaper([trial.eeg for trial in sample_rows]) + + def set_reshaper(self, reshaper: Callable): + """Set the reshaper""" + self.model_input_reshaper = reshaper + + def __str__(self): + return f"<{self.__class__.__name__}>" diff --git a/bcipy/simulator/data/sampler/inquiry_range_sampler.py b/bcipy/simulator/data/sampler/inquiry_range_sampler.py new file mode 100644 index 000000000..c9ca0502d --- /dev/null +++ b/bcipy/simulator/data/sampler/inquiry_range_sampler.py @@ -0,0 +1,66 @@ +import logging +from typing import List, Optional + +from bcipy.simulator.data.data_engine import QueryFilter, RawDataEngine +from bcipy.simulator.data.sampler.target_nontarget_sampler import \ + TargetNontargetSampler + +log = logging.getLogger(__name__) + + +class InquiryRangeSampler(TargetNontargetSampler): + """Sampler that queries a subset of inquiries for each series. + + Parameters + ---------- + data_engine - data repository to be queried + inquiry_start - index of first inquiry to include (starting at 1) + inquiry_count - number of inquiries to include + series_start - index of first series to include (starting at 1) + series_end - optional index of last series to include + """ + + def __init__(self, + data_engine: RawDataEngine, + inquiry_start: int = 1, + inquiry_count: int = 3, + series_start: int = 1, + series_count: Optional[int] = None): + super().__init__(data_engine) + if inquiry_start < 1: + raise ValueError("inquiry_start can't be less than 1") + if inquiry_count < 1: + raise ValueError("inquiry_count must be at least 1") + + self.inquiry_start = inquiry_start + self.inquiry_count = inquiry_count + self.series_start = series_start + self.series_count = series_count + + def query_filters(self, symbol: str, is_target: bool) -> List[QueryFilter]: + """Expression used to query for a single sample.""" + # In the data, inquiries are 0-indexed. + inq_start = self.inquiry_start - 1 + inq_end = inq_start + self.inquiry_count + filters = [ + QueryFilter('target', '==', int(is_target)), + QueryFilter('series_inquiry', '>=', inq_start), + QueryFilter('series_inquiry', '<', inq_end), + QueryFilter('series', '>=', self.series_start) + ] + if self.series_count: + series_end = self.series_start + self.series_count + filters.append(QueryFilter('series', '<', series_end)) + return filters + + def __str__(self): + fields = [ + f"inquiry_start={self.inquiry_start}", + f"inquiry_count={self.inquiry_count}", + f"series_start={self.series_start}", + f"series_count={self.series_count}" + ] + return f"InquiryRangeSampler({', '.join(fields)})" + + def __repr__(self): + return str(self) diff --git a/bcipy/simulator/data/sampler.py b/bcipy/simulator/data/sampler/inquiry_sampler.py similarity index 55% rename from bcipy/simulator/data/sampler.py rename to bcipy/simulator/data/sampler/inquiry_sampler.py index 5424c95e2..d4a7cc214 100644 --- a/bcipy/simulator/data/sampler.py +++ b/bcipy/simulator/data/sampler/inquiry_sampler.py @@ -1,117 +1,19 @@ import logging import random -from abc import ABC, abstractmethod from collections import defaultdict from pathlib import Path -from typing import Callable, Dict, List, Tuple +from typing import Dict, List, Tuple -import numpy as np import pandas as pd -from bcipy.simulator.data.data_engine import QueryFilter, RawDataEngine, Trial +from bcipy.simulator.data.data_engine import RawDataEngine +from bcipy.simulator.data.sampler.base_sampler import Sampler, format_samples +from bcipy.simulator.data.trial import Trial from bcipy.simulator.util.state import SimState log = logging.getLogger(__name__) -def default_reshaper(eeg_responses: List[np.ndarray]) -> np.ndarray: - """Default data reshaper. - - Returns - ------- - ndarray with shape (channel_n, trial_n, sample_n) - """ - - channels_eeg: List[List[np.ndarray]] = [ - [] for i in range(len(eeg_responses[0])) - ] - - for _i, trial_channels_eeg in enumerate(eeg_responses): - for c_i, channel_eeg in enumerate(trial_channels_eeg): - channels_eeg[c_i].append(channel_eeg) - - return np.array(channels_eeg) - - -class Sampler(ABC): - """Represents a strategy for sampling signal model data from a DataEngine - comprised of signal data from one or more data collection sessions.""" - - def __init__(self, data_engine: RawDataEngine): - self.data_engine: RawDataEngine = data_engine - self.model_input_reshaper: Callable = default_reshaper - - @abstractmethod - def sample(self, state: SimState) -> List[Trial]: - """ - Query the data engine for a list of trials corresponding to each - currently displayed symbol. - - Parameters - ---------- - state - specifies the target symbol and current inquiry (displayed symbols). - - Returns - ------- - a list of Trials with an item for each symbol in the current inquiry. - """ - raise NotImplementedError - - def sample_data(self, state: SimState) -> np.ndarray: - """ - Query for trials and reshape for signal model input according to the - provided reshaper. - - Return: - ndarray of shape (n_channel, n_trial, n_sample) - """ - trials = self.sample(state) - return self.reshaped(trials) - - def sample_with_context(self, - state: SimState) -> Tuple[np.ndarray, List[Trial]]: - """ - Returns - ------- - A tuple of the reshaped data (ndarray of shape (n_channel, n_trial, n_sample)) as - well as a list of Trial data (metadata and data not reshaped) for context. - """ - trials = self.sample(state) - data = self.reshaped(trials) - return data, trials - - def reshaped(self, sample_rows: List[Trial]) -> np.ndarray: - """Returns the queried trials reshaped into a format that a model can predict.""" - return self.model_input_reshaper([trial.eeg for trial in sample_rows]) - - def set_reshaper(self, reshaper: Callable): - """Set the reshaper""" - self.model_input_reshaper = reshaper - - def __str__(self): - return f"<{self.__class__.__name__}>" - - -class TargetNontargetSampler(Sampler): - """Sampler that that queries based on target/non-target label.""" - - def sample(self, state: SimState) -> List[Trial]: - sample_rows = [] - for symbol in state.display_alphabet: - filters = self.query_filters( - symbol, is_target=(symbol == state.target_symbol)) - filtered_data = self.data_engine.query(filters, samples=1) - sample_rows.append(filtered_data[0]) - - log.debug(f"Samples:\n{format_samples(sample_rows)}") - return sample_rows - - def query_filters(self, symbol: str, is_target: bool) -> List[QueryFilter]: - """Expression used to query for a single sample.""" - # QueryFilter('symbol', '==', symbol) - return [QueryFilter('target', '==', int(is_target))] - - class InquirySampler(Sampler): """Samples an inquiry of data at a time.""" @@ -126,9 +28,9 @@ def __init__(self, data_engine: RawDataEngine): def prepare_data( self, data: pd.DataFrame ) -> Tuple[Dict[Path, List[int]], Dict[Path, List[int]]]: - """Partition the data into those inquiries that displayed the target - and those that did not. The resulting data structures map the data - source with a list of inquiry_n numbers.""" + """Partition the data into those inquiries that displayed the target and those that did not. + The resulting data structures map the data source with a list of inquiry_n numbers. + """ target_inquiries = defaultdict(list) no_target_inquiries = defaultdict(list) @@ -180,8 +82,8 @@ def sample(self, state: SimState) -> List[Trial]: inquiry_n = random.choice(source_inquiries[data_source]) # select all trials for the data_source and inquiry - inquiry_df = self.data.loc[(self.data['source'] == data_source) & - (self.data['inquiry_n'] == inquiry_n)] + inquiry_df = self.data.loc[(self.data['source'] == data_source) + & (self.data['inquiry_n'] == inquiry_n)] assert len(inquiry_df) == len( inquiry_letter_subset), f"Invalid data source {data_source}" @@ -196,6 +98,7 @@ def sample(self, state: SimState) -> List[Trial]: inquiry_target_position = inquiry_df.index.tolist().index( inquiry_target_index) + new_target_position = float(target_position) if inquiry_target_position == target_position: # target already in the correct location, no need to adjust new_target_position = inquiry_target_position + 0.0 @@ -220,10 +123,5 @@ def sample(self, state: SimState) -> List[Trial]: Trial(**sorted_inquiry_df.iloc[i]) for i in range(len(sorted_inquiry_df)) ] - log.debug(f"EEG Samples:\n{format_samples(rows)}") + log.debug(f"Samples:\n{format_samples(rows)}") return rows - - -def format_samples(sample_rows: List[Trial]) -> str: - """Returns a tabular representation of the sample rows.""" - return '\n'.join([str(row) for row in sample_rows]) diff --git a/bcipy/simulator/data/sampler/replay_sampler.py b/bcipy/simulator/data/sampler/replay_sampler.py new file mode 100644 index 000000000..084fbb5a1 --- /dev/null +++ b/bcipy/simulator/data/sampler/replay_sampler.py @@ -0,0 +1,61 @@ +import logging +from typing import List + +from bcipy.simulator.data.data_engine import QueryFilter, RawDataEngine, Trial +from bcipy.simulator.data.sampler.base_sampler import Sampler, format_samples +from bcipy.simulator.exceptions import IncompatibleData +from bcipy.simulator.util.state import SimState + +log = logging.getLogger(__name__) + + +class ReplaySampler(Sampler): + """Sampler that provides inquiries for replaying a session. + + Assumes that the state is sending sample requests sequentially and that the + order of symbols match the original session. + """ + + def __init__(self, data_engine: RawDataEngine): + super().__init__(data_engine) + + source_count = len(self.data_engine.source_dirs) + if source_count > 1: + log.warning("Only 1 dataset is supported.") + if source_count == 0: + raise IncompatibleData("At least one data source is required.") + self.current_source_index = 0 + + @property + def current_source(self) -> str: + """Current data source""" + return self.data_engine.source_dirs[self.current_source_index] + + def sample(self, state: SimState) -> List[Trial]: + """Sample data that exactly matches the provided state.""" + + sample_rows = [] + for symbol in state.display_alphabet: + filters = self.query_filters(state, symbol) + filtered_data = self.data_engine.query(filters, samples=1) + sample_rows.append(filtered_data[0]) + log.info(f"Samples:\n{format_samples(sample_rows)}") + + return sample_rows + + def query_filters(self, state: SimState, symbol: str) -> List[QueryFilter]: + """Expression used to query for a single sample.""" + return [ + QueryFilter('source', '==', self.current_source), + QueryFilter('series', '==', state.series_n), + QueryFilter('series_inquiry', '==', state.inquiry_n), + QueryFilter('symbol', '==', symbol) + ] + + def next_source(self) -> None: + """Increment to query from the next data source.""" + last_index = len(self.data_engine.source_dirs) - 1 + if self.current_source_index < last_index: + self.current_source_index += 1 + else: + self.current_source_index = 0 diff --git a/bcipy/simulator/data/sampler/target_nontarget_sampler.py b/bcipy/simulator/data/sampler/target_nontarget_sampler.py new file mode 100644 index 000000000..71e4e69f0 --- /dev/null +++ b/bcipy/simulator/data/sampler/target_nontarget_sampler.py @@ -0,0 +1,30 @@ +import logging +from typing import List + +from bcipy.simulator.data.data_engine import QueryFilter +from bcipy.simulator.data.sampler.base_sampler import Sampler, format_samples +from bcipy.simulator.data.trial import Trial +from bcipy.simulator.util.state import SimState + +log = logging.getLogger(__name__) + + +class TargetNontargetSampler(Sampler): + """Sampler that that queries based on target/non-target label.""" + + def sample(self, state: SimState) -> List[Trial]: + """Sample trials for each symbol in the display alphabet, labeling as target or non-target.""" + sample_rows = [] + for symbol in state.display_alphabet: + filters = self.query_filters( + symbol, is_target=(symbol == state.target_symbol)) + filtered_data = self.data_engine.query(filters, samples=1) + sample_rows.append(filtered_data[0]) + + log.debug(f"Samples:\n{format_samples(sample_rows)}") + return sample_rows + + def query_filters(self, symbol: str, is_target: bool) -> List[QueryFilter]: + """Expression used to query for a single sample.""" + # QueryFilter('symbol', '==', symbol) + return [QueryFilter('target', '==', int(is_target))] diff --git a/bcipy/simulator/data/switch_data_processor.py b/bcipy/simulator/data/switch_data_processor.py new file mode 100644 index 000000000..7616b8360 --- /dev/null +++ b/bcipy/simulator/data/switch_data_processor.py @@ -0,0 +1,181 @@ +"""Process raw button press data.""" + +from pathlib import Path +from typing import List, Tuple + +import numpy as np + +from bcipy.acquisition import devices +from bcipy.acquisition.devices import DeviceSpec +from bcipy.acquisition.multimodal import ContentType +from bcipy.config import TRIGGER_FILENAME +from bcipy.core.list import grouper +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawData +from bcipy.core.triggers import TriggerType +from bcipy.display.main import ButtonPressMode, PreviewParams +from bcipy.helpers.acquisition import raw_data_filename +from bcipy.io.load import load_raw_data +from bcipy.simulator.data.data_process import (DecodedTriggers, + ExtractedExperimentData, + RawDataProcessor, ReshapedData, + TimingParams) +from bcipy.simulator.exceptions import IncompatibleData, IncompatibleParameters +from bcipy.simulator.util.switch_utils import inquiry_windows, switch_device +from bcipy.task.data import EvidenceType + + +class SwitchDataProcessor(RawDataProcessor): + """Data Processor for button press data. + + Note that this class reads raw switch data. If this is not present in the + data_folder it can be generated from Inquiry Preview triggers or simulated. + See the switch_utils module for details. + + The processed data values associated with a switch press depend on the button + press mode configured parameters. + + If the mode is 'press to accept/confirm' and the switch is pressed, all trials + in that inquiry are given a data value of 1.0. Otherwise, the data value is 0.0. + + If the mode is 'press to skip', all trials in inquiries with a button press are + given a value 0.0. Otherwise, the data value is 1.0. + + The switch model will upvote all symbols in an inquiry if any of the symbols have + a value of 1.0, and will downvote if all are 0.0. + + This also means that this processor should only be used in conjunction with the + InquirySampler. + """ + consumes = ContentType.MARKERS + produces = EvidenceType.BTN + + def data_value(self, raw_data: RawData, inq_start: float, inq_stop: float, + button_press_mode: ButtonPressMode) -> float: + """Returns the data value for all trials in the inquiry. + + The switch was pressed some time during the inquiry but not necessarily + coinciding with a specific symbol, so all symbols are assigned the same + value (1.0 or 0.0). + + The value depends on the button press mode and indicates whether the + symbols in the inquiry should be upgraded or downgraded. + """ + times = raw_data.dataframe['lsl_timestamp'] + switch_was_pressed = any(inq_start <= time <= inq_stop + for time in times) + + rules = { + ButtonPressMode.NOTHING: lambda: 1.0, + ButtonPressMode.ACCEPT: lambda: 1.0 if switch_was_pressed else 0.0, + ButtonPressMode.REJECT: lambda: 1.0 + if not switch_was_pressed else 0.0 + } + return rules[button_press_mode]() + + def process(self, data_folder: str, + parameters: Parameters) -> ExtractedExperimentData: + """Load and process the data. + + Parameters + ---------- + data_folder - session directory for a given dataset + (contains raw_data, devices.json, and parameters.json). + parameters - parameters.json file for the calibration session used + to train the model / run the simulation. + """ + raw_data, _spec = self.load_device_data(data_folder, parameters) + + timing_params = parameters.instantiate(TimingParams) + button_press_mode = parameters.instantiate( + PreviewParams).button_press_mode + + if button_press_mode is ButtonPressMode.NOTHING: + raise IncompatibleParameters("Button press mode must be set.") + + decoded_triggers = self.decode_triggers(data_folder, parameters) + time_ranges = inquiry_windows(Path(data_folder, TRIGGER_FILENAME), + timing_params.time_flash) + + inquiry_data: List[List[float]] = [] + target_labels: List[List[int]] = [] + + # chunk triggers into inquiries and iterate. + for i, inquiry_triggers in enumerate( + grouper(decoded_triggers.triggers, + timing_params.trials_per_inquiry, + incomplete='ignore')): + inquiry_trial_data = [] + inquiry_target_labels = [] + + # Returns the same value for all trials in the inquiry. + start, stop = time_ranges[i] + data = self.data_value(raw_data, start, stop, button_press_mode) + + # collect data for each trial in the inquiry + for trg in inquiry_triggers: + target_lbl = 1 if trg.type == TriggerType.TARGET else 0 + inquiry_trial_data.append(data) + inquiry_target_labels.append(target_lbl) + + inquiry_data.append(inquiry_trial_data) + target_labels.append(inquiry_target_labels) + + # shape: (channels/1 , inquiries/inquiry_count, samples/trials_per_inquiry) + inquiry_arr = np.array([inquiry_data]) + trial_count = inquiry_arr.shape[1] * timing_params.trials_per_inquiry + + # shape: (channels/1, trials/trial_count, samples/1) + trial_arr = inquiry_arr.reshape((1, trial_count, 1)) + + return ExtractedExperimentData( + source_dir=data_folder, + inquiries=inquiry_arr, + trials=trial_arr, + labels=target_labels, + inquiry_timing=[], # timing data not used + decoded_triggers=decoded_triggers, + trials_per_inquiry=timing_params.trials_per_inquiry) + + def load_device_data(self, data_folder: str, + parameters: Parameters) -> Tuple[RawData, DeviceSpec]: + """Load the device data""" + device_spec = switch_device() + raw_data_path = Path(data_folder, raw_data_filename(device_spec)) + if not raw_data_path.exists(): + raise IncompatibleData( + "Missing raw data for switch. Use switch_utils to generate.") + raw_data = load_raw_data(str(raw_data_path)) + return raw_data, device_spec + + def reshape_data(self, raw_data: RawData, + decoded_triggers: DecodedTriggers, + timing_params: TimingParams) -> ReshapedData: + """Use the configured reshaper to reshape the data.""" + raise NotImplementedError + + def apply_filters(self, reshaped_data: ReshapedData, + parameters: Parameters, + data_sample_rate: int) -> Tuple[ReshapedData, int]: + """Apply any filters to the reshaped data. + + Returns + ------- + inquiry data after filtering, updated sample_rate + """ + return reshaped_data, devices.IRREGULAR_RATE + + def extract_trials(self, filtered_reshaped_data: ReshapedData, + timing_params: TimingParams, + updated_sample_rate: float) -> np.ndarray: + """Extract trial data from the filtered, reshaped data. + + Returns + ------- + np.ndarray of shape (Channels, Trials, Samples) + """ + raise NotImplementedError + + def excluded_triggers(self): + """Trigger types to exclude when decoding""" + return [TriggerType.PREVIEW, TriggerType.EVENT, TriggerType.FIXATION] diff --git a/bcipy/simulator/data/trial.py b/bcipy/simulator/data/trial.py new file mode 100644 index 000000000..58ff9e20d --- /dev/null +++ b/bcipy/simulator/data/trial.py @@ -0,0 +1,128 @@ +"""Functions for trial-related data.""" +import itertools as it +from pathlib import Path +from typing import Callable, List, NamedTuple, Optional, Tuple + +import numpy as np + +from bcipy.config import SESSION_DATA_FILENAME +from bcipy.core.list import find_index +from bcipy.core.session import read_session +from bcipy.simulator.data.data_process import ExtractedExperimentData + + +class Trial(NamedTuple): + """Data for a given trial (a symbol within an Inquiry). + + Attrs + ----- + source - directory of the data source + series - starts at 1; computed from session.json + series_inquiry - starts at 0; inquiry within the series; computed + from session.json + inquiry_n - starts at 0; value from the start of the session (does not + reset at each series); can be computed from raw_data. + inquiry_pos - starts at 1; position in which the symbol was presented + symbol - alphabet symbol that was presented + target - 1 or 0 indicating a boolean of whether this was a target symbol + eeg - EEG data associated with this trial + """ + source: str + series: Optional[int] + series_inquiry: Optional[int] + inquiry_n: int + inquiry_pos: int + symbol: str + target: int + # Channels by Samples ; ndarray.shape = (channel_n, sample_n) + eeg: np.ndarray + + def __str__(self): + fields = [ + f"source='{self.source}'", f"series={self.series}", + f"series_inquiry={self.series_inquiry}", + f"inquiry_n={self.inquiry_n}", f"inquiry_pos={self.inquiry_pos}", + f"symbol='{self.symbol}'", f"target={self.target}", + f"eeg={self.eeg.shape}" + ] + return f"Trial({', '.join(fields)})" + + def __repr__(self): + return str(self) + + +def session_series_counts(source_dir: str) -> List[int]: + """Read the session.json file in the provided directory and compute the number of inquiries per series.""" + session_path = Path(source_dir, SESSION_DATA_FILENAME) + if session_path.exists(): + session = read_session(str(session_path)) + return [len(series) for series in session.series] + return [] + + +def series_inquiry(series_counts: List[int], + inquiry_n: int) -> Tuple[Optional[int], Optional[int]]: + """Given the number of inquiries per series and the inquiry from the start of the session, + compute the series and inquiry relative to the start of that series. + + Parameters + ---------- + series_counts - number of inquiries for each series in the session. + inquiry_n - index of the inquiry from the start of the session + starts at 0. + Returns + ------- + a tuple of the series (1-based), inquiry_index (0-based) relative to series. + """ + if series_counts: + accumulations = list(it.accumulate(series_counts)) + series_index = find_index(accumulations, + match_item=lambda val: val > inquiry_n) + if series_index is not None: + if series_index > 0: + inq_index = inquiry_n - accumulations[series_index - 1] + else: + inq_index = inquiry_n + return (series_index + 1, inq_index) + return (None, None) + + +def convert_trials( + data_source: ExtractedExperimentData, + get_series_counts: Callable[[str], List[int]] = session_series_counts +) -> List[Trial]: + """Convert extracted data from a single data source to a list of Trials. + + Parameters + ---------- + data_source - Data from an acquisition device after reshaping and filtering. + get_series_counts - function to get the session metadata needed to assign + series and relative_inquiry information to each trial. The function should + take the source_directory path as an input and return the number of inquiries + in each series. By default this is read from the session.json in the source_dir. + """ + trials = [] + symbols_by_inquiry = data_source.symbols_by_inquiry + labels_by_inquiry = data_source.labels_by_inquiry + series_counts = get_series_counts(data_source.source_dir) + + for i, inquiry_eeg in enumerate(data_source.trials_by_inquiry): + # iterate through each inquiry + inquiry_symbols = symbols_by_inquiry[i] + inquiry_labels = labels_by_inquiry[i] + + for sym_i, symbol in enumerate(inquiry_symbols): + # iterate through each symbol in the inquiry + series, inquiry = series_inquiry(series_counts, i) + eeg_samples = [channel[sym_i] + for channel in inquiry_eeg] # (channel_n, sample_n) + trials.append( + Trial(source=data_source.source_dir, + series=series, + series_inquiry=inquiry, + inquiry_n=i, + inquiry_pos=sym_i + 1, + symbol=symbol, + target=inquiry_labels[sym_i], + eeg=np.array(eeg_samples))) + return trials diff --git a/bcipy/simulator/demo/demo_group_simulation.py b/bcipy/simulator/demo/demo_group_simulation.py new file mode 100644 index 000000000..5b6e84b64 --- /dev/null +++ b/bcipy/simulator/demo/demo_group_simulation.py @@ -0,0 +1,215 @@ +""" +This script will loop through all users in the experimental data directory and run simulations using copy phrase data. The primary outcome is to observe how +the task performance changes with different language models across a variety of phrases. This script will output results to a directory defined by OUTPUT_DIR. + +The results will be saved in a directory with the following format: + +```text + +output_dir/ + user1/ + phrase1/ + language_model1/ + user1_phrase1_language_model1_SIM_datetime/ + run_1/ + run_1.log + session.json + session.xlsx + triggers.txt + run_2/ + ... + summary_data.csv + metrics.png + phrase2/ + language_model1/ + user1_phrase2_language_model1_SIM_datetime/ + ... + user2/ + ... + +``` + +The summary data at the simulation run level (summary_data.json) will be the the data used to compare across users, phrases, language models. + +""" +from pathlib import Path +from typing import Optional + +import bcipy.simulator.util.metrics as metrics +from bcipy.io.load import load_json_parameters +from bcipy.simulator.task.task_factory import TaskFactory +from bcipy.simulator.task.task_runner import TaskRunner, init_simulation_dir + +# Define the phrases, starting indeces, and language models to use for the simulation + +# Add phrases and starting indeces to this list +PHRASES = [ + ("I_LOVE_YOU", 0), + ("SEE_YOU_LATER", 4), + ("I_NEED_SOME_HELP", 7), +] +# Add registered BciPy language models by name here +LANGUAGE_MODELS = ["UNIFORM"] + +# Number of runs for each simulation +RUN_COUNT = 2 + +# add a custom output path for simulation output +OUTPUT_DIR = "./" + +# Filter data by file name that will be loaded and used for the simulation +MODE = "RSVP" +DATA_PATTERN = f"{MODE}_Copy_Phrase" + + +def run_simulation( + data_dir: Path, + user: str, + phrase: str, + starting_index: int, + language_model: str, + signal_model_path: Optional[str] = None) -> None: + """Run a simulation for a user, phrase, and language model. + + Optionally, a signal model path can be provided to use a specific signal model for the simulation. + If not provided, the script will search for a signal model in the mode calibration directory for the user. + + Parameters + ---------- + data_dir : Path + The path to the experimental data directory. + user : str + The user name. + phrase : str + The phrase to type. + starting_index : int + The starting index of the phrase. + language_model : str + The language model to use. + signal_model_path : Optional[str], optional + The path to the signal model to use for the simulation, by default None. + If not provided, the script will search for a signal model in the mode calibration directory. + Note*: The output structure in `init_simulation_dir` below should be updated to reflect the + signal model used if varying signal models. + + Raises + ------ + FileNotFoundError + I. If the signal model path is not provided and a signal model cannot be found in the mode calibration directory. + II. If a data directory cannot be found for the user. + + Outputs + ------- + The simulation results will be saved in the output directory defined by OUTPUT_DIR. + """ + print( + f"Running simulation for {user} with phrase {phrase} and language model {language_model}") + + model_path = None + params_path = None + mode_calibration_dir = None + # load the parameters and model for the simulation from the mode calibration directory + + if not signal_model_path: + + for file in data_dir.iterdir(): + if file.is_dir() and MODE in file.name and "Calibration" in file.name: + mode_calibration_dir = file + # search for a pkl file + for pkl_file in mode_calibration_dir.iterdir(): + if pkl_file.is_file() and pkl_file.suffix == ".pkl": + model_path = pkl_file + break + if not model_path: + raise FileNotFoundError( + f"Could not find a model file in {mode_calibration_dir}") + else: + model_path = signal_model_path + + print(f"Using signal model: {model_path}") + + # load the parameters + params_path = mode_calibration_dir / "parameters.json" + parameters = load_json_parameters(params_path, value_cast=True) + + # update the parameters with the new phrase, starting index, and language model + phrase_length = len(phrase) - starting_index + print( + f"Processing {user}:{phrase}:{language_model} of phrase length: {phrase_length}") + parameters["task_text"] = phrase + parameters["spelled_letters_count"] = starting_index + parameters["lang_model_type"] = language_model + + # Below are task constraints that impact typing speed and letter selection. Here we use criteria based on phrase length + # and some sensible defaults. + parameters["max_inq_len"] = phrase_length * 8 + # This should be 2 * the length of the phrase to type + parameters["max_selections"] = phrase_length * 2 + parameters["min_inq_per_series"] = 1 + parameters["max_inq_per_series"] = 8 + parameters["backspace_always_shown"] = True + parameters["summarize_session"] = False + parameters["lm_backspace_prob"] = 0.03571 + # signal model decision threshold for letter selection + parameters["decision_threshold"] = 0.8 + # This is not used in the simulation. But we set it high to avoid any issues. + parameters["max_minutes"] = 120 + # This should be half the length of the phrase to type + parameters["max_incorrect"] = int(phrase_length / 2) + + # get the correct list of source directories from the data directory + source_dirs = [str(file) for file in data_dir.iterdir() + if file.is_dir() and DATA_PATTERN in file.name] + if not source_dirs: + raise FileNotFoundError(f"Could not find a data directory for {user}") + + # Construct the simulation task factory and output directory strucutre + task_factory = TaskFactory(source_dirs=source_dirs, + signal_model_paths=[str(model_path)], + parameters=parameters) + sim_dir = init_simulation_dir( + save_location=Path(OUTPUT_DIR), + prefix=f"{user}/{language_model}/{phrase}/{user}_{phrase}_{language_model}_") + runner = TaskRunner(save_dir=sim_dir, + task_factory=task_factory, + runs=RUN_COUNT) + # run the simulation and output the metrics + try: + runner.run() + metrics.report(sim_dir) + except Exception as e: + print( + f"Error running simulation for {user} with phrase {phrase} and language model {language_model}") + print(e) + + +if __name__ == "__main__": + from pathlib import Path + + from tqdm import tqdm + + from bcipy.io.load import load_experimental_data + + # load experimental directory. This will have users/run/data + data_dir = Path(load_experimental_data()) + + progress_bar = tqdm( + Path(data_dir).iterdir(), + total=len(list(Path(data_dir).iterdir())), + bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt} [est. {remaining}][ela. {elapsed}]\n", + colour='MAGENTA') + + # Loop over all the users, phrases and language models defined. + # Optionally, a signal model could be provided using the signal_model_path parameter. + # This is available in case the trained model is not in the mode calibration directory. It could be used to evaluate different signal models. + # We recommend changing the init_simulation_dir with some model name + # indicator to help with organizing the output for analysis. + for user in progress_bar: + if user.is_dir(): + progress_bar.set_description(f"Processing {user.name}") + for phrase, starting_index in PHRASES: + for language_model in LANGUAGE_MODELS: + run_simulation(user, user.name, phrase, + starting_index, language_model) + + progress_bar.close() diff --git a/bcipy/simulator/exceptions.py b/bcipy/simulator/exceptions.py index a7f3bad15..80e69a27d 100644 --- a/bcipy/simulator/exceptions.py +++ b/bcipy/simulator/exceptions.py @@ -1,6 +1,5 @@ class DeviceSpecNotFoundError(Exception): - """Thrown when a suitable DeviceSpec was not found in the devices.json file - """ + """Thrown when a suitable DeviceSpec was not found in the devices.json file.""" class IncompatibleData(Exception): @@ -15,4 +14,9 @@ class IncompatibleDeviceSpec(IncompatibleData): class IncompatibleParameters(IncompatibleData): """Thrown when the timing parameters used for data collection are - incompatible with the timing parameters of the simulation.""" + incompatible with the timing parameters of the simulation. + """ + + +class IncompatibleSampler(Exception): + """Thrown when the provided sampler is incompatible with a given task.""" diff --git a/bcipy/simulator/task/copy_phrase.py b/bcipy/simulator/task/copy_phrase.py index 40f242f0a..fa8a1fb76 100644 --- a/bcipy/simulator/task/copy_phrase.py +++ b/bcipy/simulator/task/copy_phrase.py @@ -1,20 +1,23 @@ -# mypy: disable-error-code="union-attr" +# mypy: disable-error-code="union-attr, override" """Simulates the Copy Phrase task""" -from typing import Any, Dict, List, Optional, Tuple import logging +from pathlib import Path +from typing import Any, Dict, List, Optional, Tuple +from bcipy.acquisition.multimodal import ClientManager +from bcipy.core.parameters import Parameters +from bcipy.core.stimuli import InquirySchedule from bcipy.display.main import Display from bcipy.feedback.visual.visual_feedback import VisualFeedback -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.stimuli import InquirySchedule from bcipy.language.main import LanguageModel from bcipy.signal.model.base_model import SignalModel from bcipy.simulator.data.sampler import Sampler +from bcipy.simulator.task.null_daq import NullDAQ from bcipy.simulator.task.null_display import NullDisplay from bcipy.simulator.util.state import SimState +from bcipy.task import TaskMode from bcipy.task.control.evidence import EvidenceEvaluator from bcipy.task.data import EvidenceType -from bcipy.task import TaskMode from bcipy.task.paradigm.rsvp.copy_phrase import RSVPCopyPhraseTask DEFAULT_EVIDENCE_TYPE = EvidenceType.ERP @@ -34,12 +37,14 @@ def get_evidence_type(model: SignalModel) -> EvidenceType: try: return EvidenceType(evidence_type) except ValueError: - raise ValueError(f"Unsupported evidence type: {evidence_type}. Supported types: {EvidenceType.list()}") + raise ValueError( + f"Unsupported evidence type: {evidence_type}. Supported types: {EvidenceType.list()}") class SimulatorCopyPhraseTask(RSVPCopyPhraseTask): """CopyPhraseTask that simulates user interactions by sampling data - from a DataSampler.""" + from a DataSampler. + """ name = "Simulator Copy Phrase" paradigm = "RSVP" @@ -64,7 +69,7 @@ def setup( data_save_location: str, fake: bool = False) -> Tuple[Any, Any, Display]: """Override the setup method to avoid initializing the data acquisition.""" - daq = None + daq = self.init_acquisition() server = None display = self.init_display() self.initalized = True @@ -80,6 +85,7 @@ def get_language_model(self): def init_evidence_evaluators( self, signal_models: List[SignalModel]) -> List[EvidenceEvaluator]: + """Initialize evidence evaluators for the simulation (returns empty list).""" # Evidence will be sampled so we don't need to evaluate raw data. return [] @@ -87,17 +93,25 @@ def init_evidence_types( self, signal_models: List[SignalModel], evidence_evaluators: List[EvidenceEvaluator] ) -> List[EvidenceType]: + """Initialize evidence types for the simulation.""" evidence_types = set( [get_evidence_type(model) for model in self.signal_models]) return [EvidenceType.LM, *evidence_types] def init_display(self) -> Display: + """Initialize the display for the simulation (returns NullDisplay).""" return NullDisplay() + def init_acquisition(self) -> ClientManager: + """Override to do nothing.""" + return NullDAQ() + def init_feedback(self) -> Optional[VisualFeedback]: + """Initialize feedback for the simulation (returns None).""" return None def user_wants_to_continue(self) -> bool: + """Always continue for simulation purposes.""" return True def wait(self, seconds: Optional[float] = None) -> None: @@ -106,8 +120,7 @@ def wait(self, seconds: Optional[float] = None) -> None: def present_inquiry( self, inquiry_schedule: InquirySchedule ) -> Tuple[List[Tuple[str, float]], bool]: - """Override ; returns empty timing info; always proceed for inquiry - preview""" + """Override; returns empty timing info; always proceed for inquiry preview.""" return [], True def show_feedback(self, selection: str, correct: bool = True) -> None: @@ -115,16 +128,18 @@ def show_feedback(self, selection: str, correct: bool = True) -> None: def compute_button_press_evidence( self, proceed: bool) -> Optional[Tuple[EvidenceType, List[float]]]: + """Compute button press evidence for simulation (returns None).""" return None def compute_device_evidence( self, stim_times: List[List], proceed: bool = True) -> List[Tuple[EvidenceType, List[float]]]: + """Compute device evidence for simulation.""" current_state = self.get_sim_state() - self.logger.info("Computing evidence with sim_state:") - self.logger.info(current_state) + self.logger.debug("Computing evidence with sim_state:") + self.logger.debug(current_state) evidences = [] @@ -133,7 +148,7 @@ def compute_device_evidence( # This assumes that sampling is independent. Changes to the sampler API are needed if # we need to provide the trial context of the last sample. sampled_data = sampler.sample_data(current_state) - evidence = model.compute_class_probabilities( + evidence = model.compute_likelihood_ratio( sampled_data, self.current_symbols(), self.alp) @@ -141,10 +156,21 @@ def compute_device_evidence( evidences.append((evidence_type, evidence)) return evidences + def cleanup(self): + """Cleanup after simulation, including saving session data and removing empty trigger files.""" + self.save_session_data() + trigger_path = Path(self.trigger_handler.file_path) + self.trigger_handler.close() + + # delete empty triggers.txt file + if trigger_path.exists() and trigger_path.is_file(): + trigger_path.unlink(missing_ok=True) + def exit_display(self) -> None: """Close the UI and cleanup.""" def elapsed_seconds(self) -> float: + """Return elapsed seconds for simulation (always 0.0).""" return 0.0 def write_offset_trigger(self) -> None: diff --git a/bcipy/simulator/task/null_daq.py b/bcipy/simulator/task/null_daq.py new file mode 100644 index 000000000..4aaed7e4b --- /dev/null +++ b/bcipy/simulator/task/null_daq.py @@ -0,0 +1,18 @@ +"""DAQ that doesn't do anything""" +from bcipy.acquisition.multimodal import ClientManager + + +class NullDAQ(ClientManager): + """DAQ that doesn't do anything.""" + + def start_acquisition(self) -> None: + """Do nothing""" + + def stop_acquisition(self) -> None: + """Do nothing""" + + def cleanup(self) -> None: + """Do nothing""" + + def get_data_by_device(self, *args, **kwargs) -> None: + """Do nothing""" diff --git a/bcipy/simulator/task/null_display.py b/bcipy/simulator/task/null_display.py index e59c07f02..3db159c7b 100644 --- a/bcipy/simulator/task/null_display.py +++ b/bcipy/simulator/task/null_display.py @@ -6,9 +6,11 @@ class NullDisplay(Display): """Display that doesn't show anything to the user. Useful in simulated tasks - that do not have a display component.""" + that do not have a display component. + """ def do_inquiry(self) -> List[Tuple[str, float]]: + """Perform an inquiry and return an empty list (no display).""" return [] def wait_screen(self, *args, **kwargs) -> None: @@ -16,3 +18,6 @@ def wait_screen(self, *args, **kwargs) -> None: def update_task_bar(self, *args, **kwargs) -> None: """Do nothing""" + + def close(self) -> None: + """Do nothing""" diff --git a/bcipy/simulator/task/replay_session.py b/bcipy/simulator/task/replay_session.py new file mode 100644 index 000000000..df60e7fb4 --- /dev/null +++ b/bcipy/simulator/task/replay_session.py @@ -0,0 +1,74 @@ +"""Task that will replay sessions to compare model predictions on that data. +Used for testing if changes to a model result in more easily differentiated signals. +""" + +import argparse +import logging +from pathlib import Path + +from bcipy.io.load import load_json_parameters +from bcipy.simulator.data.sampler.replay_sampler import ReplaySampler +from bcipy.simulator.task.replay_task import ReplayTask +from bcipy.simulator.task.task_factory import TaskFactory +from bcipy.simulator.task.task_runner import TaskRunner +from bcipy.simulator.util.artifact import (DEFAULT_SAVE_LOCATION, + TOP_LEVEL_LOGGER_NAME, + init_simulation_dir) +from bcipy.simulator.util.replay_comparison import comparison_metrics + +logger = logging.getLogger(TOP_LEVEL_LOGGER_NAME) + + +def main(): + """Run the task""" + parser = argparse.ArgumentParser() + data_help = ('Raw data folders to be processed.' + ' Multiple values can be provided.') + parser.add_argument("-d", + "--data_folder", + type=Path, + required=False, + action='append', + help=data_help) + parser.add_argument("-m", + "--model_path", + type=Path, + required=True, + help="Signal model to be used.") + parser.add_argument("-p", + "--parameters", + type=Path, + required=False, + help="Parameter File to be used") + parser.add_argument("-o", + "--output", + type=Path, + required=False, + default=DEFAULT_SAVE_LOCATION, + help="Sim output path") + args = parser.parse_args() + sim_args = vars(args) + + runs = len(sim_args['data_folder']) + outdir = sim_args['output'] + + parameters = load_json_parameters(sim_args['parameters'], value_cast=True) + + task_factory = TaskFactory(parameters=parameters, + source_dirs=sim_args['data_folder'], + signal_model_paths=[sim_args['model_path']], + sampling_strategy=ReplaySampler, + task=ReplayTask) + + sim_dir = init_simulation_dir(save_location=outdir) + logger.info(sim_dir) + task_factory.log_state() + + runner = TaskRunner(save_dir=sim_dir, task_factory=task_factory, runs=runs) + runner.run() + + comparison_metrics(sim_dir, sim_args['data_folder']) + + +if __name__ == '__main__': + main() diff --git a/bcipy/simulator/task/replay_task.py b/bcipy/simulator/task/replay_task.py new file mode 100644 index 000000000..84035e212 --- /dev/null +++ b/bcipy/simulator/task/replay_task.py @@ -0,0 +1,140 @@ +from pathlib import Path +from typing import Dict, List, Tuple + +from bcipy.config import SESSION_DATA_FILENAME +from bcipy.core.parameters import Parameters +from bcipy.core.session import read_session +from bcipy.core.stimuli import InquirySchedule +from bcipy.language.main import LanguageModel +from bcipy.signal.model.base_model import SignalModel +from bcipy.simulator.data.sampler.base_sampler import Sampler +from bcipy.simulator.data.sampler.replay_sampler import ReplaySampler +from bcipy.simulator.exceptions import IncompatibleSampler +from bcipy.simulator.task.copy_phrase import SimulatorCopyPhraseTask +from bcipy.simulator.util.state import SimState +from bcipy.task.data import EvidenceType, Inquiry +from bcipy.task.main import TaskData, TaskMode + + +def clone_inquiry(original_inquiry: Inquiry) -> Inquiry: + """Construct a new inquiry data record.""" + new_inquiry = Inquiry( + original_inquiry.stimuli, + timing=original_inquiry.timing, + triggers=original_inquiry.triggers, + target_info=original_inquiry.target_info, + target_letter=original_inquiry.target_letter, + current_text=original_inquiry.current_text, + target_text=original_inquiry.target_text, + selection=original_inquiry.selection, + next_display_state=original_inquiry.next_display_state) + new_inquiry.precision = original_inquiry.precision + return new_inquiry + + +class ReplayTask(SimulatorCopyPhraseTask): + """Task to replay a session and record predictions on that data for a new model.""" + + name = "Replay Session" + mode = TaskMode.COPYPHRASE + + def __init__(self, parameters: Parameters, file_save: str, + signal_models: List[SignalModel], + language_model: LanguageModel, samplers: Dict[SignalModel, + Sampler]): + super().__init__(parameters, file_save, signal_models, language_model, + samplers) + + if len(signal_models) > 1: + self.logger.warning("Only the first provided model will be used.") + + self.signal_model = signal_models[0] + self.sampler = samplers[self.signal_model] + + if not isinstance(self.sampler, ReplaySampler): + raise IncompatibleSampler( + "ReplaySampler is the only supported sampler for this task") + + def execute(self) -> TaskData: + """Executes the task. + + Returns + ------- + data save location (triggers.txt, session.json) + """ + # assertion to avoid typing error + assert isinstance(self.sampler, + ReplaySampler), "Sampler must be ReplaySampler" + + self.logger.info("Starting Replay Task!") + data_folder = self.sampler.current_source + original_session = read_session( + str(Path(data_folder, SESSION_DATA_FILENAME))) + + # Iterate through original session. + for series_n, series in enumerate(original_session.series): + for inquiry_n, inquiry in enumerate(series): + + # Variables used to generate sim state for sampling. + self.current_inquiry = InquirySchedule( + stimuli=inquiry.stimuli, + durations=inquiry.timing, + colors=[]) + self.series_n = series_n + 1 # 1-based index + self.inquiry_n = inquiry_n + self.inquiry = inquiry + + evidence_types = self.add_evidence(stim_times=[], proceed=True) + + # we only need to evaluate_evidence to involve the copy phrase wrapper + # for combined likelihood. If that's not used it can be deleted. + _decision = self.evaluate_evidence() + + data = clone_inquiry(inquiry) + evidence = self.copy_phrase_task.conjugator.latest_evidence + data.evidences = { + ev_type: ev_data if ev_type in evidence_types else [] + for ev_type, ev_data in evidence.items() + } + data.likelihood = list( + self.copy_phrase_task.conjugator.likelihood) + + # Set decision_made to False since we are manually calling add_series. + self.update_session_data(data, save=True, decision_made=False) + self.session.add_series() + + self.sampler.next_source() + self.cleanup() + + return TaskData(save_path=self.file_save, + task_dict=self.session.as_dict()) + + def compute_device_evidence( + self, + stim_times: List[List], + proceed: bool = True) -> List[Tuple[EvidenceType, List[float]]]: + """Override to compute the model evidence based on the current state.""" + assert self.signal_model, "Signal model is required" + + current_state = self.get_sim_state() + self.logger.info("Computing evidence with sim_state:") + self.logger.info(current_state) + + sampled_data = self.sampler.sample_data(current_state) + evidence = self.signal_model.compute_likelihood_ratio( + sampled_data, current_state.display_alphabet, self.alp) + evidences = [(EvidenceType.ERP, evidence)] + + return evidences + + def get_sim_state(self) -> SimState: + """Get the current state in the format expected by the simulation tools.""" + + return SimState( + target_symbol=self.inquiry.target_letter or '', + current_sentence=self.inquiry.current_text or '', + target_sentence=self.inquiry.target_text or '', + # without the '+' fixation + display_alphabet=self.inquiry.stimuli[1:], + inquiry_n=self.inquiry_n, + series_n=self.series_n) diff --git a/bcipy/simulator/task/task_factory.py b/bcipy/simulator/task/task_factory.py index 4de38fe0b..aacdc8784 100644 --- a/bcipy/simulator/task/task_factory.py +++ b/bcipy/simulator/task/task_factory.py @@ -1,13 +1,13 @@ """Classes and functions for building a simulation.""" import logging -from typing import Dict, List, Type +from typing import Any, Dict, List, Optional, Type +from bcipy.core.parameters import DEFAULT_PARAMETERS_PATH, Parameters from bcipy.helpers.language_model import init_language_model -from bcipy.helpers.load import load_json_parameters, load_signal_models -from bcipy.helpers.parameters import DEFAULT_PARAMETERS_PATH +from bcipy.io.load import load_json_parameters, load_signal_model from bcipy.signal.model.base_model import SignalModel from bcipy.simulator.data.data_engine import RawDataEngine -from bcipy.simulator.data.data_process import init_data_processor +from bcipy.simulator.data.processor_registry import init_data_processor from bcipy.simulator.data.sampler import Sampler, TargetNontargetSampler from bcipy.simulator.task.copy_phrase import SimulatorCopyPhraseTask from bcipy.simulator.util.artifact import TOP_LEVEL_LOGGER_NAME @@ -15,47 +15,78 @@ logger = logging.getLogger(TOP_LEVEL_LOGGER_NAME) -class TaskFactory(): - """Constructs the hierarchy of objects necessary for initializing a task.""" +def update_latest_params(parameters: Parameters) -> None: + """Update the given parameters with the latest missing values""" + default_params = load_json_parameters(DEFAULT_PARAMETERS_PATH, + value_cast=True) + added_params = [ + key for key, change in default_params.diff(parameters).items() + if change.original_value is None + ] + if added_params: + logger.info( + f"Added missing parameters using default values: {added_params}") + parameters.add_missing_items(default_params) + + +class TaskFactory: + """Constructs the hierarchy of objects necessary for initializing a task. + + Parameters + ---------- + parameters : Parameters + The parameters to use for the simulation. + source_dirs : List[str] + The directories containing the raw data to be used in the simulation. + signal_model_paths : List[str] + The paths to the signal models to be used for data loaded via source_dirs in the simulation. + sampling_strategy : Type[Sampler], optional + The data sampling strategy to use, by default TargetNontargetSampler. + task : Type[SimulatorCopyPhraseTask], optional + The task to use for simulation, by default SimulatorCopyPhraseTask. This should ideally be + the corresponding task used to generate the data in the source_dirs. + sampler_args : Optional[Dict[str, Any]], optional + Additional arguments to pass to the sampler constructor, by default None. + """ def __init__( self, - params_path: str, - model_path: str, + parameters: Parameters, source_dirs: List[str], + signal_model_paths: List[str], sampling_strategy: Type[Sampler] = TargetNontargetSampler, - task: Type[SimulatorCopyPhraseTask] = SimulatorCopyPhraseTask): - self.params_path = params_path - self.model_path = model_path + task: Type[SimulatorCopyPhraseTask] = SimulatorCopyPhraseTask, + sampler_args: Optional[Dict[str, Any]] = None): + + self.signal_model_paths = signal_model_paths + self.source_dirs = source_dirs self.sampling_strategy = sampling_strategy + self.sampler_args = sampler_args if sampler_args else {} self.simulation_task = task - logger.info("Loading parameters") - self.parameters = load_json_parameters(self.params_path, - value_cast=True) - default_params = load_json_parameters(DEFAULT_PARAMETERS_PATH, - value_cast=True) + self.parameters = parameters - added_params = [ - key - for key, change in default_params.diff(self.parameters).items() - if change.original_value is None - ] - logger.info( - f"Added missing parameters using default values: {added_params}") - self.parameters.add_missing_items(default_params) + update_latest_params(self.parameters) logger.info("Loading signal models") - self.signal_models = load_signal_models(directory=self.model_path) - logger.debug(self.signal_models) + self.signal_models = [ + load_signal_model(path) for path in signal_model_paths + ] logger.info("Initializing language model") self.language_model = init_language_model(self.parameters) - logger.debug(self.language_model) - self.samplers = self.init_samplers(self.signal_models) - logger.debug(self.samplers) + + def log_state(self): + """Log configured objects of interest. This should be done after the + sim directory has been created and TOP_LEVEL_LOGGER has been configured, + which may happen some time after object construction. + """ + logger.debug("Language model:") + logger.debug(f"\t{repr(self.language_model)}") + logger.debug("Models -> Samplers:") + logger.debug(f"\t{self.samplers}") def init_samplers( self, @@ -73,7 +104,7 @@ def init_samplers( engine = RawDataEngine(list(map(str, self.source_dirs)), self.parameters, data_processor=processor) - sampler = self.sampling_strategy(engine) + sampler = self.sampling_strategy(engine, **self.sampler_args) samplers[model] = sampler return samplers diff --git a/bcipy/simulator/task/task_runner.py b/bcipy/simulator/task/task_runner.py index 17cacce27..b5120e681 100644 --- a/bcipy/simulator/task/task_runner.py +++ b/bcipy/simulator/task/task_runner.py @@ -1,93 +1,176 @@ """Setup and run the task""" - import argparse +import json import logging -from glob import glob +import sys from pathlib import Path +from typing import Any, Dict + +from rich.progress import track -from bcipy.simulator.data.sampler import TargetNontargetSampler +import bcipy.simulator.util.metrics as metrics +from bcipy.io.load import load_json_parameters +# pylint: disable=wildcard-import,unused-wildcard-import +# flake8: noqa +from bcipy.simulator.data.sampler import * from bcipy.simulator.task.copy_phrase import SimulatorCopyPhraseTask from bcipy.simulator.task.task_factory import TaskFactory -from bcipy.simulator.util.artifact import (TOP_LEVEL_LOGGER_NAME, +from bcipy.simulator.ui import cli, gui +from bcipy.simulator.util.artifact import (DEFAULT_SAVE_LOCATION, + TOP_LEVEL_LOGGER_NAME, configure_run_directory, - init_simulation_dir) + init_simulation_dir, + remove_handlers, set_verbose) logger = logging.getLogger(TOP_LEVEL_LOGGER_NAME) +def classify(classname): + """Convert the given class name to a class.""" + return getattr(sys.modules[__name__], classname) + + +def parse_args(args: str) -> Dict[str, Any]: + """Converts sampler command line args to a dictionary of parameters to be + passed to the constructor. + + Parameters + ---------- + args - str formatted as a valid JSON object. + """ + return json.loads(args) + + class TaskRunner(): """Responsible for executing a task a given number of times.""" def __init__(self, save_dir: str, task_factory: TaskFactory, - runs: int = 1): + runs: int = 1, + verbose: bool = True): self.task_factory = task_factory self.sim_dir = save_dir self.runs = runs + self.verbose = verbose def run(self) -> None: """Run one or more simulations""" - self.task_factory.parameters.save(self.sim_dir) - for i in range(self.runs): - logger.info(f"Executing task {i+1}") + self.task_factory.parameters.save(self.sim_dir, 'parameters.json') + for i in track(range(self.runs), description="Processing..."): self.do_run(i + 1) - logger.info("Task complete") def do_run(self, run: int): """Execute a simulation run.""" - run_dir = configure_run_directory(self.sim_dir, run) - logger.info(run_dir) + logger.debug(f"Executing task {run}") + run_dir, run_log = configure_run_directory(self.sim_dir, run) + logger.debug(run_dir) task = self.task_factory.make_task(run_dir) task.execute() + logger.debug("Task complete") + remove_handlers(run_log) def main(): """Run the task""" glob_help = ('glob pattern to select a subset of data folders' - ' Ex. "*RSVP_Copy_Phrase*"') + ' Ex. "*RSVP_Copy_Phrase*"' + ' Used with a single data_folder') + data_help = ( + 'Raw data folders to be processed.' + ' Multiple values can be provided, or a single parent folder.') parser = argparse.ArgumentParser() + parser.add_argument( + "-i", + "--interactive", + required=False, + default=False, + action='store_true', + help="Use interactive command line for selecting simulator inputs") + parser.add_argument( + "--gui", + required=False, + default=False, + action='store_true', + help="Use interactive GUI for selecting simulator inputs") parser.add_argument("-d", "--data_folder", type=Path, - required=True, - help="Raw data folders to be processed.") - parser.add_argument('-g', '--glob_pattern', help=glob_help, default="*") - parser.add_argument("-m", - "--model_path", - type=Path, - required=True, - help="Signal models to be used") + required=False, + action='append', + help=data_help) + parser.add_argument( + "-m", + "--model_path", + type=Path, + action='append', + required=False, + help="Signal models to be used. Multiple models can be provided.") parser.add_argument("-p", "--parameters", type=Path, - required=True, + required=False, help="Parameter File to be used") parser.add_argument("-n", type=int, required=False, default=1, help="Number of times to run the simulation") + parser.add_argument("-s", + "--sampler", + type=str, + required=False, + default='TargetNontargetSampler', + help="Sampling strategy") + parser.add_argument("--sampler_args", + type=str, + required=False, + default="{}", + help="Sampler args structured as a JSON string.") + parser.add_argument("-o", + "--output", + type=Path, + required=False, + default=DEFAULT_SAVE_LOCATION, + help="Sim output path") + parser.add_argument("-v", + "--verbose", + action='store_true', + help="Verbose mode for more detailed logging.") args = parser.parse_args() sim_args = vars(args) - sim_args['source_dirs'] = [ - Path(d) for d in glob(str(Path(args.data_folder, args.glob_pattern))) - if Path(d).is_dir() - ] - - sim_dir = init_simulation_dir() - logger.info(sim_dir) - task_factory = TaskFactory(params_path=sim_args['parameters'], - model_path=sim_args['model_path'], - source_dirs=sim_args['source_dirs'], - sampling_strategy=TargetNontargetSampler, - task=SimulatorCopyPhraseTask) - runner = TaskRunner(save_dir=sim_dir, - task_factory=task_factory, - runs=sim_args['n']) - runner.run() + runs = sim_args['n'] + outdir = sim_args['output'] + + if args.gui: + runs, outdir, task_factory = gui.configure() + elif args.interactive: + task_factory = cli.main(sim_args) + else: + parameters = load_json_parameters( + sim_args['parameters'], value_cast=True) + task_factory = TaskFactory( + parameters=parameters, + source_dirs=sim_args['data_folder'], + signal_model_paths=sim_args['model_path'], + sampling_strategy=classify(sim_args['sampler']), + task=SimulatorCopyPhraseTask, + sampler_args=parse_args(sim_args['sampler_args'])) + + if sim_args['verbose']: + set_verbose(True) + if task_factory: + sim_dir = init_simulation_dir(save_location=outdir) + logger.info(sim_dir) + task_factory.log_state() + + runner = TaskRunner(save_dir=sim_dir, + task_factory=task_factory, + runs=runs) + runner.run() + metrics.report(sim_dir) if __name__ == '__main__': diff --git a/bcipy/simulator/tests/resources/btn_subset_parameters.json b/bcipy/simulator/tests/resources/btn_subset_parameters.json new file mode 100644 index 000000000..c8048d991 --- /dev/null +++ b/bcipy/simulator/tests/resources/btn_subset_parameters.json @@ -0,0 +1,127 @@ +{ + "acq_mode": { + "value": "EEG+MARKERS", + "section": "acq_config", + "name": "Acquisition Mode", + "helpTip": "Specifies the hardware device(s) used for data collection. Default: EEG", + "recommended": [ + "EEG", + "EEG/DSI-24", + "Eyetracker", + "EEG+Eyetracker" + ], + "type": "str", + "editable": false + }, + "trial_window": { + "value": "0.2:0.7", + "section": "bci_config", + "name": "Trial Classification Window Length", + "helpTip": "Specifies the window (in seconds) of the EEG data collection window after each stimulus presentation. Default: 0.0:0.5", + "recommended": [ + "0.0:0.5", + "0.0:0.8", + "0.2:0.8" + ], + "type": "range", + "editable": false + }, + "prestim_length": { + "value": "1", + "section": "bci_config", + "name": "Prestimulus Window Length", + "helpTip": "Specifies the length (in seconds) of the EEG data window to return before inquiry presentation. Default: 1", + "recommended": "", + "type": "float", + "editable": false + }, + "task_buffer_length": { + "value": "2", + "section": "bci_config", + "name": "Inter-inquiry Interval", + "helpTip": "Specifies the delay time (in seconds) between the final stimulus in one inquiry and the beginning (target stimulus or fixation cross) of the next inquiry in a task. Default: 2", + "recommended": "", + "type": "float", + "editable": false + }, + "stim_length": { + "value": "10", + "section": "bci_config", + "name": "Stimuli Per inquiry", + "helpTip": "Specifies the number of stimuli to present in each inquiry. Default: 10", + "recommended": "", + "type": "int", + "editable": false + }, + "time_flash": { + "value": "0.20", + "section": "bci_config", + "name": "Stimulus Presentation Duration", + "helpTip": "Specifies the duration of time (in seconds) that each stimulus is displayed in an inquiry.", + "recommended": "", + "type": "float", + "editable": false + }, + "show_preview_inquiry": { + "value": "false", + "section": "bci_config", + "name": "Preview Inquiry On/Off", + "helpTip": "If \u2018true\u2019, the inquiry will be previewed as applicable for the task. *Note* Not all tasks will have this enabled!", + "recommended": "", + "type": "bool", + "editable": false + }, + "preview_inquiry_progress_method": { + "value": "1", + "section": "bci_config", + "name": "Preview Inquiry Progression Method", + "helpTip": "If show_preview_inquiry true, this will determine how to proceed after a key hit. 0 = preview only; 1 = press to confirm; 2 = press to skip to another inquiry", + "recommended": [ + "0", + "1", + "2" + ], + "type": "int", + "editable": false + }, + "preview_inquiry_length": { + "value": "5", + "section": "bci_config", + "name": "Preview Inquiry Display Length", + "helpTip": "Length of time in seconds to present an inquiry preview to the user.", + "recommended": "", + "type": "float", + "editable": false + }, + "preview_inquiry_key_input": { + "value": "return", + "section": "bci_config", + "name": "Preview Inquiry Display Key Input Method", + "helpTip": "Defines the key used to engage with inquiry preview.", + "recommended": [ + "space", + "escape", + "return" + ], + "type": "str", + "editable": false + }, + "preview_inquiry_isi": { + "value": "1", + "section": "bci_config", + "name": "Preview Inquiry Inter-Stimulus Interval", + "helpTip": "The time between previewing an inquiry and the start of an inquiry.", + "recommended": "", + "type": "float", + "editable": false + }, + "preview_box_text_size": { + "value": "0.1", + "section": "task_config", + "name": "Preview Inquiry Box Text Size", + "helpTip": "Specifies the height of text stimuli in the preview inquiry box. See https://www.psychopy.org/general/units.html. Default: 0.1", + "recommended": "", + "editable": false, + "type": "float" + } +} \ No newline at end of file diff --git a/bcipy/simulator/tests/resources/markers_data_switch.csv b/bcipy/simulator/tests/resources/markers_data_switch.csv new file mode 100644 index 000000000..d5a390f00 --- /dev/null +++ b/bcipy/simulator/tests/resources/markers_data_switch.csv @@ -0,0 +1,17 @@ +daq_type,Switch +sample_rate,0 +timestamp,Marker,lsl_timestamp +1,1.0,6409.3349438000005 +2,1.0,6415.4949134 +3,1.0,6421.6229766 +4,1.0,6427.7268517 +5,1.0,6433.8069707 +6,1.0,6441.9749359 +7,1.0,6450.3189464 +8,1.0,6456.342932199999 +9,1.0,6462.4309103000005 +10,1.0,6468.4149259 +11,1.0,6474.414876 +12,1.0,6480.2709153999995 +13,1.0,6488.694970699999 +14,1.0,6500.3589364 \ No newline at end of file diff --git a/bcipy/simulator/tests/resources/session.json b/bcipy/simulator/tests/resources/session.json new file mode 100644 index 000000000..388b22d1a --- /dev/null +++ b/bcipy/simulator/tests/resources/session.json @@ -0,0 +1,386 @@ +{ + "session": "/Users/lawhead/workspace/bci/BciPy/data/simulator/SIM_12-18-2024_17_12_58/run_1", + "task": "Copy Phrase", + "mode": "copy phrase", + "symbol_set": [ + "A", + "B", + "C", + "D", + "E", + "F", + "G", + "H", + "I", + "J", + "K", + "L", + "M", + "N", + "O", + "P", + "Q", + "R", + "S", + "T", + "U", + "V", + "W", + "X", + "Y", + "Z", + "<", + "_" + ], + "decision_threshold": 0.8, + "series": { + "1": { + "0": { + "stimuli": [ + [ + "+", + "S", + "D", + "X", + "K", + "H", + "_", + "E", + "C", + "R", + "W" + ] + ], + "timing": [ + [ + 0.5, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2 + ] + ], + "triggers": [], + "target_info": [], + "target_letter": "A", + "current_text": "", + "target_text": "ASK_A_QUESTION", + "selection": "", + "next_display_state": "", + "lm_evidence": [ + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571, + 0.03571 + ], + "eeg_evidence": [ + 1.0, + 1.0, + 0.0145, + 0.94859, + 0.01, + 1.0, + 1.0, + 0.39689, + 1.0, + 1.0, + 0.31747, + 1.0, + 1.0, + 1.0, + 1.0, + 1.0, + 1.0, + 0.11467, + 0.34407, + 1.0, + 1.0, + 1.0, + 0.44074, + 0.14787, + 1.0, + 1.0, + 1.0, + 0.43638 + ], + "likelihood": [ + 0.04723, + 0.04723, + 0.00068, + 0.04481, + 0.00047, + 0.04723, + 0.04723, + 0.01875, + 0.04723, + 0.04723, + 0.015, + 0.04723, + 0.04723, + 0.04723, + 0.04723, + 0.04723, + 0.04723, + 0.00542, + 0.01625, + 0.04723, + 0.04723, + 0.04723, + 0.02082, + 0.00698, + 0.04723, + 0.04723, + 0.04723, + 0.02061 + ] + }, + "1": { + "stimuli": [ + [ + "+", + "Y", + "Z", + "O", + "I", + "M", + "<", + "P", + "G", + "N", + "B" + ] + ], + "timing": [ + [ + 0.5, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2 + ] + ], + "triggers": [], + "target_info": [], + "target_letter": "A", + "current_text": "", + "target_text": "ASK_A_QUESTION", + "selection": "", + "next_display_state": "", + "lm_evidence": [], + "eeg_evidence": [ + 1.0, + 0.12321, + 1.0, + 1.0, + 1.0, + 1.0, + 0.01, + 1.0, + 0.01269, + 1.0, + 1.0, + 1.0, + 0.43755, + 0.40155, + 0.02363, + 0.37681, + 1.0, + 1.0, + 1.0, + 1.0, + 1.0, + 1.0, + 1.0, + 1.0, + 0.05845, + 0.39573, + 0.43228, + 1.0 + ], + "likelihood": [ + 0.07439, + 0.00917, + 0.00108, + 0.07056, + 0.00074, + 0.07439, + 0.00074, + 0.02952, + 0.00094, + 0.07439, + 0.02362, + 0.07439, + 0.03255, + 0.02987, + 0.00176, + 0.02803, + 0.07439, + 0.00853, + 0.02559, + 0.07439, + 0.07439, + 0.07439, + 0.03279, + 0.011, + 0.00435, + 0.02944, + 0.03216, + 0.03246 + ] + }, + "2": { + "stimuli": [ + [ + "+", + "T", + "J", + "W", + "D", + "L", + "V", + "U", + "A", + "F", + "Q" + ] + ], + "timing": [ + [ + 0.5, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2, + 0.2 + ] + ], + "triggers": [], + "target_info": [], + "target_letter": "A", + "current_text": "", + "target_text": "ASK_A_QUESTION", + "selection": "A", + "next_display_state": "A", + "lm_evidence": [], + "eeg_evidence": [ + 100.0, + 1.0, + 1.0, + 0.14948, + 1.0, + 0.04914, + 1.0, + 1.0, + 1.0, + 0.01, + 1.0, + 0.01, + 1.0, + 1.0, + 1.0, + 1.0, + 0.13505, + 1.0, + 1.0, + 2.77386, + 0.065, + 0.19065, + 0.27223, + 1.0, + 1.0, + 1.0, + 1.0, + 1.0 + ], + "likelihood": [ + 0.92981, + 0.00115, + 0.00013, + 0.00132, + 9e-05, + 0.00046, + 9e-05, + 0.00369, + 0.00012, + 9e-05, + 0.00295, + 9e-05, + 0.00407, + 0.00373, + 0.00022, + 0.0035, + 0.00126, + 0.00107, + 0.0032, + 0.02579, + 0.0006, + 0.00177, + 0.00112, + 0.00137, + 0.00054, + 0.00368, + 0.00402, + 0.00406 + ] + } + } + }, + "total_time_spent": 0.0, + "total_minutes": 0.0, + "total_number_series": 18, + "total_inquiries": 41, + "total_selections": 18, + "inquiries_per_selection": 2.2777777777777777, + "task_summary": { + "selections_correct": 16, + "selections_incorrect": 2, + "selections_correct_symbols": 14, + "switch_total": 0, + "switch_per_selection": 0.0, + "switch_response_time": null, + "typing_accuracy": 0.8888888888888888, + "correct_rate": 0, + "copy_rate": 0 + } + } \ No newline at end of file diff --git a/bcipy/simulator/tests/resources/triggers.txt b/bcipy/simulator/tests/resources/triggers.txt new file mode 100644 index 000000000..2e420fa21 --- /dev/null +++ b/bcipy/simulator/tests/resources/triggers.txt @@ -0,0 +1,26 @@ +starting_offset offset -6377.0265653 +inquiry_preview preview 6400.5528593 ++ fixation 6404.0877378 +T nontarget 6404.5932127 +D nontarget 6404.7993812 +B nontarget 6405.0073678 +L nontarget 6405.2136213 +W nontarget 6405.4196753 +A nontarget 6405.6272747 +R nontarget 6405.8345703 +N nontarget 6406.0418707 +_ nontarget 6406.2494323 +< nontarget 6406.4567316 +inquiry_preview preview 6408.2049968 +bcipy_key_press_space event 6409.3349438000005 ++ fixation 6410.361287 +< nontarget 6410.8665035 +A nontarget 6411.0721914 +R nontarget 6411.278046 +B nontarget 6411.4836817 +D nontarget 6411.6893584 +L nontarget 6411.8949886 +N nontarget 6412.1007098 +W nontarget 6412.3064079 +_ nontarget 6412.5120152 +S target 6412.7176601 \ No newline at end of file diff --git a/bcipy/simulator/tests/test_gui_utils.py b/bcipy/simulator/tests/test_gui_utils.py new file mode 100644 index 000000000..469fe5b11 --- /dev/null +++ b/bcipy/simulator/tests/test_gui_utils.py @@ -0,0 +1,60 @@ +"""Tests for GUI utils""" +import unittest +from typing import Optional + +from bcipy.simulator.data.sampler.base_sampler import Sampler +from bcipy.simulator.data.sampler.inquiry_sampler import InquirySampler +from bcipy.simulator.ui.gui_utils import (InputField, get_inputs, + sampler_options) + + +class TestSampler(Sampler): + """Sampler used for testing""" + + def __init__(self, + data_engine, + a: int, + b: str, + c: int = 10, + d: Optional[str] = None): + super().__init__(data_engine) + self.a = a + self.b = b + self.c = c + self.d = d + + +class GuiUtilsTest(unittest.TestCase): + """Tests for GUI utility functions.""" + + def test_input_params(self): + """Test that introspecting an object produces the correct input + parameters.""" + + inputs = get_inputs(TestSampler) + + self.assertTrue( + InputField(name="a", input_type="int", value=None) in inputs, + "param a should be an int") + self.assertTrue( + InputField(name="b", input_type="str", value=None) in inputs, + "param b should be a str") + self.assertTrue( + InputField(name="c", input_type="int", value=10) in inputs, + "param c should be an int with value") + self.assertTrue( + InputField(name="d", input_type="str", value=None, required=False) + in inputs, "param d should be an optional str") + + def test_sampler_options(self): + """Test sampler options puts the default value first""" + opts = sampler_options() + self.assertEqual("TargetNontargetSampler", list(opts.keys())[0]) + + opts = sampler_options(default=InquirySampler) + self.assertEqual("InquirySampler", list(opts.keys())[0]) + self.assertTrue("TargetNontargetSampler" in opts.keys()) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/simulator/tests/test_inquiry_range_sampler.py b/bcipy/simulator/tests/test_inquiry_range_sampler.py new file mode 100644 index 000000000..2fc78a907 --- /dev/null +++ b/bcipy/simulator/tests/test_inquiry_range_sampler.py @@ -0,0 +1,78 @@ +"""Tests for inquiry range sampler""" +import unittest +from unittest.mock import Mock + +from bcipy.simulator.data.data_engine import QueryFilter +from bcipy.simulator.data.sampler.inquiry_range_sampler import \ + InquiryRangeSampler + + +class InquiryRangeSamplerTest(unittest.TestCase): + """Tests for InquiryRangeSampler""" + + def test_init(self): + """Test initialization""" + sampler = InquiryRangeSampler(data_engine=Mock(), inquiry_count=3) + + self.assertEqual(1, sampler.inquiry_start) + self.assertEqual(3, sampler.inquiry_count) + + self.assertRaises( + ValueError, lambda: InquiryRangeSampler( + data_engine=Mock(), inquiry_count=3, inquiry_start=-1)) + + self.assertRaises( + ValueError, lambda: InquiryRangeSampler( + data_engine=Mock(), inquiry_count=0, inquiry_start=2)) + + def test_query_filters(self): + """Test that queries are limited to the configured range""" + sampler = InquiryRangeSampler(data_engine=Mock(), inquiry_count=3) + + filters = sampler.query_filters(symbol='A', is_target=True) + + target_filter = QueryFilter('target', '==', 1) + nontarget_filter = QueryFilter('target', '==', 0) + start_filter = QueryFilter('series_inquiry', '>=', 0) + end_filter = QueryFilter('series_inquiry', '<', 3) + series_start_filter = QueryFilter('series', '>=', 1) + + self.assertEqual(4, len(filters)) + self.assertTrue(target_filter in filters) + self.assertFalse(nontarget_filter in filters) + self.assertTrue(start_filter in filters) + self.assertTrue(end_filter in filters) + self.assertTrue(series_start_filter in filters) + + filters = sampler.query_filters(symbol='A', is_target=False) + self.assertFalse(target_filter in filters) + self.assertTrue(nontarget_filter in filters) + + def test_filters_with_series_count(self): + """Test when a series count is provided.""" + sampler = InquiryRangeSampler(data_engine=Mock(), + inquiry_count=3, + series_start=2, + series_count=2) + series_start_filter = QueryFilter('series', '>=', 2) + series_end_filter = QueryFilter('series', '<', 4) + filters = sampler.query_filters(symbol='A', is_target=True) + self.assertEqual(5, len(filters)) + self.assertTrue(series_start_filter in filters) + self.assertTrue(series_end_filter in filters) + + def test_filter_with_nondefault_start(self): + """Test with non-defaults""" + sampler = InquiryRangeSampler(data_engine=Mock(), + inquiry_start=5, + inquiry_count=1) + start_filter = QueryFilter('series_inquiry', '>=', 4) + end_filter = QueryFilter('series_inquiry', '<', 5) + filters = sampler.query_filters(symbol='A', is_target=True) + + self.assertTrue(start_filter in filters) + self.assertTrue(end_filter in filters) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/simulator/tests/test_metrics.py b/bcipy/simulator/tests/test_metrics.py new file mode 100644 index 000000000..e1ce6c2d2 --- /dev/null +++ b/bcipy/simulator/tests/test_metrics.py @@ -0,0 +1,213 @@ +"""Test simulator metrics""" +import unittest +from unittest.mock import Mock, patch + +from bcipy.simulator.util.metrics import (SUMMARY_DATA_FILE_NAME, add_item, + add_items, calculate_duration, + get_final_typed, + log_descriptive_stats, plot_results, + plot_save_path, rename_df_column, + report, summarize) + +SAMPLE_SERIES_DATA = { + "1": { + "0": { + "next_display_state": "HELL" + } + }, + "2": { + "0": { + "next_display_state": "HELL" + }, + "1": { + "next_display_state": "HELLO" + } + } +} + +SAMPLE_SESSION1 = { + "series": SAMPLE_SERIES_DATA, + "total_time_spent": 0.0, + "total_minutes": 0.0, + "total_number_series": 14, + "total_inquiries": 45, + "total_selections": 14, + "inquiries_per_selection": 3.2, + "task_summary": { + "selections_correct": 14, + "selections_incorrect": 0, + "selections_correct_symbols": 14, + "switch_total": 0, + "switch_per_selection": 0.0, + "switch_response_time": None, + "typing_accuracy": 1.0, + "correct_rate": 0, + "copy_rate": 0 + } +} + +SAMPLE_SESSION2 = { + "series": SAMPLE_SERIES_DATA, + "total_time_spent": 0.0, + "total_minutes": 0.0, + "total_number_series": 14, + "total_inquiries": 16, + "total_selections": 14, + "inquiries_per_selection": 1.1428571428571428, + "task_summary": { + "selections_correct": 14, + "selections_incorrect": 0, + "selections_correct_symbols": 14, + "switch_total": 0, + "switch_per_selection": 0.0, + "switch_response_time": None, + "typing_accuracy": 1.0, + "correct_rate": 0, + "copy_rate": 0 + } +} + +SUMMARY = { + "total_number_series": [11, 19], + "total_inquiries": [54, 90], + "total_selections": [11, 19], + "inquiries_per_selection": [5, 4], + "task_summary__selections_correct": [11, 15], + "task_summary__selections_incorrect": [0, 4], + "task_summary__selections_correct_symbols": [11, 11], + "task_summary__typing_accuracy": [1.0, 0.7894736842105263], + "typed": ["HELLO_WORLD", "HELLO_WORLD"], + "total_seconds": [405.0, 675.0] +} + + +class TestSimMetrics(unittest.TestCase): + """Tests for simulator metrics""" + + def test_add_item(self): + """Test adding an item to a dict of sequences.""" + container = {'data1': [1]} + add_item(container, 'data2', 10) + self.assertTrue('data2' in container) + self.assertEqual([10], container['data2']) + + add_item(container, 'data1', 2) + self.assertEqual([1, 2], container['data1']) + + def test_get_final_typed(self): + """Get final typed text from the series data""" + session_data = {'series': SAMPLE_SERIES_DATA} + self.assertEqual("HELLO", get_final_typed(session_data)) + + def test_add_session_items(self): + """Test session metrics accumulation""" + combined = {} + session_data = SAMPLE_SESSION1 + add_items(combined, session_data, inquiry_seconds=2) + for key in [ + "total_number_series", "total_inquiries", "total_selections", + "inquiries_per_selection", "task_summary__selections_correct", + "task_summary__selections_incorrect", + "task_summary__selections_correct_symbols", + "task_summary__typing_accuracy", "typed" + ]: + self.assertTrue(key in combined) + self.assertEqual(1, len(combined[key])) + + @patch('bcipy.simulator.util.metrics.max_inquiry_duration') + @patch('bcipy.simulator.util.metrics.sim_parameters') + @patch('bcipy.simulator.util.metrics.load') + @patch('bcipy.simulator.util.metrics.open') + @patch('bcipy.simulator.util.metrics.session_paths') + def test_summarize(self, session_path_mock, open_mock, json_mock, + sim_parameters_mock, max_inquiry_duration_mock): + """Test summary function""" + session_path_mock.return_value = [ + 'run1/session.json', 'run2/session.json' + ] + json_mock.side_effect = [SAMPLE_SESSION1, SAMPLE_SESSION2] + max_inquiry_duration_mock.return_value = 2 + result = summarize("sim-dir") + + sim_parameters_mock.assert_called_once_with("sim-dir") + max_inquiry_duration_mock.assert_called_once() + self.assertEqual(open_mock.call_count, 2) + for key in [ + "total_number_series", "total_inquiries", "total_selections", + "inquiries_per_selection", "task_summary__selections_correct", + "task_summary__selections_incorrect", + "task_summary__selections_correct_symbols", + "task_summary__typing_accuracy", "typed" + ]: + self.assertTrue(key in result) + self.assertEqual(2, len(result[key])) + + def test_rename_df_column(self): + """Test renaming columns for output""" + self.assertEqual("total_inquiries", + rename_df_column("total_inquiries")) + self.assertEqual("selections_correct", + rename_df_column("task_summary__selections_correct")) + + def test_plot_name(self): + """Test naming for plots""" + self.assertEqual("sim_dir/metrics.png", plot_save_path("sim_dir")) + + def test_compute_duration(self): + """Test the calculation of the overall session duration""" + self.assertEqual( + 250, calculate_duration(inquiry_count=100, inquiry_seconds=2.5)) + + @patch("bcipy.simulator.util.metrics.plt.show") + @patch("bcipy.simulator.util.metrics.plt.savefig") + def test_plot_results_no_save(self, savefig_mock, show_mock): + """Test plotting without saving""" + mock_df = Mock() + plot_results(mock_df) + savefig_mock.assert_not_called() + show_mock.assert_called_once() + + @patch("bcipy.simulator.util.metrics.plt.show") + @patch("bcipy.simulator.util.metrics.plt.savefig") + def test_plot_results_no_show(self, savefig_mock, show_mock): + """Test plotting without saving""" + mock_df = Mock() + plot_results(mock_df, show=False) + savefig_mock.assert_not_called() + show_mock.assert_not_called() + + @patch("bcipy.simulator.util.metrics.plt.show") + @patch("bcipy.simulator.util.metrics.plt.savefig") + def test_plot_results_with_save(self, savefig_mock, show_mock): + """Test plotting without saving""" + mock_df = Mock() + plot_results(mock_df, save_path=".") + savefig_mock.assert_called_once() + show_mock.assert_called_once() + + def test_log_descriptive_stats(self): + """Test logging stats""" + mock_df = Mock() + log_descriptive_stats(mock_df) + mock_df.rename.assert_called_once() + mock_df.describe.assert_called_once() + + @patch("bcipy.simulator.util.metrics.plot_results") + @patch("bcipy.simulator.util.metrics.log_descriptive_stats") + @patch("bcipy.simulator.util.metrics.save_json_data") + @patch("bcipy.simulator.util.metrics.summarize") + def test_report(self, summarize_mock, save_json_data_mock, log_stats_mock, + plot_results_mock): + """Test reporting""" + summarize_mock.return_value = SUMMARY + report("test_dir") + + summarize_mock.assert_called_once() + save_json_data_mock.assert_called_with(SUMMARY, "test_dir", + SUMMARY_DATA_FILE_NAME) + log_stats_mock.assert_called_once() + plot_results_mock.assert_called_once() + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/simulator/tests/test_obj_args_widget.py b/bcipy/simulator/tests/test_obj_args_widget.py new file mode 100644 index 000000000..197362cf1 --- /dev/null +++ b/bcipy/simulator/tests/test_obj_args_widget.py @@ -0,0 +1,97 @@ +"""Test functionality of UI component""" + +import sys +import unittest +from typing import Optional + +# pylint: disable=E0611 +from PyQt6.QtWidgets import QApplication + +from bcipy.simulator.ui.obj_args_widget import ObjectArgInputs + +app = QApplication(sys.argv) + + +class NoArgs: + """Object without args""" + + +class ArgsObj: + """Object with args used for testing""" + + def __init__(self, a: int, b: str, c: int = 10, d: Optional[str] = None): + self.a = a + self.b = b + self.c = c + self.d = d + + +class ObjectArgsWidgetTest(unittest.TestCase): + """Tests for component.""" + + def test_no_args(self): + """Test object with no args""" + widget = ObjectArgInputs(object_type=NoArgs) + self.assertEqual(0, len(widget.controls)) + + def test_with_args(self): + """Test object with args""" + widget = ObjectArgInputs(object_type=ArgsObj) + self.assertEqual(4, len(widget.controls)) + + labels = [control[0] for control in widget.controls] + self.assertTrue('a' in labels) + self.assertTrue('b' in labels) + self.assertTrue('c' in labels) + self.assertTrue('d' in labels) + + def test_set_obj(self): + """Test that the widget updates""" + widget = ObjectArgInputs(object_type=NoArgs) + widget.set_object_type(ArgsObj) + self.assertEqual(4, len(widget.controls)) + + def test_value_no_args(self): + """Test getting value with no args""" + widget = ObjectArgInputs(object_type=NoArgs) + self.assertEqual('{}', widget.value()) + + def test_value_with_args(self): + """Test get value with default args""" + widget = ObjectArgInputs(object_type=ArgsObj) + self.assertEqual('{"a": null, "b": null, "c": 10, "d": null}', + widget.value()) + + def test_value_set_args(self): + """Test get value after updating inputs""" + widget = ObjectArgInputs(object_type=ArgsObj) + b_control = None + for label, control in widget.controls: + if label == "b": + b_control = control + break + self.assertIsNotNone(b_control) + b_control.setText("hello") + + self.assertEqual('{"a": null, "b": "hello", "c": 10, "d": null}', + widget.value()) + + def test_required_inputs(self): + """Test check for required inputs""" + widget = ObjectArgInputs(object_type=ArgsObj) + [a, b, _c, _d] = [control for _name, control in widget.controls] + + self.assertFalse(widget.required_inputs_provided()) + + a.setText("10") + b.setText("hi") + self.assertTrue(widget.required_inputs_provided()) + + def test_required_inputs_no_args(self): + """Test check for required inputs with no args""" + widget = ObjectArgInputs(object_type=NoArgs) + self.assertTrue(widget.required_inputs_provided()) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/simulator/tests/test_replay_comparison.py b/bcipy/simulator/tests/test_replay_comparison.py new file mode 100644 index 000000000..79f9a37d5 --- /dev/null +++ b/bcipy/simulator/tests/test_replay_comparison.py @@ -0,0 +1,52 @@ +import os +import shutil +import tempfile +import unittest +from pathlib import Path + +from bcipy.simulator.util.replay_comparison import (load_eeg_records, + prepare_data) + + +class ReplayComparisonTest(unittest.TestCase): + """Tests comparing evidence from identical sessions.""" + + def setUp(self): + """Override; set up the needed path for load functions.""" + self.data_dir = f"{os.path.dirname(__file__)}/resources/" + self.temp_dir = tempfile.mkdtemp() + + def tearDown(self): + """Override""" + shutil.rmtree(self.temp_dir) + + def test_load_eeg_evidence(self): + """Test loading evidence""" + + path = Path(self.data_dir, "session.json") + records = load_eeg_records(str(path), is_original_model=False) + + target_eeg = [ + record.response_value for record in records + if record.which_model == "new_target" + ] + nontarget_eeg = [ + record.response_value for record in records + if record.which_model == "new_nontarget" + ] + msg = "Target was not shown in first two inquiries but had a high response in the third." + self.assertEqual([1.0, 1.0, 100.0], target_eeg, msg) + num_symbols = 28 + num_inquiries = 3 + self.assertEqual((num_symbols - 1) * num_inquiries, len(nontarget_eeg)) + + def test_prepare_data(self): + """Test data prep""" + records = prepare_data(sim_dir=self.data_dir, data_folders=[]) + self.assertTrue( + all(record.which_model in ["new_target", "new_nontarget"] + for record in records)) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/simulator/tests/test_replay_sampler.py b/bcipy/simulator/tests/test_replay_sampler.py new file mode 100644 index 000000000..74284d5cb --- /dev/null +++ b/bcipy/simulator/tests/test_replay_sampler.py @@ -0,0 +1,83 @@ +import unittest +from unittest.mock import Mock + +from bcipy.simulator.data.data_engine import QueryFilter +from bcipy.simulator.data.sampler.replay_sampler import ReplaySampler +from bcipy.simulator.data.trial import Trial +from bcipy.simulator.exceptions import IncompatibleData +from bcipy.simulator.util.state import SimState + + +class ReplaySamplerTest(unittest.TestCase): + """Tests for Replay sampler class.""" + + def test_init(self): + """Test initialization""" + data_source = Mock() + data_source.source_dirs = [] + self.assertRaises(IncompatibleData, lambda: ReplaySampler(data_source)) + + data_source.source_dirs = ['source1'] + sampler = ReplaySampler(data_source) + self.assertEqual('source1', sampler.current_source) + + def test_filters(self): + """Test query filters""" + data_source = Mock() + data_source.source_dirs = ['source1'] + sampler = ReplaySampler(data_source) + + state = SimState(target_symbol='H', + current_sentence='', + target_sentence='HELLO', + display_alphabet=['A', 'B', 'C'], + inquiry_n=0, + series_n=1) + + expected = [ + QueryFilter('source', '==', 'source1'), + QueryFilter('series', '==', 1), + QueryFilter('series_inquiry', '==', 0), + QueryFilter('symbol', '==', 'A') + ] + self.assertEqual(expected, sampler.query_filters(state, 'A')) + + def test_sample(self): + """Test sampling""" + data_source = Mock() + data_source.source_dirs = ['source1'] + data_source.query.return_value = [ + Trial(source='source1', + series=1, + series_inquiry=0, + inquiry_n=0, + inquiry_pos=0, + symbol='A', + target=0, + eeg=Mock()) + ] + + sampler = ReplaySampler(data_source) + + state = SimState(target_symbol='H', + current_sentence='', + target_sentence='HELLO', + display_alphabet=['A', 'B', 'C'], + inquiry_n=0, + series_n=1) + sampler.sample(state) + self.assertEqual( + 3, + data_source.query.call_count, + msg="should have been called for each displayed symbol") + + def test_next_source(self): + """Test incrementing the source""" + data_source = Mock() + + data_source.source_dirs = ['source1', 'source2'] + sampler = ReplaySampler(data_source) + self.assertEqual('source1', sampler.current_source) + + sampler.next_source() + self.assertEqual('source2', sampler.current_source) diff --git a/bcipy/simulator/tests/test_sim_artifact.py b/bcipy/simulator/tests/test_sim_artifact.py new file mode 100644 index 000000000..f2c684622 --- /dev/null +++ b/bcipy/simulator/tests/test_sim_artifact.py @@ -0,0 +1,71 @@ +"""Tests for simulator logging and directory functions.""" +import logging +import shutil +import tempfile +import unittest +from pathlib import Path + +from bcipy.simulator.util.artifact import configure_logger, remove_handlers + + +class TestSimArtifact(unittest.TestCase): + """Test for simulator artifact functions.""" + + def setUp(self): + self.temp_dir = tempfile.mkdtemp() + + def tearDown(self): + shutil.rmtree(self.temp_dir) + + def test_configure_named_logger(self): + """Test configure named logger""" + + configure_logger(self.temp_dir, + file_name='test_1a.log', + logger_name='TEST_LOGGER', + use_stdout=True) + + log = logging.getLogger('TEST_LOGGER') + self.assertEqual(2, len(log.handlers)) + self.assertEqual('TEST_LOGGER', log.name) + log.info("testing 1 2 3") + self.assertTrue(Path(self.temp_dir, "test_1a.log").exists()) + + self.assertFalse(Path(self.temp_dir, "test_1b.log").exists()) + configure_logger(self.temp_dir, + file_name='test_1b.log', + logger_name='TEST_LOGGER', + use_stdout=True) + + log.info("testing 4 5 6") + self.assertTrue(Path(self.temp_dir, "test_1b.log").exists()) + self.assertEqual(2, len(log.handlers)) + remove_handlers(log) + + def test_configure_named_logger_without_stdout(self): + """Test the named logger without logging to stdout.""" + + configure_logger(self.temp_dir, + file_name='test_2.log', + logger_name='TEST_LOGGER', + use_stdout=False) + + log = logging.getLogger('TEST_LOGGER') + self.assertEqual(1, len(log.handlers)) + self.assertTrue(isinstance(log.handlers[0], logging.FileHandler)) + remove_handlers(log) + + def test_configure_root_logger(self): + """Test configure root logger""" + configure_logger(self.temp_dir, + file_name='test_root_logger.log', + logger_name=None, + use_stdout=False) + log = logging.getLogger() + self.assertEqual(1, len(log.handlers)) + self.assertTrue(isinstance(log.handlers[0], logging.FileHandler)) + remove_handlers(log) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/simulator/tests/test_switch_data_processor.py b/bcipy/simulator/tests/test_switch_data_processor.py new file mode 100644 index 000000000..b9ff52922 --- /dev/null +++ b/bcipy/simulator/tests/test_switch_data_processor.py @@ -0,0 +1,89 @@ +"""Tests for Button Press data processor.""" +import os +import tempfile +import unittest +from pathlib import Path + +import numpy as np + +from bcipy.acquisition.datastream.mock.switch import switch_device +from bcipy.core.raw_data import RawData +from bcipy.display.main import ButtonPressMode +from bcipy.io.load import load_json_parameters +from bcipy.signal.model.base_model import SignalModelMetadata +from bcipy.signal.model.switch_model import SwitchModel +from bcipy.simulator.data.switch_data_processor import SwitchDataProcessor + + +class SwitchProcessorTest(unittest.TestCase): + """Tests for Switch data processor.""" + + def setUp(self): + """Override.""" + self.data_dir = f"{os.path.dirname(__file__)}/resources/" + self.temp_dir = tempfile.mkdtemp() + self.model = SwitchModel() + self.model.metadata = SignalModelMetadata(device_spec=switch_device(), + evidence_type="BTN", + transform=None) + self.params_path = Path(self.data_dir, "btn_subset_parameters.json") + + def test_extracted_data(self): + """Test extracted data.""" + processor = SwitchDataProcessor(model=self.model) + params = load_json_parameters(self.params_path) + + extracted_data = processor.process(self.data_dir, params) + self.assertEqual( + [[0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 1]], + extracted_data.labels) + self.assertEqual((1, 2, 10), extracted_data.inquiries.shape) + self.assertEqual((1, 20, 1), extracted_data.trials.shape) + + data = np.array([[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], + [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]]) + expected_inquiries = data.reshape((1, 2, 10)) + expected_trials = data.reshape((1, 20, 1)) + self.assertTrue( + np.allclose(expected_inquiries, extracted_data.inquiries)) + self.assertTrue(np.allclose(expected_trials, extracted_data.trials)) + + def test_data_values(self): + """Test data values with different button press modes""" + processor = SwitchDataProcessor(model=self.model) + sample_data = RawData(daq_type='Switch', + sample_rate=0, + columns=['timestamp', 'Marker', 'lsl_timestamp']) + sample_data.append([1, 1.0, 6409.33]) + + self.assertEqual( + 1.0, + processor.data_value(sample_data, + inq_start=6408.20, + inq_stop=6412.91, + button_press_mode=ButtonPressMode.ACCEPT)) + + self.assertEqual( + 0.0, + processor.data_value(sample_data, + inq_start=6400.20, + inq_stop=6406.91, + button_press_mode=ButtonPressMode.ACCEPT)) + + self.assertEqual( + 0.0, + processor.data_value(sample_data, + inq_start=6408.20, + inq_stop=6412.91, + button_press_mode=ButtonPressMode.REJECT)) + + self.assertEqual( + 1.0, + processor.data_value(sample_data, + inq_start=6400.20, + inq_stop=6406.91, + button_press_mode=ButtonPressMode.REJECT)) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/simulator/tests/test_task_runner.py b/bcipy/simulator/tests/test_task_runner.py new file mode 100644 index 000000000..cf27b2e63 --- /dev/null +++ b/bcipy/simulator/tests/test_task_runner.py @@ -0,0 +1,19 @@ +import unittest + +from bcipy.simulator.task.task_runner import (TargetNontargetSampler, classify, + parse_args) + + +class TaskRunnerTest(unittest.TestCase): + """Unit tests for task_runner module.""" + + def test_classify(self): + """Test classifying a string""" + self.assertEqual(TargetNontargetSampler, + classify("TargetNontargetSampler")) + + def test_parse_args(self): + """Test parsing sampler args""" + expected = dict(a=1, b=2, c="hello") + self.assertEqual(expected, + parse_args('{"a": 1, "b": 2.0, "c": "hello"}')) diff --git a/bcipy/simulator/tests/test_trial.py b/bcipy/simulator/tests/test_trial.py new file mode 100644 index 000000000..4dbef41f6 --- /dev/null +++ b/bcipy/simulator/tests/test_trial.py @@ -0,0 +1,148 @@ +"""Test for trial data""" + +import unittest +from unittest.mock import Mock, patch + +import numpy as np + +from bcipy.simulator.data.data_process import (DecodedTriggers, + ExtractedExperimentData) +from bcipy.simulator.data.trial import (Trial, convert_trials, series_inquiry, + session_series_counts) + + +class TestTrial(unittest.TestCase): + """Test for trial class and functions.""" + + def test_trial_str(self): + """Test representation of a trial""" + trial = Trial(source="path-to-source", + series=1, + series_inquiry=2, + inquiry_n=2, + inquiry_pos=5, + symbol='M', + target=1, + eeg=np.zeros(shape=(3, 2))) + self.assertTrue('series=1' in str(trial)) + self.assertTrue('eeg=(3, 2)' in str(trial)) + + def test_trial_without_optional(self): + """Test without the optional data""" + trial = Trial(source="path-to-source", + series=None, + series_inquiry=None, + inquiry_n=2, + inquiry_pos=5, + symbol='M', + target=1, + eeg=np.zeros(shape=(3, 2))) + self.assertTrue('series=None' in str(trial)) + + @patch("bcipy.simulator.data.trial.read_session") + @patch("bcipy.simulator.data.trial.Path") + def test_session_series_counts(self, path_constructor_mock, + read_session_mock): + """Test computing the series counts from the session data when the + session path exists.""" + path_mock = Mock() + path_mock.exists.return_value = True + path_constructor_mock.return_value = path_mock + session_series_counts("example-data-directory") + read_session_mock.assert_called_once() + + @patch("bcipy.simulator.data.trial.read_session") + @patch("bcipy.simulator.data.trial.Path") + def test_session_series_counts_bad_path(self, path_constructor_mock, + read_session_mock): + """Test computing the series counts from the session data when session + data is not present.""" + path_mock = Mock() + path_mock.exists.return_value = False + path_constructor_mock.return_value = path_mock + session_series_counts("no-session") + read_session_mock.assert_not_called() + + def test_series_inquiry(self): + """Test series inquiry calculation""" + counts = [5, 2, 4] + self.assertEqual((1, 0), series_inquiry(counts, 0)) + self.assertEqual((1, 4), series_inquiry(counts, 4)) + self.assertEqual((2, 0), series_inquiry(counts, 5)) + self.assertEqual((2, 1), series_inquiry(counts, 6)) + self.assertEqual((3, 0), series_inquiry(counts, 7)) + self.assertEqual((3, 2), series_inquiry(counts, 9)) + self.assertEqual((3, 3), series_inquiry(counts, 10)) + + self.assertEqual((None, None), series_inquiry([], 0)) + + def test_convert_trials(self): + """Test converting data to trials.""" + + sample_data = ExtractedExperimentData( + source_dir="test-src", + inquiries=np.ones((6, 4, 436)), + trials=np.ones((6, 12, 75)), + labels=[[0, 0, 0], [0, 0, 0], [0, 0, 0], [0, 0, 1]], + inquiry_timing=[[150, 180, 210], [150, 180, 210], [150, 180, 210], + [150, 180, 210]], + decoded_triggers=DecodedTriggers( + targetness=[ + 'nontarget', 'nontarget', 'nontarget', 'nontarget', + 'nontarget', 'nontarget', 'nontarget', 'nontarget', + 'nontarget', 'nontarget', 'nontarget', 'target' + ], + times=[ + 10.515330292284489, 10.717246917076409, 10.919030375313014, + 15.644844584167004, 15.846348999999464, 16.047540083993226, + 20.790782417170703, 20.992313000373542, 21.193465375341475, + 25.914405125193298, 26.115663417149335, 26.31681716721505 + ], + symbols=[ + '<', 'N', 'J', '<', 'N', 'J', 'J', 'B', '<', '<', 'J', 'B' + ], + corrected_times=[ + 10.515330292284489, 10.717246917076409, 10.919030375313014, + 15.644844584167004, 15.846348999999464, 16.047540083993226, + 20.790782417170703, 20.992313000373542, 21.193465375341475, + 25.914405125193298, 26.115663417149335, 26.31681716721505 + ]), + trials_per_inquiry=3) + + trials = convert_trials(sample_data, get_series_counts=lambda x: [4]) + self.assertEqual(12, len(trials)) + + # check properties for first element + self.assertEqual(trials[0].source, "test-src") + self.assertEqual(trials[0].series, 1) + self.assertEqual(trials[0].series_inquiry, 0) + self.assertEqual(trials[0].inquiry_n, 0) + self.assertEqual(trials[0].inquiry_pos, 1) + self.assertEqual(trials[0].symbol, '<') + self.assertEqual(trials[0].target, 0) + self.assertEqual(trials[0].eeg.shape, (6, 75)) + + # check properties for last element + self.assertEqual(trials[-1].source, "test-src") + self.assertEqual(trials[-1].series, 1) + self.assertEqual(trials[-1].series_inquiry, 3) + self.assertEqual(trials[-1].inquiry_n, 3) + self.assertEqual(trials[-1].inquiry_pos, 3) + self.assertEqual(trials[-1].symbol, 'B') + self.assertEqual(trials[-1].target, 1) + self.assertEqual(trials[-1].eeg.shape, (6, 75)) + + # check properties when series_counts are different + trials = convert_trials(sample_data, + get_series_counts=lambda x: [3, 1]) + self.assertEqual(trials[-1].series, 2) + self.assertEqual(trials[-1].series_inquiry, 0) + self.assertEqual(trials[-1].inquiry_n, 3) + self.assertEqual(trials[-1].inquiry_pos, 3) + self.assertEqual(trials[-1].symbol, 'B') + self.assertEqual(trials[-1].target, 1) + self.assertEqual(trials[-1].eeg.shape, (6, 75)) + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/simulator/ui/cli.py b/bcipy/simulator/ui/cli.py new file mode 100644 index 000000000..973d0810e --- /dev/null +++ b/bcipy/simulator/ui/cli.py @@ -0,0 +1,271 @@ +"""Command line interface for the simulator.""" + +import json +import logging +from glob import glob +from pathlib import Path +from typing import Any, Callable, Dict, List, Optional, Type + +from rich import print as rprint +from rich.filesize import decimal +from rich.markup import escape +from rich.prompt import Confirm, Prompt, PromptBase +from rich.text import Text +from rich.tree import Tree + +from bcipy.gui.file_dialog import ask_directory, ask_filename +from bcipy.helpers.acquisition import active_content_types +from bcipy.io.load import choose_model_paths, load_json_parameters +from bcipy.simulator.data.sampler import (InquirySampler, Sampler, + TargetNontargetSampler) +from bcipy.simulator.task.copy_phrase import SimulatorCopyPhraseTask +from bcipy.simulator.task.task_factory import TaskFactory +from bcipy.simulator.util.artifact import TOP_LEVEL_LOGGER_NAME +from bcipy.task.paradigm.rsvp.copy_phrase import RSVPCopyPhraseTask + +logger = logging.getLogger(TOP_LEVEL_LOGGER_NAME) + + +def do_directories(parent: Path, + fn: Callable[[Path], Any], + max_depth: int = 3, + current_depth: int = 1) -> None: + """Recursively walk a tree of directories, calling the provided + function on each path. + """ + + paths = sorted( + Path(parent).iterdir(), + key=lambda path: (path.is_file(), path.name.lower()), + ) + for path in paths: + # Remove hidden files + if path.name.startswith("."): + continue + if path.is_dir(): + fn(path) + if (current_depth + 1) <= max_depth: + do_directories(path, fn, max_depth, current_depth + 1) + + +def walk_directory(directory: Path, + tree: Tree, + show_files: bool = True, + skip_dir: Callable[[Path], bool] = lambda p: False) -> None: + """Recursively build a Tree with directory contents. + Adapted from rich library examples/tree.py + + Parameters + ---------- + directory - root directory of the tree + tree - Tree object that gets recursively updated + show_files - boolean indicating if files should be displayed + skip_dir - predicate to determine if a directory should be skipped + """ + # Sort dirs first then by filename + paths = sorted( + Path(directory).iterdir(), + key=lambda path: (path.is_file(), path.name.lower()), + ) + for path in paths: + # Remove hidden files + + if path.name.startswith(".") or (path.is_dir() and skip_dir(path)): + continue + if path.is_dir(): + style = "dim" if path.name.startswith("__") else "" + branch = tree.add( + f"[blue]:open_file_folder: [link file://{path}]{escape(path.name)}", + style=style, + guide_style=style, + ) + walk_directory(path, branch, show_files, skip_dir) + else: + if show_files: + text_filename = Text(path.name) + text_filename.stylize(f"link file://{path}") + file_size = path.stat().st_size + text_filename.append(f" ({decimal(file_size)})", "blue") + tree.add(text_filename) + else: + continue + + +def print_directories(parent, paths: List[Path]) -> None: + """Print the list of directories to terminal as a tree.""" + assert paths, "Paths are required" + paths = sorted(paths) + + def pred(p): + return p not in paths + + show_tree(parent, pred) + + +def excluded(path: Path) -> bool: + """Predicate to determine if a path should not be presented.""" + return path.is_file() or path.name == 'logs' or 'Action' in path.name + + +def select_directories(parent: Path) -> List[Path]: + """Select all directories of interest within the parent path. + Traverses all directories and prompts for each. + """ + accum = [] + + def do_prompt(path: Path): + if not excluded(path) and Confirm.ask(str(path.relative_to(parent))): + accum.append(path) + + do_directories(parent, do_prompt, max_depth=2) + return accum + + +def select_subset(parent, paths: List[Path]) -> List[Path]: + """Prompt the user to confirm the subset of paths that should be retained.""" + return [ + path for path in paths + if not excluded(path) and Confirm.ask(str(path.relative_to(parent))) + ] + + +def show_tree(directory: Path, + skip_pred: Callable[[Path], bool] = lambda p: False): + """Prints a tree representation of a directory. + + Parameters + ---------- + directory - root path to display + skip_pred - callable function to determine if a branch in the tree should + be skipped during rendering. + """ + tree = Tree( + f":open_file_folder: [link file://{directory}]{directory}", + guide_style="bold bright_blue", + ) + walk_directory(Path(directory), tree, show_files=False, skip_dir=skip_pred) + rprint(tree) + + +class PromptPath(PromptBase[Path]): + """A prompt that returns a Path. + + Example: + >>> name = PromptPath.ask("Enter a file name") + """ + + response_type = Path + + def process_response(self, value: str) -> Path: + """Process the response value and return a Path object.""" + value = value.strip("'\"") + return super().process_response(value) + + +def select_data_folder() -> Path: + """Select a root data folder for simulation.""" + # PromptPath.ask("Input a data folder") + return Path(ask_directory("Select a data folder")) + + +def prompt_filter() -> str: + """Prompt for an optional glob filter.""" + return Prompt.ask("Enter a glob filter (optional)", default="*") + + +def select_data(parent_folder: Optional[str] = None) -> List[Path]: + """Select data to use for the simulation.""" + if parent_folder: + path = Path(parent_folder) + else: + selected = select_data_folder() + path = Path(selected) + + glob_pattern = prompt_filter() + paths = sorted([ + Path(p) for p in glob(str(Path(path, glob_pattern)), recursive=True) + if not excluded(Path(p)) + ]) + print_directories(path, paths) + if not Confirm.ask("Use all of these?"): + paths = select_subset(path, paths) + print_directories(path, paths) + return paths + + +def choose_sampling_strategy() -> Type[Sampler]: + """Choose a sampling strategy""" + classes = [InquirySampler, TargetNontargetSampler] + options = {klass.__name__: klass for klass in classes} + selected = Prompt.ask("Choose a sampling strategy", + choices=options.keys(), + default='TargetNontargetSampler') + return options[selected] + + +def choose_task() -> Type[RSVPCopyPhraseTask]: + """Choose a task to simulate""" + classes = [SimulatorCopyPhraseTask] + options = {klass.__name__: klass for klass in classes} + selected = Prompt.ask("Choose a simulation task", + choices=options.keys(), + default='SimulatorCopyPhraseTask') + return options.get(selected, SimulatorCopyPhraseTask) + + +def select_models(acq_mode: str) -> List[Path]: + """Select the signal models to use in simulation.""" + signal_models = choose_model_paths(active_content_types(acq_mode)) + return signal_models + + +def select_parameters_path() -> str: + """Select the parameters path""" + return ask_filename(file_types="*.json", prompt="Select Parameters file") + + +def get_acq_mode(params_path: str): + """Extract the acquisition mode field from the json file at the given path.""" + with open(params_path, 'r', encoding='utf8') as json_file: + params = json.load(json_file) + return params['acq_mode'].get('value', 'EEG') + + +def command(params: str, models: List[str], source_dirs: List[str], sampler: Type[Sampler]) -> str: + """Command equivalent to the result of the interactive selection of + simulator inputs. + """ + model_args = ' '.join([f"-m {path}" for path in models]) + dir_args = ' '.join(f"-d {source}" for source in source_dirs) + sampler_args = f"-s {sampler.__name__}" + return f"bcipy-sim -p {params} {model_args} {sampler_args} {dir_args}" + + +def main(args: Dict[str, Any]) -> TaskFactory: + """Main function""" + params = args.get('parameters', None) + if not params: + params = select_parameters_path() + + model_paths = args.get('model_path', None) + if not model_paths: + model_paths = select_models(get_acq_mode(params)) + + source_dirs = [ + str(path) for path in select_data(args.get('data_folder', None)) + ] + + sampler = choose_sampling_strategy() + + print(command(params, model_paths, source_dirs, sampler)) + + parameters = load_json_parameters(params, value_cast=True) + return TaskFactory(parameters=parameters, + source_dirs=source_dirs, + signal_model_paths=model_paths, + sampling_strategy=sampler, + task=SimulatorCopyPhraseTask) + + +if __name__ == '__main__': + main({}) diff --git a/bcipy/simulator/ui/gui.py b/bcipy/simulator/ui/gui.py new file mode 100644 index 000000000..0d61303f4 --- /dev/null +++ b/bcipy/simulator/ui/gui.py @@ -0,0 +1,808 @@ +"""Graphical User Interface for configuring the Simulator.""" + +# pylint: disable=E0611 +import argparse +import fnmatch +import json +import os +import subprocess +import sys +from pathlib import Path +from typing import Callable, List, Optional, Tuple, Union + +from PyQt6.QtCore import Qt +from PyQt6.QtGui import QFont +from PyQt6.QtWidgets import (QApplication, QCheckBox, QComboBox, QFormLayout, + QGroupBox, QHBoxLayout, QLabel, QLineEdit, + QPushButton, QSpinBox, QTreeWidget, + QTreeWidgetItem, QVBoxLayout, QWidget) + +from bcipy.core.parameters import Parameters +from bcipy.gui.file_dialog import FileDialog +from bcipy.gui.main import static_text_control +from bcipy.helpers.acquisition import active_content_types +from bcipy.io.load import load_json_parameters +from bcipy.preferences import preferences +from bcipy.simulator.data.sampler import TargetNontargetSampler +from bcipy.simulator.data.sampler.base_sampler import Sampler +from bcipy.simulator.task.copy_phrase import SimulatorCopyPhraseTask +from bcipy.simulator.task.task_factory import TaskFactory +from bcipy.simulator.ui.cli import excluded +from bcipy.simulator.ui.gui_utils import sampler_options +from bcipy.simulator.ui.obj_args_widget import ObjectArgInputs +from bcipy.simulator.util.artifact import DEFAULT_SAVE_LOCATION + + +def walk_directory(directory: Path, + tree: Union[QTreeWidget, QTreeWidgetItem], + skip_dir: Callable[[Path], bool] = lambda p: False) -> None: + """Recursively build a Tree with directory contents. + Adapted from rich library examples/tree.py + + Parameters + ---------- + directory - root directory of the tree + tree - Tree object that gets recursively updated + skip_dir - predicate to determine if a directory should be skipped + """ + # Sort dirs first then by filename + paths = sorted( + Path(directory).iterdir(), + key=lambda path: (path.is_file(), path.name.lower()), + ) + for path in paths: + # Remove hidden files + if path.name.startswith(".") or path.is_file() or (path.is_dir() + and skip_dir(path)): + continue + if path.is_dir(): + branch = QTreeWidgetItem(tree, [path.name]) + walk_directory(path, branch, skip_dir) + + +def is_ancestor(directory: Path, paths: List[Path]) -> bool: + """Check if the given directory is the ancestor of any of the provided paths.""" + for path in paths: + if directory in path.parents: + return True + return False + + +class DirectoryTree(QWidget): + """Display a tree of directories""" + + def __init__(self, + parent: Optional[QWidget] = None, + parent_directory: Optional[str] = None, + selected_subdirectories: Optional[List[Path]] = None): + super().__init__(parent=parent) + self.parent_directory = parent_directory + self.paths = selected_subdirectories or [] + + self.label = "Selected Directories" + self.tree = self.make_tree() + self.box_layout = QVBoxLayout() + self.box_layout.addWidget( + LabeledWidget(self.label, self.tree, label_size=12)) + self.box_layout.addWidget(self.tree) + self.setLayout(self.box_layout) + + def update_tree(self, parent_directory: Optional[str], + selected_subdirectories: Optional[List[Path]]) -> None: + """Update the widget.""" + self.parent_directory = parent_directory + self.paths = selected_subdirectories or [] + + clear_layout(self.box_layout) + if self.parent_directory: + self.tree = self.make_tree() + self.box_layout.addWidget( + LabeledWidget(self.label, self.tree, label_size=12)) + + def make_tree(self) -> QTreeWidget: + """Initialize the tree widget""" + + tree = QTreeWidget() + if self.parent_directory: + tree.setColumnCount(1) + tree.setHeaderLabels([self.parent_directory]) + walk_directory(Path(self.parent_directory), + tree, + skip_dir=self.skip_path) + return tree + + def skip_path(self, directory: Path) -> bool: + """Should the given directory be skipped""" + if directory in self.paths or is_ancestor(directory, self.paths): + return False + return True + + +class ChooseFileInput(QWidget): + """Text field and button which pops open a file selection dialog.""" + + def __init__(self, + parent: Optional[QWidget] = None, + value: Optional[str] = None, + file_selector: str = "*", + prompt: str = "Select a file", + change_event: Optional[Callable] = None): + + super().__init__(parent=parent) + self.file_selector = file_selector + self.prompt = prompt + self.change_event = change_event + self.control = QLineEdit(value) + self.control.textChanged.connect(self.change) + + btn = QPushButton('...') + btn.setFixedWidth(40) + btn.clicked.connect(self.update_path) + hbox = QHBoxLayout() + hbox.setContentsMargins(0, 0, 0, 0) + hbox.addWidget(self.control) + hbox.addWidget(btn) + self.setLayout(hbox) + + def prompt_path(self) -> str: + """Prompts the user with a FileDialog. Returns the selected value or None.""" + dialog = FileDialog() + directory = preferences.last_directory + filename = dialog.ask_file(self.file_selector, + directory, + prompt=self.prompt) + path = Path(filename) + if filename and path.is_file(): + preferences.last_directory = str(path.parent) + return filename + + def update_path(self) -> None: + """Prompts the user for a value and updates the control's value if one was input.""" + name = self.prompt_path() + if name: + self.control.setText(name) + + def change(self): + """Called when the path changes""" + if self.change_event: + self.change_event() + + def value(self) -> Optional[str]: + """Path value""" + return self.control.text() + + +class ChooseDirectoryInput(ChooseFileInput): + """Text field and button which pops open a directory selection dialog.""" + + def __init__(self, + parent: Optional[QWidget] = None, + value: Optional[str] = None, + prompt: str = "Select a directory", + change_event: Optional[Callable] = None): + super().__init__(parent=parent, + value=value, + prompt=prompt, + change_event=change_event) + + def prompt_path(self): + """Prompt the user to select a directory path.""" + dialog = FileDialog() + directory = '' + if preferences.last_directory: + directory = str(Path(preferences.last_directory).parent) + name = dialog.ask_directory(directory, prompt=self.prompt) + if name and Path(name).is_dir(): + preferences.last_directory = name + return name + + +class ParameterFileInput(ChooseFileInput): + """Prompts for a parameters file.""" + + def __init__(self, **kwargs): + kwargs['file_selector'] = "*.json" + kwargs['prompt'] = "Select a parameters file" + super().__init__(**kwargs) + self.parameters: Optional[Parameters] = None + + def change(self): + """Connected to a change in the user input parameters.""" + value = self.value() + if value is not None and Path(value).is_file(): + self.parameters = Parameters(value, cast_values=True) + else: + self.parameters = None + if self.change_event: + self.change_event() + + +class DirectoryFilters(QWidget): + """Fields that filter the selected directories""" + + def __init__(self, + parent: Optional[QWidget] = None, + change_event: Optional[Callable] = None, + **kwargs): + super().__init__(parent=parent, **kwargs) + self.change_event = change_event + self.box_layout = QVBoxLayout() + + self.nested_filter_control = QCheckBox("Include nested directories") + self.nested_filter_control.setChecked(True) + self.nested_filter_control.checkStateChanged.connect(self.change) + + # self.name_filter_control_label = QLabel("Name contains") + self.name_filter_control = QLineEdit("") + self.name_filter_control.textChanged.connect(self.change) + self.box_layout.addWidget(self.nested_filter_control) + + form = QFormLayout() + form.setFormAlignment(Qt.AlignmentFlag.AlignLeft) + form.addRow("Name contains", self.name_filter_control) + + self.box_layout.addLayout(form) + self.setLayout(self.box_layout) + + def change(self): + """Called when a filter field is modified.""" + if self.change_event: + self.change_event() + + +class DataDirectorySelect(QWidget): + """Widget that facilitates the selection of data directories. + Includes an input for a parent directory and optional filters. + """ + + def __init__(self, + parent: Optional[QWidget] = None, + parent_directory: Optional[str] = None, + change_event: Optional[Callable] = None): + super().__init__(parent=parent) + vbox = QVBoxLayout() + self.change_event = change_event + self.filters_enabled = False + self.parent_directory_control = ChooseDirectoryInput( + change_event=self.update_directory_tree, + prompt="Select a parent data directory", + value=parent_directory) + + self.directory_filter_control = DirectoryFilters( + change_event=self.update_directory_tree) + self.directory_tree = DirectoryTree() + + parent_layout = self.parent_directory_control.layout() + filter_layout = self.directory_filter_control.layout() + if parent_layout: + parent_layout.setContentsMargins(0, 0, 0, 0) + if filter_layout: + filter_layout.setContentsMargins(0, 0, 0, 0) + self.directory_filter_control.setEnabled(self.filters_enabled) + self.directory_tree.setEnabled(self.filters_enabled) + + form = QFormLayout() + form.setFormAlignment(Qt.AlignmentFlag.AlignLeft + | Qt.AlignmentFlag.AlignVCenter) + form.setFieldGrowthPolicy( + QFormLayout.FieldGrowthPolicy.AllNonFixedFieldsGrow) + form.addRow("Data Parent Directory", self.parent_directory_control) + vbox.addLayout(form) + vbox.addWidget(self.directory_filter_control) + vbox.addWidget(self.directory_tree) + self.setLayout(vbox) + + def parent_directory(self) -> Optional[str]: + """Parent directory""" + parent = self.parent_directory_control.value() + if parent: + return parent.strip() + return None + + def match_pattern(self) -> str: + """Pattern used to match a directory with fnmatch.""" + name_filter = self.directory_filter_control.name_filter_control.text() + if name_filter: + return f"*{name_filter.strip(' *')}*" + return "*" + + def use_nested(self) -> bool: + """Include nested directories""" + return self.directory_filter_control.nested_filter_control.isChecked() + + def data_directories(self) -> Optional[List[Path]]: + """Compute the data directories of interest.""" + parent = self.parent_directory() + if not parent: + return None + + pattern = self.match_pattern() + subdirs = [] + if self.use_nested(): + for cur_path, directories, _files in os.walk(parent, topdown=True): + for name in fnmatch.filter(directories, pattern): + path = Path(cur_path, name) + if not excluded(path): + subdirs.append(path) + else: + cur_path, directories, _files = next(os.walk(parent)) + for name in fnmatch.filter(directories, pattern): + path = Path(cur_path, name) + if not excluded(path): + subdirs.append(path) + return sorted(subdirs) + + def update_directory_tree(self): + """Update the directory tree""" + + if self.parent_directory(): + if not self.filters_enabled: + self.filters_enabled = True + self.directory_filter_control.setEnabled(True) + self.directory_tree.setEnabled(True) + self.directory_tree.update_tree(self.parent_directory(), + self.data_directories()) + else: + self.filters_enabled = False + self.directory_filter_control.setEnabled(False) + self.directory_tree.setEnabled(False) + # notify any listeners of the change + if self.change_event: + self.change_event() + + +class ModelFileInput(ChooseFileInput): + """Prompts for a parameters file.""" + + def __init__(self, + parent: Optional[QWidget] = None, + value: Optional[str] = None, + file_selector: str = "*.pkl", + prompt: str = "Select a model", + change_event: Optional[Callable] = None): + super().__init__(parent=parent, + value=value, + file_selector=file_selector, + prompt=prompt, + change_event=change_event) + + +class ModelInputs(QWidget): + """Provide a model path input for each configured content type.""" + + def __init__(self, + parent: Optional[QWidget] = None, + content_types: Optional[List[str]] = None, + change_event: Optional[Callable] = None): + super().__init__(parent=parent) + self.change_event = change_event + self.form_layout = QFormLayout() + self.form_layout.setFormAlignment(Qt.AlignmentFlag.AlignLeft + | Qt.AlignmentFlag.AlignVCenter) + self.form_layout.setFieldGrowthPolicy( + QFormLayout.FieldGrowthPolicy.AllNonFixedFieldsGrow) + self.content_types = content_types or ['EEG'] + self.controls = self._create_inputs() + self._add_controls() + self.setLayout(self.form_layout) + + def value(self) -> List[str]: + """Model paths""" + return [control[1].value() for control in self.controls] + + def set_content_types(self, value: List[str]): + """Set the content_content types and re-generate inputs.""" + self.content_types = value + self.controls = self._create_inputs(initialized=True) + self._add_controls() + + def _create_inputs(self, + initialized: bool = False) -> List[Tuple[str, QWidget]]: + """Create a path input to a model for each content type""" + return [(self._label(content_type), + ModelFileInput( + parent=self, + change_event=self.change, + value=self._path(content_type) if initialized else None)) + for content_type in self.content_types] + + def _path(self, content_type: str) -> Optional[str]: + """Get the input path for the provided content type""" + matches = [ + control for control in self.controls + if control[0] == self._label(content_type) + ] + if matches: + return matches[0][1].value() + return None + + def _label(self, content_type: str) -> str: + return f"{content_type} Model" + + def _add_controls(self) -> None: + """Add each model input to the layout.""" + clear_layout(self.form_layout) + for (label, control) in self.controls: + self.form_layout.addRow(label, control) + + def change(self): + """Called when a model path changes""" + if self.change_event: + self.change_event() + + +class SelectionList(QWidget): + """Widget for selecting a sampler.""" + + def __init__(self, + parent: Optional[QWidget] = None, + change_event: Optional[Callable] = None, + items: Optional[List[str]] = None): + super().__init__(parent=parent) + self.change_event = change_event + self.form_layout = QFormLayout() + self.control = QComboBox() + if items: + self.control.addItems(items) + self.control.currentTextChanged.connect(self.change) + + hbox = QHBoxLayout() + hbox.setContentsMargins(0, 0, 0, 0) + hbox.addWidget(self.control) + self.setLayout(hbox) + + def value(self) -> str: + """Selected value""" + return self.control.currentText() + + def change(self): + """Called when a model path changes""" + if self.change_event: + self.change_event() + + +class LabeledWidget(QWidget): + """Renders a widget with a label above it.""" + + def __init__(self, + label: str, + widget: QWidget, + label_size: int = 14, + parent: Optional[QWidget] = None): + super().__init__(parent=parent) + vbox = QVBoxLayout() + lbl = QLabel() + lbl.setText(label) + if label_size: + lbl.setFont(QFont(None, label_size)) + + vbox.setContentsMargins(0, 0, 0, 0) + vbox.addWidget(lbl) + vbox.addWidget(widget) + self.setLayout(vbox) + + +def sim_runs_control(value: int = 1) -> QWidget: + """Create a widget for entering simulation runs.""" + spin_box = QSpinBox() + spin_box.setMinimum(1) + spin_box.setMaximum(1000) + # disable scroll wheel + spin_box.wheelEvent = lambda event: None # type: ignore + spin_box.setValue(value) + return spin_box + + +class SimConfigForm(QWidget): + """The InputForm class is a QWidget that creates controls/inputs for each simulation parameter. + + Parameters + ---------- + json_file - path of parameters file to be edited. + width - optional; used to set the width of the form controls. + """ + + def __init__(self, + width: int = 400, + change_event: Optional[Callable] = None): + super().__init__() + + vbox = QVBoxLayout() + self.setFixedWidth(width) + + self.change_event = change_event + self.parameters_path: Optional[str] = None + self.model_paths: List[str] = [] + self.data_paths: Optional[List[Path]] = [] + + self.sampler: Optional[Sampler] = TargetNontargetSampler + self.sampler_options = sampler_options(default=self.sampler) + self.sampler_args = '{}' + + self.runs_control = sim_runs_control() + self.output_control = ChooseDirectoryInput( + value=DEFAULT_SAVE_LOCATION, change_event=self.update_data_paths) + + self.parameter_control = ParameterFileInput( + change_event=self.update_parameters) + self.directory_control = DataDirectorySelect( + change_event=self.update_data_paths) + self.model_input_control = ModelInputs(change_event=self.update_models) + self.sampler_input_control = SelectionList( + change_event=self.update_sampler, + items=list(self.sampler_options.keys())) + self.sampler_args_control = ObjectArgInputs( + change_event=self.update_sampler_args, object_type=self.sampler) + + form = QFormLayout() + form.setFormAlignment(Qt.AlignmentFlag.AlignLeft + | Qt.AlignmentFlag.AlignVCenter) + form.setFieldGrowthPolicy( + QFormLayout.FieldGrowthPolicy.AllNonFixedFieldsGrow) + form.addRow("Simulation Runs:", self.runs_control) + form.addRow("Output Directory:", self.output_control) + form.addRow("Sim Parameters:", self.parameter_control) + + vbox.addLayout(form) + vbox.addSpacing(2) + vbox.addWidget(self.create_model_group()) + vbox.addSpacing(2) + vbox.addWidget(self.create_sampler_group()) + vbox.addSpacing(2) + vbox.addWidget(self.create_data_group()) + self.setLayout(vbox) + self.show() + + def create_sampler_group(self) -> QWidget: + """Create a group box for model inputs""" + group = QGroupBox("Sampler") + vbox = QVBoxLayout() + vbox.addWidget(self.sampler_input_control) + vbox.addWidget(self.sampler_args_control) + group.setLayout(vbox) + return group + + def create_data_group(self) -> QWidget: + """Create a group box for data inputs.""" + group_box = QGroupBox("Data") + vbox = QVBoxLayout() + vbox.addWidget(self.directory_control) + group_box.setLayout(vbox) + return group_box + + def create_model_group(self) -> QWidget: + """Create a group box for model inputs""" + group = QGroupBox("Models") + vbox = QVBoxLayout() + vbox.addWidget(self.model_input_control) + group.setLayout(vbox) + return group + + def runs(self) -> int: + """Number of runs""" + return int(self.runs_control.text()) + + def outdir(self) -> Optional[str]: + """Output directory""" + return self.output_control.value() + + def command_valid(self) -> bool: + """Returns True if all necessary fields are input.""" + return bool(self.parameters_path and self.model_paths + and self.data_paths and self.sampler and self.sampler_args) + + def command(self) -> str: + """Command equivalent to the result of the interactive selection of simulator inputs.""" + if not self.command_valid(): + return '' + + args = [] + if self.outdir(): + args.append(f"-o '{self.outdir()}'") + args.append(f"-p '{self.parameters_path}'") + args.extend([f"-m '{path}'" for path in self.model_paths]) + if self.data_paths: + args.extend([f"-d '{source}'" for source in self.data_paths]) + + args.append(f"-n {self.runs()}") + if self.sampler is not None: + args.append(f"-s {self.sampler.__name__}") + args.append(f"--sampler_args='{self.sampler_args}'") + args.append("-v") + + return f"bcipy-sim {' '.join(args)}" + + def update_parameters(self) -> None: + """When simulation parameters are updated include an input for each model.""" + self.parameters_path = self.parameter_control.value() + params = self.parameter_control.parameters + if params: + content_types = active_content_types(params.get('acq_mode', 'EEG')) + else: + content_types = ['EEG'] + self.model_input_control.set_content_types(content_types) + self.change() + + def update_models(self) -> None: + """Update the model paths from the input controls""" + self.model_paths = self.model_input_control.value() + self.change() + + def update_data_paths(self) -> None: + """Update the data paths from the directory inputs""" + self.data_paths = self.directory_control.data_directories() + self.change() + + def update_sampler(self) -> None: + """Called when the sampler is updated. Updates the sampler args input""" + selected_sampler = self.sampler_options.get( + self.sampler_input_control.value(), None) + self.sampler = selected_sampler + self.sampler_args_control.set_object_type(selected_sampler) + self.change() + + def update_sampler_args(self) -> None: + """Update the sampler args""" + if self.sampler_args_control.required_inputs_provided(): + self.sampler_args = self.sampler_args_control.value() + else: + self.sampler_args = '' + self.change() + + def change(self): + """Announce change to any registered change events.""" + if self.change_event: + self.change_event() + + +def clear_layout(layout): + """Clear all items from a layout. + https://stackoverflow.com/questions/9374063/remove-all-items-from-a-layout + """ + while layout.count(): + child = layout.takeAt(0) + if child.widget() is not None: + child.widget().setVisible(False) + child.widget().deleteLater() + elif child.layout() is not None: + clear_layout(child.layout()) + + +class MainPanel(QWidget): + """Main GUI window. + Parameters: + ----------- + json_file: path to the parameters file. + title: window title + size: window size; (width, height) + """ + + def __init__(self, title: str, size: Tuple[int, int]): + super().__init__() + self.title = title + self.w_size = size + + self.command = '' + + self.form = SimConfigForm(width=self.w_size[0], + change_event=self.on_params_change) + self.flash_msg = '' + self.init_ui() + + def init_ui(self): + """Initialize the UI""" + vbox = QVBoxLayout() + + header_box = QHBoxLayout() + header_box.addSpacing(4) + header_box.addWidget( + static_text_control(self, + label='BciPy Simulator Configuration', + size=16, + color='dimgray')) + vbox.addLayout(header_box) + vbox.addWidget(self.form) + vbox.addSpacing(4) + + # Controls + control_box = QHBoxLayout() + control_box.addStretch() + self.run_button = QPushButton('Run') + self.run_button.setFixedWidth(80) + self.run_button.clicked.connect(self.on_run) + self.run_button.setEnabled(False) + control_box.addWidget(self.run_button) + + vbox.addLayout(control_box) + + self.command_msg = static_text_control(self, + label='', + size=12, + color='darkgray') + vbox.addWidget(self.command_msg) + self.setLayout(vbox) + self.setFixedHeight(self.w_size[1]) + self.setWindowTitle(self.title) + self.show() + + def cli_output(self) -> str: + """Returns the command with arguments.""" + if self.form.command_valid(): + return self.form.command() + return '' + + def on_run(self): + """Event handler for running the simulation.""" + + if self.form.command_valid(): + self.command_msg.setText(self.cli_output()) + self.command_msg.repaint() + self.close() + + def on_params_change(self) -> None: + """Event performed when form parameters change.""" + if self.form.command_valid(): + self.run_button.setEnabled(True) + else: + self.run_button.setEnabled(False) + + +def init(title='BCI Simulator', size=(900, 600)) -> str: + """Set up the GUI components and start the main loop.""" + app = QApplication(sys.argv) + panel = MainPanel(title, size) + app.exec() + command = panel.cli_output() + app.quit() + if command: + print(command, file=sys.stdout) + subprocess.run(command, shell=True) + return command + + +def configure( + title='BCI Simulator', + size=(600, 900) +) -> Tuple[int, Optional[str], Optional[TaskFactory]]: + """Main function""" + app = QApplication(sys.argv) + panel = MainPanel(title, size) + app.exec() + command = panel.cli_output() + + runs = panel.form.runs() + outdir = panel.form.outdir() + params = panel.form.parameters_path + data_paths = panel.form.data_paths + model_paths = panel.form.model_paths + sampler = panel.form.sampler + sampler_args = panel.form.sampler_args + + app.quit() + + factory = None + if command: + print(command, file=sys.stdout) + parameters = load_json_parameters(params, value_cast=True) + factory = TaskFactory(parameters=parameters, + source_dirs=data_paths, + signal_model_paths=model_paths, + sampling_strategy=sampler, + sampler_args=json.loads(sampler_args), + task=SimulatorCopyPhraseTask) + return (runs, outdir, factory) + + +def run(): + """Process command line arguments and initialize the GUI.""" + parser = argparse.ArgumentParser() + + parser.add_argument('--width', default=600, type=int) + parser.add_argument('--height', default=900, type=int) + + args = parser.parse_args() + init(size=(args.width, args.height)) + + +if __name__ == '__main__': + run() diff --git a/bcipy/simulator/ui/gui_utils.py b/bcipy/simulator/ui/gui_utils.py new file mode 100644 index 000000000..c7bd84336 --- /dev/null +++ b/bcipy/simulator/ui/gui_utils.py @@ -0,0 +1,115 @@ +"""Helper functions for the GUI code""" +import inspect +from typing import (Any, Dict, List, NamedTuple, Optional, Tuple, Type, Union, + get_args, get_origin) + +# pylint: disable=wildcard-import,unused-wildcard-import +# flake8: noqa: F403 +from bcipy.simulator.data.sampler import * +from bcipy.simulator.data.sampler import Sampler, TargetNontargetSampler + +# This can be expanded as needed (ex. Path support). +SUPPORTED_INPUT_TYPES = ['int', 'str', 'float'] + + +class InputField(NamedTuple): + """Represents a GUI input parameter.""" + name: str + input_type: str + value: Optional[Any] = None + required: bool = True + + +def get_param_value(param: inspect.Parameter) -> Any: + """Default value of the argument.""" + is_empty = param.default is None or param.default == inspect.Parameter.empty + if is_empty: + return None + return param.default + + +def is_annotated(param: inspect.Parameter) -> bool: + """Test if an arg is annotated""" + return param.annotation != inspect.Parameter.empty + + +def get_input_type(param: inspect.Parameter) -> Tuple[Optional[str], bool]: + """For a given constructor parameter, determine the GUI input type. For + subscriptable types such as Optional, the first type is returned (except None). + + Returns a tuple of (type str, required) + """ + input_type = None + required = True + + # if this is a subscriptable type, such as Optional or Union, get the first sub-type. + origin = get_origin(param.annotation) + if origin: + # only check for Optional types. we don't currently provide GUI inputs for other + # subscriptable types such as Lists or Dicts. + if origin == Union: + sub_types = get_args(param.annotation) + if type(None) in sub_types: + required = False + input_type = next(sub_type for sub_type in sub_types + if not isinstance(sub_type, type(None))).__name__ + else: + input_type = param.annotation.__name__ + return input_type, required + + +def get_inputs(input_class: Type[Any]) -> List[InputField]: + """Given the class, determine the input parameters for GUI prompts. + Only outputs parameters with a type annotation for basic types that can be + input through a GUI (int, float, str). + """ + + # introspect the model arguments to determine what parameters to pass. + params = inspect.signature(input_class).parameters + + inputs = [] + for key in params.keys(): + param = params[key] + if is_annotated(param): + input_type, required = get_input_type(param) + # filter on types that we can input through the GUI + if input_type in SUPPORTED_INPUT_TYPES: + inputs.append( + InputField(name=param.name, + input_type=input_type, + value=get_param_value(param), + required=required)) + return inputs + + +def all_subclasses(parent_cls: Type[Any]): + """Get all subclasses of the given class. Note that a class can only see + a subclass if the module with the sub has been loaded. + See: https://stackoverflow.com/questions/3862310/how-to-find-all-the-subclasses-of-a-class-given-its-name""" + return set(parent_cls.__subclasses__()).union([ + sub for cls in parent_cls.__subclasses__() + for sub in all_subclasses(cls) + ]) + + +def sampler_options( + default: Type[Sampler] = TargetNontargetSampler +) -> Dict[str, Type[Sampler]]: + """Returns available samplers as a name -> class dict. + Orders with the default item first, then sorted alphabetically.""" + + subclasses = all_subclasses(Sampler) + if default in subclasses: + subclasses.remove(default) + subclasses = [ + default, *sorted(subclasses, key=lambda cls: cls.__name__) + ] + else: + subclasses = sorted(subclasses, key=lambda cls: cls.__name__) + return {cls.__name__: cls for cls in subclasses} + + +def sampler_inputs(sampler_class: Type[Sampler]) -> List[InputField]: + """Returns the list of inputs needed to initialize instances of the given + sampler class.""" + return get_inputs(sampler_class) diff --git a/bcipy/simulator/ui/obj_args_widget.py b/bcipy/simulator/ui/obj_args_widget.py new file mode 100644 index 000000000..6aa35a9d4 --- /dev/null +++ b/bcipy/simulator/ui/obj_args_widget.py @@ -0,0 +1,118 @@ +from typing import Any, Callable, List, Optional, Tuple, Type + +# pylint: disable=E0611 +from PyQt6.QtCore import Qt +from PyQt6.QtWidgets import QFormLayout, QLineEdit, QWidget + +from bcipy.core.list import find_index +from bcipy.gui.parameters.params_form import clear_layout +from bcipy.simulator.ui.gui_utils import InputField, get_inputs + + +class ObjectArgInputs(QWidget): + """Widget with inputs for parameters needed to instantiate an object for a + given class. + """ + + def __init__(self, + parent: Optional[QWidget] = None, + change_event: Optional[Callable] = None, + object_type: Optional[Type[Any]] = None): + super().__init__(parent=parent) + self.change_event = change_event + self.form_layout = QFormLayout() + self.form_layout.setFormAlignment(Qt.AlignmentFlag.AlignLeft + | Qt.AlignmentFlag.AlignVCenter) + self.form_layout.setFieldGrowthPolicy( + QFormLayout.FieldGrowthPolicy.AllNonFixedFieldsGrow) + + self.object_type = object_type + self.input_fields = self._init_input_fields() + self.controls = self._create_inputs() + self._add_controls() + self.setLayout(self.form_layout) + + def set_object_type(self, object_type: Optional[Type[Any]]) -> None: + """Set the class for which we should provide inputs.""" + self.object_type = object_type + self.input_fields = self._init_input_fields() + self.controls = self._create_inputs() + self._add_controls() + + def required_inputs_provided(self) -> bool: + """Check if required inputs have been filled out.""" + for label, control in self.controls: + field = self._field_definition(label) + if field.required and not self._input_value(field, control): + return False + return True + + def value(self) -> str: + """Returns a json string representing a dict of name: value for each input.""" + vals = ", ".join([ + self._json_name_value(name, control) + for (name, control) in self.controls + ]) + return f"{{{vals}}}" + + def _init_input_fields(self) -> List[InputField]: + """Determine the input fields for the configured object type.""" + if self.object_type: + return get_inputs(self.object_type) + return [] + + def _field_definition(self, name: str) -> InputField: + """Get the InputField for the control with the given name.""" + index = find_index(self.input_fields, name, key=lambda item: item.name) + if index is None: + raise KeyError(f"Not found: {name}") + return self.input_fields[index] + + def _json_name_value(self, name: str, control: QWidget) -> str: + """Returns a json partial for a name: value, quoting the value according + to the input_type + """ + field = self._field_definition(name) + value = self._input_value(field, control) + + if not value: + return f'"{name}": null' + if field.input_type == 'str': + value = f'"{value}"' + + return f'"{name}": {value}' + + def _create_inputs(self) -> List[Tuple[str, QWidget]]: + """Create inputs for the inputs for associated args.""" + return [(input_field.name, self._create_input(input_field)) + for input_field in self.input_fields] + + def _create_input(self, input_field: InputField) -> QWidget: + """Create an input for the given InputField""" + # currently only supports int, str, and float. Text inputs are used + # since the spinbox inputs do not allow a None value and default to + # 0, which is not always correct. + input_map = {'str': QLineEdit, 'int': QLineEdit, 'float': QLineEdit} + + make_control = input_map[input_field.input_type] + control = make_control() + if input_field.value is not None: + control.setText(str(input_field.value)) + control.textChanged.connect(self.change) + return control + + def _input_value(self, field: InputField, control: QWidget) -> Any: + """Get the cast value for the provided input.""" + # TODO: cast this according to its type + return control.text() + + def _add_controls(self) -> None: + """Add each input to the layout.""" + clear_layout(self.form_layout) + for (label, control) in self.controls: + self.form_layout.addRow(label, control) + + def change(self): + """Called when the sampler or any inputs change.""" + if self.change_event: + self.change_event() diff --git a/bcipy/simulator/util/artifact.py b/bcipy/simulator/util/artifact.py index dcc39f434..2859ff7af 100644 --- a/bcipy/simulator/util/artifact.py +++ b/bcipy/simulator/util/artifact.py @@ -1,9 +1,10 @@ -""" Handles artifacts related logic ie. logs, save dir creation, result.json, ...""" +"""Handles artifacts related logic ie. logs, save dir creation, result.json, ...""" + import datetime import logging import os import sys -from typing import Optional +from typing import Optional, Tuple from bcipy.config import ROOT @@ -13,12 +14,33 @@ TOP_LEVEL_LOGGER_NAME = 'sim_logger' DEFAULT_LOGFILE_NAME = 'sim.log' DEFAULT_SAVE_LOCATION = f"{ROOT}/data/simulator" +RUN_PREFIX = "run_" + +DEFAULT_VERBOSE = False + + +def set_verbose(value: bool) -> None: + """Set default verbose mode""" + # pylint: disable=global-statement + global DEFAULT_VERBOSE + DEFAULT_VERBOSE = value + + +def remove_handlers(log: logging.Logger) -> None: + """Remove any file handlers from the provided logger.""" + handlers = log.handlers[:] # make copy + for handler in handlers: + # call the method, which handles locking. + log.removeHandler(handler) + if isinstance(handler, logging.FileHandler): + handler.close() def configure_logger(log_path: str, file_name: str, logger_name: Optional[str] = None, - use_stdout: bool = True): + use_stdout: bool = True, + verbose: Optional[bool] = None) -> logging.Logger: """Configures logger for standard out and file output. Parameters @@ -27,64 +49,86 @@ def configure_logger(log_path: str, file_name - name of the log file logger_name - None configures the root logger; otherwise configures a named logger. use_stdout - if True, INFO messages will be output to stdout. + verbose - determines the log level; set True to log as DEBUG """ log = logging.getLogger(logger_name) # configuring root logger - log.setLevel(logging.DEBUG) - # Create handlers for logging to the standard output and a file - stdout_handler = logging.StreamHandler(stream=sys.stdout) - file_handler = logging.FileHandler(f"{log_path}/{file_name}") - # Set the log levels on the handlers - stdout_handler.setLevel(logging.INFO) - file_handler.setLevel(logging.DEBUG) + remove_handlers(log) + if verbose is None: + verbose = DEFAULT_VERBOSE + level = logging.DEBUG if verbose else logging.INFO + log.setLevel(level) fmt = '[%(asctime)s][%(name)s][%(levelname)s]: %(message)s' - fmt_file = logging.Formatter(fmt) - fmt_stdout = logging.Formatter("%(message)s") - # Set the log format on each handler - stdout_handler.setFormatter(fmt_stdout) - file_handler.setFormatter(fmt_file) - - # Add each handler to the Logger object - if use_stdout and stdout_handler not in log.handlers: + if use_stdout: + stdout_handler = logging.StreamHandler(stream=sys.stdout) + stdout_handler.setLevel(logging.INFO) + stdout_handler.setFormatter(logging.Formatter("%(message)s")) log.addHandler(stdout_handler) + file_handler = logging.FileHandler(f"{log_path}/{file_name}") + file_handler.setLevel(level) + file_handler.setFormatter(logging.Formatter(fmt)) log.addHandler(file_handler) + return log def init_simulation_dir(save_location: str = DEFAULT_SAVE_LOCATION, - logfile_name: str = DEFAULT_LOGFILE_NAME) -> str: + logfile_name: str = DEFAULT_LOGFILE_NAME, + verbose: Optional[bool] = None, + prefix: str = '') -> str: """Setup the folder structure and logging for a simulation. Parameters ---------- save_location - optional path in which new simulation directory will be created. logfile_name - optional name of the top level logfile within that directory. + verbose - optional flag to set the log level to DEBUG. + prefix - optional prefix for the simulation directory. Returns the path of the simulation directory. """ - save_dir = f"{save_location}/{directory_name()}" + save_dir = f"{save_location}/{prefix}{directory_name()}" os.makedirs(save_dir) configure_logger(save_dir, logfile_name, logger_name=TOP_LEVEL_LOGGER_NAME, - use_stdout=True) + use_stdout=True, + verbose=verbose) return save_dir -def configure_run_directory(sim_dir: str, run: int) -> str: +def configure_run_directory( + sim_dir: str, + run: int, + verbose: Optional[bool] = None) -> Tuple[str, logging.Logger]: """Create the necessary directories and configure the logger. Returns the run directory. """ - run_name = f"run_{run}" + run_name = f"{RUN_PREFIX}{run}" path = f"{sim_dir}/{run_name}" os.mkdir(path) - configure_logger(log_path=path, - file_name=f"{run_name}.log", - use_stdout=False) - return path + log = configure_logger(log_path=path, + file_name=f"{run_name}.log", + logger_name=None, + use_stdout=False, + verbose=verbose) + return path, log + + +def remove_file_logger(sim_dir: str, run: int) -> None: + """Disable any configured file handler for the root logger.""" + path = f"{sim_dir}/{RUN_PREFIX}{run}" + + log = logging.getLogger() + handlers = log.handlers[:] + for handler in handlers: + if isinstance(handler, + logging.FileHandler) and path in handler.baseFilename: + log.removeHandler(handler) + handler.close() def directory_name() -> str: diff --git a/bcipy/simulator/util/generate_marker_data.py b/bcipy/simulator/util/generate_marker_data.py new file mode 100644 index 000000000..634343253 --- /dev/null +++ b/bcipy/simulator/util/generate_marker_data.py @@ -0,0 +1,38 @@ +import argparse +from pathlib import Path + +from bcipy.config import DEFAULT_PARAMETERS_FILENAME +from bcipy.io.load import load_json_parameters +from bcipy.simulator.util.switch_utils import (generate_raw_data, + simulate_raw_data) + + +def main() -> Path: + """Main method used to generate a raw data file for a switch device.""" + parser = argparse.ArgumentParser( + description="Create raw marker data for a given session.") + parser.add_argument("data_folder", + type=Path, + help="Data directory (must contain triggers.txt file)") + mock_help = "Mock data (use when button presses are not recorded in trigger file)" + parser.add_argument("-m", "--mock", action='store_true', help=mock_help) + parser.add_argument( + "-p", + "--parameters", + type=Path, + required=False, + help="Optional parameters file to use when mocking data.") + args = parser.parse_args() + data_dir = args.data_folder + + if args.mock: + params_file = args.parameters or Path(data_dir, + DEFAULT_PARAMETERS_FILENAME) + params = load_json_parameters(str(params_file), value_cast=True) + return simulate_raw_data(data_dir, params) + else: + return generate_raw_data(data_dir) + + +if __name__ == '__main__': + print(str(main())) diff --git a/bcipy/simulator/util/metrics.py b/bcipy/simulator/util/metrics.py new file mode 100644 index 000000000..edecb742e --- /dev/null +++ b/bcipy/simulator/util/metrics.py @@ -0,0 +1,186 @@ +"""Summarize metrics across simulator runs.""" + +import logging +import sys +from collections import Counter +from json import load +from pathlib import Path +from typing import Any, Dict, List, Optional + +import matplotlib.pyplot as plt +import pandas as pd + +from bcipy.config import (DEFAULT_ENCODING, DEFAULT_PARAMETERS_FILENAME, + SESSION_DATA_FILENAME) +from bcipy.core.parameters import Parameters +from bcipy.helpers.acquisition import max_inquiry_duration +from bcipy.io.load import load_json_parameters +from bcipy.io.save import save_json_data +from bcipy.simulator.util.artifact import RUN_PREFIX, TOP_LEVEL_LOGGER_NAME + +logger = logging.getLogger(TOP_LEVEL_LOGGER_NAME) + +SUMMARY_DATA_FILE_NAME = "summary_data.json" +TASK_SUMMARY_PREFIX = "task_summary__" + + +def add_item(container: Dict[str, List], key: str, value: Any): + """Add or append value""" + if key in container: + container[key].append(value) + else: + container[key] = [value] + + +def get_final_typed(session_dict: Dict) -> str: + """Get the final typed word + + Parameters + ---------- + session_dict - Session data from a single run. + Equivalent to reading the Session and calling as_dict(). + + Returns + ------- + the final spelled text (from the last inquiry) + """ + all_series = session_dict['series'] + if all_series.keys(): + last_series_key = str(max(map(int, all_series.keys()))) + inquiries = all_series.get(last_series_key, {}) + if inquiries.keys(): + last_inquiry_key = str(max(map(int, inquiries.keys()))) + return inquiries.get(last_inquiry_key).get('next_display_state', + '') + return '' + + +def calculate_duration(inquiry_count: int, inquiry_seconds: float) -> float: + """Compute the total number of seconds.""" + return inquiry_count * inquiry_seconds + + +def add_items(combined_metrics: Dict, session_dict: Dict, + inquiry_seconds: float): + """Add all items of interest from the session data.""" + keys = [ + 'total_number_series', 'total_inquiries', 'total_selections', + 'inquiries_per_selection' + ] + for key in keys: + add_item(combined_metrics, key, session_dict[key]) + + # Summarize task_summary data. Task summaries may be different depending on + # task. Note that switch presses and typing rates are not accurately reflected + # in simulation so are removed from metrics. + for key in session_dict['task_summary'].keys(): + if 'switch' not in key and 'rate' not in key: + add_item(combined_metrics, f"{TASK_SUMMARY_PREFIX}{key}", + session_dict['task_summary'][key]) + + add_item(combined_metrics, 'typed', get_final_typed(session_dict)) + add_item( + combined_metrics, 'total_seconds', + calculate_duration(session_dict['total_inquiries'], inquiry_seconds)) + + +def session_paths(sim_dir: str) -> List[Path]: + """List of paths to the session.json files""" + return [ + Path(run_dir, SESSION_DATA_FILENAME) + for run_dir in sorted(Path(sim_dir).glob(f"{RUN_PREFIX}*/")) + ] + + +def sim_parameters(sim_dir: str) -> Parameters: + """Simulation parameters""" + return load_json_parameters( + str(Path(sim_dir, DEFAULT_PARAMETERS_FILENAME)), True) + + +def summarize(sim_dir: str) -> Dict[str, List[Any]]: + """Summarize all session runs. + + Parameters + ---------- + sim_dir - path to the simulation directory with 1 or more runs. + + Returns + ------- + a dict with a key for each metric of interest and a value which + is a list accumulating the value of that metric from each run. + ex. {'total_number_series': [14, 22, 12], ...} + """ + inquiry_seconds = max_inquiry_duration(sim_parameters(sim_dir)) + combined_metrics: Dict[str, List[Any]] = {} + for session_path in session_paths(sim_dir): + with open(session_path, 'r', encoding=DEFAULT_ENCODING) as json_file: + session_dict = load(json_file) + add_items(combined_metrics, session_dict, inquiry_seconds) + return combined_metrics + + +def rename_df_column(colname: str) -> str: + """Rename dataframe columns for reporting""" + if colname.startswith(TASK_SUMMARY_PREFIX): + return colname[len(TASK_SUMMARY_PREFIX):] + return colname + + +def log_descriptive_stats(df: pd.DataFrame) -> None: + """Log the descriptive statistics for the given dataframe. + + See https://stackoverflow.com/questions/25351968/how-can-i-display-full-non-truncated-dataframe-information-in-html-when-conver + """ + df.rename(columns=rename_df_column, inplace=True) + + pd.set_option('display.max_columns', None) + pd.set_option('display.width', 2000) + pd.set_option('display.float_format', "{:20,.2f}".format) + pd.set_option('display.max_colwidth', None) + + logger.info(f"Metrics:\n{df.describe()}") + + pd.reset_option('display.max_columns') + pd.reset_option('display.width') + pd.reset_option('display.float_format') + pd.reset_option('display.max_colwidth') + + +def plot_save_path(sim_dir: str) -> str: + """Save path for plots.""" + return f"{sim_dir}/metrics.png" + + +def plot_results(df: pd.DataFrame, + save_path: Optional[str] = None, + show: bool = True) -> None: + """Plot the dataframe""" + cols = [ + 'total_selections', 'total_inquiries', 'inquiries_per_selection', + 'selections_correct', 'selections_incorrect' + ] + df.boxplot(column=cols, figsize=(11, 8.5)) + if save_path: + plt.savefig(save_path) + if show: + plt.show() + + +def report(sim_dir: str, show_plots: bool = False) -> None: + """Summarize the data, write as a JSON file, and output a summary to the top level log file.""" + summary = summarize(sim_dir) + save_json_data(summary, sim_dir, SUMMARY_DATA_FILE_NAME) + + df = pd.DataFrame(summary) + log_descriptive_stats(df) + + logger.info("Typed:") + logger.info(Counter(summary.get('typed'))) + ave_minutes = round((df['total_seconds'] / 60).mean(), 2) + logger.info(f"Average duration: {ave_minutes} minutes") + plot_results(df, save_path=plot_save_path(sim_dir), show=show_plots) + + +if __name__ == '__main__': + report(sim_dir=sys.argv[1]) diff --git a/bcipy/simulator/util/replay_comparison.py b/bcipy/simulator/util/replay_comparison.py new file mode 100644 index 000000000..f13d7b342 --- /dev/null +++ b/bcipy/simulator/util/replay_comparison.py @@ -0,0 +1,132 @@ +"""Generates plots for replay session.""" +import logging +from pathlib import Path +from typing import List, NamedTuple + +import matplotlib.pyplot as plt +import pandas as pd +import seaborn as sns + +from bcipy.config import SESSION_DATA_FILENAME +from bcipy.core.session import evidence_records, read_session +from bcipy.simulator.util.artifact import TOP_LEVEL_LOGGER_NAME +from bcipy.simulator.util.metrics import session_paths + +logger = logging.getLogger(TOP_LEVEL_LOGGER_NAME) + + +class Record(NamedTuple): + """Record for plotting.""" + which_model: str + response_value: float + + +def make_record(is_original_model: bool, is_target: bool, + response_value: float) -> Record: + """Construct a new Record""" + prefix = "old" if is_original_model else "new" + ev_type = "target" if is_target else "nontarget" + + return Record(f"{prefix}_{ev_type}", response_value) + + +def load_eeg_records(session_json: Path, + is_original_model: bool) -> List[Record]: + """Load EEG evidence from session.json file for comparison with replay outputs. + + Parameters + ---------- + session_json - path to session.json file + """ + session = read_session(str(session_json)) + return [ + make_record(is_original_model=is_original_model, + is_target=bool(ev_record.is_target), + response_value=ev_record.eeg) + for ev_record in evidence_records(session) + ] + + +def prepare_data(sim_dir: str, data_folders: List[str]) -> List[Record]: + """Prepare the data for plotting. + + Parameters + ---------- + sim_dir - simulation directory path + data_folders - data folders used in the simulation + """ + + original_sessions = [ + Path(folder, SESSION_DATA_FILENAME) for folder in data_folders + ] + simulated_sessions = session_paths(sim_dir) + + records = [] + for session_path in simulated_sessions: + records.extend(load_eeg_records(session_path, is_original_model=False)) + for session_path in original_sessions: + records.extend(load_eeg_records(session_path, is_original_model=True)) + + return records + + +def plot(sim_dir: str, data: List[Record]) -> None: + """Plot the summary + + Parameters + ---------- + sim_dir - simulation directory; figures will be written here. + df - dataframe with the evidence data + """ + df = pd.DataFrame(data) + logger.info(f"{df.describe()}") + data_order = ["old_target", "new_target", "old_nontarget", "new_nontarget"] + + ax = sns.stripplot( + x="which_model", + y="response_value", + data=df, + order=data_order, + ) + sns.boxplot( + showmeans=True, + meanline=True, + meanprops={ + "color": "k", + "ls": "-", + "lw": 2 + }, + medianprops={"visible": False}, + whiskerprops={"visible": False}, + zorder=10, + x="which_model", + y="response_value", + data=df, + showfliers=False, + showbox=False, + showcaps=False, + ax=ax, + order=data_order, + ) + + ax.set(yscale="log") + plt.savefig(Path(sim_dir, "response_values.stripplot.png"), + dpi=150, + bbox_inches="tight") + plt.close() + ax = sns.boxplot( + x="which_model", + y="response_value", + data=df, + order=data_order, + ) + ax.set(yscale="log") + plt.savefig(Path(sim_dir, "response_values.boxplot.png"), + dpi=150, + bbox_inches="tight") + + +def comparison_metrics(sim_dir, data_folders: List[str]) -> None: + """Compare the simulated results with the original.""" + data = prepare_data(sim_dir, data_folders) + plot(sim_dir, data) diff --git a/bcipy/simulator/util/state.py b/bcipy/simulator/util/state.py index a048dd8a7..abb6ca4ce 100644 --- a/bcipy/simulator/util/state.py +++ b/bcipy/simulator/util/state.py @@ -5,12 +5,13 @@ from typing import Any, Dict, List from bcipy.config import SESSION_DATA_FILENAME -from bcipy.helpers.session import read_session +from bcipy.core.session import read_session @dataclass class SimState: - """ Represents the state of a current session during simulation """ + """Represents the state of a current session during simulation.""" + target_symbol: str current_sentence: str target_sentence: str @@ -20,8 +21,7 @@ class SimState: def get_inquiry(session_dir: str, n: int) -> Dict[str, Any]: - """Extracts an inquiry from a session.json file. Useful for debugging - simulator output.""" + """Extracts an inquiry from a session.json file. Useful for debugging simulator output.""" session = read_session(f"{session_dir}/{SESSION_DATA_FILENAME}") inq = session.all_inquiries[n] return inq.stim_evidence(session.symbol_set) diff --git a/bcipy/simulator/util/switch_utils.py b/bcipy/simulator/util/switch_utils.py new file mode 100644 index 000000000..680412586 --- /dev/null +++ b/bcipy/simulator/util/switch_utils.py @@ -0,0 +1,147 @@ +"""Utilities for working with switch data.""" + +import random +from pathlib import Path +from typing import List, Tuple + +from bcipy import config +from bcipy.acquisition.datastream.mock.switch import switch_device +from bcipy.core.list import pairwise +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawDataWriter +from bcipy.core.triggers import Trigger, TriggerType, load_triggers +from bcipy.display.main import ButtonPressMode, PreviewParams +from bcipy.helpers.acquisition import raw_data_filename + + +def partition_triggers(trigger_path: Path) -> List[List[Trigger]]: + """Partition the triggers into inquiries. + + Returns + ------- + list of entries where each entry represents the triggers for an inquiry. + """ + triggers = load_triggers(str(trigger_path), + remove_pre_fixation=False, + apply_starting_offset=False) + includes_preview = any(trg.type == TriggerType.PREVIEW for trg in triggers) + start_type = TriggerType.PREVIEW if includes_preview else TriggerType.FIXATION + + # index for each prompt trigger + inq_start_indices = [ + i for i, trg in enumerate(triggers) if trg.type == start_type + ] + inquiry_triggers = [] + for i, j in pairwise(inq_start_indices): + inquiry_triggers.append(triggers[i:j]) + inquiry_triggers.append(triggers[inq_start_indices[-1]:]) + + return inquiry_triggers + + +def has_target(triggers: List[Trigger]) -> bool: + """Check if the list of inquiries contains a target.""" + for trg in triggers: + if trg.type == TriggerType.TARGET: + return True + return False + + +def time_range(inquiry_triggers: List[Trigger], + time_flash: float) -> Tuple[float, float]: + """Given a list of triggers for a given inquiry, determine the start and end timestamps of that inquiry.""" + return (inquiry_triggers[0].time, inquiry_triggers[-1].time + time_flash) + + +def inquiry_windows(trigger_path: Path, + time_flash: float) -> List[Tuple[float, float]]: + """Returns a list of (inquiry_start, inquiry_stop) timestamp pairs for all inquiries in the trigger file.""" + return [ + time_range(inq_triggers, time_flash) + for inq_triggers in partition_triggers(trigger_path) + ] + + +def should_press_switch(inquiry_triggers: List[Trigger], + button_press_mode: ButtonPressMode) -> bool: + """Determine if a marker should be written for the given inquiry depending on the presence of a target and the button press mode.""" + return (button_press_mode == ButtonPressMode.ACCEPT + and has_target(inquiry_triggers)) or ( + button_press_mode == ButtonPressMode.REJECT + and not has_target(inquiry_triggers)) + + +def timestamp_within_inquiry(inquiry_triggers: List[Trigger], + parameters: Parameters) -> float: + """Timestamp is a random value between inquiry start and end.""" + inq_start, inq_end = time_range(inquiry_triggers, parameters['time_flash']) + return random.uniform(inq_start, inq_end) + + +def simulate_raw_data(data_dir: Path, parameters: Parameters) -> Path: + """Simulate what the raw_data file for a switch would generate. + + Reads through trigger data. For inquiries with target, outputs one or + more markers within the inquiry timestamp range. Or if press to reject, + output markers for inquiries without target. + """ + + spec = switch_device() + raw_data_path = Path(data_dir, raw_data_filename(spec)) + + if raw_data_path.exists(): + return raw_data_path + + # determine button mode from parameters + button_press_mode = parameters.instantiate(PreviewParams).button_press_mode + + columns = ['timestamp', 'Marker', 'lsl_timestamp'] + rownum = 0 + with RawDataWriter(str(raw_data_path), + daq_type=spec.name, + sample_rate=spec.sample_rate, + columns=columns) as writer: + for inquiry_triggers in partition_triggers( + Path(data_dir, config.TRIGGER_FILENAME)): + if should_press_switch(inquiry_triggers, button_press_mode): + rownum += 1 + stamp = timestamp_within_inquiry(inquiry_triggers, parameters) + writer.writerow([rownum, 1.0, stamp]) + + return raw_data_path + + +def generate_raw_data(data_dir: Path, + event_label_prefix: str = 'bcipy_key_press') -> Path: + """Given a data directory for a task where the Inquiry Preview feature was used, + output a raw_data file for the switch data. + + Parameters + ---------- + data_dir - data directory for a task which should include a triggers.txt file. + event_label_prefix - optional label given to key press events (see task.py get_key_press). + """ + + spec = switch_device() + raw_data_path = Path(data_dir, raw_data_filename(spec)) + + if raw_data_path.exists(): + return raw_data_path + + trigger_path = Path(data_dir, config.TRIGGER_FILENAME) + triggers = load_triggers(str(trigger_path), apply_starting_offset=False) + + key_press_triggers = [ + trg for trg in triggers + if trg.type == TriggerType.EVENT and event_label_prefix in trg.label + ] + + columns = ['timestamp', 'Marker', 'lsl_timestamp'] + with RawDataWriter(str(raw_data_path), + daq_type=spec.name, + sample_rate=spec.sample_rate, + columns=columns) as writer: + for i, trg in enumerate(key_press_triggers): + writer.writerow([i + 1, 1.0, trg.time]) + + return raw_data_path diff --git a/bcipy/static/images/gui/cambi_fav.ico b/bcipy/static/images/gui/cambi_fav.ico new file mode 100644 index 000000000..897130825 Binary files /dev/null and b/bcipy/static/images/gui/cambi_fav.ico differ diff --git a/bcipy/task/__init__.py b/bcipy/task/__init__.py index 2a60353aa..0ad844a15 100644 --- a/bcipy/task/__init__.py +++ b/bcipy/task/__init__.py @@ -2,7 +2,6 @@ This import statement allows users to import submodules from Task """ from .main import Task, TaskData, TaskMode - # Makes the following classes available to the task registry from .registry import TaskRegistry diff --git a/bcipy/task/actions.py b/bcipy/task/actions.py index 907e7456a..ac943ce9f 100644 --- a/bcipy/task/actions.py +++ b/bcipy/task/actions.py @@ -1,38 +1,51 @@ # mypy: disable-error-code="assignment,arg-type" -import subprocess -from typing import Any, Optional, List, Callable, Tuple +"""Task actions module for BCI tasks. + +This module provides various task actions that can be executed as part of a BCI +experiment, including code hooks, offline analysis, intertask management, and +report generation. +""" + +import glob import logging +import subprocess from pathlib import Path -import glob +from typing import Any, Callable, Dict, List, Optional, Tuple -from bcipy.gui.bciui import run_bciui from matplotlib.figure import Figure +from bcipy.acquisition import devices +from bcipy.acquisition.devices import DeviceSpec +from bcipy.config import (RAW_DATA_FILENAME, SESSION_LOG_FILENAME, + TRIGGER_FILENAME) +from bcipy.core.parameters import Parameters +from bcipy.core.raw_data import RawData +from bcipy.core.report import (Report, ReportSection, SessionReportSection, + SignalReportSection) +from bcipy.core.triggers import TriggerType, trigger_decoder +from bcipy.gui.bciui import run_bciui +from bcipy.gui.experiments.ExperimentField import \ + start_experiment_field_collection_gui from bcipy.gui.file_dialog import ask_directory from bcipy.gui.intertask_gui import IntertaskGUI -from bcipy.gui.experiments.ExperimentField import start_experiment_field_collection_gui -from bcipy.task import Task, TaskMode, TaskData -from bcipy.helpers.triggers import trigger_decoder, TriggerType - -from bcipy.acquisition import devices from bcipy.helpers.acquisition import analysis_channels -from bcipy.helpers.parameters import Parameters -from bcipy.acquisition.devices import DeviceSpec -from bcipy.helpers.load import load_raw_data -from bcipy.helpers.raw_data import RawData -from bcipy.signal.process import get_default_transform -from bcipy.helpers.report import SignalReportSection, SessionReportSection, Report, ReportSection -from bcipy.config import SESSION_LOG_FILENAME, RAW_DATA_FILENAME, TRIGGER_FILENAME from bcipy.helpers.visualization import visualize_erp +from bcipy.io.load import load_raw_data from bcipy.signal.evaluate.artifact import ArtifactDetection - +from bcipy.signal.process import get_default_transform +from bcipy.task import Task, TaskData, TaskMode logger = logging.getLogger(SESSION_LOG_FILENAME) class CodeHookAction(Task): - """ - Action for running generic code hooks. + """Action for running generic code hooks. + + Attributes: + name: Name of the task. + mode: Task execution mode. + code_hook: Code to execute. + subprocess: Whether to run in a subprocess. """ name = "CodeHookAction" @@ -45,23 +58,43 @@ def __init__( code_hook: Optional[str] = None, subprocess: bool = True, **kwargs) -> None: + """Initialize the code hook action. + + Args: + parameters: Task parameters. + data_directory: Directory for data storage. + code_hook: Code to execute. + subprocess: Whether to run in a subprocess. + **kwargs: Additional keyword arguments. + """ super().__init__() self.code_hook = code_hook self.subprocess = subprocess def execute(self) -> TaskData: + """Execute the code hook. + + Returns: + TaskData: Empty task data. + """ if self.code_hook: if self.subprocess: subprocess.Popen(self.code_hook, shell=True) - else: subprocess.run(self.code_hook, shell=True) return TaskData() class OfflineAnalysisAction(Task): - """ - Action for running offline analysis. + """Action for running offline analysis. + + Attributes: + name: Name of the task. + mode: Task execution mode. + parameters: Task parameters. + parameters_path: Path to parameters file. + data_directory: Directory containing data to analyze. + alert_finished: Whether to alert when analysis completes. """ name = "OfflineAnalysisAction" @@ -75,6 +108,16 @@ def __init__( last_task_dir: Optional[str] = None, alert_finished: bool = False, **kwargs: Any) -> None: + """Initialize the offline analysis action. + + Args: + parameters: Task parameters. + data_directory: Directory containing data to analyze. + parameters_path: Path to parameters file. + last_task_dir: Directory of last executed task. + alert_finished: Whether to alert when analysis completes. + **kwargs: Additional keyword arguments. + """ super().__init__() self.parameters = parameters self.parameters_path = parameters_path @@ -93,6 +136,11 @@ def execute(self) -> TaskData: to stop execution. For example, if Exception is thrown in cross_validation due to the # of folds being inconsistent. + Returns: + TaskData: Contains analysis results and parameters. + + Raises: + Exception: If offline analysis fails. """ logger.info("Running offline analysis action") try: @@ -117,6 +165,21 @@ def execute(self) -> TaskData: class IntertaskAction(Task): + """Action for managing transitions between tasks. + + Attributes: + name: Name of the task. + mode: Task execution mode. + tasks: List of tasks to manage. + current_task_index: Index of current task. + save_folder: Directory for saving task data. + parameters: Task parameters. + next_task_index: Index of next task to execute. + task_name: Name of current task. + task_names: List of task names. + exit_callback: Function to call on exit. + """ + name = "IntertaskAction" mode = TaskMode.ACTION tasks: List[Task] @@ -130,11 +193,25 @@ def __init__( tasks: Optional[List[Task]] = None, exit_callback: Optional[Callable] = None, **kwargs: Any) -> None: + """Initialize the intertask action. + + Args: + parameters: Task parameters. + save_path: Directory for saving task data. + progress: Current progress (1-indexed). + tasks: List of tasks to manage. + exit_callback: Function to call on exit. + **kwargs: Additional keyword arguments. + + Raises: + AssertionError: If progress or tasks is None, or if progress < 0. + """ super().__init__() self.save_folder = save_path self.parameters = parameters assert progress is not None and tasks is not None, "Either progress or tasks must be provided" - self.next_task_index = progress # progress is 1-indexed, tasks is 0-indexed so we can use the same index + # progress is 1-indexed, tasks is 0-indexed so we can use the same index + self.next_task_index = progress assert self.next_task_index >= 0, "Progress must be greater than 1 " self.tasks = tasks self.task_name = self.tasks[self.next_task_index].name @@ -142,7 +219,11 @@ def __init__( self.exit_callback = exit_callback def execute(self) -> TaskData: + """Execute the intertask action. + Returns: + TaskData: Contains task state information. + """ run_bciui( IntertaskGUI, tasks=self.task_names, @@ -159,12 +240,19 @@ def execute(self) -> TaskData: ) def alert(self): + """Handle alerts (not implemented).""" pass class ExperimentFieldCollectionAction(Task): - """ - Action for collecting experiment field data. + """Action for collecting experiment field data. + + Attributes: + name: Name of the task. + mode: Task execution mode. + experiment_id: Identifier for the experiment. + save_folder: Directory for saving collected data. + parameters: Task parameters. """ name = "ExperimentFieldCollectionAction" @@ -176,16 +264,30 @@ def __init__( data_directory: str, experiment_id: str = 'default', **kwargs: Any) -> None: + """Initialize the experiment field collection action. + + Args: + parameters: Task parameters. + data_directory: Directory for saving collected data. + experiment_id: Identifier for the experiment. + **kwargs: Additional keyword arguments. + """ super().__init__() self.experiment_id = experiment_id self.save_folder = data_directory self.parameters = parameters def execute(self) -> TaskData: + """Execute the experiment field collection. + + Returns: + TaskData: Contains experiment metadata. + """ logger.info( f"Collecting experiment field data for experiment {self.experiment_id} in save folder {self.save_folder}" ) - start_experiment_field_collection_gui(self.experiment_id, self.save_folder) + start_experiment_field_collection_gui( + self.experiment_id, self.save_folder) return TaskData( save_path=self.save_folder, task_dict={ @@ -195,8 +297,22 @@ def execute(self) -> TaskData: class BciPyCalibrationReportAction(Task): - """ - Action for generating a report after calibration Tasks. + """Action for generating a report after calibration Tasks. + + Attributes: + name: Name of the task. + mode: Task execution mode. + parameters: Task parameters. + save_folder: Directory for saving reports. + protocol_path: Path to protocol file. + last_task_dir: Directory of last executed task. + trial_window: Time window for trial analysis. + report: Report instance. + report_sections: List of report sections. + all_raw_data: List of raw data. + default_transform: Signal transformation function. + type_amp: Amplifier type. + static_offset: Static offset value. """ name = "BciPyReportAction" @@ -210,6 +326,16 @@ def __init__( last_task_dir: Optional[str] = None, trial_window: Optional[Tuple[float, float]] = None, **kwargs: Any) -> None: + """Initialize the calibration report action. + + Args: + parameters: Task parameters. + save_path: Directory for saving reports. + protocol_path: Path to protocol file. + last_task_dir: Directory of last executed task. + trial_window: Time window for trial analysis. + **kwargs: Additional keyword arguments. + """ super().__init__() self.save_folder = save_path # Currently we assume all Tasks have the same parameters, this may change in the future. @@ -217,7 +343,8 @@ def __init__( if not protocol_path: protocol_path = ask_directory( - prompt="Select BciPy protocol directory with calibration data...") + prompt="Select BciPy protocol directory with calibration data...", + strict=True) self.protocol_path = protocol_path self.last_task_dir = last_task_dir self.trial_window = (-0.2, 1.0) @@ -231,9 +358,12 @@ def __init__( self.static_offset = None def execute(self) -> TaskData: - """Excute the report generation action. + """Execute the report generation action. This assumes all data were collected using the same protocol, device, and parameters. + + Returns: + TaskData: Contains report data and metadata. """ logger.info(f"Generating report in save folder {self.save_folder}") # loop through all the files in the last_task_dir @@ -252,14 +382,17 @@ def execute(self) -> TaskData: task_name = path_data_dir.parts[-1].split('_')[0] data_directories.append(path_data_dir) # For each calibration directory, attempt to load the raw data - signal_report_section = self.create_signal_report(path_data_dir) - session_report = self.create_session_report(path_data_dir, task_name) + signal_report_section = self.create_signal_report( + path_data_dir) + session_report = self.create_session_report( + path_data_dir, task_name) self.report_sections.append(session_report) self.report.add(session_report) self.report_sections.append(signal_report_section) self.report.add(signal_report_section) if data_directories: - logger.info(f"Saving report generated from: {self.protocol_path}") + logger.info( + f"Saving report generated from: {self.protocol_path}") else: logger.info(f"No data found in {self.protocol_path}") @@ -268,6 +401,7 @@ def execute(self) -> TaskData: self.report.compile() self.report.save() + return TaskData( save_path=self.save_folder, task_dict={ @@ -276,6 +410,14 @@ def execute(self) -> TaskData: ) def create_signal_report(self, data_dir: Path) -> SignalReportSection: + """Create a report section for signal quality metrics. + + Args: + data_dir: Directory containing signal data. + + Returns: + SignalReportSection: Report section containing signal metrics. + """ raw_data = load_raw_data(Path(data_dir, f'{RAW_DATA_FILENAME}.csv')) if not self.type_amp: self.type_amp = raw_data.daq_type @@ -296,11 +438,22 @@ def create_signal_report(self, data_dir: Path) -> SignalReportSection: triggers = self.get_triggers(data_dir) # get figure handles - figure_handles = self.get_figure_handles(raw_data, channel_map, triggers) - artifact_detector = self.get_artifact_detector(raw_data, device_spec, triggers) + figure_handles = self.get_figure_handles( + raw_data, channel_map, triggers) + artifact_detector = self.get_artifact_detector( + raw_data, device_spec, triggers) return SignalReportSection(figure_handles, artifact_detector) - def create_session_report(self, data_dir, task_name) -> SessionReportSection: + def create_session_report(self, data_dir: Path, task_name: str) -> SessionReportSection: + """Create a report section for session information. + + Args: + data_dir: Directory containing session data. + task_name: Name of the task. + + Returns: + SessionReportSection: Report section containing session info. + """ # get task name summary_dict = { "task": task_name, @@ -312,11 +465,17 @@ def create_session_report(self, data_dir, task_name) -> SessionReportSection: return SessionReportSection(summary_dict) - def get_signal_model_metrics(self, data_directory: Path) -> dict: + def get_signal_model_metrics(self, data_directory: Path) -> Dict[str, Any]: """Get the signal model metrics from the session folder. In the future, the model will save a ModelMetrics with the pkl file. For now, we just look for the pkl file and extract the AUC from the filename. + + Args: + data_directory: Directory containing model data. + + Returns: + Dict[str, Any]: Dictionary of model metrics. """ pkl_file = None for file in data_directory.iterdir(): @@ -332,6 +491,11 @@ def get_signal_model_metrics(self, data_directory: Path) -> dict: return {'AUC': auc} def set_default_transform(self, sample_rate: int) -> None: + """Set the default signal transformation function. + + Args: + sample_rate: Sampling rate of the signal. + """ downsample_rate = self.parameters.get("down_sampling_rate") notch_filter = self.parameters.get("notch_filter_frequency") filter_high = self.parameters.get("filter_high") @@ -346,7 +510,15 @@ def set_default_transform(self, sample_rate: int) -> None: downsample_factor=downsample_rate, ) - def find_eye_channels(self, device_spec: DeviceSpec) -> Optional[list]: + def find_eye_channels(self, device_spec: DeviceSpec) -> Optional[List[str]]: + """Find eye-tracking channels in the device specification. + + Args: + device_spec: Device specification. + + Returns: + Optional[List[str]]: List of eye channel names if found. + """ eye_channels = [] for channel in device_spec.channels: if 'F' in channel: @@ -355,7 +527,15 @@ def find_eye_channels(self, device_spec: DeviceSpec) -> Optional[list]: eye_channels = None return eye_channels - def get_triggers(self, session: str) -> tuple: + def get_triggers(self, session: str) -> Tuple[List[Any], List[float], List[str]]: + """Get triggers from the session data. + + Args: + session: Path to session directory. + + Returns: + Tuple[List[Any], List[float], List[str]]: Trigger type, timing, and labels. + """ trigger_type, trigger_timing, trigger_label = trigger_decoder( offset=self.static_offset, trigger_path=f"{session}/{TRIGGER_FILENAME}", @@ -367,7 +547,18 @@ def get_triggers(self, session: str) -> tuple: ) return trigger_type, trigger_timing, trigger_label - def get_figure_handles(self, raw_data, channel_map, triggers) -> List[Figure]: + def get_figure_handles(self, raw_data: RawData, channel_map: List[str], + triggers: Tuple[TriggerType, List[float], List[str]]) -> List[Figure]: + """Generate figures for the report. + + Args: + raw_data: Raw signal data. + channel_map: List of channel names. + triggers: Tuple of trigger type, timing, and labels. + + Returns: + List[Figure]: List of generated figures. + """ trigger_type, trigger_timing, _ = triggers figure_handles = visualize_erp( raw_data, @@ -382,7 +573,18 @@ def get_figure_handles(self, raw_data, channel_map, triggers) -> List[Figure]: ) return figure_handles - def get_artifact_detector(self, raw_data, device_spec, triggers) -> ArtifactDetection: + def get_artifact_detector(self, raw_data: RawData, device_spec: DeviceSpec, + triggers: Tuple[TriggerType, List[float], List[str]]) -> ArtifactDetection: + """Create an artifact detector for the signal data. + + Args: + raw_data: Raw signal data. + device_spec: Device specification. + triggers: Tuple of trigger type, timing, and labels. + + Returns: + ArtifactDetection: Configured artifact detector. + """ eye_channels = self.find_eye_channels(device_spec) artifact_detector = ArtifactDetection( raw_data, diff --git a/bcipy/task/calibration.py b/bcipy/task/calibration.py index c80496480..9f416534d 100644 --- a/bcipy/task/calibration.py +++ b/bcipy/task/calibration.py @@ -1,4 +1,6 @@ """Base calibration task.""" +# mypy: disable-error-code="override" +import logging from abc import abstractmethod from typing import Any, Dict, Iterator, List, NamedTuple, Optional, Tuple @@ -7,25 +9,24 @@ import bcipy.task.data as session_data from bcipy.acquisition import ClientManager -from bcipy.config import (SESSION_DATA_FILENAME, TRIGGER_FILENAME, - WAIT_SCREEN_MESSAGE, SESSION_LOG_FILENAME) -from bcipy.helpers.acquisition import init_acquisition, LslDataServer -from bcipy.display import init_display_window, Display +from bcipy.config import (SESSION_DATA_FILENAME, SESSION_LOG_FILENAME, + TRIGGER_FILENAME, WAIT_SCREEN_MESSAGE) +from bcipy.core.parameters import Parameters +from bcipy.core.stimuli import (DEFAULT_TEXT_FIXATION, StimuliOrder, + TargetPositions, + generate_calibration_inquiries) +from bcipy.core.symbols import alphabet +from bcipy.core.triggers import (FlushFrequency, Trigger, TriggerHandler, + TriggerType, convert_timing_triggers, + offset_label) +from bcipy.display import Display, init_display_window +from bcipy.helpers.acquisition import LslDataServer, init_acquisition from bcipy.helpers.clock import Clock -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.save import _save_session_related_data -from bcipy.helpers.stimuli import (DEFAULT_TEXT_FIXATION, StimuliOrder, - TargetPositions, - generate_calibration_inquiries) -from bcipy.helpers.symbols import alphabet from bcipy.helpers.task import (get_user_input, pause_calibration, trial_complete_message) -from bcipy.helpers.triggers import (FlushFrequency, Trigger, TriggerHandler, - TriggerType, convert_timing_triggers, - offset_label) +from bcipy.io.save import _save_session_related_data from bcipy.task import Task, TaskData, TaskMode -import logging logger = logging.getLogger(SESSION_LOG_FILENAME) @@ -126,6 +127,7 @@ def setup( parameters: Parameters, data_save_location: str, fake: bool = False) -> Tuple[ClientManager, List[LslDataServer], Window]: + """Set up acquisition and return client manager, data servers, and window.""" # Initialize Acquisition daq, servers = init_acquisition( parameters, data_save_location, server=fake) @@ -213,7 +215,7 @@ def init_session(self) -> session_data.Session: task_data=self.session_task_data()) def session_task_data(self) -> Optional[Dict[str, Any]]: - """"Task-specific session data""" + """Task-specific session data.""" return None def trigger_type(self, @@ -346,8 +348,7 @@ def write_trigger_data(self, timing: List[Tuple[str, float]], convert_timing_triggers(timing, timing[0][0], self.trigger_type)) def write_offset_trigger(self) -> None: - """Append an offset value to the end of the trigger file. - """ + """Append an offset value to the end of the trigger file.""" # To help support future refactoring or use of lsl timestamps only # we write only the sample offset here. triggers = [] diff --git a/bcipy/task/control/criteria.py b/bcipy/task/control/criteria.py index 701fb544d..b51eb1d82 100644 --- a/bcipy/task/control/criteria.py +++ b/bcipy/task/control/criteria.py @@ -1,55 +1,95 @@ -import numpy as np +"""Decision criteria module for BCI task control. + +This module provides classes for evaluating decision criteria in BCI tasks. +These criteria are used to determine when to stop collecting evidence and +make a decision based on the accumulated data. +""" + import logging -from typing import Dict, List from copy import copy +from typing import Any, Dict, List, Optional + +import numpy as np from bcipy.config import SESSION_LOG_FILENAME + log = logging.getLogger(SESSION_LOG_FILENAME) class DecisionCriteria: - """Abstract class for Criteria which can be applied to evaluate a inquiry + """Abstract base class for decision criteria evaluation. + + This class defines the interface for criteria that can be applied to + evaluate whether a decision should be made based on accumulated evidence. + + Attributes: + None """ - def __init__(self, **kwargs): + def __init__(self, **kwargs: Any) -> None: + """Initialize the decision criteria. + + Args: + **kwargs: Arbitrary keyword arguments. + """ pass - def reset(self): + def reset(self) -> None: + """Reset the criteria state.""" pass - def decide(self, series: Dict): - """ - Apply the given criteria. - Parameters: - ----------- - series - series data - - target(str): target of the series - - time_spent(ndarray[float]): |num_trials|x1 - time spent on the inquiry - - list_sti(list[list[str]]): presented symbols in each - inquiry - - list_distribution(list[ndarray[float]]): list of |alp|x1 - arrays with prob. dist. over alp + def decide(self, series: Dict[str, Any]) -> bool: + """Apply the decision criteria to the given series data. + + Args: + series: Dictionary containing series data with the following keys: + target (str): Target of the series. + time_spent (np.ndarray): Time spent on each inquiry. + list_sti (List[List[str]]): Presented symbols in each inquiry. + list_distribution (List[np.ndarray]): Probability distributions + over the alphabet for each inquiry. + + Returns: + bool: True if the criteria is met, False otherwise. + Raises: + NotImplementedError: This is an abstract method. """ raise NotImplementedError() class MinIterationsCriteria(DecisionCriteria): - """ Returns true if the minimum number of iterations have not yet - been reached. """ + """Criteria for ensuring a minimum number of iterations. - def __init__(self, min_num_inq: int): - """ Args: - min_num_inq(int): minimum number of inquiry number before any - termination objective is allowed to be triggered """ + Returns true if the minimum number of iterations have not yet been reached. + + Attributes: + min_num_inq: Minimum number of inquiries required. + """ + + def __init__(self, min_num_inq: int) -> None: + """Initialize the minimum iterations criteria. + + Args: + min_num_inq: Minimum number of inquiries required before any + termination objective is allowed to be triggered. + """ self.min_num_inq = min_num_inq - def decide(self, series: Dict): - # Note: we use 'list_sti' parameter since this is the number of - # inquiries displayed. The length of 'list_distribution' is 1 greater - # than this, since the language model distribution is added before - # the first inquiry is displayed. + def decide(self, series: Dict[str, Any]) -> bool: + """Check if minimum number of iterations has been reached. + + Note: Uses 'list_sti' parameter since this is the number of inquiries + displayed. The length of 'list_distribution' is 1 greater than this, + since the language model distribution is added before the first + inquiry is displayed. + + Args: + series: Dictionary containing series data. + + Returns: + bool: True if current iterations < minimum required, False otherwise. + """ current_inq = len(series['list_sti']) log.info( f"Checking min iterations; current iteration is {current_inq}") @@ -57,51 +97,99 @@ def decide(self, series: Dict): class DecreasedProbabilityCriteria(DecisionCriteria): - """Returns true if the letter with the max probability decreased from the - last inquiry.""" + """Criteria for detecting decreased probability of the most likely symbol. + + Returns true if the letter with the max probability decreased from the + last inquiry. + + Attributes: + None + """ + + def decide(self, series: Dict[str, Any]) -> bool: + """Check if probability of most likely symbol has decreased. + + Args: + series: Dictionary containing series data. - def decide(self, series: Dict): + Returns: + bool: True if probability decreased for same symbol, False otherwise. + """ if len(series['list_distribution']) < 2: return False prev_dist = series['list_distribution'][-2] cur_dist = series['list_distribution'][-1] - return np.argmax(cur_dist) == np.argmax( - prev_dist) and np.max(cur_dist) < np.max(prev_dist) + return np.argmax(cur_dist) == np.argmax(prev_dist) and np.max(cur_dist) < np.max(prev_dist) class MaxIterationsCriteria(DecisionCriteria): - """Returns true if the max iterations have been reached.""" + """Criteria for enforcing maximum number of iterations. + + Returns true if the maximum allowed iterations have been reached. - def __init__(self, max_num_inq: int): - """ Args: - max_num_inq(int): maximum number of inquiries allowed before - mandatory termination """ + Attributes: + max_num_inq: Maximum number of inquiries allowed. + """ + + def __init__(self, max_num_inq: int) -> None: + """Initialize the maximum iterations criteria. + + Args: + max_num_inq: Maximum number of inquiries allowed before + mandatory termination. + """ self.max_num_inq = max_num_inq - def decide(self, series: Dict): - # Note: len(series['list_sti']) != len(series['list_distribution']) - # see MinIterationsCriteria comment + def decide(self, series: Dict[str, Any]) -> bool: + """Check if maximum iterations have been reached. + + Note: len(series['list_sti']) != len(series['list_distribution']) + See MinIterationsCriteria comment. + + Args: + series: Dictionary containing series data. + + Returns: + bool: True if max iterations reached, False otherwise. + """ current_inq = len(series['list_sti']) if current_inq >= self.max_num_inq: - log.info( - "Committing to decision: max iterations have been reached.") + log.info("Committing to decision: max iterations have been reached.") return True return False class ProbThresholdCriteria(DecisionCriteria): - """Returns true if the commit threshold has been met.""" - - def __init__(self, threshold: float): - """ Args: - threshold(float in [0,1]): A threshold on most likely - candidate posterior. If a candidate exceeds a posterior - the system terminates. - """ + """Criteria for probability threshold-based decisions. + + Returns true if the commit threshold has been met. + + Attributes: + tau: Probability threshold value. + """ + + def __init__(self, threshold: float) -> None: + """Initialize the probability threshold criteria. + + Args: + threshold: A threshold value in [0,1]. If a candidate exceeds this + posterior probability, the system terminates. + + Raises: + AssertionError: If threshold is not in [0,1]. + """ assert 1 >= threshold >= 0, "stopping threshold should be in [0,1]" self.tau = threshold - def decide(self, series: Dict): + def decide(self, series: Dict[str, Any]) -> bool: + """Check if probability threshold has been exceeded. + + Args: + series: Dictionary containing series data. + + Returns: + bool: True if threshold exceeded, False otherwise. + """ current_distribution = series['list_distribution'][-1] if np.max(current_distribution) > self.tau: log.info("Committing to decision: posterior exceeded threshold.") @@ -110,52 +198,79 @@ def decide(self, series: Dict): class MarginCriteria(DecisionCriteria): - """ Stopping criteria based on the difference of two most likely candidates. - This condition enforces the likelihood difference between two top - candidates to be at least a value. E.g. in 4 category case with - a margin 0.2, the edge cases [0.6,0.4,0.,0.] and [0.4,0.2,0.2,0.2] - satisfy the condition. + """Criteria based on margin between top two candidates. + + This condition enforces the likelihood difference between two top + candidates to be at least a specified value. E.g. in 4 category case with + a margin 0.2, the edge cases [0.6,0.4,0.,0.] and [0.4,0.2,0.2,0.2] + satisfy the condition. + + Attributes: + margin: Required margin between top candidates. """ - def __init__(self, margin: float): - """ Args: - margin(float in [0,1]): Minimum distance required between - two most likely competing candidates to trigger termination. - """ + def __init__(self, margin: float) -> None: + """Initialize the margin criteria. + + Args: + margin: Minimum distance required between two most likely competing + candidates to trigger termination. + + Raises: + AssertionError: If margin is not in [0,1]. + """ assert 1 >= margin >= 0, "difference margin should be in [0,1]" self.margin = margin - def decide(self, series: Dict): - # Get the current posterior probability values + def decide(self, series: Dict[str, Any]) -> bool: + """Check if margin between top candidates is sufficient. + + Args: + series: Dictionary containing series data. + + Returns: + bool: True if margin is sufficient, False otherwise. + """ p = copy(series['list_distribution'][-1]) - # This criteria compares most likely candidates (best competitors) candidates = [p[idx] for idx in list(np.argsort(p)[-2:])] stopping_rule = np.abs(candidates[0] - candidates[1]) d = stopping_rule > self.margin if d: log.info("Committing to decision: margin is high enough.") - return d class MomentumCommitCriteria(DecisionCriteria): - """ Stopping criteria based on Shannon entropy on the simplex - Attr: - lam(float): linear combination parameter between entropy and the - speed term - tau(float): decision threshold - """ - - def __init__(self, tau: float, lam: float): + """Criteria based on Shannon entropy and momentum. + + This stopping criteria combines Shannon entropy on the simplex with + a momentum term. + + Attributes: + lam: Linear combination parameter between entropy and speed term. + tau: Decision threshold. + """ + + def __init__(self, tau: float, lam: float) -> None: + """Initialize the momentum commit criteria. + + Args: + tau: Decision threshold value. + lam: Linear combination parameter. + """ self.lam = lam self.tau = tau - def reset(self): - pass + def decide(self, series: Dict[str, Any]) -> bool: + """Evaluate momentum-based stopping criteria. - def decide(self, series): - eps = np.power(.1, 6) + Args: + series: Dictionary containing series data. + Returns: + bool: True if stopping criteria met, False otherwise. + """ + eps = np.power(.1, 6) prob_history = copy(series['list_distribution']) p = prob_history[-1] @@ -174,60 +289,77 @@ def decide(self, series): else: stopping_rule = tmp - d = stopping_rule < tau_ + return stopping_rule < tau_ - return d +class CriteriaEvaluator: + """Evaluates decision criteria for BCI task control. -class CriteriaEvaluator(): - """Evaluates whether an series should commit to a decision based on the - provided criteria. + This class manages multiple decision criteria to determine when to commit + to a decision based on the accumulated evidence. - Parameters: - ----------- - continue_criteria: list of criteria; if any of these evaluate to true the - decision maker continues. - commit_criteria: list of criteria; if any of these return true and - continue_criteria are all false, decision maker commits to a decision. + Attributes: + continue_criteria: List of criteria that must all be false to allow + commitment. + commit_criteria: List of criteria where any true value triggers + commitment. """ - def __init__(self, continue_criteria: List[DecisionCriteria], - commit_criteria: List[DecisionCriteria]): + def __init__(self, + continue_criteria: Optional[List[DecisionCriteria]] = None, + commit_criteria: Optional[List[DecisionCriteria]] = None) -> None: + """Initialize the criteria evaluator. + + Args: + continue_criteria: List of criteria that must all be false to allow + commitment. + commit_criteria: List of criteria where any true value triggers + commitment. + """ self.continue_criteria = continue_criteria or [] self.commit_criteria = commit_criteria or [] @classmethod - def default(cls, min_num_inq: int, max_num_inq: int, threshold: float): - return cls(continue_criteria=[MinIterationsCriteria(min_num_inq)], - commit_criteria=[ - MaxIterationsCriteria(max_num_inq), - ProbThresholdCriteria(threshold) - ]) - - def do_series(self): + def default(cls, min_num_inq: int, max_num_inq: int, + threshold: float) -> 'CriteriaEvaluator': + """Create a default CriteriaEvaluator instance. + + Args: + min_num_inq: Minimum number of inquiries required. + max_num_inq: Maximum number of inquiries allowed. + threshold: Probability threshold for commitment. + + Returns: + CriteriaEvaluator: Configured with default criteria. + """ + return cls( + continue_criteria=[MinIterationsCriteria(min_num_inq)], + commit_criteria=[ + MaxIterationsCriteria(max_num_inq), + ProbThresholdCriteria(threshold) + ]) + + def do_series(self) -> None: + """Reset all criteria for a new series.""" for el_ in self.continue_criteria: el_.reset() for el in self.commit_criteria: el.reset() - def should_commit(self, series: Dict): - """Evaluates the given series; returns true if stoppage criteria has - been met, otherwise false. - - Parameters: - ----------- - series - series data - - target(str): target of the series - - time_spent(ndarray[float]): |num_trials|x1 - time spent on the inquiry - - list_sti(list[list[str]]): presented symbols in each - inquiry - - list_distribution(list[ndarray[float]]): list of |alp|x1 - arrays with prob. dist. over alp - """ - if any( - criteria.decide(series) - for criteria in self.continue_criteria): + def should_commit(self, series: Dict[str, Any]) -> bool: + """Evaluate whether to commit to a decision. + + Args: + series: Dictionary containing series data with: + target (str): Target of the series. + time_spent (np.ndarray): Time spent on each inquiry. + list_sti (List[List[str]]): Presented symbols in each inquiry. + list_distribution (List[np.ndarray]): Probability distributions + over the alphabet for each inquiry. + + Returns: + bool: True if commitment criteria met, False otherwise. + """ + if any(criteria.decide(series) for criteria in self.continue_criteria): return False - return any( - criteria.decide(series) for criteria in self.commit_criteria) + return any(criteria.decide(series) for criteria in self.commit_criteria) diff --git a/bcipy/task/control/evidence.py b/bcipy/task/control/evidence.py index bb8a828eb..83c6b68c6 100644 --- a/bcipy/task/control/evidence.py +++ b/bcipy/task/control/evidence.py @@ -1,15 +1,24 @@ +"""Evidence evaluation module for BCI task control. + +This module provides classes and functions for extracting evidence from raw device data, +including EEG, gaze tracking, and switch input data. The module supports different types +of evidence evaluation based on the input data type and desired output evidence type. +""" + # mypy: disable-error-code="override" -"""Classes and functions for extracting evidence from raw device data.""" import logging -from typing import List, Optional, Type +from typing import Any, List, Optional, Type import numpy as np from bcipy.acquisition.multimodal import ContentType from bcipy.config import SESSION_LOG_FILENAME +from bcipy.core.parameters import Parameters +from bcipy.core.stimuli import GazeReshaper, TrialReshaper +from bcipy.display.main import ButtonPressMode from bcipy.helpers.acquisition import analysis_channels -from bcipy.helpers.stimuli import TrialReshaper from bcipy.signal.model import SignalModel +from bcipy.signal.process import extract_eye_info from bcipy.task.data import EvidenceType from bcipy.task.exceptions import MissingEvidenceEvaluator @@ -17,17 +26,33 @@ class EvidenceEvaluator: - """Base class for a class that can evaluate raw device data using a - signal_model. EvidenceEvaluators are responsible for performing necessary - preprocessing steps such as filtering and reshaping. + """Base class for evaluating raw device data using a signal model. - Parameters - ---------- - symbol_set: set of possible symbols presented - signal_model: model trained using a calibration session of the same user. + This class defines the interface for evidence evaluators, which are responsible + for performing necessary preprocessing steps such as filtering and reshaping + before evaluating the evidence. + + Attributes: + symbol_set: List of possible symbols that can be presented. + signal_model: Model trained using calibration session data. + device_spec: Specification of the input device. """ - def __init__(self, symbol_set: List[str], signal_model: SignalModel): + def __init__( + self, + symbol_set: List[str], + signal_model: SignalModel, + parameters: Optional[Parameters] = None) -> None: + """Initialize the evidence evaluator. + + Args: + symbol_set: List of possible symbols that can be presented. + signal_model: Model trained using calibration session data. + parameters: Optional configuration parameters. + + Raises: + AssertionError: If signal model metadata is missing or incompatible. + """ assert signal_model.metadata, "Metadata missing from signal model." device_spec = signal_model.metadata.device_spec assert ContentType( @@ -39,125 +64,320 @@ def __init__(self, symbol_set: List[str], signal_model: SignalModel): @property def consumes(self) -> ContentType: - """ContentType of the data that should be input""" + """Get the type of data this evaluator consumes. + + Returns: + ContentType: Type of input data required. + """ + raise NotImplementedError() @property def produces(self) -> EvidenceType: - """Type of evidence that is output""" + """Get the type of evidence this evaluator produces. - def evaluate(self, **kwargs): - """Evaluate the evidence""" + Returns: + EvidenceType: Type of evidence output. + """ + raise NotImplementedError() + + def evaluate(self, **kwargs: Any) -> np.ndarray: + """Evaluate the evidence from raw data. + + Args: + **kwargs: Arbitrary keyword arguments for evaluation. + + Returns: + np.ndarray: Evaluated evidence data. + """ + raise NotImplementedError() class EEGEvaluator(EvidenceEvaluator): - """EvidenceEvaluator that extracts symbol likelihoods from raw EEG data. + """Evidence evaluator for extracting symbol likelihoods from EEG data. - Parameters - ---------- - symbol_set: set of possible symbols presented - signal_model: trained signal model + This evaluator processes raw EEG data to compute likelihood ratios for + different symbols based on the ERP response. + + Attributes: + consumes: Type of input data (EEG). + produces: Type of evidence output (ERP). + channel_map: Mapping of EEG channels. + transform: Signal transformation function. + reshape: Trial reshaping function. """ + consumes = ContentType.EEG produces = EvidenceType.ERP - def __init__(self, symbol_set: List[str], signal_model: SignalModel): - super().__init__(symbol_set, signal_model) + def __init__( + self, + symbol_set: List[str], + signal_model: SignalModel, + parameters: Optional[Parameters] = None) -> None: + """Initialize the EEG evaluator. + + Args: + symbol_set: List of possible symbols that can be presented. + signal_model: Model trained using calibration session data. + parameters: Optional configuration parameters. + """ + super().__init__(symbol_set, signal_model, parameters) self.channel_map = analysis_channels(self.device_spec.channels, self.device_spec) self.transform = signal_model.metadata.transform self.reshape = TrialReshaper() - def preprocess(self, raw_data: np.ndarray, times: List[float], - target_info: List[str], window_length: float) -> np.ndarray: - """Preprocess the inquiry data. - - Parameters - ---------- - raw_data - C x L eeg data where C is number of channels and L is the - signal length - symbols - symbols displayed in the inquiry - times - timestamps associated with each symbol - target_info - target information about the stimuli; - ex. ['nontarget', 'nontarget', ...] - window_length - The length of the time between stimuli presentation + def preprocess( + self, + raw_data: np.ndarray, + times: List[float], + target_info: List[str], + window_length: float) -> np.ndarray: + """Preprocess the inquiry EEG data. + + Args: + raw_data: C x L EEG data where C is number of channels and L is + signal length. + times: Timestamps associated with each symbol. + target_info: Target information about the stimuli + (e.g. ['nontarget', 'nontarget', ...]). + window_length: Length of time between stimuli presentation. + + Returns: + np.ndarray: Preprocessed EEG data. """ transformed_data, transform_sample_rate = self.transform( raw_data, self.device_spec.sample_rate) # The data from DAQ is assumed to have offsets applied - reshaped_data, _lbls = self.reshape(trial_targetness_label=target_info, - timing_info=times, - eeg_data=transformed_data, - sample_rate=transform_sample_rate, - channel_map=self.channel_map, - poststimulus_length=window_length) + reshaped_data, _lbls = self.reshape( + trial_targetness_label=target_info, + timing_info=times, + eeg_data=transformed_data, + sample_rate=transform_sample_rate, + channel_map=self.channel_map, + poststimulus_length=window_length) return reshaped_data - # pylint: disable=arguments-differ - def evaluate(self, raw_data: np.ndarray, symbols: List[str], - times: List[float], target_info: List[str], - window_length: float) -> np.ndarray: - """Evaluate the evidence. - - Parameters - ---------- - raw_data - C x L eeg data where C is number of channels and L is the - signal length - symbols - symbols displayed in the inquiry - times - timestamps associated with each symbol - target_info - target information about the stimuli; - ex. ['nontarget', 'nontarget', ...] - window_length - The length of the time between stimuli presentation + def evaluate( + self, + raw_data: np.ndarray, + symbols: List[str], + times: List[float], + target_info: List[str], + window_length: float, + *args: Any) -> np.ndarray: + """Evaluate EEG evidence. + + Args: + raw_data: C x L EEG data where C is number of channels and L is + signal length. + symbols: Symbols displayed in the inquiry. + times: Timestamps associated with each symbol. + target_info: Target information about the stimuli + (e.g. ['nontarget', 'nontarget', ...]). + window_length: Length of time between stimuli presentation. + *args: Additional arguments. + + Returns: + np.ndarray: Likelihood ratios for each symbol. """ data = self.preprocess(raw_data, times, target_info, window_length) - return self.signal_model.compute_likelihood_ratio(data, symbols, self.symbol_set) + return self.signal_model.compute_likelihood_ratio( + data, symbols, self.symbol_set) class GazeEvaluator(EvidenceEvaluator): - """EvidenceEvaluator that extracts symbol likelihoods from raw gaze data. + """Evidence evaluator for extracting symbol likelihoods from gaze data. - Parameters - ---------- - symbol_set: set of possible symbols presented - gaze_model: trained gaze model + This evaluator processes raw eye tracking data to compute likelihoods + for different symbols based on gaze patterns. + + Attributes: + consumes: Type of input data (EYETRACKER). + produces: Type of evidence output (EYE). + channel_map: Mapping of eye tracking channels. + transform: Signal transformation function. + reshape: Gaze data reshaping function. """ + consumes = ContentType.EYETRACKER produces = EvidenceType.EYE - def __init__(self, symbol_set: List[str], signal_model: SignalModel): - super().__init__(symbol_set, signal_model) + def __init__( + self, + symbol_set: List[str], + signal_model: SignalModel, + parameters: Optional[Parameters] = None) -> None: + """Initialize the gaze evaluator. + + Args: + symbol_set: List of possible symbols that can be presented. + signal_model: Model trained using calibration session data. + parameters: Optional configuration parameters. + """ + super().__init__(symbol_set, signal_model, parameters) self.channel_map = analysis_channels(self.device_spec.channels, self.device_spec) self.transform = signal_model.metadata.transform - self.reshape = TrialReshaper() + self.reshape = GazeReshaper() + + def preprocess( + self, + raw_data: np.ndarray, + times: List[float], + flash_time: float) -> np.ndarray: + """Preprocess the inquiry gaze data. + + The preprocessing is functionally different than Gaze Reshaper, since + the raw data contains only one inquiry. start_idx is determined as the + start time of first symbol flashing multiplied by the sampling rate + of eye tracker. stop_idx is the index indicating the end of last + symbol flashing. + + Args: + raw_data: C x L data where C is number of channels and L is signal + length. Includes all channels in devices.json. + times: Timestamps associated with each symbol. + flash_time: Duration (in seconds) of each stimulus. + + Returns: + np.ndarray: Preprocessed gaze data (4, N_samples). + """ + if self.transform: + transformed_data, transform_sample_rate = self.transform( + raw_data, self.device_spec.sample_rate) + else: + transformed_data = raw_data + transform_sample_rate = self.device_spec.sample_rate + + start_idx = int(self.device_spec.sample_rate * times[0]) + stop_idx = start_idx + int( + (times[-1] - times[0] + flash_time) * self.device_spec.sample_rate) + data_all_channels = transformed_data[:, start_idx:stop_idx] + + # Extract left and right eye from all channels. Remove/replace nan values + left_eye, right_eye, _, _, _, _ = extract_eye_info(data_all_channels) + reshaped_data = np.vstack( + (np.array(left_eye).T, np.array(right_eye).T)) - def preprocess(self, raw_data: np.ndarray, times: List[float], - target_info: List[str], window_length: float) -> np.ndarray: - """Preprocess the inquiry data. + return reshaped_data - Parameters - ---------- - raw_data - C x L eeg data where C is number of channels and L is the - signal length - symbols - symbols displayed in the inquiry - times - timestamps associated with each symbol - target_info - target information about the stimuli; - ex. ['nontarget', 'nontarget', ...] - window_length - The length of the time between stimuli presentation + def evaluate( + self, + raw_data: np.ndarray, + symbols: List[str], + times: List[float], + target_info: List[str], + window_length: float, + flash_time: float, + stim_length: float) -> np.ndarray: + """Evaluate gaze evidence. + + Args: + raw_data: C x L data where C is number of channels and L is signal + length. + symbols: Symbols displayed in the inquiry. + times: Timestamps associated with each symbol. + target_info: Target information about the stimuli. + window_length: Length of time between stimuli presentation. + flash_time: Duration of each stimulus. + stim_length: Length of stimulus sequence. + + Returns: + np.ndarray: Likelihood values for each symbol. """ - transformed_data, transform_sample_rate = self.transform( - raw_data, self.device_spec.sample_rate) + data = self.preprocess(raw_data, times, flash_time) + # We need the likelihoods in the form of p(label | gaze). + # predict returns the argmax of the likelihoods. + # Therefore we need predict_proba method to get the likelihoods. + likelihood = self.signal_model.evaluate_likelihood( + data, symbols, self.symbol_set) + return likelihood - # The data from DAQ is assumed to have offsets applied - reshaped_data, _lbls = self.reshape(trial_targetness_label=target_info, - timing_info=times, - eeg_data=transformed_data, - sample_rate=transform_sample_rate, - channel_map=self.channel_map, - poststimulus_length=window_length) - return reshaped_data + +class SwitchEvaluator(EvidenceEvaluator): + """Evidence evaluator for extracting symbol likelihoods from switch data. + + This evaluator processes raw switch input data to compute likelihoods + for different symbols based on button press patterns. + + Attributes: + consumes: Type of input data (MARKERS). + produces: Type of evidence output (BTN). + button_press_mode: Mode of button press interpretation. + trial_count: Number of trials in stimulus sequence. + """ + + consumes = ContentType.MARKERS + produces = EvidenceType.BTN + + def __init__( + self, + symbol_set: List[str], + signal_model: SignalModel, + parameters: Optional[Parameters] = None) -> None: + """Initialize the switch evaluator. + + Args: + symbol_set: List of possible symbols that can be presented. + signal_model: Model trained using calibration session data. + parameters: Optional configuration parameters. + + Raises: + AssertionError: If button press mode is not supported. + """ + super().__init__(symbol_set, signal_model, parameters) + if not parameters: + raise ValueError("Parameters required for SwitchEvaluator") + + self.button_press_mode = ButtonPressMode( + parameters.get('preview_inquiry_progress_method')) + self.trial_count = parameters.get('stim_length') + + if self.button_press_mode == ButtonPressMode.NOTHING: + raise AssertionError(( + "Button press mode not supported.", + "To run without button press evidence set the acq_mode to exclude MARKERS." + )) + + def preprocess( + self, + raw_data: np.ndarray, + times: List[float], + target_info: List[str], + window_length: float) -> np.ndarray: + """Preprocess the inquiry switch data. + + Determines the return data based on whether the switch was pressed + during the inquiry and the configured ButtonPressMode. + + Args: + raw_data: Switch input data. + times: Timestamps associated with each symbol. + target_info: Target information about the stimuli. + window_length: Length of time between stimuli presentation. + + Returns: + np.ndarray: Preprocessed switch data. + """ + switch_was_pressed = np.any(raw_data) + + # shape: (channels/1, trials/trial_count, samples/1) + data_shape = (1, self.trial_count, 1) + ones = np.ones(data_shape) + zeros = np.zeros(data_shape) + + # Inquiries with 1.0s will be upgraded/supported by the model probabilities. + rules = { + ButtonPressMode.ACCEPT: + lambda: ones if switch_was_pressed else zeros, + ButtonPressMode.REJECT: + lambda: ones if not switch_was_pressed else zeros + } + return rules[self.button_press_mode]() # pylint: disable=arguments-differ def evaluate(self, raw_data: np.ndarray, symbols: List[str], @@ -176,9 +396,9 @@ def evaluate(self, raw_data: np.ndarray, symbols: List[str], window_length - The length of the time between stimuli presentation """ data = self.preprocess(raw_data, times, target_info, window_length) - # We need the likelihoods in the form of p(label | gaze). predict returns the argmax of the likelihoods. - # Therefore we need predict_proba method to get the likelihoods. - return self.signal_model.evaluate_likelihood(data) # multiplication over the inquiry + probs = self.signal_model.compute_likelihood_ratio( + data, symbols, self.symbol_set) + return probs def get_evaluator( @@ -208,8 +428,7 @@ def get_evaluator( def find_matching_evaluator( signal_model: SignalModel) -> Type[EvidenceEvaluator]: - """Find the first EvidenceEvaluator compatible with the given signal - model.""" + """Find the first EvidenceEvaluator compatible with the given signal model.""" content_type = ContentType(signal_model.metadata.device_spec.content_type) # Metadata may provide an EvidenceType with a model so the same data source can # be used to produce multiple types of evidence (ex. alpha) @@ -220,13 +439,13 @@ def find_matching_evaluator( evidence_type = EvidenceType(model_output.upper()) except ValueError: log.error(f"Unsupported evidence type: {model_output}") - return get_evaluator(content_type, evidence_type) -def init_evidence_evaluator(symbol_set: List[str], - signal_model: SignalModel) -> EvidenceEvaluator: - """Find an EvidenceEvaluator that matches the given signal_model and - initialize it.""" +def init_evidence_evaluator( + symbol_set: List[str], + signal_model: SignalModel, + parameters: Optional[Parameters] = None) -> EvidenceEvaluator: + """Find an EvidenceEvaluator that matches the given signal_model and initialize it.""" evaluator_class = find_matching_evaluator(signal_model) - return evaluator_class(symbol_set, signal_model) + return evaluator_class(symbol_set, signal_model, parameters) diff --git a/bcipy/task/control/handler.py b/bcipy/task/control/handler.py index fbda582db..dd87987ab 100644 --- a/bcipy/task/control/handler.py +++ b/bcipy/task/control/handler.py @@ -1,52 +1,75 @@ +"""Task control handler module for BCI tasks. + +This module provides classes for managing decision making and evidence fusion +in BCI tasks. It includes functionality for scheduling inquiries, managing +task state, and making decisions based on accumulated evidence. +""" + import logging import string -from typing import Dict, List, Tuple, Optional +from typing import Dict, List, Optional, Tuple import numpy as np from bcipy.config import SESSION_LOG_FILENAME -from bcipy.helpers.stimuli import InquirySchedule, inq_generator, StimuliOrder -from bcipy.helpers.symbols import SPACE_CHAR, BACKSPACE_CHAR -from bcipy.task.control.query import RandomStimuliAgent, StimuliAgent +from bcipy.core.stimuli import InquirySchedule, StimuliOrder, inq_generator +from bcipy.core.symbols import BACKSPACE_CHAR, SPACE_CHAR from bcipy.task.control.criteria import CriteriaEvaluator +from bcipy.task.control.query import RandomStimuliAgent, StimuliAgent from bcipy.task.data import EvidenceType log = logging.getLogger(SESSION_LOG_FILENAME) -class EvidenceFusion(): - """ Fuses likelihood evidences provided by the inference - Attr: - evidence_history(dict{list[ndarray]}): Dictionary of difference - evidence types in list. Lists are ordered using the arrival - time. - likelihood(ndarray[]): current probability distribution over the - set. Gets updated once new evidence arrives. """ +class EvidenceFusion: + """Class for fusing likelihood evidence from multiple sources. - def __init__(self, list_name_evidence, len_dist): - self.evidence_history = {name: [] for name in list_name_evidence} - self.likelihood = np.ones(len_dist) / len_dist + This class manages the combination of evidence from different sources + (e.g., EEG, eye tracking) to compute a final probability distribution + over possible decisions. - def update_and_fuse(self, dict_evidence): - """ Updates the probability distribution - Args: - dict_evidence(dict{name: ndarray[float]}): dictionary of - evidences (EEG (likelihood ratios) and other likelihoods) + Attributes: + evidence_history: Dictionary mapping evidence types to their history. + likelihood: Current probability distribution over the decision space. + """ + + def __init__(self, list_name_evidence: List[EvidenceType], + len_dist: int) -> None: + """Initialize the evidence fusion system. + + Args: + list_name_evidence: List of evidence types to track. + len_dist: Length of the probability distribution (number of + possible decisions). """ - # {EEG: [], GAZE: ()} + self.evidence_history: Dict[EvidenceType, List[np.ndarray]] = { + name: [] for name in list_name_evidence + } + self.likelihood = np.ones(len_dist) / len_dist - for key in dict_evidence.keys(): + def update_and_fuse(self, + dict_evidence: Dict[EvidenceType, + np.ndarray]) -> np.ndarray: + """Update and fuse probability distributions with new evidence. + + Args: + dict_evidence: Dictionary mapping evidence types to their + likelihood arrays. + + Returns: + np.ndarray: Updated probability distribution after fusion. + """ + for key in dict_evidence: tmp = dict_evidence[key][:][:] self.evidence_history[key].append(tmp) - # Current rule is to multiply + # Current fusion rule is multiplication for value in dict_evidence.values(): self.likelihood *= value[:] if np.isinf(np.sum(self.likelihood)): tmp = np.zeros(len(self.likelihood)) tmp[np.where(self.likelihood == np.inf)[0][0]] = 1 - self.likelihood = tmp if not np.isnan(np.sum(self.likelihood)): @@ -56,24 +79,26 @@ def update_and_fuse(self, dict_evidence): return likelihood - def reset_history(self): - """ Clears evidence history """ + def reset_history(self) -> None: + """Clears evidence history.""" for value in self.evidence_history.values(): del value[:] self.likelihood = np.ones(len(self.likelihood)) / len(self.likelihood) def save_history(self) -> None: - """ Saves the current likelihood history """ + """Save the current likelihood history. + + Note: + Not currently implemented. + """ log.warning('save_history not implemented') - return @property def latest_evidence(self) -> Dict[EvidenceType, List[float]]: - """Latest evidence of each type in the evidence history. + """Get the latest evidence of each type. - Returns - ------- - a dictionary with an entry for all configured evidence types. + Returns: + Dict mapping evidence types to their most recent values. """ return { name: list(evidence[-1]) if evidence else [] @@ -82,57 +107,54 @@ def latest_evidence(self) -> Dict[EvidenceType, List[float]]: class DecisionMaker: - """ Scheduler of the entire framework - Attr: - state(str): state of the framework, which increases in size - by 1 after each inquiry. Elements are alphabet, ".,_,<" - where ".": null_inquiry(no decision made) - "_": space bar - "<": back space - alphabet(list[str]): list of symbols used by the framework. Can - be switched with location of images or one hot encoded images. - is_txt_stim(bool): whether the stimuli are text or images - inq_constants(list[str]): optional list of letters which should appear in - every inquiry. - stopping_evaluator: CriteriaEvaluator - optional parameter to - provide alternative rules for committing to a decision. - stimuli_agent(StimuliAgent): the query selection mechanism of the - system - stimuli_timing(list[float]): list of timings for the stimuli ([fixation_time, stimuli_flash_time]) - stimuli_order(StimuliOrder): ordering of the stimuli (random, distributed) - stimuli_jitter(float): jitter of the inquiry stimuli in seconds - - Functions: - decide(): - Checks the criteria for making and series, using all - evidences and decides to do an series or to collect more - evidence - do_series(): - Once committed an series perform updates to condition the - distribution on the previous letter. - schedule_inquiry(): - schedule the next inquiry using the current information - decide_state_update(): - If committed to an series update the state using a decision - metric. - (e.g. pick the letter with highest likelihood) - prepare_stimuli(): - prepares the query set for the next inquiry - (e.g pick n-highest likely letters and randomly shuffle) + """Scheduler and decision maker for BCI task control. + + This class manages the scheduling of inquiries and decision making based + on accumulated evidence. It maintains the task state and coordinates + the interaction between evidence collection and decision making. + + Attributes: + state: Current state string, growing by 1 after each inquiry. + displayed_state: State formatted for display. + alphabet: List of possible symbols. + is_txt_stim: Whether stimuli are text or images. + stimuli_timing: Timing parameters for stimuli presentation. + stimuli_order: Order of stimuli presentation. + stimuli_jitter: Jitter in stimulus timing. + inq_constants: Symbols to include in every inquiry. + stopping_evaluator: Evaluator for stopping criteria. + stimuli_agent: Agent for selecting stimuli. + list_series: List of series data. + time: Current time. + inquiry_counter: Number of inquiries made. + last_selection: Last selected symbol. + """ + + def __init__( + self, + state: str = '', + alphabet: List[str] = list(string.ascii_uppercase) + [BACKSPACE_CHAR] + + [SPACE_CHAR], + is_txt_stim: bool = True, + stimuli_timing: List[float] = [1, .2], + stimuli_jitter: float = 0, + stimuli_order: StimuliOrder = StimuliOrder.RANDOM, + inq_constants: Optional[List[str]] = None, + stopping_evaluator: Optional[CriteriaEvaluator] = None, + stimuli_agent: Optional[StimuliAgent] = None) -> None: + """Initialize the decision maker. + + Args: + state: Initial state string. + alphabet: List of possible symbols. + is_txt_stim: Whether stimuli are text or images. + stimuli_timing: [fixation_time, stimuli_flash_time]. + stimuli_jitter: Jitter in stimulus timing (seconds). + stimuli_order: Order of stimuli presentation. + inq_constants: Symbols to include in every inquiry. + stopping_evaluator: Evaluator for stopping criteria. + stimuli_agent: Agent for selecting stimuli. """ - - def __init__(self, - state: str = '', - alphabet: List[str] = list(string.ascii_uppercase) + [BACKSPACE_CHAR] + [SPACE_CHAR], - is_txt_stim: bool = True, - stimuli_timing: List[float] = [1, .2], - stimuli_jitter: float = 0, - stimuli_order: StimuliOrder = StimuliOrder.RANDOM, - inq_constants: Optional[List[str]] = None, - stopping_evaluator: CriteriaEvaluator = CriteriaEvaluator.default(min_num_inq=2, - max_num_inq=10, - threshold=0.8), - stimuli_agent: Optional[StimuliAgent] = None): self.state = state self.displayed_state = self.form_display_state(state) self.stimuli_timing = stimuli_timing @@ -142,75 +164,90 @@ def __init__(self, self.alphabet = alphabet self.is_txt_stim = is_txt_stim - self.list_series = [{'target': None, 'time_spent': 0, - 'list_sti': [], 'list_distribution': [], - 'decision': None}] + self.list_series = [{ + 'target': None, + 'time_spent': 0, + 'list_sti': [], + 'list_distribution': [], + 'decision': None + }] self.time = 0 self.inquiry_counter = 0 self.stopping_evaluator = stopping_evaluator - self.stimuli_agent = stimuli_agent or RandomStimuliAgent(alphabet=self.alphabet) + self.stimuli_agent = stimuli_agent or RandomStimuliAgent( + alphabet=self.alphabet) self.last_selection = '' # Items shown in every inquiry self.inq_constants = inq_constants - def reset(self, state=''): - """ Resets the decision maker with the initial state - Args: - state(str): current state of the system """ + def reset(self, state: str = '') -> None: + """Reset the decision maker to initial state. + + Args: + state: New initial state string. + """ self.state = state self.displayed_state = self.form_display_state(self.state) - self.list_series = [{'target': None, 'time_spent': 0, - 'list_sti': [], 'list_distribution': []}] + self.list_series = [{ + 'target': None, + 'time_spent': 0, + 'list_sti': [], + 'list_distribution': [] + }] self.time = 0 self.inquiry_counter = 0 self.stimuli_agent.reset() - def form_display_state(self, state): - """ Forms the state information or the user that fits to the - display. Basically takes '.' and BACKSPACE_CHAR into consideration and rewrites - the state - Args: - state(str): state string - Return: - displayed_state(str): state without '<,.' and removes - backspaced letters """ + def form_display_state(self, state: str) -> str: + """Format state string for display. + + Processes special characters (backspace, dots) and formats the + state appropriately for display. + + Args: + state: Raw state string. + + Returns: + str: Formatted state string for display. + """ tmp = '' for i in state: if i == BACKSPACE_CHAR: tmp = tmp[0:-1] elif i != '.': tmp += i - return tmp - def update(self, state=''): + def update(self, state: str = '') -> None: + """Update the current state. + + Args: + state: New state string. + """ self.state = state self.displayed_state = self.form_display_state(state) - def decide(self, p) -> Tuple[bool, InquirySchedule]: - """ Once evidence is collected, decision_maker makes a decision to - stop or not by leveraging the information of the stopping - criteria. Can decide to do an series or schedule another inquiry. - - Args - ---- - p(ndarray[float]): |A| x 1 distribution array - |A|: cardinality of the alphabet - - Return - ------ - - commitment: True if a letter is a commitment is made - False if requires more evidence - - inquiry schedule: Extra arguments depending on the decision - """ + def decide(self, p: np.ndarray) -> Tuple[bool, Optional[InquirySchedule]]: + """Make a decision based on current evidence. + + Evaluates whether to commit to a decision or schedule another + inquiry based on the current probability distribution and + stopping criteria. + Args: + p: Probability distribution over possible decisions. + + Returns: + Tuple containing: + - bool: True if committing to a decision. + - Optional[InquirySchedule]: Schedule for next inquiry if needed. + """ self.list_series[-1]['list_distribution'].append(p[:]) - # Check stopping criteria if self.stopping_evaluator.should_commit(self.list_series[-1]): self.do_series() return True, None @@ -218,34 +255,46 @@ def decide(self, p) -> Tuple[bool, InquirySchedule]: stimuli = self.schedule_inquiry() return False, stimuli - def do_series(self): - """ series refers to a commitment to a decision. - If made, state is updated, displayed state is updated - a new series is appended. """ + def do_series(self) -> None: + """Handle commitment to a decision. + + Updates state and prepares for the next series when a decision + is made. + """ self.inquiry_counter = 0 decision = self.decide_state_update() self.last_selection = decision self.state += decision self.displayed_state = self.form_display_state(self.state) - # Initialize next series - self.list_series.append({'target': None, 'time_spent': 0, - 'list_sti': [], 'list_distribution': []}) + self.list_series.append({ + 'target': None, + 'time_spent': 0, + 'list_sti': [], + 'list_distribution': [] + }) self.stimuli_agent.do_series() self.stopping_evaluator.do_series() def schedule_inquiry(self) -> InquirySchedule: - """ Schedules next inquiry """ + """Schedule the next inquiry. + + Returns: + InquirySchedule: Schedule for the next inquiry. + """ self.state += '.' stimuli = self.prepare_stimuli() self.list_series[-1]['list_sti'].append(stimuli[0]) self.inquiry_counter += 1 - return stimuli - def decide_state_update(self): - """ Checks stopping criteria to commit to an series """ + def decide_state_update(self) -> str: + """Determine the next state update. + + Returns: + str: Selected symbol for state update. + """ idx = np.where( self.list_series[-1]['list_distribution'][-1] == np.max(self.list_series[-1]['list_distribution'][-1]))[0][0] @@ -254,13 +303,10 @@ def decide_state_update(self): return decision def prepare_stimuli(self) -> InquirySchedule: - """ Given the alphabet, under a rule, prepares a stimuli for - the next inquiry. + """Prepare stimuli for the next inquiry. - Return - ------ - stimuli(tuple[list[str],list[float],list[str]]): tuple of - stimuli information. [0]: letter, [1]: timing, [2]: color + Returns: + InquirySchedule: Schedule containing stimuli and timing information. """ # querying agent decides on possible letters to be shown on the screen diff --git a/bcipy/task/control/query.py b/bcipy/task/control/query.py index 617d029b6..af7d478be 100644 --- a/bcipy/task/control/query.py +++ b/bcipy/task/control/query.py @@ -1,55 +1,96 @@ +"""Query module for BCI task control. + +This module provides classes for managing stimulus presentation in BCI tasks. +It includes agents that determine which stimuli to present based on different +selection strategies, such as random selection or N-best selection based on +probability distributions. +""" + import random from abc import ABC, abstractmethod -from typing import List, Optional +from typing import Any, List, Optional import numpy as np -from bcipy.helpers.stimuli import best_selection +from bcipy.core.stimuli import best_selection class StimuliAgent(ABC): + """Abstract base class for stimulus selection agents. + + This class defines the interface for agents that select stimuli to present + during BCI tasks. Subclasses implement different selection strategies. + """ + @abstractmethod - def reset(self): + def reset(self) -> None: + """Reset the agent's state.""" ... @abstractmethod - def return_stimuli(self, list_distribution: np.ndarray, **kwargs): - """ updates the agent with most likely posterior and selects queries - Args: - list_distribution(list[ndarray]): posterior distributions as - stored in the decision maker - Return: - query(list[str]): queries """ + def return_stimuli(self, list_distribution: np.ndarray, + **kwargs: Any) -> List[str]: + """Update agent with posterior probabilities and select queries. + + Args: + list_distribution: List of posterior probability distributions. + **kwargs: Additional keyword arguments. + + Returns: + List[str]: Selected stimuli for the next query. + """ ... @abstractmethod - def do_series(self): - """ If the system decides on a class let the agent know about it """ + def do_series(self) -> None: + """Handle series completion. + + Called when the system decides on a class to let the agent update + its state accordingly. + """ ... class RandomStimuliAgent(StimuliAgent): - """ An inherited class of StimuliAgent. Chooses random set of letters for - queries instead of most likely letters. - Attr: - alphabet(list[str]): Query space(possible queries). - len_query(int): number of elements in a query - Functions: - reset(): reset the agent - return_stimuli(): update the agent and return a stimuli set - do_series(): one a commitment is made update agent - """ - - def __init__(self, alphabet: List[str], len_query: int = 4): + """Stimuli agent that randomly selects queries. + + This agent chooses random sets of letters for queries instead of using + probability-based selection. + + Attributes: + alphabet: List of possible symbols to query from. + len_query: Number of symbols to include in each query. + """ + + def __init__(self, alphabet: List[str], len_query: int = 4) -> None: + """Initialize the random stimuli agent. + + Args: + alphabet: List of possible symbols to query from. + len_query: Number of symbols to include in each query. + """ self.alphabet = alphabet self.len_query = len_query - def reset(self): - """ This querying method is memoryless no reset needed """ + def reset(self) -> None: + """Reset the agent's state. + + This querying method is memoryless, so no reset is needed. + """ pass - def return_stimuli(self, list_distribution: np.ndarray, constants: Optional[List[str]] = None): - """ return random elements from the alphabet """ + def return_stimuli(self, + list_distribution: np.ndarray, + constants: Optional[List[str]] = None) -> List[str]: + """Return random elements from the alphabet. + + Args: + list_distribution: List of probability distributions (unused). + constants: Optional list of symbols to always include in the result. + + Returns: + List[str]: Randomly selected symbols, with constants if provided. + """ tmp = [i for i in self.alphabet] query = random.sample(tmp, self.len_query) @@ -58,41 +99,58 @@ def return_stimuli(self, list_distribution: np.ndarray, constants: Optional[List return query - def do_series(self): + def do_series(self) -> None: + """Handle series completion. + + This agent is stateless, so no action is needed. + """ pass class NBestStimuliAgent(StimuliAgent): - """ An inherited class of StimuliAgent. Updates the agent with N most likely - letters based on posteriors and selects queries. - Attr: - alphabet(list[str]): Query space(possible queries). - len_query(int): number of elements in a query - Functions: - reset(): reset the agent - return_stimuli(): update the agent and return a stimuli set - do_series(): one a commitment is made update agent - """ - - def __init__(self, alphabet: List[str], len_query: int = 4): + """Stimuli agent that selects the N most likely symbols. + + This agent updates its selection based on posterior probabilities, + choosing the N symbols with highest probability for each query. + + Attributes: + alphabet: List of possible symbols to query from. + len_query: Number of symbols to include in each query. + """ + + def __init__(self, alphabet: List[str], len_query: int = 4) -> None: + """Initialize the N-best stimuli agent. + + Args: + alphabet: List of possible symbols to query from. + len_query: Number of symbols to include in each query. + """ self.alphabet = alphabet self.len_query = len_query - def reset(self): + def reset(self) -> None: + """Reset the agent's state. + + This agent is stateless, so no reset is needed. + """ pass def return_stimuli(self, list_distribution: np.ndarray, constants: Optional[List[str]] = None) -> List[str]: - """Returns a list of the n most likely symbols based on the provided - probabilities, where n is self.len_query. Symbols of the same - probability will be ordered randomly. - - Parameters - ---------- - list_distribution - list of lists of probabilities. Only the last list will - be used. - constants - optional list of symbols which should appear every result + """Return the N most likely symbols based on probabilities. + + Selects symbols based on their probabilities in the distribution, + where N is self.len_query. Symbols with equal probabilities are + ordered randomly. + + Args: + list_distribution: List of probability distributions. Only the + last distribution is used. + constants: Optional list of symbols to always include in the result. + + Returns: + List[str]: Selected symbols, with constants if provided. """ symbol_probs = list(zip(self.alphabet, list_distribution[-1])) randomized = random.sample(symbol_probs, len(symbol_probs)) @@ -102,5 +160,9 @@ def return_stimuli(self, len_query=self.len_query, always_included=constants) - def do_series(self): + def do_series(self) -> None: + """Handle series completion. + + This agent is stateless, so no action is needed. + """ pass diff --git a/bcipy/task/data.py b/bcipy/task/data.py index 51a1df069..aed8a44e7 100644 --- a/bcipy/task/data.py +++ b/bcipy/task/data.py @@ -1,4 +1,8 @@ -"""Module for functionality related to session-related data.""" +"""Module for functionality related to session-related data. + +This module provides classes and functions for managing BCI session data, +including evidence types, inquiries, and session management. +""" from collections import Counter from enum import Enum from typing import Any, Dict, List, Optional, Tuple @@ -9,15 +13,25 @@ def rounded(values: List[float], precision: int) -> List[float]: """Round the list of values to the given precision. - Parameters - ---------- - values - values to round + Args: + values: Values to round. + precision: Number of decimal places to round to. + + Returns: + List[float]: Rounded values. """ return [round(value, precision) for value in values] class EvidenceType(Enum): - """Enum of the supported evidence types used in the various spelling tasks.""" + """Enum of the supported evidence types used in the various spelling tasks. + + Attributes: + LM: Language Model evidence. + ERP: Event-Related Potential using EEG signals. + BTN: Button press evidence. + EYE: Eye tracker evidence. + """ LM = 'LM' # Language Model ERP = 'ERP' # Event-Related Potential using EEG signals BTN = 'BTN' # Button @@ -25,16 +39,22 @@ class EvidenceType(Enum): @classmethod def list(cls) -> List[str]: - """List of evidence types""" + """List of evidence types. + + Returns: + List[str]: List of evidence type names. + """ return [ev_type.name for ev_type in cls] @classmethod def deserialized(cls, serialized_name: str) -> 'EvidenceType': """Deserialized name of the given evidence type. - Parameters: - evidence_name - ex. 'lm_evidence' + + Args: + serialized_name: Evidence name (ex. 'lm_evidence'). + Returns: - deserialized value: ex. EvidenceType.LM + EvidenceType: Deserialized value (ex. EvidenceType.LM). """ if serialized_name == 'eeg_evidence': return EvidenceType.ERP @@ -45,7 +65,11 @@ def __str__(self) -> str: @property def serialized(self) -> str: - """Name used when serialized to a json file.""" + """Name used when serialized to a json file. + + Returns: + str: Serialized name of the evidence type. + """ if self == EvidenceType.ERP: return 'eeg_evidence' return f'{self.name.lower()}{EVIDENCE_SUFFIX}' @@ -54,19 +78,18 @@ def serialized(self) -> str: class Inquiry: """Represents a sequence of stimuli. - Parameters: - ---------- - stimuli - list of stimuli presented (letters, icons, etc) - timing - duration in seconds for each stimulus - target_info - targetness ('nontarget', 'target', etc) for each stimulus - target_letter - current letter that the user is attempting to spell - current_text - letters spelled so far - target_text - word or words the user is attempting to spell - next_display_state - text to be displayed after evaluating the current evidence - lm_evidence - language model evidence for each stimulus - eeg_evidence - eeg evidence for each stimulus - likelihood - combined likelihood for each stimulus - task_data - task-specific information about the inquiry that may be useful in training a model + Args: + stimuli: List of stimuli presented (letters, icons, etc). + timing: Duration in seconds for each stimulus. + triggers: List of (trigger_name, timestamp) tuples. + target_info: Targetness ('nontarget', 'target', etc) for each stimulus. + target_letter: Current letter that the user is attempting to spell. + current_text: Letters spelled so far. + target_text: Word or words the user is attempting to spell. + selection: Currently selected symbol. + next_display_state: Text to be displayed after evaluating evidence. + likelihood: Combined likelihood for each stimulus. + task_data: Task-specific information about the inquiry. """ def __init__(self, @@ -80,7 +103,7 @@ def __init__(self, selection: Optional[str] = None, next_display_state: Optional[str] = None, likelihood: Optional[List[float]] = None, - task_data: Optional[Dict] = None) -> None: + task_data: Optional[Dict[str, Any]] = None) -> None: super().__init__() self.stimuli = stimuli self.timing = timing @@ -100,37 +123,53 @@ def __init__(self, @property def lm_evidence(self) -> List[float]: - """Language model evidence""" + """Language model evidence. + + Returns: + List[float]: Language model evidence values. + """ return self.evidences.get(EvidenceType.LM, []) @property def eeg_evidence(self) -> List[float]: - """EEG evidence""" + """EEG evidence. + + Returns: + List[float]: EEG evidence values. + """ return self.evidences.get(EvidenceType.ERP, []) @property def decision_made(self) -> bool: - """Returns true if the result of the inquiry was a decision.""" + """Returns true if the result of the inquiry was a decision. + + Returns: + bool: True if a decision was made. + """ return self.current_text != self.next_display_state @property def is_correct_decision(self) -> bool: - """Indicates whether the current selection was the target""" + """Indicates whether the current selection was the target. + + Returns: + bool: True if selection matches target_letter. + """ if self.selection and self.target_letter: return self.selection == self.target_letter return False @classmethod - def from_dict(cls, data: dict) -> 'Inquiry': - """Deserializes from a dict + def from_dict(cls, data: Dict[str, Any]) -> 'Inquiry': + """Deserializes from a dict. - Parameters: - ---------- - data - a dict in the format of the data output by the as_dict - method. + Args: + data: A dict in the format of the data output by the as_dict method. + + Returns: + Inquiry: New instance created from dict data. """ # partition into evidence data and other data. - evidences = { EvidenceType.deserialized(name): value for name, value in data.items() if name.endswith(EVIDENCE_SUFFIX) @@ -148,9 +187,13 @@ def from_dict(cls, data: dict) -> 'Inquiry': inquiry.evidences = evidences return inquiry - def as_dict(self) -> Dict: - """Dict representation""" - data: Dict = { + def as_dict(self) -> Dict[str, Any]: + """Dict representation. + + Returns: + Dict[str, Any]: Dictionary containing inquiry data. + """ + data: Dict[str, Any] = { 'stimuli': self.stimuli, 'timing': self.timing, 'triggers': self.triggers, @@ -174,15 +217,18 @@ def as_dict(self) -> Dict: def stim_evidence(self, symbol_set: List[str], n_most_likely: int = 5) -> Dict[str, Any]: - """Returns a dict of stim sequence data useful for debugging. Evidences - are paired with the appropriate symbol for easier visual + """Returns a dict of stim sequence data useful for debugging. + + Evidences are paired with the appropriate symbol for easier visual scanning. Also, an additional attribute is provided to display the top n most likely symbols based on the current evidence. - Parameters: - ----------- - symbol_set - list of stim in the same order as the evidences. - n_most_likely - number of most likely elements to include + Args: + symbol_set: List of stim in the same order as the evidences. + n_most_likely: Number of most likely elements to include. + + Returns: + Dict[str, Any]: Dictionary containing stimulus evidence data. """ likelihood = dict(zip(symbol_set, self.format(self.likelihood))) data: Dict[str, Any] = { @@ -199,9 +245,11 @@ def stim_evidence(self, def format(self, evidence: List[float]) -> List[float]: """Format the evidence for output. - Parameters - ---------- - evidence - list of evidence values + Args: + evidence: List of evidence values. + + Returns: + List[float]: Formatted evidence values. """ if self.precision: return rounded(evidence, self.precision) @@ -209,7 +257,16 @@ def format(self, evidence: List[float]) -> List[float]: class Session: - """Represents a data collection session. Not all tasks record session data.""" + """Represents a data collection session. Not all tasks record session data. + + Args: + save_location: Location where session data will be saved. + symbol_set: List of possible symbols that can be presented. + task: Name of the task being performed. + mode: Mode of operation (e.g., 'RSVP'). + decision_threshold: Threshold for making decisions. + task_data: Additional task-specific data. + """ def __init__(self, save_location: str, @@ -232,24 +289,40 @@ def __init__(self, @property def total_number_series(self) -> int: - """Total number of series that contain sequences.""" + """Total number of series that contain sequences. + + Returns: + int: Number of non-empty series. + """ return len([lst for lst in self.series if lst]) @property def total_number_decisions(self) -> int: - """Total number of series that ended in a decision.""" + """Total number of series that ended in a decision. + + Returns: + int: Number of completed series. + """ # An alternate implementation would be to count the inquiries with # decision_made property of true. return len(self.series) - 1 @property def total_inquiries(self) -> int: - """Total number of inquiries presented.""" + """Total number of inquiries presented. + + Returns: + int: Total number of inquiries. + """ return sum([len(lst) for lst in self.series]) @property def inquiries_per_selection(self) -> Optional[float]: - """Inquiries per selection""" + """Inquiries per selection. + + Returns: + Optional[float]: Average inquiries per selection, or None if no selections. + """ selections = self.total_number_decisions if selections == 0: return None @@ -257,25 +330,32 @@ def inquiries_per_selection(self) -> Optional[float]: @property def all_inquiries(self) -> List[Inquiry]: - """List of all Inquiries for the whole session""" + """List of all Inquiries for the whole session. + + Returns: + List[Inquiry]: All inquiries from non-empty series. + """ return [inq for inquiries in self.series for inq in inquiries if inquiries] def has_evidence(self) -> bool: - """Tests whether any inquiries have evidence.""" + """Tests whether any inquiries have evidence. + + Returns: + bool: True if any inquiries have evidence. + """ return any(inq.evidences for inq in self.all_inquiries) def add_series(self) -> None: - """Add another series unless the last one is empty""" + """Add another series unless the last one is empty.""" if self.last_series(): self.series.append([]) def add_sequence(self, inquiry: Inquiry, new_series: bool = False) -> None: - """Append sequence information + """Append sequence information. - Parameters: - ----------- - inquiry - data to append - new_series - a True value indicates that this is the first stim of + Args: + inquiry: Data to append. + new_series: A True value indicates that this is the first stim of a new series. """ if new_series: @@ -283,23 +363,42 @@ def add_sequence(self, inquiry: Inquiry, new_series: bool = False) -> None: self.last_series().append(inquiry) def last_series(self) -> List[Inquiry]: - """Returns the last series""" + """Returns the last series. + + Returns: + List[Inquiry]: Last series of inquiries. + """ return self.series[-1] def last_inquiry(self) -> Optional[Inquiry]: - """Returns the last inquiry of the last series.""" + """Returns the last inquiry of the last series. + + Returns: + Optional[Inquiry]: Last inquiry if it exists. + """ series = self.last_series() if series: return series[-1] return None def latest_series_is_empty(self) -> bool: - """Whether the latest series has had any inquiries added to it.""" + """Whether the latest series has had any inquiries added to it. + + Returns: + bool: True if latest series is empty. + """ return len(self.last_series()) == 0 def as_dict(self, evidence_only: bool = False) -> Dict[str, Any]: - """Dict representation""" + """Dict representation. + + Args: + evidence_only: Whether to include only evidence-related data. + + Returns: + Dict[str, Any]: Dictionary containing session data. + """ series_dict: Dict[str, Any] = {} for i, series in enumerate(self.series): if series: @@ -339,13 +438,14 @@ def as_dict(self, return info @classmethod - def from_dict(cls, data: dict) -> 'Session': + def from_dict(cls, data: Dict[str, Any]) -> 'Session': """Deserialize from a dict. - Parameters: - ---------- - data - a dict in the format of the data output by the as_dict - method. + Args: + data: A dict in the format of the data output by the as_dict method. + + Returns: + Session: New session instance created from dict data. """ session = cls(save_location=data['session'], task=data['task'], diff --git a/bcipy/task/demo/actions/demo_calibration_report.py b/bcipy/task/demo/actions/demo_calibration_report.py index bce16274c..9ca7b79f8 100644 --- a/bcipy/task/demo/actions/demo_calibration_report.py +++ b/bcipy/task/demo/actions/demo_calibration_report.py @@ -1,14 +1,16 @@ import logging -from bcipy.task.actions import BciPyCalibrationReportAction + from bcipy.config import DEFAULT_PARAMETERS_PATH -from bcipy.helpers.load import load_json_parameters +from bcipy.io.load import load_json_parameters +from bcipy.task.actions import BciPyCalibrationReportAction logging.basicConfig(level=logging.INFO) if __name__ == '__main__': import argparse - parser = argparse.ArgumentParser(description='Generate a calibration report from a session data file.') + parser = argparse.ArgumentParser( + description='Generate a calibration report from a session data file.') # Add the arguments: parameters and protocol parser.add_argument( '--parameters', @@ -30,6 +32,7 @@ The protocol path is the path to the directory containing the calibration sessions. """ - action = BciPyCalibrationReportAction(parameters=parameters, save_path='.', protocol_path=args.protocol) + action = BciPyCalibrationReportAction( + parameters=parameters, save_path='.', protocol_path=args.protocol) print('Generating Report.') task_data = action.execute() diff --git a/bcipy/task/demo/control/demo_handler.py b/bcipy/task/demo/control/demo_handler.py index cf8b8e0f9..318f24960 100644 --- a/bcipy/task/demo/control/demo_handler.py +++ b/bcipy/task/demo/control/demo_handler.py @@ -1,6 +1,7 @@ -from bcipy.task.control.handler import EvidenceFusion, DecisionMaker import numpy as np +from bcipy.task.control.handler import DecisionMaker, EvidenceFusion + def _demo_fusion(): len_alp = 4 @@ -39,8 +40,6 @@ def _demo_decision_maker(): conjugator = EvidenceFusion(evidence_names, len_dist=len_alp) decision_maker = DecisionMaker( - min_num_inq=1, - max_num_inq=10, state='', alphabet=alp) diff --git a/bcipy/task/demo/orchestrator/demo_orchestrator.py b/bcipy/task/demo/orchestrator/demo_orchestrator.py index d57bd0013..fdc6f777e 100644 --- a/bcipy/task/demo/orchestrator/demo_orchestrator.py +++ b/bcipy/task/demo/orchestrator/demo_orchestrator.py @@ -1,9 +1,11 @@ from bcipy.config import DEFAULT_PARAMETERS_PATH +from bcipy.task.actions import (BciPyCalibrationReportAction, IntertaskAction, + OfflineAnalysisAction) from bcipy.task.orchestrator import SessionOrchestrator -from bcipy.task.actions import (OfflineAnalysisAction, IntertaskAction, BciPyCalibrationReportAction) -from bcipy.task.paradigm.rsvp import RSVPCalibrationTask # from bcipy.task.paradigm.rsvp import RSVPCopyPhraseTask, RSVPTimingVerificationCalibration from bcipy.task.paradigm.matrix import MatrixCalibrationTask +from bcipy.task.paradigm.rsvp import RSVPCalibrationTask + # from bcipy.task.paradigm.matrix.timing_verification import MatrixTimingVerificationCalibration @@ -41,7 +43,8 @@ def demo_orchestrator(parameters_path: str) -> None: import argparse - parser = argparse.ArgumentParser(description="Demo the SessionOrchestrator") + parser = argparse.ArgumentParser( + description="Demo the SessionOrchestrator") parser.add_argument( '-p', '--parameters_path', diff --git a/bcipy/task/exceptions.py b/bcipy/task/exceptions.py index 7de570c24..5e29cb573 100644 --- a/bcipy/task/exceptions.py +++ b/bcipy/task/exceptions.py @@ -1,33 +1,79 @@ +"""Task-specific exceptions for the BciPy task module. + +This module defines custom exceptions that can be raised during task execution, +registration, and evidence evaluation. +""" + from typing import Any, Optional class InsufficientDataException(Exception): - """Insufficient Data Exception. + """Exception raised when task data requirements are not met. + + This exception is raised when a task does not have sufficient data to + execute properly, such as missing calibration data or required parameters. + + Args: + message: Description of what data was insufficient. + errors: Optional additional error information. - Thrown when data requirements to execute task are violated. + Attributes: + message: The error message. + errors: Additional error details, if any. """ def __init__(self, message: str, errors: Optional[Any] = None) -> None: super().__init__(message) + self.message = message self.errors = errors class TaskRegistryException(Exception): - """Task Registry Exception. + """Exception raised when there are issues with task registration. - Thrown when task type is unregistered. + This exception is raised when attempting to use an unregistered task type + or when there are problems with the task registry. + + Args: + message: Description of the registration issue. + errors: Optional additional error information. + + Attributes: + message: The error message. + errors: Additional error details, if any. """ def __init__(self, message: str, errors: Optional[Any] = None) -> None: super().__init__(message) + self.message = message self.errors = errors class MissingEvidenceEvaluator(Exception): - """Thrown when an evidence evaluator can't be found that matches the - provided data content type input and evidence_type output""" + """Exception raised when a required evidence evaluator is not found. + + This exception is raised when no evidence evaluator can be found that matches + the provided data content type input and evidence_type output requirements. + + Args: + message: Description of the missing evaluator. + """ + + def __init__(self, message: str) -> None: + super().__init__(message) + self.message = message class DuplicateModelEvidence(Exception): - """Thrown from a task when more than one of the provided models produces - the same type of evidence""" + """Exception raised when multiple models produce the same evidence type. + + This exception is raised when more than one of the provided models produces + the same type of evidence, making it ambiguous which evidence should be used. + + Args: + message: Description of the duplicate evidence. + """ + + def __init__(self, message: str) -> None: + super().__init__(message) + self.message = message diff --git a/bcipy/task/main.py b/bcipy/task/main.py index 65083f8d1..0e3c51809 100644 --- a/bcipy/task/main.py +++ b/bcipy/task/main.py @@ -1,24 +1,47 @@ -from dataclasses import dataclass -from typing import Optional -from bcipy.helpers.parameters import Parameters +"""Core task module defining base classes for BciPy tasks. + +This module provides the foundational classes for implementing BCI tasks, +including the abstract base Task class and supporting data structures. +""" + from abc import ABC, abstractmethod +from dataclasses import dataclass from enum import Enum +from typing import Any, Dict, Optional -from bcipy.helpers.stimuli import play_sound from bcipy.config import STATIC_AUDIO_PATH +from bcipy.core.parameters import Parameters +from bcipy.core.stimuli import play_sound @dataclass -class TaskData(): - """TaskData. +class TaskData: + """Data structure for storing task execution results. + + This class encapsulates the data returned from a task execution, including + the save path for any generated data and a dictionary of task-specific data. - Data structure for storing task return data. + Attributes: + save_path: Path where task data was saved. + task_dict: Dictionary containing task-specific data and results. """ save_path: Optional[str] = None - task_dict: Optional[dict] = None + task_dict: Optional[Dict[str, Any]] = None class TaskMode(Enum): + """Enumeration of supported BCI task modes. + + This enum defines the different types of tasks that can be executed in the BCI system. + Each mode represents a specific type of interaction or experiment. + + Attributes: + CALIBRATION: Mode for system calibration tasks. + COPYPHRASE: Mode for copy-spelling tasks. + TIMING_VERIFICATION: Mode for timing verification tasks. + ACTION: Mode for action-based tasks. + TRAINING: Mode for training tasks. + """ CALIBRATION = "calibration" COPYPHRASE = "copy phrase" TIMING_VERIFICATION = "timing verification" @@ -26,16 +49,37 @@ class TaskMode(Enum): TRAINING = "training" def __str__(self) -> str: + """Return the string value of the task mode. + + Returns: + str: The string representation of the task mode. + """ return self.value def __repr__(self) -> str: + """Return the string representation of the task mode. + + Returns: + str: The string representation of the task mode. + """ return self.value class Task(ABC): - """Task. + """Abstract base class for BciPy tasks. + + This class defines the interface that all BCI tasks must implement. It provides + the basic structure for task execution, setup, and cleanup. - Base class for BciPy tasks. + Attributes: + name: Name of the task. + mode: Mode of operation for the task. + parameters: Task configuration parameters. + data_save_location: Location where task data should be saved. + + Note: + Subclasses must define the 'name' and 'mode' class attributes and + implement the execute() method. """ name: str mode: TaskMode @@ -43,19 +87,62 @@ class Task(ABC): data_save_location: str def __init__(self, *args, **kwargs) -> None: + """Initialize the task. + + Args: + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + + Raises: + AssertionError: If name or mode attributes are not defined. + """ super(Task, self).__init__() - assert getattr(self, 'name', None) is not None, "Task must have a `name` attribute defined" - assert getattr(self, 'mode', None) is not None, "Task must have a `mode` attribute defined" + assert getattr( + self, 'name', None) is not None, "Task must have a `name` attribute defined" + assert getattr( + self, 'mode', None) is not None, "Task must have a `mode` attribute defined" @abstractmethod def execute(self) -> TaskData: + """Execute the task. + + This method must be implemented by all task subclasses to define the + task's execution logic. + + Returns: + TaskData: Object containing the results of the task execution. + """ ... - def setup(self, *args, **kwargs): + def setup(self, *args, **kwargs) -> None: + """Set up the task before execution. + + This method can be overridden by subclasses to perform any necessary + setup before task execution. + + Args: + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + """ ... - def cleanup(self, *args, **kwargs): + def cleanup(self, *args, **kwargs) -> None: + """Clean up after task execution. + + This method can be overridden by subclasses to perform any necessary + cleanup after task execution. + + Args: + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + """ ... - def alert(self): - play_sound(f"{STATIC_AUDIO_PATH}/{self.parameters['alert_sound_file']}") + def alert(self) -> None: + """Play an alert sound. + + Plays the configured alert sound file to notify the user. + The sound file is specified in the task parameters. + """ + play_sound( + f"{STATIC_AUDIO_PATH}/{self.parameters['alert_sound_file']}") diff --git a/bcipy/task/orchestrator/__init__.py b/bcipy/task/orchestrator/__init__.py index df0973e4c..b594a7eb2 100644 --- a/bcipy/task/orchestrator/__init__.py +++ b/bcipy/task/orchestrator/__init__.py @@ -1,3 +1,10 @@ +"""Task orchestration module for managing BCI experiment sessions. + +This module provides functionality for managing and executing sequences of BCI tasks, +including task initialization, execution order, data saving, and logging. The main +component is the SessionOrchestrator, which handles the lifecycle of task execution. +""" + from bcipy.task.orchestrator.orchestrator import SessionOrchestrator __all__ = ['SessionOrchestrator'] diff --git a/bcipy/task/orchestrator/orchestrator.py b/bcipy/task/orchestrator/orchestrator.py index 1f07fb82a..3090c0e9f 100644 --- a/bcipy/task/orchestrator/orchestrator.py +++ b/bcipy/task/orchestrator/orchestrator.py @@ -1,69 +1,92 @@ +"""Task orchestration module for managing BCI experiment sessions. + +This module provides functionality for managing and executing sequences of BCI tasks, +handling task initialization, execution, logging, and data management. +""" + # mypy: disable-error-code="arg-type, assignment" import errno -import os import json -import subprocess -from datetime import datetime -import random import logging +import os +import random +import subprocess import time +from datetime import datetime from logging import Logger -from typing import List, Type, Optional - -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.system_utils import get_system_info, configure_logger +from typing import Any, Dict, List, Optional, Tuple, Type + +from bcipy.config import (DEFAULT_EXPERIMENT_ID, DEFAULT_PARAMETERS_FILENAME, + DEFAULT_PARAMETERS_PATH, DEFAULT_USER_ID, + MULTIPHRASE_FILENAME, PROTOCOL_FILENAME, + PROTOCOL_LOG_FILENAME, SESSION_LOG_FILENAME) +from bcipy.core.parameters import Parameters +from bcipy.helpers.utils import configure_logger, get_system_info +from bcipy.io.load import load_json_parameters from bcipy.task import Task, TaskData, TaskMode -from bcipy.config import ( - DEFAULT_EXPERIMENT_ID, - DEFAULT_PARAMETERS_FILENAME, - DEFAULT_PARAMETERS_PATH, - DEFAULT_USER_ID, - MULTIPHRASE_FILENAME, - PROTOCOL_FILENAME, - PROTOCOL_LOG_FILENAME, - SESSION_LOG_FILENAME, -) -from bcipy.helpers.load import load_json_parameters class SessionOrchestrator: + """Manages the execution of a protocol of BCI tasks. + + The Session Orchestrator is responsible for managing the execution of a sequence + of tasks within an experiment session. It handles task initialization, execution + order, data saving, and logging. + + Attributes: + tasks: List of task classes to execute. + task_names: List of task names in execution order. + parameters: Configuration parameters for the session. + sys_info: System information dictionary. + log: Session logger instance. + save_folder: Path where session data is saved. + session_data: List of data from executed tasks. + ready_to_execute: Whether tasks are ready to execute. + last_task_dir: Path to the last executed task's directory. + copyphrases: List of phrases for copy tasks. + next_phrase: Next phrase to be used in copy tasks. + starting_index: Starting index for copy tasks. + user: User identifier. + fake: Whether to use fake data. + experiment_id: Experiment identifier. + alert: Whether to alert when tasks complete. + visualize: Whether to visualize task results. + progress: Current task execution progress. + user_exit: Whether user has requested to exit. """ - Session Orchestrator - -------------------- - - The Session Orchestrator is responsible for managing the execution of a protocol of tasks. It is initialized with an - experiment ID, user ID, and parameters file. Tasks are added to the orchestrator, which are then executed in order. - """ - tasks: List[Type[Task]] - task_names: List[str] - parameters: Parameters - sys_info: dict - log: Logger - save_folder: str - session_data: List[TaskData] - ready_to_execute: bool = False - last_task_dir: Optional[str] = None def __init__( self, experiment_id: str = DEFAULT_EXPERIMENT_ID, user: str = DEFAULT_USER_ID, parameters_path: str = DEFAULT_PARAMETERS_PATH, - parameters: Parameters = None, + parameters: Optional[Parameters] = None, fake: bool = False, alert: bool = False, visualize: bool = False ) -> None: + """Initialize the session orchestrator. + + Args: + experiment_id: Identifier for the experiment session. + user: User identifier. + parameters_path: Path to parameters file. + parameters: Optional pre-loaded parameters object. + fake: Whether to use fake data for testing. + alert: Whether to alert when tasks complete. + visualize: Whether to visualize task results. + """ self.parameters_path = parameters_path if not parameters: - self.parameters = load_json_parameters(parameters_path, value_cast=True) + self.parameters = load_json_parameters( + parameters_path, value_cast=True) else: # This allows for the parameters to be passed in directly and modified before executions self.parameters = parameters - self.copyphrases = None - self.next_phrase = None - self.starting_index = 0 + self.copyphrases: Optional[List[Tuple[str, int]]] = None + self.next_phrase: Optional[str] = None + self.starting_index: int = 0 self.initialize_copy_phrases() @@ -71,37 +94,49 @@ def __init__( self.fake = fake self.experiment_id = experiment_id self.sys_info = self.get_system_info() - self.tasks = [] - self.task_names = [] - self.session_data = [] - self.save_folder = self._init_orchestrator_save_folder(self.parameters["data_save_loc"]) + self.tasks: List[Type[Task]] = [] + self.task_names: List[str] = [] + self.session_data: List[TaskData] = [] + self.save_folder = self._init_orchestrator_save_folder( + self.parameters["data_save_loc"]) self.logger = self._init_orchestrator_logger(self.save_folder) self.alert = alert - self.logger.info("Alerts are on") if self.alert else self.logger.info("Alerts are off") + self.logger.info("Alerts are on") if self.alert else self.logger.info( + "Alerts are off") self.visualize = visualize - self.progress = 0 + self.progress: int = 0 self.ready_to_execute = False self.user_exit = False + self.last_task_dir = None self.logger.info("Session Orchestrator initialized successfully") def add_task(self, task: Type[Task]) -> None: - """Add a task to the orchestrator""" + """Add a single task to the execution queue. + + Args: + task: Task class to add to the queue. + """ self.tasks.append(task) self.task_names.append(task.name) self.ready_to_execute = True def add_tasks(self, tasks: List[Type[Task]]) -> None: - """Add a list of tasks to the orchestrator""" + """Add multiple tasks to the execution queue. + + Args: + tasks: List of task classes to add to the queue. + """ for task in tasks: self.add_task(task) self.ready_to_execute = True def set_next_phrase(self) -> None: - """Set the next phrase to be copied from the list of copy phrases loaded or the parameters directly. + """Set the next phrase for copy phrase tasks. - If there are no more phrases to copy, the task text and spelled letters from parameters will be used. + If there are phrases in the copyphrases list, uses the next one. + Otherwise, uses the task_text from parameters. """ if self.copyphrases: if len(self.copyphrases) > 0: @@ -114,9 +149,9 @@ def set_next_phrase(self) -> None: self.parameters['spelled_letters_count'] = self.starting_index def initialize_copy_phrases(self) -> None: - """Load copy phrases from a json file or take the task text if no file is provided. + """Load copy phrases from a JSON file. - Expects a json file structured as follows: + The JSON file should be structured as: { "Phrases": [ [string, int], @@ -124,8 +159,9 @@ def initialize_copy_phrases(self) -> None: ... ] } + + If no file is provided, uses task_text from parameters. """ - # load copy phrases from json file or take the task text if no file is provided if self.parameters.get('copy_phrases_location'): with open(self.parameters['copy_phrases_location'], 'r') as f: copy_phrases = json.load(f) @@ -138,21 +174,26 @@ def initialize_copy_phrases(self) -> None: self.starting_index = self.parameters['spelled_letters_count'] def execute(self) -> None: - """Executes queued tasks in order""" + """Execute all queued tasks in order. + Raises: + Exception: If no tasks have been added to the queue. + """ if not self.ready_to_execute: msg = "Orchestrator not ready to execute. No tasks have been added." - self.log.error(msg) + self.logger.error(msg) raise Exception(msg) - self.logger.info(f"Session Orchestrator executing tasks in order: {self.task_names}") + self.logger.info( + f"Session Orchestrator executing tasks in order: {self.task_names}") for task in self.tasks: self.progress += 1 if task.mode == TaskMode.COPYPHRASE: self.set_next_phrase() try: # initialize the task save folder and logger - self.logger.info(f"Initializing task {self.progress}/{len(self.tasks)} {task.name}") + self.logger.info( + f"Initializing task {self.progress}/{len(self.tasks)} {task.name}") data_save_location = self._init_task_save_folder(task) self._init_task_logger(data_save_location) @@ -185,13 +226,15 @@ def execute(self) -> None: if self.visualize: # Visualize session data and fail silently if it errors try: - self.logger.info(f"Visualizing session data. Saving to {data_save_location}") + self.logger.info( + f"Visualizing session data. Saving to {data_save_location}") subprocess.run( f'bcipy-erp-viz -s "{data_save_location}" ' f'--parameters "{self.parameters_path}" --show --save', shell=True) except Exception as e: - self.logger.info(f'Error visualizing session data: {e}') + self.logger.info( + f'Error visualizing session data: {e}') initialized_task = None @@ -199,7 +242,7 @@ def execute(self) -> None: self.logger.error(f"Task {task.name} failed to execute") self.logger.exception(e) try: - initialized_task.cleanup() + initialized_task.cleanup() # type: ignore except BaseException: pass @@ -214,25 +257,52 @@ def execute(self) -> None: self.progress = 0 def _init_orchestrator_logger(self, save_folder: str) -> Logger: + """Initialize the session logger. + + Args: + save_folder: Directory to save log files. + + Returns: + Logger: Configured logger instance. + """ return configure_logger( save_folder, PROTOCOL_LOG_FILENAME, logging.DEBUG) def _init_orchestrator_save_folder(self, save_path: str) -> str: + """Initialize the session save directory. + + Args: + save_path: Base path for saving session data. + + Returns: + str: Path to the created save directory. + """ date_time = datetime.now() date = date_time.strftime("%Y-%m-%d") timestamp = date_time.strftime("%Y-%m-%d_%H-%M-%S") - # * No '/' after `save_folder` since it is included in - # * `data_save_location` in parameters path = f'{save_path}{self.user}/{date}/{self.experiment_id}/{timestamp}/' os.makedirs(path) os.makedirs(os.path.join(path, 'logs'), exist_ok=True) return path def _init_task_save_folder(self, task: Type[Task]) -> str: + """Initialize a save directory for a task. + + Args: + task: Task class to create directory for. + + Returns: + str: Path to the created task directory. + + Raises: + OSError: If directory creation fails for reasons other than + the directory already existing. + """ timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S") - save_directory = self.save_folder + f'{task.name.replace(" ", "_")}_{timestamp}/' + save_directory = self.save_folder + \ + f'{task.name.replace(" ", "_")}_{timestamp}/' try: # make a directory to save task data to os.makedirs(save_directory) @@ -250,49 +320,68 @@ def _init_task_save_folder(self, task: Type[Task]) -> str: "type": "str", } ) - self.parameters.save(save_directory, name=DEFAULT_PARAMETERS_FILENAME) + self.parameters.save( + save_directory, name=DEFAULT_PARAMETERS_FILENAME) except OSError as error: # If the error is anything other than file existing, raise an error if error.errno != errno.EEXIST: raise error + return save_directory def _init_task_logger(self, save_folder: str) -> None: - configure_logger( - save_folder, - SESSION_LOG_FILENAME, - logging.DEBUG) + """Initialize a logger for a task. + + Args: + save_folder: Directory to save task logs. + """ + configure_logger(save_folder, SESSION_LOG_FILENAME, logging.DEBUG) def _save_data(self) -> None: + """Save all session data. - self._save_procotol_data() - # Save the remaining phrase data to a json file to be used in the next session - if self.copyphrases and len(self.copyphrases) > 0: - self._save_copy_phrases() - - def _save_procotol_data(self) -> None: - # Save the protocol data to a json file - with open(f'{self.save_folder}/{PROTOCOL_FILENAME}', 'w') as f: - f.write(json.dumps({ - 'tasks': self.task_names, - 'parameters': self.parameters_path, - 'system_info': self.sys_info, - })) - self.logger.info("Protocol data successfully saved") + Saves protocol data and copy phrases data to their respective files. + """ + self._save_protocol_data() + self._save_copy_phrases() + + def _save_protocol_data(self) -> None: + """Save protocol data to a JSON file. + + Saves task names, system info, and other session metadata. + """ + data = { + 'tasks': self.task_names, + 'sys_info': self.sys_info, + 'parameters': self.parameters_path, + 'user': self.user, + 'experiment_id': self.experiment_id, + 'fake': self.fake + } + with open(os.path.join(self.save_folder, PROTOCOL_FILENAME), 'w') as f: + json.dump(data, f) def _save_copy_phrases(self) -> None: - # Save the copy phrases data to a json file - with open(f'{self.save_folder}/{MULTIPHRASE_FILENAME}', 'w') as f: - f.write(json.dumps({ - 'Phrases': self.copyphrases - })) - self.logger.info("Copy phrases data successfully saved") - - def get_system_info(self) -> dict: + """Save copy phrases data to a JSON file. + + Only saves if copy phrases were used in the session. + """ + if self.copyphrases: + with open(os.path.join(self.save_folder, MULTIPHRASE_FILENAME), 'w') as f: + json.dump({'Phrases': self.copyphrases}, f) + + def get_system_info(self) -> Dict[str, Any]: + """Get system information. + + Returns: + Dict[str, Any]: Dictionary containing system information. + """ return get_system_info() - def close_experiment_callback(self): - """Callback to close the experiment.""" - self.logger.info("User has exited the experiment.") + def close_experiment_callback(self) -> None: + """Callback for handling user-initiated experiment closure. + + Sets the user_exit flag to true to stop task execution. + """ self.user_exit = True diff --git a/bcipy/task/orchestrator/protocol.py b/bcipy/task/orchestrator/protocol.py index af950162c..30f680492 100644 --- a/bcipy/task/orchestrator/protocol.py +++ b/bcipy/task/orchestrator/protocol.py @@ -1,76 +1,68 @@ -"""This file can define actions that can happen in a session orchestrator visit. -To start these will be 1:1 with tasks, but later this can be extended to represent training sequences, GUI popups etc""" +"""Protocol handling module for BciPy task orchestration. + +This module provides functionality for parsing and managing task protocols, +which define sequences of actions to be executed in a session. While currently +focused on task sequences, this can be extended to support training sequences, +GUI interactions, and other orchestrated behaviors. +""" from typing import List, Type + +from bcipy.config import TASK_SEPARATOR from bcipy.task import Task -from bcipy.config import TASK_SEPERATOR from bcipy.task.registry import TaskRegistry def parse_protocol(protocol: str) -> List[Type[Task]]: - """ - Parses a string of actions into a list of Task objects. - - Converts a string of actions into a list of Task objects. The string is expected - to be in the format of 'Action1 -> Action2 -> ... -> ActionN'. - Parameters - ---------- - protocol : str - A string of actions in the format of 'Action1 -> Action2 -> ... -> ActionN'. - - Returns - ------- - List[TaskType] - A list of TaskType objects that represent the actions in the input string. + """Parse a protocol string into a list of Task classes. + + Converts a string of task names into a list of Task classes. The string + should be in the format 'Task1 -> Task2 -> ... -> TaskN', where each + task name corresponds to a registered task in the TaskRegistry. + + Args: + protocol: String of task names separated by the task separator. + Format: 'Task1 -> Task2 -> ... -> TaskN' + + Returns: + List[Type[Task]]: List of Task classes corresponding to the protocol. + + Raises: + ValueError: If any task name in the protocol is not registered. """ task_registry = TaskRegistry() - return [task_registry.get(item.strip()) for item in protocol.split(TASK_SEPERATOR)] + return [task_registry.get(item.strip()) for item in protocol.split(TASK_SEPARATOR)] def validate_protocol_string(protocol: str) -> None: - """ - Validates a string of actions. + """Validate a protocol string against registered tasks. - Validates a string of actions. The string is expected to be in the format of 'Action1 -> Action2 -> ... -> ActionN'. + Checks that all task names in the protocol string correspond to + registered tasks in the TaskRegistry. - Parameters - ---------- - protocol : str - A string of actions in the format of 'Action1 -> Action2 -> ... -> ActionN'. + Args: + protocol: String of task names separated by the task separator. + Format: 'Task1 -> Task2 -> ... -> TaskN' - Raises - ------ - ValueError - If the string of actions is invalid. + Raises: + ValueError: If any task name in the protocol is not registered. """ - for protocol_item in protocol.split(TASK_SEPERATOR): + for protocol_item in protocol.split(TASK_SEPARATOR): if protocol_item.strip() not in TaskRegistry().list(): - raise ValueError(f"Invalid task '{protocol_item}' name in protocol string.") + raise ValueError( + f"Invalid task '{protocol_item}' name in protocol string.") -def serialize_protocol(protocol: List[Type[Task]]) -> str: - """ - Converts a list of TaskType objects into a string of actions. +def serialize_protocol(tasks: List[Type[Task]]) -> str: + """Convert a list of Task classes into a protocol string. - Converts a list of TaskType objects into a string of actions. The string is in the format of - 'Action1 -> Action2 -> ... -> ActionN'. + Creates a protocol string from a list of Task classes, using the task + separator to join task names. - Parameters - ---------- - protocol : str - A string of actions in the format of 'Action1 -> Action2 -> ... -> ActionN'. + Args: + tasks: List of Task classes to serialize. - Returns - ------- - List[TaskType] - A list of TaskType objects that represent the actions in the input string. + Returns: + str: Protocol string in format 'Task1 -> Task2 -> ... -> TaskN'. """ - - return f" {TASK_SEPERATOR} ".join([item.name for item in protocol]) - - -if __name__ == '__main__': - actions = parse_protocol("Matrix Calibration -> Matrix Copy Phrase") - string = serialize_protocol(actions) - print(actions) - print(string) + return f" {TASK_SEPARATOR} ".join([item.name for item in tasks]) diff --git a/bcipy/task/paradigm/matrix/calibration.py b/bcipy/task/paradigm/matrix/calibration.py index a16cc6305..851bc7942 100644 --- a/bcipy/task/paradigm/matrix/calibration.py +++ b/bcipy/task/paradigm/matrix/calibration.py @@ -1,44 +1,63 @@ -from typing import Any, Dict, Optional, List +"""Matrix calibration task module. + +This module provides the Matrix calibration task implementation which performs +Matrix stimulus inquiries to elicit ERPs. The task presents a matrix of stimuli +and highlights them according to configured parameters. +""" + +from typing import Any, Dict, List, Optional from psychopy import visual +from bcipy.core.parameters import Parameters from bcipy.display import InformationProperties, StimuliProperties from bcipy.display.components.task_bar import CalibrationTaskBar from bcipy.display.main import PreviewParams from bcipy.display.paradigm.matrix.display import MatrixDisplay from bcipy.helpers.clock import Clock -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.save import save_stimuli_position_info -from bcipy.helpers.system_utils import get_screen_info +from bcipy.helpers.utils import get_screen_info +from bcipy.io.save import save_stimuli_position_info from bcipy.task.calibration import BaseCalibrationTask class MatrixCalibrationTask(BaseCalibrationTask): """Matrix Calibration Task. - Calibration task performs an Matrix stimulus inquiry - 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 --> highlighting inquiries --> - saving data - - PARAMETERS: - ---------- - parameters (dict) - file_save (str) - fake (bool) - + This task performs Matrix stimulus inquiries to elicit ERPs by highlighting + elements in a matrix display. Parameters control the number of stimuli, + highlight duration, colors, and text/image inputs. + + Task flow: + 1. Setup variables + 2. Initialize EEG + 3. Await user input + 4. Setup stimuli + 5. Perform highlighting inquiries + 6. Save data + + Attributes: + name: Name of the task. + paradigm: Name of the paradigm. + parameters: Task configuration parameters. + file_save: Path for saving task data. + fake: Whether to run in fake (testing) mode. + window: PsychoPy window for display. + experiment_clock: Task timing clock. + display: Matrix display instance. + symbol_set: Set of symbols to display. """ + name = 'Matrix Calibration' paradigm = 'Matrix' @property def screen_info(self) -> Dict[str, Any]: - """Screen properties""" + """Get screen properties. + + Returns: + Dict[str, Any]: Dictionary containing screen size, refresh rate, + and units information. + """ return { 'screen_size_pixels': self.window.size.tolist(), 'screen_hz': get_screen_info().rate, @@ -46,22 +65,45 @@ def screen_info(self) -> Dict[str, Any]: } def init_display(self) -> MatrixDisplay: - """Initialize the display""" + """Initialize the matrix display. + + Returns: + MatrixDisplay: Configured matrix display instance. + """ return init_matrix_display(self.parameters, self.window, self.experiment_clock, self.symbol_set) def exit_display(self) -> None: + """Clean up display resources and save screenshot. + + Raises: + AssertionError: If display is not a MatrixDisplay instance. + """ assert isinstance(self.display, MatrixDisplay) self.display.capture_grid_screenshot(self.file_save) return super().exit_display() def cleanup(self) -> None: + """Perform cleanup operations and save stimuli position data. + + Raises: + AssertionError: If display is not a MatrixDisplay instance. + """ assert isinstance(self.display, MatrixDisplay) save_stimuli_position_info(self.display.stim_positions, self.file_save, self.screen_info) return super().cleanup() def session_task_data(self) -> Optional[Dict[str, Any]]: + """Get session task data. + + Returns: + Optional[Dict[str, Any]]: Dictionary containing stimuli positions + and screen information. + + Raises: + AssertionError: If display is not a MatrixDisplay instance. + """ assert isinstance(self.display, MatrixDisplay) return {**self.display.stim_positions, **self.screen_info} @@ -69,7 +111,17 @@ def session_task_data(self) -> Optional[Dict[str, Any]]: def init_matrix_display(parameters: Parameters, window: visual.Window, experiment_clock: Clock, symbol_set: List[str]) -> MatrixDisplay: - """Initialize the matrix display""" + """Initialize the matrix display with given parameters. + + Args: + parameters: Task configuration parameters. + window: PsychoPy window for display. + experiment_clock: Task timing clock. + symbol_set: Set of symbols to display. + + Returns: + MatrixDisplay: Configured matrix display instance. + """ info = InformationProperties( info_color=[parameters['info_color']], info_pos=[(parameters['info_pos_x'], parameters['info_pos_y'])], @@ -78,7 +130,8 @@ def init_matrix_display(parameters: Parameters, window: visual.Window, info_text=[parameters['info_text']], ) stimuli = StimuliProperties(stim_font=parameters['font'], - stim_pos=(parameters['matrix_stim_pos_x'], parameters['matrix_stim_pos_y']), + stim_pos=( + parameters['matrix_stim_pos_x'], parameters['matrix_stim_pos_y']), stim_height=parameters['matrix_stim_height'], stim_inquiry=[''] * parameters['stim_length'], stim_colors=[parameters['stim_color']] * diff --git a/bcipy/task/paradigm/matrix/copy_phrase.py b/bcipy/task/paradigm/matrix/copy_phrase.py index 56f89d8bc..fe993e813 100644 --- a/bcipy/task/paradigm/matrix/copy_phrase.py +++ b/bcipy/task/paradigm/matrix/copy_phrase.py @@ -1,35 +1,41 @@ -"""Defines the Copy Phrase Task which uses a Matrix display""" +"""Matrix copy phrase task module. + +This module defines the Copy Phrase Task implementation using a Matrix display. +The task allows users to copy a predefined phrase using a matrix-based interface. +""" + from psychopy import visual +from bcipy.core.parameters import Parameters from bcipy.display import InformationProperties, StimuliProperties from bcipy.display.components.task_bar import CopyPhraseTaskBar from bcipy.display.main import PreviewParams from bcipy.display.paradigm.matrix.display import MatrixDisplay +from bcipy.helpers.clock import Clock from bcipy.task import TaskMode from bcipy.task.paradigm.rsvp.copy_phrase import RSVPCopyPhraseTask -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.clock import Clock class MatrixCopyPhraseTask(RSVPCopyPhraseTask): """Matrix Copy Phrase Task. - Initializes and runs all needed code for executing a copy phrase task. A - phrase is set in parameters and necessary objects (daq, display) are - passed to this function. - - Parameters - ---------- - parameters : dict, - configuration details regarding the experiment. See parameters.json - file_save : str, - path location of where to save data from the session - fake : boolean, optional - boolean to indicate whether this is a fake session or not. - Returns - ------- - TaskData + This task allows users to copy a predefined phrase using a matrix-based + interface. The task initializes and runs all necessary components for + executing a copy phrase task. + + Attributes: + name: Name of the task. + paradigm: Name of the paradigm. + mode: Task execution mode. + parameters: Task configuration parameters. + file_save: Path for saving task data. + fake: Whether to run in fake (testing) mode. + window: PsychoPy window for display. + experiment_clock: Task timing clock. + spelled_text: Currently spelled text. + PARAMETERS_USED: List of parameter names used by this task. """ + name = 'Matrix Copy Phrase' paradigm = 'Matrix' mode = TaskMode.COPYPHRASE @@ -100,7 +106,11 @@ class MatrixCopyPhraseTask(RSVPCopyPhraseTask): ] def init_display(self) -> MatrixDisplay: - """Initialize the Matrix display""" + """Initialize the Matrix display. + + Returns: + MatrixDisplay: Configured matrix display instance. + """ return init_display(self.parameters, self.window, self.experiment_clock, self.spelled_text) @@ -110,8 +120,17 @@ def init_display( win: visual.Window, experiment_clock: Clock, starting_spelled_text: str) -> MatrixDisplay: - """Constructs a new Matrix display""" + """Initialize a new Matrix display with given parameters. + Args: + parameters: Task configuration parameters. + win: PsychoPy window for display. + experiment_clock: Task timing clock. + starting_spelled_text: Initial text to display. + + Returns: + MatrixDisplay: Configured matrix display instance. + """ info = InformationProperties( info_color=[parameters['info_color']], info_pos=[(parameters['info_pos_x'], parameters['info_pos_y'])], diff --git a/bcipy/task/paradigm/matrix/timing_verification.py b/bcipy/task/paradigm/matrix/timing_verification.py index a26c20876..bd225ece6 100644 --- a/bcipy/task/paradigm/matrix/timing_verification.py +++ b/bcipy/task/paradigm/matrix/timing_verification.py @@ -1,10 +1,16 @@ +"""Matrix timing verification module. + +This module provides functionality for verifying display timing in Matrix tasks +using photodiode stimuli. It alternates between solid and empty boxes that can +be measured with a photodiode to ensure accurate stimulus presentation timing. +""" + from itertools import cycle, islice, repeat from typing import Iterator, List -from bcipy.helpers.stimuli import (PhotoDiodeStimuli, get_fixation, - jittered_timing) -from bcipy.task.calibration import Inquiry +from bcipy.core.stimuli import PhotoDiodeStimuli, get_fixation, jittered_timing from bcipy.task import TaskMode +from bcipy.task.calibration import Inquiry from bcipy.task.paradigm.matrix.calibration import (MatrixCalibrationTask, MatrixDisplay) @@ -12,32 +18,49 @@ class MatrixTimingVerificationCalibration(MatrixCalibrationTask): """Matrix Timing Verification Task. - This task is used for verifying display timing by alternating solid and empty boxes. These - stimuli can be used with a photodiode to ensure accurate presentations. + This task verifies display timing by alternating solid and empty boxes. + The stimuli can be measured with a photodiode to ensure accurate + presentation timing. - Input: - parameters (Dictionary) - file_save (String) - fake (Boolean) - - Output: - TaskData + Attributes: + name: Name of the task. + mode: Task execution mode. + parameters: Task configuration parameters. + file_save: Path for saving task data. + fake: Whether to run in fake (testing) mode. """ + name = 'Matrix Timing Verification' mode = TaskMode.TIMING_VERIFICATION def init_display(self) -> MatrixDisplay: - """Initialize the display""" + """Initialize the display with transparent background. + + Returns: + MatrixDisplay: Configured matrix display instance. + """ display = super().init_display() display.start_opacity = 0.0 return display @property def symbol_set(self) -> List[str]: - """Symbols used in the calibration""" + """Get symbols used in the calibration. + + Returns: + List[str]: List of symbols with photodiode stimuli inserted. + """ return symbols_with_photodiode_stim(super().symbol_set) def init_inquiry_generator(self) -> Iterator[Inquiry]: + """Initialize the inquiry generator for timing verification. + + The generator alternates between solid and empty boxes with specified + timing parameters. A fixation point is shown between stimuli. + + Returns: + Iterator[Inquiry]: Generator yielding timing verification inquiries. + """ params = self.parameters # alternate between solid and empty boxes @@ -64,11 +87,27 @@ def init_inquiry_generator(self) -> Iterator[Inquiry]: def symbols_with_photodiode_stim(symbols: List[str]) -> List[str]: - """Stim symbols with the central letters swapped out for Photodiode stim. + """Replace central symbols with photodiode stimuli. + + Args: + symbols: List of symbols to modify. + + Returns: + List[str]: Modified list with central symbols replaced by photodiode + stimuli. """ mid = int(len(symbols) / 2) - def sym_at_index(sym, index) -> str: + def sym_at_index(sym: str, index: int) -> str: + """Get symbol at given index, replacing central indices with stimuli. + + Args: + sym: Original symbol. + index: Position in symbol list. + + Returns: + str: Original symbol or photodiode stimulus. + """ if index == mid: return PhotoDiodeStimuli.SOLID.value if index == mid + 1: diff --git a/bcipy/task/paradigm/rsvp/__init__.py b/bcipy/task/paradigm/rsvp/__init__.py index 111883a46..82e79d99e 100644 --- a/bcipy/task/paradigm/rsvp/__init__.py +++ b/bcipy/task/paradigm/rsvp/__init__.py @@ -1,4 +1,5 @@ # Import all RSVP tasks to make them available to the task registry from .calibration.calibration import RSVPCalibrationTask # noqa -from .calibration.timing_verification import RSVPTimingVerificationCalibration # noqa +from .calibration.timing_verification import \ + RSVPTimingVerificationCalibration # noqa from .copy_phrase import RSVPCopyPhraseTask # noqa diff --git a/bcipy/task/paradigm/rsvp/calibration/calibration.py b/bcipy/task/paradigm/rsvp/calibration/calibration.py index cd8fa0b25..b00024c41 100644 --- a/bcipy/task/paradigm/rsvp/calibration/calibration.py +++ b/bcipy/task/paradigm/rsvp/calibration/calibration.py @@ -1,47 +1,76 @@ +"""RSVP calibration task module. + +This module provides the RSVP (Rapid Serial Visual Presentation) calibration task +implementation which performs stimulus inquiries to elicit ERPs. The task presents +stimuli in rapid succession with configurable timing and appearance parameters. +""" from psychopy import core, visual +from bcipy.core.parameters import Parameters from bcipy.display import Display, InformationProperties, StimuliProperties from bcipy.display.components.task_bar import CalibrationTaskBar from bcipy.display.main import PreviewParams from bcipy.display.paradigm.rsvp.mode.calibration import CalibrationDisplay from bcipy.helpers.clock import Clock -from bcipy.helpers.parameters import Parameters from bcipy.task.calibration import BaseCalibrationTask class RSVPCalibrationTask(BaseCalibrationTask): """RSVP Calibration Task. - Calibration task performs an RSVP 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. - - This task progresses as follows: + This task performs RSVP stimulus inquiries to elicit ERPs by presenting + stimuli in rapid succession. Parameters control the number of stimuli, + presentation duration, colors, and text/image inputs. - setting up variables --> initializing eeg --> awaiting user input to start --> setting up stimuli --> - presenting inquiries --> saving data + Task flow: + 1. Setup variables + 2. Initialize EEG + 3. Await user input + 4. Setup stimuli + 5. Present inquiries + 6. Save data - PARAMETERS: - ---------- - parameters (dict) - file_save (str) - fake (bool) + Attributes: + name (str): Name of the task. + paradigm (str): Name of the paradigm. + parameters (Parameters): Task configuration parameters. + file_save (str): Path for saving task data. + fake (bool): Whether to run in fake (testing) mode. + window (visual.Window): PsychoPy window for display. + static_clock (core.StaticPeriod): Clock for static timing. + experiment_clock (Clock): Clock for experiment timing. """ - name = 'RSVP Calibration' - paradigm = 'RSVP' + + name: str = 'RSVP Calibration' + paradigm: str = 'RSVP' def init_display(self) -> Display: + """Initialize the RSVP display. + + Returns: + Display: Configured RSVP calibration display instance. + """ return init_calibration_display_task(self.parameters, self.window, self.static_clock, self.experiment_clock) def init_calibration_display_task( - parameters: Parameters, window: visual.Window, + parameters: Parameters, + window: visual.Window, static_clock: core.StaticPeriod, experiment_clock: Clock) -> CalibrationDisplay: - """Initialize the display""" + """Initialize the RSVP calibration display. + + Args: + parameters (Parameters): Task configuration parameters. + window (visual.Window): PsychoPy window for display. + static_clock (core.StaticPeriod): Clock for static timing. + experiment_clock (Clock): Clock for experiment timing. + + Returns: + CalibrationDisplay: Configured RSVP calibration display instance. + """ info = InformationProperties( info_color=[parameters['info_color']], info_pos=[(parameters['info_pos_x'], parameters['info_pos_y'])], @@ -51,7 +80,8 @@ def init_calibration_display_task( ) stimuli = StimuliProperties( stim_font=parameters['font'], - stim_pos=(parameters['rsvp_stim_pos_x'], parameters['rsvp_stim_pos_y']), + stim_pos=(parameters['rsvp_stim_pos_x'], + parameters['rsvp_stim_pos_y']), stim_height=parameters['rsvp_stim_height'], stim_inquiry=[''] * parameters['stim_length'], stim_colors=[parameters['stim_color']] * parameters['stim_length'], @@ -72,7 +102,8 @@ def init_calibration_display_task( stimuli, task_bar, info, - preview_config=parameters.instantiate(PreviewParams), + preview_config=parameters.instantiate( + PreviewParams), trigger_type=parameters['trigger_type'], space_char=parameters['stim_space_char'], full_screen=parameters['full_screen']) diff --git a/bcipy/task/paradigm/rsvp/calibration/timing_verification.py b/bcipy/task/paradigm/rsvp/calibration/timing_verification.py index 07bcbba74..579369359 100644 --- a/bcipy/task/paradigm/rsvp/calibration/timing_verification.py +++ b/bcipy/task/paradigm/rsvp/calibration/timing_verification.py @@ -1,30 +1,37 @@ # mypy: disable-error-code="assignment" +"""RSVP timing verification module. + +This module provides functionality for verifying display timing in RSVP tasks +using photodiode stimuli. It alternates between solid and empty boxes that can +be measured with a photodiode to ensure accurate stimulus presentation timing. +""" + from itertools import cycle, islice, repeat from typing import Any, Iterator, List -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.stimuli import (PhotoDiodeStimuli, get_fixation, - jittered_timing) -from bcipy.task.calibration import Inquiry +from bcipy.core.parameters import Parameters +from bcipy.core.stimuli import PhotoDiodeStimuli, get_fixation, jittered_timing from bcipy.task import TaskMode +from bcipy.task.calibration import Inquiry from bcipy.task.paradigm.rsvp.calibration.calibration import \ RSVPCalibrationTask class RSVPTimingVerificationCalibration(RSVPCalibrationTask): - """RSVP Calibration Task. - - This task is used for verifying display timing by alternating solid and empty boxes. These - stimuli can be used with a photodiode to ensure accurate presentations. + """RSVP Timing Verification Task. - Input: - parameters (Parameters) - file_save (str) - fake (bool) + This task verifies display timing by alternating solid and empty boxes. + The stimuli can be measured with a photodiode to ensure accurate + presentation timing. - Output: - TaskData + Attributes: + name: Name of the task. + mode: Task execution mode. + parameters: Task configuration parameters. + file_save: Path for saving task data. + fake: Whether to run in fake (testing) mode. """ + name = 'RSVP Timing Verification' mode = TaskMode.TIMING_VERIFICATION @@ -33,6 +40,14 @@ def __init__(self, file_save: str, fake: bool = False, **kwargs: Any) -> None: + """Initialize the RSVP timing verification task. + + Args: + parameters: Task configuration parameters. + file_save: Path for saving task data. + fake: Whether to run in fake (testing) mode. + **kwargs: Additional keyword arguments. + """ parameters['rsvp_stim_height'] = 0.8 parameters['rsvp_stim_pos_y'] = 0.0 super(RSVPTimingVerificationCalibration, @@ -40,10 +55,22 @@ def __init__(self, @property def symbol_set(self) -> List[str]: - """Symbols used in the calibration""" + """Get symbols used in the calibration. + + Returns: + List[str]: List of photodiode stimuli symbols. + """ return PhotoDiodeStimuli.list() def init_inquiry_generator(self) -> Iterator[Inquiry]: + """Initialize the inquiry generator for timing verification. + + The generator alternates between solid and empty boxes with specified + timing parameters. A fixation point is shown between stimuli. + + Returns: + Iterator[Inquiry]: Generator yielding timing verification inquiries. + """ params = self.parameters # alternate between solid and empty boxes diff --git a/bcipy/task/paradigm/rsvp/copy_phrase.py b/bcipy/task/paradigm/rsvp/copy_phrase.py index a7f335dbd..68f401f85 100644 --- a/bcipy/task/paradigm/rsvp/copy_phrase.py +++ b/bcipy/task/paradigm/rsvp/copy_phrase.py @@ -1,4 +1,4 @@ -# mypy: disable-error-code="arg-type" +# mypy: disable-error-code="arg-type, override" import logging from typing import Any, List, NamedTuple, Optional, Tuple @@ -9,6 +9,14 @@ from bcipy.config import (DEFAULT_EVIDENCE_PRECISION, SESSION_DATA_FILENAME, SESSION_LOG_FILENAME, SESSION_SUMMARY_FILENAME, TRIGGER_FILENAME, WAIT_SCREEN_MESSAGE) +from bcipy.core.list import destutter +from bcipy.core.parameters import Parameters +from bcipy.core.session import session_excel +from bcipy.core.stimuli import InquirySchedule, StimuliOrder +from bcipy.core.symbols import BACKSPACE_CHAR, alphabet +from bcipy.core.triggers import (FlushFrequency, Trigger, TriggerHandler, + TriggerType, convert_timing_triggers, + offset_label) from bcipy.display import (InformationProperties, StimuliProperties, init_display_window) from bcipy.display.components.task_bar import CopyPhraseTaskBar @@ -21,21 +29,13 @@ from bcipy.helpers.clock import Clock from bcipy.helpers.copy_phrase_wrapper import CopyPhraseWrapper from bcipy.helpers.language_model import init_language_model -from bcipy.helpers.list import destutter -from bcipy.helpers.load import choose_signal_models -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.save import _save_session_related_data -from bcipy.helpers.session import session_excel -from bcipy.helpers.stimuli import InquirySchedule, StimuliOrder -from bcipy.helpers.symbols import BACKSPACE_CHAR, alphabet from bcipy.helpers.task import (consecutive_incorrect, construct_triggers, fake_copy_phrase_decision, get_device_data_for_decision, get_user_input, relative_triggers, target_info, trial_complete_message) -from bcipy.helpers.triggers import (FlushFrequency, Trigger, TriggerHandler, - TriggerType, convert_timing_triggers, - offset_label) +from bcipy.io.load import choose_signal_models +from bcipy.io.save import _save_session_related_data from bcipy.language.main import LanguageModel from bcipy.signal.model import SignalModel from bcipy.signal.model.inquiry_preview import compute_probs_after_preview @@ -178,8 +178,10 @@ def __init__( self.button_press_error_prob = parameters['preview_inquiry_error_prob'] self.signal_model = self.signal_models[0] if self.signal_models else None - self.evidence_evaluators = self.init_evidence_evaluators(self.signal_models) - self.evidence_types = self.init_evidence_types(self.signal_models, self.evidence_evaluators) + self.evidence_evaluators = self.init_evidence_evaluators( + self.signal_models) + self.evidence_types = self.init_evidence_types( + self.signal_models, self.evidence_evaluators) self.file_save = file_save self.save_session_every_inquiry = True @@ -201,6 +203,7 @@ def setup( parameters: Parameters, data_save_location: str, fake: bool = False) -> Tuple[ClientManager, List[LslDataServer], Window]: + """Set up acquisition and return client manager, data servers, and display.""" # Initialize Acquisition daq, servers = init_acquisition( parameters, data_save_location, server=fake) @@ -212,9 +215,11 @@ def setup( return daq, servers, display def get_language_model(self) -> LanguageModel: + """Return the initialized language model.""" return init_language_model(self.parameters) def get_signal_models(self) -> Optional[List[SignalModel]]: + """Return the list of signal models, or an empty list if fake.""" if not self.fake: try: signal_models = choose_signal_models( @@ -227,6 +232,7 @@ def get_signal_models(self) -> Optional[List[SignalModel]]: return [] def cleanup(self): + """Clean up resources and save session data.""" self.exit_display() self.write_offset_trigger() self.save_session_data() @@ -256,6 +262,7 @@ def cleanup(self): logger.exception(str(e)) def save_session_data(self) -> None: + """Save the session data and summary to disk.""" self.session.task_summary = TaskSummary( self.session, self.parameters["show_preview_inquiry"], @@ -282,7 +289,8 @@ def init_evidence_evaluators( evidence_types = [] evaluators = [] for model in signal_models: - evaluator = init_evidence_evaluator(self.alp, model) + evaluator = init_evidence_evaluator(self.alp, model, + self.parameters) content_type = evaluator.consumes evidence_type = evaluator.produces if content_type in self.daq.active_device_content_types: @@ -302,6 +310,7 @@ def init_evidence_types( self, signal_models: List[SignalModel], evidence_evaluators: List[EvidenceEvaluator] ) -> List[EvidenceType]: + """Initialize evidence types for the simulation.""" evidence_types = [EvidenceType.LM] evidence_types.extend( [evaluator.produces for evaluator in evidence_evaluators]) @@ -317,7 +326,8 @@ def default_trigger_handler(self) -> TriggerHandler: def set(self) -> None: """Initialize/reset parameters used in the execute run loop.""" - self.spelled_text = str(self.copy_phrase[0: self.starting_spelled_letters()]) + self.spelled_text = str( + self.copy_phrase[0: self.starting_spelled_letters()]) self.last_selection = "" self.inq_counter = 0 self.session = Session( @@ -363,13 +373,15 @@ def validate_parameters(self) -> None: # ensure all required parameters are provided for param in RSVPCopyPhraseTask.PARAMETERS_USED: if param not in self.parameters: - raise TaskConfigurationException(f"parameter '{param}' is required") + raise TaskConfigurationException( + f"parameter '{param}' is required") # ensure data / query parameters are set correctly buffer_len = self.parameters["task_buffer_length"] prestim = self.parameters["prestim_length"] poststim = ( - self.parameters["trial_window"][1] - self.parameters["trial_window"][0] + self.parameters["trial_window"][1] - + self.parameters["trial_window"][0] ) if buffer_len < prestim: raise TaskConfigurationException( @@ -724,6 +736,8 @@ def compute_device_evidence( post_stim_buffer = int(self.parameters.get("task_buffer_length") / 2) prestim_buffer: float = self.parameters["prestim_length"] trial_window: Tuple[float, float] = self.parameters["trial_window"] + flash_time = self.parameters["time_flash"] + stim_length = self.parameters["stim_length"] window_length = trial_window[1] - trial_window[0] inquiry_timing = self.stims_for_decision(stim_times) @@ -756,6 +770,8 @@ def compute_device_evidence( times=times, target_info=filtered_labels, window_length=window_length, + flash_time=flash_time, + stim_length=stim_length, ) evidences.append((evidence_evaluator.produces, probs)) @@ -836,7 +852,8 @@ def exit_display(self) -> None: self.rsvp.update_task_bar(text=self.spelled_text) # Say Goodbye! - self.rsvp.info_text = trial_complete_message(self.window, self.parameters) + self.rsvp.info_text = trial_complete_message( + self.window, self.parameters) self.rsvp.draw_static() self.window.flip() @@ -906,9 +923,11 @@ def write_trigger_data( for content_type, client in self.daq.clients_by_type.items(): label = offset_label(content_type.name) time = ( - client.offset(self.rsvp.first_stim_time) - self.rsvp.first_stim_time + client.offset(self.rsvp.first_stim_time) - + self.rsvp.first_stim_time ) - offset_triggers.append(Trigger(label, TriggerType.OFFSET, time)) + offset_triggers.append( + Trigger(label, TriggerType.OFFSET, time)) self.trigger_handler.add_triggers(offset_triggers) triggers = convert_timing_triggers( @@ -970,16 +989,19 @@ def __init__( def as_dict(self) -> dict: """Computes the task summary data to append to the session.""" - selections = [inq for inq in self.session.all_inquiries if inq.selection] + selections = [ + inq for inq in self.session.all_inquiries if inq.selection] correct = [inq for inq in selections if inq.is_correct_decision] incorrect = [inq for inq in selections if not inq.is_correct_decision] # Note that SPACE is considered a symbol - correct_symbols = [inq for inq in correct if inq.selection != BACKSPACE_CHAR] + correct_symbols = [ + inq for inq in correct if inq.selection != BACKSPACE_CHAR] btn_presses = self.btn_press_count() sel_count = len(selections) - switch_per_selection = (btn_presses / sel_count) if sel_count > 0 else 0 + switch_per_selection = ( + btn_presses / sel_count) if sel_count > 0 else 0 accuracy = (len(correct) / sel_count) if sel_count > 0 else 0 # Note that minutes includes startup time and any breaks. @@ -997,9 +1019,7 @@ def as_dict(self) -> dict: } def btn_press_count(self) -> int: - """Compute the number of times the switch was activated. Returns 0 if - inquiry preview mode was off or mode was preview-only.""" - + """Compute the number of times the switch was activated. Returns 0 if inquiry preview mode was off or mode was preview-only.""" if not self.show_preview or self.preview_mode == 0: return 0 @@ -1029,7 +1049,8 @@ def switch_response_time(self) -> Optional[float]: logger.info("Could not compute switch_response_time") return None - response_times = [keypress.time - preview.time for preview, keypress in pairs] + response_times = [keypress.time - + preview.time for preview, keypress in pairs] count = len(response_times) return sum(response_times) / count if count > 0 else None @@ -1061,7 +1082,8 @@ def _init_copy_phrase_display( ) stimuli = StimuliProperties( stim_font=parameters["font"], - stim_pos=(parameters["rsvp_stim_pos_x"], parameters["rsvp_stim_pos_y"]), + stim_pos=(parameters["rsvp_stim_pos_x"], + parameters["rsvp_stim_pos_y"]), stim_height=parameters["rsvp_stim_height"], stim_inquiry=["A"] * parameters["stim_length"], stim_colors=[parameters["stim_color"]] * parameters["stim_length"], diff --git a/bcipy/task/paradigm/vep/calibration.py b/bcipy/task/paradigm/vep/calibration.py index 34cf9909e..52ad1c6b8 100644 --- a/bcipy/task/paradigm/vep/calibration.py +++ b/bcipy/task/paradigm/vep/calibration.py @@ -1,10 +1,18 @@ -"""VEP Calibration task-related code""" +"""VEP calibration task module. + +This module provides the VEP (Visual Evoked Potential) calibration task +implementation. The task presents visual stimuli with different flicker rates +to calibrate the system's response to visual evoked potentials. +""" + import logging from typing import Any, Dict, Iterator, List, Optional from psychopy import visual # type: ignore from bcipy.config import DEFAULT_FRAME_RATE, SESSION_LOG_FILENAME +from bcipy.core.parameters import Parameters +from bcipy.core.triggers import TriggerType from bcipy.display import InformationProperties, VEPStimuliProperties from bcipy.display.components.layout import centered from bcipy.display.components.task_bar import CalibrationTaskBar @@ -12,8 +20,6 @@ from bcipy.display.paradigm.vep.display import VEPDisplay from bcipy.display.paradigm.vep.layout import BoxConfiguration from bcipy.helpers.clock import Clock -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.triggers import TriggerType from bcipy.task.calibration import BaseCalibrationTask, Inquiry from bcipy.task.paradigm.vep.stim_generation import \ generate_vep_calibration_inquiries @@ -24,17 +30,27 @@ class VEPCalibrationTask(BaseCalibrationTask): """VEP Calibration Task. - A task begins setting up variables --> initializing eeg --> - awaiting user input to start --> - setting up stimuli --> highlighting inquiries --> - saving data + This task calibrates the system's response to visual evoked potentials by + presenting visual stimuli with different flicker rates. + + Task flow: + 1. Setup variables + 2. Initialize EEG + 3. Await user input + 4. Setup stimuli + 5. Present flickering inquiries + 6. Save data - PARAMETERS: - ---------- - parameters (dict) - file_save (str) - fake (bool) + Attributes: + name: Name of the task. + paradigm: Name of the paradigm. + parameters: Task configuration parameters. + file_save: Path for saving task data. + fake: Whether to run in fake (testing) mode. + box_colors: List of colors for stimulus boxes. + num_boxes: Number of stimulus boxes. """ + name = 'VEP Calibration' paradigm = 'VEP' @@ -43,6 +59,14 @@ def __init__(self, file_save: str, fake: bool = False, **kwargs: Any) -> None: + """Initialize the VEP calibration task. + + Args: + parameters: Task configuration parameters. + file_save: Path for saving task data. + fake: Whether to run in fake (testing) mode. + **kwargs: Additional keyword arguments. + """ self.box_colors = [ '#00FF80', '#FFFFB3', '#CB99FF', '#FB8072', '#80B1D3', '#FF8232' ] @@ -50,14 +74,22 @@ def __init__(self, super().__init__(parameters, file_save, fake=fake, **kwargs) def init_display(self) -> VEPDisplay: - """Initialize the display""" + """Initialize the VEP display. + + Returns: + VEPDisplay: Configured VEP display instance. + """ return init_vep_display(self.parameters, self.window, self.experiment_clock, self.symbol_set, self.box_colors, fake=self.fake) def init_inquiry_generator(self) -> Iterator[Inquiry]: - """Initializes a generator that returns inquiries to be presented.""" + """Initialize the inquiry generator. + + Returns: + Iterator[Inquiry]: Generator yielding VEP calibration inquiries. + """ parameters = self.parameters schedule = generate_vep_calibration_inquiries( alp=self.symbol_set, @@ -75,12 +107,30 @@ def init_inquiry_generator(self) -> Iterator[Inquiry]: def trigger_type(self, symbol: str, target: str, index: int) -> TriggerType: + """Get trigger type for a symbol. + + Args: + symbol: Presented symbol. + target: Target symbol. + index: Position in sequence. + + Returns: + TriggerType: Type of trigger to use. + """ if target == symbol: return TriggerType.TARGET return TriggerType.EVENT def session_task_data(self) -> Dict[str, Any]: - """Task-specific session data""" + """Get task-specific session data. + + Returns: + Dict[str, Any]: Dictionary containing box configurations and + starting positions. + + Raises: + AssertionError: If display is not a VEPDisplay instance. + """ assert isinstance(self.display, VEPDisplay) boxes = [{ "colors": box.colors, @@ -94,7 +144,18 @@ def session_task_data(self) -> Dict[str, Any]: def session_inquiry_data(self, inquiry: Inquiry) -> Optional[Dict[str, Any]]: - """Defines task-specific session data for each inquiry.""" + """Get task-specific data for an inquiry. + + Args: + inquiry: Inquiry to get data for. + + Returns: + Optional[Dict[str, Any]]: Dictionary containing target box index + and frequency. + + Raises: + AssertionError: If display is not a VEPDisplay instance. + """ assert isinstance(self.display, VEPDisplay) target_box = target_box_index(inquiry) target_freq = self.display.flicker_rates[ @@ -105,7 +166,14 @@ def session_inquiry_data(self, } def stim_labels(self, inquiry: Inquiry) -> List[str]: - """labels for each stimuli in the session data.""" + """Get labels for each stimulus in the session data. + + Args: + inquiry: Inquiry to get labels for. + + Returns: + List[str]: List of stimulus labels. + """ target_box = target_box_index(inquiry) targetness = [TriggerType.NONTARGET for _ in range(self.num_boxes)] if target_box is not None: @@ -115,7 +183,14 @@ def stim_labels(self, inquiry: Inquiry) -> List[str]: def target_box_index(inquiry: Inquiry) -> Optional[int]: - """Index of the target box.""" + """Get the index of the target box. + + Args: + inquiry: Inquiry to find target box in. + + Returns: + Optional[int]: Index of target box if found, None otherwise. + """ target_letter, _fixation, *boxes = inquiry.stimuli for i, box in enumerate(boxes): if target_letter in box: @@ -126,7 +201,19 @@ def target_box_index(inquiry: Inquiry) -> Optional[int]: def init_vep_display(parameters: Parameters, window: visual.Window, experiment_clock: Clock, symbol_set: List[str], box_colors: List[str], fake: bool = False) -> VEPDisplay: - """Initialize the display""" + """Initialize the VEP display. + + Args: + parameters: Task configuration parameters. + window: PsychoPy window for display. + experiment_clock: Clock for experiment timing. + symbol_set: Set of symbols to display. + box_colors: List of colors for stimulus boxes. + fake: Whether to run in fake (testing) mode. + + Returns: + VEPDisplay: Configured VEP display instance. + """ info = InformationProperties( info_color=[parameters['info_color']], info_pos=[(parameters['info_pos_x'], parameters['info_pos_y'])], diff --git a/bcipy/task/paradigm/vep/stim_generation.py b/bcipy/task/paradigm/vep/stim_generation.py index e5111f8e6..aed53e663 100644 --- a/bcipy/task/paradigm/vep/stim_generation.py +++ b/bcipy/task/paradigm/vep/stim_generation.py @@ -1,12 +1,18 @@ -"""Functions related to stimuli generation for VEP tasks""" +"""VEP stimulus generation module. + +This module provides functions for generating visual stimuli used in VEP +(Visual Evoked Potential) tasks. It handles the creation of calibration +inquiries, stimulus box configurations, and inquiry schedules. +""" + import itertools import math import random from typing import Any, List, Optional -from bcipy.helpers.list import find_index, swapped -from bcipy.helpers.stimuli import (InquirySchedule, get_fixation, - random_target_positions) +from bcipy.core.list import find_index, swapped +from bcipy.core.stimuli import (InquirySchedule, get_fixation, + random_target_positions) def generate_vep_calibration_inquiries(alp: List[str], @@ -15,30 +21,25 @@ def generate_vep_calibration_inquiries(alp: List[str], inquiry_count: int = 100, num_boxes: int = 4, is_txt: bool = True) -> InquirySchedule: - """ - Generates VEP inquiries with target letters in all possible positions. + """Generate VEP inquiries with target letters in all possible positions. In the VEP paradigm, all stimuli in the alphabet are displayed in each inquiry. The symbols with the highest likelihoods are displayed alone while those with lower likelihoods occur together. - Parameters - ---------- - alp(list[str]): stimuli - timing(list[float]): Task specific timing for generator. - [target, fixation, stimuli] - color(list[str]): Task specific color for generator - [target, fixation, stimuli] - inquiry_count(int): number of inquiries in a calibration - num_boxes(int): number of display boxes - is_txt(bool): whether the stimuli type is text. False would be an image stimuli. - - Return - ------ - schedule_inq(tuple( - samples[list[list[str]]]: list of inquiries - timing(list[list[float]]): list of timings - color(list(list[str])): list of colors)): scheduled inquiries + Args: + alp: List of stimuli. + timing: Task specific timing for generator [target, fixation, stimuli]. + color: Task specific color for generator [target, fixation, stimuli]. + inquiry_count: Number of inquiries in a calibration. + num_boxes: Number of display boxes. + is_txt: Whether the stimuli type is text (False for image stimuli). + + Returns: + InquirySchedule: Schedule containing inquiries, timings, and colors. + + Raises: + AssertionError: If timing list does not contain exactly 3 values. """ if timing is None: timing = [0.5, 1, 2] @@ -64,7 +65,20 @@ def generate_vep_inquiries(symbols: List[str], num_boxes: int = 6, inquiry_count: int = 20, is_txt: bool = True) -> List[List[Any]]: - """Generates inquiries""" + """Generate a list of VEP inquiries. + + Args: + symbols: List of symbols to use in inquiries. + num_boxes: Number of display boxes. + inquiry_count: Number of inquiries to generate. + is_txt: Whether the stimuli type is text. + + Returns: + List[List[Any]]: List of inquiries, where each inquiry contains: + - Target symbol + - Fixation point + - List of symbols for each box + """ fixation = get_fixation(is_txt) target_indices = random_target_positions(inquiry_count, stim_per_inquiry=num_boxes, @@ -86,44 +100,29 @@ def stim_per_box(num_symbols: int, num_boxes: int = 6, max_empty_boxes: int = 0, max_single_sym_boxes: int = 4) -> List[int]: - """Determine the number of stimuli per vep box. - - Parameters - ---------- - num_symbols - number of symbols - num_boxes - number of boxes - max_empty_boxes - the maximum number of boxes which won't have any - symbols within them. - max_single_sym_boxes - maximum number of boxes with a single symbol - - Returns - ------- - A list of length num_boxes, where each number in the list represents - the number of symbols that should be in the box at that position. - - Post conditions: - The sum of the list should equal num_symbols. Further, there should - be at most max_empty_boxes with value of 0 and max_single_sym_boxes - with a value of 1. + """Determine the number of stimuli per VEP box. + + This function distributes symbols across boxes based on rules derived from + example sessions. It ensures a balanced distribution while allowing for + some empty boxes and boxes with single symbols. + + Args: + num_symbols: Number of symbols to distribute. + num_boxes: Number of boxes to distribute symbols across. + max_empty_boxes: Maximum number of boxes that can be empty. + max_single_sym_boxes: Maximum number of boxes that can have a single symbol. + + Returns: + List[int]: List where each number represents the number of symbols + that should be in the box at that position. + + Notes: + - The sum of the returned list equals num_symbols + - There will be at most max_empty_boxes with value 0 + - There will be at most max_single_sym_boxes with value 1 + - Distribution is based on example sessions from: + https://www.youtube.com/watch?v=JNFYSeIIOrw """ - # Logic based off of example sessions from: - # https://www.youtube.com/watch?v=JNFYSeIIOrw - # [[2, 3, 5, 5, 6, 7], - # [2, 1, 10, 1, 1, 13], - # [3, 4, 17, 1, 1, 2], - # [1, 1, 1, 0, 1, 24], - # [1, 2, 1, 22, 1, 1], - # [2, 1, 1, 21, 2, 1], - # [1, 1, 25, 0, 1, 0]] - # and - # [[7, 3, 4, 9, 2, 3], - # 1, 1, 6, 9, 7, 2], - # 1, 2, 18, 2, 3, 2], - # 1, 1, 4, 4, 17, 1], - # 1, 3, 1, 1, 20, 2], - # 1, 1, 1, 20, 3, 2], - # 1, 1, 1, 4, 21, 0]] - if max_empty_boxes + max_single_sym_boxes >= num_boxes: max_empty_boxes = 0 max_single_sym_boxes = num_boxes - 1 @@ -160,26 +159,24 @@ def generate_vep_inquiry(alphabet: List[str], num_boxes: int = 6, target: Optional[str] = None, target_pos: Optional[int] = None) -> List[List[str]]: - """Generates a single random inquiry. - - Parameters - ---------- - alphabet - list of symbols from which to select. - num_boxes - number of display areas; symbols will be partitioned into - these areas. - target - target symbol for the generated inquiry - target_pos - box index that should contain the target - - Returns - ------- - An inquiry represented by a list of lists, where each sublist - represents a display box and contains symbols that should appear in that box. - - Post-conditions: - Symbols will not be repeated and all symbols will be partitioned into - one of the boxes. + """Generate a single random VEP inquiry. + + Args: + alphabet: List of symbols to select from. + num_boxes: Number of display areas to partition symbols into. + target: Target symbol for the inquiry. + target_pos: Box index that should contain the target. + + Returns: + List[List[str]]: List of lists where each sublist represents a display + box and contains symbols that should appear in that box. + + Notes: + - Symbols will not be repeated + - All symbols will be partitioned into one of the boxes + - If target is specified, it will be placed in the lowest count box + greater than 0 """ - box_counts = stim_per_box(num_symbols=len(alphabet), num_boxes=num_boxes) assert len(box_counts) == num_boxes syms = [sym for sym in alphabet] @@ -189,6 +186,7 @@ def generate_vep_inquiry(alphabet: List[str], # Move the target to the front so it gets put in the lowest count box # greater than 0. syms = swapped(syms, index1=0, index2=syms.index(target)) + # Put syms in boxes boxes = [] sym_index = 0 diff --git a/bcipy/task/registry.py b/bcipy/task/registry.py index 36b1bacf2..035b55bbb 100644 --- a/bcipy/task/registry.py +++ b/bcipy/task/registry.py @@ -1,49 +1,108 @@ -"""Task Registry ; used to provide task options to the GUI and command line -tools. User defined tasks can be added to the Registry.""" -from typing import Dict, List, Type +"""Task Registry module for managing BciPy tasks. + +This module provides a registry system for BCI tasks, allowing tasks to be +dynamically discovered and accessed by the GUI and command line tools. +User-defined tasks can be added to the Registry. +""" + +from typing import Dict, List, Type, TypeVar + from bcipy.task import Task +# Type variable for Task subclasses +T = TypeVar('T', bound=Task) + class TaskRegistry: - registry_dict: Dict[str, Type[Task]] + """Registry for managing and accessing BCI tasks. + + This class maintains a registry of all available task types in the system. + It automatically discovers and registers all non-abstract Task subclasses + when initialized, and provides methods for accessing and managing tasks. - def __init__(self): - # Collects all non-abstract subclasses of Task. type ignore is used to work around a mypy bug - # https://github.com/python/mypy/issues/3115 - from bcipy.task.paradigm import vep, rsvp, matrix # noqa + Attributes: + registry_dict: Dictionary mapping task names to task classes. + """ + + def __init__(self) -> None: + """Initialize the task registry. + + Collects all non-abstract subclasses of Task and registers them. + Imports task modules to ensure all tasks are discovered. + """ + # Import task modules to ensure all tasks are discovered from bcipy.task import actions # noqa + from bcipy.task.paradigm import matrix, rsvp, vep # noqa - self.registry_dict = {} + self.registry_dict: Dict[str, Type[Task]] = {} self.collect_subclasses(Task) # type: ignore[type-abstract] - def collect_subclasses(self, cls: Type[Task]): - """Recursively collects all non-abstract subclasses of the given class and adds them to the registry.""" + def collect_subclasses(self, cls: Type[T]) -> None: + """Recursively collect and register non-abstract subclasses. + + Args: + cls: The base class to collect subclasses from. + + Note: + Subclasses are only registered if they have no abstract methods. + """ for sub_class in cls.__subclasses__(): + # Only register non-abstract subclasses if not getattr(sub_class, '__abstractmethods__', False): - self.registry_dict[sub_class.name] = sub_class + if hasattr(sub_class, 'name'): + self.registry_dict[sub_class.name] = sub_class + else: + raise ValueError(f'Task class {sub_class} missing name attribute') self.collect_subclasses(sub_class) def get(self, task_name: str) -> Type[Task]: - """Returns a task type based on its name property.""" + """Get a task class by its name. + + Args: + task_name: Name of the task to retrieve. + + Returns: + Type[Task]: The task class. + + Raises: + ValueError: If the task name is not registered. + """ if task_name in self.registry_dict: return self.registry_dict[task_name] raise ValueError(f'{task_name} not a registered task') def get_all_types(self) -> List[Type[Task]]: - """Returns a list of all registered tasks.""" + """Get all registered task classes. + + Returns: + List[Type[Task]]: List of all registered task classes. + """ return list(self.registry_dict.values()) def list(self) -> List[str]: - """Returns a list of all registered task names.""" + """Get names of all registered tasks. + + Returns: + List[str]: List of registered task names. + """ return list(self.registry_dict.keys()) def calibration_tasks(self) -> List[Type[Task]]: - """Returns a list of all registered calibration tasks.""" + """Get all registered calibration tasks. + + Returns: + List[Type[Task]]: List of registered calibration task classes. + """ from bcipy.task.calibration import BaseCalibrationTask return [task for task in self.get_all_types() if issubclass(task, BaseCalibrationTask)] def register_task(self, task: Type[Task]) -> None: - """Registers a task with the TaskRegistry.""" - # Note that all imported tasks are automatically registered when the TaskRegistry is initialized. This - # method allows for the registration of additional tasks after initialization. + """Register a new task with the registry. + + This method allows registration of additional tasks after initialization. + Tasks imported during initialization are automatically registered. + + Args: + task: The task class to register. + """ self.registry_dict[task.name] = task diff --git a/bcipy/task/tests/core/test_actions.py b/bcipy/task/tests/core/test_actions.py index 185ba8cf3..d4442f4b2 100644 --- a/bcipy/task/tests/core/test_actions.py +++ b/bcipy/task/tests/core/test_actions.py @@ -1,9 +1,12 @@ -import unittest import subprocess +import unittest + +from mockito import mock, unstub, verify, when -from mockito import mock, when, verify, unstub -from bcipy.task import actions, TaskData -from bcipy.task.actions import CodeHookAction, OfflineAnalysisAction, ExperimentFieldCollectionAction +from bcipy.task import TaskData, actions +from bcipy.task.actions import (CodeHookAction, + ExperimentFieldCollectionAction, + OfflineAnalysisAction) class TestActions(unittest.TestCase): @@ -45,7 +48,8 @@ def test_code_hook_action_no_subprocess(self) -> None: def test_offline_analysis_action(self) -> None: cmd_expected = f'bcipy-train -p "{self.parameters_path}"' - when(subprocess).run(cmd_expected, shell=True, check=True).thenReturn(None) + when(subprocess).run(cmd_expected, + shell=True, check=True).thenReturn(None) action = OfflineAnalysisAction( parameters=self.parameters, data_directory=self.data_directory, @@ -57,7 +61,8 @@ def test_offline_analysis_action(self) -> None: def test_experiment_field_collection_action(self) -> None: experiment_id = 'experiment_id' - when(actions).start_experiment_field_collection_gui(experiment_id, self.data_directory).thenReturn(None) + when(actions).start_experiment_field_collection_gui( + experiment_id, self.data_directory).thenReturn(None) action = ExperimentFieldCollectionAction( parameters=self.parameters, data_directory=self.data_directory, @@ -66,7 +71,8 @@ def test_experiment_field_collection_action(self) -> None: task_data = action.execute() self.assertIsNotNone(task_data) self.assertIsInstance(task_data, TaskData) - verify(actions, times=1).start_experiment_field_collection_gui(experiment_id, self.data_directory) + verify(actions, times=1).start_experiment_field_collection_gui( + experiment_id, self.data_directory) if __name__ == '__main__': diff --git a/bcipy/task/tests/core/test_evidence.py b/bcipy/task/tests/core/test_evidence.py index 4f0a994e0..bf18619ca 100644 --- a/bcipy/task/tests/core/test_evidence.py +++ b/bcipy/task/tests/core/test_evidence.py @@ -4,7 +4,8 @@ from unittest.mock import Mock from bcipy.acquisition.multimodal import ContentType -from bcipy.task.control.evidence import (EEGEvaluator, find_matching_evaluator, +from bcipy.task.control.evidence import (EEGEvaluator, SwitchEvaluator, + find_matching_evaluator, get_evaluator) from bcipy.task.data import EvidenceType from bcipy.task.exceptions import MissingEvidenceEvaluator @@ -18,11 +19,10 @@ def test_get_evaluator(self): self.assertEqual(EEGEvaluator, get_evaluator(ContentType.EEG)) self.assertEqual(EEGEvaluator, get_evaluator(ContentType.EEG, EvidenceType.ERP)) + self.assertEqual(SwitchEvaluator, get_evaluator(ContentType.MARKERS)) def test_missing_evaluator(self): """Test error condition when evaluator is missing""" - with self.assertRaises(MissingEvidenceEvaluator): - get_evaluator(ContentType.MARKERS) with self.assertRaises(MissingEvidenceEvaluator): get_evaluator(ContentType.EEG, EvidenceType.EYE) diff --git a/bcipy/task/tests/core/test_handler.py b/bcipy/task/tests/core/test_handler.py index b34914649..020527198 100644 --- a/bcipy/task/tests/core/test_handler.py +++ b/bcipy/task/tests/core/test_handler.py @@ -1,11 +1,15 @@ +import math import unittest + import numpy as np -import math + +from bcipy.core.symbols import alphabet +from bcipy.task.control.criteria import (CriteriaEvaluator, + MaxIterationsCriteria, + MinIterationsCriteria, + ProbThresholdCriteria) from bcipy.task.control.handler import DecisionMaker, EvidenceFusion -from bcipy.task.control.criteria import CriteriaEvaluator, \ - MaxIterationsCriteria, MinIterationsCriteria, ProbThresholdCriteria from bcipy.task.control.query import NBestStimuliAgent -from bcipy.helpers.symbols import alphabet class TestDecisionMaker(unittest.TestCase): @@ -153,7 +157,8 @@ def test_prepare_stimuli(self): len(stimuli[0][0])) for i in range(1, len(stimuli[0][0])): self.assertIn(stimuli[0][0][i], self.decision_maker.alphabet) - self.assertEqual(stimuli[1][0][0:2], self.decision_maker.stimuli_timing) + self.assertEqual(stimuli[1][0][0:2], + self.decision_maker.stimuli_timing) class TestDecisionMakerOld(unittest.TestCase): diff --git a/bcipy/task/tests/core/test_switch_evaluator.py b/bcipy/task/tests/core/test_switch_evaluator.py new file mode 100644 index 000000000..6518667a8 --- /dev/null +++ b/bcipy/task/tests/core/test_switch_evaluator.py @@ -0,0 +1,61 @@ +"""Tests for Switch evidence evaluator""" + +import unittest +from unittest.mock import Mock + +import numpy as np + +from bcipy.core.parameters import Parameters +from bcipy.task.control.evidence import SwitchEvaluator + + +class TestSwitchEvaluator(unittest.TestCase): + """Tests for Switch evidence evaluator.""" + + def setUp(self): + """Setup common state""" + self.symbol_set = [] + + self.device_mock = Mock() + self.device_mock.content_type = 'MARKERS' + self.device_mock.channels = ['Marker'] + self.device_mock.sample_rate = 1 + + self.transform_mock = Mock() + self.signal_model_mock = Mock() + meta_mock = Mock() + meta_mock.device_spec = self.device_mock + meta_mock.transform = self.transform_mock + self.signal_model_mock.metadata = meta_mock + self.signal_model_mock.compute_likelihood_ratio = Mock() + + def test_evaluate(self): + """Test evaluation of evidence""" + parameters = Parameters.from_cast_values( + preview_inquiry_progress_method=1, stim_length=10) + raw_data = np.array([1.0]) + + # Parameters + symbols = ["+", "H", "D", "J", "B", "C", "A", "F", "G", "I", "E"] + times = [ + 0.0, 0.56, 0.81, 1.08, 1.33, 1.58, 1.83, 2.08, 2.33, 2.58, 2.83 + ] + target_info = ['nontarget'] * len(symbols) + window_length = 0.5 + + # Run the code + evaluator = SwitchEvaluator(self.symbol_set, self.signal_model_mock, + parameters) + evaluator.evaluate(raw_data, symbols, times, target_info, + window_length) + + expected_reshaped_data = np.ones((1, 10, 1)) + reshaped = evaluator.preprocess(raw_data, times, target_info, + window_length) + # Assertions + self.assertTrue(np.allclose(expected_reshaped_data, reshaped)) + self.signal_model_mock.compute_likelihood_ratio.assert_called_once() + + +if __name__ == '__main__': + unittest.main() diff --git a/bcipy/task/tests/core/test_task_main.py b/bcipy/task/tests/core/test_task_main.py deleted file mode 100644 index dd3ce22f1..000000000 --- a/bcipy/task/tests/core/test_task_main.py +++ /dev/null @@ -1,57 +0,0 @@ -import unittest -from bcipy.task import Task, TaskData, TaskMode - - -class TestTask(unittest.TestCase): - - def test_task_fails_without_name(self): - mode = TaskMode.CALIBRATION - - class TestTask(Task): - - def execute(self) -> TaskData: - ... - - with self.assertRaises(AssertionError): - TestTask(mode=mode) - - def test_task_fails_without_mode(self): - name = "test task" - - class TestTask(Task): - - def execute(self) -> TaskData: - ... - - with self.assertRaises(AssertionError): - TestTask(name=name) - - def test_task_fails_without_execute(self): - name = "test task" - mode = TaskMode.CALIBRATION - - class TestTask(Task): - pass - - with self.assertRaises(TypeError): - TestTask(name=name, mode=mode) - - def test_task_initializes(self): - name = "test task" - mode = TaskMode.CALIBRATION - - class TestTask(Task): - - def __init__(self, name: str, mode: TaskMode): - self.name = name - self.mode = mode - - def execute(self) -> TaskData: - ... - task = TestTask(name=name, mode=mode) - self.assertEqual(task.name, name) - self.assertEqual(task.mode, mode) - - -if __name__ == '__main__': - unittest.main() diff --git a/bcipy/task/tests/orchestrator/test_orchestrator.py b/bcipy/task/tests/orchestrator/test_orchestrator.py index f2805a849..3e14699e7 100644 --- a/bcipy/task/tests/orchestrator/test_orchestrator.py +++ b/bcipy/task/tests/orchestrator/test_orchestrator.py @@ -1,12 +1,14 @@ -import unittest -import logging import json +import logging +import unittest + from mock import mock_open -from mockito import any, mock, when, unstub, verify -from bcipy.task.orchestrator import SessionOrchestrator -from bcipy.task import Task, TaskData +from mockito import any, mock, unstub, verify, when + from bcipy.config import DEFAULT_PARAMETERS_PATH -from bcipy.helpers.load import load_json_parameters +from bcipy.io.load import load_json_parameters +from bcipy.task import Task, TaskData +from bcipy.task.orchestrator import SessionOrchestrator class TestSessionOrchestrator(unittest.TestCase): @@ -25,8 +27,10 @@ def test_orchestrator_add_task(self) -> None: task = mock(spec=Task) task.name = "test task" task.mode = "test mode" - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn() - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn() + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) orchestrator = SessionOrchestrator() self.assertTrue(orchestrator.tasks == []) orchestrator.add_task(task) @@ -43,8 +47,10 @@ def test_orchestrator_add_tasks(self) -> None: task2.name = "test task" task2.mode = "test mode" tasks = [task1, task2] - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn() - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn() + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) orchestrator = SessionOrchestrator() self.assertTrue(orchestrator.tasks == []) orchestrator.add_tasks(tasks) @@ -61,8 +67,10 @@ def test_orchestrator_execute(self) -> None: task.name = "test task" task.mode = "test mode" task.execute = lambda: TaskData() - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn() - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn() + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) when(SessionOrchestrator)._init_task_save_folder(any()).thenReturn() when(SessionOrchestrator)._init_task_logger(any()).thenReturn() when(SessionOrchestrator)._save_data().thenReturn() @@ -103,12 +111,15 @@ def test_orchestrator_execute(self) -> None: @mock_open(read_data='{"Phrases": []}') def test_orchestrator_multiple_copyphrases_loads_from_parameters_when_set(self, mock_file): - parameters = load_json_parameters(self.parameter_location, value_cast=True) + parameters = load_json_parameters( + self.parameter_location, value_cast=True) copy_phrase_location = "bcipy/parameters/experiments/phrases.json" parameters['copy_phrases_location'] = copy_phrase_location mock_copy_phrases = {"Phrases": [["test", 0], ["test2", 1]]} - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn() - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn() + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) when(SessionOrchestrator)._init_task_save_folder(any()).thenReturn() when(SessionOrchestrator)._init_task_logger(any()).thenReturn() when(SessionOrchestrator)._save_data().thenReturn() @@ -116,30 +127,35 @@ def test_orchestrator_multiple_copyphrases_loads_from_parameters_when_set(self, orchestrator = SessionOrchestrator(parameters=parameters) - self.assertEqual(orchestrator.copyphrases, mock_copy_phrases['Phrases']) + self.assertEqual(orchestrator.copyphrases, + mock_copy_phrases['Phrases']) verify(json, times=1).load(mock_file) def test_orchestrator_save_data_multiple_copyphrases_saves_remaining_phrases(self): - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn() - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn() + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) when(SessionOrchestrator)._init_task_save_folder(any()).thenReturn() when(SessionOrchestrator)._init_task_logger(any()).thenReturn() - when(SessionOrchestrator)._save_procotol_data().thenReturn() + when(SessionOrchestrator)._save_protocol_data().thenReturn() when(SessionOrchestrator)._save_copy_phrases().thenReturn() orchestrator = SessionOrchestrator() orchestrator.copyphrases = [["test", 0], ["test2", 1]] orchestrator._save_data() - verify(SessionOrchestrator, times=1)._save_procotol_data() + verify(SessionOrchestrator, times=1)._save_protocol_data() verify(SessionOrchestrator, times=1)._save_copy_phrases() def test_orchestrator_next_phrase(self): - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn() - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn() + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) when(SessionOrchestrator)._init_task_save_folder(any()).thenReturn() when(SessionOrchestrator)._init_task_logger(any()).thenReturn() - when(SessionOrchestrator)._save_procotol_data().thenReturn() + when(SessionOrchestrator)._save_protocol_data().thenReturn() when(SessionOrchestrator).initialize_copy_phrases().thenReturn() orchestrator = SessionOrchestrator() diff --git a/bcipy/task/tests/orchestrator/test_protocol.py b/bcipy/task/tests/orchestrator/test_protocol.py index 1ea8750fe..b2f65f686 100644 --- a/bcipy/task/tests/orchestrator/test_protocol.py +++ b/bcipy/task/tests/orchestrator/test_protocol.py @@ -1,7 +1,11 @@ import unittest -from bcipy.task.orchestrator.protocol import parse_protocol, serialize_protocol, validate_protocol_string + from bcipy.task.actions import OfflineAnalysisAction -from bcipy.task.paradigm.rsvp.calibration.calibration import RSVPCalibrationTask +from bcipy.task.orchestrator.protocol import (parse_protocol, + serialize_protocol, + validate_protocol_string) +from bcipy.task.paradigm.rsvp.calibration.calibration import \ + RSVPCalibrationTask from bcipy.task.paradigm.rsvp.copy_phrase import RSVPCopyPhraseTask @@ -67,6 +71,7 @@ def test_serializes_one_task(self) -> None: assert serialized == RSVPCalibrationTask.name def test_serializes_multiple_tasks(self) -> None: - sequence = [RSVPCalibrationTask, OfflineAnalysisAction, RSVPCopyPhraseTask] + sequence = [RSVPCalibrationTask, + OfflineAnalysisAction, RSVPCopyPhraseTask] serialized = serialize_protocol(sequence) assert serialized == 'RSVP Calibration -> OfflineAnalysisAction -> RSVP Copy Phrase' diff --git a/bcipy/task/tests/paradigm/matrix/test_matrix_calibration.py b/bcipy/task/tests/paradigm/matrix/test_matrix_calibration.py index 1e4c9b073..49027271e 100644 --- a/bcipy/task/tests/paradigm/matrix/test_matrix_calibration.py +++ b/bcipy/task/tests/paradigm/matrix/test_matrix_calibration.py @@ -9,9 +9,9 @@ from bcipy.acquisition import LslAcquisitionClient from bcipy.acquisition.devices import DeviceSpec from bcipy.acquisition.multimodal import ContentType +from bcipy.core.parameters import Parameters +from bcipy.core.triggers import TriggerHandler, TriggerType from bcipy.display.paradigm.matrix import MatrixDisplay -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.triggers import TriggerHandler, TriggerType from bcipy.task.paradigm.matrix.calibration import MatrixCalibrationTask diff --git a/bcipy/task/tests/paradigm/rsvp/calibration/test_rsvp_calibration.py b/bcipy/task/tests/paradigm/rsvp/calibration/test_rsvp_calibration.py index 2ab8fc9dd..87523e0ea 100644 --- a/bcipy/task/tests/paradigm/rsvp/calibration/test_rsvp_calibration.py +++ b/bcipy/task/tests/paradigm/rsvp/calibration/test_rsvp_calibration.py @@ -9,8 +9,8 @@ from bcipy.acquisition import LslAcquisitionClient from bcipy.acquisition.devices import DeviceSpec from bcipy.acquisition.multimodal import ContentType -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.triggers import TriggerHandler, TriggerType +from bcipy.core.parameters import Parameters +from bcipy.core.triggers import TriggerHandler, TriggerType from bcipy.task.paradigm.rsvp.calibration.calibration import \ RSVPCalibrationTask @@ -400,7 +400,8 @@ def test_cleanup(self, save_session_mock, trigger_handler_mock): (self.daq, self.servers, self.win)) # Mock the default cleanup - when(bcipy.task.calibration.BaseCalibrationTask).write_offset_trigger().thenReturn(None) + when(bcipy.task.calibration.BaseCalibrationTask).write_offset_trigger( + ).thenReturn(None) when(bcipy.task.calibration.BaseCalibrationTask).exit_display().thenReturn(None) when(bcipy.task.calibration.BaseCalibrationTask).wait().thenReturn(None) @@ -421,8 +422,10 @@ def test_cleanup(self, save_session_mock, trigger_handler_mock): verify(self.daq, times=1).cleanup() verify(self.servers[0], times=1).stop() verify(self.win, times=1).close() - verify(bcipy.task.calibration.BaseCalibrationTask, times=1).setup(any(), any(), any()) - verify(bcipy.task.calibration.BaseCalibrationTask, times=1).write_offset_trigger() + verify(bcipy.task.calibration.BaseCalibrationTask, + times=1).setup(any(), any(), any()) + verify(bcipy.task.calibration.BaseCalibrationTask, + times=1).write_offset_trigger() verify(bcipy.task.calibration.BaseCalibrationTask, times=1).exit_display() verify(bcipy.task.calibration.BaseCalibrationTask, times=1).wait() diff --git a/bcipy/task/tests/paradigm/rsvp/test_copy_phrase.py b/bcipy/task/tests/paradigm/rsvp/test_copy_phrase.py index d5465fe29..2e2f86145 100644 --- a/bcipy/task/tests/paradigm/rsvp/test_copy_phrase.py +++ b/bcipy/task/tests/paradigm/rsvp/test_copy_phrase.py @@ -13,11 +13,11 @@ from bcipy.acquisition.devices import DeviceSpec from bcipy.acquisition.multimodal import ContentType from bcipy.config import DEFAULT_ENCODING +from bcipy.core.parameters import Parameters +from bcipy.core.stimuli import InquirySchedule +from bcipy.core.triggers import TriggerHandler from bcipy.exceptions import TaskConfigurationException from bcipy.helpers.copy_phrase_wrapper import CopyPhraseWrapper -from bcipy.helpers.parameters import Parameters -from bcipy.helpers.stimuli import InquirySchedule -from bcipy.helpers.triggers import TriggerHandler from bcipy.task.data import EvidenceType, Session from bcipy.task.paradigm.rsvp.copy_phrase import RSVPCopyPhraseTask @@ -111,7 +111,8 @@ def setUp(self): } }) self.servers = [mock()] - when(self.daq).get_client(ContentType.EEG).thenReturn(self.eeg_client_mock) + when(self.daq).get_client( + ContentType.EEG).thenReturn(self.eeg_client_mock) self.temp_dir = tempfile.mkdtemp() self.model_metadata = mock({ 'device_spec': device_spec, @@ -464,7 +465,8 @@ def test_execute_fake_data_with_preview(self, process_data_mock, message_mock, # Assertions verify(self.copy_phrase_wrapper, times=2).initialize_series() verify(self.display, times=1).do_inquiry() - verify(self.copy_phrase_wrapper, times=1).add_evidence(EvidenceType.BTN, ...) + verify(self.copy_phrase_wrapper, times=1).add_evidence( + EvidenceType.BTN, ...) self.assertEqual(self.temp_dir, result.save_path) @patch('bcipy.task.paradigm.rsvp.copy_phrase.init_evidence_evaluator') @@ -655,7 +657,8 @@ def test_btn_evidence_with_preview_only(self): when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).setup(any(), any(), any()).thenReturn( (self.daq, self.servers, self.win)) self.parameters['show_preview_inquiry'] = True - self.parameters['preview_inquiry_progress_method'] = 0 # ButtonPressMode.NOTHING.value + # ButtonPressMode.NOTHING.value + self.parameters['preview_inquiry_progress_method'] = 0 task = RSVPCopyPhraseTask( parameters=self.parameters, @@ -693,10 +696,14 @@ def test_cleanup(self): (self.daq, self.servers, self.win)) # Mock the default cleanup - when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).write_offset_trigger().thenReturn(None) - when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).exit_display().thenReturn(None) - when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).save_session_data().thenReturn(None) - when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).wait().thenReturn(None) + when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).write_offset_trigger( + ).thenReturn(None) + when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).exit_display( + ).thenReturn(None) + when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).save_session_data( + ).thenReturn(None) + when(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask).wait( + ).thenReturn(None) # Mock the initialized cleanup when(self.daq).stop_acquisition().thenReturn(None) @@ -716,9 +723,12 @@ def test_cleanup(self): verify(self.daq, times=1).cleanup() verify(self.servers[0], times=1).stop() verify(self.win, times=1).close() - verify(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask, times=1).setup(any(), any(), any()) - verify(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask, times=1).write_offset_trigger() - verify(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask, times=1).exit_display() + verify(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask, + times=1).setup(any(), any(), any()) + verify(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask, + times=1).write_offset_trigger() + verify(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask, + times=1).exit_display() verify(bcipy.task.paradigm.rsvp.copy_phrase.RSVPCopyPhraseTask, times=1).wait() diff --git a/bcipy/task/tests/paradigm/rsvp/test_copy_phrase_task_summary.py b/bcipy/task/tests/paradigm/rsvp/test_copy_phrase_task_summary.py index a98840db8..87573239d 100644 --- a/bcipy/task/tests/paradigm/rsvp/test_copy_phrase_task_summary.py +++ b/bcipy/task/tests/paradigm/rsvp/test_copy_phrase_task_summary.py @@ -4,7 +4,7 @@ from mock import patch -from bcipy.helpers.triggers import Trigger +from bcipy.core.triggers import Trigger from bcipy.task.data import EvidenceType, Inquiry, Session from bcipy.task.paradigm.rsvp.copy_phrase import TaskSummary diff --git a/bcipy/task/tests/paradigm/vep/test_stimuli_vep.py b/bcipy/task/tests/paradigm/vep/test_stimuli_vep.py index b7f4d5170..f2d292b40 100644 --- a/bcipy/task/tests/paradigm/vep/test_stimuli_vep.py +++ b/bcipy/task/tests/paradigm/vep/test_stimuli_vep.py @@ -1,6 +1,6 @@ import unittest -from bcipy.helpers.symbols import alphabet +from bcipy.core.symbols import alphabet from bcipy.task.paradigm.vep.stim_generation import ( generate_vep_calibration_inquiries, generate_vep_inquiry, stim_per_box) diff --git a/bcipy/tests/test_bci_main.py b/bcipy/tests/test_bci_main.py index 76edfa019..348cd8332 100644 --- a/bcipy/tests/test_bci_main.py +++ b/bcipy/tests/test_bci_main.py @@ -42,7 +42,8 @@ def test_bci_main_fails_without_experiment_or_task(self) -> None: ) def test_bcipy_main_fails_with_invalid_experiment(self) -> None: - when(main).validate_bcipy_session(any(), any()).thenRaise(UnregisteredExperimentException) + when(main).validate_bcipy_session(any(), any()).thenRaise( + UnregisteredExperimentException) with self.assertRaises(UnregisteredExperimentException): bci_main( parameter_location=self.parameters_path, @@ -54,13 +55,16 @@ def test_bcipy_main_fails_with_invalid_experiment(self) -> None: ) def test_bci_main_runs_with_valid_experiment(self) -> None: - when(main).validate_bcipy_session(any(), any()).thenReturn(True) # Mock the validate_bcipy_session function + when(main).validate_bcipy_session(any(), any()).thenReturn( + True) # Mock the validate_bcipy_session function when(main).load_json_parameters( any(), value_cast=any()).thenReturn( self.parameters) # Mock the load_json_parameters function when(SessionOrchestrator).get_system_info().thenReturn(None) - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn(None) - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn(None) + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) when(SessionOrchestrator).initialize_copy_phrases().thenReturn(None) when(SessionOrchestrator).add_tasks(any()).thenReturn(None) when(SessionOrchestrator).execute().thenReturn(None) @@ -83,10 +87,13 @@ def test_bci_main_runs_with_valid_experiment(self) -> None: def test_bci_main_runs_with_valid_task(self) -> None: when(main).validate_bcipy_session(any(), any()).thenReturn(True) - when(main).load_json_parameters(any(), value_cast=any()).thenReturn(self.parameters) + when(main).load_json_parameters( + any(), value_cast=any()).thenReturn(self.parameters) when(SessionOrchestrator).get_system_info().thenReturn(None) - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn(None) - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn(None) + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) when(SessionOrchestrator).initialize_copy_phrases().thenReturn(None) when(SessionOrchestrator).add_tasks(any()).thenReturn(None) when(SessionOrchestrator).execute().thenReturn(None) @@ -110,10 +117,13 @@ def test_bci_main_runs_with_valid_task(self) -> None: def test_bci_main_returns_false_with_orchestrator_execute_exception(self): when(main).validate_bcipy_session(any(), any()).thenReturn(True) - when(main).load_json_parameters(any(), value_cast=any()).thenReturn(self.parameters) + when(main).load_json_parameters( + any(), value_cast=any()).thenReturn(self.parameters) when(SessionOrchestrator).get_system_info().thenReturn(None) - when(SessionOrchestrator)._init_orchestrator_save_folder(any()).thenReturn(None) - when(SessionOrchestrator)._init_orchestrator_logger(any()).thenReturn(self.logger) + when(SessionOrchestrator)._init_orchestrator_save_folder( + any()).thenReturn(None) + when(SessionOrchestrator)._init_orchestrator_logger( + any()).thenReturn(self.logger) when(SessionOrchestrator).initialize_copy_phrases().thenReturn(None) when(SessionOrchestrator).add_tasks(any()).thenReturn(None) when(SessionOrchestrator).execute().thenRaise(Exception) diff --git a/bcipy/tests/test_preferences.py b/bcipy/tests/test_preferences.py index f526d570c..967ac0000 100644 --- a/bcipy/tests/test_preferences.py +++ b/bcipy/tests/test_preferences.py @@ -1,8 +1,9 @@ """Tests for the Preferences""" -import unittest import shutil import tempfile +import unittest from pathlib import Path + from bcipy.preferences import Preferences diff --git a/dev_requirements.txt b/dev_requirements.txt deleted file mode 100644 index 2ee6263fc..000000000 --- a/dev_requirements.txt +++ /dev/null @@ -1,12 +0,0 @@ -autopep8==1.6.0 -coverage>=6.0 -flake8==5.0.4 -mypy==1.6.1 -lxml -mock -mockito -pylint -pytest -pytest-mpl -wheel -twine==3.2.0 \ No newline at end of file diff --git a/mypy.ini b/mypy.ini deleted file mode 100644 index 8015d10e0..000000000 --- a/mypy.ini +++ /dev/null @@ -1,11 +0,0 @@ -# Global options: -[mypy] -warn_return_any = False -warn_unused_configs = False -ignore_missing_imports = True -follow_imports = skip -strict_optional = True -disallow_incomplete_defs = False -check_untyped_defs = True -no_implicit_optional = True -exclude = tests|demo|gui|scripts|acquisition|display.paradigm|language|signal.model|task.control|helpers.parameters diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 000000000..c7c9cd050 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,205 @@ +[build-system] +build-backend = "setuptools.build_meta" +requires = ["setuptools>=61.0", "wheel>=0.37.1"] + +[project] +name = "bcipy" +version = "2.0.0" +authors = [ + {name="CAMBI", email="cambi_support@googlegroups.com"}, +] +description = "Python Software for Brain-Computer Interface Development." +readme = "README.md" +requires-python = ">3.8,<3.11" +classifiers = [ + 'License :: Other/Proprietary License', + 'Topic :: Scientific/Engineering :: Human Machine Interfaces', + 'Intended Audience :: Science/Research', + 'Intended Audience :: End Users/Desktop', + 'Intended Audience :: Developers', + 'Programming Language :: Python', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', +] + +dependencies = [ + "textslinger~=0.1.1", + "attrdict3==2.0.2", + "EDFlib-Python==1.0.8", + "torch==2.2.0", + "construct==2.8.14", + "mne==1.6.1", + "mne-bids==0.14.0", + "pyobjc==7.3;platform_system=='Darwin'", + "pybv==0.7.5", + "pyo==1.0.5", + "pyglet<=1.5.27,>=1.4", + "PsychoPy==2024.2.1", + "openpyxl==3.1.2", + "numpy==1.24.4", + "sounddevice==0.4.4", + "SoundFile==0.12.1", + "scipy==1.10.1", + "scikit-learn==1.2.2", + "seaborn==0.13.2", + "matplotlib==3.7.5", + "pylsl==1.16.2", + "pandas==2.0.3", + "psutil==5.7.2", + "Pillow==10.2.0", + "py-cpuinfo==9.0.0", + "pyopengl==3.1.7", + "PyQt6==6.7.1", + "PyQt6-sip==13.8", + "pywavelets==1.4.1", + "tqdm==4.62.2", + "rich==13.9.4", + "reportlab==4.2.0", + "tables==3.7.0", + "pyWinhook==1.6.2;python_version=='3.9' and platform_system=='Windows'", + "WxPython==4.2.1;platform_system!='Linux'", +] + +[project.license] +file = "LICENSE.md" + +[project.optional-dependencies] +dev = [ + "autopep8==1.5.7", + "coverage>=7.0", + "flake8==5.0.4", + "Flake8-pyproject==1.2.3", + "flake8-docstrings==1.7.0", + "mypy==1.13", + "lxml", + "mock", + "mockito", + "pylint", + "pytest", + "pytest-mpl", +] +release = [ + "twine==3.2.0", + "build==1.2.2.post1", + "pyinstaller==6.13.0", + "wheel==0.43.0", +] + +[project.scripts] +bcipy = "bcipy.main:bcipy_main" +bcipy-erp-viz = "bcipy.helpers.visualization:erp" +bcipy-replay = "bcipy.simulator.task.replay_session:main" +bcipy-sim = "bcipy.simulator:main" +bcipy-train = "bcipy.signal.model.offline_analysis:main" +bcipy-params = "bcipy.gui.parameters.params_form:main" + +[project.urls] +"Homepage" = "https://www.cambi.tech/" +"Documentation" = "https://bcipy.github.io/" +"Source" = "https://github.com/CAMBI-tech/BciPy" + +[tool.setuptools] +# https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html +platforms = ["Linux", "Windows", "Mac OS-X"] +include-package-data = true +zip-safe = true + +# Python modules and packages that are included in the +# distribution package (and therefore become importable) +[tool.setuptools.packages.find] +exclude = ["tests", "demo", "scripts"] + +[tool.distutils.bdist_wheel] +universal = true + +[tool.coverage.run] +omit = [ + "*__init__*", + "*__main__*", + "*usr/local/lib*", + "*tests*", + "*test*", + "*demo*", + "*exceptions.py", + "*visualization.py", + "*/gui/*", + "*/simulator/ui/*" +] +source = ["bcipy"] +branch = true + +[tool.coverage.report] +exclude_also = [ + "pragma: no cover", + "def __repr__", + "def __str__", + "raise NotImplementedError", + "@abstract", + "if __name__ == .__main__.:", + "logging.getLogger(__name__)", + "raise AssertionError", + "@(abc\\.)?abstractmethod", + "pass", +] + + +[tool.flake8] + +max_complexity = 10 +max_line_length = 120 +application_import_names = "bcipy" + +ignore = [ + "D100", + "D105", + "D107", + "D202", + "D204", + "D205", + "D400", + "D401", + "D403", + "D412", + "F841", + "F821", + "E402", + "E501", + "C901", + "W503", + "W504", +] +exclude = [ + "tests", + "__init__.py", + "demo", + "signal", # TODO: Remove when fixed + "gui", +] + +[tool.isort] +skip = [".gitignore"] + +[tool.pytest.ini] +markers = "slow" + +[tool.mypy] + +warn_return_any = false +warn_unused_configs = false +ignore_missing_imports = true +follow_imports = "skip" +strict_optional = true +disallow_incomplete_defs = false +check_untyped_defs = true +no_implicit_optional = true +exclude = [ + "tests", + "demo", + "gui", + "scripts", + "acquisition", + "display.paradigm", + "signal.model", + "task.control", + "core.parameters", +] diff --git a/pytest.ini b/pytest.ini deleted file mode 100644 index 95697f21b..000000000 --- a/pytest.ini +++ /dev/null @@ -1,3 +0,0 @@ -[pytest] -markers = - slow: marks tests as slow (deselect with '-m "not slow"') \ No newline at end of file diff --git a/requirements-winmac.txt b/requirements-winmac.txt deleted file mode 100644 index 36616d5f4..000000000 --- a/requirements-winmac.txt +++ /dev/null @@ -1 +0,0 @@ -WxPython==4.2.1 diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index b6c87fecc..000000000 --- a/requirements.txt +++ /dev/null @@ -1,28 +0,0 @@ -attrdict3==2.0.2 -transformers==4.26.0 -torch==2.0.0 -construct==2.8.14 -mne==1.6.1 -pyo==1.0.5 -pyglet<=1.5.27,>=1.4 -PsychoPy==2024.2.1 -openpyxl==3.1.2 -numpy==1.24.4 -sounddevice==0.4.4 -SoundFile==0.12.1 -scipy==1.10.1 -scikit-learn==1.2.2 -seaborn==0.9.0 -matplotlib==3.7.5 -pylsl==1.16.2 -pandas==2.0.3 -psutil==5.7.2 -Pillow==9.4.0 -py-cpuinfo==9.0.0 -pyedflib==0.1.34 -pyopengl==3.1.7 -PyQt6==6.7.1 -pywavelets==1.4.1 -tqdm==4.62.2 -reportlab==4.2.0 -tables==3.7.0 \ No newline at end of file diff --git a/scripts/python/lm_eval.py b/scripts/python/lm_eval.py deleted file mode 100644 index bc377f7b6..000000000 --- a/scripts/python/lm_eval.py +++ /dev/null @@ -1,214 +0,0 @@ -from bcipy.language.model.kenlm import KenLMLanguageModel -from bcipy.language.model.mixture import MixtureLanguageModel -from bcipy.language.model.unigram import UnigramLanguageModel -from bcipy.language.model.causal import CausalLanguageModel -from bcipy.language.main import ResponseType -from math import log10 -from timeit import default_timer as timer -from bcipy.helpers.symbols import SPACE_CHAR, alphabet -import argparse -import numpy as np -import sys - -if __name__ == "__main__": - - parser = argparse.ArgumentParser() - parser.add_argument('--verbose', dest='verbose', type=int, required=True, - help=('0: Only output model averages\n1: Output results from each phrase\n2: ' - 'Output results from each character')) - - parser.add_argument('--model', dest='model', type=int, required=True, - help=('1: Unigram\n2: Mixture (80/20 Causal GPT-2/Unigram)\n3: ' - 'KenLM n-gram\n4: Causal Hugging Face')) - - parser.add_argument('--phrases', dest='phrases', type=str, required=True, - help='Phrase set filename') - - parser.add_argument('--model-name', dest='model_name') - parser.add_argument('--model-dir', - dest='model_dir', - help="Local directory to load fine-tuned causal model") - parser.add_argument("--use-mps", - action="store_true", - help="Use MPS Apple Silicon GPU during inference") - parser.add_argument("--use-cuda", - action="store_true", - help="Use CUDA GPU during inference") - parser.add_argument("--left-context", help="left language model context for causal model", default="") - - args = parser.parse_args() - - verbose = args.verbose - model = args.model - phrases = args.phrases - - if model == 3 and not args.model_dir: - print("ERROR: For KenLM n-gram model you must specify filename of model using --model-dir") - sys.exit(1) - - if model == 4 and not args.model_name: - print("ERROR: For causal model you must specify name of model using --model-name") - sys.exit(1) - - # Allow passing in of space characters in the context using word - args.left_context = args.left_context.replace("", " ") - - device = "cpu" - if args.use_mps: - device = "mps" - elif args.use_cuda: - device = "cuda" - - # Read in the phrase file - phrase_file = open(phrases, "r") - phrases = phrase_file.readlines() - phrase_file.close() - - lm = None - - start = timer() - - symbol_set = alphabet() - response_type = ResponseType.SYMBOL - if model == 1: - lm = UnigramLanguageModel(response_type, symbol_set) - elif model == 2: - lm = MixtureLanguageModel(response_type, symbol_set) - elif model == 3: - lm = KenLMLanguageModel(response_type, symbol_set, args.model_dir) - elif model == 4: - lm = CausalLanguageModel(response_type=response_type, - symbol_set=symbol_set, - lang_model_name=args.model_name, - lm_device=device, - lm_path=args.model_dir, - lm_left_context=args.left_context) - else: - parser.print_help() - exit() - - print(f"Model load time = {timer() - start:.6f}") - - phrase_count = 0 - sum_per_symbol_logprob = 0.0 - zero_prob = 0 - overall_predict_time_arr = np.array([]) - overall_predict_details_arr = np.array([]) - - start = timer() - - # Iterate over phrases - for phrase in phrases: - sentence = phrase.strip() - if len(sentence) > 0: - accum = 0.0 - - # Phrase-level output - if verbose >= 1: - print(f"sentence = '{sentence}'") - - # Split into characters - tokens = sentence.split() - symbols = len(tokens) - - # Initial previous token is the start symbol, initial context empty - prev_token = "" - context = "" - - predict_time_arr = np.array([]) - predict_details_arr = np.array([]) - - # Iterate over characters in phrase - for (i, token) in enumerate(tokens): - start_predict = timer() - correct_char = "" - - # BciPy treats space as underscore - if (token == ""): - token = SPACE_CHAR - correct_char = SPACE_CHAR - else: - correct_char = token.upper() - score = 0.0 - next_char_pred = lm.state_update(list(context)) - - predict_time = timer() - start_predict - predict_time_arr = np.append(predict_time_arr, predict_time) - predict_details_arr = np.append(predict_details_arr, - f"sentence = {sentence}, index = {i}, p( {token} | {prev_token} )") - - # Find the probability for the correct character - p = next_char_pred[[c[0] for c in next_char_pred].index(correct_char)][1] - if p == 0: - zero_prob += 1 - accum = 1 - if verbose >= 2: - print(f"p( {token} | {prev_token} ...) = 0") - print(f"prediction time = {predict_time:.6f}") - break - else: - score = log10(p) - - # Character-level output - if verbose >= 2: - print(f"p( {token} | {prev_token} ...) = {p:.6f} [ {score:.6f} ]") - print(f"prediction time = {predict_time:.6f}") - accum += score - prev_token = token - context += token - - # Compute summary stats on prediction times for this phrase - per_symbol_time = np.average(predict_time_arr) - phrase_std = np.std(predict_time_arr) - phrase_max = np.max(predict_time_arr) - phrase_min = np.min(predict_time_arr) - - # Add this phrase's prediction times to overall array - overall_predict_time_arr = np.append(overall_predict_time_arr, predict_time_arr, axis=None) - overall_predict_details_arr = np.append(overall_predict_details_arr, predict_details_arr, axis=None) - - if accum == 1: - if verbose >= 1: - print("Zero-prob event encountered, terminating phrase") - print(f"per-symbol prediction time = {per_symbol_time:.6f} +/- {phrase_std:.6f} [{phrase_min:.6f}, " - f"{phrase_max:.6f}]\n") - else: - per_symbol_logprob = accum / symbols - - # Phrase-level output - if verbose >= 1: - print(f"sum logprob = {accum:.4f}, per-symbol logprob = {per_symbol_logprob:.4f}, " - f"ppl = {pow(10,-1 * per_symbol_logprob):.4f}") - print(f"per-symbol prediction time = {per_symbol_time:.6f} +/- {phrase_std:.6f} " - f"[{phrase_min:.6f}, {phrase_max:.6f}]\n") - - sum_per_symbol_logprob += per_symbol_logprob - phrase_count += 1 - - average_per_symbol_logprob = sum_per_symbol_logprob / phrase_count - - overall_per_symbol_time = np.average(overall_predict_time_arr) - overall_std_time = np.std(overall_predict_time_arr) - overall_min_time = np.min(overall_predict_time_arr) - overall_max_time = np.max(overall_predict_time_arr) - - ci_floor = overall_per_symbol_time - (3 * overall_std_time) - ci_ceiling = overall_per_symbol_time + (3 * overall_std_time) - - # Model-level output - print(f"OVERALL \ - \nphrases = {phrase_count}, \ - \naverage per symbol logprob = {average_per_symbol_logprob:.4f}, \ - \nppl = {pow(10,-1 * average_per_symbol_logprob):.4f}, \ - \nzero-prob events = {zero_prob} \ - \nper-symbol prediction time = {overall_per_symbol_time:.6f} +/- {overall_std_time:.6f} \ - [{overall_min_time:.6f}, {overall_max_time:.6f}] \ - \n95% CI = [{ci_floor}, {ci_ceiling}]\n") - - print(f"Inference time = {timer() - start:.6f}") - - for (i, time) in enumerate(overall_predict_time_arr): - if time < ci_floor: - print(f"LOW OUTLIER: {overall_predict_details_arr[i]}, predict time = {time:.6f}\n") - if time > ci_ceiling: - print(f"HIGH OUTLIER: {overall_predict_details_arr[i]}, predict time = {time:.6f}\n") diff --git a/scripts/python/lsl_buffer_test.py b/scripts/python/lsl_buffer_test.py deleted file mode 100644 index 426b9137d..000000000 --- a/scripts/python/lsl_buffer_test.py +++ /dev/null @@ -1,92 +0,0 @@ -"""Example to demonstrate behavior when the StreamInlet max_buflen is exceeded. - -Prior to running, start a data streamer, such as the SendData.py example -script included in pylsl. - -Example usage: -$ python3 lsl_buffer_test.py --buffer=1 --seconds=2 -""" - -import time - -from pylsl import StreamInlet, resolve_stream - - -def pull_all_data(inlet: StreamInlet, max_samples: int) -> None: - """Pull all buffered data in the given stream inlet.""" - - print("\nPulling buffered data:") - count = pull_chunk(inlet, max_samples) - while count == max_samples: - count = pull_chunk(inlet, max_samples) - - -def pull_chunk(inlet: StreamInlet, max_samples: int) -> int: - """Pull a chunk of samples from a stream inlet. - Returns the count of samples pulled.""" - - _chunk, timestamps = inlet.pull_chunk(timeout=0.0, max_samples=max_samples) - count = len(timestamps) - - time_range = "" - if timestamps: - time_range = f"{round(timestamps[0], 3)} to {round(timestamps[-1], 3)}" - - print(f"-> pulled {count} samples: {time_range};", - f"sorted: {timestamps == sorted(timestamps)}") - - return count - - -def main(max_buflen: int, max_samples: int, sleep_seconds: int) -> None: - """Continuously read from a StreamInlet, pausing for a given time between - reads and then consuming all data in the stream. - - Parameters - ---------- - max_buflen - StreamInlet max_buflen; buffer size in seconds - max_samples - maximum samples to pull in a single chunk - sleep_seconds - seconds to sleep between data pulls - """ - - # first resolve an EEG stream on the lab network - print("looking for an EEG stream...") - streams = resolve_stream('type', 'EEG') - - # create a new inlet to read from the stream - print("\n---") - print(f"max_buflen seconds: {max_buflen}") - print(f"max_samples: {max_samples}") - print(f"sleep_seconds: {sleep_seconds}") - print("---") - inlet = StreamInlet(streams[0], max_buflen=max_buflen) - - while True: - # pull all available samples - pull_all_data(inlet, max_samples) - time.sleep(sleep_seconds) - - -if __name__ == '__main__': - import argparse - - parser = argparse.ArgumentParser() - parser.add_argument('-b', - '--buffer', - help='StreamInlet max_buflen (seconds)', - default=360, - type=int) - parser.add_argument('-c', - '--chunk', - help='Maximum samples per chunk', - default=1024, - type=int) - parser.add_argument('-s', - '--seconds', - help='Seconds to sleep between data pulls', - default=2, - type=int) - args = parser.parse_args() - main(max_buflen=args.buffer, - max_samples=args.chunk, - sleep_seconds=args.seconds) diff --git a/scripts/python/mixture_tuning.py b/scripts/python/mixture_tuning.py deleted file mode 100644 index e8e5e172f..000000000 --- a/scripts/python/mixture_tuning.py +++ /dev/null @@ -1,77 +0,0 @@ -import argparse -from itertools import permutations -import numpy as np -from math import log10 - -if __name__ == "__main__": - parser = argparse.ArgumentParser() - parser.add_argument('--step', dest='step', type=int, required=True, - help='The number of weight steps to be used in the sweep search') - - parser.add_argument('--in', dest='files', type=str, required=True, nargs='+', - help="Two or more paths pointing to output files from the lm_eval script with --verbose 2") - - args = parser.parse_args() - - step = 1.0 / args.step - possible_weights = np.round(list(np.arange(0, 1.0 + step, step)), 5) - perms = list(permutations(possible_weights, len(args.files))) - - weights = [perm for perm in perms if (np.sum(perm) == 1)] - - files = [] - for f in args.files: - files.append(open(f, 'r')) - - lines = [] - for f in files: - lines.append(f.readlines()) - f.close() - - probs = [] - sentence_pslp_arr = [] - for line in zip(*lines): - if line[0].startswith("sentence = "): - for elm in line: - if not elm.startswith("sentence = "): - print("Line mismatch. Please ensure all files were run on the same phrase set.") - exit() - probs = [] - elif line[0].startswith("p( "): - for elm in line: - if not elm.startswith("p( "): - print("Line mismatch. Please ensure all files were run on the same phrase set.") - exit() - if elm[-5:] == " = 0\n": - print("Error: Component model zero prob.") - exit() - component_probs = [] - mixed_probs = [] - for elm in line: - component_probs.append(float(elm[elm.index("=") + 2:elm.index("[") - 1])) - for weight in weights: - mixed_probs.append(np.dot(weight, component_probs)) - probs.append(mixed_probs) - elif line[0].startswith("sum logprob = "): - for elm in line: - if not elm.startswith("sum logprob = "): - print("Line mismatch. Please ensure all files were run on the same phrase set.") - exit() - logprobs = [] - for prob in probs: - log_list = [log10(i) for i in prob] - logprobs.append(log_list) - sentence_pslp_arr.append([np.average(w) for w in zip(*logprobs)]) - elif line[0].startswith("OVERALL"): - for elm in line: - if not elm.startswith("OVERALL"): - print("Line mismatch. Please ensure all files were run on the same phrase set.") - exit() - - overall_ppl_arr = [pow(10, -1 * np.average(w)) for w in zip(*sentence_pslp_arr)] - print("Weight Distribution\tAverage Char Perplexity") - for weight, ppl in zip(weights, overall_ppl_arr): - print(f"{weight}\t\t{ppl:.3f}") - - print(f"\nBEST: {weights[np.argmin(overall_ppl_arr)]} {np.min(overall_ppl_arr):.3f}") - break diff --git a/scripts/python/replay_session.py b/scripts/python/replay_session.py deleted file mode 100644 index 053f4abd2..000000000 --- a/scripts/python/replay_session.py +++ /dev/null @@ -1,364 +0,0 @@ -"""Script that will replay sessions and allow us to simulate new model predictions on that data.""" -import json -import logging as logger -import pickle -from pathlib import Path -from typing import Tuple - -import matplotlib.pyplot as plt -import numpy as np -import pandas as pd -import seaborn as sns - -import bcipy.acquisition.devices as devices -from bcipy.config import (DEFAULT_DEVICE_SPEC_FILENAME, - DEFAULT_PARAMETERS_FILENAME, RAW_DATA_FILENAME, - SESSION_DATA_FILENAME, TRIGGER_FILENAME) -from bcipy.helpers.acquisition import analysis_channels -from bcipy.helpers.list import grouper -from bcipy.helpers.load import load_json_parameters, load_raw_data -from bcipy.helpers.stimuli import InquiryReshaper, update_inquiry_timing -from bcipy.helpers.symbols import alphabet -from bcipy.helpers.triggers import TriggerType, trigger_decoder -from bcipy.signal.model import PcaRdaKdeModel, SignalModel -from bcipy.signal.process import (ERPTransformParams, filter_inquiries, - get_default_transform) - -logger.getLogger().setLevel(logger.INFO) - - -def load_model(model_path: Path, k_folds: int, model_class=PcaRdaKdeModel): - """Load the model at the given path""" - with open(model_path, "rb") as f: - model = pickle.load(f) - return model - - -def generate_replay_outputs( - data_folder, - parameters, - model_path: Path, - model_class=PcaRdaKdeModel, - symbol_set=alphabet(), - write_output=False) -> Tuple[dict, list, list]: - """Replay a session and generate outputs for the provided model. - - Parameters - ---------- - data_folder: Path - Path to the data folder containing the session data (session.json, raw_data.csv, triggers.txt) - parameters: dict - Parameters to use for the replay session. - model_path: Path - Path to the model to use for the replay session. - model_class: class - Class of the model to use for the replay session. By default, this is PcaRdaKdeModel. - symbol_set: list - List of symbols to use for the replay session. By default, this is the alphabet. - write_output: bool - Whether or not to write the output to a file. By default, this is False. - - Returns - ------- - tuple - new_model_outputs, old_model_target_output, old_model_nontarget_output - """ - k_folds = parameters.get("k_folds") - model: SignalModel = load_model(model_path, k_folds, model_class) - logger.info(f"Loaded model from {model_path}") - - # get trial information; to make backwards compatible, we will try to get the trial length - # from the parameters file (old), but if it's not there, we use the trial window and adjust timing (>2.0). - adjust_trials_by_window = False - trial_length = parameters.get("trial_length", None) - if trial_length is None: - trial_window = parameters.get("trial_window") - trial_length = trial_window[1] - trial_window[0] - adjust_trials_by_window = True - logger.info(f"Trial Window: {trial_window[0]}-{trial_window[1]}s") - - trials_per_inquiry = parameters.get("stim_length") - prestim_length = parameters.get("prestim_length", trial_length) - buffer_length = int(parameters.get("task_buffer_length") / 2) - - # get signal filtering information - static_offset = parameters.get("static_trigger_offset") - k_folds = parameters.get("k_folds") - transform_params = parameters.instantiate(ERPTransformParams) - downsample_rate = transform_params.down_sampling_rate - - logger.info( - f"\nData processing settings: \n" - f"{str(transform_params)} \n" - f"Trial Length: {trial_length}s, Trials per Inquiry: {trials_per_inquiry} \n" - f"Prestimulus Buffer: {prestim_length}s, Poststimulus Buffer: {buffer_length}s \n" - f"Static offset: {static_offset}" - ) - - data_list = load_raw_data(data_folder, [f"{RAW_DATA_FILENAME}.csv"]) - # NOTE: With the current inputs this function only loads the EEG data. Update needed for eyetracker data. - raw_data = data_list[0] - channels = raw_data.channels - type_amp = raw_data.daq_type - sample_rate = raw_data.sample_rate - devices.load(Path(data_folder, DEFAULT_DEVICE_SPEC_FILENAME)) - device_spec = devices.preconfigured_device(raw_data.daq_type) - channel_map = analysis_channels(channels, device_spec) - - # extract the raw data for the channels we care about. The channel map will further reduce this if necessary. - # by default, only the sample number and internal trigger channels are excluded. - raw_data, _ = raw_data.by_channel() - - logger.info(f"Device type: {type_amp}") - logger.info(f"Channels read from csv: {channels}") - channels_used = [channels[i] for i, keep in enumerate(channel_map) if keep == 1] - logger.info(f'Channels used in analysis: {channels_used}') - - trigger_targetness, trigger_timing, trigger_symbols = trigger_decoder( - offset=static_offset, - trigger_path=f"{data_folder}/{TRIGGER_FILENAME}", - exclusion=[TriggerType.PREVIEW, TriggerType.EVENT], - ) - - # Adjust trigger timing by trial window if necessary - if adjust_trials_by_window: - trigger_timing = [timing + trial_window[0] for timing in trigger_timing] - - inquiries, inquiry_labels, inquiry_timing = InquiryReshaper()( - trial_targetness_label=trigger_targetness, - timing_info=trigger_timing, - eeg_data=raw_data, - sample_rate=sample_rate, - trials_per_inquiry=trials_per_inquiry, - channel_map=channel_map, - poststimulus_length=trial_length, - prestimulus_length=prestim_length, - transformation_buffer=buffer_length, - ) - - default_transform = get_default_transform( - sample_rate_hz=sample_rate, - notch_freq_hz=transform_params.notch_filter_frequency, - bandpass_low=transform_params.filter_low, - bandpass_high=transform_params.filter_high, - bandpass_order=transform_params.filter_order, - downsample_factor=transform_params.down_sampling_rate, - ) - - inquiries, transformed_sample_rate = filter_inquiries(inquiries, default_transform, sample_rate) - trial_duration_samples = int(trial_length * transformed_sample_rate) - inquiry_timing = update_inquiry_timing(inquiry_timing, downsample_rate) - trials = InquiryReshaper.extract_trials(inquiries, trial_duration_samples, inquiry_timing) - - # get the model outputs using the reshaped data - outputs = {} - inquiry_worth_of_trials = np.split(trials, inquiries.shape[1], 1) - inquiry_worth_of_letters = grouper(trigger_symbols, trials_per_inquiry, incomplete="ignore") - for i, (inquiry_trials, this_inquiry_letters, this_inquiry_labels) in enumerate( - zip(inquiry_worth_of_trials, inquiry_worth_of_letters, inquiry_labels) - ): - response = model.compute_likelihood_ratio(inquiry_trials, this_inquiry_letters, symbol_set=symbol_set) - if np.any(this_inquiry_labels == 1): - index_of_target_trial = np.argwhere(this_inquiry_labels == 1)[0][0] - target_letter = this_inquiry_letters[index_of_target_trial] - target_index_in_alphabet = symbol_set.index(target_letter) - - nontarget_idx_in_alphabet = [symbol_set.index(q) for q in this_inquiry_letters if q != target_letter] - else: - target_index_in_alphabet = None - nontarget_idx_in_alphabet = [symbol_set.index(q) for q in this_inquiry_letters] - - outputs[i] = { - "eeg_evidence": list(response), - "target_idx": target_index_in_alphabet, - "nontarget_idx": nontarget_idx_in_alphabet, - } - - if write_output: - with open(data_folder / "replay_outputs.json", "w") as f: - json.dump(outputs, f, indent=2) - - # Get values computed during actual experiment from session.json for comparison - session_json = data_folder / SESSION_DATA_FILENAME - all_target_eeg, all_nontarget_eeg = load_eeg_evidence_from_session_json(session_json, symbol_set) - - return outputs, all_target_eeg, all_nontarget_eeg - - -def load_eeg_evidence_from_session_json(session_json, symbol_set) -> Tuple[list, list]: - """Load EEG evidence from session.json file for comparison with replay outputs. - - Parameters - ---------- - session_json : str - Path to session.json file - symbol_set : list - List of symbols used in experiment - - Returns - ------- - all_target_eeg : list - List of EEG evidence for target stimuli - all_nontarget_eeg : list - List of EEG evidence for nontarget stimuli - """ - with open(session_json, "r") as f: - contents = json.load(f) - series = contents["series"] - - all_target_eeg = [] - all_nontarget_eeg = [] - - for inquiries in series.values(): - for inquiry in inquiries.values(): - if len(inquiry["eeg_evidence"]) < 1: - continue - else: - stim_label = inquiry["stimuli"][0] # name of symbols presented - stim_label.pop(0) # remove fixation cross - stim_indices = [symbol_set.index(sym) for sym in stim_label] - targetness = inquiry["target_info"] # targetness of stimuli - targetness.pop(0) # remove fixation cross - target = [index for index, label in zip(stim_indices, targetness) if label == "target"] - nontarget = [index for index, label in zip(stim_indices, targetness) if label == "nontarget"] - all_target_eeg.extend([inquiry["eeg_evidence"][pos] for pos in target]) - all_nontarget_eeg.extend([inquiry["eeg_evidence"][pos] for pos in nontarget]) - - return all_target_eeg, all_nontarget_eeg - - -def plot_collected_outputs( - outputs_with_new_model: dict, - targets_with_old_model: list, - nontargets_with_old_model: list, - outdir: str) -> None: - """Plot collected outputs from replay experiment. - - Parameters - ---------- - outputs_with_new_model : dict - List of outputs from replay experiment using new model - targets_with_old_model : list - List of outputs from the session data using old model for target stimuli - nontargets_with_old_model : list - List of outputs from the session using old model for nontarget stimuli - outdir : str - Path to directory to save plots - """ - records = [] - for output in outputs_with_new_model: # each session - for _, inquiry_contents in output.items(): # each inquiry - target_idx = inquiry_contents["target_idx"] - if target_idx is not None: - records.append( - { - "which_model": "new_target", - "response_value": inquiry_contents["eeg_evidence"][target_idx], - } - ) - - nontarget_idx = inquiry_contents["nontarget_idx"] - for i in nontarget_idx: - records.append({"which_model": "new_nontarget", "response_value": inquiry_contents["eeg_evidence"][i]}) - - for target_response in targets_with_old_model: - records.append({"which_model": "old_target", "response_value": target_response}) - for nontarget_response in nontargets_with_old_model: - records.append({"which_model": "old_nontarget", "response_value": nontarget_response}) - - df = pd.DataFrame.from_records(records) - logger.info(f"{df.describe()}") - ax = sns.stripplot( - x="which_model", - y="response_value", - data=df, - order=["old_target", "new_target", "old_nontarget", "new_nontarget"], - ) - sns.boxplot( - showmeans=True, - meanline=True, - meanprops={"color": "k", "ls": "-", "lw": 2}, - medianprops={"visible": False}, - whiskerprops={"visible": False}, - zorder=10, - x="which_model", - y="response_value", - data=df, - showfliers=False, - showbox=False, - showcaps=False, - ax=ax, - order=["old_target", "new_target", "old_nontarget", "new_nontarget"], - ) - - ax.set(yscale="log") - plt.savefig(outdir / "response_values.stripplot.png", dpi=150, bbox_inches="tight") - plt.close() - ax = sns.boxplot( - x="which_model", - y="response_value", - data=df, - order=["old_target", "new_target", "old_nontarget", "new_nontarget"], - ) - ax.set(yscale="log") - plt.savefig(outdir / "response_values.boxplot.png", dpi=150, bbox_inches="tight") - - -if __name__ == "__main__": - import argparse - - parser = argparse.ArgumentParser() - parser.add_argument( - "-d", - "--data_folders", - action="append", - type=Path, - required=True, - help="Session data folders to be processed. This argument can be repeated to accumulate sessions data.") - parser.add_argument("-m", "--model_file", required=True) - parser.add_argument("-o", "--outdir", type=Path, default=None) - parser.add_argument( - "-p", - "--parameter_file", - type=Path, - default=None, - help="Parameter file to be used for replay. If none, the session parameter file will be used.") - - args = parser.parse_args() - - assert len(set(args.data_folders)) == len(args.data_folders), "Duplicated data folders" - - if args.outdir is None: - args.outdir = Path(__file__).resolve().parent - - logger.info(f"Outdir: {args.outdir}") - - outputs_with_new_model = [] - targets_with_old_model = [] - nontargets_with_old_model = [] - for data_folder in args.data_folders: - logger.info(f"Processing {data_folder}") - - if args.parameter_file is not None: - params_file = args.parameter_file - else: - params_file = Path(data_folder, DEFAULT_PARAMETERS_FILENAME) - logger.info(f"Loading params from {params_file}") - params = load_json_parameters(params_file, value_cast=True) - - # Generate replay outputs using the model provided against the session data in data_folder - outputs, all_target_eeg, all_nontarget_eeg = generate_replay_outputs( - data_folder, params, args.model_file, write_output=False - ) - outputs_with_new_model.append(outputs) - targets_with_old_model.extend(all_target_eeg) - nontargets_with_old_model.extend(all_nontarget_eeg) - - plot_collected_outputs( - outputs_with_new_model, - targets_with_old_model, - nontargets_with_old_model, - args.outdir) - - # breakpoint() - - logger.info("Replay complete.") \ No newline at end of file diff --git a/scripts/python/update_params.py b/scripts/python/update_params.py new file mode 100644 index 000000000..a3b74d288 --- /dev/null +++ b/scripts/python/update_params.py @@ -0,0 +1,68 @@ +"""Update parameters files to latest.""" + +import json +import shutil +from pathlib import Path + +from bcipy.core.parameters import DEFAULT_PARAMETERS_PATH, Parameters + + +def update(params_path: str) -> None: + """Update the parameters at the given path""" + default_params = Parameters(DEFAULT_PARAMETERS_PATH, cast_values=True) + + # open as json, not Parameters, to avoid validation checks + with open(params_path, 'r', encoding='utf8') as json_file: + params = json.load(json_file) + + # rename attributes if needed + mapping = {"readableName": "name", "recommended_values": "recommended"} + + updated_params = {} + for key, entry in params.items(): + editable = False + if key in default_params: + editable = default_params.get_entry(key)['editable'] + value = {mapping.get(k, k): v for k, v in entry.items()} + + if "editable" not in value: + value["editable"] = editable + updated_params[key] = value + + # overwrite json file if needed + original_path = Path(params_path) + shutil.copyfile(original_path, + Path(original_path.parent, "parameters_original.json")) + + with open(params_path, 'w', encoding='utf8') as json_path: + json.dump(updated_params, json_path, ensure_ascii=False, indent=2) + + # load from overwritten file + parameters = Parameters(source=params_path, cast_values=True) + + added_params = [ + key for key, change in default_params.diff(parameters).items() + if change.original_value is None + ] + + if added_params: + print( + f"Adding missing parameters using default values: {added_params}") + parameters.add_missing_items(default_params) + + parameters.save() + + +if __name__ == "__main__": + from bcipy.io.load import load_experimental_data + # load experimental directory. This will have users/run/data + data_dir = Path(load_experimental_data()) + + # loop over all the users + for user in data_dir.iterdir(): + if user.is_dir(): + for run in user.iterdir(): + if run.is_dir(): + for file in run.iterdir(): + if file.name == "parameters.json": + update(str(file)) diff --git a/scripts/shell/connect_dsi.sh b/scripts/shell/connect_dsi.sh deleted file mode 100644 index 01a7a3a32..000000000 --- a/scripts/shell/connect_dsi.sh +++ /dev/null @@ -1,27 +0,0 @@ -#!/bin/bash -###### Connect DSI LSL. ####### -# Make sure DSI cap is on and paired via bluetooth or connection to a port. -# You can locate what port is paired to the device in the Device Manager in Windows. -# Change directory to the location of the DSI App - -sname_prompt="Select the DSI headset type:" -options=("DSI" "DSI_VR300") -echo "DSI headset types" -PS3="$sname_prompt " -select opt in "${options[@]}"; do -case $REPLY in -1 ) sname="$opt"; break;; -2 ) sname="$opt"; break;; -*) echo "Invalid option. Try another one (Ctrl+C to exit)."; continue;; -esac -done - -read -p "Enter a COM port [COM3]: " com -com=${com:-COM3} - -read -rsp $"Press Enter to Connect to $sname" -printf "\nStarting connection to $sname on $com.. Press Ctrl+C to end session." -eval "./dsi2lsl.exe --lsl-stream-name=$sname --port=$com" - -read -rsp $"Error. Please address messages above. Press enter to exit." -printf "disconnected" diff --git a/scripts/shell/linux_requirements.sh b/scripts/shell/linux_requirements.sh index 661347507..5ac9dec6e 100755 --- a/scripts/shell/linux_requirements.sh +++ b/scripts/shell/linux_requirements.sh @@ -21,5 +21,4 @@ sudo apt-get install xvfb # sudo apt-get install python3.9-tk python3.9-dev # run headless without a display connected. All commands must have xvfb-run preceeding them. -# ex. $ xvfb-run pytest -# sudo apt-get install xvfb \ No newline at end of file +# ex. $ xvfb-run pytest \ No newline at end of file diff --git a/scripts/shell/m2chip_install.sh b/scripts/shell/m2chip_install.sh index 6b8977099..8edbb5747 100644 --- a/scripts/shell/m2chip_install.sh +++ b/scripts/shell/m2chip_install.sh @@ -23,10 +23,3 @@ brew install hdf5 brew install portaudio # also make sure the path is correct/exported in .zprofile or .bash_profile export HDF5_DIR=/opt/homebrew/opt/hdf5 -# portaudio installation for soundfile and pyo -python -m pip install pyaudio -# your path may be different to the portaudio version -pip install --global-option='build_ext' --global-option='-I/usr/local/Cellar/portaudio/19.7.0/include' --global-option='-L/usr/local/Cellar/portaudio/19.7.0/lib' pyo -pip install Psychopy==2024.2.1 --no-deps # install psychopy without dependencies -pip install -e . -pip install kenlm==0.1 --global-option="--max_order=12" # install kenlm with max_order=12 for language model. Not required for BciPy to run in most places. \ No newline at end of file diff --git a/setup.cfg b/setup.cfg deleted file mode 100644 index 162e9c4e5..000000000 --- a/setup.cfg +++ /dev/null @@ -1,20 +0,0 @@ -# Flake8 Configuration - -[flake8] - -max_complexity = 10 - -max_line_length = 120 - -application_import_names = bcipy - -ignore = - - # Ignoring D205, F841, F821, and D400 because of false positives - - D205, D400, F841, F821, E402, C901 - - # Ignoring W503, W504 : line break before binary operator, line break after - # binary operator - - W503, W504 diff --git a/setup.py b/setup.py deleted file mode 100644 index 33cddd581..000000000 --- a/setup.py +++ /dev/null @@ -1,136 +0,0 @@ -"""Setup for bcipy package. - -Installation: - To install locally, run: - pip install -e . - To install as a package, run: - python setup.py install - To create a distribution, run: - python setup.py sdist bdist_wheel - -Release: - *credentials required* - PyPi: https://pypi.org/project/bcipy/ - GitHub: https://github.com/CAMBI-tech/BciPy - To upload to PyPi and create git tags, run: - python setup.py upload -""" - -import os -import platform -import sys -from shutil import rmtree - -from setuptools import Command, find_packages, setup - -# Package meta-data. -NAME = 'bcipy' -DESCRIPTION = 'Python Software for Brain-Computer Interface.' -URL = 'https://github.com/CAMBI-tech/BciPy' -EMAIL = 'cambi_support@googlegroups.com' -AUTHOR = 'CAMBI' -REQUIRES_PYTHON = '>3.7,<3.11' - -VERSION = '2.0.1rc4' - -REQUIRED = [] - -# What packages are required for this module to be executed? -if platform.system() == 'Windows' or platform.system() == 'Darwin': - with open('requirements-winmac.txt', 'r', encoding='utf-8') as f: - REQUIRED += f.read().splitlines() -with open('requirements.txt', 'r', encoding='utf-8') as f: - REQUIRED += f.read().splitlines() - -here = os.path.abspath(os.path.dirname(__file__)) - -long_description = 'Python Brain-Computer Interface Software' - -about = {'__version__': VERSION} - - -class UploadCommand(Command): - """Support setup.py upload. - - Modified from https://github.com/kennethreitz/setup.py - """ - - description = 'Build and publish the package.' - user_options = [] - - @staticmethod - def status(s): - """Prints things in bold.""" - print('\033[1m{0}\033[0m'.format(s)) - - def initialize_options(self): - pass - - def finalize_options(self): - pass - - def run(self): - try: - self.status('Removing previous builds…') - rmtree(os.path.join(here, 'dist')) - except OSError: - pass - - self.status('Building Source and Wheel (universal) distribution…') - os.system('{0} setup.py sdist bdist_wheel --universal'.format(sys.executable)) - - self.status('Uploading the package to PyPi via Twine…') - os.system('twine upload dist/*') - - self.status('Pushing git tags…') - os.system('git tag v{0}'.format(about['__version__'])) - os.system('git push --tags') - - sys.exit() - - -# Where the magic happens: -setup( - name=NAME, - version=about['__version__'], - description=DESCRIPTION, - long_description=long_description, - long_description_content_type='text/markdown', - author=AUTHOR, - author_email=EMAIL, - python_requires=REQUIRES_PYTHON, - url=URL, - packages=find_packages(exclude=( - 'tests', - 'demo', - 'data', - )), - entry_points={ - 'console_scripts': [ - 'bcipy = bcipy.main:bcipy_main', - 'bcipy-erp-viz = bcipy.helpers.visualization:erp', - 'bcipy-sim = bcipy.simulator:main', - 'bcipy-train = bcipy.signal.model.offline_analysis:main', - 'bcipy-params = bcipy.gui.parameters.params_form:main' - ], - }, - install_requires=REQUIRED, - include_package_data=True, - license='Hippocratic License 2.1', - classifiers=[ - # Trove classifiers - # Full list: https://pypi.python.org/pypi?%3Aaction=list_classifiers - 'License :: Other/Proprietary License', - 'Topic :: Scientific/Engineering :: Human Machine Interfaces', - 'Intended Audience :: Science/Research', - 'Intended Audience :: End Users/Desktop', - 'Intended Audience :: Developers', - 'Programming Language :: Python', - 'Programming Language :: Python :: 3.8', - 'Programming Language :: Python :: 3.9', - ], - # $ setup.py publish support. - cmdclass={ - 'upload': UploadCommand, - }, -)