neurostatx.clustering.metrics

Functions

Name	Description
compute_evaluation_metrics	Compute silhouette, Calinski-Harabasz, and Davies-Bouldin scores.
compute_gap_stats	Compute the GAP statistic against uniformly sampled reference data.
compute_knee_location	Return the elbow location of a clustering metric curve.
compute_rand_index	Compute pairwise adjusted Rand indices from membership dataframes.
compute_sse	Compute the within-cluster sum of squared errors (WSS).
find_optimal_gap	Return the first k satisfying Tibshirani's GAP rule.

compute_evaluation_metricsfunction#

View source

def compute_evaluation_metrics(X, labels, metric='euclidean')

Compute silhouette, Calinski-Harabasz, and Davies-Bouldin scores.

Parameters

Name	Type	Default	Description
X	array - like	required	Data used to evaluate the clustering solution.
labels	list	required	Cluster labels for each sample.
metric	str	'euclidean'	Distance metric passed to the silhouette score. Defaults to "euclidean". Accepts options from sklearn.metrics.pairwise.pairwise_distances.

Returns

ssfloat

Silhouette score.

chifloat

Calinski-Harabasz index.

dbifloat

Davies-Bouldin index.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.metrics import compute_evaluation_metrics
>>> X = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [0.9, 1.1]])
>>> ss, chi, dbi = compute_evaluation_metrics(X, [0, 0, 1, 1])
>>> ss > 0
True

compute_gap_statsfunction#

View source

def compute_gap_stats(X, wss, nrefs, n_cluster, m=2, error=1e-06, maxiter=1000, metric='euclidean', init=None)

Compute the GAP statistic against uniformly sampled reference data.

Parameters

Name	Type	Default	Description
X	np.array	required	Data array used to generate reference samples.
wss	float	required	Within-cluster sum of squared errors for the fitted model.
nrefs	int	required	Number of random reference datasets to average.
n_cluster	int	required	Number of clusters in the fitted model.
m	float	2	Fuzziness exponent passed to Fuzzy C-Means. Defaults to 2.
error	float	1e-06	Convergence tolerance. Defaults to 1e-6.
maxiter	int	1000	Maximum iterations for each reference fit. Defaults to 1000.
metric	str	'euclidean'	Distance metric. Defaults to "euclidean".
init	array	None	Initial fuzzy c-partitioned matrix. Defaults to None.

Returns

gapfloat

GAP statistic.

skfloat

Standard error of the GAP statistic.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.metrics import compute_gap_stats,
...                                           compute_sse
>>> X = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [0.9, 1.0]])
>>> cntr = np.array([[0.05, 0.0], [0.95, 1.0]])
>>> labels = np.array([0, 0, 1, 1])
>>> gap, sk = compute_gap_stats(X, compute_sse(X, cntr, labels),
...                             nrefs=2, n_cluster=2)
>>> gap > 0
True

compute_knee_locationfunction#

View source

def compute_knee_location(lst, direction='decreasing')

Return the elbow location of a clustering metric curve.

Parameters

Name	Type	Default	Description
lst	list	required	Metric values used to locate the elbow, typically one per k.
direction	str	'decreasing'	Curve direction passed to Kneed. Defaults to "decreasing".

Returns

elbowint

Estimated elbow location (cluster count).

Examples

>>> from neurostatx.clustering.metrics import compute_knee_location
>>> compute_knee_location([10.0, 4.0, 3.5, 3.2])
3

compute_rand_indexfunction#

View source

def compute_rand_index(dict)

Compute pairwise adjusted Rand indices from membership dataframes.

Hard labels are obtained with argmax before scoring, because the adjusted Rand index applies only to crisp partitions.

Parameters

Name	Type	Description
dict	dict	Mapping of labels to membership dataframes.

Returns

arinp.array

Symmetric pairwise adjusted Rand index matrix.

Examples

>>> import pandas as pd
>>> from neurostatx.clustering.metrics import compute_rand_index
>>> a = pd.DataFrame([[0.9, 0.1], [0.2, 0.8]])
>>> b = pd.DataFrame([[0.8, 0.2], [0.1, 0.9]])
>>> compute_rand_index({"a": a, "b": b}).shape
(2, 2)

compute_ssefunction#

View source

def compute_sse(X, cntr, labels)

Compute the within-cluster sum of squared errors (WSS).

Parameters

Name	Type	Description
X	array	Original data of shape (n_samples, n_features).
cntr	array	Cluster centroids of shape (n_clusters, n_features).
labels	array	Hard cluster labels of shape (n_samples,).

Returns

WSSfloat

Within-cluster sum of squared errors.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.metrics import compute_sse
>>> X = np.array([[0.0, 0.0], [1.0, 1.0]])
>>> cntr = np.array([[0.0, 0.0], [1.0, 1.0]])
>>> compute_sse(X, cntr, np.array([0, 1]))
0.0

find_optimal_gapfunction#

View source

def find_optimal_gap(gap, sk)

Return the first k satisfying Tibshirani’s GAP rule.

Selects the first index where GAP[k] >= GAP[k+1] - SD[k+1].

Parameters

Name	Type	Description
gap	np.array	GAP statistic values for a range of cluster counts.
sk	np.array	Standard errors aligned with gap.

Returns

optimalint

Index of the selected solution.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.metrics import find_optimal_gap
>>> find_optimal_gap(np.array([0.2, 0.8, 0.7]), np.array([0.1, 0.1, 0.1]))
1