ibl_alignment_gui.backends.allen.docdb_api

An injectable client for the Allen Neural Dynamics DocDB.

DocDB plays the same role for the Allen/Code Ocean (anatomical) workflow that ONE plays for the IBL/Alyx workflow: a single instance wraps the DocDB connection and is injected into the DocDB alignment loader and uploader (AlignmentLoaderDocDB and AlignmentUploaderDocDB).

It reads previous alignments from, and writes alignment QC evaluations to, a session’s derived ecephys record. The MetadataDbClient is built lazily and cached so the connection is reused across calls, and a pre-built client can be injected to use a fake backend in tests.

This module imports the heavy aind/boto3/aws_requests_auth dependencies (the allen extra: pip install ibl_alignment_gui[allen]) at the top level, so importing it requires them. To keep the base install lean, importers load it lazily (e.g. ProbeHandlerAllenYaml imports DocDB inside its __init__). The alignment-gui-allen launcher checks the extra is installed up front (see ibl_alignment_gui.utils.optional.has_allen()), so the import succeeds whenever the DocDB backend is actually used.

Classes

DocDB

Client for reading/writing alignment data to the Allen Neural Dynamics DocDB.
class ibl_alignment_gui.backends.allen.docdb_api.DocDB(docdb_api_client=None)[source]

Bases: object

Client for reading/writing alignment data to the Allen Neural Dynamics DocDB.

Parameters:

docdb_api_client (MetadataDbClient or None) – A pre-built DocDB client. If None, a default client is created lazily on first use.

property client: Any

The underlying DocDB client, built lazily and cached on first access.

load_alignments(session_name, probe, shank_idx=0)[source]

Load previously stored alignments for a probe/shank from DocDB.

Reads the QC evaluation named Probe Alignment for {session}_{probe}_{shank_idx} from the session’s derived ecephys record and returns its stored previous_alignments.

Parameters:

  • session_name (str) – The name of the session for the probe.

  • probe (str) – The probe for which the alignment was done.

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

Returns:

The stored alignments dictionary, or None if no matching evaluation is found.

Return type:

dict or None

Raises:

ValueError – If no derived ecephys record is found for the session.

query_docdb_id(session_name)[source]

Return the DocDB id and record for a session’s derived ecephys asset.

Parameters:

session_name (str) – The name of the session to query (matched as a regex against data_description.name).

Returns:

The DocDB _id and the full record for the most recent matching asset.

Return type:

tuple of (str, dict)

Raises:

ValueError – If no derived ecephys record is found for the session.

write_output(session_name, probe, channel_results, previous_alignments, ccf_channel_results, curator=None)[source]

Append an alignment QC evaluation to a session’s derived ecephys DocDB record.

Pulls the latest ephys sorted record and posts a QC evaluation holding the current channel results, previous alignments and CCF channel results.

Parameters:

  • session_name (str) – The name of the session for the probe.

  • probe (str) – The probe for which the alignment is being done.

  • channel_results (dict) – The current channel results (atlas space) from the GUI.

  • previous_alignments (dict) – The stored alignment information.

  • ccf_channel_results (dict) – The channel results aligned to the Allen common coordinate framework (CCF).

  • curator (str or None) – Name of the curator recorded in the evaluation. Falls back to the USERNAME/USER environment variables when None.

Return type:

None