API#

AnnData workflow#

bcmp.bcmp(adata, *, batch_key='batch', partition_n_pcs=30, partition_n_hvg=2000, k_min=3, k_max=None, batch_frac_threshold_for_k_max=0.01, min_batch_coverage=None, min_cells_in_domain_per_batch=5, max_underrepresentation_fold=10, max_residual_cell_frac=0.05, exclude_cells=None, seed=236, progress_logger=None, output_level='standard', verbose=True)[source]#

Run the complete BCMP workflow from raw counts in adata.X. BCMP selects highly variable genes within batches, normalizes and scales the counts, computes an unintegrated PCA representation, and runs the partition search. The input object is not modified.

Parameters:

  • adata (anndata.AnnData) – Input object with raw counts in adata.X. Observation and variable names must be unique.

  • batch_key (str) – Column in adata.obs containing non-missing batch labels.

  • partition_n_pcs (int) – Number of principal components used for BCMP.

  • partition_n_hvg (int) – Number of highly variable genes used for BCMP.

  • k_min (int) – Lower bound of the representation-scale search.

  • k_max (int or None) – Upper bound of the representation-scale search. None lets BCMP derive the bound from batch sizes.

  • batch_frac_threshold_for_k_max (float) – Batches below this global cell fraction are ignored during automatic k upper-bound derivation.

  • min_batch_coverage (int or None) – Minimum number of batches required in each evaluated domain. None resolves to max(2, ceil(n_batches * 0.5)).

  • min_cells_in_domain_per_batch (int) – Minimum effective cells required for a batch to count as represented in a domain.

  • max_underrepresentation_fold (float) – Maximum allowed fold under-representation relative to the global batch proportion.

  • max_residual_cell_frac (float) – Maximum fraction of active cells that may fall in residual domains excluded from the pass/fail decision.

  • exclude_cells (sequence of str, pandas.Series or None) – Cell identifiers to exclude from partitioning. They remain in the returned AnnData and receive Excluded_<batch> labels.

  • seed (int) – Random seed used by preprocessing, partitioning, and debug UMAP.

  • progress_logger (logging.Logger or None) – Optional destination for progress records.

  • output_level (str) – "standard" (default) or "debug".

  • verbose (bool) – Emit progress records when True.

Returns:

An AnnData result containing a copied AnnData object, final selection, and search trace. Debug output adds diagnostics.

See Output for details.

Return type:

bcmp.models.AnnDataResult

Embedding workflow#

bcmp.bcmp_embedding(embedding, batch_labels, *, cell_ids=None, k_min=3, k_max=None, batch_frac_threshold_for_k_max=0.01, min_batch_coverage=None, min_cells_in_domain_per_batch=5, max_underrepresentation_fold=10, max_residual_cell_frac=0.05, seed=236, progress_logger=None, output_level='standard', verbose=True)[source]#

Run BCMP on an existing unintegrated cell-by-dimension embedding and its batch labels.

Parameters:

  • embedding (numpy.ndarray) – Cell-by-dimension embedding matrix with shape (n_cells, n_dimensions).

  • batch_labels (sequence of str) – Batch label for each row of embedding. Labels must be non-missing and non-empty.

  • cell_ids (sequence of str or None) – Unique cell identifiers. If omitted, BCMP uses "0" through "n-1".

  • k_min (int) – Lower bound of the representation-scale search.

  • k_max (int or None) – Upper bound, or None for automatic derivation.

  • batch_frac_threshold_for_k_max (float) – Small-batch threshold for automatic upper-bound derivation.

  • min_batch_coverage (int or None) – Minimum number of batches required per evaluated domain.

  • min_cells_in_domain_per_batch (int) – Minimum effective cells required for a batch to count as represented in a domain.

  • max_underrepresentation_fold (float) – Maximum allowed fold under-representation relative to the global batch proportion.

  • max_residual_cell_frac (float) – Maximum active-cell fraction assigned to residual domains.

  • seed (int) – Random seed used by partitioning.

  • progress_logger (logging.Logger or None) – Optional destination for progress records.

  • output_level (str) – "standard" (default) or "debug".

  • verbose (bool) – Emit progress records when True.

Returns:

Cell-indexed labels, final selection, and search trace. Debug output adds diagnostics.

See Output for details.

Return type:

bcmp.models.EmbeddingResult

Runtime cache#

bcmp.set_cache_dir(cache_dir, *, force=False)[source]#

Configure process-level cache directories for Numba, Matplotlib, and XDG consumers. Call this before importing cache-sensitive libraries such as Numba, UMAP, or Matplotlib.

Parameters:

  • cache_dir (str or pathlib.Path) – Base directory under which BCMP creates namespaced cache directories.

  • force (bool) – Override conflicting environment values when True.

Returns:

The effective cache configuration.

Return type:

dict

bcmp.cache_info()[source]#

Return the currently observed process-level cache configuration. The dict contains configured, source, base_dir, numba_cache_dir, matplotlib_config_dir, and xdg_cache_home.

Return type:

dict

Bundled dataset#

bcmp.datasets.diabetic_kidney_lite()[source]#

Load the bundled 1,500-cell diabetic kidney AnnData example used by the vignette. Raw counts are stored in X; obs contains batch. obsm["X_demo_umap"] contains frozen coordinates used for vignette visualization. Candidate integration embeddings are recorded under obsm; their keys and display names are recorded under uns["integration_benchmark"].

Dataset source. This bundled example is a downsampled derivative of the Open Problems diabetic kidney dataset. The original study is Wilson PC, et al. Multimodal single cell sequencing implicates chromatin accessibility and genetic background in diabetic kidney disease progression. Nature Communications 13, 5253 (2022). doi:10.1038/s41467-022-32972-z. The source dataset is available under the CC BY 4.0 license.

Return type:

anndata.AnnData