autoemxsp.core.EMXSp_composition_analyser module

EMXSp_Composition_Analyzer

Main class for automated compositional analysis of electron microscopy X-ray spectroscopy (EMXSp) data.

Can be run from Run_Acquisition_Quant_Analysis.py

Features: - Structured configuration for microscope, sample, measurement, and analysis parameters. - Automated acquisition and quantification of X-ray spectra at electron microscope. - Filtering and clustering of compositional data. - Phase identification, mixture analysis, and comprehensive results export. - Utilities for plotting, saving, and reporting analysis results.

Example Usage

# Create analyzer instance >>> analyzer = EMXSp_Composition_Analyzer(

microscope_cfg=microscope_cfg, sample_cfg=sample_cfg, measurement_cfg=measurement_cfg, sample_substrate_cfg=sample_substrate_cfg, quant_cfg=quant_cfg, clustering_cfg=clustering_cfg, powder_meas_cfg=powder_meas_cfg, plot_cfg=plot_cfg, is_acquisition=True, development_mode=False, output_filename_suffix=’’, verbose=True,

)

# Acquire and quantify spectra, and analyse compositions >>> analyzer.run_collection_and_quantification(quantify=True)

# Alternatively, acquire only, then quantify: >>> analyzer.run_collection_and_quantification(quantify=False) >>> quantify and analyse on another machine using Run_Quantification.py

@author: Andrea Created on Mon Jul 22 17:43:35 2024

class autoemxsp.core.EMXSp_composition_analyser.EMXSp_Composition_Analyzer(microscope_cfg: MicroscopeConfig, sample_cfg: SampleConfig, measurement_cfg: MeasurementConfig, sample_substrate_cfg: SampleSubstrateConfig, quant_cfg: QuantConfig = QuantConfig(method='PB', spectrum_lims=(14, 1100), fit_tolerance=0.0001, use_instrument_background=False, interrupt_fits_bad_spectra=True, min_bckgrnd_cnts=5, num_CPU_cores=6), clustering_cfg: ClusteringConfig = ClusteringConfig(method='kmeans', features='at_fr', k=None, k_finding_method='silhouette', max_k=6, ref_formulae=[], max_analytical_error_percent=5, quant_flags_accepted=[0, -1]), powder_meas_cfg: PowderMeasurementConfig = PowderMeasurementConfig(is_manual_particle_selection=False, is_known_powder_mixture_meas=False, par_search_frame_width_um=195.44100476116796, max_n_par_per_frame=30, max_spectra_per_par=3, max_area_par=300.0, min_area_par=10.0, par_mask_margin=1.0, xsp_spots_distance_um=1.0, par_segmentation_model='threshold_bright', par_brightness_thresh=100, par_xy_spots_thresh=100, par_feature_selection='random', par_spot_spacing='random'), bulk_meas_cfg: BulkMeasurementConfig = BulkMeasurementConfig(grid_spot_spacing_um=100.0, min_xsp_spots_distance_um=5.0, image_frame_width_um=1000.0, randomize_frames=False, exclude_sample_margin=False), exp_stds_cfg: ExpStandardsConfig = ExpStandardsConfig(is_exp_std_measurement=False, formula='', use_for_mean_PB_calc=True, min_acceptable_PB_ratio=10, quant_flags_accepted=[0], w_frs=None), plot_cfg: PlotConfig = PlotConfig(show_unused_comps_clust=True, els_excluded_clust_plot=[], show_legend_clustering=True, save_plots=True, show_plots=False, use_custom_plots=False), is_acquisition: bool = False, standards_dict: dict = None, development_mode: bool = False, output_filename_suffix: str = '', verbose: bool = True, results_dir: str | None = None)[source]

Bases: object

Main class for electron microscopy X-ray spectroscopy (EMXSp) composition analysis.

This class orchestrates the acquisition, quantification, clustering, and plotting of X-ray spectra and composition data, using structured configuration objects for all instrument and analysis settings.

Parameters:

  • microscope_cfg (MicroscopeConfig) – Configuration for the microscope hardware.

  • sample_cfg (SampleConfig) – Configuration for the sample.

  • measurement_cfg (MeasurementConfig) – Configuration for the measurement/acquisition.

  • sample_substrate_cfg (SampleSubstrateConfig) – Configuration for the sample substrate.

  • quant_cfg (QuantConfig) – Configuration for spectrum fitting and quantification.

  • clustering_cfg (ClusteringConfig) – Configuration for clustering of spectra/compositions.

  • powder_meas_cfg (PowderMeasurementConfig) – Configuration for powder measurement.

  • bulk_meas_cfg (BulkMeasurementConfig) – Configuration for measurements of bulk or bulk-like samples.

  • exp_stds_cfg (ExpStandardsConfig) – Configuration for measurements of experimental standards.

  • plot_cfg (PlotConfig) – Configuration for plotting.

  • is_acquisition (bool, optional) – If True, indicates class is being used for automated acquisition (default: False).

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

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

  • output_filename_suffix (str, optional) – String to append to saved filenames (default: ‘’).

  • verbose (bool, optional) – If True, enables verbose output (default: True).

  • results_dir (Optional[str], optional) –

    Directory to save results (default: None). If None, uses default directory, created inside package folder

    • Results, for sample analysis

    • Std_measurements, for experimental standard measurements

