autoemxsp.config.classes module

AutoEMXSp configuration dataclasses.

Created on Mon Jul 28 10:33:35 2025

@author: Andrea

This module provides configuration dataclasses for all stages of an automated X-ray spectroscopy workflow, including microscope setup, sample and substrate definition, measurement and acquisition settings, spectrum fitting, quantification and filtering, powder measurement, clustering, and plotting.

Configurations:

• MicroscopeConfig: Settings for microscope hardware, calibration, and imaging parameters.

• SampleConfig: Defines the sample’s identity, elements, and spatial properties.

• SampleSubstrateConfig: Specifies the substrate composition and geometry supporting the sample.

• MeasurementConfig: Controls measurement type, beam parameters, and acquisition settings.

• QuantConfig: Options for spectral fitting and quantification.

• PowderMeasurementConfig: Settings for analyzing powder samples and particle selection.

• BulkMeasurementConfig: Settings for analyzing non-powder samples.

• ClusteringConfig: Configures clustering algorithms and filtering of X-ray spectra.

• PlotConfig: Options for saving, displaying, and customizing plots.

Each dataclass includes attribute documentation and input validation.

class autoemxsp.config.classes.MicroscopeConfig(ID: str = 'PhenomXL', type: str = 'SEM', detector_type: str = 'BSD', is_auto_BC: bool = True, brightness: float | None = None, contrast: float | None = None, energy_zero: float | None = None, bin_width: float | None = None)

Bases: object

Configuration for the microscope hardware.

ID

Identifier for the microscope, defining instrument calibrations at ./XSp_calibs/Microscopes/ID.

Type:

str

type

Type of microscope. Allowed: ‘SEM’ (implemented), ‘STEM’ (not implemented).

Type:

str

is_auto_BC

If True, brightness/contrast are set automatically.

Type:

bool

brightness

Manual brightness value; required if is_auto_BC is False.

Type:

Optional[float]

contrast

Manual contrast value; required if is_auto_BC is False.

Type:

Optional[float]

energy_zero

Set from detector calibration files during spectral collection.

Type:

Optional[float]

bin_width

Set from detector calibration files during spectral collection.

Type:

Optional[float]

Notes

• If is_auto_BC is False, both brightness and contrast must be provided.

• STEM mode is not implemented and will raise NotImplementedError.

• The microscope ID must correspond to a folder at ./XSp_calibs/Microscopes/ID containing all necessary calibration files.

ID: str = 'PhenomXL'

type: str = 'SEM'

detector_type: str = 'BSD'

is_auto_BC: bool = True

brightness: float | None = None

contrast: float | None = None

energy_zero: float | None = None

bin_width: float | None = None

ALLOWED_TYPES = ('SEM', 'STEM')

ALLOWED_DETECTOR_TYPES = 'BSD'

class autoemxsp.config.classes.SampleConfig(ID: str, elements: List[str], type: str = 'powder', w_frs: Dict[str, float] = None, center_pos: Tuple[float, float] = (0.0, 0.0), half_width_mm: float = 2.9, is_powder_sample: bool = False, is_surface_rough: bool = False, is_grid_acquisition: bool = False, is_particle_acquisition: bool = False)

Bases: object

Configuration for the sample.

ID

Identifier for the sample.

Type:

str

elements

List of elemental symbols (e.g., [‘Fe’, ‘O’]).

Type:

List[str]

type

Sample type. Allowed types: - powder: Expects particles, and uses geometrical correction factors during spectral fits. - powder_continuous: Expects a quasi-continuous powder mixture, sampled in a grid (NO PARTICLE DETECTION APPLIED).

Applies geometrical correction factors during spectral fits.

• bulk: Expects a flat, continuous surface, sampled in a grid. Does not apply geometrical factors.

• bulk_rough: Expects a continuous surface, sampled in a grid. Applies geometrical factors.

• film: NOT IMPLEMENTED YET

Type:

str

w_frs

Dict of elemental mass fractions to be kept fixed (e.g., {‘Fe’: 0.4, ‘O’: 0.6}). Normally not used

Type:

Dict[str,float]

center_pos

(x, y) center position of the sample on the stage, in mm.

Type:

Tuple[float, float]

half_width_mm

Half-width of the sample in millimeters.

Type:

float

Notes

• Only ‘powder’ and ‘bulk’ type are implemented. ‘film’ will raise NotImplementedError.

