graintrace.cluster_indicator

Cluster indicators wrapping sklearn/scipy clustering over similarity metrics.

class graintrace.cluster_indicator.ClusterAnalysisIndicator(csv_path, id_col='id', coord_cols=('x', 'y', 'z'))

Bases: object

Run clustering algorithms on field data and summarize per-cluster statistics.

Parameters:

• csv_path (str)

• id_col (str)

• coord_cols (Tuple[str, str, str])

load_data()

Load CSV and populate data, features, coords.

Return type:

None

check_feature_matrix(spec)

Validate that the required feature columns for spec are numeric and finite.

Parameters:

spec (SimilarityMetric)

Return type:

None

run(method_type, spec, minimal_return=False, **kwargs)

Cluster points and return {“points”, “clusters”, “extras”}.

Parameters:

• method_type (str)

• spec (SimilarityMetric)

• minimal_return (bool)

• kwargs (Any)

Return type:

Dict[str, Any]

run_sklearn_dbscan(spec, eps=0.5, min_samples=5, algorithm='auto', leaf_size=30, p=None, n_jobs=None, include_noise_in_summaries=False, noise_label=-1, minimal_return=False)

Cluster with sklearn DBSCAN and return points, cluster summaries, and extras.

Parameters:

• spec (SimilarityMetric)

• eps (float)

• min_samples (int)

• algorithm (str)

• leaf_size (int)

• p (float | None)

• n_jobs (int | None)

• include_noise_in_summaries (bool)

• noise_label (int)

• minimal_return (bool)

Return type:

Tuple[DataFrame | None, DataFrame, Dict[str, Any]]

run_sklearn_agglomerative(spec, n_clusters=2, memory=None, connectivity=None, compute_full_tree='auto', linkage='average', distance_threshold=None, compute_distances=False, minimal_return=False)

Cluster with sklearn AgglomerativeClustering using the metric’s distance func.

Parameters:

• spec (SimilarityMetric)

• n_clusters (int | None)

• memory (Any | None)

• connectivity (Any | None)

• compute_full_tree (Any)

• linkage (str)

• distance_threshold (float | None)

• compute_distances (bool)

• minimal_return (bool)

Return type:

Tuple[DataFrame | None, DataFrame, Dict[str, Any]]

run_sklearn_optics(spec, min_samples=5, max_eps=inf, p=2, metric_params=None, cluster_method='xi', eps=None, xi=0.05, predecessor_correction=True, min_cluster_size=None, algorithm='auto', leaf_size=30, memory=None, n_jobs=None, include_noise_in_summaries=False, noise_label=-1, minimal_return=False)

Cluster with sklearn OPTICS and return points, cluster summaries, and extras.

Parameters:

• spec (SimilarityMetric)

• min_samples (Any)

• max_eps (float)

• p (float)

• metric_params (Dict[str, Any] | None)

• cluster_method (str)

• eps (float | None)

• xi (float)

• predecessor_correction (bool)

• min_cluster_size (int | None)

• algorithm (str)

• leaf_size (int)

• memory (Any | None)

• n_jobs (int | None)

• include_noise_in_summaries (bool)

• noise_label (int)

• minimal_return (bool)

Return type:

Tuple[DataFrame | None, DataFrame, Dict[str, Any]]

plot_dendrogram(Z, threshold, save_path=None, ax=None, no_labels=True)

Plot a hierarchical-clustering dendrogram with a cut threshold; return leaf info.

Parameters:

• Z (ndarray)

• threshold (float)

• save_path (str | None)

• no_labels (bool)

Return type:

Dict[str, Any]

run_scipy_hierarchical(spec, method='average', criterion='distance', threshold=1.0, depth=10, dendrogram_path=None, minimal_return=False)

Cluster with scipy hierarchical linkage and return points, summaries, and extras.

Parameters:

• spec (SimilarityMetric)

• method (str)

• criterion (str)

• threshold (float)

• depth (int)

• dendrogram_path (str | None)

• minimal_return (bool)

Return type:

Tuple[DataFrame | None, DataFrame, Dict[str, Any]]