autoemxsp.runners.batch_acquire_and_analyze module

Automated X-Ray Spectral Acquisition and Analysis

This module configures and runs automated collection and (optionally) quantification of EDS/WDS spectra for powder samples using an electron microscope (EM) with a specified substrate and calibration.

Import this module in your own Python code and call the batch_acquire_and_analyze() function, passing your desired configuration and sample list as arguments. This enables integration into larger automation workflows or pipelines.

Workflow includes:

  • Configuration of microscope, measurement, substrate, and fitting parameters

  • Sample setup (elements, position, reference formulae)

  • Calibration and quantification options

  • Optional clustering for compositional analysis

  • Automated or manual navigation and acquisition modes

Requirements:

  • Proper instrument calibration files and instrument driver for the selected microscope

Typical usage:

  • Edit the ‘samples’ list to define your standards or unknowns

  • Adjust configuration parameters as needed, either directly in the script or by passing them to batch_acquire_and_analyze

  • Run the script, or import and call batch_acquire_and_analyze() to perform spectrum collection and (optionally) quantification for one or multiple samples at a time

param samples:
List of sample definitions. Each dictionary must contain:

  • ‘ID’ (str): Sample identifier (SampleConfig.ID).

  • ‘els’ (list of str): List of expected element symbols (SampleConfig.elements).

  • ‘pos’ (tuple of float): (x, y) stage coordinates in mm (SampleConfig.center_pos).

  • ‘cnd’ (list of str, optional): Reference chemical formulae for known phases (ClusteringConfig.ref_formulae).

type samples:

list of dict

param microscope_ID:

Identifier for the microscope hardware. Must correspond to a calibration folder in ./XSp_calibs/Microscopes/<ID> (MicroscopeConfig.ID). Default is ‘PhenomXL’.

type microscope_ID:

str, optional

param microscope_type:

Type of microscope. Allowed: ‘SEM’ (implemented), ‘STEM’ (not implemented). Default is ‘SEM’ (MicroscopeConfig.type).

type microscope_type:

str, optional

param measurement_type:

Measurement type. Allowed: ‘EDS’ (implemented), ‘WDS’ (not implemented). Default is ‘EDS’ (MeasurementConfig.type).

type measurement_type:

str, optional

param measurement_mode:

Acquisition mode (e.g., ‘point’, ‘map’), defining beam/detector calibration settings. Default is ‘point’ (MeasurementConfig.mode).

type measurement_mode:

str, optional

param quantification_method:

Quantification method. Currently only ‘PB’ (Phi-Rho-Z) is implemented. Default is ‘PB’ (QuantConfig.method).

type quantification_method:

str, optional

param sample_type:

Sample type. Allowed: ‘powder’ (implemented), ‘bulk’, ‘film’ (not implemented). Default is ‘powder’ (SampleConfig.type).

type sample_type:

str, optional

param sample_halfwidth:

Half-width of the sample area in mm for mapping/acquisition. Default is 3.0 (SampleConfig.half_width_mm).

type sample_halfwidth:

float, optional

param sample_substrate_type:

Type of sample substrate. Allowed: ‘Ctape’, ‘None’. Default is ‘Ctape’ (SampleSubstrateConfig.type).

type sample_substrate_type:

str, optional

param sample_substrate_shape:

Shape of the substrate. Allowed: ‘circle’, ‘square’. Default is ‘circle’ (SampleSubstrateConfig.shape).

type sample_substrate_shape:

str, optional

param sample_substrate_width_mm:

Lateral dimension of substrate holder in mm (SampleSubstrateConfig.stub_w_mm).

type sample_substrate_width_mm:

float, optional

param working_distance:

Working distance in mm for acquisition. If None, taken from microscope driver. Default is 5.0 (MeasurementConfig.working_distance).

type working_distance:

float, optional

param beam_energy:

Electron beam energy in keV. Default is 15.0 (MeasurementConfig.beam_energy_keV).

type beam_energy:

float, optional

param spectrum_lims:

Lower and upper energy limits for spectrum fitting in eV. Default is (14, 1100) (QuantConfig.spectrum_lims).

type spectrum_lims:

tuple of float, optional

param use_instrument_background:

