ibl_alignment_gui.handlers.probe_handler

Classes

`ProbeHandler`	Abstract base class for handling alignment and data loading for a probe.
`ProbeHandlerAllenYaml`	Probe handler for the Allen/Code Ocean (anatomical) workflow with DocDB support.
`ProbeHandlerCSV`	ProbeHandler where data from two channel maps has been recorded on the shanks.
`ProbeHandlerLocal`	Local file system implementation of ProbeHandler.
`ProbeHandlerLocalYaml`	Local file system ProbeHandler driven by a session yaml file.
`ProbeHandlerONE`	ONE implementation of ProbeHandler.

class ibl_alignment_gui.handlers.probe_handler.ProbeHandler(brain_atlas=None)[source] 

Bases: ABC

Abstract base class for handling alignment and data loading for a probe.

This class provides access to loader methods that handle different aspects of the alignment process. Where applicable the probe is split into shanks and each shank is handled separately.

It can also handle multiple configurations for each shank, for example if two different channel maps are used to record data.

Parameters:: brain_atlas (BrainAtlas or None) – A pre-built BrainAtlas instance (AllenAtlas or BrainAtlasAnatomical). If None, the atlas is built lazily by build_atlas() (run on a background thread as part of load_all()), so that the slow atlas construction does not block the GUI.

build_atlas(progress_callback=None)[source] 

Build the brain atlas if not already available, and share it with the shank uploaders.

Building the atlas (downloading/reading volumes) is slow, so this is called from load_all() on a background thread rather than in __init__. The uploaders created in initialise_shanks hold a reference to the atlas; because the atlas may not exist yet at that point, this method (re)assigns the freshly built atlas onto each of them.

Return type:: None

property current_idx: int 

Return the current index of the alignment stored in the buffer for the selected shank.

Returns:: The index of the current alignment
Return type:: int

abstractmethod download_histology()[source] : Load histology data.

property feature_keys: list[str] 

Find the list of available feature plot keys across all shanks and configurations.

Returns:: A tuple of unique probe plot keys.
Return type:: tuple

get_config(idx)[source] 

Select a configuration by index.

Parameters:: idx (int) – Index in the list of possible configurations.
Return type:: None

get_current_shank(shank, config)[source] 

Return the currently active shank.

Return type:: ShankHandler

get_plot(shank, plot, key, config=None)[source] 

Access a specific plot for a specific shank and configuration.

Parameters:

shank (str) – The shank label to access.
plot (str) – The plot type to access. One of ‘image’, ‘scatter’, ‘line’, ‘probe’ or ‘slice’
key (str) – The plot key to access.
config (str) – The configuration to access. If None, uses the default configuration.

Returns:

The requested plot, or None if not found.

Return type:

Any

get_plot_keys(plot)[source] 

Find a list of available keys across all shanks and configurations for a given plot type.

Parameters:: plot (str) – The plot type to get the keys for. One of ‘image’, ‘scatter’, ‘line’, ‘probe’ or ‘slice’
Returns:: A list of unique plot keys.
Return type:: list

get_previous_alignments()[source] 

Get previous alignments for the selected shank.

Always returns the alignments from the default configuration.

Returns:: Previous alignments for the selected shank
Return type:: dict

get_selected_shank()[source] 

Return the currently selected shank.

Return type:: Bunch

abstractmethod get_shanks(*args)[source] : Return shank information.

get_start_alignment_idx()[source] 

Return the index of the alignment to display for the selected shank when data is loaded.

Delegates to the default configuration’s alignment loader. A recovered alignment takes precedence over the stored (resolved) alignment, which in turn takes precedence over the most recent one.

Returns:: Index of the alignment in the alignment keys list.
Return type:: int

get_starting_alignment(idx)[source] 

Set the index of the starting alignment for the selected shank and each configuration.

Parameters:: idx (int) – The index of the previous alignment to load.
Return type:: None

property image_keys: list[str] 

Find the list of available image plot keys across all shanks and configurations.

Returns:: A list of unique image plot keys.
Return type:: list

abstractmethod initialise_shanks()[source] : Initialize shank data.