TO COMPLETE
analyse_data(max_analytical_error_percent, k=None, compute_k_only_once=False)[source]

Analyse quantified spectra, perform clustering, assign candidate phases and mixtures, and save results.

This function orchestrates the workflow:

  1. Selects good compositions for clustering.

  2. Prepares DataFrames for clustering.

  3. Determines the optimal number of clusters (k).

  4. Runs clustering and computes cluster statistics.

  5. Assigns candidate phases and detects mixtures.

  6. Saves results and related plots.

Parameters:

  • max_analytical_error (float or None) – Maximum allowed analytical error for a composition to be considered valid, expressed as w%.

  • k (int, optional) – Number of clusters to use (if not provided, determined automatically).

  • compute_k_only_once (bool, optional) – If True, compute k only once; otherwise, use the most frequent k.

Returns:

  • success (bool) – True if analysis was successful, False otherwise.

  • max_cl_rmsdist (float) – Maximum standard deviation across clusters.

  • min_conf (float or None) – Minimum confidence among assigned candidate phases.

run_collection_and_quantification(quantify: bool = True) → Tuple[bool, bool][source]

Perform iterative collection (and optional quantification) of spectra, followed by phase analysis and convergence check.

This method:

  • Iteratively collects spectra in batches (and quantifies them if quantify is True).

  • After each batch, saves collected data and (if quantification is enabled) performs phase analysis (clustering).

  • Checks for convergence based on clustering statistics and confidence.

  • Stops early if convergence is achieved and minimum spectra is reached, or if no more particles are available.

Parameters:

quantify (bool, optional) – If True (default), spectra are quantified after each batch and clustering is performed. If False, only spectra collection is performed; quantification and clustering are skipped.

Returns:

  • is_analysis_successful (bool) – if quantify == True: True if analysis was successful, False otherwise. if quantify == False: True if collection of target number of spectra was successful, False otherwise.

  • is_converged (bool) – True if phase identification converged to acceptable errors, False otherwise.

Notes

  • During experimental standard collection, “quantify” in fact determines whether spectra are “fitted” in-situ

  • Saves data after each batch to prevent data loss.

  • Prints a summary and processing times at the end.

run_quantification() → None[source]

Perform quantification of all collected spectra and save the results.

This method quantifies the spectra using self._fit_and_quantify_spectra(), then saves the quantification results to file using self._save_collected_data().

Notes

  • The arguments (None, None) to _save_collected_data indicate that all spectra are to be saved.

  • Assumes that spectra have been correctly saved in self.quant_results

run_exp_std_collection(fit_during_collection: bool, update_std_library: bool) → None[source]

Collect, fit, and optionally update the library of experimental standards.

This method automates the acquisition and fitting of spectra from experimental standards, ensuring that all required elemental fractions are defined before proceeding.

Parameters:

  • fit_during_collection (bool) – If True, spectra will be fitted in real-time during collection. If False, fitting must be performed after collection.

  • update_std_library (bool) – If True, the experimental standard library will be updated with the newly fitted PB ratios.

Raises:

  • ValueError – If self.exp_stds_cfg.is_exp_std_measurement is not set to True.

  • KeyError – If any element in self.sample_cfg.elements is missing from self.exp_stds_cfg.w_frs.

print_results(n_cnd_to_print=2, n_mix_to_print=2) → None[source]

Print a summary of clustering results, including clustering configuration, metrics, and a table of identified phases with elemental fractions, standard deviations, and reference/mixture assignments if present.

The method:

  • Prints main clustering configuration and metrics.

  • Prints a table of phases, each with number of points, elemental fractions (with stddev), cluster stddev, WCSS, reference assignments, and mixture information if available.

Parameters:

  • n_cnd_to_print (int) – Max number of candidate phases and relative confidence scores to show. Candidates with scores close to 0 are not shown.

  • n_mix_to_print (int) – Max number of candidate mixtures and relative confidence scores to show. Mixtures with scores close to 0 are not shown.

Raises:

  • AttributeError – If required attributes (clustering_info, clusters_df, etc.) are missing.

  • KeyError – If expected keys are missing from clustering_info or clusters_df.