• Element symbols are validated. An error is raised if any symbol is unrecognized.

ID: str

elements: List[str]

type: str = 'powder'

w_frs: Dict[str, float] = None

center_pos: Tuple[float, float] = (0.0, 0.0)

half_width_mm: float = 2.9

ALLOWED_TYPES = ('powder', 'powder_continuous', 'bulk', 'bulk_rough', 'film')

POWDER_SAMPLES_TYPES = ['powder', 'powder_continuous']

is_powder_sample: bool = False

ROUGH_SURFACE_TYPES = ['powder', 'powder_continuous', 'bulk_rough']

is_surface_rough: bool = False

GRID_ACQUISITION_TYPES = ('bulk', 'powder_continuous', 'bulk_rough', 'film')

is_grid_acquisition: bool = False

PARTICLE_ACQUISITION_TYPES = 'powder'

is_particle_acquisition: bool = False

class autoemxsp.config.classes.SampleSubstrateConfig(elements: ~typing.List[str] = <factory>, type: str = 'Ctape', shape: str = 'circle', auto_detection: bool = True, stub_w_mm: float = 12)

Bases: object

Configuration for the sample substrate.

elements

List of element symbols present in the sample substrate.

Type:

List[str]

type

Type of the sample substrate. Allowed values: ‘Ctape’.

Type:

str

shape

Shape of the sample substrate. Allowed values: ‘circle’, ‘rectangle’.

Type:

str

auto_detection

Whether to attempt automatic detection of substrate. (implemented only for type = Ctape & shape = ‘circle’)

Type:

bool

stub_w_mm

Lateral dimension of substrate holder in mm, used for determining image size for auto_detection.

Type:

float

Notes

• Element symbols are validated. An error is raised if any symbol is unrecognized.

elements: List[str]

type: str = 'Ctape'

shape: str = 'circle'

auto_detection: bool = True

stub_w_mm: float = 12

ALLOWED_TYPES = ('Ctape', 'None')

ALLOWED_SHAPES = ('circle', 'square')

ALLOWED_AUTO_DETECTION_TYPES = 'Ctape'

class autoemxsp.config.classes.MeasurementConfig(type: str = 'EDS', mode: str = 'point', working_distance: float = None, working_distance_tolerance: float = 1, beam_energy_keV: float = 15.0, beam_current: float | None = None, emergence_angle: float | None = None, is_manual_navigation: bool = False, max_acquisition_time: float = 30.0, target_acquisition_counts: int = 50000, min_n_spectra: int = 30, max_n_spectra: int = 100)

Bases: object

Configuration for the measurement/acquisition.

type

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

Type:

str

mode

Measurement mode (e.g., ‘point’). Defines set of measurement parameters (i.e., beam current), determining detector calibration parameters

Type:

str

working_distance

Working distance to use for current measurement, in mm. Takes it from EM_driver if left unspecified.

Type:

Optional[float]

working_distance_tolerance

Defines maximum accepted deviation of working distance from its typical value, in mm. Used to prevent gross mistakes from EM autofocus. Default: 1 mm.

Type:

Optional[float]

beam_energy_keV

Electron beam energy in keV.

Type:

float

beam_current

Beam current; must be provided at initialization or via detector channel calibration file.

Type:

Optional[float]

emergence_angle

Emergence angle; updated from microscope driver file if not provided.

Type:

Optional[float]

is_manual_navigation

If True, instrument navigation is performed manually.

Type:

bool

max_acquisition_time

Maximum X-ray spectral acquisition time in seconds.

Type:

float

target_acquisition_counts

Target number of counts for acquisition of X-ray spectrum.

Type:

int

min_n_spectra

Minimum number of spectra to acquire.

Type:

int

max_n_spectra

Maximum number of spectra to acquire.

Type:

int

Notes

• Only ‘EDS’ type is implemented. ‘WDS’ will raise NotImplementedError.

• If beam_current or emergence_angle are not provided, they should be set via calibration or microscope driver.

type: str = 'EDS'

mode: str = 'point'

working_distance: float = None

working_distance_tolerance: float = 1

beam_energy_keV: float = 15.0

beam_current: float | None = None

emergence_angle: float | None = None

is_manual_navigation: bool = False

max_acquisition_time: float = 30.0

target_acquisition_counts: int = 50000

