dire_rapids.utils module

Utility classes and functions for dire-rapids package.

This module provides: - ReducerConfig: Configuration dataclass for dimensionality reduction algorithms - ReducerRunner: General-purpose runner for dimensionality reduction benchmarking - Dataset loading utilities for sklearn, cytof, DiRe geometric datasets, and more

dire_rapids.utils.build_embedding_figure(embedding, labels=None, *, title='Embedding', n_dims=None, categorical_labels=True, mode='auto', density_threshold=50000, max_points=10000, n_bins=200, point_size=None, width=None, height=None, seed=42, logger=None)

Build a Plotly figure for a 2D/3D embedding (scatter or binned density).

Parameters:

• embedding (ndarray of shape (n_points, 2 or 3)) – The low-dimensional layout to plot.

• labels (array-like of shape (n_points,), optional) – Per-point labels used for coloring (scatter) or density layers.

• title (str, default="Embedding") – Base title; the render type and point count are appended.

• n_dims (int, optional) – Embedding dimensionality; inferred from embedding if None.

• categorical_labels (bool, default=True) – Treat labels as discrete classes (per-category colors / density layers) rather than a continuous scalar (single colorbar / mean heatmap).

• mode ({'auto', 'scatter', 'density'}, default='auto') – 'auto' switches to density once a 2D embedding exceeds density_threshold points; 'density' forces density (2D only, falls back to scatter in 3D); 'scatter' always draws markers.

• density_threshold (int, default=50000) – Point count above which 'auto' mode uses density.

• max_points (int, default=10000) – Subsample cap for scatter rendering (density uses all points).

• n_bins (int, default=300) – Bins per axis for density; bounds the figure payload.

• point_size (int, optional) – Marker size; defaults to 4 (2D) / 2 (3D) when None.

• width (int, optional) – Figure size overrides.

• height (int, optional) – Figure size overrides.

• seed (int, default=42) – RNG seed for reproducible scatter subsampling.

• logger (logging.Logger, optional) – Used for warnings; falls back to silent when None.

Returns:

None if the embedding is not 2D/3D.

Return type:

plotly.graph_objects.Figure or None

dire_rapids.utils.rand_point_disk(n_features, n_samples=1, rng=None)

Generate uniformly distributed points in n-dimensional unit disk.

dire_rapids.utils.rand_point_sphere(n_features, n_samples=1, rng=None)

Generate uniformly distributed points on n-dimensional unit sphere.

class dire_rapids.utils.elgen(a)

Bases: object

Ellipsoid generator - transforms sphere points to ellipsoid.

__init__(a)

dire_rapids.utils.rand_point_ell(semi_axes, n_features, n_samples=1, rng=None)

Generate uniformly distributed points on n-dimensional ellipsoid with semi-axes.

class dire_rapids.utils.ReducerConfig(name: str, reducer_class: type, reducer_kwargs: dict, visualize: bool = False, categorical_labels: bool = True, max_points: int = 10000, mode: str = 'auto', density_threshold: int = 50000)

Bases: object

Configuration for a dimensionality reduction algorithm.

All fields are mutable and can be changed after creation:

config.visualize = True config.categorical_labels = False config.max_points = 20000

name: str

reducer_class: type

reducer_kwargs: dict

visualize: bool = False

categorical_labels: bool = True

max_points: int = 10000

mode: str = 'auto'

density_threshold: int = 50000

__init__(name: str, reducer_class: type, reducer_kwargs: dict, visualize: bool = False, categorical_labels: bool = True, max_points: int = 10000, mode: str = 'auto', density_threshold: int = 50000) → None

class dire_rapids.utils.ReducerRunner(config: ReducerConfig)

Bases: object

General-purpose runner for dimensionality reduction algorithms.

Supports: - DiRe (create_dire, DiRePyTorch, DiRePyTorchMemoryEfficient, DiReCuVS) - cuML (UMAP, TSNE) - scikit-learn (any TransformerMixin-compatible class)

Parameters:

config (ReducerConfig) – Configuration object containing reducer_class, reducer_kwargs, name, and visualize flag.

config: ReducerConfig

__post_init__()

Validate that config is provided.

run(dataset, *, dataset_kwargs=None, transform=None)

Run dimensionality reduction on specified dataset.

Parameters:

• dataset (str) – Dataset selector (sklearn:name, openml:name, cytof:name, dire:name, file:path)

• dataset_kwargs (dict, optional) – Arguments for dataset loader

• transform (callable, optional) – Custom transform function (X, y) -> (X’, y’)

Returns:

Results containing: - embedding: reduced data - labels: data labels - reducer: fitted reducer instance - fit_time_sec: time taken for fit_transform - dataset_info: dataset metadata

Return type:

dict

static available_sklearn()

Return available sklearn dataset loaders, fetchers, and generators.

static available_cytof()

Return available CyTOF datasets.

__init__(config: ReducerConfig) → None