Processing Module

Phase retrieval and post-processing tools.

Phase Retrieval

exception cdiutils.process.phaser.PyNXImportError(msg=None)

Bases: ImportError

Custom exception to handle Pynx import error.

__init__(msg=None)

class cdiutils.process.phaser.PyNXPhaser(iobs, mask=None, operators=None, **params)

Bases: object

A class for using PyNX’s phasing algorithms without worrying too much about the initialisation and the parameters. This class uses generic PyNX parameters but they can also be provided upon instanciation.

__init__(iobs, mask=None, operators=None, **params)

Initialisation method.

Parameters:

• iobs (np.ndarray) – the observed intensity.

• mask (np.ndarray, optional) – the mask, can include detector gap mask/hot pixels/aliens. Defaults to None.

• operators (dict, optional) – the operators you might want to use. If not provided, ER, HIO and RAAR will be initialised anyway. Defaults to None.

• params (dict, optional) – the PyNX parameters. If not provided, will use some generic parameters.

Raises:

ModuleNotFoundError – if PyNX is not installed, this class is of no use.

init_cdi(verbose=True, init_main_cdi=True, **params)

Initialise the CDI object.

Parameters:

• verbose (bool, optional) – whether to print the initialisation steps. Defaults to True.

• init_main_cdi (bool, optional) – whether to set the cdi attribute or not. Defaults to True.

• **params (optional) – the parameters to update the default ones with.

Returns:

the initialised CDI object.

Return type:

CDI_Type

classmethod read_instructions(recipe)

Read the instructions given in the recipe.

run(recipe, cdi=None, init_cdi=True)

Run the reconstruction algorithm.

Parameters:

• recipe (str) – the instruction to run, i.e. the sequence of projection algorithms (ex: “ER**200, HIO**400, RAAR**800”)

• cdi (CDI_Type, optional) – a cdi object you might to work on, if not provided, will used the attribute self.cdi. Defaults to None.

• init_cdi (bool, optional) – whether to initialise the cdi object or not. Defaults to True.

Raises:

• ValueError – if instruction is not authorised.

• ValueError – if instruction is invalid

run_multiple_instances(run_nb, recipe, init_cdi=True)

Run several reconstructions.

Parameters:

• run_nb (int) – the number of reconstructions

• recipe (str) – the instruction to run, i.e. the sequence of projection algorithms (ex: “ER**200, HIO**400, RAAR**800”)

• init_cdi (bool, optional) – whether to initialise the cdi object or not. Defaults to True.

Raises:

ValueError – if init_cdi is False but no initialisation was done with the init_cdi() method beforehand.

genetic_phasing(run_nb, genetic_pass_nb, recipe, selection_method='sharpness', init_cdi=True)

Run ‘genetic’-like phasing. It runs a number of reconstruction independently (defined by the recipe). The support of the best result based on the selection_method is used to replace other reconstruction support. This is repeated genetic_pass_nb number of times.

Parameters:

• run_nb (int) – the number of reconstructions.

• genetic_pass_nb (int) – the number of genetic pass, i.e. the number of times the recipe is applied.

• recipe (str) – the instruction to run, i.e. the sequence of projection algorithms (ex: “ER**200, HIO**400, RAAR**800”)

• selection_method (str, optional) – The metric used to select the best reconstruction. Defaults to “sharpness”.

• init_cdi (bool, optional) – whether to initialise the cdi object or not. Defaults to True.

Raises:

• ValueError – if init_cdi is False but no initialisation was done with the init_cdi() method beforehand.

• ValueError – selection method is unknown/invalid.

static plot_cdi(cdi, spaces='both', axis=0, title=None, axes=None)

A staticmethod to plot cdi object main quantity.

See ShowCDI operator to see how Vincent plots CDI objects. https://gitlab.esrf.fr/favre/PyNX/-/blob/master/pynx/cdi/cpu_operator.py?ref_type=heads

Parameters:

• cdi (CDI_Type) – the cdi object to plot the quantity from.

• spaces (str, optional) – Whether reciprocal or direct space. Defaults to “both”.

• axis (int, optional) – What slice to plot. Defaults to 0.

• title (str, optional) – A title for the plot. Defaults to None.

class cdiutils.process.phaser.PhasingResultAnalyser(cdi_results=None, result_dir_path=None)

Bases: object

This class provided utility function for phase retrieval results analysis.

__init__(cdi_results=None, result_dir_path=None)

Init method.

Parameters:

• cdi_results (list, optional) – results as CDI objects. Defaults to None.

• result_dir_path (str, optional) – the path of directory containing the .cxi phase retrieval results. Defaults to None.

Raises:

ValueError – if non of the parameters is provided or if both are.

property metrics: dict

property sorted_phasing_results: dict

find_phasing_results(search_pattern='*Run*.cxi')

Find phasing results (.cxi files) that match the given pattern.

Parameters:

search_pattern (str, optional) – Pattern to search for files. Uses glob syntax (not regex). Defaults to “Run.cxi”.

Raises:

