Determine the optimal number of dimensions for downstream analysis

Uses two complementary heuristics to choose how many dimensions from a linear reduction (PCA, LSI, etc.) to pass to UMAP, neighbor graphs, and clustering.

Usage

Determine_nDims(
  seurat_object,
  threshold_pct = 5,
  reduction = "pca",
  threshold_cum_pct = 90,
  threshold_diff_pct = 0.1,
  elbow_plot = TRUE
)

Arguments

seurat_object: A Seurat object with the target reduction already computed (e.g. via RunPCA() or RunLSI()).
threshold_pct: Numeric. A selected dimension must contribute less than this percentage of total variance. Default 5.
reduction: Character. Name of the reduction slot to inspect. Default "pca".
threshold_cum_pct: Numeric. Cumulative variance (%) that must be reached before Heuristic 1 can trigger. Default 90.
threshold_diff_pct: Numeric. Minimum drop in per-dimension variance between consecutive dimensions for Heuristic 2. Default 0.1.
elbow_plot: Logical. Return an annotated elbow plot? Default TRUE.

Value

A named list:

n_dims: Recommended number of dimensions (integer).
cum_thresh: Dimension selected by Heuristic 1.
elbow_thresh: Dimension selected by Heuristic 2.
plot: A ggplot2 elbow plot, or NULL when elbow_plot = FALSE.

Details

Heuristic 1 - cumulative variance plateau: finds the first dimension where cumulative variance explained exceeds threshold_cum_pct and the per-dimension contribution has already dropped below threshold_pct. This marks the point of diminishing returns.

Heuristic 2 - elbow: finds the last dimension where the drop in per-dimension variance between successive dimensions is still larger than threshold_diff_pct. Beyond this point the curve has flattened.

The function returns the minimum of the two, which is the more conservative choice.