Skip to content

hbac.md

Latest commit

 

History

History
140 lines (100 loc) · 3.07 KB

hbac.md

File metadata and controls

140 lines (100 loc) · 3.07 KB
Raw

HBACDetector API

The HBACDetector class implements Hierarchical Bias-Aware Clustering for shortcut detection.

Class Reference

::: shortcut_detect.clustering.HBACDetector options: show_root_heading: true show_source: true

Quick Reference

Constructor

HBACDetector(
    max_iterations: int = 3,
    min_cluster_size: float = 0.05,
    linkage: str = 'ward',
    distance_metric: str = 'euclidean',
    random_state: int = None
)

Parameters

Parameter Type Default Description
max_iterations int 3 Maximum depth of hierarchical analysis
min_cluster_size float 0.05 Minimum cluster size as fraction of total
linkage str 'ward' Linkage method for clustering
distance_metric str 'euclidean' Distance metric
random_state int None Random seed

Linkage Options

Value Description
'ward' Minimize within-cluster variance (default)
'complete' Maximum distance between clusters
'average' Average distance between clusters
'single' Minimum distance between clusters

Methods

fit()

def fit(
    embeddings: np.ndarray,
    group_labels: np.ndarray
) -> HBACDetector

Fit the HBAC detector.

Parameters:

Parameter Type Description
embeddings ndarray Shape (n_samples, n_features)
group_labels ndarray Shape (n_samples,)

Returns: self

predict()

def predict(embeddings: np.ndarray) -> np.ndarray

Predict cluster assignments for new embeddings.

Returns: Cluster labels array

get_dendrogram()

def get_dendrogram() -> dict

Get dendrogram data for visualization.

Returns: Dictionary with linkage matrix and labels

Attributes (after fit)

Attribute Type Description
purity_ float Cluster purity score (0-1)
linearity_ float Linear separability score (0-1)
shortcut_detected_ bool Whether shortcut was detected
cluster_labels_ ndarray Cluster assignments
dendrogram_ dict Dendrogram data
n_clusters_ int Number of clusters found

Usage Examples

Basic Usage

from shortcut_detect import HBACDetector

detector = HBACDetector()
detector.fit(embeddings, group_labels)

print(f"Purity: {detector.purity_:.2f}")
print(f"Shortcut detected: {detector.shortcut_detected_}")

Custom Configuration

detector = HBACDetector(
    max_iterations=5,
    min_cluster_size=0.03,
    linkage='complete',
    random_state=42
)

Visualization

from scipy.cluster.hierarchy import dendrogram
import matplotlib.pyplot as plt

detector.fit(embeddings, group_labels)

fig, ax = plt.subplots(figsize=(12, 6))
dendrogram(detector.dendrogram_, ax=ax)
plt.title(f"HBAC Dendrogram (Purity: {detector.purity_:.2f})")
plt.savefig("dendrogram.png")

See Also