We have developed a Python toolkit, NeuroCarto, for the construction and manipulation of custom channel maps for the Neuropixels probe family. The toolkit provides convenience functions for creating block-based channel maps, in which channels are uniformly distributed along one or more shanks at full-, half-, quarter-, or one-eighth-density (Fig. 3a, Online Resource 1). The main purpose of the toolkit is to support experimenters with constructing non-trivial custom channel maps that make the best use of the limited number of read-out channels (compared to the total number of available electrodes). Thus, experimenters may want to allocate more read-out channels to brain regions of most interest along the probe shanks.

The main steps to construct a custom channel map with NeuroCarto are as follows. First, experimenters need to determine which electrodes cover the brain regions of interest (such as cell layers) based on the implantation coordinates and depth, and further refined by observed signals along the probe. Second, using NeuroCarto’s functions or graphical interface, experimenters construct a “blueprint” that describes the desired distribution and priority of recording electrodes. Third, NeuroCarto automatically generates a channel map that closely follows the blueprint and does not violate the probe’s hardware restrictions. Finally, the experimenter checks the generated channel map and optionally makes adjustments to the selected electrodes before using the channel map in experiment.

An example blueprint is shown in Fig. 3b and features multiple zones with varying desired electrode densities, zones with excluded electrodes, and low-priority zones (see Online Resource 1 for a demonstration of how to use a blueprint with the toolkit). The current implementation assigns the highest priority to zones in the blueprint that were set to full electrode density, and stepwise lower priority to half- and quarter-density zones. Thus, when a blueprint is used to build a channel map, electrodes in full-density zones are selected first, followed by the lower-density zones. Finally, any remaining read-out channels are assigned to electrodes in the low-priority zones.

One possible channel map that was generated from the example blueprint is shown in Fig. 3c. As expected, the map contains all electrodes in the full-density zone and does not contain electrodes in the exclusion zones. Selected electrodes in the half-density zone on the second shank are arranged in a checkerboard pattern, except for a gap around 2.2 mm. For the quarter-density zones on the third and fourth shanks, the coverage is patchy, with the expected checkerboard pattern only on a limited part and a gap around 2.0 mm. As not all read-out channels were assigned to electrodes in the full/half/quarter-density zones, the channel map also contains electrodes in the low-priority zones that appear to be distributed non-uniformly.

The gaps, and irregular and non-uniform electrode distributions are fundamentally a consequence of the conflicts introduced by electrodes sharing the same read-out channel in combination with the selection priority. This demonstrates the challenge of constructing a custom channel map that follows an experimenter’s specifications. To provide more insight into the conflicts that arise when constructing a channel map, we show the state of the channel map and candidate electrodes for three selected iterations in the construction process (Fig. 3c). The electrodes in the full-density zone share read-out channels with blocks of electrodes that correspond to the gaps in the half- and quarter-density zones (Fig. 3d left). At later iterations, an increasing number of candidate electrodes conflict with previously selected electrodes, which explains the irregular and non-uniform electrode selection in the final channel map (Fig. 3d middle and right).

Given that electrodes are selected randomly among electrodes with equal priority, the same blueprint may lead to multiple distinct channel maps. To determine the probability that each electrode is part of the final channel map, we constructed 1000 channel maps from the blueprint in Fig. 3b and computed the average channel map (Fig. 3e). The selection probability values for electrodes in full- and half-density zones are close to the expected density as specified in the blueprint, except for a half-density zone around 2.2 mm on the second shank that conflicts with the full-density zone on the first shank. Large fractions of the quarter-density zone conflict with the full- and half-density zones, and the selection probability values for the corresponding electrodes are lower than expected based on the blueprint.

As the example shows, the probe’s hardware restrictions may significantly impact the final channel map for a given blueprint. If the read-out channel conflicts lead to an undesirable channel map, there are a few options that can be considered. First, conflicts may be reduced by changing the blueprint to focus on the most critical electrodes, for example by shrinking or (re)moving zones, or by reducing the electrode density requirements. A second option is to introduce more flexibility in the update rules, for example by allowing deviations from a strict checkerboard pattern for the half-density and quarter-density zones.

NeuroCarto Web Interface

