pypty.tcbf

run_tcbf_alignment

Align and fit the beam contrast transfer function (CTF) using 4D-STEM data.

This function estimates beam aberrations by aligning individual pixel images using cross-correlation and fitting a CTF model. It supports iterative fitting with various binning levels and options for low-frequency drift compensation.

PARAMETER	DESCRIPTION
params	Dictionary containing PyPTY experimental and reconstruction settings.
binning_for_fit	List (for integers) of binning factors for each iteration of the CTF fit. TYPE: list DEFAULT: [8]
save	Whether to save intermediate tcBF images and shift estimates. TYPE: bool DEFAULT: True
optimize_angle	Whether to include probe rotation angle in the fit. TYPE: bool DEFAULT: True
aberrations	Initial guess for aberrations. If None, n_aberrations_to_fit zeros will be used. TYPE: list DEFAULT: None
n_aberrations_to_fit	Number of aberrations to fit if no initial guess is provided. TYPE: int DEFAULT: 12
reference_type	Reference used for cross-correlation ("bf" or "zero"). TYPE: string DEFAULT: 'bf'
ctf_sign_flip	Boolean flag, helps to align the images. DEFAULT: False
refine_box_dim	Radius (in pixels) of the interpolation box for sub-pixel shift refinement. TYPE: int DEFAULT: 10
upsample	Factor for refining cross-correlation to estimate sub-pixel shifts. TYPE: int DEFAULT: 3
cross_corr_type	Type of cross-correlation to use ("phase" or "classical"). TYPE: str DEFAULT: 'phase'
cancel_large_shifts	Threshold (0–1) to ignore large shift outliers in the fit. TYPE: float DEFAULT: None
pattern_blur_width	Radius for optional circular blur mask applied to patterns. TYPE: int DEFAULT: None
scan_pad	Number of scan pixels to pad around the dataset (auto if None). TYPE: int DEFAULT: None
aperture	Aperture mask. If None, attempts to extract from parameters. TYPE: ndarray DEFAULT: None
subscan_region	Subregion for CTF fitting: [left, top, right, bottom]. TYPE: list DEFAULT: None
compensate_lowfreq_drift	Whether to compensate for pattern drift in large FOVs. TYPE: bool DEFAULT: False
append_lowfreq_shifts_to_params	Whether to store low-frequency drift corrections in params. TYPE: bool DEFAULT: True
interpolate_scan_factor	Factor to upsample the scan via interpolation (experimental). TYPE: int DEFAULT: 1
binning_cross_corr	Binning factor before peak detection in cross-correlation. TYPE: int DEFAULT: 1
phase_cross_corr_formula	Use analytical peak refinement formula for phase correlation. TYPE: bool DEFAULT: False
f_scale_lsq	Scaling factor for residuals in least_squares. TYPE: float DEFAULT: 1
x_scale_lsq	Scaling for initial step size in least_squares. TYPE: float DEFAULT: 1
loss_lsq	Loss function for least_squares optimization. TYPE: string DEFAULT: 'linear'
tol_ctf	Tolerance (ftol) for stopping criterion in optimization. TYPE: float DEFAULT: 1e-08

RETURNS	DESCRIPTION
dict	Updated parameter dictionary with fitted aberrations, defocus, and potentially updated scan positions and rotation.

upsampled_tcbf

Perform an upsampled tcBF (transmission coherent Bright Field) reconstruction.

This function reconstructs a tcBF image on an upsampled scan grid from 4D-STEM data. It applies Fourier-based shifts to align the bright field pixel images and combines them into a final image. Prior to calling this function, it is recommended to run the tcBF alignment routine to update pypty_params.

PARAMETER	DESCRIPTION
pypty_params	Dictionary containing experimental parameters and reconstruction settings. This should include keys such as 'data_path', 'scan_size', 'aperture_mask', 'acc_voltage', etc. TYPE: dict
upsample	Upsampling factor for the scan grid. Default is 5. TYPE: int DEFAULT: 5
pad	Number of additional scan positions to pad on each side to avoid wrap-around artifacts. Default is 10. TYPE: int DEFAULT: 10
compensate_lowfreq_drift	If True, compensates for low-frequency drift of the aperture. Requires that run_tcbf_alignment has been executed to provide drift corrections. Default is False. TYPE: bool DEFAULT: False
ctf_sign_flig	Boolean flag, helps to compensate artifacts
default_float	Precision for floating point computations. Use 64 for higher precision or 32 for lower memory usage. Default is 64. TYPE: (64, 32) DEFAULT: 64
round_shifts	If True, shifts are rounded and alignment is performed using array roll operations. If False, FFT-based subpixel shifting is used. Default is False. TYPE: bool DEFAULT: False
xp	Backend array module (e.g., numpy or cupy). Default is cupy. TYPE: module DEFAULT: numpy
save	Flag to save the output image. If True, the image is saved to disk. Ignored if 'save_preprocessing_files' is set in pypty_params. Default is 0 (False). TYPE: bool or int DEFAULT: 0
max_parallel_fft	Maximum number of FFTs to perform in parallel for vectorized processing. Default is 100. TYPE: int DEFAULT: 100
bin_fac	Binning factor for the data in reciprocal space. Default is 1 (no binning). TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
ndarray	Real-valued tcBF image reconstructed on the upsampled grid.
float	Final pixel size in Ångströms after upsampling.

