Stimupy

A pure-Python package for creating new and existing visual stimuli commonly used in the study of contrast, brightness, lightness, and other aspects of visual perception.

---

• documentation: https://stimupy.readthedocs.io/en/latest/
• source code: https://github.com/computational-psychology/stimupy

---

stimupy has been designed to:

• generate (novel) visual stimuli in a reproducible, flexible, and easy way
• recreate exact stimuli as they have been used in prior vision research
• explore large parameter spaces to reveal relations between formerly unconnected stimuli
• provide classic stimulus sets (e.g. ModelFest), exactly as described in the original manuscripts (including experimental data)
• build new stimulus sets or benchmarks (e.g. for testing computational models), and easily add them to stimupy
• support vision science by providing a large, openly-available and flexible battery of relevant stimulus functions
• unify and automate stimulus creation
• be FAIR: Findable, Accessible, Interoperable, and Reusable

---

Core features:

Stimupy has been designed to generate stimuli from code, so that they are reproducible, flexible, and easy.

• basic visual stimulus components, such as basic shapes, wave gratings, Gaussians

• visual noise textures, of different kinds,

• many different parameterized visual stimuli

  • Gabors, plaids, edges,
  • a variety of so-called illusions (e.g. Simultaneous Brightness Contrast, White's illusion, Hermann grid, Ponzo illusion), and many more

• exact replications of stimuli previously published (e.g. ModelFest) as described in their respective papers

• all stimuli are fully parameterizable

  • with interpretable parameters that are familiar and relevant to vision scientists (e.g. visual angle, spatial frequency, target placements).
  • This also makes it possible to explore stimulus parameter spaces which might reveal relations between formerly unconnected stimuli

• stimuli are composable/composed:

  • stimuli tend to be composed from several components, and these provided building blocks and masks can be used to assemble more complicated geometries

• flexible output structures

  • generated stimuli are Python dictionary
    • mutable data structures (compared to objects), so they allow the user to add additional information easily (e.g. stimulus descriptions, stimulus masks, experimental data).
  • containing the stimulus-image as a NumPy-array,
    • makes images fully interoperable using common NumPy tooling (rather than, e.g., an OpenGL texture),
  • together with other useful stimulus-specific information (e.g. (target) masks, sizes etc.).

• modular and therefore easy to extend with new stimulus functions, and new stimulus sets

• utility functions for stimulus import, export, manipulation (e.g. contrast, size), or plotting

• application-oriented documentation documentation, including interactive demonstrations of stimulus functions

• unit and integration tests

See the documentation for more details

---

Citing stimupy

If you use stimupy for your scientific work, please cite the paper as:

Schmittwilken, L., Maertens, M., & Vincent, J. (2023). stimupy: A Python package for creating stimuli in vision science. Journal of Open Source Software, 8(86), 5321. https://doi.org/10.21105/joss.05321

Here is a BibTeX entry for this reference:

@article{Schmittwilken2023,
    doi = {10.21105/joss.05321},
    url = {https://doi.org/10.21105/joss.05321},
    year = {2023},
    publisher = {The Open Journal},
    volume = {8},
    number = {86},
    pages = {5321},
    author = {Lynn Schmittwilken and Marianne Maertens and Joris Vincent},
    title = {stimupy: A Python package for creating stimuli in vision science},
    journal = {Journal of Open Source Software}
}

Your stimulus (set) is not here?

Given the modular nature of the package, any stimulus or stimulus set not currently available, can be easily added. Open an issue and let us know what you'd like to see added.

If you want to contribute yourself, see contributing

---

Installation

pip can install stimupy directly PyPI:

pip install stimupy

OR (for developers), install from source:

1. Clone the repository from GitHub:

   git clone git@github.com:computational-psychology/stimupy.git

2. stimupy can then be installed using pip. From top-level directory run:

   pip install .

   to install to your local python library.

To install in developer/editable mode: pip install -e . at the root directory. This makes changes to files immediately usable, rather than having to reinstall the package after every change.

Dependencies

Dependencies should be automatically installed (at least using pip). stimupys required dependencies are:

• NumPy
• SciPy
• matplotlib
• Pillow
• pandas