Whether to use instrument background files during fitting. If False, background is computed during fitting. Default is False (QuantConfig.use_instrument_background).

type use_instrument_background:

bool, optional

param interrupt_fits_bad_spectra:

If True, fitting stops early for poor-quality spectra. Default is True (QuantConfig.interrupt_fits_bad_spectra).

type interrupt_fits_bad_spectra:

bool, optional

param max_analytical_error_percent:

Maximum allowed analytical error (%) for compositions to be included in clustering. Default is 5 (ClusteringConfig.max_analytical_error_percent).

type max_analytical_error_percent:

float, optional

param min_bckgrnd_cnts:

Minimum background counts required for a spectrum not to be filtered out. Default is 5 (QuantConfig.min_bckgrnd_cnts).

type min_bckgrnd_cnts:

float, optional

param quant_flags_accepted:

List of acceptable quantification flags; others are filtered out before clustering. Default is [0, -1] (ClusteringConfig.quant_flags_accepted).

type quant_flags_accepted:

list of int, optional

param max_n_clusters:

Maximum number of clusters allowed in compositional clustering. Default is 6 (ClusteringConfig.max_k).

type max_n_clusters:

int, optional

param show_unused_comps_clust:

Whether to display unused compositions in clustering plots. Default is True (PlotConfig.show_unused_comps_clust).

type show_unused_comps_clust:

bool, optional

param is_manual_navigation:

If True, navigation to sample positions is manual. Default is False (MeasurementConfig.is_manual_navigation).

type is_manual_navigation:

bool, optional

param is_auto_substrate_detection:

If True, substrate elements are detected automatically. Implemented only for ‘Ctape’ substrates. Default is False (SampleSubstrateConfig.auto_detection).

type is_auto_substrate_detection:

bool, optional

param auto_adjust_brightness_contrast:

If True, brightness/contrast are set automatically. Default is True (MicroscopeConfig.is_auto_BC).

type auto_adjust_brightness_contrast:

bool, optional

param contrast:

Manual contrast setting (required if auto_adjust_brightness_contrast is False). Default is 4.3877 (MicroscopeConfig.contrast).

type contrast:

float, optional

param brightness:

Manual brightness setting (required if auto_adjust_brightness_contrast is False). Default is 0.4504 (MicroscopeConfig.brightness).

type brightness:

float, optional

param quantify_spectra:

If True, perform quantification after acquisition. Default is False.

type quantify_spectra:

bool, optional

param min_n_spectra:

Minimum number of spectra to acquire. Default is 50 (MeasurementConfig.min_n_spectra).

type min_n_spectra:

int, optional

param max_n_spectra:

Maximum number of spectra to acquire. Default is 100 (MeasurementConfig.max_n_spectra).

type max_n_spectra:

int, optional

param target_Xsp_counts:

Target counts for spectrum acquisition. Default is 50000 (MeasurementConfig.target_acquisition_counts).

type target_Xsp_counts:

int, optional

param max_XSp_acquisition_time:

Maximum acquisition time in seconds. If None, estimated from target counts. Default is None (MeasurementConfig.max_acquisition_time).

type max_XSp_acquisition_time:

float, optional

param els_substrate:

List of substrate element symbols. Default is [‘C’, ‘O’, ‘Al’] (SampleSubstrateConfig.elements).

type els_substrate:

list of str, optional

param powder_meas_cfg_kwargs:

Additional keyword arguments for PowderMeasurementConfig.

type powder_meas_cfg_kwargs:

dict, optional

param bulk_meas_cfg_kwargs:

Additional keyword arguments for BulkMeasurementConfig.

type bulk_meas_cfg_kwargs:

dict, optional

param output_filename_suffix:

String appended to output filenames. Default is ‘’.

type output_filename_suffix:

str, optional

param development_mode:

If True, enables development/debug features. Default is False.

type development_mode:

bool, optional

param verbose:

If True, print verbose output. Default is True.

type verbose:

bool, optional

param results_dir:

Directory where results are saved. Default is None.

type results_dir:

str, optional

param Created on Fri Jul 26 09:

type Created on Fri Jul 26 09:

34:34 2024

param @author:

type @author:

Andrea

