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 (primary source).

  • Falls back to Data.csv only when no ledger exists; the first quantification run then migrates the CSV data into a ledger.json for all subsequent runs.

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

  • When a ledger.json is present it is always used as the authoritative source of spectral data and quantification results; Data.csv is only read as a one-time migration path when no ledger has been created yet.

  • spectra_quant (the in-memory composition buffer consumed by analyse_data) is always populated by run_quantification from ledger records — the runner never needs to pre-build it.

  • 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, output_filename_suffix: str = '', use_instrument_background: bool = False, max_analytical_error: float = 5, 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_precursor_mixture: bool | None = None, standards_dict: dict | None = None, spectrum_lims: tuple | None = None, els_substrate: List[str] | 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 number of background counts underneath reference peaks below which spectra are flagged. If None, leaves it unchanged. Default: None

  • 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 90 % of target (flag 2).

    • 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_precursor_mixture (bool, optional) –

    Whether sample is a mixture of two known powders. Used to characterize extent of intermixing in powders. 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).

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

Returns:

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

Return type:

list()