API Reference

The classes below are the supported top-level interface. Import them directly from cvi rather than from their implementation modules.

Base class

cvi.CVI(*[, backend, capacity])

Superclass containing elements shared between all CVIs.

Indices

cvi.CH(*[, backend, capacity])	Calinski-Harabasz (CH) Cluster Validity Index.
cvi.CONN([rho, alpha, beta, match_tracking, ...])	CONN Cluster Validity Index.
cvi.cSIL(*[, backend])	Centroid-based Silhouette (cSIL) Cluster Validity Index.
cvi.DB(*[, backend])	Davies-Bouldin (DB) Cluster Validity Index.
cvi.GD43(*[, backend])	Generalized Dunn's Index 43 (GD43) Cluster Validity Index.
cvi.GD53(*[, backend])	Generalized Dunn's Index 53 (GD53) Cluster Validity Index.
cvi.PS(*[, backend])	Partition Separation (PS) Cluster Validity Index.
cvi.rCIP(*[, backend])	(Renyi's) representative Cross Information Potential (rCIP) Cluster Validity Index.
cvi.WB(*[, backend, capacity])	WB-Index (WB) Cluster Validity Index.
cvi.XB(*[, backend, capacity])	Xie-Beni (XB) Cluster Validity Index.

Common methods

All indices inherit the common update interface from cvi.CVI. CONN does not currently implement remove, merge, or split.

cvi.CVI.get_cvi(data, label)	Update the CVI and return its criterion value.
cvi.CVI.update_many(data, labels, *[, ...])	Add a chunk to a fixed-capacity JAX stream, atomically on input errors.
cvi.CVI.remove(sample, label)	Remove a sample from an initialized CVI.
cvi.CVI.merge(target_label, source_label)	Merge a source cluster into a target cluster.
cvi.CVI.split(retained_label, new_label, ...)	Split a tracked subset from an existing cluster.

Undefined results

Every index returns numpy.nan when its criterion is not mathematically defined. An undefined batch evaluation also emits a RuntimeWarning. Incremental updates and functional JAX calls return NaN without warnings. For CH, WB, and XB, fewer than two clusters or an exactly zero denominator makes the score undefined: WGSS for CH, BGSS for WB, and minimum centroid separation for XB. Denominators are checked exactly, with no epsilon adjustment.

Functional JAX batch interface

Install the optional jax extra and enable JAX x64 before using this module. See Getting Started for label encoding, precision, and supported operations.

cvi.jax.batch_state(data, labels, *, n_clusters)

Return an immutable BatchState pytree of device-resident sufficient statistics. Labels must be dense and every cluster must be represented. n_clusters must be static under JIT.

cvi.jax.evaluate(state, *, index)

Return a JAX scalar for index="CH", "WB", or "XB". The index name must be static under JIT.

cvi.jax.batch_cvi(data, labels, *, n_clusters, index)

Compute batch statistics and evaluate the chosen index in one functional call. Suitable for composition with jit, vmap, and differentiation with fixed labels. No host scalar conversion is performed.

Functional JAX streaming interface

cvi.jax.empty_stream(*, capacity, n_features, index)

Allocate an immutable StreamingState of fixed-shape device arrays. Capacity and feature count must be positive static integers.

cvi.jax.stream_from_batch(state, *, capacity, index)

Pad a valid BatchState into a stream without changing its statistics. Capacity must accommodate all existing clusters.

cvi.jax.stream_update(state, sample, slot, *, index)

Return (new_state, score) after one incremental addition. Slots are integers in [0, capacity); they need not be contiguous.

cvi.jax.stream_chunk(state, data, slots, *, index, return_history=True)

Return (new_state, history) using a compiled scan, or a final scalar when return_history=False. Empty chunks are no-ops. Invalid slot values or nonfinite data return unchanged state and NaN output for the whole call. Shape/dtype errors raise ValueError. Options must be static under JIT.

cvi.jax.evaluate_stream(state, *, index)

Evaluate active clusters. The result is NaN until at least two clusters are active and the index’s denominator is positive (WGSS for CH, BGSS for WB, or minimum centroid separation for XB). Denominators are checked exactly, with no epsilon adjustment. The index must match the state’s distance layout (CH/WB versus XB).