ibl_alignment_gui.loaders.alignment_uploader

Classes

`AlignmentUploader`	Abstract base class for saving alignment results.
`AlignmentUploaderDocDB`	Alignment uploader for the Allen/Code Ocean (anatomical) workflow with DocDB support.
`AlignmentUploaderLocal`	Alignment uploader using local file system.
`AlignmentUploaderOne`	Alignment uploader using ONE.

class ibl_alignment_gui.loaders.alignment_uploader.AlignmentUploader(brain_atlas, data_path=None, shank_idx=0, n_shanks=1)[source] 

Bases: ABC

Abstract base class for saving alignment results.

Subclasses must implement the abstract upload_data method.

Parameters:

brain_atlas (AllenAtlas) – An AllenAtlas instance
data_path (Path or None) – The path to the folder that work in progress alignments are saved to. If None, progress can’t be saved.
shank_idx (int) – Index of the shank (0-based).
n_shanks (int) – Total number of shanks.

delete_progress()[source] 

Delete any saved progress, as the alignment has now been uploaded.

Return type:: None

property progress_file: Path | None 

Return the path of the file that work in progress alignments are saved to.

Returns:: The path of the file, or None if there is nowhere to save progress to.
Return type:: Path or None

save_progress(feature, track)[source] 

Save the current alignment to file so that it can be recovered if the GUI crashes.

Any previously saved progress is replaced, so the file always holds the most recent alignment. It is deleted once the alignment has been successfully uploaded.

Parameters:

feature (list) – The positions of the feature reference lines.
track (list) – The positions of the track reference lines.

Returns:

Message containing information about the save result.

Return type:

str

abstractmethod upload_data(*args, **kwargs)[source] 

Upload alignment data.

Return type:: str

class ibl_alignment_gui.loaders.alignment_uploader.AlignmentUploaderDocDB(data_path, shank_idx, n_shanks, brain_atlas, docdb, user=None, transform_loader=None, use_db=True)[source] 

Bases: AlignmentUploaderLocal

Alignment uploader for the Allen/Code Ocean (anatomical) workflow with DocDB support.

Extends AlignmentUploaderLocal: the local json files (channel locations, previous alignments and, when a transform loader is available, the CCF channel locations) are always written. When use_db is True a QC evaluation holding the channel results, previous alignments and CCF channel results is additionally posted to DocDB via the injected DocDB client; when False only the local files are written and the uploader behaves like AlignmentUploaderLocal.

Parameters:

data_path (Path) – The path to the local data folder.
shank_idx (int) – Index of the shank (0-based).
n_shanks (int) – Total number of shanks.
brain_atlas (BrainAtlas) – A BrainAtlas instance (AllenAtlas or BrainAtlasAnatomical).
docdb (DocDB) – The DocDB client used to post the QC evaluation (injected, analogous to one).
user (str or None) – Username for tagging alignments and recorded as the DocDB curator.
transform_loader (TransformLoader or None) – A TransformLoader used to warp channel locations into the Allen CCF. When available, the CCF channel results are included in the DocDB record.
use_db (bool) – Whether to post results to DocDB (True) in addition to writing the local files, or write only the local files (False).

upload_data(data, shank_sites=None)[source] 

Save channels and alignments locally, then post to DocDB when use_db is set.

Parameters:

data (dict) – Alignment and channel data.
shank_sites (Bunch) – A Bunch object containing the channels that correspond to the shank.

Returns:

Message describing the upload result.

Return type:

str

class ibl_alignment_gui.loaders.alignment_uploader.AlignmentUploaderLocal(data_path, shank_idx, n_shanks, brain_atlas, user=None, transform_loader=None)[source] 

Bases: AlignmentUploader

Alignment uploader using local file system.

xyz channels and alignments are saved to json files.

For single-shank data, save filenames:

channel_locations.json
prev_alignments.json

For multi-shank data, expected filenames:

channel_locations_shank<N>.json
prev_alignments_shank<N>.json

Parameters:

data_path (Path) – The path to the local data folder.
shank_idx (int) – Index of the shank (0-based).
n_shanks (int) – Total number of shanks.
brain_atlas (BrainAtlas) – A BrainAtlas instance (AllenAtlas or BrainAtlasAnatomical)
user (str or None) – Username for tagging alignments.
transform_loader (TransformLoader or None) – A TransformLoader used to additionally save channel locations in the Allen CCF (used in the anatomical workflow). If None, only the atlas-space channel locations are saved.

get_brain_regions(data)[source] 

Get brain regions for each channel based on xyz coordinates.

Parameters:: data (dict) – Alignment and channel data.
Returns:: brain_regions – Information about location of electrode channels in brain atlas
Return type:: dict