property line_keys: list[str] 

Find the list of available line plot keys across all shanks and configurations.

Returns:: A list of unique line plot keys.
Return type:: list

load_all(progress_callback=None)[source] 

Build the atlas, then load all data and plots for the session.

This is the single entry point run on the background loading thread, so the slow atlas construction, data loading and plot building all happen off the GUI thread.

Parameters:: progress_callback (Callable or None) – Optional callback invoked as progress_callback(message, current, total) to report progress. No-op when None.
Return type:: None

load_data(progress_callback=None)[source] 

Download and load data for all configs and shanks.

Parameters:: progress_callback (Callable or None) – Optional callback invoked as progress_callback(message, current, total) before each loading step to report progress (e.g. to a GUI progress dialog). No-op when None, so headless callers are unaffected.
Return type:: None

load_plots(progress_callback=None)[source] 

Load plots for all configs and shanks.

Parameters:: progress_callback (Callable or None) – Optional callback invoked as progress_callback(message, current, total) before each loading step to report progress. No-op when None.
Return type:: None

load_previous_alignments()[source] 

Load previous alignments for the selected shank.

Always returns the alignments from the default configuration.

Returns:: Previous alignments for the selected shank.
Return type:: dict

next_idx()[source] 

Return the index of the next available alignment for the selected shank.

Returns:: The index of the next available alignment stored in th circular buffer.
Return type:: int

static normalize_shank_label(shank_label)[source] 

Normalize a shank label to the form ‘probe0X’.

Parameters:: shank_label (str) – Input shank label.
Returns:: Normalized label.
Return type:: str

prev_idx()[source] 

Return the index of the previously available alignment for the selected shank.

Returns:: The index of the previous available alignment stored in th circular buffer.
Return type:: int

property probe_keys: list[str] 

Find the list of available probe plot keys across all shanks and configurations.

Returns:: A tuple of unique probe plot keys.
Return type:: tuple

save_progress(shanks)[source] 

Save the current alignment of several shanks to file.

The alignments are saved so that they can be recovered if the GUI crashes before they have been uploaded. Only the default configuration is saved.

Parameters:: shanks (list of str) – The shanks to save the alignment for.
Returns:: A mapping of shank label to the save result message for that shank.
Return type:: dict[str, str]

property scatter_keys: list[str] 

Find the list of available scatter plot keys across all shanks and configurations.

Returns:: A list of unique scatter plot keys.
Return type:: list

abstractmethod set_info(*args)[source] : Set probe information.

set_init_alignment()[source] 

Initialise the alignment for the selected shank and each configuration.

Return type:: None

property slice_keys: list[str] 

Find the list of available slice plot keys across all shanks and configurations.

Returns:: A list of unique slice plot keys.
Return type:: list

sync_config_alignments()[source] 

Make the configurations of a shank share one set of alignments.

The alignments of the default configuration are shared with the non default one, so that the alignments, and the keys used to choose between them, can never differ between the configurations of a shank. Both configurations refer to the same dictionary, so any later change is seen by both. Does nothing when there is only one configuration.

The default configuration is the source of truth, so where it is the online one its alignments take precedence over any that were found locally. Where it has no alignments of its own it takes on those of the other configuration, so that none are lost.

The starting alignment of both configurations is set, as the alignments they can choose between may have changed.

Return type:: None

property total_idx: int 

Return the total index of the alignments stored in the buffer for the selected shank.

Returns:: The total number of alignments stored in the circular buffer
Return type:: int

upload_data()[source] 

Upload data for the selected shank for each configuration.

Always returns the upload result from the default configuration.

Returns:: Upload result from the default config.
Return type:: str

upload_shanks(shanks, progress_callback=None)[source] 

Upload data for several shanks in turn.

Saving channels and alignments (and, online, registering tracks, running alignment QC and writing to flatiron) is slow, so this is run on a background thread. Any per-shank user input (QC, upload confirmation) must be gathered on the main thread beforehand; this method only performs the saving.

Parameters:

shanks (list of str) – The shanks to upload, in order.
progress_callback (Callable or None) – Optional callback invoked as progress_callback(message, current, total) before each shank is uploaded. No-op when None.

