unfoldtoolbox · vladdez · Dec 17, 2024 · Nov 13, 2024 · Nov 13, 2024 · Nov 13, 2024
diff --git a/joss_paper/complex_plot.png b/joss_paper/complex_plot.png
diff --git a/joss_paper/paper.bib b/joss_paper/paper.bib
@@ -0,0 +1,279 @@
+@article{mikheev2024art,
+  title={The Art of Brainwaves: A Survey on Event-Related Potential Visualization Practices},
+  author={Mikheev, Vladimir and Skukies, Rene and Ehinger, Benedikt V},
+  journal={Aperture Neuro},
+  doi = {10.52294/001c.116386},
+  volume={4},
+  year={2024},
+  publisher={Organization for Human Brain Mapping}
+}
+
+@article{ehinger2019unfold,
+  title={Unfold: an integrated toolbox for overlap correction, non-linear modeling, and regression-based EEG analysis},
+  author={Ehinger, Benedikt V and Dimigen, Olaf},
+  journal={PeerJ},
+  doi={10.5281/zenodo.5759066},
+  volume={7},
+  pages={e7838},
+  year={2019},
+  publisher={PeerJ Inc.}
+}
+@article{danisch2021makie,
+  title={Makie.jl: Flexible high-performance data visualization for Julia},
+  author={Danisch, Simon and Krumbiegel, Julius},
+  journal={Journal of Open Source Software},
+  volume={6},
+  number={65},
+  pages={3349},
+  year={2021}
+}
+
+@article{jung1998analyzing,
+  title={Analyzing and visualizing single-trial event-related potentials},
+  author={Jung, Tzyy-Ping and Makeig, Scott and Westerfield, Marissa and Townsend, Jeanne and Courchesne, Eric and Sejnowski, Terrence J},
+  journal={Advances in neural information processing systems},
+  volume={11},
+  year={1998}
+}
+
+@article{ten2006design,
+  title={Design and evaluation of tiled parallel coordinate visualization of multichannel EEG data},
+  author={Ten Caat, Michael and Maurits, Natasha M and Roerdink, Jos BTM},
+  journal={IEEE Transactions on Visualization and Computer Graphics},
+  volume={13},
+  number={1},
+  pages={70--79},
+  year={2006},
+  publisher={IEEE}
+}
+
+@article{ehinger2018eegvis,
+  title={EEGVIS toolbox},
+  author={Ehinger, Benedikt V},
+  journal={Osnabr{\"u}ck.[Google Scholar]},
+  year={2018}
+}
+
+@article{delorme2004eeglab,
+  title={EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics including independent component analysis},
+  author={Delorme, Arnaud and Makeig, Scott},
+  journal={Journal of neuroscience methods},
+  volume={134},
+  number={1},
+  pages={9--21},
+  year={2004},
+  publisher={Elsevier}
+}
+
+@article{oostenveld2011fieldtrip,
+  title={FieldTrip: open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data},
+  author={Oostenveld, Robert and Fries, Pascal and Maris, Eric and Schoffelen, Jan-Mathijs},
+  journal={Computational intelligence and neuroscience},
+  volume={2011},
+  number={1},
+  pages={156869},
+  year={2011},
+  publisher={Wiley Online Library}
+}
+
+@article{lopez2014erplab,
+  title={ERPLAB: an open-source toolbox for the analysis of event-related potentials},
+  author={Lopez-Calderon, Javier and Luck, Steven J},
+  journal={Frontiers in human neuroscience},
+  volume={8},
+  pages={213},
+  year={2014},
+  publisher={Frontiers Media SA}
+}
+
+@article{tadel2019meg,
+  title={MEG/EEG group analysis with brainstorm},
+  author={Tadel, Fran{\c{c}}ois and Bock, Elizabeth and Niso, Guiomar and Mosher, John C and Cousineau, Martin and Pantazis, Dimitrios and Leahy, Richard M and Baillet, Sylvain},
+  journal={Frontiers in neuroscience},
+  volume={13},
+  pages={76},
+  year={2019},
+  publisher={Frontiers Media SA}
+}
+
+@software{ehigner_2018eegvis,
+  author = {Ehinger, Benedikt V},
+  doi = {10.5281/zenodo.1312813},
+  title = {{EEGVIS toolbox}},
+  url = {https://github.com/behinger/eegvis},
+  version = {0.1},
+  year = {2018}
+}
+
+@software{Wysokinski_NeuroAnalyzer,
+  author = {Wysokiński, Adam},
+  license = {BSD-2-Clause},
+  title = {{NeuroAnalyzer}},
+  version = {0.24.11},
+  year = {2024},
+  doi = {10.5281/zenodo.14010334},
+  url = {https://codeberg.org/AdamWysokinski/NeuroAnalyzer.jl}
+}
+
+@software{Pereyra_EEGToolkit,
+  author = {Pereyra, Santiago Lopez},
+  license = {MIT},
+  title = {{EEGToolkit.jl}},
+  version = {0.2},
+  year = {2024},
+  url = {https://github.com/slopezpereyra/EEGToolkit.jl}
+}
+
+@article{Gramfort_MEG_and_EEG_2013,
+  author = {Gramfort, Alexandre and Luessi, Martin and Larson, Eric and Engemann, Denis A. and Strohmeier, Daniel and Brodbeck, Christian and Goj, Roman and Jas, Mainak and Brooks, Teon and Parkkonen, Lauri and Hämäläinen, Matti S.},
+  doi = {10.3389/fnins.2013.00267},
+  journal = {Frontiers in Neuroscience},
+  number = {267},
+  pages = {1--13},
+  title = {{MEG and EEG Data Analysis with MNE-Python}},
+  volume = {7},
+  year = {2013}
+}
+
+@software{Luke_Neuroimaging,
+  author = {Luke, Rob},
+  license = {BSD-3-Clause},
+  title = {{Neuroimaging.jl}},
+  version = {1.1.2},
+  year = {2021},
+  url = {https://github.com/rob-luke/Neuroimaging.jl}
+}
+
+@software{Krumbiegel_AlgebraOfGraphics,
+  author = {{Krumbiegel}, Julius and {Vertechi}, Pietro},
+  license = {MIT},
+  title = {{AlgebraOfGraphics.jl}},
+  version = {0.8.13},
+  year = {2024},
+  url = {https://github.com/MakieOrg/AlgebraOfGraphics.jl}
+}
+
+@article{BenchmarkTools_jl_2016,
+  author =	 {{Chen}, Jiahao and {Revels}, Jarrett},
+  title =	 "{Robust benchmarking in noisy environments}",
+  journal =	 {arXiv e-prints},
+  keywords =	 {Computer Science - Performance, 68N30, B.8.1, D.2.5},
+  year =	 2016,
+  month =	 "Aug",
+  eid =		 {arXiv:1608.04295},
+  archivePrefix ={arXiv},
+  eprint =	 {1608.04295},
+  primaryClass = {cs.PF},
+  adsurl =	 {https://ui.adsabs.harvard.edu/abs/2016arXiv160804295C},
+  adsnote =	 {Provided by the SAO/NASA Astrophysics Data System}
+}
+@article{robbins2012eegvis,
+  title={EEGVIS: a Matlab toolbox for browsing, exploring, and viewing large datasets},
+  author={Robbins, Kay A},
+  journal={Frontiers in Neuroinformatics},
+  volume={6},
+  pages={17},
+  year={2012},
+  publisher={Frontiers Research Foundation}
+}
+
+@software{Documenter_jl,
+    year={2024},
+    author = {M. Hatherly and M. Piibeleht and F. Ekre},
+    title = {Documenter: A documentation generator for Julia},
+    version = {1.7},
+    url = {https://github.com/JuliaDocs/Documenter.jl}
+}
+
+@software{topoplots_jl,
+    year={2024},
+    author = {Ehinger, Benedikt V and {Phillip} Alday and {Singhvi}, Anshul and {Danisch} Simon},
+    title = {TopoPlots.jl: A Julia package for topoplot generation},
+    version = {0.1.9},
+    url = {https://github.com/MakieOrg/TopoPlots.jl}
+  }
+
+@software{pymne_jl,
+    year={2024},
+    author = {Phillip Alday and Alex Arslan},
+    title = {PyMNE.jl},
+    version = {0.2.2},
+    url = {https://github.com/beacon-biosignals/PyMNE.jl}
+  }
+
+
+@article{crameri2020misuse,
+  title={The misuse of colour in science communication},
+  author={Crameri, Fabio and Shephard, Grace E and Heron, Philip J},
+  journal={Nature communications},
+  volume={11},
+  number={1},
+  pages={5444},
+  year={2020},
+  publisher={Nature Publishing Group UK London}
+}
+
+@techreport{moreland2015we,
+  title={Why We Use Bad Color Maps and What You Can Do About It.},
+  author={Moreland, Kenneth D},
+  year={2015},
+  institution={Sandia National Lab.(SNL-NM), Albuquerque, NM (United States)}
+}
+
+
+@software{simon_kornblith_2023_8344531,
+author = {Simon Kornblith and
+  Galen Lynch and
+  Martin Holters and
+  João Felipe Santos and
+  Spencer Russell and
+  Jay Kickliter and
+  Jeff Bezanson and
+  Gudmundur Adalsteinsson and
+  Alex Arslan and
+  Ryuichi Yamamoto and
+  jordancluts and
+  Matti Pastell and
+  Tony Kelman and
+  Ben Arthur and
+  Tom Krauss and
+  HDictus and
+  Hamza El-Saawy and
+  Jared Kofron and
+  Eric Hanson and
+  Rob Luke and
+  Viral B. Shah and
+  Aleco Kastanos and
+  Bill and
+  Clemens and
+  Elliot Saba and
+  ibadr and
+  Jake Bolewski and
+  Jordan Smith},
+  title = {JuliaDSP/DSP.jl: v0.7.9},
+  month = sep,
+  year = 2023,
+  publisher = {Zenodo},
+  version = {v0.7.9},
+  doi = {10.5281/zenodo.8344531},
+  url = {https://doi.org/10.5281/zenodo.8344531}
+}
+
+@article{JSSv107i04,
+ title={DataFrames.jl: Flexible and Fast Tabular Data in Julia},
+ volume={107},
+ url={https://www.jstatsoft.org/index.php/jss/article/view/v107i04},
+ doi={10.18637/jss.v107.i04},
+ number={4},
+ journal={Journal of Statistical Software},
+ author={Bouchet-Valat, Milan and Kamiński, Bogumił},
+ year={2023},
+ pages={1--32}
+}
+
+@software{Schepers_UnfoldSim_jl,
+  author = {Schepers, Judith and Lips, Luis and Marathe, Maanik and Ehinger, Benedikt},
+  title = {{UnfoldSim.jl}},
+  year={2024},
+  url = {https://github.com/unfoldtoolbox/UnfoldSim.jl}
+}
diff --git a/joss_paper/paper.md b/joss_paper/paper.md
@@ -0,0 +1,119 @@
+---
+title: '`UnfoldMakie.jl`: EEG/ERP visualization package'
+
+tags:
+  - Julia
+  - Event-related potentials (ERP)
+  - Electroencephalography (EEG)
+  - Plotting
+  - Visualization
+  - Interactivity 
+  - ERP image
+  - Topoplot
+  - ERP grid
+  - Butterfly plot
+
+
+authors:
+  - name: Vladimir Mikheev
+    orcid: 0000-0002-4738-6655
+    equal-contrib: true
+    affiliation: 1
+  - name: Benedikt Ehinger
+    orcid: 0000-0002-6276-3332
+    equal-contrib: true
+    affiliation: "1, 2"
+affiliations:
+ - name: University of Stuttgart, Institute for Visualization and Interactive Systems, Germany
+   index: 1
+ - name: University of Stuttgart, Stuttgart Center for Simulation Science, Germany
+   index: 2
+
+date: 30 October 2024
+bibliography: paper.bib
+
+---
+
+
+# Statement of need
+
+`UnfoldMakie.jl` is a Julia package for visualization of electroencephalography (EEG) data, with a focus on event-related potentials (ERPs) and regression-ERPs (rERPs). `UnfoldMakie.jl` fills a gap as one of the only dedicated EEG visualization libraries and offers ease of use, customization, speed, and detailed documentation. It allows for both explorative analysis (zooming/panning) and export to publication-ready vector graphics. This is achieved via multiple backends of `Makie.jl` [@danisch2021makie]: vector graphics with `CairoMakie.jl`, GPU-accelerated interactive graphics with `GLMakie.jl` and the browser-based `WGLMakie,jl`. 
+
+In an earlier study [@mikheev2024art], we asked novice and expert practitioners for insights into their ERP visualization practices. The results of this survey were used to develop and improve `UnfoldMakie.jl`. Further, `UnfoldMakie.jl` is agnostic (independent) of any specific analysis framework, but it nicely accompanies the rERP analysis package `Unfold.jl` [@ehinger2019unfold].
+
+The target audience of this package is anyone working with EEG, MEG, ERP, iEEG or other time-series data.
+
+# Functionality
+`UnfoldMakie.jl` excels in various fields:
+
+- Focused. `UnfoldMakie.jl` focuses exclusively on visualizing (r)ERPs, unlike other toolboxes such as `EEGLAB`, `FieldTrip`, `Brainstorm`, or `MNE`. This makes it easier to understand, use, and maintain the package in the future.
+
+- Customizable. The majority of EEG researchers perceive the flexibility of coding as the most important feature of the EEG toolbox [@mikheev2024art]. Consequently, users `UnfoldMakie.jl` have great flexibility in customizing most aspects of the plots, such as colors, line styles, and axis decorations. 
+
+- Combining plots. The layout system for subplots in `Makie.jl` makes it easy to combine and align various plot types.
+- Flexible mapping. With `AlgebraOfGraphics.jl`, it is easy to map conditions, groups, channels, or other features, to a large variety of aesthetics like linestyle, color, marker and others. It works similar to the popular R package `ggplot2`.
+
+- Flexible data input. All functions support basic `Arrays` and tidy `DataFrames`.
+
+- Fast. Julia and `Makie.jl` allows fast plotting of figures with very complex layout. As an example, it is able to plot one figure with 50 topoplots in 1.9 seconds (1.6 sec with DelaunayMesh interpolation), which is ~20 times faster, compared to `EEGLAB`. Although, the Python-based `MNE` is faster by one second (Table 1). [^1]
+
+[^1]: Be aware that results of benchmarking can vary each run and depends on a OS, package environment, other processes running on computer etc. Current measurements were done by using `BenchmarkTools.jl`. [@BenchmarkTools_jl_2016]
+
+- Faster updating. `Makie.jl` is incredibly fast at updating figures, which is beneficial for developing interactive tools and creating animations. `UnfoldMakie.jl` can create and save a topoplot gif file with 50 frames in 1.7 times less time than `MNE` (Table 2).
+
+- Interactive. Several plots in our package have interactive features. They are supported by `Observables.jl`, which allows for fast data exchange and quick plot updating.
+
+- Scientific color maps. According to our previous study [@mikheev2024art], 40% of EEG researchers are not aware of the issue of perceptually non-uniform color maps. `UnfoldMakie.jl` uses scientific color maps throughout [@crameri2020misuse] [@moreland2015we].
+
+- Documented. There is extensive documentation with many usage examples and docstrings [@Documenter_jl].
+
+
+| **Languages** | **Package**    | **Median speed** |
+|---------------|----------------|------------------|
+| MATLAB        | EEGLAB         | 36 sec           |
+| Julia         | UnfoldMakie    | 1.998 sec        |
+| Python        | MNE            | 0.826 sec        |
+
+: Table 1. Benchmark for a topoplot series with 50 topolots
+
+
+
+| **Languages** | **Package**        | **Median speed** |
+|---------------|--------------------|------------------|
+| Julia         | UnfoldMakie (.gif) | 5.801 sec        |
+| Python        | MNE (.gif)         | 9.494 sec        |
+
+: Table 2. Benchmark for generating (and saving) a topoplot animation with 50 timepoints. No similar functionality exists in `EEGLAB`.
+
+
+We currently support nine general EEG plot types (Figure 1) 
+and two Unfold-specific plots: Design matrices and Spline plots.
+
+# State of the field
+
+There are dozens of libraries in Python and MATLAB for ERP analysis and visualization. According to a recent survey [@mikheev2024art], most EEG practitioners (82%) have experience with MATLAB-based tools like `EEGLAB` [@delorme2004eeglab], `FieldTrip` [@oostenveld2011fieldtrip], `ERPLAB` [@lopez2014erplab] and Brainstorm [@tadel2019meg]. The Python-based `MNE` [@Gramfort_MEG_and_EEG_2013] (41%) and the commercial software `Brain Vision Analyzer` (22%) further showed strong popularity. None of these toolboxes focuses particularly on visualizations. Indeed, in terms of specialized EEG visualization toolboxes, we are aware of only two such libraries, both MATLAB-based and both named `eegvis` [@robbins2012eegvis] and [@ehigner_2018eegvis]. 
+
+Few EEG/ERP analysis and/or visualization libraries have been written in Julia. We are aware of `NeuroAnalyzer.jl` [@Wysokinski_NeuroAnalyzer], `EEGToolkit.jl` [@Pereyra_EEGToolkit], `Neuroimaging.jl` [@Luke_Neuroimaging]. There are also [traces](https://julianeuro.github.io/packages) of several abandoned projects. Worth highlighting is `PyMNE.jl`, a wrapper for the Python-MNE toolbox. [@pymne_jl]
+
+However, all these packages are focused on the analysis of EEG data, while our package is specialized on the visualization of ERPs and rERPs. This is the gap that `UnfoldMakie.jl` fills.
+
+![8 plots generated by UnfoldMakie.jl. A) ERP plot, B) Butterfly plot, C) Topoplot, D) Topoplot timeseries, E) ERP image [@jung1998analyzing], G) Channel image, H) Parallel coordinate plot [@ten2006design].](complex_plot.png)
+
+
+# Funding
+Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) – Project-ID 251654672 – TRR 161 and in the Emmy Noether Programme - Project-ID 538578433.
+
+# Acknowledgements
+
+We acknowledge contributions from Daniel Baumgartner, Niklas Gärtner, Soren Doring, Fadil Furkan Lokman, Judith Schepers, and René Skukies. 
+
+# Toolbox dependencies
+
+Only the main dependencies are listed here. The dependencies of the dependencies can be found in the respective `Manifest.toml` files. Furthermore, please note that we only list rather than cite the packages for which we could not find any citation instructions.
+
+`AlgebraOfGraphics.jl` [@Krumbiegel_AlgebraOfGraphics], `BenchmarkTools.jl`, `BSplineKit.jl`, `CSV.jl`, `CairoMakie.jl`, `CategoricalArrays.jl`, `ColorSchemes.jl`, `ColorTypes.jl`, `Colors.jl`, `CoordinateTransformations.jl`, `DataFrames.jl` [@JSSv107i04], `DataFramesMeta.jl`, `DataStructures.jl`, `DocStringExtensions.jl`, `Documenter.jl` [@Documenter_jl], `DSP.jl` [@simon_kornblith_2023_8344531], `FFMPEG_jll.jl`, `GeometryBasics.jl`, `Glob.jl`, `GridLayoutBase.jl`, `ImageFiltering.jl`, `Interpolations.jl`, `Literate.jl`, `LiveServer.jl`, `LinearAlgebra.jl`, `Makie.jl` [@danisch2021makie], `MakieThemes.jl`, `Observables.jl`, `PyMNE.jl` [@pymne_jl], `PythonCall.jl`, `PythonPlot.jl`, `Random.jl`, `Revise.jl`, `SparseArrays.jl`, `StaticArrays.jl`, `Statistics.jl`, `StatsModels.jl`, `Test.jl`, `TopoPlots.jl` [@topoplots_jl], `Unfold.jl` [@ehinger2019unfold], `UnfoldSim.jl` [@Schepers_UnfoldSim_jl], `XML2_jll.jl`
+
+
+# References
+
+