autoemxsp.runners.batch_acquire_and_analyze.batch_acquire_and_analyze(samples: List[Dict[str, Any]], microscope_ID: str = 'PhenomXL', microscope_type: str = 'EDS', measurement_type: str = 'EDS', measurement_mode: str = 'point', quantification_method: str = 'PB', sample_type: str = 'powder', sample_halfwidth: float = 3.0, sample_substrate_type: str = 'Ctape', sample_substrate_shape: str = 'circle', sample_substrate_width_mm: float = 12, working_distance: float = 5, working_distance_tolerance: float = 1, beam_energy: float = 15.0, spectrum_lims: Tuple[float, float] = (14, 1100), use_instrument_background: bool = False, interrupt_fits_bad_spectra: bool = True, max_analytical_error_percent: float = 5, min_bckgrnd_cnts: float = 5, quant_flags_accepted: List[int] = [0, -1], max_n_clusters: int = 6, show_unused_comps_clust: bool = True, is_manual_navigation: bool = False, is_auto_substrate_detection: bool = False, auto_adjust_brightness_contrast: bool = True, contrast: float = 4.3877, brightness: float = 0.4504, quantify_spectra: bool = False, min_n_spectra: int = 50, max_n_spectra: int = 100, target_Xsp_counts: int = 50000, max_XSp_acquisition_time: float = None, els_substrate: List[str] = None, powder_meas_cfg_kwargs: Dict[str, Any] = None, bulk_meas_cfg_kwargs: Dict[str, Any] = None, standards_dict: Dict[str, float] = None, output_filename_suffix: str = '', development_mode: bool = False, verbose: bool = True, results_dir: str = None) → None[source]

Batch acquisition (and optional quantification) of X-ray spectra for a list of powder samples.