ValueError – If no files match the given pattern.

static amplitude_based_metrics(amplitude, support)

Compute the criteria based on amplitude analysis, namely:

• the mean_to_max, mean of the gaussian fitting to max

  distance.

• the std, the standard deviation of the amplitude

• the sharpness, the sum or mean of the amplitude to the

  power of 4.

Parameters:

• amplitude (np.ndarray) – the amplitude to work on.

• support (np.ndarray) – the associated support.

Returns:

the dictionary containing the metrics.

Return type:

dict

analyse_phasing_results(sorting_criterion='mean_to_max', search_pattern='*Run*.cxi', plot=True, plot_phasing_results=True, plot_phase=False)

Analyse the phase retrieval results by sorting them according to the sorting_criteion, which must be selected in among: * mean_to_max the difference between the mean of the

Gaussian fitting of the amplitude histogram and the maximum value of the amplitude. We consider the closest to the max the mean is, the most homogeneous is the amplitude of the reconstruction, hence the best.

• the sharpness the sum of the amplitude within support to

  the power of 4. For reconstruction with similar support, lowest values means graeter amplitude homogeneity.

• std the standard deviation of the amplitude.

• llk the log-likelihood of the reconstruction.

• llkf the free log-likelihood of the reconstruction.

Parameters:

• sorting_criterion (str, optional) – the criterion to sort the results with. Defaults to “mean_to_max”.

• search_pattern (str, optional) – Pattern to search for files. Uses glob syntax (not regex). Defaults to “Run.cxi”.

• plot (bool, optional) – whether or not to disable all plots.

• plot_phasing_results (bool, optional) – whether to plot the phasing results. Defaults to True.

• plot_phase (bool, optional) – whether the phase must be plotted. If True, will the phase is plotted with amplitude as opacity. If False, amplitude is plotted instead. Defaults to False.

Raises:

ValueError – if sorting_criterion is unknown.

select_best_candidates(nb_of_best_sorted_runs=None, best_runs=None, search_pattern='*Run*.cxi')

Select the best candidates, two methods are possible. Either select a specific number of runs, provided they were alaysed and sorted beforehand. Or simply provide a list of integers corresponding to the digit numbers of the best runs.

Parameters:

• nb_of_best_sorted_runs (int, optional) – the number of best runs to select, provided they were analysed beforehand. Defaults to None.

• best_runs (list[int], optional) – the best runs to select. Defaults to None.

• search_pattern (str, optional) – Pattern to search for files. Uses glob syntax (not regex). Defaults to “Run.cxi”.

Raises:

• ValueError – If nb_of_best_sorted_runs but reconstructions

• were not analysed before. –

mode_decomposition(verbose=True, search_pattern='*Run*.cxi')

Run a mode decomposition à la PyNX. See pynx_cdi_analysis.py script. Note that this method only works if PyNX is installed. If not, use the BcdiPipeline method.

Parameters:

• verbose (bool, optional) – whether to print some logs. Defaults to True.

• search_pattern (str, optional) – Pattern to search for files. Uses glob syntax (not regex). Defaults to “Run.cxi”.

Raises:

• ValueError – in script/notebook mode, if not results are

• found in the reconstruction folder. –

Returns:

the main mode.

Return type:

np.ndarray

static plot_phasing_result(data, support, title=None, plot_phase=False)

Plot the reconstructed object in reciprocal and direct spaces.

Parameters:

• data (np.ndarray) – the reconstruction data to plot.

• support (np.ndarray) – the support of the reconstruction.

• title (str, optional) – the title of the plot. Defaults to None.

• plot_phase (bool, optional) – whether to plot the phase, if True, will plot the phase whit amplitude as opacity. If False, amplitude will be plotted. Defaults to False.

static twin_image_checkup(ref, reconstruction, phase_unwrap=True, **plot_params)

