ibl_alignment_gui.plugins.ephys_atlas.spatial_encoder

Automatic probe alignment with the Ephys Atlas channel-level model (channel-prediction plugin).

The model and the alignment method live in ephysatlas.alignment (ibleatools); this module is only their GUI. The released model is loaded with ephysatlas.load_pretrained (through ephysatlas.alignment.ChannelModel) from the Hugging Face Hub or a local release, and run with its predict, which predicts the way the release says. The shank’s recorded channel features are then warped along its histology track (the GUI’s xyz_samples, top to bottom of the brain) onto the model’s predictions along it, behind a progress dialog. The result figure opens in a pop-up window, and the prediction panel shows either the atlas region of each channel where the alignment placed it, or the alignment confidence along the probe.

Each shank is aligned once: both prediction-panel views – the predicted regions and the alignment confidence, two prediction options – are built from the alignment straight away and cached by the plugin, so switching between them, or selecting one again, does not re-align. The result window opens once and is kept in the plugin state; the ‘Show auto-alignment results’ menu item shows it again.

ephysatlas (and torch) are imported only when the model is loaded or a shank is aligned, so this module can be imported without them, like inference.

Functions

_align	Align the shank with a loaded model, without Qt.
_current_pid
_default_source	Return the alignment model's default repository and release tag, from ephysatlas.
_depth_edges	Return the edges (µm) of probe depths: halfway between them, 10 µm past the ends.
_first_most_common	Return the most common of ids; on a tie, the one that comes first.
_load_encoder	Load an alignment model release, with its probe-confidence model.
_open_result_window	Draw the shank's alignment result in a new window, keep it and show it once.
_show_result	Open the shank's result window, on the main thread (the alignment model's on_computed).
align_shank	Align the shank and return both auto-alignment views, and what its result window needs.
alignment_inputs	Turn a features table into the alignment's inputs, without the GUI or a shank.
invalidate_predictions	Forget a shank's auto-alignment views so the next selection re-aligns it.
predict_confidence	Return the confidence view: the alignment confidence p(good) along the probe.
predict_regions	Return the regions view: the atlas region of each channel where the alignment placed it.

Classes

AlignmentResultWindow

A non-modal window with the alignment result figure, a toolbar and a save button.

class ibl_alignment_gui.plugins.ephys_atlas.spatial_encoder.AlignmentResultWindow(parent, figure, title)

Bases: QDialog

A non-modal window with the alignment result figure, a toolbar and a save button.

Closing only hides it, so the prediction option can show it again.

ibl_alignment_gui.plugins.ephys_atlas.spatial_encoder.align_shank(controller, items, model, progress)

Align the shank and return both auto-alignment views, and what its result window needs.

The alignment model’s compute (see ModelSpec): no Qt is used, so it can run on a background thread; the result window is opened afterwards by _show_result(). Nothing is kept here: the Channel Prediction plugin caches the views, so the shank is aligned again only after they are cleared (invalidate_predictions()).

Return type:

tuple[dict[str, Bunch], tuple]

Returns:

• dict of {str (Bunch}) – The regions view (predict_regions()) under 'Auto-alignment' and the confidence view (predict_confidence()) under 'Auto-alignment (confidence)'.

• tuple – The alignment result and its inputs, for the result window.

Raises:

• PredictionError – If the probe has no usable features or the alignment fails.

• TaskCancelledError – If Cancel was pressed.

ibl_alignment_gui.plugins.ephys_atlas.spatial_encoder.alignment_inputs(model, df)

Turn a features table into the alignment’s inputs, without the GUI or a shank.

Parameters:

• model (ChannelModel) – The loaded alignment model, for its features and vintage.

• df (pandas.DataFrame) – The probe’s features, with an axial_um column.

Returns:

features (the model’s features, rows top of the probe first, non-finite values set to 0), planned_xyz (the planned trajectory, or None if the table has none) and axial_um.

Return type:

dict

Raises:

PredictionError – If the table lacks a feature the model needs.

ibl_alignment_gui.plugins.ephys_atlas.spatial_encoder.invalidate_predictions(controller, items, **kwargs)

Forget a shank’s auto-alignment views so the next selection re-aligns it.

Used after a new model or features file; the shank’s result window is closed.

Return type:

None

ibl_alignment_gui.plugins.ephys_atlas.spatial_encoder.predict_confidence(p_good, valid, axial_um)

Return the confidence view: the alignment confidence p(good) along the probe.

Green is high and red low confidence (RdYlGn); channels without a value are grey. Depths are the channels’ probe depths (µm), and the view covers the probe only, like the regions view.

Parameters:

• p_good (np.ndarray) – [C] alignment confidence of each channel.

• valid (np.ndarray) – [C] whether each channel was aligned; channels that were not have no value.

• axial_um (np.ndarray) – [C] probe depth (µm) of each channel.

Returns:

The segments (region), their colour and axis_label, without boundary lines, for plot_prediction.

Return type:

Bunch

ibl_alignment_gui.plugins.ephys_atlas.spatial_encoder.predict_regions(brain_atlas, channel_xyz, axial_um)

Return the regions view: the atlas region of each channel where the alignment placed it.

The view covers the probe only. A Neuropixels probe has two sites per depth, which can land either side of a region boundary, so each depth takes the region most of its sites are in (on a tie, the region of its first site in probe order).

Parameters:

• brain_atlas (AllenAtlas) – The GUI’s brain atlas.

• channel_xyz (np.ndarray) – [C, 3] position (m) of each channel on the histology track, from the alignment.

• axial_um (np.ndarray) – [C] probe depth (µm) of each channel.

Returns:

The region boundaries, labels and colours along the probe, for plot_prediction.

Return type:

Bunch