seuratsubclustering

name	seuratsubclustering
description	Performs fine-grained re-clustering on specific subsets of cells (e.g., individual clusters, cell types, or custom subsets). Unlike `Seurat::FindSubCluster` which only finds subclusters within a single cluster, this process performs the complete clustering workflow (PCA, UMAP, FindNeighbors, FindClusters) on any subset of cells defined by metadata filters or cell barcode lists.

SeuratSubClustering Process Configuration

Purpose

Performs fine-grained re-clustering on specific subsets of cells (e.g., individual clusters, cell types, or custom subsets). Unlike Seurat::FindSubCluster which only finds subclusters within a single cluster, this process performs the complete clustering workflow (PCA, UMAP, FindNeighbors, FindClusters) on any subset of cells defined by metadata filters or cell barcode lists.

When to Use

• Cluster heterogeneity analysis: When initial clustering identifies mixed cell populations within a cluster
• Cell type sub-clustering: To resolve heterogeneity within annotated cell types (e.g., T cell subsets: CD4+, CD8+, naive, memory, effector)
• Lineage-specific analysis: To examine substructure within major cell lineages
• Differential sub-populations: When a cluster contains multiple biologically distinct populations (e.g., NK cells + CD4 T cells)
• Multi-resolution exploration: To test different clustering granularities on specific cell subsets
• Downstream marker discovery: When you need markers for sub-populations within larger clusters

Configuration Structure

Process Enablement

[SeuratSubClustering]
cache = true  # Cache intermediate results for faster re-runs

Input Specification

[SeuratSubClustering.in]
srtobj = ["SeuratClustering"]  # Path or reference to Seurat object

Environment Variables

Core Parameters

[SeuratSubClustering.envs]
# Number of cores for parallelization
ncores = 1  # int; Higher values speed up computation

# Metadata mutaters to define subset cells
# Applied BEFORE subsetting to create temporary columns
mutaters = {}  # json; Dictionary of dplyr-like mutations

# Expression to subset cells (dplyr::filter syntax)
# Applied to metadata using tidyseurat::filter()
subset = "seurat_clusters == 'c3'"  # str; Filter expression

# Cache location for intermediate results
cache = "/tmp"  # Path; Set to false to disable caching

Sub-clustering Cases (Multiple Subsets)

[SeuratSubClustering.envs.cases]
# Keys are case names (prefixes for outputs)
# Values inherit envs parameters (except mutaters, cache)
# If empty, default case "subcluster" is created

Case Naming Rules:

• Case name becomes prefix for reductions: <CASENAME>PC_, <CASENAME>UMAP_
• Case name becomes prefix for cluster columns: <CASENAME>.<resolution>
• Case name becomes final cluster column: <CASENAME>
• Non-alphanumeric characters in case names are removed

Metadata Output:

• Each case adds new metadata columns to original Seurat object
• Reductions saved: <CASENAME>.pc, <CASENAME>.umap
• Clusters saved: <CASENAME>.<resolution> for each resolution
• Final clusters: <CASENAME> column

RunPCA Parameters

[SeuratSubClustering.envs.RunPCA]
# See https://satijalab.org/seurat/reference/runpca
# object specified internally as subset object
npcs = 30  # int; Number of PCs to compute

RunUMAP Parameters

[SeuratSubClustering.envs.RunUMAP]
# See https://satijalab.org/seurat/reference/runumap
# object specified internally as subset object
# dims=N expanded to dims=1:N (min(N, ncol-1))

dims = 30  # int; Number of PCs to use

# Use specific features instead of dimensions
# Can be list: {order = "desc(abs(avg_log2FC))", n = 30}
# Or numeric (treated as n with default order)
features = 30  # int or list; Top markers for UMAP

# Reduction to use for UMAP
reduction = "pca"  # str; Uses sobj@misc$integrated_new_reduction if omitted

n.neighbors = 30  # int; Neighborhood size
min.dist = 0.3  # float; Cluster tightness (0.001-0.5)
spread = 1  # float; Embedding scale
seed.use = 42  # int; Random seed

FindNeighbors Parameters

[SeuratSubClustering.envs.FindNeighbors]
# See https://satijalab.org/seurat/reference/findneighbors
# object specified internally

reduction = "pca"  # str; Uses sobj@misc$integrated_new_reduction if omitted
dims = 30  # int; Dimensions to use
k.param = 20  # int; K-nearest neighbors
prune.SNN = 0.067  # float; SNN pruning threshold (default: 1/15)
nn.method = "annoy"  # str; "annoy" or "rann"

FindClusters Parameters

[SeuratSubClustering.envs.FindClusters]
# See https://satijalab.org/seurat/reference/findclusters
# object specified internally

