scib-metrics 0.5.4__tar.gz → 0.5.5__tar.gz

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
     hooks:
       - id: prettier
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.6
+    rev: v0.11.12
     hooks:
       - id: ruff
         types_or: [python, pyi, jupyter]

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/CHANGELOG.md

@@ -10,6 +10,18 @@ and this project adheres to [Semantic Versioning][].
 
 ## 0.6.0 (unreleased)
 
+## 0.5.5 (2025-06-03)
+
+### Added
+
+- Add batch removal adapted silhouette (BRAS) metric ({func}`scib_metrics.metrics.bras`) {pr}`197`, which addresses limitations of silhouette for scoring batch effect removal.
+- Add cosine distance implementation required for BRAS.
+
+### Changed
+
+- Changed {func}`scib_metrics.utils.cdist` to support cosine distance.
+- Changed silhouette-related functions to be compatible with adaptions required for BRAS.
+
 ## 0.5.4 (2025-04-23)
 
 ### Fixed

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scib-metrics
-Version: 0.5.4
+Version: 0.5.5
 Summary: Accelerated and Python-only scIB metrics
 Project-URL: Documentation, https://scib-metrics.readthedocs.io/
 Project-URL: Source, https://github.com/yoseflab/scib-metrics

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/docs/api.md

@@ -42,6 +42,7 @@ scib_metrics.ilisi_knn(...)
     pcr_comparison
     silhouette_label
     silhouette_batch
+    bras
     ilisi_knn
     clisi_knn
     kbet

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/docs/references.bib

@@ -36,3 +36,13 @@
   pages = {43--49},
   publisher = {Springer Science and Business Media {LLC}}
 }
+
+@article{rautenstrauch2025,
+  title = {Metrics Matter: Why We Need to Stop Using Silhouette in Single-Cell Benchmarking},
+  author = {Pia Rautenstrauch and Uwe Ohler},
+  doi = {10.1101/2025.01.21.634098},
+  year = {2025},
+  month = jan,
+  journal = {bioRxiv},
+  publisher = {Cold Spring Harbor Laboratory}
+}

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/pyproject.toml

@@ -5,7 +5,7 @@ requires = ["hatchling"]
 
 [project]
 name = "scib-metrics"
-version = "0.5.4"
+version = "0.5.5"
 description = "Accelerated and Python-only scIB metrics"
 readme = "README.md"
 requires-python = ">=3.10"

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/src/scib_metrics/__init__.py

@@ -15,6 +15,7 @@ from .metrics import (
     pcr_comparison,
     silhouette_batch,
     silhouette_label,
+    bras,
 )
 from ._settings import settings
 
