diff --git a/paper/paper.md b/paper/paper.md index 44757ff..e74a112 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -43,16 +43,16 @@ PixelMap is a browser-based application for creating custom channelmaps for Neur # Statement of need -Neuropixels probes have revolutionised systems neuroscience by enabling simultaneous recordings from hundreds of neurons across multiple brain regions at any depth [@jun2017; @beau2021; @steinmetz2021; @bondy2024; @ye2025; @beau2025]. However, configuring these probes presents challenges. Limited by the number of readout channels and integrated analogue-to-digital converters (ADCs), Neuropixels probes contain 960–5120 physical electrodes per shank but can only record from 384–1536 channels simultaneously (Table 1). Users must therefore select a subset of electrodes to activate for each recording, forming a "channelmap". +Neuropixels probes have revolutionised systems neuroscience by enabling simultaneous recordings from hundreds of neurons across multiple brain regions at any depth [@jun2017; @beau2021; @steinmetz2021; @bondy2024; @ye2025; @beau2025]. However, configuring these probes presents challenges. Limited by the number of readout channels and integrated analogue-to-digital converters (ADCs), Neuropixels probes contain 960–5120 physical electrodes per shank but can only record from 384–1536 channels simultaneously (Table 1). Users must therefore select a subset of electrodes to activate for each recording, forming an electrode selection set colloquially called "channelmap". -Because readout lines within each shank and ADCs in the probe head are each shared by multiple physical electrodes, activating one electrode makes others unavailable. For Neuropixels 1.0, these dependencies follow a regular, bank-aligned pattern that is relatively intuitive. With single-shank Neuropixels 2.0 probes [@steinmetz2021], whose wiring is intentionally scrambled to enable recording from several banks simultaneously, and four-shank Neuropixels 2.0 probes, whose wiring become untractable due to the high number of electrode banks, the inter-electrode incompatibilities become difficult to anticipate manually. The difficulty compounds when multiple probes are used simultaneously: experiments can use up to eight simultaneous Neuropixels probes [@bondy2024], each requiring its own valid channelmap, making a reliable wiring-aware design tool increasingly essential as experimental scale grows. +Because readout lines within each shank and ADCs in the probe head are each shared by multiple physical electrodes, activating one electrode makes others unavailable. For Neuropixels 1.0, these dependencies follow a regular, bank-aligned pattern that is relatively intuitive. With single-shank Neuropixels 2.0 probes [@steinmetz2021], whose wiring is intentionally scrambled to enable recording from several banks simultaneously, and four-shank Neuropixels 2.0 probes, whose wiring become untractable due to the high number of electrode banks, the inter-electrode incompatibilities become difficult to anticipate. -Beyond satisfying hardware constraints, channelmaps must be tailored to the experiment. Before implantation, researchers plan which brain regions each probe will traverse given its intended insertion trajectory; this requires mapping anatomical boundaries onto the physical electrode layout. After implantation — whether in a chronic preparation where the probe remains in place for weeks, or an acute preparation on the same day as surgery — researchers must adjust their channelmap based on observed neural activity. Sites with high neural activity typically correspond to grey matter with neuron somata, which should be recording with the highest priority. The most effective workflow is therefore iterative: plan anatomically before implantation, survey activity afterwards, and refine the channelmap to maximise unit yield in the target regions. Developing a tool to support this workflow within the Brody laboratory — which reuns experiments featuring eight probes simultaneously [@bondy2024] — motivated the creation of PixelMap, which is now made available to the wider community. PixelMap addresses these needs by: +Beyond satisfying hardware constraints, channelmaps must be tailored to the experiment. Before implantation, researchers plan which brain regions each probe will traverse given its intended insertion trajectory; this requires mapping anatomical boundaries onto the physical electrode layout. After implantation, either in a chronic preparation where the probe remains in place for weeks, or an acute preparation on the same day as surgery, researchers must adjust their channelmap based on observed neural activity. Sites with large extracellular waveforms typically correspond to areas with a high density of neuron somata and axon initial segments (grey matter), which can be used to identify target regions entry and exit points. The typical workflow is therefore the following: plan anatomically before implantation, survey activity afterwards, and refine the channelmap to maximise unit yield in the target regions. The difficulty compounds when multiple probes are used simultaneously: experiments can use up to eight simultaneous Neuropixels probes [@bondy2024], each requiring to iterate on its own valid channelmap, making a fast and reliable wiring-aware design tool increasingly essential. Developing a tool to support this workflow within the Brody laboratory motivated the creation of PixelMap, which addresses these needs by: 1. **Being available on any machine installation-free**: The tool is available both as a browser-based web application at [https://pixelmap.pni.princeton.edu](https://pixelmap.pni.princeton.edu), as a Docker image, and a Python package. 2. **Visualising in real time Neuropixels wiring constraints, interactively**: When users select electrodes, the interface immediately shows which other electrodes become unavailable (marked in black) due to shared ADC lines, preventing invalid configurations. -3. **Supporting arbitrary electrode geometries**: Users can select electrodes by 1) choosing from common preset geometries, 2) entering electrode ranges as text for reproducibility, 3) directly clicking or dragging on the probe visualization, or 4) loading pre-existing `.imro` files. These four selection methods are fully intercompatible and can be combined. See the [documentation](https://pixelmap-neuropixels.readthedocs.io/en/latest/) for details on supported preset geometries and selection methods, in particular the five different dragging boxes that enable great flexibility in electrode selection. -4. **Guiding channelmap design with activity and anatomy information**: Users can overlay a SpikeGLX activity survey heatmap to identify the most spiking-active channels after probe implantation, and independently overlay anatomical region boundaries from any brain atlas available through BrainGlobe [@claudi2020] to plan recordings around specific brain regions of interest. +3. **Supporting arbitrary electrode geometries**: Users can select electrodes by 1) choosing from common preset geometries, 2) entering electrode ranges as text for reproducibility, 3) directly clicking or dragging on the probe visualization, or 4) loading pre-existing `.imro` files. These four selection methods are fully intercompatible and can be combined. See the documentation [https://pixelmap-neuropixels.readthedocs.io](https://pixelmap-neuropixels.readthedocs.io/en/latest/) for details on supported preset geometries and selection methods, in particular the five different dragging boxes that enable great flexibility in electrode selection. +4. **Guiding channelmap design with anatomy and activity overlays**: Users can overlay anatomical region boundaries from any brain atlas available through BrainGlobe [@claudi2020] to plan recordings around specific brain regions of interest, and **simultaneously** a SpikeGLX activity survey heatmap to identify the most spiking-active channels after probe implantation. | Probe Version | Physical Channels | Simultaneously Recordable Channels | |---------------|-------------------|-------------------------------------| @@ -65,13 +65,13 @@ Beyond satisfying hardware constraints, channelmaps must be tailored to the expe # State of the Field -SpikeGLX [@karsh_spikeglx] and Open Ephys [@siegle2017], the two most widely used systems for acquiring Neuropixels data, allow channelmap editing but their primary purpose is to enable reliable data acquisition. Both are designed to run and monitor recordings; their priorities are stable high-throughput streaming, synchronisation with auxiliary data streams, and online visualisation. In both, channelmap editing is a configuration step performed at the rig, on the machine connected to the probe, and is optimised for fast on-the-fly setup at recording time. SpikeGLX's editor is also the field's authoritative reference for wiring constraints, since it obtains the electrode-to-readout correspondence directly from the manufacturer (IMEC); for this reason, PixelMap takes its version-specific constraints from this same source and, like SpikeGLX, writes channelmaps as `.imro` files. NeuroCarto [@su2025], a recently published browser-based editor that runs locally, offers a GUI that is built around a novel automated channelmap-generation algorithm: the user specifies a target electrode density for each region along the shank, and a channelmap meeting those constraints is generated. +SpikeGLX ([https://billkarsh.github.io/SpikeGLX](https://billkarsh.github.io/SpikeGLX)) and Open Ephys ([https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Neuropixels-PXI.html](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Neuropixels-PXI.html)), the two most widely used systems for acquiring Neuropixels data, allow channelmap editing but their primary purpose is to enable reliable data acquisition. Both are designed to run and monitor recordings; their priorities are stable high-throughput streaming, synchronisation with auxiliary data streams, and online visualisation. In both, channelmap editing is a configuration step performed at the rig, on the machine connected to the probe, and is optimised for fast on-the-fly setup at recording time. SpikeGLX's editor is also the field's authoritative reference for wiring constraints, since it obtains the electrode-to-readout correspondence directly from the manufacturer (IMEC); for this reason, PixelMap takes its version-specific constraints from this same source and, like SpikeGLX, writes channelmaps as `.imro` files. NeuroCarto [@su2025], a recently published browser-based editor that runs locally, offers a GUI that is built around a novel automated channelmap-generation algorithm: the user specifies a target electrode density for each region along the shank, and a channelmap meeting those constraints is generated. PixelMap, by contrast, is built with the primary purpose of being a no-install generalist Neuropixels channelmap design tool. It brings together in a single tool the features otherwise distributed across the solutions above, including real-time visualisation of wiring constraints, `.imro` output from the same IMEC source, an interactive click-and-drag electrode selection editor, and anatomical reference, and adds several capabilities not available elsewhere. First, PixelMap is the only solution that requires no installation: it is hosted at [https://pixelmap.pni.princeton.edu](https://pixelmap.pni.princeton.edu) as a web app backed by a Docker image, and is also distributed as a Python package and a programmatic API, so a channelmap can be built on any machine without desktop acquisition software or a connected probe. Second, probe support follows the authoritative reference. Probe-group and subgroup definitions, which impact electrode wiring constraints as well as `.imro` file formats, are read from the source maintained by the SpikeGLX developer (see Acknowledgements and [http://billkarsh.github.io/SpikeGLX/help/imroTables](http://billkarsh.github.io/SpikeGLX/help/imroTables)). New probe types can become supported easily as they are added to SpikeGLX; current coverage is Neuropixels 1.0, 2.0 single- and four-shank, and 2.0 Quad Base. PixelMap also exposes the full probe-dependent `.imro` metadata, including the Neuropixels 1.0 hardware filter and gain settings and the electrode reference (external, tip, or join-tips). Third, PixelMap allows arbitrary electrode geometries: in addition to a large set of custom preset geometries, text entry of electrode ranges, and an `.imro` loader, it provides five drag-box tools, among them interleaved and checkerboard selectors and a "deselect dependents" box, unique to PixelMap, that frees the electrodes blocking an unavailable target region. Fourth, PixelMap implements an anatomical overlay built on the BrainGlobe Atlas API [@claudi2020], which makes any BrainGlobe atlas available immediately. PixelMap computes the region each electrode traverses along a user-specified insertion trajectory, and renders named depth bands beside the probe with three orthogonal atlas slices through the tip. Fifth, PixelMap provides an activity overlay that places a SpikeGLX activity survey next to the probe for channelmap refinement. Critically, the anatomical and activity overlays can be displayed simultaneously during electrode selection, which is very helpful for experiment planning and is not offered by any of the currently available software. # Software Design -PixelMap is implemented in Python using [Holoviz Panel](https://panel.holoviz.org/) for the web interface, providing an interactive and responsive user experience. The software architecture consists of four main components. +PixelMap is implemented in Python using [Holoviz Panel](https://panel.holoviz.org/) for the web interface, providing an interactive and responsive user experience. The software architecture consists of three main components. First, the **probe type database and wiring maps** (distributed in `./constants.py`. `./utils/probe_features.py`, `./wiring_maps/*`) derives the mapping between probe part numbers, SpikeGLX probe type identifiers, and IMRO format numbers directly from the authoritative source maintained by SpikeGLX developer Bill Karsh. This provides both accuracy and forward compatibility with new probe versions as they are added to SpikeGLX. The **wiring maps** at `./wiring_maps/*.csv` are CSV files describing the electrode-to-ADC mappings for each supported probe type. They were adapted from files provided by IMEC (Neuropixels manufacturer - downloadable [here](https://www.neuropixels.org/support)) and SpikeGLX (https://github.com/billkarsh/SpikeGLX/tree/a9024ba79f4481883766f5468563accb74fd58fd/Src-imro). PixelMap currently supports Neuropixels 1.0, 2.0 single-shank, 2.0 four-shank, and 2.0 Quad Base probes. diff --git a/paper/paper.pdf b/paper/paper.pdf index 0b42306..b3691d1 100644 Binary files a/paper/paper.pdf and b/paper/paper.pdf differ