cratepy.clustering.crve.HAACRMP

class HAACRMP(mat_phase, cluster_data_matrix, n_clusters, adaptivity_type)[source]

Bases: ACRMP

Hierarchical Agglomerative Adaptive Cluster-Reduced Material Phase.

_clustering_type

Type of cluster-reduced material phase.

Type:

str

_linkage_matrix

Linkage matrix associated with the hierarchical agglomerative clustering (numpy.ndarray of shape (n_phase_voxels - 1, 4)).

Type:

numpy.ndarray (2d)

_cluster_node_map

Tree node id (item, int) associated with each cluster label (key, str).

Type:

dict

_adaptive_step

Counter of adaptive clustering steps, with 0 associated with the base clustering.

Type:

int

_adapt_split_factor

Adaptive clustering split factor. The adaptive clustering split factor must be contained between 0 and 1 (included). The lower bound (0) enforces a single split, i.e., 2 new clusters, while the upper bound (1) is associated with a maximum defined number of new voxels.

Type:

float

_threshold_n_clusters

Threshold number of adaptive material phase number of clusters. Once this threshold is surpassed, the adaptive procedures of the adaptive material phase are deactivated.

Type:

int

_is_dynamic_split_factor

True if adaptive clustering split factor is to be computed dynamically. Otherwise, the adaptive clustering split factor is always set equal to _adapt_split_factor.

Type:

bool

max_label

Clustering maximum label.

Type:

int

cluster_labels

Material phase cluster labels (numpy.ndarray[int] of shape (n_phase_voxels,)).

Type:

numpy.ndarray (1d)

adaptive_time

Total amount of time (s) spent in the adaptive procedures.

Type:

float

adaptivity_lock

True if the adaptive procedures are deactivated, False otherwise.

Type:

bool

perform_base_clustering(self, base_clustering_scheme, min_label=0)[source]

Perform HAACRMP base clustering.

perform_adaptive_clustering(self, target_clusters, target_clusters_data, adaptive_clustering_scheme=None, min_label=0)[source]

Perform HAACRMP adaptive clustering step.

add_to_tree_node_list(node_list, node)[source]

Add node to tree node list and sort by descending linkage distance.

_check_adaptivity_lock(self)[source]

Check ACRMP adaptivity locking conditions.

print_adaptive_clustering(self, adaptive_clustering_map, adaptive_tree_node_map)[source]
get_valid_clust_algs()[source]

Get valid clustering algorithms to compute the CRMP.

get_n_clusters(self)[source]

Get current number of clusters.

get_clustering_type(self)[source]

Get cluster-reduced material phase adaptivity type.

get_adaptivity_type_parameters()[source]

Get ACRMP mandatory and optional adaptivity type parameters.

_set_adaptivity_type_parameters(self, adaptivity_type)[source]

Set clustering adaptivity parameters.

get_adaptive_output(self)[source]

Get adaptivity metrics for clustering adaptivity output.

Constructor.

Parameters:
  • mat_phase (str) – Material phase label.

  • cluster_data_matrix (numpy.ndarray (2d)) – Data matrix (numpy.ndarray of shape (n_phase_voxels, n_features_dims)) containing the clustering features data to perform the material phase cluster analyses.

  • n_clusters (int) – Number of material phase clusters.

  • adaptivity_type (dict) – Clustering adaptivity parameters.

List of Public Methods

add_to_tree_node_list

Add node to tree node list and sort by descending linkage distance.

get_adaptive_output

Get adaptivity metrics for clustering adaptivity output.

get_adaptivity_type_parameters

Get ACRMP mandatory and optional adaptivity type parameters.

get_clustering_type

Get cluster-reduced material phase adaptivity type.

get_n_clusters

Get current number of clusters.

get_valid_clust_algs

Get valid clustering algorithms to compute the CRMP.

perform_adaptive_clustering

Perform HAACRMP adaptive clustering step.

perform_base_clustering

Perform HAACRMP base clustering.

print_adaptive_clustering

Print hierarchical adaptive clustering report (validation).

Methods

__init__(mat_phase, cluster_data_matrix, n_clusters, adaptivity_type)[source]

Constructor.

Parameters:
  • mat_phase (str) – Material phase label.

  • cluster_data_matrix (numpy.ndarray (2d)) – Data matrix (numpy.ndarray of shape (n_phase_voxels, n_features_dims)) containing the clustering features data to perform the material phase cluster analyses.

  • n_clusters (int) – Number of material phase clusters.

  • adaptivity_type (dict) – Clustering adaptivity parameters.

_check_adaptivity_lock()[source]

Check ACRMP adaptivity locking conditions.

Check conditions that may deactivate the adaptive procedures in the ACRMP. Once the ACRMP adaptivity is locked, it is treated as a SCRMP for the remainder of the problem numerical solution.

static _dynamic_split_factor(ref_split_factor, adapt_trigger_ratio, magnitude, dynamic_amp=0)

Compute dynamic adaptive clustering split factor.

A detailed description of the dynamic adaptive clustering split factor can be found in Ferreira et. al (2022) [1].


