Package: toeplitzlda
ToeplitzLDACode for the ToeplitzLDA classifier proposed inhere.
The classifier conforms sklearn and can be used as a drop-in replacement for other LDA
classifiers. For in-depth usage refer to the learning from label proportions (LLP) example
or the example script.Note we used Ubuntu 20.04 with python 3.8.10 to generate our results.Getting Started / User SetupIf you only want to use this library, you can use the following setup. Note that this
setup is based on a fresh Ubuntu 20.04 installation.Getting fresh ubuntu readyaptinstallpython3-pippython3-venvPython package installationIn this setup, we assume you want to run the examples that actually make use of real EEG
data or the actual unsupervised speller replay. If you only want to employToeplitzLDAin your own spatiotemporal data / withoutmneandmoabbthen you can remove the
package extraneuro, i.e.pip install toeplitzldaorpip install toeplitzlda[solver](Optional) Install fortran Compiler. On ubuntu:apt install gfortranCreate virtual environment:python3 -m venv toeplitzlda_venvActivate virtual environment:source toeplitzlda_venv/bin/activateInstall toeplitzlda:pip install toeplitzlda[neuro,solver], if you dont have a
fortran compiler:pip install toeplitzlda[neuro]Check if everything worksEither clone this repo or just download thescripts/example_toeplitz_lda_bci_data.pyfile and run it:python example_toeplitz_lda_bci_data.py. Note that this will
automatically download EEG data with a size of around 650MB.Alternatively, you can use thescripts/example_toeplitz_lda_generated_data.pywhere
artificial data is generated. Note however, that only stationary background noise is
modeled and no interfering artifacts as is the case in, e.g., real EEG data. As a result,
theoverfittingeffect of traditional slda on these artifacts is reduced.Using ToeplitzLDA in place of traditional shrinkage LDA from sklearnIf you have already your own pipeline, you can simply addtoeplitzldaas a dependency in
your project and then replace sklearns LDA, i.e., instead of:fromsklearn.discriminant_analysisimportLinearDiscriminantAnalysisclf=LinearDiscriminantAnalysis(solver="lsqr",shrinkage="auto")# or eigen solverusefromtoeplitzlda.classificationimportToeplitzLDAclf=ToeplitzLDA(n_channels=your_n_channels)whereyour_n_channelsis the number of channels of your signal and needs to be provided
for this method to work.If you prefer using sklearn, you can only replace the covariance estimation part, note
however, that this in practice (on our data) yields worse performance, as sklearn
estimates the class-wise covariance matrices and averages them afterwards, whereas we
remove the class-wise means and the estimate one covariance matrix from the pooled data.So instead of:fromsklearn.discriminant_analysisimportLinearDiscriminantAnalysisclf=LinearDiscriminantAnalysis(solver="lsqr",shrinkage="auto")# or eigen solveryou would usefromsklearn.discriminant_analysisimportLinearDiscriminantAnalysisfromtoeplitzlda.classification.covarianceimportToepTapLWtoep_cov=ToepTapLW(n_channels=your_n_channels)clf=LinearDiscriminantAnalysis(solver="lsqr",covariance_estimator=toep_cov)# or eigen solverDevelopment SetupWe use a fortran compiler to provide speedups for solving block-Toeplitz linear equation
systems. If you are on ubuntu you can installgfortran.We usepoetryfor dependency management. If you have it installed you can simply usepoetry installto set up the virtual environment with all dependencies. All extra
features can be installed withpoetry install -E solver -E neuro.If setup does not work for you, please open an issue. We cannot provide in-depth support
for many different platforms, but could provide asingularityimage.Learning from label proportionsUse therun_llp.pyscript to apply ToeplitzLDA in the LLP scenario and create the
results file for the different preprocessing parameters. These can then be visualized
usingvisualize_llp.pyto create the plots shown in our publication. Note that running
LLP takes a while and the two datasets will be downloaded automatically and are
approximately 16GB in size. Alternatively, you can use the results provided by us that are
stored inscripts/usup_replay/provided_resultsby moving/copying them to the location
thatvisualize_llp.pylooks for.ERP benchmarkThis is not yet available.Note this benchmark will take quite a long time if you do not have access to a computing
cluster. The public datasets (including the LLP datasets) total a size of approximately
120GB.BLOCKING TODO: How should we handle the private datasets?Split benchmark into public and private/closed classesCan we provide the code for private datasets without the data? Or is that too
sensitive?FAQWhy is my classification performance for my stationary spatiotemporal data really bad?Check if your data is inchannel-primeorder, i.e., in the flattened feature vector, you
first enumerate over all channels (or some other spatially distributed sensors) for the
first time point and then for the second time point and so on. If this is not the case,
tell the classifier: e.g.ToeplitzLDA(n_channels=16, data_is_channel_prime=False)I dont know if my data is stationary. How can I find out?We do not provide any statistical testing or other facilities to check for stationarity.
However, we use theblockmatrixpackage (disclaimer: also provided by us), which can
visualize your covariance matrix in a way that you can see if stationarity is a reasonable
assumption or not. Note however, sometimes your data will look non-stationary due to,
e.g., artifacts, even though your underlying process is stationary. This often happens if
the number of data samples to estimate the covariance is small. However, in our data it
then is often better to enforce stationarity anyhow, as you can avoid overfitting on thepresumablynon-stationary observed data.Further Work / TodosExample how to check data for stationarity. Maybe better inblockmatrixpackage.