autoemx.runners.quantify_external_spectra module

Import and quantify externally-acquired X-ray spectra.

This module copies .msa / .msg / .emsa spectrum files from an arbitrary directory into the canonical sample_id/spectra/ subfolder under results_path, builds a complete ledger.json (identical to what the acquisition runner writes), and then hands off to batch_quantify_and_analyze() for quantification and optional clustering analysis.

Typical workflow

  1. Run quantify_external_spectra.py → copies spectra, writes ledger.json, runs quantification, and (optionally) clustering analysis.

  2. Re-run run_analysis.py at any time to repeat clustering with different parameters.

Created on Fri Apr 24 2026

@author: Andrea

autoemx.runners.quantify_external_spectra.read_energy_calibration(files: List[Path]) → Tuple[float, float][source]

Energy calibration (offset, width) in keV (energy of channel 0 and channel width), from the #OFFSET and #XPERCHAN lines of the EMSA headers of files, read as in the web app (load_msa + parse_emsa_geometry).

Raises ValueError if the files have no calibration or different ones.

autoemx.runners.quantify_external_spectra.quantify_external_spectra(samples: List[Dict[str, Any]], microscope_ID: str = 'PhenomXL', microscope_type: str = 'SEM', measurement_type: str = 'EDS', measurement_mode: str = 'point', beam_energy: float = 15.0, els_substrate: List[str] | None = None, sample_substrate_type: str = 'Ctape', sample_substrate_shape: str = 'circle', sample_substrate_width_mm: float = 12, sample_type: str = 'bulk', sample_halfwidth: float = 2.9, quantification_method: str = 'PB', use_project_specific_std_dict: bool = False, use_instrument_background: bool = False, 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, interrupt_fits_bad_spectra: bool = False, num_CPU_cores: int | None = None, run_analysis: bool = True, powder_meas_cfg_kwargs: Dict[str, Any] | None = None, bulk_meas_cfg_kwargs: Dict[str, Any] | None = None, results_path: str | None = None, overwrite_existing: bool = False, standards_dict: dict | None = None, verbose: bool = True, quantify: bool = True) → List[EMXSp_Composition_Analyzer][source]

Copy externally-acquired spectra into the AutoEMX sample folder layout, build a complete ledger.json, then run quantification and (optionally) clustering analysis via batch_quantify_and_analyze().

Parameters:

  • samples (list of dict) –

    Each entry describes one sample. Recognised keys:

    • 'ID' (str, required): Sample identifier; the output folder is named after this.

    • 'els' (list of str, required): Element symbols expected in the sample.

    • 'spectra_dir' (str, optional): Path to a folder containing .msa / .msg / .emsa spectrum files. Files are copied and renamed spectrum_0<ext>, spectrum_1<ext>, … in sort order. When omitted (or set to None), the spectra are expected to already be present at <results_path>/<ID>/spectra/ in the canonical naming.

    • 'cnd' (list of str, optional): Candidate phase formulae for clustering (e.g. ['PbMoO4']).

    • 'type' (str, optional): Override sample_type for this entry.

    • 'half_width_mm' (float, optional): Override sample_halfwidth.

  • microscope_ID (str) – Identifier of the microscope calibration folder. Default: 'PhenomXL'.

  • microscope_type (str) – Microscope type ('SEM').

  • measurement_type (str) – Measurement type ('EDS').

  • measurement_mode (str) – Measurement mode ('point'); selects the detector-channel calibration.

  • beam_energy (float) – Electron beam energy in keV. Must match the energy used during acquisition.

  • els_substrate (list of str, optional) – Elements in the sample substrate. Default: ['C'] (defaults.substrate_els).

  • sample_substrate_type (str) – Substrate material type ('Ctape' or 'None').

  • sample_substrate_shape (str) – Stub shape ('circle' or 'square').

  • sample_substrate_width_mm (float) – Stub lateral dimension in mm.

  • sample_type (str) – Sample geometry for quantification corrections ('powder', 'bulk', 'bulk_rough', 'powder_continuous').

  • sample_halfwidth (float) – Half-width of the sample area in mm.

  • quantification_method (str) – Quantification algorithm. Only 'PB' is currently implemented.

  • use_project_specific_std_dict (bool) – Load standards from the project folder rather than global calibrations.

  • use_instrument_background (bool) – Use instrument background during fitting when available.

  • max_analytical_error_percent (float) – Compositions above this analytical-error threshold (w%) are excluded from clustering.

  • min_bckgrnd_cnts (int) – Minimum background counts under the reference peak for a spectrum to be accepted for quantification.

  • quant_flags_accepted (list of int, optional) – Quantification flags included during clustering. Default: [0, -1]. See the user documentation page “Quantification flags (quant_flag)”.

  • max_n_clusters (int) – Maximum number of clusters.

  • show_unused_comps_clust (bool) – Show discarded compositions in the clustering plot.

  • interrupt_fits_bad_spectra (bool) – Abort fits early when quality indicators are poor (speeds up batch runs).

  • num_CPU_cores (int, optional) – Parallel fitting cores. None uses half the available cores.

  • run_analysis (bool) – Run clustering / statistical analysis after quantification.

  • powder_meas_cfg_kwargs (dict, optional) – Extra kwargs forwarded to PowderMeasurementConfig.

  • bulk_meas_cfg_kwargs (dict, optional) – Extra kwargs forwarded to BulkMeasurementConfig.

  • results_path (str, optional) – Root directory for sample sub-folders. Defaults to <cwd>/Results.

  • overwrite_existing (bool) – Re-copy external spectra files into sample_id/spectra even when ledger.json already exists. The existing ledger is never deleted; quantification history is preserved.

  • standards_dict (dict, optional) – Custom dictionary of reference PB values; None loads the defaults.

  • verbose (bool) – Print progress information.

  • quantify (bool) – If False, only copies the spectra and builds the ledgers (no quantification nor analysis); the samples can then be quantified with batch_quantify_and_analyze(). Default: True.

Returns:

One analyzer per successfully quantified sample: from analyze_sample() if analysed, otherwise from batch_quantify_and_analyze().

Return type:

list of EMXSp_Composition_Analyzer