community guidelines (doc)

- added links to issue-tracker to README - filled out Contributing-section in the documentation See also: #2
ihrke · Jun 25, 2020 · dd9974e · dd9974e
1 parent 97850e8
commit dd9974e
Show file tree

Hide file tree

Showing 18 changed files with 233 additions and 57 deletions.
diff --git a/README.md b/README.md
@@ -11,3 +11,10 @@ This package implements functions for the analysis of pupillometric data. Featur
 - Homepage/Documentation: <http://ihrke.github.com/pypillometry>
 
 
+---
+
+The project is maintained by Matthias Mittner <matthias.mittner@uit.no>
+
+To report a bug or recommend a new feature, please use [github's issue tracker](https://github.com/ihrke/pypillometry/issues).
+
+For more details about how to contribute, please see the [contribution-section](https://ihrke.github.io/pypillometry/html/docs/dev.html) in the documentation.
diff --git a/docs/dev.rst b/docs/dev.rst
@@ -1,28 +1,54 @@
+.. currentmodule:: pypillometry.pupildata
+
 Developers
 ==========
 
 .. image:: https://travis-ci.com/ihrke/pypillometry.svg?branch=master
     :target: https://travis-ci.com/ihrke/pypillometry
 
-Contibuting
------------
+This package is developed and maintained by the `Cognitive Neuroscience Research Group <http://uit.no/research/cognitive-neuroscience>`_ at the `University of Tromsø <http://uit.no>`_. We encourage everyone to become a member of the team and to contribute to the package's development, either by `reporting bugs  <https://github.com/ihrke/pypillometry/issues>`_, `providing enhancements <https://github.com/ihrke/pypillometry/pulls>`_ or otherwise.
+
+How to contribute
+-----------------
 
 Development of this package happens on GitHub: https://github.com/ihrke/pypillometry
 
-- Issue-tracker: https://github.com/ihrke/pypillometry/issues
-- PR's welcome: https://github.com/ihrke/pypillometry/pulls
+In order to contribute, please use
+
+- `github's issue tracker <https://github.com/ihrke/pypillometry/issues>`_ for reporting bugs or proposing enhancements
+- `github's pull-request (PR) feature <https://github.com/ihrke/pypillometry/pulls>`_ for contributing to the package and/or documentation
+
+If you are unfamiliar with Github's system, you can read up about `collaborating with issues and pull-requests on Github <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
+
+
+Coding style/package architecture
+---------------------------------
+
+We chose to put most functionality directly below :mod:`pypillometry`'s main class :class:`PupilData`. This is mostly for convenience,
+as users can easily find and chain commands together (see the following page more on this: :ref:`Pipeline-based processing in pypillometry </docs/pipes.ipynb>`).
+
+The implementation of the functionality, however, is coded in submodules using "stateless" functions that take :mod:`numpy`-arrays as arguments. So, in order to create a new function that changes a :class:`PupilData`-object, you will first want to implement a function working purely on :mod:`numpy`-arrays and then create a thin wrapper function below :class:`PupilData` that calls this low-level function with the correct arguments.
 
-Building docs
--------------
+Unit-testing
+------------
 
-A couple of non-standard sphinx extensions are being used:
+Every newly developed function should be provided with `Unit-testing functions <https://en.wikipedia.org/wiki/Unit_testing>`_. As a minimum, the function should be called with some reasonable arguments to ensure that the function does not crash. Better yet, the results of the functions should be tested against the desired output within these test functions. All unit-tests are located in `/pypillometry/tests/` and are run automatically for every commit to Github using `Travis CI <https://travis-ci.com/ihrke/pypillometry>`_. 
+
+Building the packages documentation
+-----------------------------------
+
+This is only necessary when extending `pypillometry`'s documentation (i.e., updating the website at https://ihrke.github.io/pypillometry).
+
+The package uses the `Sphinx documentation generator <https://www.sphinx-doc.org/>`_ to create this website. All source-files are located under `/docs/` (both `.rst` and `.ipynb` files are being used). In addition, the API-documentation is placed within each function or classes' docstring.
+
+To compile the documentation, sphinx must be installed. In addition, a couple of non-standard sphinx extensions are being used:
 
 .. code-block:: python
 
     ['sphinx_math_dollar',  "m2r",'sphinx_autodoc_typehints', 'nbsphinx']
 
 
-Installation: 
+These can be installed by using the following commands:
 
 
 .. code-block:: bash
@@ -36,6 +62,14 @@ Installation:
     # for the typehints
     conda install -c conda-forge sphinx-autodoc-typehints
 
+Finally, the documentation can be created by running
+
+.. code-block:: bash
+
+    make html
+    
+in the packages' root-directory. 
+
 .. warning::
 
     don't run `make clean`, it will delete the source-files from `docs`
diff --git a/docs/doctrees/README.doctree b/docs/doctrees/README.doctree
diff --git a/docs/doctrees/docs/dev.doctree b/docs/doctrees/docs/dev.doctree
diff --git a/docs/doctrees/environment.pickle b/docs/doctrees/environment.pickle
diff --git a/docs/doctrees/index.doctree b/docs/doctrees/index.doctree
diff --git a/docs/doctrees/paper/paper.doctree b/docs/doctrees/paper/paper.doctree
diff --git a/docs/html/README.html b/docs/html/README.html
@@ -45,6 +45,10 @@ <h1>Welcome to pypillometry!<a class="headerlink" href="#welcome-to-pypillometry
 <li><p>Github-repository: <a class="reference external" href="https://github.com/ihrke/pypillometry">https://github.com/ihrke/pypillometry</a></p></li>
 <li><p>Homepage/Documentation: <a class="reference external" href="http://ihrke.github.com/pypillometry">http://ihrke.github.com/pypillometry</a></p></li>
 </ul>
+<hr class="docutils" />
+<p>The project is maintained by Matthias Mittner <a class="reference external" href="mailto:matthias&#46;mittner&#37;&#52;&#48;uit&#46;no">matthias<span>&#46;</span>mittner<span>&#64;</span>uit<span>&#46;</span>no</a></p>
+<p>To report a bug or recommend a new feature, please use <a class="reference external" href="https://github.com/ihrke/pypillometry/issues">github’s issue tracker</a>.</p>
+<p>For more details about how to contribute, please see the <a class="reference external" href="https://ihrke.github.io/pypillometry/html/docs/dev.html">contribution-section</a> in the documentation.</p>
 </div>
 
 

diff --git a/docs/html/_sources/README.md.txt b/docs/html/_sources/README.md.txt
@@ -11,3 +11,10 @@ This package implements functions for the analysis of pupillometric data. Featur
 - Homepage/Documentation: <http://ihrke.github.com/pypillometry>
 
 
+---
+
+The project is maintained by Matthias Mittner <matthias.mittner@uit.no>
+
+To report a bug or recommend a new feature, please use [github's issue tracker](https://github.com/ihrke/pypillometry/issues).
+
+For more details about how to contribute, please see the [contribution-section](https://ihrke.github.io/pypillometry/html/docs/dev.html) in the documentation.
diff --git a/docs/html/_sources/docs/dev.rst.txt b/docs/html/_sources/docs/dev.rst.txt
@@ -1,28 +1,54 @@
+.. currentmodule:: pypillometry.pupildata
+
 Developers
 ==========
 
 .. image:: https://travis-ci.com/ihrke/pypillometry.svg?branch=master
     :target: https://travis-ci.com/ihrke/pypillometry
 
-Contibuting
------------
+This package is developed and maintained by the `Cognitive Neuroscience Research Group <http://uit.no/research/cognitive-neuroscience>`_ at the `University of Tromsø <http://uit.no>`_. We encourage everyone to become a member of the team and to contribute to the package's development, either by `reporting bugs  <https://github.com/ihrke/pypillometry/issues>`_, `providing enhancements <https://github.com/ihrke/pypillometry/pulls>`_ or otherwise.
+
+How to contribute
+-----------------
 
 Development of this package happens on GitHub: https://github.com/ihrke/pypillometry
 
-- Issue-tracker: https://github.com/ihrke/pypillometry/issues
-- PR's welcome: https://github.com/ihrke/pypillometry/pulls
+In order to contribute, please use
+
+- `github's issue tracker <https://github.com/ihrke/pypillometry/issues>`_ for reporting bugs or proposing enhancements
+- `github's pull-request (PR) feature <https://github.com/ihrke/pypillometry/pulls>`_ for contributing to the package and/or documentation
+
+If you are unfamiliar with Github's system, you can read up about `collaborating with issues and pull-requests on Github <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
+
+
+Coding style/package architecture
+---------------------------------
+
+We chose to put most functionality directly below :mod:`pypillometry`'s main class :class:`PupilData`. This is mostly for convenience,
+as users can easily find and chain commands together (see the following page more on this: :ref:`Pipeline-based processing in pypillometry </docs/pipes.ipynb>`).
+
+The implementation of the functionality, however, is coded in submodules using "stateless" functions that take :mod:`numpy`-arrays as arguments. So, in order to create a new function that changes a :class:`PupilData`-object, you will first want to implement a function working purely on :mod:`numpy`-arrays and then create a thin wrapper function below :class:`PupilData` that calls this low-level function with the correct arguments.
 
-Building docs
--------------
+Unit-testing
+------------
 
-A couple of non-standard sphinx extensions are being used:
+Every newly developed function should be provided with `Unit-testing functions <https://en.wikipedia.org/wiki/Unit_testing>`_. As a minimum, the function should be called with some reasonable arguments to ensure that the function does not crash. Better yet, the results of the functions should be tested against the desired output within these test functions. All unit-tests are located in `/pypillometry/tests/` and are run automatically for every commit to Github using `Travis CI <https://travis-ci.com/ihrke/pypillometry>`_. 
+
+Building the packages documentation
+-----------------------------------
+
+This is only necessary when extending `pypillometry`'s documentation (i.e., updating the website at https://ihrke.github.io/pypillometry).
+
+The package uses the `Sphinx documentation generator <https://www.sphinx-doc.org/>`_ to create this website. All source-files are located under `/docs/` (both `.rst` and `.ipynb` files are being used). In addition, the API-documentation is placed within each function or classes' docstring.
+
+To compile the documentation, sphinx must be installed. In addition, a couple of non-standard sphinx extensions are being used:
 
 .. code-block:: python
 
     ['sphinx_math_dollar',  "m2r",'sphinx_autodoc_typehints', 'nbsphinx']
 
 
-Installation: 
+These can be installed by using the following commands:
 
 
 .. code-block:: bash
@@ -36,6 +62,14 @@ Installation:
     # for the typehints
     conda install -c conda-forge sphinx-autodoc-typehints
 
+Finally, the documentation can be created by running
+
+.. code-block:: bash
+
+    make html
+    
+in the packages' root-directory. 
+
 .. warning::
 
     don't run `make clean`, it will delete the source-files from `docs`
diff --git a/docs/html/_sources/docs/modeling.ipynb.txt b/docs/html/_sources/docs/modeling.ipynb.txt
diff --git a/docs/html/_sources/paper/paper.md.txt b/docs/html/_sources/paper/paper.md.txt
@@ -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
diff --git a/docs/html/docs/api.html b/docs/html/docs/api.html
@@ -18,7 +18,7 @@
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" />
     <link rel="next" title="Developers" href="dev.html" />
-    <link rel="prev" title="Overview" href="usage.html" /> 
+    <link rel="prev" title="Example: Preprocessing of a full dataset with multiple subjects" href="preproc_example_pavlov.html" /> 
   </head><body>
     <div class="related" role="navigation" aria-label="related navigation">
       <h3>Navigation</h3>
@@ -33,7 +33,7 @@ <h3>Navigation</h3>
           <a href="dev.html" title="Developers"
              accesskey="N">next</a> |</li>
         <li class="right" >
-          <a href="usage.html" title="Overview"
+          <a href="preproc_example_pavlov.html" title="Example: Preprocessing of a full dataset with multiple subjects"
              accesskey="P">previous</a> |</li>
         <li class="nav-item nav-item-0"><a href="../index.html">pypillometry  documentation</a> &#187;</li> 
       </ul>
@@ -783,7 +783,7 @@ <h2>erpd.py<a class="headerlink" href="#erpd-py" title="Permalink to this headli
 <li><p><strong>overlays</strong> (single or sequence of <code class="xref py py-class docutils literal notranslate"><span class="pre">ERPDSingleSubject</span></code>-objects) – the overlays will be added to the same plot</p></li>
 <li><p><strong>meanfct</strong> (<em>callable</em>) – mean-function to apply to the single-trial ERPDs for plotting</p></li>
 <li><p><strong>varfct</strong> (<em>callable</em><em> or </em><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.8)"><em>None</em></a>) – function to calculate error-bands (e.g., <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.std.html#numpy.std" title="(in NumPy v1.18)"><code class="xref py py-func docutils literal notranslate"><span class="pre">numpy.std()</span></code></a> for standard-deviation
-or <a class="reference external" href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.sem.html#scipy.stats.sem" title="(in SciPy v1.4.1)"><code class="xref py py-func docutils literal notranslate"><span class="pre">scipy.stats.sem()</span></code></a> for standard-error)
+or <a class="reference external" href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.sem.html#scipy.stats.sem" title="(in SciPy v1.5.0)"><code class="xref py py-func docutils literal notranslate"><span class="pre">scipy.stats.sem()</span></code></a> for standard-error)
 if None, no error bands are plotted</p></li>
 <li><p><strong>plot_missing</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.8)"><em>bool</em></a>) – plot percentage interpolated/missing data per time-point?</p></li>
 </ul>
@@ -1548,8 +1548,8 @@ <h3><a href="../index.html">Table of Contents</a></h3>
 </ul>
 
   <h4>Previous topic</h4>
-  <p class="topless"><a href="usage.html"
-                        title="previous chapter">Overview</a></p>
+  <p class="topless"><a href="preproc_example_pavlov.html"
+                        title="previous chapter">Example: Preprocessing of a full dataset with multiple subjects</a></p>
   <h4>Next topic</h4>
   <p class="topless"><a href="dev.html"
                         title="next chapter">Developers</a></p>
@@ -1587,7 +1587,7 @@ <h3>Navigation</h3>
           <a href="dev.html" title="Developers"
              >next</a> |</li>
         <li class="right" >
-          <a href="usage.html" title="Overview"
+          <a href="preproc_example_pavlov.html" title="Example: Preprocessing of a full dataset with multiple subjects"
              >previous</a> |</li>
         <li class="nav-item nav-item-0"><a href="../index.html">pypillometry  documentation</a> &#187;</li> 
       </ul>