bcdi.preprocessing: Preprocessing of (B)CDI data before phase retrieval

preprocessing_runner

This module provides the function which manage the preprocessing.

API Reference

Main runner for BCDI data preprocessing, before phase retrieval.

bcdi.preprocessing.preprocessing_runner.initialize_parameters_bcdi(parameters: Dict[str, Any]) → Dict[str, Any]

Configure and validate the existing dictionary of parameters for BCDI.

bcdi.preprocessing.preprocessing_runner.initialize_parameters_cdi(parameters: Dict[str, Any]) → Dict[str, Any]

Configure and validate the existing dictionary of parameters for CDI.

bcdi.preprocessing.preprocessing_runner.run(prm: Dict[str, Any]) → None

Run the preprocessing.

Parameters:

prm – the parsed parameters

analysis

This module provides the classes used in data preprocessing. It is mainly an abstration layer making analysis steps more understandable.

API Reference

Implementation of preprocessing analysis classes.

class bcdi.preprocessing.analysis.Analysis(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Base class for the pre-processing analysis workflow.

class bcdi.preprocessing.analysis.DetectorFrameAnalysis(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Analysis worklow in the detector frame.

class bcdi.preprocessing.analysis.FirstDataLoading(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Load a dataset for the first time, de facto in the detector frame.

class bcdi.preprocessing.analysis.InteractiveMasker(data: numpy.ndarray, mask: numpy.ndarray, parameters: Dict[str, Any], starting_frame: List[int])

Mask interactively aliens (slice by slice) and hotpixels in a 3D CDI dataset.

on_click(event: matplotlib.backend_bases.MouseEvent) → None

Interact with a plot, return the position of clicked pixel.

If flag_pause==1 or if the mouse is out of plot axes, it will not register the click.

Parameters:

event – mouse click event

press_key_aliens(event: matplotlib.backend_bases.KeyEvent) → None

Interact with a plot for masking parasitic intensity or detector gaps.

Parameters:

event – button press event

press_key_mask(event: matplotlib.backend_bases.KeyEvent) → None

Interact with a plot for masking parasitic intensity or detector gaps.

Parameters:

event – button press event

class bcdi.preprocessing.analysis.LinearizationAnalysis(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Analysis worklow for data to be interpolated using the linerization matrix.

class bcdi.preprocessing.analysis.OrthogonalFrameAnalysis(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Analysis worklow for reloaded data interpolated in an orthogonal frame.

class bcdi.preprocessing.analysis.PreprocessingLoader(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Base class for loading/reloading a dataset in preprocessing.

class bcdi.preprocessing.analysis.ReloadingDetectorFrame(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Reload a dataset which is still in the detector frame.

class bcdi.preprocessing.analysis.ReloadingOrthogonalFrame(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Reload a dataset already interpolated in an orthogonal frame.

class bcdi.preprocessing.analysis.XrayUtilitiesAnalysis(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs)

Analysis worklow for data to be interpolated using the xrayutilities.

bcdi.preprocessing.analysis.create_analysis(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs) → Analysis

Create the correct analysis class depending on the parameters.

bcdi.preprocessing.analysis.create_data_loader(scan_index: int, parameters: Dict[str, Any], setup: Setup, **kwargs) → PreprocessingLoader

Instantiate a data loading class depending on analysis parameters.

bcdi.preprocessing.analysis.define_analysis_type(reload_orthogonal: bool, use_rawdata: bool, interpolation_method: str) → str

Define the correct analysis type depending on the parameters.

bcdi_utils

This module provides generic methods used for pre-processing data before phase retrieval. For example (but not limited to): centering, hotpixels removal, filtering, masking… Functions are optimized for a Bragg CDI dataset.

API Reference

Functions related to BCDI data preprocessing, before phase retrieval.

class bcdi.preprocessing.bcdi_utils.PeakFinder(array: numpy.ndarray, region_of_interest: List[int] | None = None, binning: List[int] | None = None, peak_method: str = 'max_com', **kwargs)

Find the Bragg peak and optionally fit the rocking curve and plot results.

The data is expected to be stacked into a 3D array, the first axis corresponding to the rocking angle and axes 1 and 2 to the detector plane (vertical, horizontal).

Parameters:

  • array – the detector data

  • binning – the binning factor of array relative to the unbinned detector

  • region_of_interest – the region of interest applied to build array out of the full detector

  • peak_method – peak searching method, among “max”, “com”, “max_com”.

  • kwargs –

    • ‘logger’: an optional logger

    • ”user_defined_peak”: [z, y, x] Bragg peak position defined by the user

property binning: List[int]

Binning factor of the array pixels, one number per array axis.

property bragg_peak: Tuple[int, int, int]

Export the retrieved Bragg peak position.

find_peak(user_defined_peak: Tuple[int, int, int] | None = None) → Dict[str, Tuple[int, int, int]]

Find the position of the Bragg peak using three different metrics.

Peak-searching methods:

  • “max”: maximum of the modulus

  • “com”: center of mass of the modulus

  • “max_com”: “max” along the first axis, “com” along the other axes

Parameters:

user_defined_peak – [z, y, x] Bragg peak position defined by the user

fit_rocking_curve(tilt_values: numpy.ndarray | None = None)

Calculate and plot the rocking curve, optionally save the figure.

Parameters:

tilt_values – values of the tilt angle during the rocking curve.

get_indices_cropped_binned_detector(position: List[int]) → List[int]

Calculate the position in the cropped, binned detector frame.

get_indices_full_detector(position: List[int]) → Tuple[int, int, int]

Calculate the position in the unbinned, full detector frame.

property metadata: Dict[str, Any]

Export the retrieved peaks and fitted rocking curve.

property peak_method: str

Localize the peak using this method.

property peaks: Dict[str, Tuple[int, int, int]]

Position of the detected peaks in the full, unbinned detector frame.

plot_peaks(savedir: str | None = None) → None

Plot the detected peak position by several methods, optionally save the figure.

It plots the peaks in the binned, cropped detector frame.

Peak-searching methods:

  • “max”: maximum of the modulus

  • “com”: center of mass of the modulus

  • “max_com”: “max” along the first axis, “com” along the other axes

Parameters:

savedir – folder where to save the figure

plot_rocking_curve(savedir: str | None = None) → None

Plot the rocking curve, optionally save the figure.

Parameters:

savedir – folder where to save the figure

property region_of_interest: List[int]

Region of interest used when loading the detector images.

[y_start, y_stop, x_start, x_stop]

bcdi.preprocessing.bcdi_utils.center_fft(data: numpy.ndarray, mask: numpy.ndarray, detector: Detector, frames_logical: numpy.ndarray, centering: str = 'max', fft_option: str = 'crop_asymmetric_ZYX', **kwargs)

Center and crop/pad the dataset depending on user parameters.

Parameters:

  • data – the 3D data array

  • mask – the 3D mask array

  • detector – an instance of the class Detector

  • frames_logical – array of initial length the number of measured frames. In case of padding the length changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame.

  • centering – method used to determine the location of the Bragg peak: ‘max’, ‘com’ (center of mass), or ‘max_com’ (max along the first axis, center of mass in the detector plane)

  • fft_option –

    • ‘crop_sym_ZYX’: crop the array for FFT requirements, Bragg peak centered

    • ’crop_asym_ZYX’: crop the array for FFT requirements without centering the Brag peak

    • ’pad_sym_Z_crop_sym_YX’: crop detector images (Bragg peak centered) and pad the rocking angle based on ‘pad_size’ (Bragg peak centered)

    • ’pad_sym_Z_crop_asym_YX’: pad rocking angle based on ‘pad_size’ (Bragg peak centered) and crop detector (Bragg peak non-centered)

    • ’pad_asym_Z_crop_sym_YX’: crop detector images (Bragg peak centered), pad the rocking angle without centering the Brag peak

    • ’pad_asym_Z_crop_asym_YX’: pad rocking angle and crop detector without centering the Bragg peak

    • ’pad_sym_Z’: keep detector size and pad/center the rocking angle based on ‘pad_size’, Bragg peak centered

    • ’pad_asym_Z’: keep detector size and pad the rocking angle without centering the Brag peak

    • ’pad_sym_ZYX’: pad all dimensions based on ‘pad_size’, Brag peak centered

    • ’pad_asym_ZYX’: pad all dimensions based on ‘pad_size’ without centering the Brag peak

    • ’skip’: keep the full dataset

  • kwargs –

    • ‘fix_bragg’: user-defined position in pixels of the Bragg peak [z_bragg, y_bragg, x_bragg]

    • ’pad_size’: user defined output array size [nbz, nby, nbx]

    • ’q_values’: [qx, qz, qy], each component being a 1D array

    • ’logger’: an optional logger

Returns:

  • updated data, mask (and q_values if provided, [] otherwise)

  • pad_width = [z0, z1, y0, y1, x0, x1] number of pixels added at each end of the original data

  • updated frames_logical

bcdi.preprocessing.bcdi_utils.find_bragg(array: numpy.ndarray, binning: List[int] | None = None, roi: List[int] | None = None, peak_method: str = 'max_com', tilt_values: numpy.ndarray | None = None, savedir: str | None = None, plot_fit: bool = False, **kwargs) → Dict[str, Any]

Find the Bragg peak position.

Optionally, fit the rocking curve and plot results.

Parameters:

  • array – the detector data

  • binning – the binning factor of array relative to the unbinned detector

  • roi – the region of interest applied to build array out of the full detector

  • peak_method – peak searching method, among “max”, “com”, “max_com”.

  • tilt_values – the angular values of the motor during the rocking curve

  • savedir – where to save the plots

  • plot_fit – if True, will plot results and fit the rocking curve

  • kwargs –

    • “logger”: an optional logger

    • ”user_defined_peak”: [z, y, x] Bragg peak position defined by the user

Returns:

the metadata with the results of the peak search and the fit.

bcdi.preprocessing.bcdi_utils.grid_bcdi_labframe(data, mask, detector, setup, align_q=False, reference_axis=(0, 1, 0), debugging=False, **kwargs)

Interpolate BCDI reciprocal space data using a linearized transformation matrix.

The resulting (qx, qy, qz) are in the laboratory frame (qx downstrean, qz vertical up, qy outboard).

Parameters:

  • data – the 3D data, already binned in the detector frame

  • mask – the corresponding 3D mask

  • detector – an instance of the class Detector

  • setup – instance of the Class experiment_utils.Setup()

  • align_q – boolean, if True the data will be rotated such that q is along reference_axis, and q values will be calculated in the pseudo crystal frame.

  • reference_axis – 3D vector along which q will be aligned, expressed in an orthonormal frame x y z

  • debugging – set to True to see plots

  • kwargs –

    • ‘cmap’: str, name of the colormap

    • ’fill_value’: tuple of two real numbers, fill values to use for pixels outside of the interpolation range. The first value is for the data, the second for the mask. Default is (0, 0)

    • ’logger’: an optional logger

Returns:

  • the data interpolated in the laboratory frame

  • the mask interpolated in the laboratory frame

  • a tuple of three 1D vectors of q values (qx, qz, qy)

  • a numpy array of shape (3, 3): transformation matrix from the detector frame to the laboratory/crystal frame

bcdi.preprocessing.bcdi_utils.grid_bcdi_xrayutil(data, mask, scan_number, setup, frames_logical, hxrd, debugging=False, **kwargs)

Interpolate BCDI reciprocal space data using xrayutilities package.

The resulting (qx, qy, qz) are in the crystal frame (qz vertical).

Parameters:

  • data – the 3D data, already binned in the detector frame

  • mask – the corresponding 3D mask

  • scan_number – the scan number to load

  • setup – instance of the Class experiment_utils.Setup()

  • frames_logical – array of initial length the number of measured frames. In case of padding the length changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame.

  • hxrd – an initialized xrayutilities HXRD object used for the orthogonalization of the dataset

  • debugging – set to True to see plots

  • kwargs –

    • ‘cmap’: str, name of the colormap

    • ’logger’: an optional logger

Returns:

the data and mask interpolated in the crystal frame, q values (downstream, vertical up, outboard). q values are in inverse angstroms.

bcdi.preprocessing.bcdi_utils.load_bcdi_data(scan_number: int, setup: Setup, bin_during_loading: bool = False, flatfield: numpy.ndarray | None = None, hotpixels: numpy.ndarray | None = None, background: numpy.ndarray | None = None, normalize: str = 'skip', debugging: bool = False, **kwargs) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Load Bragg CDI data, apply optional threshold, normalization and binning.

Parameters:

  • scan_number – the scan number to load

  • setup – an instance of the class Setup

  • bin_during_loading – True to bin the data during loading (faster)

  • flatfield – the 2D flatfield array

  • hotpixels – the 2D hotpixels array. 1 for a hotpixel, 0 for normal pixels.

  • background – the 2D background array to subtract to the data

  • normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

  • debugging – set to True to see plots

  • kwargs –

    • ‘photon_threshold’: float, photon threshold to apply before binning

    • ’frames_pattern’: None or list of int. Use this if you need to remove some frames, and you know it in advance. You can provide a binary list of length the number of images in the dataset. If frames_pattern is 0 at index, the frame at data[index] will be skipped, if 1 the frame will be added to the stack. Or you can directly specify the indices of the frames to be skipped, e.g. [0, 127] to skip frames at indices 0 and 127.

    • ’logger’: an optional logger

Returns:

  • the 3D data and mask arrays

  • frames_logical: array of initial length the number of measured frames. In case of padding the length changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame.

  • the monitor values used for the intensity normalization

bcdi.preprocessing.bcdi_utils.reload_bcdi_data(data: numpy.ndarray, mask: numpy.ndarray, scan_number: int, setup: Setup, normalize: bool = False, debugging: bool = False, **kwargs) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Reload BCDI data, apply optional threshold, normalization and binning.

Parameters:

  • data – the 3D data array

  • mask – the 3D mask array

  • scan_number – the scan number to load

  • setup – an instance of the class Setup

  • normalize – set to “monitor” to normalize by the default monitor of the beamline, otherwise set to “skip”

  • debugging – set to True to see plots

Parama kwargs:

  • ‘frames_pattern’: None or list of int. Use this if you need to remove some frames, and you know it in advance. You can provide a binary list of length the number of images in the dataset. If frames_pattern is 0 at index, the frame at data[index] will be skipped, if 1 the frame will be added to the stack. Or you can directly specify the indices of the frames to be skipped, e.g. [0, 127] to skip frames at indices 0 and 127.

  • ‘photon_threshold’ = float, photon threshold to apply before binning

  • ‘logger’: an optional logger

Returns:

  • the updated 3D data and mask arrays

  • the monitor values used for the intensity normalization

cdi_utils

This module provides generic methods used for pre-processing data before phase retrieval. For example (but not limited to): centering, hotpixels removal, filtering, masking… Functions are optimized for a forward CDI dataset.

API Reference

Functions related to forward CDI data preprocessing, before phase retrieval.

bcdi.preprocessing.cdi_utils.beamstop_correction(data, setup, debugging=False, **kwargs)

Correct absorption from the beamstops during P10 forward CDI experiment.

Parameters:

  • data – the 3D stack of 2D CDI images, shape = (nbz, nby, nbx) or 2D image of shape (nby, nbx)

  • setup – an instance of the class Setup

  • debugging – set to True to see plots

  • kwargs –

    • ‘logger’: an optional logger

Returns:

the corrected data

bcdi.preprocessing.cdi_utils.check_cdi_angle(data, mask, cdi_angle, frames_logical, debugging=False, **kwargs)

Check for overlaps of the sample rotation motor position in forward CDI experiment.

It checks if there is no overlap in the measurement angles, and crops it otherwise. Flip the rotation direction to convert sample angles into detector angles. Update data, mask and frames_logical accordingly.

Parameters:

  • data – 3D forward CDI dataset before gridding.

  • mask – 3D mask

  • cdi_angle – array of measurement sample angles in degrees

  • frames_logical – array of initial length the number of measured frames. In case of padding the length changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame.

  • debugging – True to have more printed comments

  • kwargs –

    • ‘logger’: an optional logger

Returns:

updated data, mask, detector cdi_angle, frames_logical

bcdi.preprocessing.cdi_utils.grid_cdi(data, mask, setup, frames_logical, correct_curvature=False, debugging=False, **kwargs)

Interpolate reciprocal space forward CDI data.

The interpolation is done from the measurement cylindrical frame to the laboratory frame (cartesian coordinates). Note that it is based on PetraIII P10 beamline ( counterclockwise rotation, detector seen from the front).

Parameters:

  • data – the 3D data, already binned in the detector frame

  • mask – the corresponding 3D mask

  • setup – an instance of the class Setup

  • frames_logical – array of initial length the number of measured frames. In case of padding the length changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame.

  • correct_curvature – if True, will correct for the curvature of the Ewald sphere

  • debugging – set to True to see plots

  • kwargs –

    • ‘fill_value’: tuple of two real numbers, fill values to use for pixels outside of the interpolation range. The first value is for the data, the second for the mask. Default is (0, 0)

    • ’logger’: an optional logger

Returns:

the data and mask interpolated in the laboratory frame, q values (downstream, vertical up, outboard)

bcdi.preprocessing.cdi_utils.load_cdi_data(scan_number, setup, mask_beamstop: bool = False, bin_during_loading=False, flatfield=None, hotpixels=None, background=None, normalize='skip', debugging=False, **kwargs)

Load forward CDI data and preprocess it.

It applies beam stop correction and an optional photon threshold, normalization and binning.

Parameters:

  • scan_number – the scan number to load

  • setup – an instance of the class Setup

  • mask_beamstop – True to apply beamstop correction (direct beam on the detector, masked by a beam stop)

  • bin_during_loading – True to bin the data during loading (faster)

  • flatfield – the 2D flatfield array

  • hotpixels – the 2D hotpixels array. 1 for a hotpixel, 0 for normal pixels.

  • background – the 2D background array to subtract to the data

  • normalize – ‘skip’ to skip, ‘monitor’ to normalize by the default monitor, ‘sum_roi’ to normalize by the integrated intensity in the region of interest defined by detector.sum_roi

  • debugging – set to True to see plots

  • kwargs –

    • ‘photon_threshold’: float, photon threshold to apply before binning

    • ’frames_pattern’: 1D array of int, of length data.shape[0]. If frames_pattern is 0 at index, the frame at data[index] will be skipped, if 1 the frame will added to the stack.

    • ’logger’: an optional logger

Returns:

  • the 3D data and mask arrays

  • frames_logical: array of initial length the number of measured frames. In case of padding the length changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame.

  • the monitor values used for the intensity normalization

bcdi.preprocessing.cdi_utils.reload_cdi_data(data, mask, scan_number, setup, normalize_method='skip', debugging=False, **kwargs)

Reload forward CDI data, apply optional threshold, normalization and binning.

Parameters:

  • data – the 3D data array

  • mask – the 3D mask array

  • scan_number – the scan number to load

  • setup – an instance of the class Setup

  • normalize_method – ‘skip’ to skip, ‘monitor’ to normalize by the default monitor, ‘sum_roi’ to normalize by the integrated intensity in a defined region of interest

  • debugging – set to True to see plots

  • kwargs –

    • ‘photon_threshold’ = float, photon threshold to apply before binning

    • ’logger’: an optional logger

Returns:

  • the updated 3D data and mask arrays

  • the monitor values used for the intensity normalization

center_fft

This module provides classes related to centering the diffraction pattern in preprocessing.

API Reference

Classes related to centering the diffraction pattern in preprocessing.

class bcdi.preprocessing.center_fft.CenterFFT(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Base class, with methods needing to be overloaded depending on the centering method.

Frame conventions:

  • axis=0, z downstream, qx in reciprocal space

  • axis=1, y vertical, qz in reciprocal space

  • axis=2, x outboard, qy in reciprocal space

Params data_shape:

shape of the 3D dataset to be centered

Parameters:

  • binning – binning factor of data in each dimension

  • preprocessing_binning – additional binning factor due to a previous preprocessing step

  • roi – region of interest of the detector used to generate data. [y_start, y_stop, x_start, x_stop]

  • center_position – position of the determined center

  • max_symmetrical_window – width of the largest symmetrical window around the center_position

  • bragg_peak – position in pixels of the Bragg peak [z_bragg, y_bragg, x_bragg]

  • fft_option –

    • ‘crop_sym_ZYX’: crop the array for FFT requirements, Bragg peak centered

    • ’crop_asym_ZYX’: crop the array for FFT requirements without centering the Brag peak

    • ’pad_sym_Z_crop_sym_YX’: crop detector images (Bragg peak centered) and pad the rocking angle based on ‘pad_size’ (Bragg peak centered)

    • ’pad_sym_Z_crop_asym_YX’: pad rocking angle based on ‘pad_size’ (Bragg peak centered) and crop detector (Bragg peak non-centered)

    • ’pad_asym_Z_crop_sym_YX’: crop detector images (Bragg peak centered), pad the rocking angle without centering the Brag peak

    • ’pad_asym_Z_crop_asym_YX’: pad rocking angle and crop detector without centering the Bragg peak

    • ’pad_sym_Z’: keep detector size and pad/center the rocking angle based on ‘pad_size’, Bragg peak centered

    • ’pad_asym_Z’: keep detector size and pad the rocking angle without centering the Brag peak

    • ’pad_sym_ZYX’: pad all dimensions based on ‘pad_size’, Brag peak centered

    • ’pad_asym_ZYX’: pad all dimensions based on ‘pad_size’ without centering the Brag peak

    • ’skip’: keep the full dataset

  • pad_size – user defined output array size [nbz, nby, nbx]

  • q_values – [qx, qz, qy], each component being a 1D array

  • logger – a logger instance

center_fft(data: numpy.ndarray, mask: numpy.ndarray | None, frames_logical: numpy.ndarray | None) → Tuple[numpy.ndarray, numpy.ndarray | None, numpy.ndarray, Any | None, numpy.ndarray | None]

Center/pad arrays and modify accordingly related objects.

Parameters:

  • data – a 3D array

  • mask – an optional 3D binary array of the same shape as data

  • frames_logical – array of initial length the number of measured frames. In case of padding the length changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame.

Returns:

the updated data, mask, pad_width, q_values, frames_logical

crop_array(array: numpy.ndarray) → numpy.ndarray

Crop an array given stop-start indices.

property data_shape: Tuple[int, int, int]

Shape of the target array.

property pad_size: Tuple[int, int, int] | None

User defined shape to which the data should be padded.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

set_start_stop_indices() → None

Calculate the start-stop indices used for cropping the data.

property start_stop_indices: Tuple[int, int, int, int, int, int]

Define the indices defining ranges used when cropping the array.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTCropAsymZYX(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Crop the data without constraint on the peak position.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

set_start_stop_indices() → None

Calculate the start-stop indices used for cropping the data.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTCropSymZYX(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Crop the data so that the peak is centered in XYZ.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

set_start_stop_indices() → None

Calculate the start-stop indices used for cropping the data.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTPadAsymZ(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Pad the data along Z.

The peak is not centered.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTPadAsymZCropAsymYX(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Pad the data along Z, crop it in Y and X.

The peak is not centered.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

set_start_stop_indices() → None

Calculate the start-stop indices used for cropping the data.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTPadAsymZCropSymYX(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Pad the data along Z, crop it in Y and X.

The peak is centered in Y and X only.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

set_start_stop_indices() → None

Calculate the start-stop indices used for cropping the data.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTPadAsymZYX(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Pad the data along Z, Y and X.

The peak is not centered.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTPadSymZ(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Pad the data along Z.

The peak is centered in Z.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTPadSymZCropAsymYX(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Pad the data along Z, crop it in Y and X.

The peak is centered in Z only.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

set_start_stop_indices() → None

Calculate the start-stop indices used for cropping the data.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTPadSymZCropSymYX(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Pad the data along Z, crop it in Y and X.

The peak is centered in ZYX.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

set_start_stop_indices() → None

Calculate the start-stop indices used for cropping the data.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenterFFTPadSymZYX(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Pad the data along Z, Y and X.

The peak is centered.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

class bcdi.preprocessing.center_fft.CenteringFactory(data: numpy.ndarray, binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str = 'crop_asymmetric_ZYX', pad_size: ~typing.Tuple[int, int, int] | None = None, centering_method: str = 'max', q_values: ~typing.List[numpy.ndarray] | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Factory class to instantiate the corrent centering child class.

Parameters:

  • data – the 3D data array

  • binning – binning factor of data in each dimension

  • preprocessing_binning – additional binning factor due to a previous preprocessing step

  • roi – region of interest of the detector used to generate data. [y_start, y_stop, x_start, x_stop]

  • bragg_peak – position in pixels of the Bragg peak [z_bragg, y_bragg, x_bragg]

  • fft_option –

    • ‘crop_sym_ZYX’: crop the array for FFT requirements, Bragg peak centered

    • ’crop_asym_ZYX’: crop the array for FFT requirements without centering the Brag peak

    • ’pad_sym_Z_crop_sym_YX’: crop detector images (Bragg peak centered) and pad the rocking angle based on ‘pad_size’ (Bragg peak centered)

    • ’pad_sym_Z_crop_asym_YX’: pad rocking angle based on ‘pad_size’ (Bragg peak centered) and crop detector (Bragg peak non-centered)

    • ’pad_asym_Z_crop_sym_YX’: crop detector images (Bragg peak centered), pad the rocking angle without centering the Brag peak

    • ’pad_asym_Z_crop_asym_YX’: pad rocking angle and crop detector without centering the Bragg peak

    • ’pad_sym_Z’: keep detector size and pad/center the rocking angle based on ‘pad_size’, Bragg peak centered

    • ’pad_asym_Z’: keep detector size and pad the rocking angle without centering the Brag peak

    • ’pad_sym_ZYX’: pad all dimensions based on ‘pad_size’, Brag peak centered

    • ’pad_asym_ZYX’: pad all dimensions based on ‘pad_size’ without centering the Brag peak

    • ’skip’: keep the full dataset

  • pad_size – user defined output array size [nbz, nby, nbx]

  • centering_method – method used to determine the location of the Bragg peak: ‘max’, ‘com’ (center of mass), or ‘max_com’ (max along the first axis, center of mass in the detector plane)

  • q_values – [qx, qz, qy], each component being a 1D array

  • logger – a logger instance

check_center_position() → None

Check if the found center position is not at the edge of the data array.

property data_shape

Store the shape of the 3D dataset.

find_center(data: numpy.ndarray, method: str) → Tuple[int, ...]

Find the center (ideally the Bragg peak) of the dataset.

Parameters:

  • data – the 3D intensity dataset

  • method – “max”, “com”, “max_com”. It is overruled by bragg_peak if this parameter is not None.

Returns:

the position of the found center as a tuple of three positive integers

get_centering_instance() → CenterFFT

Return the correct centering instance depending on the FFT option.

get_max_symmetrical_box(data: numpy.ndarray) → Tuple[int, int, int]

Calculate the largest symmetrical box around the center.

Parameters:

data – the 3D intensity dataset

Returns:

the width of the largest symmetrical box as a tuple of three positive integers

log_q_values_at_center(method: str) → None

Log some message about q values at the center found by the method.

class bcdi.preprocessing.center_fft.SkipCentering(data_shape: ~typing.Tuple[int, int, int], binning: ~typing.Tuple[int, int, int], preprocessing_binning: ~typing.Tuple[int, int, int], roi: ~typing.Tuple[int, int, int, int], center_position: ~typing.Tuple[int, ...], max_symmetrical_window: ~typing.Tuple[int, int, int], bragg_peak: ~typing.List[int] | None, fft_option: str, pad_size: ~typing.Tuple[int, int, int] | None, q_values: ~typing.Any | None = None, logger: ~logging.Logger = <Logger bcdi.preprocessing.center_fft (WARNING)>)

Skip centering.

set_pad_width() → None

Calculate the pad_width parameter depending on the centering method.

update_frames_logical(frames_logical: numpy.ndarray) → numpy.ndarray

Update the logical array depending on the processing applied to the data.

update_q_values() → None

Update q values depending on the processing applied to the data.

bcdi.preprocessing.center_fft.round_sequence_to_int(sequence: Tuple[Any, ...] | List[Any]) → Tuple[int, ...]

Round a sequence of numbers to integers.

bcdi.preprocessing.center_fft.zero_pad(array: numpy.ndarray, padding_width: numpy.ndarray = numpy.zeros, mask_flag: bool = False, debugging: bool = False) → numpy.ndarray

Pad obj with zeros.

Parameters:

  • array – 3D array to be padded

  • padding_width – number of zero pixels to padd on each side

  • mask_flag (bool) – set to True to pad with 1, False to pad with 0

  • debugging (bool) – set to True to see plots

Returns:

obj padded with zeros

process_scan

This module provides the function which manage the preprocessing for a single scan.

API Reference

Workflow for BCDI data preprocessing of a single scan, before phase retrieval.

The detector is expected to be on a goniometer.

bcdi.preprocessing.process_scan.process_scan(scan_idx: int, prm: Dict[str, Any]) → Tuple[Path, Path, Logger | None]

Run the BCDI preprocessing with the configuration parameters for a single scan.

This function is meant to be run as a process in multiprocessing, although it can also be used as a normal function for a single scan. It assumes that the dictionary of parameters was validated via a ConfigChecker instance. Interactive masking and reloading of previous masking are not compatible with multiprocessing.

Parameters:

  • scan_idx – index of the scan to be processed in prm[“scans”]

  • prm – the parsed parameters

process_scan_cdi

This module provides the function which manage the preprocessing for a single scan when the detector is not on a goniometer (detector plane always perpendicular to the direct beam independently of its position).

API Reference

Workflow for CDI data preprocessing of a single scan, before phase retrieval.

The detector is expected to be fixed, its plane being always perpendicular to the direct beam independently of the detector position.

bcdi.preprocessing.process_scan_cdi.process_scan_cdi(scan_idx: int, prm: Dict[str, Any]) → Tuple[Path, Path, Logger | None]

Run the CDI preprocessing defined by the configuration parameters for a single scan.

This function is meant to be run as a process in multiprocessing, although it can also be used as a normal function for a single scan. It assumes that the dictionary of parameters was validated via a ConfigChecker instance. Interactive masking and reloading of previous masking are not compatible with multiprocessing.

Parameters:

  • scan_idx – index of the scan to be processed in prm[“scans”]

  • prm – the parsed parameters