Interactive Figure

This package serves for students to learn the basics of Python, Matplotlib and setting up reaction time experiments (visual search task, Stroop task, etc.). For a more accurate timing environment one should refer to e.g. PsychoPy.

This is currently used at the University of Amsterdam (UvA) in the courses Introduction to Python Programming for Neuroscientists and Experimentatie - Inleiding Programmeren.

Development and packaging are managed with uv.

Installation

Requires Python 3.11 or newer. To add the package to a uv project:

uv add interactive-figure

You can also install it with pip:

pip install interactive-figure

Usage

import interactive_figure as ifig

ifig.create()
# Wait until user input is received.
ifig.wait_for_interaction()
key = ifig.get_last_key_press()
print(f"Pressed key: {key}")
ifig.close()

Each edge of the axes frame can be hidden independently. For example, to keep only the bottom and left edges:

ifig.create(hide_top_frame=True, hide_right_frame=True)

The four options are hide_top_frame, hide_right_frame, hide_bottom_frame, and hide_left_frame, all defaulting to False. Set all four to True to hide the entire frame. Axis labels are controlled separately with hide_x_labels and hide_y_labels. Frame options are reapplied when ifig.clear() is called.

Demos can be found in the demo folder on GitHub.

Limitations

• Waiting for user input will not work in Jupyter Notebooks and the interactive interpreter due to the way Matplotlib handles events.
• Automated testing is hard since tests should cover multiple backends (macosx, QtAgg, Tkgg) on multiple platforms (Windows, macOS, Linux). Tips are very welcome!

Development

Install uv, then run these commands from the repository root:

# Create the project environment and install development tools.
uv sync

# Run a demo (requires a graphical desktop).
uv run python demo/usage.py

# Check formatting, lint, and types.
uv run black --check --diff .
uv run ruff check .
uv run mypy src/interactive_figure

# Format and fix lint issues.
uv run black .
uv run ruff check --fix .

uv manages the project environment in .venv; uv run uses it automatically without manual activation. If your shell has another virtual environment activated, run deactivate or open a fresh terminal before using uv.

The dev dependency group includes the lint tools. Documentation dependencies are in the separate docs group. Commit uv.lock to keep development dependencies reproducible. There is currently no automated test suite; use the demos to check GUI behavior.

Documentation

# Install the docs dependencies and build the HTML documentation.
./generate_docs.sh

# Or run Sphinx directly.
uv run --group docs sphinx-build -b html docs_source docs

Both commands use the existing configuration in docs_source/conf.py and write HTML to docs/.

Releases

The package version is maintained in pyproject.toml, and packages are built with uv_build. For example, to release version 0.6.0:

# Set the next release version.
uv version 0.6.0

# Build a wheel and source distribution.
uv build

# Publish this release to PyPI using a PyPI API token.
# Set UV_PUBLISH_TOKEN in your environment before running this command.
uv publish dist/interactive_figure-0.6.0*

Use the chosen release version in the upload filename pattern so only that release's artifacts are published.

Links

• GitHub
• PyPI
• Documentation