ibl_alignment_gui.plugins.ephys_atlas.inference

Region-decoder inference for the channel-prediction plugin.

Loads the released channel-level region decoders with ephysatlas.load_pretrained – from the Hugging Face Hub (a repository and a release tag) or from a local release directory – and runs their predict to get per-channel Cosmos regions from an ephys-feature table. Two decoders are offered (DECODERS): the fold-averaged XGBoost classifier and the ProbeTransformer seed ensemble. Both predict outputs carry the best region (predicted_atlas_id) and one p_<acronym> probability column per class.

Functions

_decode	Run a loaded decoder on the shank's features, without Qt.
_default_source	Return a decoder's default repository and release tag, from ephysatlas.
_load_decoder	Load a region decoder release.
classifier_regions	Brain regions that resolve every class a classifier can emit.
decode_shank	Run decoder name once on the shank and return both of its prediction views.
invalidate_predictions	Drop decoders' cached predictions on a shank so the next click recomputes.
predict	Return the view of the most probable region per channel.
predict_cumulative	Return the view of the cumulative class probabilities by depth, for the stacked plot.
run_decoder	Run a loaded region decoder on a features table.

Classes

Decoder

A released region decoder.

class ibl_alignment_gui.plugins.ephys_atlas.inference.Decoder(repo: str, model_class: str, needs_torch: bool, short_name: str)

Bases: NamedTuple

A released region decoder.

Variables:

• repo (str) – Its Hugging Face repository.

• model_class (str) – The model_class its release manifest (ephysatlas_model.json) declares, which identifies a local release directory as this decoder.

• needs_torch (bool) – Whether it needs torch (only offered when torch is installed).

• short_name (str) – Its name in the titles above the prediction panels, e.g. ‘XGBoost prediction’.

model_class: str

Alias for field number 1

needs_torch: bool

Alias for field number 2

repo: str

Alias for field number 0

short_name: str

Alias for field number 3

ibl_alignment_gui.plugins.ephys_atlas.inference.classifier_regions()

Brain regions that resolve every class a classifier can emit.

The Allen regions plus void_fluid (id 2000), which the classifiers predict but the GUI’s atlas does not know.

Returns:

The regions, with void_fluid added.

Return type:

ClassifierRegions

ibl_alignment_gui.plugins.ephys_atlas.inference.decode_shank(controller, items, model, progress, name)

Run decoder name once on the shank and return both of its prediction views.

The decoder’s compute (see ModelSpec): no Qt is used, so it can run on a background thread.

Parameters:

• controller (AlignmentGUIController) – The main application controller.

• items (ShankController) – The shank being predicted on.

• model (RegionClassifier or ProbeTransformerClassifier) – The loaded decoder.

• progress (Callable) – progress(fraction, message), told of each step.

• name (str) – The decoder, a key of DECODERS, also its prediction option.

Return type:

tuple[dict[str, Bunch], None]

Returns:

• dict of {str (Bunch}) – The most probable region per channel (predict()) under name and the cumulative class probabilities (predict_cumulative()) under name + ' (cumulative)'.

• None – Nothing for on_computed.

Raises:

PredictionError – If the shank has no features, or they lack a column the model needs.

ibl_alignment_gui.plugins.ephys_atlas.inference.invalidate_predictions(controller, items, names=('XGBoost region prediction', 'ProbeTransformer region prediction'), **kwargs)

Drop decoders’ cached predictions on a shank so the next click recomputes.

Decorated with shank_loop(), so a single call iterates over every shank/config; the shank and config keywords injected by the decorator are absorbed via **kwargs.

Parameters:

• controller (AlignmentGUIController) – The main application controller.

• items (ShankController) – The shank whose cached predictions are cleared.

• names (iterable of str) – The decoders whose predictions are cleared, keys of DECODERS; all by default.

Return type:

None

ibl_alignment_gui.plugins.ephys_atlas.inference.predict(out, depths)

Return the view of the most probable region per channel.

Parameters:

• out (pandas.DataFrame) – A decoder’s predict output, with predicted_atlas_id.

• depths (np.ndarray) – The depths (µm) of the predicted channels.

Returns:

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

Return type:

Bunch

ibl_alignment_gui.plugins.ephys_atlas.inference.predict_cumulative(out, depths, model)

Return the view of the cumulative class probabilities by depth, for the stacked plot.

Parameters:

• out (pandas.DataFrame) – A decoder’s predict output, with one p_<acronym> column per class, in the manifest’s class order.

• depths (np.ndarray) – The depths (µm) of the predicted channels.

• model (RegionClassifier or ProbeTransformerClassifier) – The decoder, for its classes.

Returns:

probability (cumulative, channels x classes), depths, regions (the class region ids) and colours (one per class), for ShankView.plot_prediction.

Return type:

Bunch

ibl_alignment_gui.plugins.ephys_atlas.inference.run_decoder(model, df)

Run a loaded region decoder on a features table.

Fills a missing outside column (in-brain default) and gives a flat table the (pid, channel) index the decoders expect, as one probe. No GUI is involved, so failures are raised for the caller to report.

Parameters:

• model (RegionClassifier or ProbeTransformerClassifier) – A decoder returned by ephysatlas.load_pretrained.

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

Return type:

tuple[DataFrame, ndarray]

Returns:

• pandas.DataFrame – The model’s predict output: one row per predicted channel, with predicted_atlas_id and a p_<acronym> column per class, in the manifest’s class order.

• np.ndarray – The depths (µm) of the predicted channels.

Raises:

• PredictionError – If df lacks a feature the model needs.

• KeyError – If the model raises one that is not about a missing feature.