Parameters:
  • ref_split_factor (float) – Reference (centered) adaptive clustering split factor. The adaptive clustering split factor must be contained between 0 and 1 (included). The lower bound (0) enforces a single split, while the upper bound (1) performs the maximum number splits of each cluster (leading to single-voxel clusters).

  • adapt_trigger_ratio (float) – Threshold associated with the adaptivity trigger condition.

  • magnitude (float) – Difference between cluster ratio and adaptive trigger ratio. Given that the cluster ratio ranges between 0 and 1 and only clusters with a ratio greater or equal than the adaptive trigger ratio are targeted, the magnitude ranges between 0 and 1 - trigger ratio.

  • dynamic_amp (float, default=0) – Dynamic split factor amplitude centered around the reference adaptive clustering split factor.

Returns:

adapt_split_factor – Adaptive clustering split factor. The adaptive clustering split factor must be contained between 0 and 1 (included). The lower bound (0) enforces a single split, i.e., 2 new clusters, while the upper bound (1) is associated with a maximum defined number of new voxels.

Return type:

float

_set_adaptivity_type_parameters(adaptivity_type)[source]

Set clustering adaptivity parameters.

Parameters:

adaptivity_type (dict) – Clustering adaptivity parameters.

static _update_cluster_labels(labels, min_label=0)

Update cluster labels starting with the provided minimum label.

Parameters:
  • labels (numpy.ndarray (1d)) – Cluster labels (numpy.ndarray[int] of shape (n_items,)).

  • min_label (int, default=0) – Minimum cluster label.

Returns:

  • new_labels (numpy.ndarray (1d)) – Updated cluster labels (numpy.ndarray[int] of shape (n_items,)).

  • max_label (int) – Maximum cluster label.

static add_to_tree_node_list(node_list, node)[source]

Add node to tree node list and sort by descending linkage distance.

Parameters:
  • node_list (list[ClusterNode]) – List of ClusterNode instances.

  • node (ClusterNode) – ClusterNode to be added to list[ClusterNode].

get_adaptive_output()[source]

Get adaptivity metrics for clustering adaptivity output.

Returns:

adaptivity_output – List containing the adaptivity metrics associated with the clustering adaptivity output file.

Return type:

list

static get_adaptivity_type_parameters()[source]

Get ACRMP mandatory and optional adaptivity type parameters.

Besides returning the ACRMP mandatory and optional adaptivity type parameters, this method establishes the default values for the optional parameters.


Returns:

  • mandatory_parameters (dict) – Mandatory adaptivity type parameters (str) and associated type (item, type).

  • optional_parameters (dict) – Optional adaptivity type parameters (key, str) and associated default value (item).

get_clustering_type()[source]

Get cluster-reduced material phase adaptivity type.

Returns:

clustering_type – Type of cluster-reduced material phase.

Return type:

str

get_n_clusters()[source]

Get current number of clusters.

Returns:

n_clusters – Number of material phase clusters.

Return type:

int

static get_valid_clust_algs()[source]

Get valid clustering algorithms to compute the CRMP.

Returns:

clust_algs – Clustering algorithms identifiers (str).

Return type:

list[str]

perform_adaptive_clustering(target_clusters, target_clusters_data, adaptive_clustering_scheme=None, min_label=0)[source]

Perform HAACRMP adaptive clustering step.

Refine the provided target clusters by splitting them according to the hierarchical agglomerative tree, prioritizing child nodes by descending order of linkage distance.


Parameters:
  • target_clusters (list[int]) – List with the labels (int) of clusters to be adapted.

  • target_clusters_data (dict) – For each target cluster (key, str), store dictionary (item, dict) containing cluster associated parameters relevant for the adaptive procedures.

  • adaptive_clustering_scheme (dict) – Prescribed adaptive clustering scheme (item, numpy.ndarray of shape (n_clusterings, 3)) for each material phase (key, str). Each row is associated with a unique clustering characterized by a clustering algorithm (col 1, int), a list of features (col 2, list[int]) and a list of the features data matrix’ indexes (col 3, list[int]).

  • min_label (int, default=0) – Minimum cluster label.

Returns:

  • adaptive_clustering_map (dict) – List of new cluster labels (item, list[int]) resulting from the adaptivity of each target cluster (key, str).

  • adaptive_tree_node_map (dict) – List of new cluster tree node ids (item, list[int]) resulting from the split of each target cluster tree node id (key, str). Validation purposes only (not returned otherwise).

perform_base_clustering(base_clustering_scheme, min_label=0)[source]

Perform HAACRMP base clustering.

Parameters:
  • base_clustering_scheme (dict) – Prescribed base clustering scheme (item, numpy.ndarray of shape (n_clusterings, 3)) for each material phase (key, str). Each row is associated with a unique clustering characterized by a clustering algorithm (col 1, int), a list of features (col 2, list[int]) and a list of the features data matrix’ indexes (col 3, list[int]).

  • min_label (int, default=0) – Minimum cluster label.

print_adaptive_clustering(adaptive_clustering_map, adaptive_tree_node_map)[source]

Print hierarchical adaptive clustering report (validation).