core.metrics

This module contains function-based utilities to compute clustering metrics used during model training and evaluation.

bulkdgd.core.metrics.encode_labels(labels_lists: list[list[str]]) → list[ndarray]

Encode string labels as integers.

Parameters:

labels_listslist

A list of lists of string labels.

Returns:

encoded_labelslist

A list of Numpy arrays of encoded integer labels, one for each input list.

bulkdgd.core.metrics.get_adjusted_mutual_info_score(y_true: object, y_pred: object) → float

Get the adjusted mutual information.

Parameters:

y_trueobject

The ground-truth labels.

y_predobject

The predicted labels.

Returns:

scorefloat

The adjusted mutual information, or nan if undefined.

bulkdgd.core.metrics.get_adjusted_rand_score(y_true: object, y_pred: object) → float

Get the adjusted Rand index.

Parameters:

y_trueobject

The ground-truth labels.

y_predobject

The predicted labels.

Returns:

scorefloat

The adjusted Rand index, or nan if undefined.

bulkdgd.core.metrics.get_bic_score(gmm_model: object, X: object) → float

Get the Bayesian information criterion (BIC).

Parameters:

gmm_modelobject

A fitted Gaussian mixture model exposing lower_bound_, covariance_type, and n_components (or n_comp).

Xobject

The feature matrix used to fit/evaluate the model.

Returns:

scorefloat

The BIC score, or nan if undefined.

bulkdgd.core.metrics.get_calinski_harabasz_score(X: object, labels: list[str]) → float

Get the Calinski-Harabasz score.

Parameters:

Xobject

The feature matrix.

labelslist

The predicted labels.

Returns:

scorefloat

The Calinski-Harabasz score, or nan if undefined.

bulkdgd.core.metrics.get_davies_bouldin_score(X: object, labels: list[str]) → float

Get the Davies-Bouldin score.

Parameters:

Xobject

The feature matrix.

labelslist

The predicted labels.

Returns:

scorefloat

The Davies-Bouldin score, or nan if undefined.

bulkdgd.core.metrics.get_metric_optimization_direction(metric_name: str) → str

Get optimization direction for a metric.

Parameters:

metric_namestr

The metric name.

Returns:

directionstr

"min" if lower values are better, "max" otherwise.

bulkdgd.core.metrics.get_metric_score(metric_name: str, X: object | None = None, labels: list[str] | None = None, gmm_model: object | None = None, y_true: ndarray | None = None, y_pred: ndarray | None = None) → float

Dispatch and compute a metric from its name.

Parameters:

metric_namestr

The metric name.

Xobject, optional

The feature matrix used by unsupervised metrics.

labelsobject, optional

Predicted labels used by unsupervised metrics.

gmm_modelobject, optional

A fitted Gaussian mixture model used by the "bic" metric.

y_trueobject, optional

Ground-truth labels used by supervised metrics.

y_predobject, optional

Predicted labels used by supervised metrics.

Returns:

scorefloat

The computed metric value.

bulkdgd.core.metrics.get_normalized_mutual_info_score(y_true: object, y_pred: object) → float

Get the normalized mutual information.

Parameters:

y_trueobject

The ground-truth labels.

y_predobject

The predicted labels.

Returns:

scorefloat

The normalized mutual information, or nan if undefined.

bulkdgd.core.metrics.get_silhouette_score(X: object, labels: list[str]) → float

Get the silhouette score.

Parameters:

Xobject

The feature matrix.

labelslist

The predicted labels.

Returns:

scorefloat

The silhouette score, or nan if undefined.