Add options to order Neuropixels channels by depth

[bparks13]

Utilizing the Probe Interface configuration, we can add a dropdown menu that includes the option to reorder channels based on pre-defined characteristics.

For instance, channels can be ordered by: Channel / Electrode / Depth.

Currently, the default is channel ordering.

[bparks13]

To avoid complicating matters, this will not be implemented in the Data nodes; those will always provide data in channel order.

Instead, we will create a transform node that takes in the ephys channels and a ProbeInterface object and can reorder the channels based on electrode or depth.

Additionally, and this may be better served in a separate issue, but we can look into using a visualizer that can load the ProbeInterface file and gives options to visually reorder the data without actually modifying it.

[bparks13]

One option for giving a Probe Interface object to either of these options is to wait for #481 to be merged, and then we can just have a filepath that the user can set. This file would then be loaded when acquisition starts.

However, as a counterargument to using the file, the user can change the electrode configuration and these changes would not be reflected in the file unless they saved it explicitly right before starting the workflow. Therefore, maybe not using a file.

The question then becomes, how do we link a visualizer / transform node to the Configure node that contains the probe object as the user expects it to exist? At some point we were working on something that allowed us to grab a Configure node from outside of the configuration chain, need to track down where that was. If we can point to the same Configure node (probably by just reusing the DeviceName) we can grab the Probe Interface object and use that for reordering or visualization as needed

[jonnew]

This should be done in the Neuropixels*Data operators. There should be an OrderByDepth boolean that changes the order these arrays:

bonsai-onix1/OpenEphys.Onix1/NeuropixelsV1eDataFrame.cs

Line 84 in b760f36

static readonly int[,] RawToChannel = {

in the Neuropixels*Data data operators by whatever depth resolution algorithm (e.g. NP2.0 there are channels at the same depth) is used by the GUI.

[bparks13]

After thinking about this, and playing around with some details, I think I have a way for us to do this, without it taking too much of a performance hit. Please review this, and let me know if anything looks out of place. I have not fully developed this implementation yet, so I can't test it to see if there are any obvious gaps in the logic, but I think that this might be a good direction to go.

I have been testing these steps using the NeuropixelsV1e as a reference, but the details are easily transferable to each of the other devices as well.

Add ProbeConfiguration to DeviceInfo

In the configuration node, we add the ProbeConfiguration property to the DeviceInfo so that we can access it in the data node and order by depth if needed.

Question: Should we add the whole configuration? Or just the channel map? The channel map is what is actually used to define the ordering by depth, so that might be all we need.

Adding OrderByDepth Property to NeuropixelsV1eData Node

This is an easy update, where we add a public boolean that the user can change to either order by channel or by depth.

Creating the Spatial Ordering

In the Generate() method, we cache the OrderByDepth property, and then if it is set to true, we extract the probe configuration. This probe configuration is then used to generate the new channel mapping one time, following the algorithm below.

OrderByDepth Algorithm

Problem
We need to reorder electrodes based on their depth (Y first, X second) while maintaining compatibility with the existing 2D RawToChannel mapping array that converts raw data frames into a data frame.

Solution Overview
The algorithm creates a new 2D mapping array with the same dimensions as the original RawToChannel array, but with values reordered to reflect the spatial arrangement of electrodes.

Code

class ChannelHelper
{
    internal static int[,] OrderChannelsByDepth(Electrode[] channelMap, int[,] originalOrder)
    {
        int rows = originalOrder.GetLength(0);
        int cols = originalOrder.GetLength(1);

        var channelToPosition = new Dictionary<int, (int row, int col)>();
        for (int row = 0; row < rows; row++)
        {
            for (int col = 0; col < cols; col++)
            {
                channelToPosition[originalOrder[row, col]] = (row, col);
            }
        }

        var spatiallyOrdered = channelMap
            .OrderBy(x => x.Position.Y)
            .ThenBy(x => x.Position.X)
            .ToArray();

        var spatialRawToChannel = new int[rows, cols];
        int index = 0;

        foreach (var e in spatiallyOrdered)
        {
            var (newRow, newCol) = channelToPosition[index++];
            var (origRow, origCol) = channelToPosition[e.Channel];

            spatialRawToChannel[origRow, origCol] = originalOrder[newRow, newCol];
        }

        if (spatialRawToChannel.Cast<int>().Distinct().Count() != originalOrder.Length)
        {
            throw new InvalidOperationException($"An error occurred reordering the channels by depth. Expected {originalOrder.Length} channels," +
                $" but only found {spatialRawToChannel.Cast<int>().Distinct().Count()} unique channels.");
        }

        return spatialRawToChannel;
    }
}

This is in turn called by each of the *DataFrame classes, since they all contain a private RawToChannel static array that is needed for the original mapping:

internal static int[,] OrderChannelsByDepth(Electrode[] channelMap)
{
    return ChannelHelper.OrderChannelsByDepth(channelMap, RawToChannel);
}

Update CopyAmplifierBuffer

Add an input to the NeuropixelsV1eDataFrame.CopyAmplifierBuffer() method, which is int[,] channelOrder = null, then use channelOrder ??= RawToChannel;, which will either use the original static array or use the given array. Then, this channelOrder variable can be used in the exact same way that RawToChannel was used.

Key Benefits

Drop-in Replacement: The new array has identical dimensions as the original, or the original is still used
Spatial Consistency: Raw data can now be ordered to match the physical electrode layout, if needed
Performance: One-time computation creates a reusable mapping