Returns:

A mapping of shank label to the upload result message for that shank.

Return type:

dict[str, str]

class ibl_alignment_gui.handlers.probe_handler.ProbeHandlerAllenYaml(yaml_file, brain_atlas=None, docdb=None, use_docdb=True)[source] 

Bases: ProbeHandlerLocalYaml

Probe handler for the Allen/Code Ocean (anatomical) workflow with DocDB support.

Extends ProbeHandlerLocalYaml (so all the yaml/anatomical/data/geometry/histology/ transform wiring is reused) and, mirroring how ProbeHandlerONE owns a one instance, owns a DocDB instance that is injected into the DocDB alignment loader and uploader (overriding the local factory hooks ProbeHandler._build_align_loader() / ProbeHandler._build_upload_loader()).

The use_docdb flag selects the alignment backend: when True the DocDB-backed loader and uploader are used (previous alignments read from DocDB with a local fallback; results written locally and posted to DocDB); when False the plain local variants are used. It can be flipped at runtime with set_use_docdb() (e.g. from the DocDB checkbox).

Parameters:

yaml_file (str or Path) – Path to the session yaml configuration file.
brain_atlas (BrainAtlas or None) – A pre-built brain atlas. If None, it is built lazily (anatomical or Allen, per the yaml).
docdb (DocDB or None) – The DocDB client to inject. A default DocDB is created if None.
use_docdb (bool) – Whether to use the DocDB alignment backend (True) or the local one (False).

set_use_docdb(use_docdb)[source] 

Switch the alignment backend and refresh previous alignments for every shank.

Flips the use_db flag on each shank’s existing DocDB alignment loader and uploader (leaving the loaded ephys/geometry/histology untouched) and re-reads the previous alignments so the alignment dropdown reflects the new source.

Parameters:: use_docdb (bool) – Whether to use the DocDB alignment backend (True) or the local one (False).
Return type:: None

class ibl_alignment_gui.handlers.probe_handler.ProbeHandlerCSV(csv_file, one=None, brain_atlas=None)[source] 

Bases: ProbeHandler

ProbeHandler where data from two channel maps has been recorded on the shanks.

The data for the dense configuration is available via ONE whereas the data for the quarter configuration is only available on the local file system. Reads in a csv file that contains information about where to read the relevant data from.

download_histology()[source] 

Download and load in the histology slice data.

Return type:: SliceLoader

get_insertion(shank)[source] 

Get the alyx probe insertion for the shank.

Return type:: dict

get_sessions(idx)[source] 

Find all probes for a given session.

Note if multi-shank data it will return probe00 rather than probe00a, the individual shank is chosen using the shank dropdown.

Parameters:: idx (idx) – The index of the chosen subject
Returns:: All probes with spikesorting data for the chosen session
Return type:: np.ndarray

get_shanks(idx)[source] 

Find all shanks for a given probe and initialise the loaders.

Parameters:: idx (idx) – The index of the chosen probe
Returns:: All shanks for the chosen probe
Return type:: np.ndarray

get_subjects()[source] 

Find all sessions with spike sorting data.

Returns:: All sessions with spikesorting data.
Return type:: np.ndarray

initialise_shanks()[source] 

Initialise each shank and config with the selected loaders.

Return type:: None

set_info(idx)[source] 

Set the information about the selected shank.

Parameters:: idx (int) – The index of the selected shank
Return type:: None

class ibl_alignment_gui.handlers.probe_handler.ProbeHandlerLocal(brain_atlas=None)[source] 

Bases: ProbeHandler

Local file system implementation of ProbeHandler.

For this ProbeHandler, all ephys and alignment data must be stored in a single folder on disk.

download_histology()[source] 

Load in the histology slice data.

Return type:: SliceLoader

get_shanks(folder_path)[source] 

Find the number of shanks on the probes.

Loads the channels or ap meta data from the folder path and initialises the loaders for each shank.

Parameters:: folder_path (Path) – A path to the folder on the local disk that contains the data
Return type:: list[str]

initialise_shanks()[source] 

Initialise each shank with the loaders.

Return type:: None