Parameters:

  • samples (list of dict) –

    List of sample definitions. Each dictionary must contain:

    • ’ID’ (str): Sample identifier (SampleConfig.ID).

    • ’els’ (list of str): List of expected element symbols (SampleConfig.elements).

    • ’pos’ (tuple of float): (x, y) stage coordinates in mm (SampleConfig.center_pos).

    • ’cnd’ (list of str, optional): Reference chemical formulae for known phases (ClusteringConfig.ref_formulae).

  • microscope_ID (str, optional) – Identifier for the microscope hardware. Must correspond to a calibration folder in ./XSp_calibs/Microscopes/<ID> (MicroscopeConfig.ID). Default is ‘PhenomXL’.

  • microscope_type (str, optional) – Type of microscope. Allowed: ‘SEM’ (implemented), ‘STEM’ (not implemented). Default is ‘SEM’ (MicroscopeConfig.type).

  • measurement_type (str, optional) – Measurement type. Allowed: ‘EDS’ (implemented), ‘WDS’ (not implemented). Default is ‘EDS’ (MeasurementConfig.type).

  • measurement_mode (str, optional) – Acquisition mode (e.g., ‘point’, ‘map’), defining beam/detector calibration settings. Default is ‘point’ (MeasurementConfig.mode).

  • quantification_method (str, optional) – Quantification method. Currently only ‘PB’ (Phi-Rho-Z) is implemented. Default is ‘PB’ (QuantConfig.method).

  • sample_type (str, optional) – Sample type. Allowed: ‘powder’ (implemented), ‘bulk’, ‘film’ (not implemented). Default is ‘powder’ (SampleConfig.type).

  • sample_halfwidth (float, optional) – Half-width of the sample area in mm for mapping/acquisition. Default is 3.0 (SampleConfig.half_width_mm).

  • sample_substrate_type (str, optional) – Type of sample substrate. Allowed: ‘Ctape’, ‘None’. Default is ‘Ctape’ (SampleSubstrateConfig.type).

  • sample_substrate_shape (str, optional) – Shape of the substrate. Allowed: ‘circle’, ‘square’. Default is ‘circle’ (SampleSubstrateConfig.shape).

  • sample_substrate_width_mm (float, optional) – Lateral dimension of substrate holder in mm (SampleSubstrateConfig.stub_w_mm).

  • working_distance (float, optional) – Working distance in mm for acquisition. If None, taken from microscope driver. Default is 5.0 (MeasurementConfig.working_distance).

  • working_distance_tolerance (float, optional) –

    Defines maximum accepted deviation of working distance from its typical value, in mm.

    Used to prevent gross mistakes from EM autofocus. Default: 1 mm.

  • beam_energy (float, optional) – Electron beam energy in keV. Default is 15.0 (MeasurementConfig.beam_energy_keV).

  • spectrum_lims (tuple of float, optional) – Lower and upper energy limits for spectrum fitting in eV. Default is (14, 1100) (QuantConfig.spectrum_lims).

  • use_instrument_background (bool, optional) – Whether to use instrument background files during fitting. If False, background is computed during fitting. Default is False (QuantConfig.use_instrument_background).

  • interrupt_fits_bad_spectra (bool, optional) – If True, fitting stops early for poor-quality spectra. Default is True (QuantConfig.interrupt_fits_bad_spectra).

  • max_analytical_error_percent (float, optional) – Maximum allowed analytical error (%) for compositions to be included in clustering. Default is 5 (ClusteringConfig.max_analytical_error_percent).

  • min_bckgrnd_cnts (float, optional) – Minimum background counts required for a spectrum not to be filtered out. Default is 5 (QuantConfig.min_bckgrnd_cnts).

  • quant_flags_accepted (list of int, optional) – List of acceptable quantification flags; others are filtered out before clustering. Default is [0, -1] (ClusteringConfig.quant_flags_accepted).

  • max_n_clusters (int, optional) – Maximum number of clusters allowed in compositional clustering. Default is 6 (ClusteringConfig.max_k).

  • show_unused_comps_clust (bool, optional) – Whether to display unused compositions in clustering plots. Default is True (PlotConfig.show_unused_comps_clust).

  • is_manual_navigation (bool, optional) – If True, navigation to sample positions is manual. Default is False (MeasurementConfig.is_manual_navigation).

  • is_auto_substrate_detection (bool, optional) – If True, substrate elements are detected automatically. Implemented only for ‘Ctape’ substrates. Default is False (SampleSubstrateConfig.auto_detection).

  • auto_adjust_brightness_contrast (bool, optional) – If True, brightness/contrast are set automatically. Default is True (MicroscopeConfig.is_auto_BC).

  • contrast (float, optional) – Manual contrast setting (required if auto_adjust_brightness_contrast is False). Default is 4.3877 (MicroscopeConfig.contrast).

  • brightness (float, optional) – Manual brightness setting (required if auto_adjust_brightness_contrast is False). Default is 0.4504 (MicroscopeConfig.brightness).

  • quantify_spectra (bool, optional) – If True, perform quantification after acquisition. Default is False.

  • min_n_spectra (int, optional) – Minimum number of spectra to acquire. Default is 50 (MeasurementConfig.min_n_spectra).

  • max_n_spectra (int, optional) – Maximum number of spectra to acquire. Default is 100 (MeasurementConfig.max_n_spectra).

  • target_Xsp_counts (int, optional) – Target counts for spectrum acquisition. Default is 50000 (MeasurementConfig.target_acquisition_counts).

  • max_XSp_acquisition_time (float, optional) – Maximum acquisition time in seconds. If None, estimated from target counts. Default is None (MeasurementConfig.max_acquisition_time).

  • els_substrate (list of str, optional) – List of substrate element symbols. Default is [‘C’, ‘O’, ‘Al’] (SampleSubstrateConfig.elements).

  • powder_meas_cfg_kwargs (dict, optional) – Additional keyword arguments for PowderMeasurementConfig.

  • bulk_meas_cfg_kwargs (dict, optional) – Additional keyword arguments for BulkMeasurementConfig.

  • standards_dict (dict, optional) – Dictionary of reference PB values from experimental standards. Default : None. If None, dictionary of standards is loaded from the XSp_calibs/Your_Microscope_ID directory. Provide standards_dict only when providing different standards from those normally used for quantification.

  • output_filename_suffix (str, optional) – String appended to output filenames. Default is ‘’.

  • development_mode (bool, optional) – If True, enables development/debug features. Default is False.

  • verbose (bool, optional) – If True, print verbose output. Default is True.

  • results_dir (str, optional) – Directory where results are saved. Default is None.

Returns:

comp_analyzer – The composition analysis object containing the results and methods for further analysis.

Return type:

EMXSp_Composition_Analyzer