graintrace.user_data_class#

User-facing dataclasses for similarity metrics, weighting, and rare criteria.

class graintrace.user_data_class.SimilarityMetric(name, feature_cols, func, dist_edges=None)[source]#

Bases: object

A named feature-space distance metric and its required columns.

Variables:

  • name (str) – Label for the metric. Used only in error messages, the progress line, and the graph-stage checkpoint metadata, where resuming compares it against the stored value. It is not a column stem and does not appear in any output frame.

  • feature_cols (List[str]) –

    Column names the metric consumes, in the order its distance function expects them. They must exist in the stage’s input frame.

    The graph stage’s reduction emits one <col>_mean per feature column (plus cluster_id, n, x, y, z, and a <prefix>_norm_mean holding the mean per-point Frobenius norm whenever the feature columns contain a complete <prefix>_11 … <prefix>_33 set). The indicator stage that reads that frame must therefore name the _mean columns, not these – which is why a two-stage Nye-norm run ends up selecting on nye_tensor_norm_mean_mean: the graph stage emits nye_tensor_norm_mean, and the indicator stage’s own reduction suffixes it again.

  • func (Callable[[numpy.ndarray, numpy.ndarray], float]) – Scalar distance between two feature vectors, func(u, v) -> float. Used by the hierarchical indicator stage.

  • dist_edges (Callable[[numpy.ndarray, numpy.ndarray], numpy.ndarray] | None) – Optional vectorized form, dist_edges(X, edges) -> (E,), evaluating one distance per graph edge. When present the graph stage uses it instead of looping func; both must agree numerically.

Parameters:
name: str#
feature_cols: List[str]#
func: Callable[[ndarray, ndarray], float]#
dist_edges: Callable[[ndarray, ndarray], ndarray] | None = None#
class graintrace.user_data_class.WeightConfig(mode='inverse', eps=1e-08, sigma=None, sigma_auto=None, power=2.0)[source]#

Bases: object

Configuration for converting edge distances into graph weights.

A larger weight means “more similar”, so every mode is a decreasing function of the edge distance d.

Variables:

  • mode (str) – Weight kernel, one of "inverse", "rbf", "exp" or "log_inv". Any other value raises ValueError.

  • eps (float) – Regularizer that keeps a zero distance finite. Read by "inverse" (\(1/(d + \varepsilon)\)) and "log_inv" (\(-\log(d + \varepsilon)\)); ignored otherwise.

  • sigma (float | None) – Length scale of "rbf" (\(e^{-(d/\sigma)^{p}}\)) and "exp" (\(e^{-d/\sigma}\)), in the units of the metric – degrees for a misorientation metric, MPa for a stress metric. When None, it is estimated from the edge distances via sigma_auto.

  • sigma_auto (Dict[str, Any] | None) – Estimation spec used only when mode is "rbf" or "exp" and sigma is None. Only the "quantile" key is read; sigma becomes that quantile of the surviving edge distances.

  • power (float) – The exponent \(p\) of "rbf" only; "inverse", "exp" and "log_inv" ignore it.

Parameters:
mode: str = 'inverse'#
eps: float = 1e-08#
sigma: float | None = None#
sigma_auto: Dict[str, Any] | None = None#
power: float = 2.0#
class graintrace.user_data_class.RareCriteria(selector=None, size_quantile=0.05, min_size=1, max_rare=None)[source]#

Bases: object

Select rare merged clusters via selector, or by the size quantile.

selector and the quantile fields are alternatives: when selector is given it decides entirely which clusters are rare, and the three fields below are not consulted.

Variables:

  • selector (Callable[[pandas.DataFrame], numpy.ndarray | List[int] | List[str]] | None) – selector(df) -> ids, taking the merged per-cluster stats frame and returning the ids of the rare clusters. The helpers in graintrace.rare_criteria_selection_library have this shape.

  • size_quantile (float) – Without a selector, clusters in the bottom quantile of cluster size n are rare – the built-in notion of “rare” is small, not extreme. Use a selector to rank by a field value.

  • min_size (int) – Absolute floor on cluster size, applied as well as the quantile, so single-point noise is not reported as a rare event.

  • max_rare (int | None) – Optional cap on how many clusters are returned, smallest first. None means no cap.

Parameters:
selector: Callable[[DataFrame], ndarray | List[int] | List[str]] | None = None#
size_quantile: float = 0.05#
min_size: int = 1#
max_rare: int | None = None#