pyntbci 1.8.0

Python Noise-Tagging Brain-Computer Interface (PyntBCI)

PyntBCI

The Python Noise-Tagging Brain-Computer Interfacing (PyntBCI) library is a specialized Python toolbox developed for the noise-tagging brain-computer interfacing (BCI) project at the Donders Institute for Brain, Cognition, and Behaviour at Radboud University in Nijmegen, the Netherlands. PyntBCI offers a suite of signal processing tools and machine learning algorithms tailored for BCIs using evoked responses, such as those recorded by electroencephalography (EEG). It is particularly focused on supporting code-modulated responses like the code-modulated visual evoked potential (c-VEP).

For detailed documentation as wel as tutorials and examples, see:

• https://thijor.github.io/pyntbci/

For a constructive review of the c-VEP BCI 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

For an extensive literature overview, also see:

• https://github.com/thijor/cvep-literature.

For an example of an online BCI with PyntBCI, see our Dareplane implementation:

• https://github.com/thijor/dp-cvep
• https://github.com/thijor/dp-cvep-speller
• https://github.com/thijor/dp-cvep-decoder

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
• 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

Contact

• Jordy Thielen ([e-mail])

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.8.0 (08-11-2024)

Added

• Added min_time to stopping methods in stopping
• Added max_time to CriterionStopping in stopping

Changed

Fixed

• Fixed fit exception in DistributionStopping in stopping

Version 1.7.0 (22-10-2024)

Added

• Added tmin to encoding_matrix in utilities
• Added tmin to rCCA in classifiers

Changed

Fixed

Version 1.6.1 (10-10-2024)

Added

• Added find_neighbours and find_worst_neighbour to utilities
• Added optimize_subset_clustering to stimulus
• Added optimize_layout_incremental to stimulus
• Added stimplot to plotting

Changed

• Changed order of tutorials and examples

Fixed

• Fixed max_time in all stopping classes to deal with "partial" segments

Version 1.5.0 (30-09-2024)

Added

• Added ValueStopping to stopping
• Added parameter distribution to DistributionStopping in stopping

Changed

• Changed envelope_rms to rms in envelope
• Changed envelope_gammatone to gammatone in envelope
• Changed BetaStopping in stopping to DistributionStopping

Fixed

• Fixed default CCA in transformers to inv, not pinv
• Fixed seed for make_m_sequence and make_gold_codes in stimulus to not be full zeros

Version 1.4.1 (19-07-2024)

Added

Changed

Fixed

• Fixed default CCA in transformers to inv, not pinv

Version 1.4.0 (15-07-2024)

Added

• Added pinv to utilities
• Added alpha_x to CCA in tranformers
• Added alpha_y to CCA in tranformers
• Added alpha_x to eCCA in classifiers
• Added alpha_t to eCCA in classifiers
• Added alpha_x to rCCA in classifiers
• Added alpha_m to rCCA in classifiers
• Added squeeze_components to rCCA, eCCA, eTRCA in `classifiers'

Changed

• Changed numpy typing of np.ndarray to NDArray
• Changed cca_ and trca_ attributes to be list always in eCCA, rCCA and eTRCA
• Changed scipy.linalg.inv to pyntbci.utilities.pinv in CCA of transformers
• Changed decision_function and predict of classifiers to return without additional dimension for components if n_components=1 and squeeze_components=True, both of which are defaults

Fixed

Version 1.3.3 (01-07-2024)

Added

Changed

Fixed

• Fixed components bug in decision_function of eCCA in classifiers

Version 1.3.2 (23-06-2024)

Added

• Added cov_estimator_t to eCCA in classifiers

Changed

• Changed separate covariance estimators for data and templates in eCCA of classifiers

Fixed

Version 1.3.1 (23-06-2024)

Added

Changed

Fixed

• Fixed zero division eventplot in plotting
• Fixed event order duration event event_matrix in utilities

Version 1.3.0 (18-06-2024)

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