# Resolution: Higher = more clusters, Lower = fewer clusters
# Multiple resolutions supported: [0.4, 0.6, 0.8, 1.0]
# Range syntax: "0.1:0.5:0.1" -> [0.1, 0.2, 0.3, 0.4, 0.5]
resolution = 0.8  # float or list; Default: 0.8

# Cluster labels prefixed with "s" (s1, s2, ...) instead of (s0, s1, ...)
algorithm = 1  # int; 1=Louvain, 4=Leiden (recommended)
graph.name = "pca_snn"  # str; Must match FindNeighbors SNN graph
random.seed = 0  # int; Reproducibility

Multi-resolution Output:

• Multiple resolutions create columns: <CASENAME>_0.4, <CASENAME>_0.6, <CASENAME>_0.8, <CASENAME>
• Final resolution uses last value in list

External References

Seurat Functions

• RunPCA(): https://satijalab.org/seurat/reference/runpca
  • Principal component analysis on subset of cells
• RunUMAP(): https://satijalab.org/seurat/reference/runumap
  • Non-linear dimensionality reduction for visualization
• FindNeighbors(): https://satijalab.org/seurat/reference/findneighbors
  • K-nearest neighbor graph construction
• FindClusters(): https://satijalab.org/seurat/reference/findclusters
  • Community detection (Louvain/Leiden algorithms)

tidyseurat::filter()

https://stemangiola.github.io/tidyseurat/reference/filter.html

• Subset Seurat objects using dplyr-like filter syntax
• Supports logical expressions: seurat_clusters == 'c3', celltype %in% c('CD4', 'CD8')
• Can use any metadata column created by mutaters

Configuration Examples

Minimal Configuration (Default Case)

[SeuratSubClustering]
[SeuratSubClustering.in]
srtobj = ["SeuratClustering"]

Result: Creates default case "subcluster" with all cells

Single Cluster Sub-clustering

[SeuratSubClustering]
[SeuratSubClustering.envs]
subset = "seurat_clusters == 'c3'"

Result: Re-clusters only cells in cluster c3

Metadata-Based Sub-clustering (Cell Type)

[SeuratSubClustering]
[SeuratSubClustering.envs]
# First add cell type annotation via mutaters
mutaters = {is_cd4 = "if_else(celltype == 'CD4 T cell', TRUE, FALSE)"}

[SeuratSubClustering.envs.RunPCA]
npcs = 50

[SeuratSubClustering.envs.FindClusters]
resolution = 1.2
algorithm = 4  # Leiden

Result: Creates subcluster case for CD4+ cells only

Multiple Sub-clustering Cases

[SeuratSubClustering]
[SeuratSubClustering.envs]
# Define multiple sub-clustering cases
[SeuratSubClustering.envs.cases.TEffector]
subset = "celltype == 'CD8 T cell' & state == 'Effector'"
resolution = 1.0

[SeuratSubClustering.envs.cases.TNaive]
subset = "celltype == 'CD8 T cell' & state == 'Naive'"
resolution = 0.8

[SeuratSubClustering.envs.cases.CD4Memory]
subset = "celltype == 'CD4 T cell' & state == 'Memory'"
resolution = 1.5

Result: Three sub-clustering analyses with different resolutions

• Metadata columns: TEffector, TNaive, CD4Memory
• Reductions: TEFFECTORPC_, TNAIVEPC_, CD4MEMORYPC_, etc.
• Clusters: TEffector, TNaive, CD4Memory

Multi-resolution Sub-clustering

[SeuratSubClustering]
[SeuratSubClustering.envs.cases.Cluster3]
subset = "seurat_clusters == 'c3'"

[SeuratSubClustering.envs.cases.Cluster3.FindClusters]
# Test multiple resolutions
resolution = "0.4:1.2:0.2"  # [0.4, 0.6, 0.8, 1.0, 1.2]
algorithm = 4  # Leiden

Result: Cluster3 has columns Cluster3_0.4, Cluster3_0.6, Cluster3_0.8, Cluster3_1.0, Cluster3

Using Top Markers for UMAP

[SeuratSubClustering]
[SeuratSubClustering.envs.cases.MixedCluster]
subset = "seurat_clusters == 'c5'"

[SeuratSubClustering.envs.cases.MixedCluster.RunUMAP]
# Use top 30 DEGs for UMAP instead of PCs
features = {order = "desc(abs(avg_log2FC))", n = 30}

Result: Sub-cluster based on top DEGs for better separation

Leiden Algorithm with Custom Parameters

[SeuratSubClustering]
[SeuratSubClustering.envs]
ncores = 4

