Contributing / Developer Guide

This guide is for contributors and developers who want to work on PixelMap.

Development Setup

Prerequisites

  • Python 3.10+

  • uv (recommended) or pip

Installation

git clone https://github.com/m-beau/pixelmap.git
cd pixelmap

# Install with dev dependencies
uv sync

# Or with pip
pip install -e ".[dev]"

Running Locally

# Launch the GUI
uv run pixelmap

# Or if installed with pip
pixelmap

Architecture Overview

pixelmap/
├── __init__.py          # Public API exports
├── backend.py           # Core electrode selection logic
├── constants.py         # Probe configurations and presets
├── types.py             # Data classes (Electrode, etc.)
├── gui/
│   ├── gui.py           # Panel frontend
│   ├── app_util.py      # GUI helper functions
│   └── assets/          # Images and static files
├── utils/
│   └── imro.py          # IMRO file reading/writing
└── wiring_maps/         # CSV/JSON files defining electrode-ADC wiring

Key Modules

backend.py

Core logic for electrode selection and validation. Handles ADC wiring constraints via find_forbidden_electrodes() and generates valid channel configurations.

gui/gui.py

Browser-based interface built with NiceGUI. Handles user interactions, electrode visualization, and IMRO file downloads.

utils/imro.py

Functions for reading, writing, and parsing IMRO files. The generate_imro_channelmap() function is the main entry point for programmatic use.

constants.py

Probe group definitions, electrode counts, and preset configurations. Edit this when adding new probe types or presets.

types.py

Data classes used throughout the codebase, including the Electrode class.

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=pixelmap

# Run specific test file
pytest tests/test_backend.py

Writing Tests

Tests are in the tests/ directory. When adding new functionality:

  1. Add tests for the new feature

  2. Ensure existing tests still pass

  3. Aim for coverage of edge cases

Code Style

We use Ruff for linting and formatting:

# Check for issues
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

Adding New Probe Types

To add support for a new probe (e.g., Quadbase, NXT):

  1. Add wiring map: Create wiring_maps/<probe_type>_wiring.csv defining electrode-to-ADC mappings

  2. Update constants: In constants.py, add entries to:

    • PROBE_TYPE_MAP - SpikeGLX probe types

    • PROBE_N - Electrode and channel counts

    • SUPPORTED_*_PRESETS - Available presets (if applicable)

  3. Update GUI: In gui/gui.py, add the probe to the dropdown options

  4. Add tests: Create tests for the new probe type

  5. Update docs: Add to the supported probes table in index.md and README.md

Contributing

To contribute:

  1. Fork the repository

  2. Create a branch with a descriptive name (e.g., feature/your-feature-name or fix/bug-description)

  3. Make your changes and run tests: pytest

  4. Push to your fork and open a pull request to the dev branch

See CONTRIBUTING.md for full guidelines on reporting bugs, requesting features, and code style.