PhasingResultAnalyser#

class cdiutils.process.PhasingResultAnalyser(cdi_results=None, result_dir_path=None)[source]#

Bases: object

This class provided utility function for phase retrieval results analysis.

Analysis Methods

find_phasing_results([search_pattern])

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

metrics

sorted_phasing_results

__init__(cdi_results=None, result_dir_path=None)[source]#

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')[source]#

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)[source]#
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)[source]#

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')[source]#

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')[source]#

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)[source]#

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)[source]#

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]

See Also#

PyNXPhaser : Phase retrieval engine BcdiPipeline : Uses analyser for result validation