Developers

This package is developed and maintained by the Cognitive Neuroscience Research Group at the University of Tromsø. We encourage everyone to become a member of the team and to contribute to the package’s development, either by reporting bugs, providing enhancements or otherwise.

Major versions

Pypillometry switched to version 2 in March 2025. This introduces breaking changes to the API.

Logging

The package uses the loguru package for logging. The log-level can be set by the user using the pypillometry.logging_set_level()-function. By default, the log-level is set to INFO.

For more detailed logging of specific sub-modules, use

import pypillometry as pp
pp.disable_logging()
pp.logger.enable("pypillometry.submodule")

How to contribute

Development of this package happens on GitHub: https://github.com/ihrke/pypillometry

In order to contribute, please use

If you are unfamiliar with Github’s system, you can read up about collaborating with issues and pull-requests on Github.

Coding style/package architecture

We chose to put most functionality directly below pypillometry’s main class PupilData. This is mostly for convenience, as users can easily find and chain commands together (see the following page more on this: Pipeline-based processing in pypillometry).

The implementation of the functionality, however, is coded in submodules using “stateless” functions that take numpy-arrays as arguments. So, in order to create a new function that changes a PupilData-object, you will first want to implement a function working purely on numpy-arrays and then create a thin wrapper function below PupilData that calls this low-level function with the correct arguments.

Documenting code

We use the NumPy style for the docstrings.

Every class or function should have a docstring that explains what it does, what the arguments are and what the return value is. See the code for examples.

Unit-testing

Every newly developed function should be provided with Unit-testing functions. 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.

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 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:

['sphinx_math_dollar',  "sphinx-mdinclude",'sphinx_autodoc_typehints', 'nbsphinx']

These can be installed by using the following commands:

# jupyter notebooks
conda install -c conda-forge nbsphinx
# math
conda install -c conda-forge sphinx-math-dollar
# markdown 2 rst (for README)
pip install sphinx-mdinclude
# for the typehints
conda install -c conda-forge sphinx-autodoc-typehints

Finally, the documentation can be created by running

make html

in the packages’ root-directory.

Warning

don’t run make clean, it will delete the source-files from docs

Creating Releases

A release should be created whenever crucial bugs have been fixed or new functionality has been added. pypillometry goes with version numbers x.y.z. Increment z for bug-fixes, y for new features and x for releases that break backward-compatibility.

Note

the process of uploading to PyPI has been automatized using Github actions; when a release is created on Github-releases, the file VERSION is updated with the most recent tag (must be PEP-440-compliant) and a PyPI release is being issued