set_info(idx)[source] 

Set the information about the selected shank.

Parameters:: idx (int) – The index of the selected shank
Return type:: None

class ibl_alignment_gui.handlers.probe_handler.ProbeHandlerLocalYaml(yaml_file, brain_atlas=None)[source] 

Bases: ProbeHandler

Local file system ProbeHandler driven by a session yaml file.

The yaml (see ibl_alignment_gui.utils.parse_yaml.load_alignment_yaml()) specifies, per probe/config, where each dataset lives (spike sorting, raw/processed ephys, picks, histology, output, and optional per-channel features). The resolved DatasetPaths for each probe/config are wired directly into the local loaders (DataLoaderLocal, GeometryLoaderLocal etc.).

Parameters:

yaml_file (str or Path) – Path to the session yaml configuration file.
brain_atlas (AllenAtlas or None) – An AllenAtlas instance (created if None).

download_histology()[source] 

Load in the histology slice data.

Return type:: SliceLoader

get_shanks(_)[source] 

Determine the shanks from the yaml and initialise the loaders.

If a single probe is specified we load its geometry to detect whether it is a multi-shank recording. Otherwise each probe entry in the yaml is treated as an individual shank.

Parameters:: _ (Any) – Ignored — the yaml path was supplied at construction time. The signature matches the other ProbeHandlers so the controller can call it uniformly.
Return type:: list[str]

initialise_shanks()[source] 

Initialise each shank and config with loaders pointing at the resolved yaml paths.

Return type:: None

set_info(idx)[source] 

Set the information about the selected shank.

Parameters:: idx (int) – The index of the selected shank.
Return type:: None

class ibl_alignment_gui.handlers.probe_handler.ProbeHandlerONE(one=None, brain_atlas=None, spike_collection=None)[source] 

Bases: ProbeHandler

ONE implementation of ProbeHandler.

For this ProbeHandler all ephys and alignment data is downloaded and accessed via ONE and Alyx.

The data for all shanks on a probe will be loaded at once.

Parameters:

one (ONE) – An ONE instance used to upload results to Alyx
brain_atlas (AllenAtlas) – An AllenAtlas object.
spike_collection (str, optional) – Spike sorting algorithm to load (e.g. ‘pykilosort’, ‘iblsorter’).

download_histology()[source] 

Download and load in the histology slice data.

Return type:: SliceLoader

get_session_probe_name(ins)[source] 

Make a string containing the combination of session information and probe name.

Removes the shank identifiers from the probe names.

Parameters:: ins (dict) – A dict containing insertion data
Returns:: A string with the session info and probe name
Return type:: str

get_sessions(idx)[source] 

Find all probes for a given subject.

Note if multi-shank data it will return probe00 rather than probe00a, the individual shank is chosen using the shank dropdown.

Parameters:: idx (idx) – The index of the chosen subject
Returns:: All probes with spikesorting data for the chosen subject
Return type:: np.ndarray

get_shanks(idx)[source] 

Find all shanks for a given probe and initialise the loaders.

Parameters:: idx (idx) – The index of the chosen probe
Returns:: All shanks for the chosen probe
Return type:: np.ndarray

get_subjects()[source] 

Find all subjects that have probe insertions with spikesorting data.

Returns:: An array of subject names
Return type:: np.ndarray

initialise_shanks()[source] : Initialise each shank with the loaders.

load_data(progress_callback=None)[source] 

Load data for all configs and shanks.

Return type:: None

resolve_pid(pid)[source] 

Resolve a probe insertion id to subject, session and shank dropdown indices.

The internal session and shank state is populated as a side effect (via get_sessions() and get_shanks()) so that the dropdowns can be configured to point at the requested insertion.

Parameters:: pid (str) – The probe insertion id (UUID) to resolve.
Returns:: The subject, session and shank dropdown indices for the insertion.
Return type:: tuple[int, int, int]
Raises:: ValueError – If no insertion exists for pid, or its subject has no spikesorted insertions (and so is absent from the subject dropdown).

set_info(idx)[source] 

Set the information about the selected shank.

Parameters:: idx (int) – The index of the selected shank