min_n_spectra: int = 30

max_n_spectra: int = 100

PARTICLE_STATS_MEAS_TYPE_KEY = 'particle_stats'

ALLOWED_TYPES = ('EDS', 'WDS', 'particle_stats')

class autoemxsp.config.classes.QuantConfig(method: str = 'PB', spectrum_lims: Tuple[float, float] = (14, 1100), fit_tolerance: float = 0.0001, use_instrument_background: bool = False, interrupt_fits_bad_spectra: bool = True, min_bckgrnd_cnts: int | None = 5, num_CPU_cores: int | None = None)

Bases: object

Configuration for X-ray spectrum fitting and quantification.

method

Method to use for quantification. Currently only accepts ‘PB’

Type:

str

spectrum_lims

Lower and upper spectral index limits.

Type:

Tuple[float, float]

fit_tolerance

lmfit tolerance for fit convergence

Type:

float

use_instrument_background

Whether to use the instrument background in the fit (Default: False). If False, AutoEMXSp computes the background while fitting.

Type:

bool

interrupt_fits_bad_spectra

If True, fitting will stop early for spectra identified as poor quality.

Type:

bool

min_bckgrnd_cnts

Minimum background counts required for spectrum not to be filtered out. Can be None.

Type:

Optional[int]

method: str = 'PB'

spectrum_lims: Tuple[float, float] = (14, 1100)

fit_tolerance: float = 0.0001

use_instrument_background: bool = False

interrupt_fits_bad_spectra: bool = True

min_bckgrnd_cnts: int | None = 5

num_CPU_cores: int | None = None

ALLOWED_METHODS = ['PB']

class autoemxsp.config.classes.PowderMeasurementConfig(is_manual_particle_selection: bool = False, is_known_powder_mixture_meas: bool = False, par_search_frame_width_um: float = None, max_n_par_per_frame: int = 30, max_spectra_per_par: int = 3, max_area_par: float = 300.0, min_area_par: float = 10.0, par_mask_margin: float = 1.0, xsp_spots_distance_um: float = 1.0, par_segmentation_model: str = 'threshold_bright', par_brightness_thresh: int = 100, par_xy_spots_thresh: int = 100, par_feature_selection: str = 'random', par_spot_spacing: str = 'random')

Bases: object

Configuration for powder measurement.

is_manual_particle_selection

Whether to manually navigate sample to select particles to analyse (Default = False).

Type:

bool

is_known_powder_mixture_meas

Whether sample is a known binary mixture of powders. Used to characterize precursor extent of intermixing (Default = False).

Type:

bool

par_search_frame_width_um

Frame width used when searching for particles, in um. Default: min(20*max_par_radius, 500 um)

Type:

float, optional

max_n_par_per_frame

Maximum number of particles analyzed in a single frame. Used to ensure spatial representation of the analyzed sample.

Type:

int

max_spectra_per_par

Maximum number of spot X-ray spectra collected in a single particle. Limiting this ensures more particles are analyzed.

Type:

int

max_area_par

Maximum area (in µm²) for a particle to be considered.

Type:

float

min_area_par

Minimum area (in µm²) for a particle to be considered.

Type:

float

par_mask_margin

Margin (in µm) from particle edge where X-ray spectra should not be collected.

Type:

float

xsp_spots_distance_um

Min distance between X-ray spectrum acquisition points

Type:

float

par_segmentation_model

Model to use for particle segmentation. Default: “threshold_bright”

Type:

str

par_brightness_thresh

Intensity threshold in 8-bit image that defines a particle over a dark background.

Type:

int

par_xy_spots_thresh

Intensity threshold in 8-bit image that defines bright (i.e., thickest) regions in particles. X-ray spectra are acquired only from these regions. Particle pixel intensities are scaled to 8-bit prior threhsolding, i.e., darkest pixel will be set to 0, and brightest to 255.

Type:

int

par_feature_selection

‘random’ for random selection of points within bright regions, ‘peaks’ for brightest peak spots (default: ‘random’).

Type:

str

par_spot_spacing

‘random’ for unbiased spot selecton, ‘maximized’ for maximized spot spacing over particle (default: ‘random’).

Type:

str

DEFAULT_PAR_SEGMENTATION_MODEL = 'threshold_bright'

is_manual_particle_selection: bool = False

is_known_powder_mixture_meas: bool = False

