autoemx.runners.analyze_sample module
Single-sample clustering and analysis of X-ray spectra.
This module loads configurations and acquired X-ray spectra for a single sample, performs clustering/statistical analysis, and prints results. It is suitable for both interactive use and integration into larger workflows.
Import this module in your own code and call the analyze_sample() function, passing the sample ID (and optional arguments) to perform analysis programmatically.
- Workflow:
Loads sample configuration and spectral data from
ledger.json(primary source)Falls back to
Data.csvonly when no ledger exists (one-time migration)Performs clustering/statistical analysis
Prints summary results
Notes
Requires sample_ID (and optionally results_path if not using the default directory).
Designed to be robust and flexible for both batch and single-sample workflows.
- Typical usage:
Edit the sample_ID and options in the script, or
Import and call analyze_sample() with your own arguments.
Created on Tue Jul 29 13:18:16 2025
@author: Andrea
- autoemx.runners.analyze_sample.analyze_sample(sample_ID: str, results_path: str | None = None, output_filename_suffix: str = '', ref_formulae: List[str] | None = None, els_excluded_clust_plot: List[str] | None = None, clustering_features: str | None = None, clustering_method: str | None = None, dbscan_params: dict | None = None, k_finding_method: str | None = None, k_forced: int | bool | None = None, do_matrix_decomposition: bool = True, max_analytical_error_percent: float = 5, quant_flags_accepted: List[int] | None = None, show_plots: bool = True, plot_custom_plots: bool = False, show_unused_compositions_cluster_plot: bool = True) EMXSp_Composition_Analyzer | None[source]
Run clustering and analysis for a single sample.
- sample_IDstr
Sample identifier.
- results_pathstr, optional
Directory where results are loaded and stored. If None, defaults to autoemx/Results
- output_filename_suffixstr, optional
Suffix for output files.
- ref_formulaelist of str, optional
Reference formulae for clustering. If the first entry is “” or None, the rest are appended to the list loaded from Comp_analysis_configs.json; otherwise, the provided list replaces it.
- els_excluded_clust_plotlist of str, optional
Elements to exclude from cluster plot.
- clustering_featureslist of str, optional
Features to use for clustering.
- clustering_methodstr, optional
Clustering algorithm to use. One of
"kmeans"or"dbscan". If None, the value stored in the sample’s clustering config is kept.- dbscan_paramsdict, optional
Overrides for DBSCAN parameters (only used when
clustering_method="dbscan"). Recognized keys:eps(float),min_samples(int),metric(str). Unspecified keys keep their existing/default values.- k_finding_methodstr, optional
- Method for determining optimal number of clusters. Set to “forced” if a value of ‘k’ is specified manually.
Allowed methods are “silhouette”, “calinski_harabasz”, “elbow”.
- k_forcedint or bool, optional
- Controls the number of clusters:
int: force clustering to use exactly this number of clusters.False: force recomputation of the optimal number of clusters, discarding any previously saved forced k. Usesk_finding_methodwhen provided, otherwise the saved (or default) finding method.None(default): reuse the clustering settings saved in the ledger.
- do_matrix_decompositionbool, optional
Whether to compute matrix decomposition for intermixed phases. Slow if many candidate phases are provided. Default: True..
- max_analytical_error_percentfloat, optional
Maximum analytical error allowed for clustering.
- quant_flags_acceptedlist of int, optional
Accepted quantification flags.
- plot_custom_plotsbool, optional
Whether to use custom plots.
- show_unused_compositions_cluster_plotbool, optional
Whether to show unused compositions in cluster plot.
- returns:
comp_analyzer – The composition analysis object containing the results and methods for further analysis.
- rtype:
EMXSp_Composition_Analyzer