API

Object workflow

bcmp(
  object,
  batch_key = "batch",
  assay = NULL,
  layer = NULL,
  partition_n_pcs = 30L,
  partition_n_hvg = 2000L,
  k_min = 3L,
  k_max = NULL,
  batch_frac_threshold_for_k_max = 0.01,
  min_batch_coverage = NULL,
  min_cells_in_domain_per_batch = 5L,
  max_underrepresentation_fold = 10L,
  max_residual_cell_frac = 0.05,
  exclude_cells = NULL,
  seed = 236L,
  output_level = "standard",
  verbose = TRUE
)

Run the complete BCMP workflow from raw counts in a Seurat v5 or SingleCellExperiment object. BCMP selects highly variable genes, normalizes and scales the counts, computes an unintegrated PCA representation, and runs the partition search. The input object is not modified.

Argument	Meaning
`object`	(`Seurat` / `SingleCellExperiment`) A Seurat object with an `Assay5` assay, or a SingleCellExperiment object.
`batch_key`	(`character`) Name of the batch metadata column in Seurat or `colData`.
`assay`	(`character` / `NULL`) Name of the raw-count assay. `NULL` uses the default Seurat assay or `"counts"` for SingleCellExperiment.
`layer`	(`character` / `NULL`) Name of the Seurat v5 raw-count layer, e.g. `"counts"`. `NULL` selects `"counts"`. For SingleCellExperiment, leave this as `NULL` and select the raw-count assay with `assay`.
`partition_n_pcs`	(`integer`) Number of principal components used for BCMP.
`partition_n_hvg`	(`integer`) Number of highly variable genes used for BCMP.
`k_min`	(`integer`) Lower bound of the representation-scale search.
`k_max`	(`integer` / `NULL`) Optional upper bound. `NULL` derives it from batch sizes.
`batch_frac_threshold_for_k_max`	(`numeric`) Batches at or below this global cell fraction are ignored during automatic upper-bound derivation.
`min_batch_coverage`	(`integer` / `NULL`) Minimum number of batches required in each evaluated domain. `NULL` resolves to `max(2, ceiling(n_batches * 0.5))`.
`min_cells_in_domain_per_batch`	(`integer`) Minimum effective cells required for a batch to count as represented in a domain.
`max_underrepresentation_fold`	(`numeric`) Maximum allowed fold under-representation relative to global batch proportion.
`max_residual_cell_frac`	(`numeric`) Maximum fraction of active cells that may fall in residual domains excluded from the pass/fail decision.
`exclude_cells`	(`character` / `factor` / `logical` / `NULL`) Cell IDs or a logical mask in object cell order, where `TRUE` excludes a cell from partitioning. Excluded cells remain in the returned object as `Excluded_<batch>`.
`seed`	(`integer`) Random seed used by preprocessing, partitioning, and debug UMAP.
`output_level`	(`character`) `"standard"` (default) or `"debug"`.
`verbose`	(`logical`) Emit progress records when `TRUE`.

Return value

See Output for details.

Embedding workflow

bcmp_embedding(
  embedding,
  batch_labels,
  cell_ids = NULL,
  k_min = 3L,
  k_max = NULL,
  batch_frac_threshold_for_k_max = 0.01,
  min_batch_coverage = NULL,
  min_cells_in_domain_per_batch = 5L,
  max_underrepresentation_fold = 10L,
  max_residual_cell_frac = 0.05,
  seed = 236L,
  output_level = "standard",
  verbose = TRUE
)

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

Argument	Meaning
`embedding`	(`matrix` / `sparseMatrix`) Numeric matrix or a numeric `Matrix::sparseMatrix` with stored numeric values (e.g. `dgCMatrix`, `dgRMatrix`, or `dgTMatrix`). Cells are rows and dimensions are columns.
`batch_labels`	(`vector`) One non-missing, non-empty batch label per embedding row.
`cell_ids`	(`vector` / `NULL`) Unique, non-missing cell IDs. With `NULL`, IDs are `"0"` through `"n-1"`.
`k_min`	(`integer`) Lower bound of the representation-scale search.
`k_max`	(`integer` / `NULL`) Optional upper bound. `NULL` derives it from batch sizes.
`batch_frac_threshold_for_k_max`	(`numeric`) Batches at or below this global cell fraction are ignored during automatic upper-bound derivation.
`min_batch_coverage`	(`integer` / `NULL`) Minimum number of batches required in each evaluated domain. `NULL` resolves to `max(2, ceiling(n_batches * 0.5))`.
`min_cells_in_domain_per_batch`	(`integer`) Minimum effective cells required for a batch to count as represented in a domain.
`max_underrepresentation_fold`	(`numeric`) Maximum allowed fold under-representation relative to global batch proportion.
`max_residual_cell_frac`	(`numeric`) Maximum fraction of active cells that may fall in residual domains excluded from the pass/fail decision.
`seed`	(`integer`) Random seed used by partitioning.
`output_level`	(`character`) `"standard"` (default) or `"debug"`.
`verbose`	(`logical`) Emit progress records when `TRUE`.

Return value

See Output for details.