get_ccf_channels(brain_regions, xyz_channels)[source] 

Create a channel dictionary with channel locations warped into the Allen CCF.

Mirrors get_channels() but replaces the atlas-space x/y/z coordinates with the CCF coordinates returned by the transform loader. The CCF coordinates are stored in the native units of the registration output (not scaled to microns), and the bregma origin is omitted, as the registration target defines its own coordinate system.

Parameters:

brain_regions (dict) – Information about location of electrode channels in brain atlas.
xyz_channels (np.ndarray) – An (N, 3) array of channel locations in the atlas physical space (RAS, metres).

Returns:

channels – Dictionary of dictionaries containing CCF data for each channel.

Return type:

dict[str, dict]

get_channels(brain_regions)[source] 

Create channel dictionary in form to write to json file.

Parameters:: brain_regions (dict) – Information about location of electrode channels in brain atlas
Returns:: channels – Dictionary of dictionaries containing data for each channel
Return type:: dict[str, dict]

save_alignments(alignments)[source] 

Save alignments to local json file.

Parameters:: alignments (dict[str, Any]) – Dictionary of alignment data.
Return type:: None

save_channels(channels, suffix='')[source] 

Save channel locations to local json file.

Parameters:

channels (dict[str, dict]) – Dictionary of dictionaries containing data for each channel
suffix (str) – Suffix appended to the channel_locations filename stem (e.g. '_ccf' for channel locations in the Allen CCF). Empty by default.

Return type:

None

upload_alignments(data)[source] 

Update and save alignments to local json file.

Parameters:: data (dict) – Alignment and channel data.
Returns:: alignments – The alignments dictionary with the newly added alignment merged in.
Return type:: dict[str, Any]

upload_channels(data)[source] 

Get channel locations and save to local json file.

When a TransformLoader is available, the channel locations are additionally warped into the Allen CCF and saved to a separate channel_locations_ccf json file.

Parameters:

data (dict) – Alignment and channel data.

Return type:

tuple[dict[str, dict], dict[str, dict]]

Returns:

channels (dict[str, dict]) – The atlas-space channel locations.
ccf_channels (dict[str, dict]) – The channel locations warped into the Allen CCF, or an empty dict when no transform loader is available.

upload_data(data, shank_sites=None)[source] 

Save channels and alignments to local files.

Parameters:

data (dict) – Alignment and channel data.
shank_sites (Bunch) – A Bunch object containing the channels that correspond to the shank

Returns:

Message containing information about upload result.

Return type:

str

Notes

This method sets the following attributes:

self.orig_idxnp.ndarray: The original index of the channel in the raw data

class ibl_alignment_gui.loaders.alignment_uploader.AlignmentUploaderOne(insertion, one, brain_atlas, data_path=None)[source] 

Bases: AlignmentUploader

Alignment uploader using ONE. xyz channels and alignments are saved to Alyx database.

Parameters:

insertion (dict) – Probe insertion information.
one (ONE) – An ONE instance used to upload results to Alyx
brain_atlas (AllenAtlas) – An AllenAtlas object.
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.

get_upload_info(channels, resolved)[source] 

Return an info message based on upload result.

Parameters:

channels (bool) – Whether channels were uploaded.
resolved (bool) – Where the alignment is resolved.

Returns:

Status message.

Return type:

str

save_alignments(alignments)[source] 

Save updated alignments to Alyx.

Parameters:: alignments (dict) – Updated alignments.
Return type:: None

set_user_qc(align_qc, ephys_qc, ephys_desc, force_resolve)[source] 

Set QC and confidence strings, optionally launching critical reasons GUI.

Parameters:

align_qc (str) – Alignment confidence.
ephys_qc (str) – Ephys QC.
ephys_desc (list of str) – Description of QC issues.
force_resolve (bool) – Whether to force the alignment to be resolved.

Return type:

None

upload_alignments(data)[source] 

Upload alignment data to Alyx.

Parameters:: data (dict) – A dict containing data for upload.
Returns:: alignments – Updated alignments dictionary.
Return type:: dict

upload_channels(data)[source] 

Upload channel locations to Alyx if not resolved.

Parameters:: data (dict) – A dict containing data for upload.
Returns:: True if channels uploaded, False otherwise.
Return type:: bool

upload_data(data, **kwargs)[source] 

Upload channels, alignments, and QC to Alyx.

Parameters:: data (dict) – Alignment and channel data.
Returns:: Message containing information about upload result.
Return type:: str

upload_qc(data, alignments)[source] 

Compute alignment qc and upload evaluation to Alyx.

Parameters:

data (dict) – Data required to run alignment qc.
alignments (dict) – Dictionary of alignments on which to compute the qc.

Returns:

self.resolved – Alignment resolved bool

Return type:

bool