Implementation of the check-up for the twin image problem as described by Manuel Sicairos (see https://www.researchgate.net/publication/233828110_Understanding_the_twin-image_problem_in_phase_retrieval) # noqa The function takes two reconstructions, one is considered a reference. After the two reconstuctions being registered, their phase in the Fourier space are compared (difference). The same procedure is applied to the twin image of the second reconstruction. To cite the paper: ‘The smoothness of the retrieved Fourier phase differences can give an indication of the twin image problem. If either of the Fourier phase differences is smooth everywhere, this would be an indication that the reconstructions are free of the twin-image problem. In this test, the twin-image problem would be characterized by the appearance of smooth and random regions that appear complementary when comparing upright with twin images.’

Parameters:

• ref (np.ndarray | str) – the reconstruction considered as the reference.

• reconstruction (np.ndarray | str) – the reconstruction that will be twinned and compared to the reference.

• phase_unwrap (bool, optional) – whether to unwrap the phase upon plotting. Defaults to True.

Returns:

the matpltolib figure and axes

objects.

Return type:

tuple[plt.Figure, plt.Axes]

cdiutils.process.phaser.extract_run_info(filename)

Extract run number and scan info from a filename.

Parameters:

filename (str) – Path or filename containing run information

Returns:

Run number and original run string

Return type:

tuple[int, str]

Post-Processing

Utility functions for phase processing in a BCDI framework.

Author:

Clément Atlan - 27.10.2023

class cdiutils.process.postprocessor.PostProcessor

Bases: object

A class to bundle all functions needed to post-process BCDI data.

static prepare_volume(complex_object, isosurface, support_parameters=None, final_shape=None)

Prepare the volume by finding a smaller array shape, centering at the center of mass of the support, and cropping

Parameters:

• complex_object (np.ndarray) – the complex object

• phi}) ((rho e^{i)

• isosurface (bool) – the isosurface that determines the

• support

• final_shape (np.ndarray | tuple | list, optional) – the

• None. (final shape of the array requested. Defaults to)

Returns:

the cropped complex_object and the associated support.

Return type:

tuple[np.ndarray, np.ndarray]

static flip_reconstruction(data)

Flip a direct space reconstruction.

Parameters:

data (np.ndarray) – the 3D direct space reconstruction

Returns:

the flipped reconstruction

Return type:

np.ndarray

static apodize(direct_space_data, window_type='blackman', scale=1)

Apodization in the direct space data using Blackman window.

Parameters:

• direct_space_data (np.ndarray) – the 3D volume data to

• apodize.

• scale (float, optional) – value of the integral of the

• None. (Blackman window. Defaults to)

Returns:

Apodized 3D array.

Return type:

np.ndarray

static unwrap_phase(phase, support=None)

Unwrap phase for voxels that belong to the given support.

Parameters:

• phase (np.ndarray) – the phase to unwrap

• support (np.ndarray) – the support where voxels of interest are

Returns:

the unwrapped phase

Return type:

np.ndarray

static remove_phase_ramp(phase)

Remove the phase ramp of a 2 | 3D phase object.

Parameters:

phase (np.ndarray) – the 2 | 3D phase object

Returns:

the phase without the computed ramp.

Return type:

np.ndarray

static phase_offset_to_zero(phase, support=None)

Set the phase offset to the mean phase value.

static get_displacement(phase, g_vector)

Calculate the displacement from phase and g_vector.

static get_displacement_gradient(displacement, voxel_size, gradient_method='hybrid')

Calculate the gradient of the displacement.

Parameters:

• displacement (np.ndarray) – displacement array.

• voxel_size (np.ndarray | tuple | list) – the voxel size of

• array. (the)

• gradient_method (str, optional) – the method employed to

• gradient. (compute the gradient. "numpy" is the traditional)

• and ("hybrid" compute first order gradient at the surface)

• reconstruction. (second order within the bulk of the)

• "hybrid". (Defaults to)

Raises:

ValueError – If parsed method is unknown.

Returns:

the gradient of the volume in the three directions.

Return type:

np.ndarray

classmethod get_het_normal_strain(displacement, g_vector, voxel_size, gradient_method='hybrid')

Compute the heterogeneous normal strain, i.e. the gradient of the displacement projected along the measured Bragg peak direction.

Parameters:

• displacement (np.ndarray) – the displacement array

• g_vector (np.ndarray | tuple | list) – the position of the

• peak (measured Bragg)

• voxel_size (np.ndarray | tuple | list) – voxel size of the

• array

• gradient_method (str, optional) – the method employed to

• gradient. (compute the gradient. "numpy" is the traditional)

• and ("hybrid" compute first order gradient at the surface)

• reconstruction. (second order within the bulk of the)

• "hybrid". (Defaults to)

Returns:

the heterogeneous normal strain

Return type:

np.ndarray

classmethod get_structural_properties(complex_object, isosurface, g_vector, hkl, voxel_size, phase_factor=-1, handle_defects=False, support_parameters=None)

Main method used in the post-processing workflow. The method computes all the structural properties of interest in BCDI (amplitude, phase, displacement, displacement gradient, heterogeneous strain d-spacing and lattice parameter maps.)

Parameters:

• complex_object (np.ndarray) – the reconstructed object (rho e^(i phi))

• g_vector (np.ndarray | tuple | list) – the reciprocal space node on which the displacement gradient must be projected.

• hkl (tuple | list) – the probed Bragg reflection. voxel_size (np.ndarray | tuple | list): the voxel size of the 3D array.

• phase_factor (int, optional) – the factor the phase should should be multiplied by, depending on the FFT convention used. Defaults to -1 (PyNX convention in Phase Retrieval, in PyNX scattering, use 1).

• handle_defects (bool, optional) – whether a defect is present in the reconstruction, in this case phasing processing and strain computation is different. Defaults to False.

Returns:

the structural properties of the object in the form of

a dictionary. Each key corresponds to one quantity of’ interest, including: amplitude, support, phase, displacement, displacement_gradient (in all three directions), het. (heterogeneous) strain using various methods, d-spacing, lattice parameter 3D maps. hkl, g_vector and voxel size are also returned.

Return type:

dict

Result Analysis