NeuroCarto provides a Bokeh-based web interface (Fig. 4) for visualizing electrodes on a Neuropixels probe and manipulating the channel map or the blueprint. The following topics will cover the input/output files of the application, the basic visualization of the probe and background brain atlas image, manual electrode selection, and blueprint construction.

Input/Output files

The minimum information needed to construct a new channel map or blueprint is the type of neural probe. At present, the application provides built-in support for the Neuropixels probe family, including Neuropixels 1.0 and 2.0 (single-shank and 4-shank versions). Users can also start from an existing channel map by loading probe information and selected electrodes from Neuropixels-specific imro files (imec readout file) or metadata files generated by the SpikeGLX acquisition software.

Channel maps generated in NeuroCarto that are complete (i.e., use all read-out channels on the probe) are saved in an imro file that can be used to program the probe prior to recording. Project-specific configuration (storing the last state of the application) and any blueprint that was used to generate a channel map, are saved alongside the imro file in respectively a JavaScript Object Notation file (json-file, extension .config.json) and numpy array file (extension .blueprint.npy). The blueprint file can be saved separately when the channel map is incomplete.

Basic visualization

A view of all electrodes on the probe is shown in the central panel of the application (Fig. 4d). Electrodes are represented by solid dots and their color indicates the activation state (Fig. 4h, i), i.e., whether an electrode is part of the channel map or not. Controls above the panel allow the user to zoom and translate the view.

