epdfsuite.ePDFsuite

Functions

extract_ePDF_from_mutliple_files(dm4_files)

Extract ePDF by averaging over multiple SAED image files.

extract_epdf(sample_processor[, ...])

Extract the electron Pair Distribution Function (ePDF) from SAED data.

Classes

PDFInteractive(sample_processor[, ...])

Jupyter widget GUI for interactive ePDF parameter optimisation.

PDFResultsReference(pdf_interactive)

Proxy object providing access to the most recent PDF results from interactive mode.

SAEDProcessor(image_file[, poni_file, mask, ...])

class epdfsuite.ePDFsuite.SAEDProcessor(image_file, poni_file=None, mask=None, mtf_file=None, wiener_epsilon=None, dqe_file=None, verbose=False)[source]

Bases: object

integrate(dm4_file=None, npt=2500, center=None, plot=False)[source]

Azimuthally integrate the SAED pattern to a 1D I(q) profile.

Beam centre recalibration is always performed with recalibrate_from_isocurve() using self.center as the initial estimate. If center is provided it overwrites self.center and is used directly without re-running isocurve.

Parameters:

  • dm4_file (str, optional) – Path to an alternative DM4 file to integrate. If None, uses self.dm4_file.

  • npt (int, optional) – Number of points in the output q profile. Default is 2500.

  • center (tuple of float, optional) – Beam centre (x, y) in pixels. If provided, overwrites self.center before integrating. If None, uses self.center as computed at initialisation.

  • plot (bool, optional) – If True, display the integrated I(q) pattern. Default is False.

Returns:

  • q (ndarray) – Scattering vector in Å⁻¹.

  • I (ndarray) – Azimuthally averaged intensity.

plot(vmin=-4, vmax=0, cmap='jet', display_mask=False)[source]
plot_recalibrated_image(**kwargs)[source]

Display the diffraction image with the detected beam centre.

Runs recalibrate_from_isocurve() with plot=True to trigger the diagnostic figure, using self.center as the initial estimate. The result is not stored.

Parameters:

**kwargs – Extra keyword arguments forwarded to recalibrate_from_isocurve() (e.g. n_levels, level_range, rms_rel_max, min_arc_deg, cluster_window).

inspect_histogram(bins=256, log_scale=True, exclude_zero=False, saturation_threshold=0.98, percentile_clip=99.9999)[source]

Plot the grey-level histogram of the image to assess camera linearity.

Always displays two side-by-side subplots:

  • Left — full image (no mask), full x-axis range, so that saturated pixels from e.g. the direct beam are visible.

  • Right — valid pixels only (mask applied, if a mask was provided), with the x-axis clipped to percentile_clip to reveal the bulk distribution.

A smooth, monotonically decreasing histogram with no spike at the maximum indicates a linear camera response.

Parameters:

  • bins (int, optional) – Number of histogram bins. Default is 256.

  • log_scale (bool, optional) – If True (default), both y-axes are in log scale.

  • exclude_zero (bool, optional) – If True, zero-valued pixels are excluded from both histograms. Default is False.

  • saturation_threshold (float, optional) – Fraction of the global maximum above which pixels are flagged as potentially saturated. A vertical red dashed line is drawn at this value on both subplots. Default is 0.98.

  • percentile_clip (float, optional) – Percentile used to clip the x-axis of the masked (right) subplot only. Useful when a few very bright pixels compress the distribution towards zero. Default is 99.9999. Set to 100 to disable clipping.

Returns:

  • counts_raw (ndarray) – Pixel counts per bin for the unmasked histogram.

  • edges_raw (ndarray) – Bin edges for the unmasked histogram.

  • counts_masked (ndarray or None) – Pixel counts per bin for the masked histogram, or None if no mask is defined.

  • edges_masked (ndarray or None) – Bin edges for the masked histogram, or None if no mask.

