Align Module

Volumes Alignment

Volumetric alignment module is designed to facilitate the precise alignment of volumetric microscopy data, particularly for large volumes, which are characterized by having large Z-slices. The central function, `volumetric_alignment`, serves as the primary interface for users to perform alignment operations. It abstracts the complexities of the underlying alignment mechanisms and offers a simple, unified entry point for processing.

exr.align.align.execute_volumetric_alignment(config, tasks_queue, q_lock)[source]

For each volume in code_fov_pairs, finds the corresponding reference volume and performs alignment.

Parameters:

  • config (Config) – Configuration options. This should be an instance of the Config class.

  • tasks_queue (multiprocessing.Queue) – A multiprocessing queue containing tasks.

  • q_lock (multiprocessing.Lock) – A lock for synchronizing tasks queue access.

Return type:

None

exr.align.align.execute_volumetric_alignment_bigstream(config, tasks_queue, q_lock)[source]

Executes volumetric alignment using BigStream for each round and ROI from the tasks queue.

Parameters:

  • config (Config) – Configuration options. This should be an instance of the Config class.

  • tasks_queue (multiprocessing.Queue) – A multiprocessing queue containing tasks. Each task is a tuple of (round, roi).

  • q_lock (multiprocessing.Lock) – A lock for synchronizing tasks queue access.

Return type:

None

exr.align.align.transform_ref_round(config, roi, bg_sub)[source]
Parameters:

  • config (Config) – Configuration options. This should be an instance of the Config class.

  • roi (int) – Region of interest.

  • bg_sub (str, optional) – Specifies the background subtraction method to be used. Can be “rolling_ball” or “top_hat”. If not provided, no background subtraction will be applied.

exr.align.align.volumetric_alignment(config, round_roi_pairs=None, parallel_processes=1, method=None, bg_sub='')[source]

Parallel processing support for alignment function.

Parameters:

  • config (Config) – Configuration options. This should be an instance of the Config class.

  • round_roi_pairs (List[Tuple[int, int]], optional) – A list of tuples, where each tuple is a (round, roi) pair. If None, uses all rounds and roi pairs from the config.

  • parallel_processes (int, optional) – The number of processes to use for parallel processing. Default is 1, which means no parallel processing.

  • method (str, optional) – The method to use for alignment. If ‘bigstream’, uses the ‘execute_volumetric_alignment_bigstream’ function. Otherwise, uses the ‘execute_volumetric_alignment’ function.

  • bg_sub (str, optional) – Specifies the background subtraction method to be used. Can be “rolling_ball” or “top_hat”. If not provided, no background subtraction will be applied.

Return type:

None

Volumes Alignment Evaluation

exr.align.align_eval.calculate_alignment_evaluation_ci(config, roi, ci=95, percentile_filter=95)[source]

Calculate the confidence interval (CI) for alignment evaluation and save it as a JSON file.

Parameters:

  • config (Config) – Configuration options. This should be an instance of the Config class.

  • roi (int) – The ROI (Region Of Interest) for which alignment evaluation will be calculated.

  • ci (float) – Confidence level for CI calculation. Default is 95.

  • percentile_filter (float) – Percentile value for filtering the data before CI calculation. Default is 95.

Returns:

A dictionary containing the lower and upper bounds of CI for each alignment key.

Return type:

Dict[str, Dict[str, float]]

exr.align.align_eval.measure_round_alignment_NCC(config, round, roi)[source]

Measures the alignment of a specific round and ROI (Region Of Interest) against a reference round using Normalized Cross-Correlation (NCC). The results are saved to a JSON file at a specified path.

Parameters:

  • config (Config) – Configuration options. This should be an instance of the Config class.

  • round (int) – The round to measure alignment for.

  • roi (int) – The ROI to measure alignment for.

Returns:

List of distance errors after alignment.

Return type:

List[float]

Note:

The results are saved to a JSON file located at <processed_data_path>/alignment_evaluation/ROI<roi>/NCC_ROI<roi>.json.

exr.align.align_eval.plot_alignment_evaluation(config, roi, percentile=95, save_fig=False)[source]

Plots alignment evaluation data using a violin plot.

Parameters:

  • config (Config) – Configuration options. This should be an instance of the Config class.

  • roi (int) – The ROI to plot.

  • percentile (int) – The percentile to filter the data. Default is 95.

  • save_fig (Optional[bool]) – Flag to save the figure. If False, the figure is not saved. Default is False.

Raises:

Raises an exception if an error occurs during the plotting process.

Note:

The function shows the plot using plt.show() and optionally saves it to <processed_data_path>/alignment_evaluation/ROI<roi>/Alignment_Evaluation_ROI<roi>.json if save_dir is True.

Return type:

None

Alignment evaluation module is dedicated to assessing the quality of alignment between different rounds of volumetric microscopy images within a field of view (FOV). It leverages Normalized Cross-Correlation (NCC) to quantify alignment, offering a robust measure of similarity between the reference round and other rounds.

exr.align.align_utils.alignment_NCC(config, vol1, vol2)[source]

Measures the alignment of two images using Normalized Cross-Correlation (NCC). expected shape [Z,Y,X]

Parameters:

  • config (Config) – Configuration options. This should be an instance of the Config class.

  • vol1 (np.ndarray) – The first volume (reference volume) for alignment comparison.

  • vol2 (np.ndarray) – The second volume (aligned volume) for alignment comparison.

Returns:

List of distance errors after alignment.

Return type:

List[float]

exr.align.align_utils.template_matching(T, I, IdataIn={})[source]

Implements template matching between two images using Fourier transform.

Parameters:

  • T (np.ndarray) – The template image.

  • I (np.ndarray) – The image to be matched.

  • IdataIn (Dict, optional) – A dictionary containing additional image data (optional).

Returns:

The Normalized Cross-Correlation (NCC) between the template and the image.

Return type:

np.ndarray