Metadata-Version: 2.1
Name: pyntbci
Version: 1.3.1
Summary: Python Noise-Tagging Brain-Computer Interface (PyntBCI)
Home-page: https://gitlab.socsci.ru.nl/jthielen/pyntbci
Author: Jordy Thielen
Author-email: jordy.thielen@donders.ru.nl
License: BSD-3-Clause
Keywords: bci,classification,cvep,c-vep,eeg
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: h5py >=3.10.0
Requires-Dist: matplotlib >=3.7.0
Requires-Dist: mne >=1.4.0
Requires-Dist: numpy >=1.24.0
Requires-Dist: scikit-learn >=1.3.0
Requires-Dist: scipy >=1.10.0
Requires-Dist: seaborn >=0.13.0
Requires-Dist: setuptools >=57.0.0

# PyntBCI

The Python Noise-Tagging Brain-Computer interface (PyntBCI) library is a Python toolbox for the noise-tagging brain-computer interfacing (BCI) project developed at the Donders Institute for Brain, Cognition and Behaviour, Radboud University, Nijmegen, the Netherlands. PyntBCI contains various signal processing steps and machine learning algorithms for BCIs that make use of evoked responses of the electroencephalogram (EEG), specifically code-modulated responses such as the code-modulated visual evoked potential (c-VEP). For a constructive review of this field, see:

