Package: coffeine
Covariance Data Frames for Predictive M/EEG PipelinesSummaryThecoffeinelibrary implements provides a high-level interface to the predictive modeling techniques focusing on the M/EEG covariance matrix as representation of the signal. The methods implemented here are built on top ofPyRiemannwhile the API is designed with the more specific use-case of building biomedical prediction models from M/EEG signals. For this purpose,coffeineuses DataFrames to handle multiple covariance matrices alongside scalar features. Vectorization and model composition functions are provided that handle composition of scikit-learn compatible modeling pipelines from covariances alongside other types of features.For details on the feature extraction pipelines and statistical models, please consider the following references:[1] D. Sabbagh, P. Ablin, G. Varoquaux, A. Gramfort, and D. A. Engemann.
Predictive regression modeling with MEG/EEG: from source power to signals and cognitive states.NeuroImage, page 116893,2020. ISSN 1053-8119.https://www.sciencedirect.com/science/article/pii/S1053811920303797[2] D. Sabbagh, P. Ablin, G. Varoquaux, A. Gramfort,
and D. A. Engemann.
Manifold-regression to predict from MEG/EEG brain signals
without source modeling.NeurIPS(Advances in Neural Information Processing Systems) 32.https://papers.nips.cc/paper/8952-manifold-regression-to-predict-from-megeeg-brain-signals-without-source-modeling[3] D. A. Engemann, O. Kozynets, D. Sabbagh, G. Lemaître, G. Varoquaux, F. Liem, and A. Gramfort
Combining magnetoencephalography with magnetic resonance imaging enhances learning of surrogate-biomarkers.eLife, 9:e54055, 2020https://elifesciences.org/articles/54055The filter-bank pipelines (across multiple frequency bands) can the thought of as follows:After preprocessing, covariance matrices can be projected to mitigate field spread and deal with rank deficient signals.
Subsequently, vectorization is performed to extract column features from the variance, covariance or both.
The Riemannian embedding is special in mitigating field spread and providing vectorization in 1 step.
It can be combined with dimensionality reduction in the projection step to deal with rank deficiency.
Finally, a statistical learning algorithm is applied.The representation, projection and vectorization steps are separately done for each frequency band.Installation of Python packageYou can clone this library, and then do:$ pip install -e .Everything worked if the following command do not return any error:$ python -c 'import coffeine'Use with Pythoncompute_featuresCompute power features from raw M/EEG data:The power spectral densityThe spectral covariance matricesThe cospectral covariance matricesThe cross-frequency covariance matricesThe cross-frequency correlation matricesThe matrices are of shape (n_frequency_bands, n_channels, n_channels)Use case example:importosimportmnefromcoffeineimportcompute_featuresdata_path=mne.datasets.sample.data_path()data_dir=os.path.join(data_path,'MEG','sample')raw_fname=os.path.join(data_dir,'sample_audvis_raw.fif')raw=mne.io.read_raw_fif(raw_fname,verbose=False)# pick some MEG and EEG channels after croppingraw=raw.copy().crop(0,200).pick([0,1,330,331,332])frequency_bands={'alpha':(8.0,15.0),'beta':(15.0,30.0)}features,_=compute_features(raw,frequency_bands=frequency_bands)make_filter_bank_modelsThe following models are implemented:riemannlw_riemanndiaglogdiagrandomnaivespocriemann_wassdummyUse case example:importnumpyasnpimportpandasaspdfromcoffeineimportmake_filter_bank_regressorfreq_bands={'alpha':(8.0,15.0),'beta':(15.0,30.0)}n_freq_bands=len(freq_bands)n_subjects=10n_channels=4# Make toy dataX_cov=np.random.randn(n_subjects,n_freq_bands,n_channels,n_channels)forsubinrange(n_subjects):forfbinrange(n_freq_bands):X_cov[sub,fb]=X_cov[sub,fb]@X_cov[sub,fb].TX_df=pd.DataFrame({band:list(X_cov[:,ii])forii,bandinenumerate(freq_bands)})X_df['drug']=np.random.randint(2,size=n_subjects)y=np.random.randn(len(X_df))# Modelsfb_model=make_filter_bank_regressor(names=freq_bands.keys(),method='riemann')fb_model.fit(X_df,y)CiteIf you use this code please cite:D. Sabbagh, P. Ablin, G. Varoquaux, A. Gramfort, and D.A. Engemann.
Predictive regression modeling with MEG/EEG: from source power
to signals and cognitive states.NeuroImage, page 116893,2020. ISSN 1053-8119.https://www.sciencedirect.com/science/article/pii/S1053811920303797