[SeuratSubClustering.envs.FindNeighbors]
k.param = 30
prune.SNN = 0.05

[SeuratSubClustering.envs.FindClusters]
algorithm = 4  # Leiden
resolution = 1.0
random.seed = 42

Complex Subset with Multiple Conditions

[SeuratSubClustering]
[SeuratSubClustering.envs.cases.ActivatedT]
subset = "celltype %in% c('CD4 T cell', 'CD8 T cell') & activation == 'Activated'"

[SeuratSubClustering.envs.cases.ActivatedT.RunPCA]
npcs = 40

[SeuratSubClustering.envs.cases.ActivatedT.RunUMAP]
dims = 40
n.neighbors = 20
min.dist = 0.2

Common Patterns

Pattern 1: Single Cluster Deep Dive

[SeuratSubClustering]
[SeuratSubClustering.envs]
# Re-cluster cluster 3 to resolve heterogeneity
subset = "seurat_clusters == 'c3'"

Pattern 2: Multiple Lineage Sub-clustering

[SeuratSubClustering]
[SeuratSubClustering.envs.cases.TCD4]
subset = "celltype == 'CD4 T cell'"

[SeuratSubClustering.envs.cases.TCD8]
subset = "celltype == 'CD8 T cell'"

[SeuratSubClustering.envs.cases.TGD]
subset = "celltype == 'Gamma delta T cell'"

[SeuratSubClustering.envs.cases.NK]
subset = "celltype == 'NK cell'"

Pattern 3: Functional State Sub-clustering

[SeuratSubClustering]
[SeuratSubClustering.envs.cases.Effector]
subset = "state == 'Effector'"

[SeuratSubClustering.envs.cases.Effector.FindClusters]
resolution = 1.5  # Higher resolution for more sub-states

[SeuratSubClustering.envs.cases.Memory]
subset = "state == 'Memory'"

[SeuratSubClustering.envs.cases.Naive]
subset = "state == 'Naive'"

Pattern 4: Re-clustering Based on Clonality (TCR+)

[SeuratSubClustering]
[SeuratSubClustering.envs]
# After ScRepCombiningExpression adds clonality metadata
[SeuratSubClustering.envs.cases.ExpandedClones]
subset = "clone_size >= 5"  # Large clones

[SeuratSubClustering.envs.cases.ExpandedClones.FindClusters]
resolution = 0.6  # Lower resolution for broader groups

[SeuratSubClustering.envs.cases.RareClones]
subset = "clone_size == 1"  # Unique clones

[SeuratSubClustering.envs.cases.RareClones.FindClusters]
resolution = 1.2  # Higher resolution to capture diversity

Pattern 5: Multi-resolution Exploration

[SeuratSubClustering]
[SeuratSubClustering.envs.cases.TumorCluster]
subset = "seurat_clusters == 'c8'"

[SeuratSubClustering.envs.cases.TumorCluster.FindClusters]
resolution = "0.2:2.0:0.2"  # Sweep: [0.2, 0.4, ..., 2.0]
algorithm = 4  # Leiden

Dependencies

Upstream Processes

• Required: SeuratClustering (or SeuratClusteringOfAllCells if TOrBCellSelection used)
• Optional: ScRepCombiningExpression (if TCR/BCR data present, adds clonality metadata for subsetting)
• Optional: CellTypeAnnotation (if using annotated cell types for subsetting)

Downstream Processes

• SeuratClusterStats: Statistics for sub-clusters
• ClusterMarkers: Differential expression between sub-clusters
• MarkersFinder: Flexible marker finding with enrichment analysis
• ScFGSEA: Pathway analysis on sub-cluster markers
• ModuleScoreCalculator: Module scoring within sub-clusters

Validation Rules

Subset Expression Validation

• Must be valid dplyr::filter() expression
• Can reference any metadata column in Seurat object
• Complex expressions supported: & (AND), | (OR), %in% (in operator)
• Example: seurat_clusters == 'c3' & percent.mt < 5
• Example: celltype %in% c('CD4 T cell', 'CD8 T cell')

Case Name Validation

• Must contain only alphanumeric characters
• Non-alphanumeric characters automatically removed
• Used as prefix: reductions and cluster names
• Avoid spaces, special characters in case names

Resolution Constraints

• Must be positive (resolution > 0)
• Single value, list, or range syntax allowed
• Range: "start:end:step" (step defaults to 0.1 if omitted)
• Multi-resolution creates multiple metadata columns

Dimension Requirements

• RunPCA.npcs must not exceed cells in subset
• RunUMAP.dims automatically truncated to min(dims, ncol(reduction) - 1)
• Use fewer dimensions for small subsets (< 100 cells)

