PixelMap: a browser-based GUI to generate Neuropixels channelmaps

⚡ Generate IMRO channelmaps for Neuropixels probes ⚡
⚡ that respect electrode-ADC wiring constraints! ⚡

>>> Online GUI <<<

Purpose of PixelMap:

• Convenient browser-based generation of .imro files for SpikeGLX.
  • IMRO tables are used to tell SpikeGLX what channels to record from (Neuropixels feature more physical electrodes than can be recorded from simultaneously); what reference to use; and sometimes recording amplification gain (1.0 only).
• Enables arbitrary selection of electrode geometries, within the boundaries of Neuropixels electrode-ADC hardware wiring constraints
• Common presets available out of the box (reach out to suggest other common geometries!)
• Option to load pre-existing .imro file as starting point (or simply to remember the probe geometry of a specific file)

Disclaimer: this tool is in beta release and should be considered a work in progress, deployed early to gather feedback. The imro editor tools in SpikeGLX and Open Ephys work correctly. What we are providing here are tools to specify imro tables more easily and conveniently. However, it will take some time to debug all the issues in this beta. If you import one of our tables into SpikeGLX or Open Ephys, please be sure to double check that all the site selections, referencing, gains, and filter settings that get imported are what you intended.

Local installation

Clone the repository and navigate to it:

git clone http://github.com/m-beau/channelmap_generator.git
cd channelmap_generator

With uv, you can either install dependencies first and then run the application, or run it directly in one command:

uv sync # install dependencies alone
uv run cmap_gui # install dependencies automatically and run

This approach is particularly convenient as uv will automatically create a virtual environment, install all dependencies from pyproject.toml, and run the GUI in a single command.

Using pip or docker

Install the package using pip

In this case, you must create a virtual environment yourself, e.g. a new conda environment:

conda create -n my_environment python=3.12
conda activate my_environment
uv pip install . # fast! run pip install uv first.
# or traditionally with pip only:
pip install .

Run using Docker (Installation-free)

Run the latest stable Docker image directly without any local installation. The application will be available at http://localhost:5008.

docker run --rm --name channelmap-app -p 5008:5008 --pull=always ghcr.io/m-beau/channelmap_generator:latest # add --platform linux/amd64 on M1 macs or linux machines

For a more robust deployment, use Docker Compose. See the included docker-compose.yml for configuration details.

Usage

Step 1. Use the app to make and download your channelmap (.imro file)

Option 1 - Browser-based GUI

Either use the online gui, or launch it locally from the cloned repository using one of these methods:

# If you're using uv (recommended):
uv run cmap_gui  # Automatically manages dependencies and virtual environment
# If you installed with pip:
cmap_gui  # Alias for: python ./channelmap_generator/gui/gui.py

Neuropixels electrodes are hardwired to specific ADCs in the probe's head. When you select an electrode, others become unavailable because they share the same recording lines. This GUI allows you to build a channelmap around those constraints: when you select channels, they turn red, and those that become unavailable because they share the same lines turn black.

Warning

If SpikeGLX seems to ignore the .imro file when you try to load it, make sure that the probe subtype is correct. You can find the subtype as the first number of the first tuple of the probe's imro table, either in the default .imro file made by SpikeGLX (save it to file though the IM setup tab), or in the .meta file saved alongside any recording from that probe (~imroTbl field, the last field of the file).

You can mix and match four selection methods:
• Presets: Pre-configured channelmaps that respect wiring constraints
• Textual selection: Type electrode ranges (e.g., "1-10,20-25") to add to the current selection
• Interactive: Click electrodes directly or drag boxes (selection, deselection, or "zigzag selection") to manually select multiple sites
• Selection from pre-existing IMRO file: you can pre-load an IMRO file as a starting point before doing any of the above.

Once you reach the target number of electrodes for the selected probe type (384 or 1536), you can download your channelmap as an IMRO file alongside a PDF rendering to easily remember what your channelmap looks like.

Tip

Online version: This GUI is available online at https://neuropixels-channelmap-generator.pni.princeton.edu - you can use it directly in your browser without installing anything.

Option 2 - Python API / Jupyter Notebook

Check out the code in generate_channel_maps.ipynb to reproducibly create custom channel maps. The notebook provides examples for all supported probe types and presets.

Here's a MWE:

import channelmap_generator as cmg

# Generate a channel map
imro_list = cmg.generate_imro_channelmap(
    probe_type="2.0-4shanks",
    layout_preset="tips_all",
    wiring_file="wiring_maps/2.0-4shanks_wiring.csv"
)

# Save to file
cmg.save_to_imro_file(imro_list, "my_channelmap.imro")

Step 2. Load the IMRO file in SpikeGLX

Like you would with any .imro file (see SpikeGLX documentation).

• Before initiating the recording: through the IM-Setup tab
• Once the recording has started: through the live probe view (the probe-shaped heatmap that represents ongoing activity across the whole shank)

Troubleshooting

The online GUI is unresponsive!
Reloading the page should fix most issues. If you have crappy network on your machine, consider installing it locally (see installation section above).

SpikeGLX ignores my .imro file upon upload!
If SpikeGLX seems to ignore the .imro file when you try to load it, make sure that the probe subtype is correct. You can find the subtype as the first number of the first tuple of the probe's imro table, either in the default .imro file made by SpikeGLX (save it to file though the IM setup tab), or in the .meta file saved alongside any recording from that probe (~imroTbl field, the last field of the file).

After loading the .imro file, SpikeGLX IMRO editing options become greyed out!
This is expected behavior for non-canonical IMRO tables. SpikeGLX greys out editing features for imported tables that don't match its canonical format (being whole/half-shank width boxes that enclose all AP channels with attributes for all channels). This allows SpikeGLX to use external tables "as is" without knowing how to modify them safely. If you need to make adjustments, use the online gui again: upload your .imrofile as a starting point, then modify your .imrotable before re-downlading it and re-importing into SpikeGLX.

Testing

PixelMap includes a comprehensive automated test suite to ensure software reliability. The tests cover:

• Hardware constraint validation
• All preset configurations for supported probe types
• IMRO file generation and I/O operations
• End-to-end workflows

Running Tests Locally

# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest tests/

# Run tests with coverage report
pytest tests/ --cov=channelmap_generator --cov-report=term

Continuous Integration

Tests run automatically via GitHub Actions on every push and pull request. The test status badge shows whether all tests are passing:

Roadmap

Supported Neuropixels versions:

• 1.0
• 2.0, 1-shank
• 2.0, 4-shanks
• Quadbase
• NXT

UHD and opto currently not on our roadmap, reach out if you need it implemented.