graintrace.rare_cluster_indicator#

Identify and export spatially coherent rare clusters from CPFE field data.

class graintrace.rare_cluster_indicator.IdentifyRareClusters(input_csv_path, id_col='id', coord_cols=('x', 'y', 'z'))[source]#

Bases: object

Graph cluster -> merge via indicator -> select rare clusters and export VTK.

Parameters:
run_clustering(gsc, indicator, *, gsc_run_kwargs, indicator_run_kwargs, reduced_csv_path)[source]#

Run graph spatial clustering then the hierarchical merge indicator.

Stage 1 runs the GraphSpatialCluster to produce per-point labels and a reduced per-cluster CSV; stage 2 runs the ClusterAnalysisIndicator to merge those clusters. Saves the stage-1 labels alongside reduced_csv_path as <base>_gsc_labels.npy.

Parameters:

  • gsc – A configured GraphSpatialCluster stage object (from make_stage_objects).

  • indicator – A configured ClusterAnalysisIndicator stage object (from make_stage_objects).

  • gsc_run_kwargs (Dict[str, Any]) – Keyword arguments for gsc.run (e.g. spec, graph_mode, manhattan_radius, n_jobs, segmenter, seed, weight_cfg, networkit_kwargs, checkpoint options).

  • indicator_run_kwargs (Dict[str, Any]) – Keyword arguments for indicator.run (e.g. method_type, spec, threshold, method, criterion, dendrogram_path).

  • reduced_csv_path (str) – Path for the reduced per-cluster CSV written by the graph stage; the labels .npy is derived from it.

Returns:

input_df, gsc_labels, reduced_csv_path, gsc_extras, indicator_points_df, indicator_clusters_df, indicator_extras. Pass it to run_get_rare_cluster.

Return type:

A result bundle dict with keys

run_get_rare_cluster(bundle, *, criteria, output_vtk_path, export_control='auto', background_block_id=1, first_rare_block_id=2, also_write_final_label=True, rare_reduced_stats_csv_path=None, rare_points_csv_path=None, use_sample_std=False)[source]#

Select rare clusters from a bundle and export them to VTK (and optional CSVs).

Maps stage-1 labels to the merged super-labels, applies the rarity criteria to pick rare clusters, assigns block ids (background then one per rare cluster), and writes the result as a STRUCTURED_GRID or POLYDATA VTK depending on export_control.

Parameters:

  • bundle (Dict[str, Any]) – The result dict returned by run_clustering.

  • criteria (RareCriteria) – A RareCriteria selecting which clusters count as rare (custom selector, or default size-quantile selection using its min_size / size_quantile / max_rare fields).

  • output_vtk_path (str) – Path for the exported VTK file.

  • export_control (str) – “auto” (grid if the points form a full regular grid, else points), “grid”, or “points”. Default “auto”.

  • background_block_id (int) – Block id assigned to non-rare (background) points. Default 1.

  • first_rare_block_id (int) – Block id assigned to the first rare cluster; subsequent rare clusters increment from here. Default 2.

  • also_write_final_label (bool) – If True, also write the per-point merged “final_label” array into the VTK. Default True.

  • rare_reduced_stats_csv_path (str | None) – Optional path to write a per-rare-cluster statistics CSV (mean/var/std per feature, plus min/max when available). Default None.

  • rare_points_csv_path (str | None) – Optional path to write an (x, y, z, rare_cluster_id) point cloud of the rare points (input to REIComparison). Default None.

  • use_sample_std (bool) – Accepted for API compatibility; currently unused. Default False.

Returns:

output_vtk_path, export_mode, n_points, n_rare_clusters, rare_super_labels, label_to_block, rare_reduced_stats_csv_path, rare_points_csv_path.

Return type:

Dict with keys

make_stage_objects(*, graph_cluster_out)[source]#

Construct the GraphSpatialCluster and ClusterAnalysisIndicator stage objects.

Parameters:

graph_cluster_out (str) – Path to the reduced per-cluster CSV that the graph stage writes and the indicator stage reads (its “cluster_id” column keys the merge).

Returns:

A (GraphSpatialCluster, ClusterAnalysisIndicator) tuple ready to pass to run_clustering.

Return type:

Tuple[GraphSpatialCluster, ClusterAnalysisIndicator]