Merge branch 'main' of https://github.com/vferat/pycrostates

.github/workflows/code-style.yml

@@ -44,6 +44,6 @@ jobs:
         with:
           check_filenames: true
           check_hidden: true
-          skip: './.git,./build'
+          skip: ./.git,./build,./.github,*.bib
       - name: Run pydocstyle
         run: pydocstyle .

.github/workflows/draft-pdf.yml

@@ -0,0 +1,23 @@
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v1
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper/paper.pdf

paper/paper.bib

@@ -0,0 +1,143 @@
+@article{pedregosa_scikit-learn_nodate,
+	title = {Scikit-learn: {Machine} {Learning} in {Python}},
+	abstract = {Scikit-learn is a Python module integrating a wide range of state-of-the-art machine learning algorithms for medium-scale supervised and unsupervised problems. This package focuses on bringing machine learning to non-specialists using a general-purpose high-level language. Emphasis is put on ease of use, performance, documentation, and API consistency. It has minimal dependencies and is distributed under the simplified BSD license, encouraging its use in both academic and commercial settings. Source code, binaries, and documentation can be downloaded from http://scikit-learn.sourceforge.net.},
+	language = {en},
+	journal = {MACHINE LEARNING IN PYTHON},
+	author = {Pedregosa, Fabian and Varoquaux, Gael and Gramfort, Alexandre and Michel, Vincent and Thirion, Bertrand and Grisel, Olivier and Blondel, Mathieu and Prettenhofer, Peter and Weiss, Ron and Dubourg, Vincent and Vanderplas, Jake and Passos, Alexandre and Cournapeau, David},
+	pages = {6},
+}
+
+@misc{buitinck_api_2013,
+	title = {{API} design for machine learning software: experiences from the scikit-learn project},
+	shorttitle = {{API} design for machine learning software},
+	url = {http://arxiv.org/abs/1309.0238},
+	abstract = {Scikit-learn is an increasingly popular machine learning li- brary. Written in Python, it is designed to be simple and efficient, accessible to non-experts, and reusable in various contexts. In this paper, we present and discuss our design choices for the application programming interface (API) of the project. In particular, we describe the simple and elegant interface shared by all learning and processing units in the library and then discuss its advantages in terms of composition and reusability. The paper also comments on implementation details specific to the Python ecosystem and analyzes obstacles faced by users and developers of the library.},
+	language = {en},
+	urldate = {2022-05-16},
+	publisher = {arXiv},
+	author = {Buitinck, Lars and Louppe, Gilles and Blondel, Mathieu and Pedregosa, Fabian and Mueller, Andreas and Grisel, Olivier and Niculae, Vlad and Prettenhofer, Peter and Gramfort, Alexandre and Grobler, Jaques and Layton, Robert and Vanderplas, Jake and Joly, Arnaud and Holt, Brian and Varoquaux, Gaël},
+	month = sep,
+	year = {2013},
+	note = {Number: arXiv:1309.0238
+arXiv:1309.0238 [cs]},
+	keywords = {Computer Science - Machine Learning, Computer Science - Mathematical Software},
+}
+
+@article{gramfort_meg_2013,
+	title = {{MEG} and {EEG} data analysis with {MNE}-{Python}},
+	volume = {7},
+	issn = {1662453X},
+	url = {http://journal.frontiersin.org/article/10.3389/fnins.2013.00267/abstract},
+	doi = {10.3389/fnins.2013.00267},
+	language = {en},
+	urldate = {2022-05-16},
+	journal = {Frontiers in Neuroscience},
+	author = {Gramfort, Alexandre},
+	year = {2013},
+}
+
+@article{babayan_mind-brain-body_2019,
+	title = {A mind-brain-body dataset of {MRI}, {EEG}, cognition, emotion, and peripheral physiology in young and old adults},
+	volume = {6},
+	issn = {2052-4463},
+	url = {http://www.nature.com/articles/sdata2018308},
+	doi = {10.1038/sdata.2018.308},
+	language = {en},
+	number = {1},
+	urldate = {2022-05-16},
+	journal = {Scientific Data},
+	author = {Babayan, Anahit and Erbey, Miray and Kumral, Deniz and Reinelt, Janis D. and Reiter, Andrea M. F. and Röbbig, Josefin and Schaare, H. Lina and Uhlig, Marie and Anwander, Alfred and Bazin, Pierre-Louis and Horstmann, Annette and Lampe, Leonie and Nikulin, Vadim V. and Okon-Singer, Hadas and Preusser, Sven and Pampel, André and Rohr, Christiane S. and Sacher, Julia and Thöne-Otto, Angelika and Trapp, Sabrina and Nierhaus, Till and Altmann, Denise and Arelin, Katrin and Blöchl, Maria and Bongartz, Edith and Breig, Patric and Cesnaite, Elena and Chen, Sufang and Cozatl, Roberto and Czerwonatis, Saskia and Dambrauskaite, Gabriele and Dreyer, Maria and Enders, Jessica and Engelhardt, Melina and Fischer, Marie Michele and Forschack, Norman and Golchert, Johannes and Golz, Laura and Guran, C. Alexandrina and Hedrich, Susanna and Hentschel, Nicole and Hoffmann, Daria I. and Huntenburg, Julia M. and Jost, Rebecca and Kosatschek, Anna and Kunzendorf, Stella and Lammers, Hannah and Lauckner, Mark E. and Mahjoory, Keyvan and Kanaan, Ahmad S. and Mendes, Natacha and Menger, Ramona and Morino, Enzo and Näthe, Karina and Neubauer, Jennifer and Noyan, Handan and Oligschläger, Sabine and Panczyszyn-Trzewik, Patricia and Poehlchen, Dorothee and Putzke, Nadine and Roski, Sabrina and Schaller, Marie-Catherine and Schieferbein, Anja and Schlaak, Benito and Schmidt, Robert and Gorgolewski, Krzysztof J. and Schmidt, Hanna Maria and Schrimpf, Anne and Stasch, Sylvia and Voss, Maria and Wiedemann, Annett and Margulies, Daniel S. and Gaebler, Michael and Villringer, Arno},
+	month = mar,
+	year = {2019},
+	pages = {180308},
+}
+
+@article{brunet_spatiotemporal_nodate,
+	title = {Spatiotemporal {Analysis} of {Multichannel} {EEG}: {CARTOOL}},
+	language = {en},
+	journal = {Computational Intelligence and Neuroscience},
+	author = {Brunet, Denis and Murray, Micah M and Michel, Christoph M},
+	pages = {16},
+}
+
+@article{von_wegner_information-theoretical_2018,
+	title = {Information-{Theoretical} {Analysis} of {EEG} {Microstate} {Sequences} in {Python}},
+	volume = {12},
+	issn = {1662-5196},
+	url = {https://www.frontiersin.org/article/10.3389/fninf.2018.00030/full},
+	doi = {10.3389/fninf.2018.00030},
+	abstract = {We present an open-source Python package to compute information-theoretical quantities for electroencephalographic data. Electroencephalography (EEG) measures the electrical potential generated by the cerebral cortex and the set of spatial patterns projected by the brain’s electrical potential on the scalp surface can be clustered into a set of representative maps called EEG microstates. Microstate time series are obtained by competitively fitting the microstate maps back into the EEG data set, i.e., by substituting the EEG data at a given time with the label of the microstate that has the highest similarity with the actual EEG topography. As microstate sequences consist of non-metric random variables, e.g., the letters A–D, we recently introduced information-theoretical measures to quantify these time series. In wakeful resting state EEG recordings, we found new characteristics of microstate sequences such as periodicities related to EEG frequency bands. The algorithms used are here provided as an open-source package and their use is explained in a tutorial style. The package is self-contained and the programming style is procedural, focusing on code intelligibility and easy portability. Using a sample EEG file, we demonstrate how to perform EEG microstate segmentation using the modified K-means approach, and how to compute and visualize the recently introduced information-theoretical tests and quantities. The time-lagged mutual information function is derived as a discrete symbolic alternative to the autocorrelation function for metric time series and confidence intervals are computed from Markov chain surrogate data. The software package provides an open-source extension to the existing implementations of the microstate transform and is specifically designed to analyze resting state EEG recordings.},
+	language = {en},
+	urldate = {2022-05-16},
+	journal = {Frontiers in Neuroinformatics},
+	author = {von Wegner, Frederic and Laufs, Helmut},
+	month = jun,
+	year = {2018},
+	pages = {30},
+}
+
+@techreport{poulsen_microstate_2018,
+	type = {preprint},
+	title = {Microstate {EEGlab} toolbox: {An} introductory guide},
+	shorttitle = {Microstate {EEGlab} toolbox},
+	url = {http://biorxiv.org/lookup/doi/10.1101/289850},
+	abstract = {EEG microstate analysis offers a sparse characterisation of the spatio-temporal features of large-scale brain network activity. However, despite the concept of microstates is straight-forward and offers various quantifications of the EEG signal with a relatively clear neurophysiological interpretation, a few important aspects about the currently applied methods are not readily comprehensible. Here we aim to increase the transparency about the methods to facilitate widespread application and reproducibility of EEG microstate analysis by introducing a new EEGlab toolbox for Matlab. EEGlab and the Microstate toolbox are open source, allowing the user to keep track of all details in every analysis step. The toolbox is specifically designed to facilitate the development of new methods. While the toolbox can be controlled with a graphical user interface (GUI), making it easier for newcomers to take their first steps in exploring the possibilities of microstate analysis, the Matlab framework allows advanced users to create scripts to automatise analysis for multiple subjects to avoid tediously repeating steps for every subject. This manuscript provides an overview of the most commonly applied microstate methods as well as a tutorial consisting of a comprehensive walk-through of the analysis of a small, publicly available dataset.},
+	language = {en},
+	urldate = {2022-05-16},
+	institution = {Neuroscience},
+	author = {Poulsen, Andreas Trier and Pedroni, Andreas and Langer, Nicolas and Hansen, Lars Kai},
+	month = mar,
+	year = {2018},
+	doi = {10.1101/289850},
+}
+
+@article{pascual-marqui_segmentation_1995,
+	title = {Segmentation of brain electrical activity into microstates: model estimation and validation},
+	volume = {42},
+	issn = {0018-9294, 1558-2531},
+	shorttitle = {Segmentation of brain electrical activity into microstates},
+	url = {https://ieeexplore.ieee.org/document/391164/},
+	doi = {10.1109/10.391164},
+	abstract = {A brain microstate is defined as a functional/physiological state of the brain during which specific neural computations are performed. It is characterized uniquelyby a fixed spatial distribution of active neuronal generators with time varying intensity. Brain electrical activity is modeled as being composed of a time sequence of nonoverlapping microstates with variable duration. A precise mathematical formulation of the model for evoked potential recordings is presented, where the microstates are represented as normalized vectors constitutedby scalpelectric potentials due to the underlying generators. An algorithm is developed for estimating the microstates, based on a modiied version of the classical IC-means clustering method, in which cluster orientations are estimated. Consequently, each instantaneous multichannel evoked potential measurement is classified as belonging to some microstate, thus producing a natural segmentation of brain activity. Use is made of statistical image segmentation techniques for obtaining smooth continuous segments. Time varying intensities are estimated by projecting the measurements onto their corresponding microstates. A goodness of fit statistic for the model is presented. Finally, a method is introduced for estimating the number of microstates, based on nonparametric data-driven statistical resampling techniques.},
+	language = {en},
+	number = {7},
+	urldate = {2022-05-30},
+	journal = {IEEE Transactions on Biomedical Engineering},
+	author = {Pascual-Marqui, R.D. and Michel, C.M. and Lehmann, D.},
+	month = jul,
+	year = {1995},
+	pages = {658--665},
+}
+
+@article{MICHEL2018577,
+title = {EEG microstates as a tool for studying the temporal dynamics of whole-brain neuronal networks: A review},
+journal = {NeuroImage},
+volume = {180},
+pages = {577-593},
+year = {2018},
+note = {Brain Connectivity Dynamics},
+issn = {1053-8119},
+doi = {https://doi.org/10.1016/j.neuroimage.2017.11.062},
+url = {https://www.sciencedirect.com/science/article/pii/S105381191731008X},
+author = {Christoph M. Michel and Thomas Koenig},
+keywords = {EEG microstates, Resting state networks, Consciousness, Psychiatric disease, State-dependent information processing, Metastability},
+abstract = {The present review discusses a well-established method for characterizing resting-state activity of the human brain using multichannel electroencephalography (EEG).
+            This method involves the examination of electrical microstates in the brain, which are defined as successive short time periods during which the configuration of the scalp potential field remains semi-stable,
+			suggesting quasi-simultaneity of activity among the nodes of large-scale networks. A few prototypic microstates, which occur in a repetitive sequence across time, can be reliably identified across participants.
+			Researchers have proposed that these microstates represent the basic building blocks of the chain of spontaneous conscious mental processes, and that their occurrence and temporal dynamics determine the quality of mentation.
+			Several studies have further demonstrated that disturbances of mental processes associated with neurological and psychiatric conditions manifest as changes in the temporal dynamics of specific microstates. Combined EEG-fMRI
+			studies and EEG source imaging studies have indicated that EEG microstates are closely associated with resting-state networks as identified using fMRI. The scale-free properties of the time series of EEG microstates explain
+			why similar networks can be observed at such different time scales. The present review will provide an overview of these EEG microstates, available methods for analysis, the functional interpretations of findings regarding
+			these microstates, and their behavioral and clinical correlates.}
+}
+
+@article{lehmann1971multichannel,
+  title={Multichannel topography of human alpha EEG fields},
+  author={Lehmann, D},
+  journal={Electroencephalography and clinical neurophysiology},
+  volume={31},
+  number={5},
+  pages={439--449},
+  year={1971},
+  publisher={Elsevier}
+}

paper/paper.md

@@ -0,0 +1,63 @@
+---
+title: 'Pycrostates: a Python library to study EEG microstates'
+tags:
+  - Python
+  - neuroscience
+  - neuroimaging
+  - EEG
+  - microstates
+  - brain
+authors:
+  - name: Victor Férat^[Co-first author]^[Corresponding author] # note this makes a footnote saying 'Co-first author'
+    orcid: 0000-0003-1952-7657
+    affiliation: 1
+  - name: Mathieu Scheltienne^[Co-first author] # note this makes a footnote saying 'Co-first author'
+    orcid: 0000-0001-8316-7436
+    affiliation: 2
+  - name: Denis Brunet
+    affiliation: "1, 3" # (Multiple affiliations must be quoted)
+  - name: Tomas Ros
+    orcid: 0000-0001-6952-0459
+    affiliation: "1, 3" # (Multiple affiliations must be quoted)
+  - name: Christoph Michel
+    orcid: 0000-0003-3426-5739
+    affiliation: "1, 3" # (Multiple affiliations must be quoted)
+affiliations:
+ - name: Functional Brain Mapping Laboratory, Department of Basic Neurosciences, Campus Biotech, University of Geneva, Geneva, Switzerland
+   index: 1
+ - name: Human Neuroscience Platform, Fondation Campus Biotech Geneva, Geneva, Switzerland
+   index: 2
+ - name: Centre for Biomedical Imaging (CIBM) Lausanne-Geneva, Geneva, Switzerland
+   index: 3
+date: 30 May 2022
+bibliography: paper.bib
+---
+
+# Summary
+Microstate analysis of the electroencephalogram (EEG), introduced in 1972 by Lehman [@lehmann1971multichannel], is a spatiotemporal analysis technique that takes advantage of the full spatial resolution of EEG recordings. Formalized further by Pascual Marqui and colleagues [@pascual-marqui_segmentation_1995], microstate analysis studies the distribution of the surface EEG potential maps over time. It transforms the EEG recordings into sequences of successive states of variable duration, called EEG microstates.
+
+Pycrostates implements multiple modules that allow researchers to apply microstate analysis on their data:
+
+- the cluster module supports the different clustering algorithms that find the optimal topographic maps that sparsely represent the EEG. 
+- the segmentation module supports the study of microstates sequences and their summary measures.
+- the metrics module quantifies the quality of the fitted clustering algorithms.
+
+Additional modules help researchers to develop analysis pipelines:
+
+- the dataset module provides direct access to preprocessed data that can be used to test pipelines. As of writing, it supports the LEMON dataset [@babayan_mind-brain-body_2019] comprising preprocessed EEG recordings of 227 healthy participants.
+- the viz module provides visualization tools for performing microstate analyses.
+
+By design, Pycrostates supports natively all data types from MNE-Python [@gramfort_meg_2013] and is not restricted to EEG data. It is designed to support future improvements and additions such as different clustering algorithms or new tools for sequence analysis such as Markov chains. Moreover, this work builds its API on top of the robust MNE-Python ecosystem, enabling a seamless integration of microstates analysis.
+
+# Statement of need
+
+Currently, several software and libraries are available to perform EEG microstates analysis: Cartool [@brunet_spatiotemporal_nodate], Thomas Koening's Matlab plugins (https://www.thomaskoenig.ch/index.php/software/microstates-in-eeglab), the Matlab microstates plugin [@poulsen_microstate_2018], or the python 2 library from Frederic von Wegner [@von_wegner_information-theoretical_2018]. In the last few years, the Python programming language ecosystem has expanded considerably, especially in scientific fields. The MNE-Python [@gramfort_meg_2013] library stands out for the analysis of human neurophysiological data. However, the current implementation of microstates analysis from Marijn van Vliet has a limited number of features and is not maintained on a regular basis. Pycrostates is based on the robust MNE-Python ecosystem and complements it with simple tools for developing integrated microstates analysis pipelines. 
+In addition to providing a simple and complete API that can replicate most of the analyses proposed in the literature [@MICHEL2018577], Pycrostates is built with a modular and scalable design, following modern development methods and standards to facilitate its maintenance and evolution over time. Finally, new users will benefits from the exhaustive documentation and tutorials describing the microstate analysis modules.
+
+With this contribution, the developer team is excited to provide the state of the art in microstates analysis and is looking forward to welcoming new contributors and users from the broader MNE, neuroscience, and electrophysiology community.
+
+# Acknowledgements
+
+Pycrostates development is partly supported by the Swiss National Science Foundation (grant No. 320030_184677) and by the Human Neuroscience Platform, Fondation Campus Biotech Geneva, Geneva, Switzerland.
+
+# References