* Martínez-Cagigal, V., Thielen, J., Santamaría-Vázquez, E., Pérez-Velasco, S., Desain, P., & Hornero, R. (2021). Brain–computer interfaces based on code-modulated visual evoked potentials (c-VEP): a literature review. Journal of Neural Engineering. DOI: [10.1088/1741-2552/ac38cf](https://doi.org/10.1088/1741-2552/ac38cf)

## Installation

To install PyntBCI, use:

	pip install pyntbci

## Getting started

Various tutorials and example analysis pipelines are provided in the `tutorials/` and `examples/` folder, which operate on limited preprocessed data as provided with PyntBCI. Furthermore, please find various pipelines for several open-access datasets below in the `pipelines/` folder.

## Referencing

When using PyntBCI, please reference at least one of the following:

* Thielen, J., van den Broek, P., Farquhar, J., & Desain, P. (2015). Broad-Band visually evoked potentials: re(con)volution in brain-computer interfacing. PLOS ONE, 10(7), e0133797. DOI: [10.1371/journal.pone.0133797](https://doi.org/10.1371/journal.pone.0133797)
* Thielen, J., Marsman, P., Farquhar, J., & Desain, P. (2021). From full calibration to zero training for a code-modulated visual evoked potentials for brain–computer interface. Journal of Neural Engineering, 18(5), 056007. DOI: [10.1088/1741-2552/abecef](https://doi.org/10.1088/1741-2552/abecef)

## Contact

* Jordy Thielen (jordy.thielen@donders.ru.nl)

## Licensing

PyntBCI is licensed by the BSD 3-Clause License:

Copyright (c) 2021, Jordy Thielen All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
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.
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.

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.

# Changelog

## Version 1.3.1

### Added

### Changed

### Fixed
- Fixed zero division `eventplot` in `plotting`
- Fixed event order duration event `event_matrix` in `utilities` 

## Version 1.3.0

### Added
- Removed `gating` of `rCCA` in `classifiers`
- Removed `_score` methods in `classifiers`
- Added `n_components` in `eCCA` in `classifiers`
- Added `n_components` in `eTRCA` in `classifiers`

### Changed
- Changed "bes" to "bds" in `BayesStopping` in `stopping` in line with publication
- Changed `lx` and `ly` to `gamma_x` and `gamma_y` iof `eCCA` in `classifiers`
- Changed `gating` to `gates`
- Changed `TRCA` in `transformers` to deal with one-class data only
- Changed `_get_T` to `get_T` in all `classifiers`

### Fixed

## Version 1.2.0 (18-04-2024)

### Added

### Changed

- Changed `lx` of `rCCA` in `classifiers` to `gamma_x`, which ranges between 0-1, such that the parameter represents shrinkage regularization
- Changed `ly` of `rCCA` in `classifiers` to `gamma_m`, which ranges between 0-1, such that the parameter represents shrinkage regularization
- Changed `lx` of `CCA` in `transformers` to `gamma_x`, which ranges between 0-1, such that the parameter represents shrinkage regularization
- Changed `ly` of `CCA` in `transformers` to `gamma_y`, which ranges between 0-1, such that the parameter represents shrinkage regularization

### Fixed

## Version 1.1.0 (17-04-2024)

### Added

- Added `envelope` module containing `envelope_gammatone` and `envelope_rms` functions
- Added `CriterionStopping` to `stopping` for some static stopping methods 

### Changed

- Changed default value of `encoding_length` in `rCCA` of `classifiers` of 0.3 to None, which is equivalent to 1 / fs

### Fixed

- Fixed variable `fs` of type np.ndarray instead of int in examples, tutorials, and pipelines 
- Fixed double call to `decoding_matrix` in `fit` of `rCCA` in `classifiers`

## Version 1.0.1 (26-03-2024)

### Added

- Added `set_stimulus_amplitudes` for `rCCA` in `classifiers`

### Changed

### Fixed

- Fixed dependency between `stimulus` and `amplitudes` in `rCCA` of `classifiers`

## Version 1.0.0 (22-03-2024)

### Added

- Added variable `decoding_length` of `rCCA` in `classifier` controlling the length of a learned spectral filter
- Added variable `decoding_stride` of `rCCA` in `classifier` controlling the stride of a learned spectral filter
- Added function `decoding_matrix` in `utilities` to phase-shit the EEG data maintaining channel-prime ordering
- Added variable `encoding_stride` of `rCCA` in `classifier` controlling the stride of a learned temporal response
- Added module `gating` with gating functions, for instance for multi-component or filterbank analysis
- Added variable `gating` of `rCCA` in `classifier` to deal with multiple CCA components
- Added variable `gating` of `Ensemble` in `classifier`, for example to deal with a filterbank

### Changed

- Changed variable `codes` of `rCCA` in `classifiers` to `stimulus`
- Changed variable `transient_size` of `rCCA` in `classifiers` to `encoding_length`
- Changed class `FilterBank` in `classifiers` to `Ensemble`
- Changed function `structure_matrix` in `utilities` to `encoding_matrix`

### Fixed

- Fixed several documentation issues

## Version 0.2.5 (29-02-2024)

### Added

- Added function `eventplot` in `plotting` to visualize an event matrix
- Added variable `running` of `covariance` in `utilities` to do incremental running covariance updates
- Added variable `running` of `CCA` in `transformers` to use a running covariance for CCA 
- Added variable `cov_estimator_x` and `cov_estimator_m` of `rCCA` in `classifiers` to change the covariance estimator 
- Added event definitions "on", "off" and "onoff" for `event_matrix` in `utilities`

### Changed

- Changed the CCA optimization to contain separate computations for Cxx, Cyy and Cxy
- Changed the CCA to allow separate BaseEstimators for Cxx and Cyy

### Fixed

- Fixed zero-division in `itr` in `utilities` 

## Version 0.2.4

### Added

- Added CCA cumulative/incremental average and covariance
- Added `amplitudes` (e.g. envelopes) in `structure_matrix` of `utilities`
- Added `max_time` to classes in `stopping` to allow a maximum stopping time for stopping methods
- Added brainamp64.loc to capfiles
- Added plt.show() in all examples

### Changed

### Fixed

## Version 0.2.3

### Added

### Changed

- Changed example pipelines to include more examples and explanation
- Changed tutorial pipelines to include more examples and explanation

### Fixed

- Fixed several documentation issues

## Version 0.2.2

### Added

- Added class `TRCA` to `transformers`
- Added class `eTRCA` to `classifiers`
- Added parameter `ensemble` to classes in `classifiers` to allow a separate spatial filter per class

### Changed

- Changed package name from PyNT to PyntBCI to avoid clash with existing pynt library
- Changed filter order in `filterbank` of `utilities` to be optimized given input parameters

### Fixed

- Fixed issue in `rCCA` of `classifiers` causing novel events in structure matrix when "cutting cycles"
- Fixed `correlation` to not contain mutable input variables

## Version 0.2.1

### Added

- Added `tests`
- Added tutorials

### Changed

- Changed `rCCA` to work with non-binary events instead of binary only

### Fixed

## Version 0.2.0

### Added

- Added dynamic stopping: classes `MarginStopping`, `BetaStopping`, and `BayesStopping` in module `stopping`
- Added value inner for variable `score_metric` in 'classifiers'

### Changed

- Changed all data shapes from (channels, samples, trials) to (trials, channels, samples)
- Changed all codes shapes from (samples, classes) to (classes, samples)
- Changed all decision functions to similarity, not distance (e.g., Euclidean), to always maximize

### Fixed

- Fixed zero-mean templates in `eCCA` and `rCCA` of `classifiers`

## Version 0.1.0

### Added

- Added `Filterbank` to `classifiers`

### Changed

- Changed classifiers all have `predict` and `decision_function` methods in `classifiers`

### Fixed

## Version 0.0.2

### Added

### Changed

- Changed CCA method from sklearn to custom covariance method

### Fixed

## Version 0.0.1

### Added

- Added `eCCA` template metrics: average, median, OCSVM
- Added `eCCA` spatial filter options: all channels or subset

### Changed

### Fixed

## Version 0.0.0

### Added

- Added `CCA` in `transformers`
- Added `rCCA` in `classifiers`
- Added `eCCA` in `classifier`

### Changed

### Fixed