extract_epdf(ref_diffraction_image=None, ref_poni_file=None, composition='Au', rmin=0.1, rmax=50.0, rstep=0.01, outputfile=None, interactive=True, plot=False, mtf_file=None, bgscale=1, qmin=1.5, qmax=24, qmaxinst=24, rpoly=1.4)[source]

Extract the ePDF from the SAED data (convenience wrapper).

Creates a SAEDProcessor for the reference image if provided (which automatically computes its own beam centre via isocurve at initialisation), then delegates to the standalone extract_epdf() function.

Parameters:

  • ref_diffraction_image (str, optional) – Path to the reference (background) diffraction image.

  • ref_poni_file (str, optional) – Path to a PONI file for the reference image if it differs from the sample.

  • composition (str, optional) – Chemical formula of the sample (e.g. 'Au', 'SiO2'). Default is 'Au'.

  • rmin, rmax, rstep (float, optional) – Real-space range and step for G(r) in Å.

  • outputfile (str, optional) – Path for the output .gr file. Auto-generated if None.

  • interactive (bool, optional) – If True (default), open the interactive slider GUI.

  • plot (bool, optional) – If True, display plots in non-interactive mode.

  • mtf_file (str, optional) – Not used in this wrapper (MTF applied at initialisation).

  • bgscale (float, optional) – Background scaling factor. Default is 1.

  • qmin, qmax, qmaxinst (float, optional) – Q-range limits in Å⁻¹ for PDF computation.

  • rpoly (float, optional) – Polynomial background degree control (PDFgetX3 convention).

Returns:

results (PDFResultsReference or tuple) – Interactive mode: PDFResultsReference supporting r, g = results unpacking. Non-interactive mode: (r, G) tuple of ndarrays.

epdfsuite.ePDFsuite.extract_epdf(sample_processor, ref_processor=None, composition='Au', rmin=0.1, rmax=50.0, rstep=0.01, outputfile=None, interactive=True, plot=False, bgscale=1, qmin=1.5, qmax=24, qmaxinst=24, rpoly=1.4)[source]

Extract the electron Pair Distribution Function (ePDF) from SAED data.

Integrates each SAEDProcessor to a 1D I(q) profile, then calls compute_ePDF(). In interactive mode an ipywidgets GUI is shown; in non-interactive mode G(r) is computed once and saved to a .gr file.

Parameters:

  • sample_processor (SAEDProcessor) – Processor loaded with the sample diffraction image. Set sample_processor.initial_center before calling if needed.

  • ref_processor (SAEDProcessor, optional) – Processor loaded with the background/reference image. If None, no background subtraction is performed.

  • composition (str, optional) – Chemical formula of the sample (e.g. 'Au', 'Fe2O3'). Default is 'Au'.

  • rmin, rmax, rstep (float, optional) – Real-space range and step for G(r) in Å. Defaults: 0.1, 50.0, 0.01.

  • outputfile (str, optional) – Path for the output .gr file. Auto-generated from the sample filename if None.

  • interactive (bool, optional) – If True (default), open the interactive slider GUI via PDFInteractive.

  • plot (bool, optional) – If True, display G(r) and F(Q) in non-interactive mode.

  • bgscale (float, optional) – Background scaling factor applied to the reference. Default is 1.

  • qmin, qmax, qmaxinst (float, optional) – Q-range limits in Å⁻¹ used for the Fourier transform and polynomial background fitting.

  • rpoly (float, optional) – Polynomial degree control (PDFgetX3 convention). Default is 1.4.

Returns:

results (PDFResultsReference or tuple) – Interactive mode: PDFResultsReference — supports r, g = results unpacking after slider adjustment. Non-interactive mode: (r, G) tuple of ndarrays.

Examples

>>> sample = SAEDProcessor('sample.dm4', poni_file='calib.poni')
>>> sample.initial_center = (335, 275)
>>> ref = SAEDProcessor('ref.dm4', poni_file='calib.poni')
>>> results = extract_epdf(sample, ref, composition='Au', interactive=False)
>>> r, G = results
class epdfsuite.ePDFsuite.PDFResultsReference(pdf_interactive)[source]

