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.
- exm.align.align.execute_volumetric_alignment_bigstream(args, tasks_queue, q_lock, accelerated, **kwargs)[source]
Executes volumetric alignment using BigStream for each code and FOV from the tasks queue.
- Parameters:
args (Args) – Configuration options. This should be an instance of the Args class.
tasks_queue (multiprocessing.Queue) – A multiprocessing queue containing tasks. Each task is a tuple of (round, roi, bg_sub).
q_lock (multiprocessing.Lock) – A lock for synchronizing tasks queue access.
accelerated (bool) – Flag to use GPU for image filter.
kwargs – Additional optional parameters, including downsample_factors, downsample_steps, full_size_steps, and percentile values (low, high).
- Return type:
None
- exm.align.align.transform_ref_code(args, fov, bg_sub)[source]
Transforms reference round for each volume specified in code_fov_pairs, convert from an nd2 file to an array, then save into an .h5 file.
- exm.align.align.volumetric_alignment(args, code_fov_pairs=None, parallel_processes=1, bg_sub='', accelerated=False, **kwargs)[source]
Coordinates the alignment of volumetric data across different fields of view (FOV) and codes.
- Parameters:
args (Args) – Configuration options. This should be an instance of the Args class.
code_fov_pairs (List[Tuple[int, int]], optional) – A list of tuples, where each tuple is a (code, fov) pair. If None, uses all code and fov pairs from the args.
parallel_processes (int, optional) – The number of processes to use for parallel processing. Default is 1, which means no parallel processing.
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.
accelerated (bool, optional) – Use GPU acceleration if you set it up. Can be. If not provided, Default is False.
kwargs –
Additional parameters to customize the alignment process. The possible options include:
General Options:
downsample_factors (tuple of int): Downsampling factors for each dimension (z, y, x). Default is (1, 1, 1).
downsample_steps (list of tuples): List of steps to perform on downscaled volumes. Each step is a tuple of (step_name, step_kwargs).
full_size_steps (list of tuples): List of steps to perform on full-size volumes. Each step is a tuple of (step_name, step_kwargs).
run_downsample_steps (bool): Whether to execute the downsampled alignment steps. Default is True.
low (float): Low percentile value for intensity normalization. Default is 1.0.
high (float): High percentile value for intensity normalization. Default is 99.0.
Alignment Pipeline Steps:
Steps passed via downsample_steps or full_size_steps must conform to the alignment_pipeline function in BigStream. Each step is a tuple of the form (step_name, step_kwargs). The available steps are:
’ransac’: Runs feature-point-based affine alignment using RANSAC.
’rigid’: Performs a rigid affine alignment (rotation and translation only).
’affine’: Performs a full affine alignment (translation, rotation, scaling, and shearing).
’deform’: Runs deformable alignment using B-splines or other methods.
- Return type:
None
For more details on step-specific arguments, refer to the [alignment_pipeline documentation](https://github.com/JaneliaSciComp/bigstream/blob/master/bigstream/align.py#L1319).
Example Usage:
With Downsampling and Full-Size Alignment:
volumetric_alignment( args, parallel_processes=4, bg_sub='rolling_ball', downsample_factors=(2, 2, 2), downsample_steps=[ ('ransac', {'blob_sizes': [5, 150], 'safeguard_exceptions': True}) ], full_size_steps=[ ('affine', {'metric': 'NCC', 'optimizer': 'Powell'}) ], run_downsample_steps=True, low=30.0, high=99.0 )
Full-Size Only Alignment:
volumetric_alignment( args, parallel_processes=4, bg_sub='rolling_ball', full_size_steps=[ ('affine', {'metric': 'NCC', 'optimizer': 'Powell'}) ], run_downsample_steps=False, low=30.0, high=99.0 )
Volumes Alignment Evaluation
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.
- exm.align.align_eval.calculate_alignment_evaluation_ci(args, fov, ci=95, percentile_filter=95)[source]
Calculate the confidence interval (CI) for alignment evaluation and save it as a JSON file.
- Parameters:
args (Args) – Configuration options. This should be an instance of the Args class.
fov (int) – The FOV 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:
- exm.align.align_eval.measure_round_alignment_NCC(args, code, fov)[source]
Analyzes the alignment between the reference round and another round for a given ROI.
This function computes the Normalized Cross-Correlation (NCC) between the volumes of the two rounds, and returns the distance errors calculated based on the offsets between the two volumes.
Note: Certain parameters are needed to be supplied via the Args class:
args.nonzero_thresh: Threshold for non-zero pixel count in the volume.
args.N : Number of sub-volumes to test the alignment with.
args.subvol_dim : Length of the side of sub-volume, in pixels.
args.xystep: Physical pixel size divided by expansion factor, um/voxel in x and y.
args.zstep : Physical z-step size divided by expansion factor, um/voxel in z.
args.pct_thresh: Percentage of pixel intensity values for thresholding.
- exm.align.align_eval.plot_alignment_evaluation(args, fov, percentile=95, save_fig=False)[source]
Plots alignment evaluation data using a violin plot.
- Parameters:
- 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
- exm.align.align_utils.alignment_NCC(args, vol1, vol2)[source]
Measures the alignment of two images using Normalized Cross-Correlation (NCC). expected shape [Z,Y,X]
- Parameters:
args (Args) – Configuration options. This should be an instance of the Args 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]
- exm.align.align_utils.template_matching(T, I, IdataIn=None)[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