autoemx.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

Created on Fri Jul 26 09:34:34 2024

@author: Andrea

autoemx.runners.batch_acquire_and_analyze.batch_acquire_and_analyze(samples: List[Dict[str, Any]], microscope_ID: str = 'PhenomXL', microscope_type: str = 'SEM', measurement_type: str = 'EDS', measurement_mode: str = 'point', quantification_method: str = 'PB', sample_type: str = 'powder', sample_halfwidth: float = 2.9, 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, use_project_specific_std_dict: bool = False, interrupt_fits_bad_spectra: bool = True, max_analytical_error_percent: float = 5.0, min_bckgrnd_cnts: float | None = 5.0, quant_flags_accepted: List[int] | None = None, 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 | None = None, brightness: float | None = None, quantify_spectra: bool = False, is_known_phase_mixture: bool = False, min_n_spectra: int = 50, max_n_spectra: int = 100, target_Xsp_counts: int = 50000, max_XSp_acquisition_time: float | None = None, els_substrate: List[str] | None = None, powder_meas_cfg_kwargs: Dict[str, Any] | None = None, bulk_meas_cfg_kwargs: Dict[str, Any] | None = None, standards_dict: Dict[str, float] | None = None, output_filename_suffix: str = '', saved_images_extension: str = 'png', save_raw_images: bool = False, annotate_particle_images: bool = False, development_mode: bool = False, verbose: bool = True, results_dir: str | None = None, xsp_spot_selector: Callable[[XSpSpotSelectionContext], Sequence[Tuple[int, int]]] | None = None, particle_ids: Sequence[int] | None = None, particle_coords_mm: Sequence[Sequence[float]] | None = None, on_sample_done: Callable[[str, BaseException | None], None] | None = None) → EMXSp_Composition_Analyzer[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).

    • ’particle_ids’ (list of int, optional): Per-sample override for list-mode ledger particle ids (requires par_selection_mode='list').

    • ’particle_coords_mm’ (list of (x, y), optional): Per-sample override for list-mode absolute stage coordinates in mm.

  • 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’ (QuantificationOptionsConfig.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) (QuantificationOptionsConfig.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 (QuantificationOptionsConfig.use_instrument_background).

  • use_project_specific_std_dict (bool, optional) – If True, loads standards from project folder (i.e. results_dir) during quantification. Default: False

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

  • 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 (ClusteringConfig.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). See the user documentation page “Quantification flags (quant_flag)”.

  • 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.

  • is_known_phase_mixture (bool, optional) – Whether the samples are mixtures of known phases (their candidate phases, ‘cnd’). If True, spectra are quantified with the reference P/B values of these phases, and the analysis characterizes their intermixing (QuantificationOptionsConfig.is_known_phase_mixture). 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’] (defaults.substrate_els).

  • 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 ‘’.

  • saved_images_extension (str, optional) – Extension used for SEM image files saved during acquisition. Default is ‘png’.

  • save_raw_images (bool, optional) – Whether to also save the non-annotated version of annotated SEM images (frame images, and particle images when annotate_particle_images is True). Default is False.

  • annotate_particle_images (bool, optional) – Whether to draw the spectrum spots (dot + spectrum ID) and a scale bar on the saved particle images. If False, raw particle images are saved; annotated copies can be made afterwards with Annotate_Particle_Images.py. Default is False.

  • 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.

  • xsp_spot_selector (callable, optional) –

    Callback invoked on each particle when powder_meas_cfg.par_spot_selection_mode='callback'. Called repeatedly on the same particle until it returns []. Signature:

    spots = xsp_spot_selector(context: XSpSpotSelectionContext)

    Return pixel (x, y) coordinates in the current frame. Return [] to finish with the current particle (including to skip it). Spots are validated against image bounds only. Stage navigation to the next particle remains automatic; spots are measured via beam positioning with drift correction like automated mode.

  • particle_ids (sequence of int, optional) – Global list of ledger particle ids to visit when powder_meas_cfg.par_selection_mode='list'. Mutually exclusive with particle_coords_mm. Can be overridden per sample via sample['particle_ids']. Missing ids raise before acquisition starts.

  • particle_coords_mm (sequence of (x, y), optional) – Global list of absolute stage coordinates in mm to visit when par_selection_mode='list'. Mutually exclusive with particle_ids. Can be overridden per sample via sample['particle_coords_mm'].

  • on_sample_done (callable, optional) –

    Called after each sample with its ID and None if it was acquired (and quantified) successfully, or the exception that made it fail (the batch then continues with the next sample). Signature:

    on_sample_done(sample_id: str, error: Optional[BaseException])

    Errors raised by the callback are logged and do not stop the batch.

Returns:

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

Return type:

EMXSp_Composition_Analyzer