scib_metrics.sbee

scib_metrics.sbee(X, X_emb, batches, labels, sensitivity=0.15)

Compute sBEE (single-cell Batch Effect Evaluator) score [Myradov et al., 2026].

sBEE is a per-cell batch integration metric that produces scores in [0, 1], where higher values indicate better batch mixing. It combines two components via their harmonic mean.

The distance component checks whether a cell is geometrically closer to same-type cells from other batches than to same-type cells from its own batch. When the ratio of intra-batch to inter-batch distance is 1 or above, the component is set to 1 (no penalty). When the ratio is below 1, a penalty is applied that grows with the degree of separation. Cells whose cell type appears in only one batch are assigned a perfect score, as batch correction is not applicable there.

The neighborhood composition component checks whether the local batch composition around a cell matches the global batch distribution for that cell type. It compares batch proportions among same-type cells in the k-nearest neighborhood against global proportions using Jensen-Shannon distance. Smaller divergence gives a higher score.

The two components are combined via harmonic mean. A low score on either component pulls the overall score down. Cell-type scores are computed by macro-averaging across batches so that each batch contributes equally regardless of its size.

Parameters:

X NeighborsResults

A NeighborsResults object (kNN graph of the integrated embedding).

X_emb ndarray

Integrated embedding array of shape (n_cells, n_dims). Used to compute intra/inter batch distances.

batches ndarray

Array of shape (n_cells,) with batch labels (any dtype; will be encoded).

labels ndarray

Array of shape (n_cells,) with cell type labels (any dtype; will be encoded).

sensitivity float (default: 0.15)

Controls the sharpness of the distance component penalty. Default: 0.15.

Return type:

float

Returns:

float sBEE score in [0, 1]. Higher is better.