autoemx.runners.batch_quantify_and_analyze module

Batch quantification and analysis of X-ray spectra for a list of samples.

This module provides automated batch quantification and (optionally) clustering/statistical analysis of acquired X-ray spectra for multiple samples. It is robust to missing files or errors in individual samples, making it suitable for unattended batch processing.

Import this module in your own code and call the batch_quantify_and_analyze() function, passing your desired sample IDs and options as arguments. This enables integration into larger workflows or pipelines.

Workflow

  • Loads sample configurations and spectral data from ledger.json. Results saved in the legacy Data.csv format are converted to a ledger.json automatically.

  • Performs quantification and optionally clustering/statistical analysis and saves results.

Notes

  • Only the sample_ID is required if acquisition output is saved in the default directory; otherwise, specify results_path.

  • Designed to continue processing even if some samples are missing or have errors.

Typical usage:

  • Edit the sample_IDs list and parameter options in the script, or

  • Import and call batch_quantify_and_analyze() with your own arguments.

returns:

  • quant_results (list()) – List of EMXSp_Composition_Analyzer, the composition analysis object containing the results and methods for further analysis.

  • Created on Tue Jul 29 13 (18:16 2025)

  • @author (Andrea)

autoemx.runners.batch_quantify_and_analyze.batch_quantify_and_analyze(sample_IDs: List[str], els_sample: List[str] | None = None, quantification_method: str | None = None, results_path: str | None = None, min_bckgrnd_cnts: float | None = None, min_total_counts_fraction: float | None = None, identify_missing_elements: bool | None = None, output_filename_suffix: str = '', use_instrument_background: bool = False, max_analytical_error: float = 5.0, run_analysis: bool = True, num_CPU_cores: int | None = None, force_requantification: bool = False, interrupt_fits_bad_spectra: bool = False, use_project_specific_std_dict: bool | None = None, is_known_phase_mixture: bool | None = None, intermixing_violin_plots: bool | None = None, standards_dict: dict | None = None, spectrum_lims: tuple | None = None, els_substrate: List[str] | None = None, fit_tolerance: float | None = None, requantify_only_unquantified_spectra: bool = False, max_spectra_to_quantify: int | None = None, is_known_precursor_mixture: bool | None = None) → List[EMXSp_Composition_Analyzer][source]

Batch quantification and analysis for a list of samples.

Parameters:

  • sample_IDs (List[str]) – List of sample identifiers.

  • els_sample (list(str), optional) – List of elements in the sample. If the first entry is “” or None, the rest of the list is appended to the list loaded from the ledger; otherwise, the provided list replaces it.

  • els_substrate (list(str), optional) – List of substrate elements. If None, uses the substrate elements from the active quantification configuration in each ledger. If the first entry is “” or None, the remaining entries are appended; otherwise, the provided list replaces the ledger value.

  • quantification_method (str, optional) – Method to use for quantification. Uses quant_cfg.method if unspecified. Currently only supports ‘PB’.

  • spectrum_lims (tuple, optional) – Lower and upper channel-index limits for spectrum fitting. If None, uses spectrum_lims from the active quantification configuration in each ledger.

  • results_path (str, optional) – Base directory where results are stored. Default: autoemx/Results

  • min_bckgrnd_cnts (float, optional) – Minimum background counts under the reference peaks: spectra below are flagged (quant_flag 8) (ClusteringConfig.min_bckgrnd_cnts). Changing it needs no re-quantification. If None, keeps the value of the sample’s active analysis. Default: None

  • min_total_counts_fraction (float, optional) – Minimum accepted total spectrum counts as a fraction of target_acquisition_counts. Spectra below this threshold are flagged quant_flag = 2 (“Total counts too low”). If None, uses the value already on the quantification config (default 0.9). Lower this to quantify shorter acquisitions; 0 disables the check.

  • identify_missing_elements (bool, optional) – If True, each spectrum is checked for elements missing from its fit before quantification (e.g. contaminants, or elements of an unknown material), and a report of the elements found is printed for each sample and for the batch. If None, uses the value of the quantification config (default True; off for quantification runs saved before this option existed).

  • output_filename_suffix (str, optional) – Suffix to append to output filenames.

  • use_instrument_background (bool, optional) – Whether to use instrument background if present (Default: False).

  • max_analytical_error (float, optional) – Maximum allowed analytical error for analysis.

  • run_analysis (bool, optional) – Whether to run clustering/statistical analysis after quantification.

  • num_CPU_cores (bool | None, optional) – Number of CPU cores to use during fitting and quantification. If None, half of the available cores are used.

  • force_requantification (bool, optional) – If True, re-quantifies all spectra regardless of whether an existing quantification run with matching settings is already available.

  • interrupt_fits_bad_spectra (bool, optional) –

    Controls early-exit behaviour during iterative spectral fitting.

    If True (default), the fit is aborted as soon as any of the following conditions is detected mid-iteration:

    • Reduced chi-squared exceeds 20 % of total spectrum counts (poor fit, flag 4).

    • Analytical error exceeds 50 w% (flag 5).

    • Excessive X-ray absorption around reference peaks (flag 6).

    • Total counts below min_total_counts_fraction of target (flag 2; default 90%).

    • Low-energy background counts below threshold (flag 3).

    The aborted spectrum is stored with QuantificationDiagnostics.interrupted=True and no composition is saved. This speeds up batch quantification significantly when many spectra are expected to be unreliable.

    If False, early-exit is disabled for the current run. Any spectrum whose previous record has interrupted=True (from a prior run with interrupt_fits_bad_spectra=True) is re-quantified, and its ledger record is overwritten with the new result.

  • use_project_specific_std_dict (bool, optional) – If True, loads standards from project folder (i.e. results_dir) during quantification. Default: None. Loads it from quant_cfg file

  • is_known_phase_mixture (bool, optional) –

    Whether the sample is a mixture of known phases (the candidate phases). If True, spectra are quantified with the reference P/B values of these phases, and the analysis characterizes their intermixing. Default: None, keeps the value of the sample’s active quantification run. See example at:

    L. N. Walters et al., Synthetic Accessibility and Sodium Ion Conductivity of the Na 8– x A x P 2 O 9 (NAP) High-Temperature Sodium Superionic Conductor Framework, Chem. Mater. 37, 6807 (2025).

  • intermixing_violin_plots (bool, optional) – Whether to plot the intermixing of the reported mixtures as violin plots (PlotConfig.intermixing_violin_plots). Default: None, keeps the saved setting (by default, plotted for known phase mixtures).

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

  • fit_tolerance (float, optional) – Tolerance for fit convergence. If None, uses fit_tolerance from the active quantification configuration in each ledger (default 1e-4).

  • requantify_only_unquantified_spectra (bool, optional) – Reuse the latest matching quantification run, but re-quantify only spectra without a composition result (never quantified, or previously skipped/flagged). Default: False.

  • max_spectra_to_quantify (int, optional) – Quantify at most this number of spectra per sample, among those that need quantification (in acquisition order), e.g. for quick tests. None (default) quantifies all of them.

  • is_known_precursor_mixture (bool, optional) – Deprecated, use is_known_phase_mixture.

Returns:

quant_results – List of EMXSp_Composition_Analyzer, the composition analysis object containing the results and methods for further analysis.

Return type:

list()