RareQ rare-cell population detection

Usage

RunRareQ(
  object,
  assay = NULL,
  reduction = "pca",
  dims = 1:30,
  k.param = 20,
  k = 6,
  Q_cut = 0.6,
  ratio = 0.2,
  max_iter = 100,
  run_neighbors = TRUE,
  force_recalc = FALSE,
  neighbor_name = NULL,
  find_neighbors_params = list(),
  rare_threshold = 0.01,
  prefix = "RareQ",
  cluster_colname = paste0(prefix, "_cluster"),
  q_colname = paste0(prefix, "_Q"),
  size_colname = paste0(prefix, "_cluster_size"),
  rare_colname = paste0(prefix, "_is_rare"),
  tool_name = "RareQ",
  verbose = TRUE,
  srt = NULL
)

Arguments

object: A Seurat object.
assay: Assay to use. NULL uses the default assay.
reduction: Reduction used to build nearest neighbors when the required {assay}.nn neighbor slot is absent or force_recalc = TRUE. If NULL, DefaultReduction() is used.
dims: Dimensions from reduction used for nearest-neighbor search.
k.param: Number of nearest neighbors to compute with Seurat::FindNeighbors() when neighbor search is needed.
k: Number of nearest neighbors used by RareQ to compute Q values.
Q_cut: Q-value threshold passed to RareQ::FindRare().
ratio: Merge-ratio threshold passed to RareQ::FindRare().
max_iter: Maximum number of RareQ propagation iterations.
run_neighbors: Whether to build the required Seurat neighbor slot if it is missing.
force_recalc: Whether to rebuild the Seurat neighbor slot before running RareQ.
neighbor_name: Name of the Seurat Neighbor object to reuse or create. If NULL, defaults to {assay}.nn, which is the neighbor slot required by RareQ::ComputeQ() and RareQ::FindRare(). A non-default neighbor is copied to {assay}.nn before running RareQ because RareQ reads that slot directly.
find_neighbors_params: Additional named parameters passed to Seurat::FindNeighbors() when neighbor search is run.
rare_threshold: Cluster-size threshold used to mark rare clusters. A value smaller than 1 is treated as a fraction of cells; a value of 1 or larger is treated as a cell count. Set to NULL to skip rare flags.
prefix: Prefix used for metadata columns.
cluster_colname, q_colname, size_colname, rare_colname: Metadata column names for RareQ clusters, Q values, cluster sizes, and rare-cluster flags.
tool_name: Name of the srt@tools entry.
verbose: Whether to print the message. Default is TRUE.
srt: Deprecated alias for object; supply exactly one of the two. It will be removed in scop 1.0.0.

Value

A Seurat object with RareQ results in metadata and srt@tools[[tool_name]].

Details

Stored results retain a private per-cell identity metadata column for GetSpatialResult(). Preserve this column when subsetting or renaming cells. The accessor returns current-cell assignments; stored results and fit parameters remain unchanged.

References

Fa B, Huang C, Ma Y, et al. (2026). Cell neighborhood topology directs rare cell population identification. Nature Communications, 17, 4618. doi:10.1038/s41467-026-71180-x

Examples

data(pancreas_sub)
pancreas_sub <- RunStandardWorkflow(
  pancreas_sub,
  verbose = FALSE
)
#> ℹ [2026-11-12 06:00:27] Skip `log1p()` because `layer = data` is not "counts"
pancreas_sub <- RunRareQ(
  pancreas_sub,
  dims = 1:20
)
#> ℹ [2026-11-12 06:00:37] Build Seurat nearest neighbors for RareQ using reduction "Standardpca"
#> Computing nearest neighbors
#> ℹ [2026-11-12 06:00:37] Only one graph name supplied, storing nearest-neighbor graph only
#> ℹ [2026-11-12 06:00:37] Run RareQ with `k = 6`, `Q_cut = 0.6`, and `ratio = 0.2`
#> ℹ [2026-11-12 06:00:37] RareQ clusters stored in metadata column "RareQ_cluster"

CellDimPlot(
  pancreas_sub,
  group.by = "RareQ_cluster"
)


CellDimPlot(
  pancreas_sub,
  group.by = "RareQ_is_rare"
)


FeatureDimPlot(
  pancreas_sub,
  features = "RareQ_Q"
)