Optionally, a brain atlas image can be displayed and aligned with the probe to serve as a reference for planning probe insertion surgery and to assist in constructing a blueprint or channel map. This feature depends on the brainglobe-atlasapi Python package and by default the Allen mouse brain atlas (Allen Institute for Brain Science, 2004; Wang et al., 2020) is used (see https://github.com/brainglobe/brainglobe-atlasapi for a list of supported brain atlases). The atlas image transformation data is saved (as a project-specific configuration) with a channel map file.

Manual electrode selection

The application provides two approaches for constructing a channel map. The first way is to manually select electrodes (Fig. 4b) and set their state to active (green; part of the channel map) or inactive (red; not part of the channel map). Selection of a block of electrodes will highlight these electrodes and also provide visual feedback on other electrodes that share a read-out channel with the selected electrodes. This feature helps the user to see the conflict regions in the probe before committing to activate the selected electrodes. As soon as a group of electrodes has been activated by the user, the application will automatically deactivate any other electrodes that share a read-out channel with the activated electrodes.

Blueprint construction

The second approach for constructing a channel map is for the user to specify a blueprint that is used to automatically generate a channel map. Users can select groups of electrodes and assign one of the available categories (see Fig. 4c). The assigned categories are indicated as colored blocks right next to each probe shank (e.g., Fig. 6b). By default, the application will automatically generate a new channel map, once the blueprint has changed. If needed, users can further modify and optimize the channel map using the manual approach after the blueprint is finalized. The default algorithm to fill the full/half/quarter density zones imposes a strict checkerboard pattern (see Methods). An alternative algorithm that uses a less strict local-density rule is available through a command-line switch.

Fig. 5

Generation of a custom channel map for recording in the dorsal and ventral hippocampus. a: Coronal brain section at the level of the hippocampus shows insertion tracks of the four probe shanks (labeled 0–3). Green: DAPI staining of cell bodies to visualize the hippocampal and cortical cell layers. Red: fluorescent dye DiI that marks the tracks of the probe shanks. Note that the shanks pass through both the dorsal and ventral hippocampus. b: Maps of the brain regions along the insertion path for each probe shank. The maps were constructed based on the brain section in a. Note that it is not feasible to pinpoint the exact location in the brain of each electrode, since it is difficult to determine the location of the probe tips, the tissue may be distorted during histological processing and probe movement relative to the brain may have occurred during the experiment. c: An overview of spiking activity along the probe shanks. The overview was constructed separately for each shank from  15-minute recordings with a half-density channel map. Left: channel map used for each shank. Colors indicate the separate recording sessions. Middle: spatial spike rasters for each shank (10-second-long segments). Right: spatial activity map (AP r.m.s.) for each shank. The colored rectangles indicate the dorsal and ventral regions of interest. d: An example of data recorded from the same animal as in a and c, but using a custom channel map. Left: the blueprint and generated custom channel map. Middle: spatial spike rasters. Right: spatial activity maps. Due to read-out channel conflicts, it was necessary to exclude electrodes in the dorsal hippocampus on shank 0 and in the ventral hippocampus on shank 3 (\(*\))

Case Study: 4-shank Neuropixels Recording in the Dorsal and Ventral Hippocampus of the Mouse

In this case study, we will introduce how NeuroCarto has been used in an experiment that aims to record from the dorsal and ventral hippocampal cell layers simultaneously using a 4-shank Neuropixels probe (Fig. 1c). A standard block-based channel map either does not cover both dorsal and ventral hippocampus, or only at a low density that is suboptimal for spike recordings. Below, we describe the steps in an experimental workflow that are supported by the NeuroCarto application.

Planning of probe implantation

NeuroCarto can be used to assist in the planning and evaluation of the best coordinates and orientation for inserting the probe into the brain. In addition to making sure that the probe shanks hit the intended targets, users can simulate channel maps and adjust the implantation approach to avoid or minimize read-out channel conflicts. We determined that all four shanks penetrate both the dorsal and ventral hippocampal cell layers when inserting the Neuropixels probe oriented in the coronal plane at an angle of 10°(medial-to-lateral). With this approach and an insertion depth of 6 mm, conflicts arise for the dorsal and ventral hippocampal cell layers across the shanks at different depths. To resolve the conflicts, we sacrificed one dorsal and one ventral hippocampal zone on the fourth and first shank, respectively (Fig. 5d, annotated by \(*\)).

Localize electrodes based on an overview of neural signals

Having established the implantation coordinates in the previous step, we have a good idea of which electrodes are located in or near particular brain regions along the probe shanks. However, the actual placement of the probe may vary from animal to animal, which requires that a custom channel map be created for every experiment. Histological verification is an essential step in building knowledge of the distribution of cell layers and (sub)regions on the probe by the probe tracks (Fig. 5a and b) and can be used to improve the estimate of electrode locations in future experiments. Since histological information is not available during an experiment, a custom channel map is constructed on the basis of an overview of neural activity along the probe shanks. Both variations in spiking activity and local field potential signatures help to identify cell layers and (sub)regions.

To obtain an overview of neural activity along the probe shanks (Fig. 5c), a 15-minute recording was performed separately for each shank using a half-density channel map (the first channel map in Fig. 3a). We chose the single-shank half-density channel map, because it fully covers the part of the shank that is inserted into the brain (i.e., the bottom 5.8 mm) and still has a sufficient spatial resolution to identify cell layers. We evaluated the impact of electrode density on spike sorting quality and cell yield (see also Ye et al., 2023; Fiath et al., 2021), which indicated that in particular the half-density channel map with checkerboard arrangement of electrodes recovered most of the clusters that were found using a full-density channel map (Fig. 9). Although it would be possible to construct an overview of the neural activity using full-density channel maps, this requires twice the number of recordings (i.e., two per shank).

After obtaining the neural signals for each shank, we computed the root-mean-square of the high-frequency band (AP r.m.s.; 1000–5000 Hz) separately for each electrode to localize regions with high spiking activity (Fig. 5c). The AP r.m.s. reveals the structures of the cell-rich layers that help to identify the location of the dorsal and ventral CA1/subiculum pyramidal cell layers on each shank (rectangles in Fig. 5c). Other cell-rich regions, representing CA3 and dentate granule cell layers, are visible in between dorsal and ventral CA1/subiculum.

Generate a custom channel map from a blueprint based on neural activity

Following the localization of the dorsal and ventral hippocampal cell layers in the neural signal overview, we used NeuroCarto to construct a blueprint with full-density zones around these cell layers. Half-density and low-priority zones were defined for the remaining hippocampal areas and electrodes in the cortex were excluded. It is also important to exclude floating electrodes that are located outside the brain, as these may induce cross-talk in the signal on selected electrodes inside the brain that share the same analog-to-digital converter. Because of read-out channel conflicts, we sacrificed one shank for the dorsal and ventral hippocampal cell layers. We used the constructed blueprint to generate a custom channel map (Fig. 5d).

Once a satisfactory channel map has been created, experimental recording sessions start. In our experience, the procedure to generate an overview of the signals and construct a custom channel map takes approximately 1–2 hours, including data processing and construction of the blueprint and channel map. Note that it is important to store the custom channel map together with the recorded data, because the map is specific to each animal and recording session. For the SpikeGLX acquisition system, the channel map that is used during recording is stored in the meta file.

Update channel map

A custom channel map will often be used for multiple recording sessions and the time spent in building the map is a one-time investment. Multiple channel maps may be created for varying (combinations) of brain regions depending on the experimental goals. An important consideration, however, is the potential of slow movement of the probe relative to the brain that we have occasionally observed for chronic Neuropixels probe implants (Fig. 8). Such movement will induce “drift” of signals along the probe and may result in a mismatch between the selected electrodes in the custom channel map and the brain regions of interest. To check and correct for slow drift, we used both spiking activity and LFP signatures (theta oscillations and sharp-wave ripples Foster & Knierim, 2012; Buzsaki, 2015) to make sure that the dorsal and ventral hippocampal cell layers were fully covered at the beginning of the recording before the behavioral experiment and after each recording session. We have included in our experimental workflow a weekly recording session with single-shank half-density channel maps to create an updated overview of the spatial distribution of neural signals. If needed, the blueprint is updated to track the signals and a new channel map is generated (see Fig. 8).

Evaluate custom channel map

To evaluate how much better using a custom channel map is compared to a block-based channel map, we compared the spike sorting results obtained from data that was recorded using either a uniform half-density channel map that covered the dorsal-ventral extent of the hippocampus on a single shank (Fig. 5c) or a customized channel map that covered the cell layers in the dorsal and ventral hippocampus with full-density across multiple shanks (Fig. 5d). For the single-shank half-density map (across separate recordings for the four shanks), we obtained 12–26 clusters in the dorsal hippocampus and 9–20 clusters in the ventral hippocampus (only cluster labeled “good” by Kilosort were counted). With the customized channel map, we obtained a higher number of clusters, respectively 51 and 53 clusters in the dorsal and ventral hippocampus. These data illustrate that by using a customized channel map to allocate electrodes specifically to the regions of interest may result in a higher overall cell yield.

Extending NeuroCarto

The functionality of the NeuroCarto library and web application can be extended in several ways. Basic extensions, such as support for another probe family or the implementation of an alternative electrode-selection algorithm, are demonstrated in Online Resource 2 and 3, respectively. Another way of adding functionality to the web application is by executing an external Python function that interacts with UI components or modifies the channel map and/or blueprint (Fig. 6). As an example, we demonstrate a script that automatically initializes a blueprint from previously recorded neural data (the example data and script can be found in the NeuroCarto repository).

The script takes as its main input a precomputed value for each of the electrodes on a probe (read from a .npy file) that summarizes the neural activity at those electrodes (Fig. 6a), for example, the multi-unit spiking rate. In this demonstration, we computed the AP r.m.s. from the signals recorded using half-density channel maps on each shank (same data as shown in Fig. 5c). The script interpolates any missing data (i.e., non-recorded electrodes) from neighboring electrodes and visualizes the activity map alongside the probe shanks (Fig. 6b). Based on the interpolated data, the script constructs a blueprint with (rectangular) full-density zones covering the electrodes with an activity value above a user-defined threshold (given as a parameter to the script). The full-density zones are extended on both sides with half-density zones. The exclusion zones cover the remaining missing data in the interpolated data. The constructed blueprint is shown on the right side of each probe shank (Fig. 6c) and users can make further modifications to adapt the blueprint and generate a channel map to meet the experimental requirements.

Fig. 6

Example of an extension that initializes a blueprint based on neural activity. A screenshot of the NeuroCarto application following the execution of a custom script that initializes a blueprint based on neural activity measurements that are supplied by the user. a: Interface to select the extension script, define the input parameters, and execute the script. Note that the documentation of the extension is shown to inform the user about the goal of the script and its parameters. b: Visualization of the imported neural activity data next to each shank. c: Visualization of the blueprint that is generated by the extension. The legend for the blueprint categories is shown at the top right (above the extension interface). The experimental data that was used for this example is the same as shown in Fig. 5c, but with shanks in reverse order