[h-mayorquin]

read_nwb_sorting_analyzer builds a curatable SortingAnalyzer directly from an NWB (Neurodata Without Borders) Units table, populating each extension from what the file already stores rather than recomputing it. When the Units table has waveform_mean, the analyzer is built recordingless from those stored templates, plus the per-unit metrics and the electrodes region for sparsity; when the file has an accessible ElectricalSeries, it is used as the recording. It mirrors read_kilosort_as_analyzer in structure, injecting the templates, quality and template metrics, sparsity, and random_spikes extensions from the file's contents. This supersedes the earlier draft #4270.

The reads are deliberate: Units columns are classified from metadata and only the templates, the electrodes region, and the scalar metric/label columns are materialized, while the large per-spike ragged columns (spike times, amplitudes, depths) are never touched at build. The sorting is kept lazy so its spike times are read only on demand, which builds on #4662 (single bulk-read NWB spike vector) and the copy_sorting option (#4668); the recordingless case builds a lightweight placeholder recording from the electrode rel_x/rel_y geometry (via generate_ground_truth_recording, #4588) purely to carry probe geometry into the standard constructor, then drops it. Together these keep the build small and memory-light regardless of file size.

Because the reads are deliberate and the sorting stays lazy, the function works the same whether the file is local or streamed (stream_mode is passed through to the extractors). That makes the streamed case cheap: as a check, building from a real IBL (International Brain Laboratory) processed file on dandiset 000409, session 6713a4a7-faed-4df2-acab-ee4e63326f8d (898 units, 20.7M spikes), produced a curatable analyzer in about 14 s while transferring only ~22 MB, with the ~130 MB spike read deferred until a spike-based view needs it. This PR is the reader itself; a separate how-to PR will cover the streaming-from-DANDI workflow in depth. It depends on #4662 and the copy_sorting PR (#4668), which should merge first so this branch rebases down to just the reader.

from dandi.dandiapi import DandiAPIClient
from spikeinterface.extractors import read_nwb_sorting_analyzer

# IBL Brain Wide Map (dandiset 000409), one session's processed file (units + templates, no raw traces)
SESSION = "6713a4a7-faed-4df2-acab-ee4e63326f8d"
with DandiAPIClient() as client:
    dandiset = client.get_dandiset("000409", "draft")
    asset = next(a for a in dandiset.get_assets_by_glob(f"*{SESSION}*.nwb") if "desc-processed" in a.path)
    s3_url = asset.get_content_url(follow_redirects=1, strip_query=True)

# build the analyzer directly from the streamed Units table (no full download)
analyzer = read_nwb_sorting_analyzer(s3_url, stream_mode="remfile")

print(analyzer)
print("num_units:", analyzer.get_num_units())
print("templates:", analyzer.get_extension("templates").get_data().shape)
print("quality metrics:", list(analyzer.get_extension("quality_metrics").get_data().columns))

# open in spikeinterface-gui for curation (needs a display and `pip install spikeinterface-gui`)
# import spikeinterface_gui
# spikeinterface_gui.run_mainwindow(analyzer)

[chrishalcrow]

I was trying this out on non-IBL datasets and I think this code makes quite a lot of assumptions about how the data is structured. E.g. all datasets I tried do not store an electrode index in their units table. I've not managed to load anything non-IBL - I failed to load any Allen datasets, but maybe @alejoe91 knows a good one to try.

So I think the current function name is over promising, and we should change it to be more IBL focused. Or maybe shelve this for 0.105 and work to try and make it more general.

[h-mayorquin]

Thanks for trying this, @alejoe91 I am gonna do another pass on Thursday maybe it can make it for release : )

[JoeZiminski]

Thanks @h-mayorquin will check this out today / tomorrow! I am curious on Chris' message and the NWB provenance. Does this load NWB files when they strictly adhere to the NWB format as described here? And the issue is that in many cases data is stored in NWB files but if not according to the exact schema?

[JoeZiminski]

Hey @h-mayorquin this is very cool, is very nice to be able to load a NWB file directly into an analyzer! + was interesting read, some general comments below.

One thing I was unsure about was what exactly the recording is used for. AFAICT It's loaded so it can be attached to the analyzer, and also for the channel_ids. We also need it for t_start but this is through a parallel mechanism (the NWBSortingExtractor) which I found slightly confusing (to allow a single source of truth, can we use the loaded recording (if successful) also for the t_start?).

Even if the recording can be loaded, is it a good idea to expose it through the analyzer? Is the intention that the user can do things like compute("waveforms") using the dummy randomly selected spikes, and/or recompute randomly selected spikes, waveforms, templates etc? If not I would unset the recording from the analzer to make clearer to the user this isn't a true analyzer but instead a handy wrapper for the precomputed data.

On this point more generally (outside the scope of this PR, but for discussion), now with this PR and the kilosort extractor, there are a few cases where an analyzer can be loaded from external sources to produce something close to an analyzer but which doesn't have the same guarantees. I wonder if it would be nice to have this as a distinct construct, like PrecomputedAnalyzer or ImmutableAnalzyer to make it very clear that this thing is not your usual analyzer. For example get_probe() when no recording will return the probe generated from the unit table, but in general a user would expect the full probe geometry as used in the recording. Similarly the extensions e.g. "templates" are set directly on the extension data object without going through a formal API (as it doesn't exist). This is okay but might be brittle going forward in case the analyzer shape changes. This is all outside of scope but just a note that if the pattern of loading external things into analysers in this way continues, we should probably formalise it.

I tried testing on some other random datasets, below are some issues (using this code below):

