ibl_alignment_gui.loaders.alignment_loader

Classes

AlignmentLoader	Abstract base class for loading xyz picks and previous alignments.
AlignmentLoaderDocDB	Alignment loader using the Allen Neural Dynamics DocDB.
AlignmentLoaderLocal	Alignment loader using local file system.
AlignmentLoaderOne	Alignment loader using ONE.

class ibl_alignment_gui.loaders.alignment_loader.AlignmentLoader(user=None, xyz_picks=None, data_path=None, shank_idx=0, n_shanks=1)

Bases: ABC

Abstract base class for loading xyz picks and previous alignments.

Subclasses must implement the abstract load_alignments and load_xyz_picks methods.

Parameters:

• user (str or None) – Username string used for tagging alignments.

• xyz_picks (np.ndarray or None) – Pre-loaded xyz_picks. If None, it will be loaded using load_xyz_picks.

• data_path (Path or None) – The path to the folder that work in progress alignments are saved to. If None, no saved progress is loaded.

• shank_idx (int) – Index of the shank (0-based).

• n_shanks (int) – Total number of shanks.

add_extra_alignments(extra_alignments)

Add additional alignment data.

Parameters:

extra_alignments (dict) – Dictionary of new alignments to add.

Returns:

Updated alignment keys.

Return type:

list of str

get_previous_alignments()

Return all available alignment keys sorted in reverse order.

Returns:

self.alignments – Alignment keys including ‘original’.

Return type:

list of str

get_start_alignment_idx()

Return the index of the alignment to display when the data is first loaded.

A recovered alignment takes precedence, so that work saved before a crash is shown, otherwise the stored alignment is used.

Returns:

Index of the alignment in self.alignment_keys.

Return type:

int

get_starting_alignment(idx)

Set the starting alignment based on the selected index.

Parameters:

idx (int) – Index in alignment_keys.

Return type:

None

get_stored_alignment_idx()

Return the index of the stored (resolved) alignment in the alignment keys list.

If no stored alignment is set or the stored key is not present in the current alignment keys, returns 0 (i.e. the most recent alignment).

Returns:

Index of the stored alignment in self.alignment_keys, or 0 if not found.

Return type:

int

abstractmethod load_alignments()

Load previously saved alignments.

Return type:

dict[str, Any] | None

load_previous_alignments()

Load previous alignments into memory.

Any work in progress that has been saved is loaded alongside them, so that it is recovered whenever the previous alignments are refreshed.

Returns:

Sorted alignment keys including ‘original’.

Return type:

list of str

load_progress()

Load a saved work in progress alignment and add it to the available alignments.

The alignment is added under a key that marks it as recovered, so that it can be chosen from the alignment dropdown but can’t be mistaken for an alignment that has been uploaded. Nothing is added if there is no saved progress.

Return type:

None

abstractmethod load_xyz_picks()

Load xyz picks.

Return type:

ndarray | None

property recovered_key: str | None

Return the key that a recovered work in progress alignment is stored under.

Derived from the alignments rather than remembered, so that it stays correct when the alignments are copied between the loaders of different configurations. The most recently saved one is used if there is more than one.

Returns:

The key of the recovered alignment, or None if there isn’t one.

Return type:

str or None

property uploadable_alignments: dict[str, Any]

Return the alignments that can be uploaded.

Recovered alignments are left out, as they are a local record of work in progress and must never be saved alongside the alignments that have been uploaded. Any recovered alignment is excluded, not just this loader’s own, as alignments are copied between the loaders of different configurations.

Returns:

The alignments, excluding any recovered alignment.

Return type:

dict

class ibl_alignment_gui.loaders.alignment_loader.AlignmentLoaderDocDB(data_path, shank_idx, n_shanks, docdb, user=None, xyz_picks=None, use_db=True, histology_space='ccf', picks_path=None)

Bases: AlignmentLoaderLocal

Alignment loader using the Allen Neural Dynamics DocDB.

Used by the Allen/Code Ocean (anatomical) workflow when the DocDB option is enabled. xyz picks are always read from the local file system (inherited from AlignmentLoaderLocal); previous alignments are read from the DocDB QC evaluation for this session/probe/shank, falling back to the local prev_alignments.json when DocDB has no matching record or is unreachable.

The session and probe names are derived from data_path to match how they are written by AlignmentUploaderDocDB: session = data_path.parent.stem and probe = data_path.stem. Both are therefore derived from the folder that the alignment results are written to, so that the record written on upload is the one read back.

Parameters:

• data_path (Path) – The path to the folder that the alignment results are written to.

• shank_idx (int) – Index of the shank (0-based).

• n_shanks (int) – Total number of shanks.

• docdb (DocDB) – The DocDB client used to read previous alignments (injected, analogous to one).

• user (str or None) – Username for tagging alignments.

• xyz_picks (np.ndarray or None) – Preloaded xyz picks. If not provided, it will attempt to load from file.

• picks_path (Path or None) – The path to the folder that the xyz picks are read from. Defaults to data_path.

load_alignments()

Load previous alignment data from DocDB, falling back to the local file.

Returns:

Dictionary of alignment data from DocDB, the local file if DocDB has no matching record, or None if neither is available.

Return type:

dict or None

class ibl_alignment_gui.loaders.alignment_loader.AlignmentLoaderLocal(data_path, shank_idx, n_shanks, user=None, xyz_picks=None, histology_space='ccf', picks_path=None)

Bases: AlignmentLoader

Alignment loader using local file system.

xyz picks and previous alignments are loaded from files on disk. The previous alignments are read from the folder that the uploader writes them to, which is not necessarily the folder that the xyz picks are read from.

For single-shank data, expected filenames:

• *xyz_picks.json

• prev_alignments.json

For multi-shank data, expected filenames:

• *xyz_picks_shank<N>.json

• prev_alignments_shank<N>.json

Parameters:

• data_path (Path) – The path to the folder that the alignment results are written to, and so the folder that previous alignments and saved progress are read from.

• shank_idx (int) – Index of the shank (0-based).

• n_shanks (int) – Total number of shanks.

• user (str or None) – Username for tagging alignments.

• xyz_picks (np.ndarray or None) – Preloaded xyz picks. If not provided, it will attempt to load from file.

• picks_path (Path or None) – The path to the folder that the xyz picks are read from. Defaults to data_path when the picks sit alongside the alignment results.

load_alignments()

Load previous alignment data from local file.

Returns:

Dictionary of alignment data or None if file not found.

Return type:

dict or None

load_xyz_picks()

Load xyz picks from local file.

Returns:

The xyz picks as a (N, 3) array in m, or None if not found.

Return type:

np.ndarray or None

class ibl_alignment_gui.loaders.alignment_loader.AlignmentLoaderOne(insertion, one, user=None, data_path=None)

Bases: AlignmentLoader

Alignment loader using ONE.

xyz picks and previous alignments are loaded from the Alyx database.

Parameters:

• insertion (dict) – Dictionary representing a probe insertion, must contain a ‘json’ key.

• one (ONE) – An ONE instance used to query the Alyx database.

• user (str or None) – Username for tagging alignments.

• data_path (Path or None) – The path to the folder that work in progress alignments are saved to, normally the folder containing the spike sorting data.

load_alignments()

Load previous alignments from the Alyx database.

Returns:

Dictionary of alignments, or None if not found.

Return type:

dict or None

load_trajectory()

Load the histology track trajectory and stores the trajectory id.

Return type:

None

load_xyz_picks()

Load xyz picks from the insertion JSON field.

Returns:

The xyz picks as a (N, 3) array in m, or None if not available.

Return type:

np.ndarray or None