What should `to_reordered_spike_vector` do?

[grahamfindlay]

@alejoe91 @samuelgarcia @zm711 @chrishalcrow @h-mayorquin

Prior to #4606 , the vanilla spike vector was lexsorted on keys ("unit_index", "sample_index", "segment_index"). Now it is lexsorted on ("sample_index", "segment_index"). This raises a question about what the behavior of to_reordered_spike_vector should be.

Here is the function signature:

def to_reordered_spike_vector(
        self,
        lexsort=("sample_index", "segment_index", "unit_index"), 
        return_order=True,
        return_slices=True,
    ):

• lexsort is the requested sort order, as keys would be passed to np.lexsort.
• return_order=True requests the numpy array needed to sort the spike vector given the requested sort is also returned.
• return_slices=True: requests the numpy array of size (num_units, num_segments, 2) or (num_segments, num_units, 2) given the lexsort, where one can obtain the indices amin, amax of all the (segment, unit_index) values.

This function mainly exists to reorder the vanilla spike vector to ("sample_index", "segment_index", "unit_index"), so unit spike trains are compact in memory. In the current codebase, it is only ever called as to_reorded_spike_vector(lexsort=("sample_index", "segment_index", "unit_index"), ...). Nevertheless, it does allow users to request lexsort=("sample_index", "unit_index", "segment_index") or lexsort=("unit_index", "sample_index", "segment_index"). It is this last option that presents a dilemma.

Previously if a user requested lexsort=("unit_index", "sample_index", "segment_index") this just built the vanilla spike vector (or fetched it from the cache). There was nothing to reorder, and no compact 2D (unit, segment) table could possibly exist for that ordering, so return_order and return_slices had to be False.

Currently, if a user requests lexsort=("unit_index", "sample_index", "segment_index"), the same thing happens (vanilla spike vector retrieved), except now the spike vector that gets returned doesn't match the requested lexsort order. The function implies a tie-break that isn't there. This is the issue.

Question A: How to resolve this? Some options:

1. Don't allow the user to request lexsort=("unit_index", "sample_index", "segment_index"). If they want the vanilla spike vector, make them call to_spike_vector.
2. Don't allow the user to request lexsort=("unit_index", "sample_index", "segment_index"), but allow lexsort=("sample_index", "segment_index") as a way to get the vanilla spike vector.
3. Allow the user to request lexsort=("unit_index", "sample_index", "segment_index"), and actually do the lexsorting (and allow return_order=True).

My vote would be for (1).

Question B (minor): Should lexsort=("sample_index", "unit_index", "segment_index") be allowed, since it seems to be seldom (if ever) used?

1. Yes
2. No

If it were not allowed, then we could refer to the reordered spike vector, rather than a reordered spike vector (and have to specify which ordering). If it stays allowed, I would like to mention what it is used for in the docstring.

My naive vote would be for (2), but I suspect there is a good reason for (1) that I am unaware of.