par_search_frame_width_um: float = None

max_n_par_per_frame: int = 30

max_spectra_per_par: int = 3

max_area_par: float = 300.0

min_area_par: float = 10.0

par_mask_margin: float = 1.0

xsp_spots_distance_um: float = 1.0

par_segmentation_model: str = 'threshold_bright'

par_brightness_thresh: int = 100

par_xy_spots_thresh: int = 100

par_feature_selection: str = 'random'

par_spot_spacing: str = 'random'

AVAILABLE_PAR_SEGMENTATION_MODELS = ['threshold_bright', 'Rettenberger2024']

AVAILABLE_FEATURE_SELECTION = ('random', 'peaks')

AVAILABLE_SPOT_SPACING_SELECTION = ('random', 'maximized')

class autoemxsp.config.classes.BulkMeasurementConfig(grid_spot_spacing_um: float = 100.0, min_xsp_spots_distance_um: float = 5.0, image_frame_width_um: float = None, randomize_frames: bool = False, exclude_sample_margin: bool = False)

Bases: object

Configuration for characterization or bulk-like samples.

grid_spot_spacing_um

Distance between grid points to measure, in micrometers (µm).

Type:

float

min_xsp_spots_distance_um

Offset distance for acquisition spot grid if the original grid does not contain enough spots to measure the required number of spectra, in micrometers (µm).

Type:

float

image_frame_width_um

Width of the image frame in micrometers (µm). If not specified, defaults to 10 × grid_spot_spacing_um.

Type:

float, optional

randomize_frames

Whether to randomize the order of spectra acquisition in the constructed grid.

Type:

bool

exclude_sample_margin

Whether to exclude the margin of the sample (useful if contaminated).

Type:

bool

grid_spot_spacing_um: float = 100.0

min_xsp_spots_distance_um: float = 5.0

image_frame_width_um: float = None

randomize_frames: bool = False

exclude_sample_margin: bool = False

class autoemxsp.config.classes.ExpStandardsConfig(is_exp_std_measurement: bool = False, formula: str = '', use_for_mean_PB_calc: bool = True, min_acceptable_PB_ratio: float = 10, quant_flags_accepted: ~typing.List[int] = <factory>, w_frs: ~typing.Dict[str, float] | None = None)

Bases: object

Configuration for the collection of experimental standards.

is_exp_std_measurement

Whether the configuration corresponds to the measurement of an experimental standard (Default = False) If True, a valid formula must be provided and weight fractions will be automatically calculated.

Type:

bool

formula

Chemical formula of the experimental standard. Required if is_exp_std_measurement is True. Must be parseable by pymatgen.core.Composition.

Type:

str

use_for_mean_PB_calc

Whether the acquired experimental standards should be used to calculate the average PB, which is the reference standard value employed generally during spectral quantification (Default = True). This should be set to False when collecting powder standards for quantifying the extent of intermixing in powder standards.

Type:

bool

min_acceptable_PB_ratio

Minimum PB ratio required for a peak to be accepted as a standard. in cnts/cnts*keV^-1 (Deafult = 10).

Type:

float

quant_flags_accepted

List of quantification flags considered acceptable. Other spectra are filtered out before clustering. Quantification flags indicate whether the quantification or the fit of each spectrum is likely to be affected by large errors:

• 0 : Quantification is ok, although it may be affected by large analytical error.

• -1 : As above, but quantification did not converge within 30 steps.

• 1 : Error during EDS acquisition. No fit executed.

• 2 : Total counts < 95% of target counts, likely due to wrong segmentation. No fit executed.

• 3 : Too little low-energy signal, causing poor quantification in that region. No fit executed.

• 4 : Poor fit. Fit interrupted if interrupt_fits_bad_spectra=True.

• 5 : High analytical error (>50%), possibly due to missing element or other major error. Fit interrupted if interrupt_fits_bad_spectra=True.

• 6 : Excessive X-ray absorption. Fit interrupted if interrupt_fits_bad_spectra=True.

• 7 : Excessive contamination from substrate.

• 8 : Too few background counts below reference peak, likely leading to large quantification errors.

• 9 : Unknown fitting error.

• 10 : (Only for measurement of experimental standards) Reference peak missing.

Type:

List[int]

w_frs

Dictionary of element symbols and their corresponding weight fractions (computed via pymatgen) if is_exp_std_measurement is True and formula is valid; otherwise None.

