paper submission to JOSS

paper/paper.bib

@@ -6,4 +6,101 @@ @article{mathot2018pupillometry
   number={1},
   year={2018},
   publisher={Ubiquity Press}
+}
+
+@article{laeng2012pupillometry,
+  title={Pupillometry: A window to the preconscious?},
+  author={Laeng, Bruno and Sirois, Sylvain and Gredeb{\"a}ck, Gustaf},
+  journal={Perspectives on psychological science},
+  volume={7},
+  number={1},
+  pages={18--27},
+  year={2012},
+  publisher={Sage Publications Sage CA: Los Angeles, CA}
+}
+
+@article{hess1960pupil,
+  title={Pupil size as related to interest value of visual stimuli},
+  author={Hess, Eckhard H and Polt, James M},
+  journal={Science},
+  volume={132},
+  number={3423},
+  pages={349--350},
+  year={1960},
+  publisher={American Association for the Advancement of Science}
+}
+@article{geller_gazer_2020,
+        title = {{GazeR}: {A} {Package} for {Processing} {Gaze} {Position} and {Pupil} {Size} {Data}},
+        issn = {1554-3528},
+        shorttitle = {{GazeR}},
+        url = {https://doi.org/10.3758/s13428-020-01374-8},
+        doi = {10.3758/s13428-020-01374-8},
+        abstract = {Eye-tracking is widely used throughout the scientific community, from vision science and psycholinguistics to marketing and human-computer interaction. Surprisingly, there is little consistency and transparency in preprocessing steps, making replicability and reproducibility difficult. To increase replicability, reproducibility, and transparency, a package in R (a free and widely used statistical programming environment) called gazeR was created to read and preprocess two types of data: gaze position and pupil size. For gaze position data, gazeR has functions for reading in raw eye-tracking data, formatting it for analysis, converting from gaze coordinates to areas of interest, and binning and aggregating data. For data from pupillometry studies, the gazeR package has functions for reading in and merging multiple raw pupil data files, removing observations with too much missing data, eliminating artifacts, blink identification and interpolation, subtractive baseline correction, and binning and aggregating data. The package is open-source and freely available for download and installation: https://github.com/dmirman/gazer. We provide step-by-step analyses of data from two tasks exemplifying the package’s capabilities.},
+        language = {en},
+        urldate = {2020-05-27},
+        journal = {Behavior Research Methods},
+        author = {Geller, Jason and Winn, Matthew B. and Mahr, Tristian and Mirman, Daniel},
+        month = apr,
+        year = {2020},
+        file = {Springer Full Text PDF:/Users/mmi041/Zotero/storage/Z3L9FUWR/Geller et al. - 2020 - GazeR A Package for Processing Gaze Position and .pdf:application/pdf}
+}
+
+@Manual{forbes2020,
+    title = {PupillometryR: A Unified Pipeline for Pupillometry Data},
+    author = {Samuel Forbes},
+    year = {2020},
+    note = {R package version 0.0.2},
+    url = {https://CRAN.R-project.org/package=PupillometryR},
+}
+  
+  
+@article{aston2005integrative,
+  title={An integrative theory of locus coeruleus-norepinephrine function: adaptive gain and optimal performance},
+  author={Aston-Jones, Gary and Cohen, Jonathan D},
+  journal={Annu. Rev. Neurosci.},
+  volume={28},
+  pages={403--450},
+  year={2005},
+  publisher={Annual Reviews}
+}
+
+@article{joshi2016relationships,
+  title={Relationships between pupil diameter and neuronal activity in the locus coeruleus, colliculi, and cingulate cortex},
+  author={Joshi, Siddhartha and Li, Yin and Kalwani, Rishi M and Gold, Joshua I},
+  journal={Neuron},
+  volume={89},
+  number={1},
+  pages={221--234},
+  year={2016},
+  publisher={Elsevier}
+}
+
+@article{mittner2016neural,
+  title={A neural model of mind wandering},
+  author={Mittner, Matthias and Hawkins, Guy E and Boekel, Wouter and Forstmann, Birte U},
+  journal={Trends in cognitive sciences},
+  volume={20},
+  number={8},
+  pages={570--578},
+  year={2016},
+  publisher={Elsevier}
+}
+
+@article{gilzenrat2010pupil,
+  title={Pupil diameter tracks changes in control state predicted by the adaptive gain theory of locus coeruleus function},
+  author={Gilzenrat, Mark S and Nieuwenhuis, Sander and Jepma, Marieke and Cohen, Jonathan D},
+  journal={Cognitive, Affective, \& Behavioral Neuroscience},
+  volume={10},
+  number={2},
+  pages={252--269},
+  year={2010},
+  publisher={Springer}
+}
+
+@inproceedings{kluyver2016jupyter,
+  title={Jupyter Notebooks-a publishing format for reproducible computational workflows.},
+  author={Kluyver, Thomas and Ragan-Kelley, Benjamin and P{\'e}rez, Fernando and Granger, Brian E and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica B and Grout, Jason and Corlay, Sylvain and others},
+  booktitle={ELPUB},
+  pages={87--90},
+  year={2016}
 }

paper/paper.md

@@ -1,5 +1,5 @@
 ---
-title: 'pypillometry: A Python package pupillometric analyses'
+title: 'pypillometry: A Python package for pupillometric analyses'
 tags:
   - Python
   - pupil
@@ -21,18 +21,14 @@ bibliography: paper.bib
 
 # Summary
 
-blub @mathot2018pupillometry
+The size of the human pupil is controlled by pairs of constrictor and dilator muscles that allow its opening (dilation) and closing (constriction) in response to varying lighting conditions [@mathot2018pupillometry]. Importantly, it has long been known that the pupil also reacts to psychological important stimuli [@hess1960pupil] and has been a firmly established tool for studying "mental effort" in the research kit of psychologists for many decades [@laeng2012pupillometry]. More recently, pupil-size has been linked to the norepinephrinergic (NE) system originating from area *locus coeruleus* (LC) in the brainstem [@aston2005integrative], a link that has been substantiated experimentally by direct recordings in the brainstem of monkeys [@joshi2016relationships]. This finding of a correlation between NE activity in the brainstem and pupil-dilation has opened the way for researchers investigating the relationship between the LC-NE system and many cognitive functions, such as cognitive control [@gilzenrat2010pupil] and mind wandering [@mittner2016neural]. Advancing this emerging field requires the decomposition of the pupillometric signal into tonic (baseline) and phasic (response) components that relate to different processing regimes of the LC-NE system. 
 
+The Python package `pypillometry` is a comprehensive library implementing preprocessing, plotting and advanced analysis tools in a coherent and extensible, object-oriented framework. It is oriented towards researchers in psychology and neuroscience that wish to analyze data from pupillometric experiments. `pypillometry` implements an intuitive, pipeline-based processing strategy where an analysis pipeline can be dynamically chained together. All operations and parameters applied to a dataset are stored in its history. This allows (1) a transparent and comprehensive logging of the operations applied for an analysis which is valuable for reproducible analyses, (2) the ability to "roll-back" any changes made to any point in the history of the dataset and (3) to easily generalize a processing pipeline to multiple datasets. The package contains pre-processing facilities implementing algorithms for blink detection and interpolation, filtering and resampling. All parameters are clearly documented, accessible and set to sensible default-parameters. A focus of the package is to provide extensive visualization features in order to facilitate dynamic exploration of the data as well as iterative adjustment of the pre-processing parameters. As the time-series of pupillometric data can be quite long, this requires separation into several plots or dynamically adjustable plot-axes. Both strategies are implemented in this package by allowing interactive plots if run from a Jupyter-Notebook [@kluyver2016jupyter] or storing a multi-page PDF document, allowing both interactive and scripted use. The `pypillometry` package also implements functions for event-related pupil-dilation (ERPD) analyses both at the individual and the group-level. Finally, the package implements novel algorithms for decomposing the pupillometric signal into tonic and phasic components. This approach allows to simultaneously quantify dynamic changes of both baseline and response-strength that can be related to the tonic and phasic processing regimes of the LC-NE system.
 
-Other packages:
-
-- https://github.com/dr-JT/pupillometry/ (only pre-processing, R, reduced functionality)
-- https://github.com/samhforbes/PupillometryR (more comprehensive, R)
-- `GazeR` https://link.springer.com/article/10.3758/s13428-020-01374-8 (https://github.com/dmirman/gazer)
-- 
+`Pypillometry` was already used for the analyses of several pupillometric datasets in our department. Several software packages with similar goals are available in R [e.g., @geller_gazer_2020; @forbes2020]. However, to date, no comprehensive Python-based solution besides `pypillometry` exists. None of the other packages provides facilities to estimate tonic and phasic components of the pupillometric signal. 
 
 # Acknowledgements
 
-I acknowledge contributions from 
+I would like to thank the members of my research group for stimulating discussions and critical advice. In particular, I would like to thank Isabel Viola Kreis, Josephine Maria Groot, Gábor Csifcsák and Carole Schmidt for their input. I would also like to thank Bruno Laeng for inspiring discussions.
 
 # References