Graph Name Consistency

• FindClusters.graph.name must match FindNeighbors output
• Default: pca_snn when not specified
• When using integrated reductions, ensure consistency

Troubleshooting

Issue: Subset Returns Zero Cells

Symptoms: Sub-clustering produces empty subset

Solutions:

1. Verify subset expression syntax

# Check if column exists and values are correct
[SeuratSubClustering.envs]
# Use single quotes for string comparison
subset = "seurat_clusters == 'c3'"  # Correct
subset = "seurat_clusters == c3"  # Wrong (treated as variable)

2. Verify column names exist in metadata

# Use existing columns only
subset = "seurat_clusters == 'c3'"  # seurat_clusters exists
subset = "cluster_id == 'c3'"  # cluster_id may not exist

3. Check for exact string matching

# Case-sensitive
subset = "celltype == 'CD4 T cell'"  # Exact match
subset = "celltype == 'CD4 T Cell'"  # Wrong case

Issue: Too Many Small Sub-clusters

Symptoms: Hundreds of tiny sub-clusters, many singletons

Solutions:

[SeuratSubClustering.envs.FindClusters]
resolution = 0.4  # Lower resolution
algorithm = 4  # Leiden handles singletons better

Issue: Sub-clusters Overlapping in UMAP

Symptoms: Poor separation in sub-cluster visualization

Solutions:

[SeuratSubClustering.envs.RunUMAP]
min.dist = 0.1  # Tighter clusters
n.neighbors = 15  # More local detail
spread = 1.2  # More separation

Issue: Sub-clustering Uses Wrong Reduction

Symptoms: Clustering on raw RNA instead of integrated data

Solutions:

[SeuratSubClustering.envs.FindNeighbors]
reduction = "integrated.cca"  # Use integrated reduction

[SeuratSubClustering.envs.RunUMAP]
reduction = "integrated.cca"

Issue: Multi-resolution Columns Not Created

Symptoms: Only final resolution column appears

Solutions:

[SeuratSubClustering.envs.FindClusters]
# Use list syntax (not single value with range)
resolution = [0.4, 0.6, 0.8, 1.0]  # Correct
resolution = "0.4:1.0:0.2"  # Also correct

Issue: Case Names Too Similar

Symptoms: Confusion between multiple cases

Solutions:

# Use descriptive, unique case names
[SeuratSubClustering.envs.cases]
T_CD4_Effector = {subset = "..."}
T_CD4_Naive = {subset = "..."}
B_Memory = {subset = "..."}

Issue: Sub-clustering on All Cells (Not Subset)

Symptoms: Default case runs on entire object

Solutions:

# Always specify subset or use cases
[SeuratSubClustering.envs]
subset = "seurat_clusters == 'c3'"  # Explicit subset

# Or define specific cases
[SeuratSubClustering.envs.cases.MyCase]
subset = "seurat_clusters == 'c3'"

Issue: Reductions Not Saved

Symptoms: Cannot find <CASENAME>PC_ or <CASENAME>UMAP_

Solutions:

# Ensure case name is alphanumeric only
[SeuratSubClustering.envs.cases]
MySubCluster1 = {subset = "..."}  # Correct
Sub-Cluster = {subset = "..."}  # Hyphen removed -> SubCluster

# Check metadata for actual reduction names
# Reductions are: <CASENAME>pc, <CASENAME>umap (lowercase)

Best Practices

1. Define explicit subsets: Always specify subset or define cases to avoid default case on all cells
2. Use descriptive case names: Make case names clear and unique (e.g., T_Effector, not case1)
3. Test multiple resolutions: Sweep resolution range to find optimal granularity for each subset
4. Use Leiden algorithm: Prefer algorithm = 4 for better community detection
5. Leverage metadata columns: Use CellTypeAnnotation results, TCR clonality, or custom mutaters for subsetting
6. Set random seeds: Ensure reproducible sub-clustering results with random.seed
7. Parallelize large subsets: Use ncores > 1 for subsets > 10k cells
8. Adjust UMAP parameters: Smaller subsets may need different n.neighbors and min.dist
9. Document sub-clustering strategy: Comment on biological rationale for each case in config
10. Use multi-resolution: Test [0.4, 0.6, 0.8, 1.0] to capture different granularities

Related Processes

• SeuratClustering: Initial clustering before sub-clustering
• SeuratClusteringOfAllCells: Clustering before T/B cell selection
• CellTypeAnnotation: Annotate clusters before sub-clustering by cell type
• ClusterMarkers: Find markers for sub-clusters
• MarkersFinder: Flexible marker finding with multiple comparison groups