Clustering modes

AutoEMX groups the measured compositions into clusters, ideally one per phase. Two settings control this:

  • method: the clustering algorithm, 'kmeans' (default) or 'dbscan'.

  • geometry: how the distance between two compositions is measured: 'euclidean', 'aitchison', or 'auto' (chosen from the data; default for new samples).

Together, these two settings decide which spectra are grouped together. They do not change how a cluster’s composition is reported: it is always the average of the element fractions of its spectra (even in Aitchison geometry, no log-ratio averaging is used). Results from different settings can therefore be compared directly.

Defaults: change them only if unsatisfied with the results

By default AutoEMX uses k-means with automatic geometry selection (geometry='auto') and chooses the number of clusters automatically (see Number of clusters). They work well in most cases.

Change them only if the results are unsatisfactory, e.g. if the clusters do not match the groups of compositions visible in the clustering plot. The rest of this page explains what each option does, to help you decide what to try.

Clustering algorithms

k-means assigns every composition to one of k clusters. k is either forced (k_forced) or found automatically: AutoEMX first checks whether the sample looks single-phase, and otherwise picks the best k up to max_k (by silhouette score by default), preferring fewer clusters when several values are equally good. See Number of clusters for details.

DBSCAN finds dense groups of compositions and labels isolated ones as noise. The number of clusters follows from the data, so k_forced is ignored. Main parameters:

  • eps: how close two compositions must be to count as neighbors. If left unset, it defaults to 0.05 in Euclidean geometry and 0.3 in Aitchison geometry, since distances have very different scales in the two.

  • min_samples: minimum number of neighbors to form a cluster (default 3).

Use k-means in most cases. Try DBSCAN to pick out a few compact phases from scattered compositions.

Geometries

Euclidean

Distances are computed directly on the element fractions: a 1 at% difference counts the same everywhere. It is simple and robust, but:

  • minor elements barely matter: 1 at% vs 3 at% of an element is a small difference, even though it is a factor of 3;

  • spectra with the same element ratios but a different oxygen content (e.g. from quantification scatter) are pulled apart.

Aitchison

Distances are computed on the log-ratios between elements (centered log-ratio transform). Only ratios matter:

  • 1 → 3 at% weighs as much as 10 → 30 at%;

  • spectra with the same element ratios are identical, regardless of dilution or normalization (atomic and weight fractions give the same clusters).

This usually separates phases better when they share the same elements in different ratios. Its weakness is that logarithms magnify small values, so near-zero measurements (mostly noise in EDS) can dominate. The next section explains how AutoEMX limits this.

Zeros and trace elements (Aitchison)

The logarithm of zero is undefined, and the logarithm of a tiny, noisy value is large and unstable. Before computing log-ratios, AutoEMX adjusts low values using a detection limit, detection_limit_percent (default 0.5%):

  1. Elements that are zero in every spectrum (e.g. undetectable Li) are ignored.

  2. Each element is classified from its median across the spectra: trace if below 1% (2 x the detection limit), major otherwise.

  3. Low values are replaced with 0.325% (0.65 x the detection limit):

    Element

    Exact zeros

    Below 0.5%

    Above 0.5%

    Trace

    replaced

    replaced

    kept

    Major

    replaced

    kept

    kept

Why:

  • Trace values are floored because they are mostly noise. Without this, an impurity at 0.3 at% in some spectra and 0 in others would look like two different phases.

  • Low values of major elements are kept because they are usually real, e.g. the element-poor end of a mixture.

  • Zeros are always replaced because a measured zero means “below detection”, not “absent”.

  • The median is used, not the mean, because it reflects a typical spectrum. An element present at 20 at% in only 10% of the spectra has a mean of about 2% but a median of about 0. It is correctly treated as trace, and its 20 at% values are untouched by the floor.

How 'auto' chooses

With geometry='auto', AutoEMX uses Euclidean geometry if either of these holds for the compositions being clustered, and Aitchison otherwise:

  1. At most two elements are present. Log-ratios then reduce to a single number, which tends to split a single phase into many clusters.

  2. In at least 10% of spectra, a major element is below 1%. This happens when phases have largely different elements, or along a mixture line that reaches an end-member. Log-ratios would magnify the noise in those near-zero values.

The choice is logged, for example:

ℹ️ Automatic geometry selection: euclidean (a major element is < 1% in 61% of spectra (threshold 10%)).

The thresholds (auto_near_zero_percent = 1.0, auto_max_near_zero_fraction = 0.10) can be changed in aitchison_params. If the choice looks wrong for a sample, set geometry explicitly.

Defaults. New samples use 'auto'. Samples analyzed before this option existed, and samples created from legacy data, use 'euclidean', so re-analysing them reproduces earlier results.

Examples

In autoemx/scripts/Run_Analysis.py (options left as None keep the values saved for the sample):

# Let AutoEMX choose the geometry (default for new samples)
clustering_geometry = 'auto'

# Force Aitchison geometry, flooring noisy trace elements more aggressively
clustering_geometry = 'aitchison'
aitchison_params = {'detection_limit_percent': 1.0}

# DBSCAN, with eps defaulting to the chosen geometry
clustering_method = 'dbscan'
dbscan_params = {'min_samples': 5}

The same options are available in analyze_sample (clustering_method, clustering_geometry, dbscan_params, aitchison_params).

Which setting to use

Start with the defaults. If you are not satisfied with the result:

Situation

Suggested setting

Default, first try

'auto'

Phases with the same elements in different ratios

'aitchison'

Phases with largely different elements, or 2-element samples

'euclidean'

Noisy trace elements splitting clusters (Aitchison)

raise detection_limit_percent

Comparing with older results

'euclidean'

Always check the clustering plot: clusters should match visible groups of compositions, with centroids near candidate phases or on the lines between them (mixtures).