from dandi.dandiapi import DandiAPIClient
from spikeinterface.extractors import read_nwb_sorting_analyzer

DANDISET = "000469"
VERSION = "0.240123.1806"

with DandiAPIClient() as client:
    dandiset = client.get_dandiset(DANDISET, VERSION)
    asset = next(a for a in dandiset.get_assets() if a.path.endswith(".nwb"))
    s3_url = asset.get_content_url(follow_redirects=1, strip_query=True)

analyzer = read_nwb_sorting_analyzer(
    s3_url, 
    stream_mode="remfile",
  #  sampling_frequency=30_000.0,
  #  group_name="18005110031 1-281"
)

Often I had to manually pass the sampling_frequency, I'm not sure why it was failing to detect this on the recordings I tried. For

DANDISET = "000363"
VERSION = "0.231012.2129"

I got

#  File "....spikeinterface\src\spikeinterface\extractors\nwbextractors.py", line 2373, in _make_templates
#    dense_templates[unit_index][:, positions] = waveform_mean[unit_index][:, :k]

it didn't seem to like that these are 1D waveform means, but i think this is supported by NWB spec and so would make sense to handle.

Similarly for

DANDISET = "000469"
VERSION = "0.240123.1806"

it didn't like that the electrode values were scalar not list, but I think this is supported in NWB spec (I think related issue to above)

Finally with

DANDISET = "000253"
VERSION = "0.240923.1441"

The electrodes couldn't be found and it failed. In this case (any maybe other unsupported cases) it can fail with a message indicating the information it was expecting, but could not find.

[JoeZiminski]

Same I was having some errors detailed below, removing the try/accept lead to somewhat confusing error like: ValueError: Multiple ElectricalSeries found in the file. Please specify the 'electrical_series_path' argument:Available options are: [].

debug code

from dandi.dandiapi import DandiAPIClient
from spikeinterface.extractors import read_nwb_sorting_analyzer

DANDISET = "000253"
VERSION = "0.240923.1441"

with DandiAPIClient() as client:
    dandiset = client.get_dandiset(DANDISET, VERSION)
    asset = next(a for a in dandiset.get_assets() if a.path.endswith(".nwb"))
    s3_url = asset.get_content_url(follow_redirects=1, strip_query=True)

import remfile
import h5py

analyzer = read_nwb_sorting_analyzer(
    s3_url, 
    stream_mode="remfile",
    sampling_frequency=30_000.0,
  #  group_name="18005110031 1-281"
)

[h-mayorquin]

Thanks @chrishalcrow and @JoeZiminski for trying this on non-IBL files, that was very useful (I answered the inline comments in their threads). @chrishalcrow you were right that it assumed the IBL layout. I re-worked it to read by default what the schema says, and @JoeZiminski that is also the answer to your question about files that follow it. It meant two things:

1. Stripping the IBL assumptions. The reader now handles forms the schema allows that it did not before: a non-ragged electrodes column (dandiset 000469) and a 1D waveform_mean (dandiset 000363), each with a test. On a file of dandiset 000363 I get 348 units with their templates on one channel each.

2. An escape hatch for the datasets that do not follow the schema to the letter, which are a lot of them. I replaced extension_map with a nwb_to_analyzer_mapping argument: each key is the analyzer object being loaded and the value is a list of places in the file to look for it, merged over the defaults. For example, in the Allen Institute Neuropixels files (e.g. dandisets 000021 and 000253, about 6 TB across their releases) the units have no electrodes column, only the id of their peak electrode, and the electrode positions are in other columns. They read with:

allen_mapping = {
    # each unit covers every electrode of its peak electrode's probe
    "sparsity": [{"source": "peak_channel_group", "peak_channel": "peak_channel_id", "order_by": "local_index"}],
    "channel_locations": [
        {"source": "electrodes_columns", "x": "probe_horizontal_position", "y": "probe_vertical_position"}
    ],
}
analyzer = read_nwb_sorting_analyzer(
    file_path,
    electrical_series_path=None,
    sampling_frequency=30_000.0,
    group_name="probeA",
    nwb_to_analyzer_mapping=allen_mapping,
)

With it a file of dandiset 000253 loads 485 units on probe A with their templates on 384 channels. The docstring has this example, plus mapping the quality metrics that Allen names differently (e.g. isi_violations to isi_violations_ratio). Without a mapping the error says which key to set.

Remember that the plan with ndx-spikesorting is to give things that do not have a canonical place in NWB (e.g. templates and their sparsity, quality metrics or unit locations) a canonical object so in the future we can load them confidently.

Other changes from the files you tried:

• When the Units table has no resolution attribute the error now says so and asks for sampling_frequency. None of the files I checked set it and that is why you had to pass it by hand.
• When the units span several probes the error now lists the group names to pass as group_name, and a group_name that matches no units raises instead of selecting none.
• The templates are converted to microvolts with the waveform unit attribute when it is set to something other than the default "volts". This is possible since NWB 2.11, before that the unit was always written as "volts" (pynwb#2162). Their alignment comes from the new time_before_peak_in_ms attribute when the file has it (nwb-schema#709). Older files keep the inference from the magnitude and the peak.

@JoeZiminski on the PrecomputedAnalyzer idea: I think the only part that cannot be trusted is the recording duration, the templates, metrics and sparsity come from a real recording. Here it is handled with the new recording_duration argument and a warning when it is estimated, and after this is merged I would give read_kilosort_as_analyzer the same argument so both readers behave the same.

[JoeZiminski]

cool! thanks @h-mayorquin the new additions look good and new way to support Allen and other organizations is very elegant. I'm sure I'll be making use of this in future!