@@ -25,6 +26,7 @@ __all__ = [
     "pcr_comparison",
     "silhouette_label",
     "silhouette_batch",
+    "bras",
     "ilisi_knn",
     "clisi_knn",
     "lisi_knn",

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/src/scib_metrics/metrics/__init__.py

@@ -4,13 +4,14 @@ from ._kbet import kbet, kbet_per_label
 from ._lisi import clisi_knn, ilisi_knn, lisi_knn
 from ._nmi_ari import nmi_ari_cluster_labels_kmeans, nmi_ari_cluster_labels_leiden
 from ._pcr_comparison import pcr_comparison
-from ._silhouette import silhouette_batch, silhouette_label
+from ._silhouette import bras, silhouette_batch, silhouette_label
 
 __all__ = [
     "isolated_labels",
     "pcr_comparison",
     "silhouette_label",
     "silhouette_batch",
+    "bras",
     "ilisi_knn",
     "clisi_knn",
     "lisi_knn",

scib_metrics-0.5.5/src/scib_metrics/metrics/_silhouette.py

@@ -0,0 +1,162 @@
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+from scib_metrics.utils import silhouette_samples
+
+
+def silhouette_label(
+    X: np.ndarray,
+    labels: np.ndarray,
+    rescale: bool = True,
+    chunk_size: int = 256,
+    metric: Literal["euclidean", "cosine"] = "euclidean",
+) -> float:
+    """Average silhouette width (ASW) :cite:p:`luecken2022benchmarking`.
+
+    Default parameters ('euclidean') match scIB implementation.
+
+    Parameters
+    ----------
+    X
+        Array of shape (n_cells, n_features).
+    labels
+        Array of shape (n_cells,) representing label values
+    rescale
+        Scale asw into the range [0, 1].
+    chunk_size
+        Size of chunks to process at a time for distance computation
+    metric
+        The distance metric to use. The distance function can be 'euclidean' (default) or 'cosine'.
+
+    Returns
+    -------
+    silhouette score
+    """
+    asw = np.mean(silhouette_samples(X, labels, chunk_size=chunk_size, metric=metric))
+    if rescale:
+        asw = (asw + 1) / 2
+    return np.mean(asw)
+
+
+def silhouette_batch(
+    X: np.ndarray,
+    labels: np.ndarray,
+    batch: np.ndarray,
+    rescale: bool = True,
+    chunk_size: int = 256,
+    metric: Literal["euclidean", "cosine"] = "euclidean",
+    between_cluster_distances: Literal["nearest", "mean_other", "furthest"] = "nearest",
+) -> float:
+    """Average silhouette width (ASW) with respect to batch ids within each label :cite:p:`luecken2022benchmarking`.
+
+    Default parameters ('euclidean', 'nearest') match scIB implementation.
+
+    Additional options enable BRAS compatible usage (see :func:`~scib_metrics.metrics.bras` documentation).
+
+    Parameters
+    ----------
+    X
+        Array of shape (n_cells, n_features).
+    labels
+        Array of shape (n_cells,) representing label values
+    batch
+        Array of shape (n_cells,) representing batch values
+    rescale
+        Scale asw into the range [0, 1]. If True, higher values are better.
+    chunk_size
+        Size of chunks to process at a time for distance computation.
+    metric
+        The distance metric to use. The distance function can be 'euclidean' (default) or 'cosine'.
+    between_cluster_distances
+        Method for computing inter-cluster distances.
+        - 'nearest': Standard silhouette (distance to nearest cluster)
+        - 'mean_other': BRAS-specific (mean distance to all other clusters)
+        - 'furthest': BRAS-specific (distance to furthest cluster)
+
+    Returns
+    -------
+    silhouette score
+    """
+    sil_dfs = []
+    unique_labels = np.unique(labels)
+    for group in unique_labels:
+        labels_mask = labels == group
+        X_subset = X[labels_mask]
+        batch_subset = batch[labels_mask]
+        n_batches = len(np.unique(batch_subset))
+
+        if (n_batches == 1) or (n_batches == X_subset.shape[0]):
+            continue
+
+        sil_per_group = silhouette_samples(
+            X_subset,
+            batch_subset,
+            chunk_size=chunk_size,
+            metric=metric,
+            between_cluster_distances=between_cluster_distances,
+        )
+
+        # take only absolute value
+        sil_per_group = np.abs(sil_per_group)
+
+        if rescale:
+            # scale s.t. highest number is optimal
+            sil_per_group = 1 - sil_per_group
+
+        sil_dfs.append(
+            pd.DataFrame(
+                {
+                    "group": [group] * len(sil_per_group),
+                    "silhouette_score": sil_per_group,
+                }
+            )
+        )
+
+    sil_df = pd.concat(sil_dfs).reset_index(drop=True)
+    sil_means = sil_df.groupby("group").mean()
+    asw = sil_means["silhouette_score"].mean()
+
+    return asw
+
+
+def bras(
+    X: np.ndarray,
+    labels: np.ndarray,
+    batch: np.ndarray,
+    chunk_size: int = 256,
+    metric: Literal["euclidean", "cosine"] = "cosine",
+    between_cluster_distances: Literal["mean_other", "furthest"] = "mean_other",
+) -> float:
+    """Batch removal adapted silhouette (BRAS) for single-cell data integration assessment :cite:p:`rautenstrauch2025`.
+
+    BRAS evaluates batch effect removal with respect to batch ids within each label (cell type cluster),
+    using a modified silhouette score that accounts for nested batch effects. Unlike standard silhouette,
+    BRAS computes between-cluster distances using the `between_cluster_distances` method rather than
+    nearest-cluster approach. A higher scores indicates better batch mixing.
+
+    Parameters
+    ----------
+    X
+        Array of shape (n_cells, n_features).
+    labels
+        Array of shape (n_cells,) representing label values
+    batch
+        Array of shape (n_cells,) representing batch values
+    rescale
+        Scale asw into the range [0, 1]. If True, higher values are better.
+    chunk_size
+        Size of chunks to process at a time for distance computation.
+    metric
+        The distance metric to use. The distance function can be 'euclidean' (default) or 'cosine'.
+    between_cluster_distances
+        Method for computing inter-cluster distances.
+        - 'mean_other': Mean distance to all cells in other clusters (default)
+        - 'furthest': Distance to furthest cluster (conservative estimate)
+
+    Returns
+    -------
+    BRAS score
+    """
+    return silhouette_batch(X, labels, batch, True, chunk_size, metric, between_cluster_distances)

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/src/scib_metrics/utils/_dist.py

@@ -1,3 +1,6 @@
+from functools import partial
+from typing import Literal
+
 import jax
 import jax.numpy as jnp
 import numpy as np
@@ -10,10 +13,20 @@ def _euclidean_distance(x: np.array, y: np.array) -> float:
 
 
 @jax.jit
-def cdist(x: np.ndarray, y: np.ndarray) -> jnp.ndarray:
+def _cosine_distance(x: np.array, y: np.array) -> float:
+    xy = jnp.dot(x, y)
+    xx = jnp.dot(x, x)
+    yy = jnp.dot(y, y)
+    dist = 1.0 - xy / jnp.sqrt(xx * yy)
+    # Clip the result to avoid rounding error
+    return jnp.clip(dist, 0.0, 2.0)
+
+
+@partial(jax.jit, static_argnames=["metric"])
+def cdist(x: np.ndarray, y: np.ndarray, metric: Literal["euclidean", "cosine"] = "euclidean") -> jnp.ndarray:
     """Jax implementation of :func:`scipy.spatial.distance.cdist`.
 
-    Uses euclidean distance.
+    Uses euclidean distance by default, cosine distance is also available.
 
     Parameters
     ----------
@@ -21,13 +34,20 @@ def cdist(x: np.ndarray, y: np.ndarray) -> jnp.ndarray:
         Array of shape (n_cells_a, n_features)
     y
         Array of shape (n_cells_b, n_features)
+    metric
+        The distance metric to use. The distance function can be 'euclidean' (default) or 'cosine'.
 
     Returns
     -------
     dist
         Array of shape (n_cells_a, n_cells_b)
     """
-    return jax.vmap(lambda x1: jax.vmap(lambda y1: _euclidean_distance(x1, y1))(y))(x)
+    if metric not in ["euclidean", "cosine"]:
+        raise ValueError("Invalid metric choice, must be one of ['euclidean' or 'cosine'].")
+    if metric == "cosine":
+        return jax.vmap(lambda x1: jax.vmap(lambda y1: _cosine_distance(x1, y1))(y))(x)
+    else:
+        return jax.vmap(lambda x1: jax.vmap(lambda y1: _euclidean_distance(x1, y1))(y))(x)
 
 
 @jax.jit

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/src/scib_metrics/utils/_silhouette.py

@@ -1,4 +1,5 @@
 from functools import partial
+from typing import Literal
 
 import jax
 import jax.numpy as jnp
@@ -9,13 +10,21 @@ from ._dist import cdist
 from ._utils import get_ndarray
 
 
-@jax.jit
+@partial(jax.jit, static_argnames=["between_cluster_distances"])
 def _silhouette_reduce(
-    D_chunk: jnp.ndarray, start: int, labels: jnp.ndarray, label_freqs: jnp.ndarray
+    D_chunk: jnp.ndarray,
+    start: int,
+    labels: jnp.ndarray,
+    label_freqs: jnp.ndarray,
+    between_cluster_distances: Literal["nearest", "mean_other", "furthest"] = "nearest",
 ) -> tuple[jnp.ndarray, jnp.ndarray]:
     """Accumulate silhouette statistics for vertical chunk of X.
 
-    Follows scikit-learn implementation.
+    Follows scikit-learn implementation with default parameter usage ('nearest').
+
+    Additional options enable BRAS compatible usage, addressing specific limitations of using silhouette in the context
+     of evaluating data integration (see :func:`~scib_metrics.metrics.bras` documentation).
+
 
     Parameters
     ----------
@@ -29,6 +38,12 @@ def _silhouette_reduce(
         Corresponding cluster labels, encoded as {0, ..., n_clusters-1}.
     label_freqs
         Distribution of cluster labels in ``labels``.
+    between_cluster_distances
+        Method for computing inter-cluster distances.
+        - 'nearest': Standard silhouette (distance to nearest cluster)
+        - 'mean_other': BRAS-specific (mean distance to all other clusters)
+        - 'furthest': BRAS-specific (distance to furthest cluster)
+
     """
     # accumulate distances from each sample to each cluster
     D_chunk_len = D_chunk.shape[0]
@@ -43,21 +58,36 @@ def _silhouette_reduce(
     # clust_dists = jax.lax.fori_loop(
     #     0, D_chunk_len, lambda i, _data: _bincount(i, _data), (clust_dists, D_chunk, labels, label_freqs)
     # )[0]
-
     clust_dists = jax.vmap(partial(jnp.bincount, length=label_freqs.shape[0]), in_axes=(None, 0))(labels, D_chunk)
 
     # intra_index selects intra-cluster distances within clust_dists
     intra_index = (jnp.arange(D_chunk_len), jax.lax.dynamic_slice(labels, (start,), (D_chunk_len,)))
     # intra_clust_dists are averaged over cluster size outside this function
     intra_clust_dists = clust_dists[intra_index]
-    # of the remaining distances we normalise and extract the minimum
-    clust_dists = clust_dists.at[intra_index].set(jnp.inf)
-    clust_dists /= label_freqs
-    inter_clust_dists = clust_dists.min(axis=1)
+
+    if between_cluster_distances == "furthest":
+        # of the remaining distances we normalise and extract the maximum
+        clust_dists = clust_dists.at[intra_index].set(-jnp.inf)
+        clust_dists /= label_freqs
+        inter_clust_dists = clust_dists.max(axis=1)
+    elif between_cluster_distances == "mean_other":
+        clust_dists = clust_dists.at[intra_index].set(jnp.nan)
+        total_other_dists = jnp.nansum(clust_dists, axis=1)
+        total_other_count = jnp.sum(label_freqs) - label_freqs[jax.lax.dynamic_slice(labels, (start,), (D_chunk_len,))]
+        inter_clust_dists = total_other_dists / total_other_count
+    elif between_cluster_distances == "nearest":
+        # of the remaining distances we normalise and extract the minimum
+        clust_dists = clust_dists.at[intra_index].set(jnp.inf)
+        clust_dists /= label_freqs
+        inter_clust_dists = clust_dists.min(axis=1)
+    else:
+        raise ValueError("Parameter 'between_cluster_distances' must be one of ['nearest', 'mean_other', 'furthest'].")
     return intra_clust_dists, inter_clust_dists
 
 
-def _pairwise_distances_chunked(X: jnp.ndarray, chunk_size: int, reduce_fn: callable) -> jnp.ndarray:
+def _pairwise_distances_chunked(
+    X: jnp.ndarray, chunk_size: int, reduce_fn: callable, metric: Literal["euclidean", "cosine"] = "euclidean"
+) -> jnp.ndarray:
     """Compute pairwise distances in chunks to reduce memory usage."""
     n_samples = X.shape[0]
     n_chunks = jnp.ceil(n_samples / chunk_size).astype(int)
@@ -66,17 +96,27 @@ def _pairwise_distances_chunked(X: jnp.ndarray, chunk_size: int, reduce_fn: call
     for i in range(n_chunks):
         start = i * chunk_size
         end = min((i + 1) * chunk_size, n_samples)
-        intra_cluster_dists, inter_cluster_dists = reduce_fn(cdist(X[start:end], X), start=start)
+        intra_cluster_dists, inter_cluster_dists = reduce_fn(cdist(X[start:end], X, metric=metric), start=start)
         intra_dists_all.append(intra_cluster_dists)
         inter_dists_all.append(inter_cluster_dists)
     return jnp.concatenate(intra_dists_all), jnp.concatenate(inter_dists_all)
 
 
-def silhouette_samples(X: np.ndarray, labels: np.ndarray, chunk_size: int = 256) -> np.ndarray:
+def silhouette_samples(
+    X: np.ndarray,
+    labels: np.ndarray,
+    chunk_size: int = 256,
+    metric: Literal["euclidean", "cosine"] = "euclidean",
+    between_cluster_distances: Literal["nearest", "mean_other", "furthest"] = "nearest",
+) -> np.ndarray:
     """Compute the Silhouette Coefficient for each observation.
 
     Implements :func:`sklearn.metrics.silhouette_samples`.
 
+    Default parameters ('euclidean', 'nearest') match scIB implementation.
+
+    Additional options enable BRAS compatible usage (see `bras()` documentation).
+
     Parameters
     ----------
     X
@@ -87,6 +127,13 @@ def silhouette_samples(X: np.ndarray, labels: np.ndarray, chunk_size: int = 256)
         for each observation.
     chunk_size
         Number of samples to process at a time for distance computation.
+    metric
+        The distance metric to use. The distance function can be 'euclidean' (default) or 'cosine'.
+    between_cluster_distances
+        Method for computing inter-cluster distances.
+        - 'nearest': Standard silhouette (distance to nearest cluster)
+        - 'mean_other': BRAS-specific (mean distance to all other clusters)
+        - 'furthest': BRAS-specific (distance to furthest cluster)
 
     Returns
     -------
@@ -97,8 +144,10 @@ def silhouette_samples(X: np.ndarray, labels: np.ndarray, chunk_size: int = 256)
     labels = pd.Categorical(labels).codes
     labels = jnp.asarray(labels)
     label_freqs = jnp.bincount(labels)
-    reduce_fn = partial(_silhouette_reduce, labels=labels, label_freqs=label_freqs)
-    results = _pairwise_distances_chunked(X, chunk_size=chunk_size, reduce_fn=reduce_fn)
+    reduce_fn = partial(
+        _silhouette_reduce, labels=labels, label_freqs=label_freqs, between_cluster_distances=between_cluster_distances
+    )
+    results = _pairwise_distances_chunked(X, chunk_size=chunk_size, reduce_fn=reduce_fn, metric=metric)
     intra_clust_dists, inter_clust_dists = results
 
     denom = jnp.take(label_freqs - 1, labels, mode="clip")

scib_metrics-0.5.5/tests/test_BRAS_metric.py

@@ -0,0 +1,347 @@
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+from sklearn.metrics import silhouette_samples as sk_silhouette_samples
+from sklearn.metrics.pairwise import pairwise_distances
+
+import scib_metrics
+from tests.utils.data import dummy_benchmarker_adata, dummy_x_labels
+
+
+# v 0.5.3 with modifications for BRAS usage
+def silhouette_batch_custom(
+    X: np.ndarray,
+    labels: np.ndarray,
+    batch: np.ndarray,
+    rescale: bool = True,
+    chunk_size: int = 256,
+    metric: Literal["euclidean", "cosine"] = "euclidean",
+    between_cluster_distances: Literal["nearest", "mean_other", "furthest"] = "nearest",
+) -> float:
+    """Average silhouette width (ASW) with respect to batch ids within each label :cite:p:`luecken2022benchmarking`.
+
+    Default parameters ('euclidean', 'nearest') match scIB implementation.
+
+    Additional options enable BRAS compatible usage (see `bras()` documentation).
+
+    This version uses a naive implementation for the silhouette score calculation, serving as a reference for the fast
+    implementation provided in this package.
+
+    Parameters
+    ----------
+    X
+        Array of shape (n_cells, n_features).
+    labels
+        Array of shape (n_cells,) representing label values
+    batch
+        Array of shape (n_cells,) representing batch values
+    rescale
+        Scale asw into the range [0, 1]. If True, higher values are better.
+    chunk_size
+        Size of chunks to process at a time for distance computation.
+    metric
+        The distance metric to use. The distance function can be 'euclidean' (default) or 'cosine'.
+    between_cluster_distances
+        Method for computing inter-cluster distances.
+        - 'nearest': Standard silhouette (distance to nearest cluster)
+        - 'mean_other': BRAS-specific (mean distance to all other clusters)
+        - 'furthest': BRAS-specific (distance to furthest cluster)
+
+    Returns
+    -------
+    silhouette score
+    """
+    sil_dfs = []
+    unique_labels = np.unique(labels)
+    for group in unique_labels:
+        labels_mask = labels == group
+        X_subset = X[labels_mask]
+        batch_subset = batch[labels_mask]
+        n_batches = len(np.unique(batch_subset))
+
+        if (n_batches == 1) or (n_batches == X_subset.shape[0]):
+            continue
+
+        sil_per_group = silhouette_samples_custom(
+            X_subset,
+            batch_subset,
+            metric=metric,
+            between_cluster_distances=between_cluster_distances,
+        )
+
+        # take only absolute value
+        sil_per_group = np.abs(sil_per_group)
+
+        if rescale:
+            # scale s.t. highest number is optimal
+            sil_per_group = 1 - sil_per_group
+
+        sil_dfs.append(
+            pd.DataFrame(
+                {
+                    "group": [group] * len(sil_per_group),
+                    "silhouette_score": sil_per_group,
+                }
+            )
+        )
+
+    sil_df = pd.concat(sil_dfs).reset_index(drop=True)
+    sil_means = sil_df.groupby("group").mean()
+    asw = sil_means["silhouette_score"].mean()
+
+    return asw
+
+
+def silhouette_samples_custom(X, cluster_labels, metric="euclidean", between_cluster_distances="nearest"):
+    """
+
+    Naive implementation of silhouette score modifications changing inter-cluster distance calculations for testing fast
+     implementations.
+
+    Experimental variants include:
+    - Standard silhouette ('nearest' cluster distance)
+    - BRAS-specific modifications ('mean_other', 'furthest')
+
+    Parameters
+    ----------
+    X
+        Array of shape (n_cells, n_features).
+    cluster_labels
+        Array of shape (n_cells,) representing cluster label values
+    metric
+        The distance metric to use. The distance function can be 'euclidean' (default) or 'cosine'.
+    between_cluster_distances
+        Method for computing inter-cluster distances.
+        - 'nearest': Standard silhouette (distance to nearest cluster)
+        - 'mean_other': BRAS-specific (mean distance to all other clusters)
+        - 'furthest': BRAS-specific (distance to furthest cluster)
+
+    Returns
+    -------
+    (Modified) silhouette scores with selected inter-cluster distance calcuation.
+    """
+
+    # Number of clusters
+    unique_cluster_labels = np.unique(cluster_labels)
+    n_clusters = len(unique_cluster_labels)
+
+    # If there's only one cluster or no clusters, return 0 as silhouette score cannot be computed
+    if n_clusters == 1 or n_clusters == 0:
+        return 0
+
+    # Initialize silhouette scores
+    silhouette_scores = np.zeros(len(X))
+
+    # Calculate pairwise distance matrix
+    distance_matrix = pairwise_distances(X, metric=metric)
+
+    for i in range(len(X)):
+        # Points in the same cluster
+        same_cluster = cluster_labels == cluster_labels[i]
+        other_clusters = cluster_labels != cluster_labels[i]
+        # Exclude the current point for intra-cluster distance
+        same_cluster[i] = False
+
+        # a: Mean distance from i to all other points in the same cluster
+        if np.sum(same_cluster) == 0:
+            silhouette_scores[i] = 0
+            continue
+
+        a = np.mean(distance_matrix[i, same_cluster])
+
+        # b: Mean distance from i to all points in the furthest different cluster
+        if between_cluster_distances == "furthest":
+            b = np.max(
+                [
+                    np.mean(distance_matrix[i, cluster_labels == label])
+                    for label in unique_cluster_labels
+                    if label != cluster_labels[i]
+                ]
+            )
+
+        # b: Mean distance from i to all points in any other cluster
+        elif between_cluster_distances == "mean_other":
+            b = np.mean(distance_matrix[i, other_clusters])
+
+        # b: Mean distance from i to all points in the nearest different cluster
+        else:
+            b = np.min(
+                [
+                    np.mean(distance_matrix[i, cluster_labels == label])
+                    for label in unique_cluster_labels
+                    if label != cluster_labels[i]
+                ]
+            )
+
+        # Silhouette score for point i
+        silhouette_scores[i] = (b - a) / max(a, b)
+
+    return silhouette_scores
+
+
+def test_silhouette_samples_cosine():
+    X, labels = dummy_x_labels()
+    assert np.allclose(
+        scib_metrics.utils.silhouette_samples(X, labels, metric="cosine"),
+        silhouette_samples_custom(X, labels, metric="cosine"),
+        atol=1e-5,
+    )
+
+
+def test_silhouette_samples_nearest():
+    X, labels = dummy_x_labels()
+    assert np.allclose(
+        scib_metrics.utils.silhouette_samples(X, labels, between_cluster_distances="nearest"),
+        silhouette_samples_custom(X, labels, between_cluster_distances="nearest"),
+        atol=1e-5,
+    )
+
+
+def test_silhouette_samples_mean_other():
+    X, labels = dummy_x_labels()
+    assert np.allclose(
+        scib_metrics.utils.silhouette_samples(X, labels, between_cluster_distances="mean_other"),
+        silhouette_samples_custom(X, labels, between_cluster_distances="mean_other"),
+        atol=1e-5,
+    )
+
+
+def test_silhouette_samples_furthest():
+    X, labels = dummy_x_labels()
+    assert np.allclose(
+        scib_metrics.utils.silhouette_samples(X, labels, between_cluster_distances="furthest"),
+        silhouette_samples_custom(X, labels, between_cluster_distances="furthest"),
+        atol=1e-5,
+    )
+
+
+def test_silhouette_label():
+    X, labels = dummy_x_labels()
+    score = scib_metrics.silhouette_label(X, labels)
+    score_sk = (np.mean(sk_silhouette_samples(X, labels)) + 1) / 2
+    assert np.allclose(score, score_sk)
+
+
+def test_silhouette_label_cosine():
+    X, labels = dummy_x_labels()
+    score = scib_metrics.silhouette_label(X, labels, metric="cosine")
+    score_sk = (np.mean(sk_silhouette_samples(X, labels, metric="cosine")) + 1) / 2
+    assert np.allclose(score, score_sk)
+
+
+def test_bras():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.bras(ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key])
+    score_no = silhouette_batch_custom(
+        ad.obsm[emb_keys[0]],
+        ad.obs[labels_key],
+        ad.obs[batch_key],
+        metric="cosine",
+        between_cluster_distances="mean_other",
+    )
+    assert np.allclose(score, score_no)
+
+
+def test_silhouette_batch_default():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.silhouette_batch(ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key])
+    score_no = silhouette_batch_custom(ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key])
+    assert np.allclose(score, score_no)
+
+
+def test_silhouette_batch_cosine():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.silhouette_batch(ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key], metric="cosine")
+    score_no = silhouette_batch_custom(ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key], metric="cosine")
+    assert np.allclose(score, score_no)
+
+
+def test_silhouette_batch_nearest():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.silhouette_batch(
+        ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key], between_cluster_distances="nearest"
+    )
+    score_no = silhouette_batch_custom(
+        ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key], between_cluster_distances="nearest"
+    )
+    assert np.allclose(score, score_no)
+
+
+def test_silhouette_batch_cosine_nearest():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.silhouette_batch(
+        ad.obsm[emb_keys[0]],
+        ad.obs[labels_key],
+        ad.obs[batch_key],
+        metric="cosine",
+        between_cluster_distances="nearest",
+    )
+    score_no = silhouette_batch_custom(
+        ad.obsm[emb_keys[0]],
+        ad.obs[labels_key],
+        ad.obs[batch_key],
+        metric="cosine",
+        between_cluster_distances="nearest",
+    )
+    assert np.allclose(score, score_no)
+
+
+def test_silhouette_batch_furthest():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.silhouette_batch(
+        ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key], between_cluster_distances="furthest"
+    )
+    score_no = silhouette_batch_custom(
+        ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key], between_cluster_distances="furthest"
+    )
+    assert np.allclose(score, score_no)
+
+
+def test_silhouette_batch_cosine_furthest():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.silhouette_batch(
+        ad.obsm[emb_keys[0]],
+        ad.obs[labels_key],
+        ad.obs[batch_key],
+        metric="cosine",
+        between_cluster_distances="furthest",
+    )
+    score_no = silhouette_batch_custom(
+        ad.obsm[emb_keys[0]],
+        ad.obs[labels_key],
+        ad.obs[batch_key],
+        metric="cosine",
+        between_cluster_distances="furthest",
+    )
+    assert np.allclose(score, score_no)
+
+
+def test_silhouette_batch_mean_other():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.silhouette_batch(
+        ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key], between_cluster_distances="mean_other"
+    )
+    score_no = silhouette_batch_custom(
+        ad.obsm[emb_keys[0]], ad.obs[labels_key], ad.obs[batch_key], between_cluster_distances="mean_other"
+    )
+    assert np.allclose(score, score_no)
+
+
+def test_silhouette_batch_cosine_mean_other():
+    ad, emb_keys, batch_key, labels_key = dummy_benchmarker_adata()
+    score = scib_metrics.silhouette_batch(
+        ad.obsm[emb_keys[0]],
+        ad.obs[labels_key],
+        ad.obs[batch_key],
+        metric="cosine",
+        between_cluster_distances="mean_other",
+    )
+    score_no = silhouette_batch_custom(
+        ad.obsm[emb_keys[0]],
+        ad.obs[labels_key],
+        ad.obs[batch_key],
+        metric="cosine",
+        between_cluster_distances="mean_other",
+    )
+    assert np.allclose(score, score_no)

{scib_metrics-0.5.4 → scib_metrics-0.5.5}/tests/test_metrics.py

@@ -32,6 +32,12 @@ def test_cdist():
     assert np.allclose(scib_metrics.utils.cdist(x, y), sp_cdist(x, y))
 
 
+def test_cdist_cosine():
+    x = jnp.array([[1, 2], [3, 4]])
+    y = jnp.array([[5, 6], [7, 8]])
+    assert np.allclose(scib_metrics.utils.cdist(x, y, metric="cosine"), sp_cdist(x, y, metric="cosine"), atol=1e-5)
+
+
 def test_pdist():
     x = jnp.array([[1, 2], [3, 4]])
     assert np.allclose(scib_metrics.utils.pdist_squareform(x), squareform(pdist(x)))

scib_metrics-0.5.4/src/scib_metrics/metrics/_silhouette.py

@@ -1,86 +0,0 @@
-import numpy as np
-import pandas as pd
-
-from scib_metrics.utils import silhouette_samples
-
-
-def silhouette_label(X: np.ndarray, labels: np.ndarray, rescale: bool = True, chunk_size: int = 256) -> float:
-    """Average silhouette width (ASW) :cite:p:`luecken2022benchmarking`.
-
-    Parameters
-    ----------
-    X
-        Array of shape (n_cells, n_features).
-    labels
-        Array of shape (n_cells,) representing label values
-    rescale
-        Scale asw into the range [0, 1].
-    chunk_size
-        Size of chunks to process at a time for distance computation.
-
-    Returns
-    -------
-    silhouette score
-    """
-    asw = np.mean(silhouette_samples(X, labels, chunk_size=chunk_size))
-    if rescale:
-        asw = (asw + 1) / 2
-    return np.mean(asw)
-
-
-def silhouette_batch(
-    X: np.ndarray, labels: np.ndarray, batch: np.ndarray, rescale: bool = True, chunk_size: int = 256
-) -> float:
-    """Average silhouette width (ASW) with respect to batch ids within each label :cite:p:`luecken2022benchmarking`.
-
-    Parameters
-    ----------
-    X
-        Array of shape (n_cells, n_features).
-    labels
-        Array of shape (n_cells,) representing label values
-    batch
-        Array of shape (n_cells,) representing batch values
-    rescale
-        Scale asw into the range [0, 1]. If True, higher values are better.
-    chunk_size
-        Size of chunks to process at a time for distance computation.
-
-    Returns
-    -------
-    silhouette score
-    """
-    sil_dfs = []
-    unique_labels = np.unique(labels)
-    for group in unique_labels:
-        labels_mask = labels == group
-        X_subset = X[labels_mask]
-        batch_subset = batch[labels_mask]
-        n_batches = len(np.unique(batch_subset))
-
-        if (n_batches == 1) or (n_batches == X_subset.shape[0]):
-            continue
-
-        sil_per_group = silhouette_samples(X_subset, batch_subset, chunk_size=chunk_size)
-
-        # take only absolute value
-        sil_per_group = np.abs(sil_per_group)
-
-        if rescale:
-            # scale s.t. highest number is optimal
-            sil_per_group = 1 - sil_per_group
-
-        sil_dfs.append(
-            pd.DataFrame(
-                {
-                    "group": [group] * len(sil_per_group),
-                    "silhouette_score": sil_per_group,
-                }
-            )
-        )
-
-    sil_df = pd.concat(sil_dfs).reset_index(drop=True)
-    sil_means = sil_df.groupby("group").mean()
-    asw = sil_means["silhouette_score"].mean()
-
-    return asw