Bases: object

Proxy object providing access to the most recent PDF results from interactive mode.

Wraps a PDFInteractive instance and supports tuple unpacking (r, g = reference) so that the same syntax works whether the extraction is interactive or not. Values reflect the last slider state — call r, g = results after adjusting the sliders.

property r

Real-space distance axis in Å from the last computation.

Type:

ndarray

property g

G(r) values in Å⁻² from the last computation.

Type:

ndarray

class epdfsuite.ePDFsuite.PDFInteractive(sample_processor, ref_processor=None, composition='Au', rmin=0, rmax=50, rstep=0.01, xray=False, outputfile='./pdf_results.csv')[source]

Bases: object

Jupyter widget GUI for interactive ePDF parameter optimisation.

Displays ipywidgets sliders for bgscale, qmin, qmax, qmaxinst, and rpoly, recomputing G(r) in real time. Results can be exported to a .gr file via the Save button.

Intended to be created by extract_epdf() — not directly by users.

update_plot(bgscale, qmin, qmax, qmaxinst, rpoly, lorch)[source]

Recompute G(r) and refresh the output plot.

Called automatically by ipywidgets.interactive_output whenever a slider value changes. Stores the result in self.last_r and self.last_G.

Parameters:

  • bgscale (float) – Background scaling factor.

  • qmin, qmax, qmaxinst (float) – Q-range limits in Å⁻¹.

  • rpoly (float) – Polynomial degree control parameter.

  • lorch (bool) – Whether to apply the Lorch modification function.

save_results(b, outputfile='./pdf_results.gr')[source]

Save the last computed G(r) to a .gr text file.

The file format is compatible with PDFgetX3 / PDFBatchAnalysis, with a structured header containing all computation parameters.

Parameters:

  • b (widget button event) – Unused; required by the ipywidgets callback signature.

  • outputfile (str, optional) – Output file path. Default is './pdf_results.gr'.

show()[source]

Render and display the interactive GUI in a Jupyter notebook.

Computes G(r) with the current slider values before displaying the interface, so that last_r and last_G are immediately available for tuple unpacking.

epdfsuite.ePDFsuite.extract_ePDF_from_mutliple_files(dm4_files, ref_diffraction_image=None, ref_poni_file=None, composition='Au', rmin=0.1, rmax=50.0, rstep=0.01, qmin=1.5, qmax=24, qmaxinst=24, bgscale=1.0, rpoly=1.4, outputfile=None, interactive=True, poni_file=None, beamstop=False, plot=False, verbose=False)[source]

Extract ePDF by averaging over multiple SAED image files.

Integrates each file independently, interpolates all profiles onto the q-grid of the first file, computes an average I(q), and calls compute_ePDF().

Parameters:

  • dm4_files (list of str) – Paths to the SAED image files (DM4, DM3, tif, tiff).

  • ref_diffraction_image (str, optional) – Path to the background/reference diffraction image.

  • ref_poni_file (str, optional) – Path to a PONI file for the reference if different from the sample.

  • composition (str, optional) – Chemical formula of the sample. Default is 'Au'.

  • rmin, rmax, rstep (float, optional) – Real-space range and step for G(r) in Å.

  • qmin, qmax, qmaxinst (float, optional) – Q-range limits in Å⁻¹ for PDF computation.

  • bgscale (float, optional) – Background scaling factor. Default is 1.0.

  • rpoly (float, optional) – Polynomial degree control (PDFgetX3 convention). Default is 1.4.

  • outputfile (str, optional) – Output .gr file path. Auto-generated if None.

  • interactive (bool, optional) – If True (default), open the interactive slider GUI.

  • poni_file (str, optional) – Path to the pyFAI PONI calibration file.

  • beamstop (bool, optional) – Reserved for future use. Default is False.

  • plot (bool, optional) – If True, display plots in non-interactive mode.

  • verbose (bool, optional) – If True, print processing details. Default is False.