run_tcbf_compressed_alignment

Perform a CTF alignment using compressed 4D-STEM data and masked bright-field regions.

This function fits the beam CTF to the shifts between the individual pixel images of the 4d-stem dataset. It's the same as run_tcbf_alignment, but for compressed data. The shift estimation is done via cross-correaltion.

PARAMETER	DESCRIPTION
params	Dictionary containing experimental and reconstruction settings. TYPE: dict
num_iterations	Number of fitting iterations to perform. TYPE: int
save	Whether to save intermediate tcBF images and shift maps. Default is True. TYPE: bool DEFAULT: True
optimize_angle	Whether to include probe rotation angle in the CTF fit. Default is True. TYPE: bool DEFAULT: True
aberrations	Initial guess for the aberration coefficients. If None, it will be inferred or zero-initialized. TYPE: list or None DEFAULT: None
n_aberrations_to_fit	Number of aberration coefficients to fit if aberrations is not provided. Default is 12. TYPE: int DEFAULT: 12
reference_type	"bf" to use the tcBF image as a reference, "zero" to use the central pixel. Default is "bf". TYPE: str DEFAULT: 'bf'
ctf_sign_flip	Boolean flag, helps to compensate artifacts DEFAULT: False
refine_box_dim	Size of the cropped region around the cross-correlation peak for sub-pixel refinement. Default is 10. TYPE: int DEFAULT: 10
upsample	Upsampling factor for sub-pixel interpolation. Default is 3. TYPE: int DEFAULT: 3
cross_corr_type	Cross-correlation method: "phase" (recommended) or "classic". Default is "phase". TYPE: str DEFAULT: 'phase'
cancel_large_shifts	Threshold to reject large shift outliers during fitting. Value between 0 and 1. Default is None. TYPE: float or None DEFAULT: None
pattern_blur_width	Width of blur kernel for patterns prior to analysis. Default is None. TYPE: int or None DEFAULT: None
scan_pad	Number of scan pixels to pad around the scan to prevent wrap-around. Default is auto. TYPE: int or None DEFAULT: None
aperture	Aperture mask defining pixels to analyze. If None, it will be loaded from params. TYPE: ndarray or None DEFAULT: None
subscan_region	Optional subregion [left, top, right, bottom] on which to perform the alignment. Default is None. TYPE: list or None DEFAULT: None
compensate_lowfreq_drift	Whether to compute and correct for slow drifting of the aperture over time. Default is False. TYPE: bool DEFAULT: False
append_lowfreq_shifts_to_params	If True, saves the low-frequency correction back into params. Default is True. TYPE: bool DEFAULT: True
interpolate_scan_factor	Experimental: interpolate scan grid by this factor (e.g., 2 for 2x upsampled grid). Default is 1. TYPE: int DEFAULT: 1
binning_cross_corr	Binning factor applied to cross-correlation maps before refinement. Default is 1. TYPE: int DEFAULT: 1
phase_cross_corr_formula	If True, uses analytical subpixel peak estimation for phase correlation. Default is False. TYPE: bool DEFAULT: False
f_scale_lsq	Scaling factor for least squares residuals (f_scale). Default is 1. TYPE: float DEFAULT: 1
x_scale_lsq	Initial step scaling (x_scale) for least squares. Default is 1. TYPE: float DEFAULT: 1
loss_lsq	Loss type for least squares optimizer. E.g., "linear", "huber". Default is "linear". TYPE: str DEFAULT: 'linear'
tol_ctf	Tolerance for optimizer convergence (ftol). Default is 1e-8. TYPE: float DEFAULT: 1e-08

RETURNS	DESCRIPTION
dict	Updated dictionary of reconstruction parameters including fitted aberrations and scan rotation.