Type:

Optional[Dict[str, float]]

Raises:

ValueError – If is_exp_std_measurement is True but formula is missing or invalid.

is_exp_std_measurement: bool = False

formula: str = ''

use_for_mean_PB_calc: bool = True

min_acceptable_PB_ratio: float = 10

quant_flags_accepted: List[int]

w_frs: Dict[str, float] | None = None

class autoemxsp.config.classes.ClusteringConfig(method: str = 'kmeans', features: ~typing.List[~typing.Any] = <factory>, k: int | None = None, k_finding_method: str = 'silhouette', max_k: int = 6, ref_formulae: ~typing.List[str] = <factory>, max_analytical_error_percent: float = 5, quant_flags_accepted: ~typing.List[int] = <factory>)

Bases: object

Configuration for clustering of compositions and their filtering.

method

Clustering algorithm to use. Allowed: ‘kmeans’ (implemented), ‘dbscan’ (not implemented).

Type:

str

features

Feature set to use for clustering.

Type:

List[Any]

k

If provided, defines a fixed number of clusters.

Type:

Optional[int]

k_finding_method

Method to determine the number of clusters. Set to “forced” if a value of ‘k’ is specified manually. Allowed methods are “silhouette”, “calinski_harabasz”, “elbow”.

Type:

str

max_k

Maximum allowed number of clusters.

Type:

int

ref_formulae

List of possible phases present in the sample, as chemical formula strings.

Type:

List[str]

max_analytical_error_percent

Maximum analytical error acceptable for composition to be considered in phase determination, expressed as w%. Can be None.

Type:

float

quant_flags_accepted

List of quantification flags considered acceptable, others are filtered out prior clustering. Quantification flags indicate whether the quantification or the fit of each spectrum is likely to be affected by large errors:

• 0: Quantification is ok, although it may be affected by large analytical error

• -1: As above, but quantification did not converge within 30 steps

• 1: Error during EDS acquisition. No fit executed

• 2: Total number of counts is lower than 95% of target counts, likely due to wrong segmentation. No fit executed

• 3: Spectrum has too low signal in its low-energy portion, leading to poor quantification in this region. No fit executed

• 4: Poor fit. Fit interrupted if interrupt_fits_bad_spectra=True

• 5: Too high analytical error (>50%) indicating a missing element or other major sources of error. Fit interrupted if interrupt_fits_bad_spectra=True

• 6: Excessive X-ray absorption. Fit interrupted if interrupt_fits_bad_spectra=True

• 7: Excessive signal contamination from substrate

• 8: Too few background counts below reference peak, likely leading to large quantification errors

• 9: Unknown fitting error

Type:

List[int]

method: str = 'kmeans'

features: List[Any]

k: int | None = None

DEFAULT_K_FINDING_METHOD = 'silhouette'

k_finding_method: str = 'silhouette'

max_k: int = 6

ref_formulae: List[str]

max_analytical_error_percent: float = 5

quant_flags_accepted: List[int]

FORCED_K_METHOD_KEY = 'forced'

ALLOWED_METHODS = ('kmeans', 'dbscan')

ALLOWED_FEATURE_SETS = ('w_fr', 'at_fr')

ALLOWED_K_FINDING_METHODS = ('silhouette', 'calinski_harabasz', 'elbow', 'forced')

class autoemxsp.config.classes.PlotConfig(show_unused_comps_clust: bool = True, els_excluded_clust_plot: ~typing.List[str] = <factory>, show_legend_clustering: bool = True, save_plots: bool = True, show_plots: bool = False, use_custom_plots: bool = False)

Bases: object

Configuration for plotting.

show_unused_comps_clust

Whether to plot unused data points in clustering plot.

Type:

bool

els_excluded_clust_plot

Elements to exclude in cluster plot when more than 3 elements are present.

Type:

List[str]

show_legend_clustering bool

Whether to show the legend in the clustering plot. Default: True

save_plots

Whether to save plots to disk.

Type:

bool

show_plots

Whether to display plots interactively.

Type:

bool

use_custom_plots

Whether to use custom plotting routines.

Type:

bool

show_unused_comps_clust: bool = True

els_excluded_clust_plot: List[str]

show_legend_clustering: bool = True

save_plots: bool = True

show_plots: bool = False

use_custom_plots: bool = False