MarkersFinder Process Configuration

Purpose

Flexible marker finding process that wraps Seurat's FindMarkers function for custom group comparisons beyond simple cluster-vs-all analysis. Unlike ClusterMarkers (all-vs-all cluster comparisons), MarkersFinder enables targeted differential expression analysis between specific groups, conditions within cell types, or any custom comparison defined by metadata columns. Automatically performs pathway enrichment analysis on significant markers and generates comprehensive visualizations.

When to Use

• Custom group comparisons: Compare specific clusters (e.g., c1 vs c3)
• Condition effects within cell types: Treatment vs control in T cells
• Targeted differential expression: Focus on biologically meaningful comparisons
• Multi-sample analysis: Find markers across different samples/batches
• Subset-based comparisons: Compare cell states within defined populations
• Complex experimental designs: Multi-condition, multi-factor comparisons

Note: Use

ClusterMarkers

for standard all-vs-all cluster analysis. Use

MarkersFinder

for custom comparisons.

Configuration Structure

Process Enablement

[MarkersFinder]
cache = true

Input Specification

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

Environment Variables

Core Group Specification

[MarkersFinder.envs]
group_by = "seurat_clusters"  # Column in metadata to group cells
ident_1 = ""  # First group (ident.1); if empty, all groups vs rest
ident_2 = ""  # Second group (ident.2); if empty, ident_1 vs rest
each = ""  # Column to create separate cases for each unique value

Statistical Test Selection (Seurat FindMarkers)

[MarkersFinder.envs]
test.use = "wilcox"  # Options: wilcox, MAST, DESeq2, roc, t, tobit, bimod, poisson, negbinom, LR
logfc.threshold = 0.25  # Minimum log2 fold change
min.pct = 0.1  # Minimum percentage of cells expressing gene
min.diff.pct = -Inf  # Minimum difference in detection
only.pos = false  # Only positive markers
min.cells.group = 3  # Minimum cells per group
min.cells.feature = 3  # Minimum cells expressing gene

Significant Markers Filter & Enrichment

[MarkersFinder.envs]
sigmarkers = "p_val_adj < 0.05"  # Filter for enrichment (vars: p_val, avg_log2FC, pct.1, pct.2, p_val_adj)
dbs = ["KEGG_2021_Human", "MSigDB_Hallmark_2020"]  # Pathway databases
enrich_style = "enrichr"  # Options: enrichr, clusterprofiler

Multiple Comparison Cases

[MarkersFinder.envs.cases."T_vs_B"]
group_by = "celltype"
ident_1 = "T cells"
ident_2 = "B cells"

[MarkersFinder.envs.cases."Treatment_vs_Control"]
group_by = "condition"
ident_1 = "treatment"
ident_2 = "control"
subset = "celltype == 'T cells'"

External References

Seurat FindMarkers Parameters

https://satijalab.org/seurat/reference/findmarkers

Key Parameters:

• ident.1

  ,

  ident.2

  : Groups to compare

• test.use

  : Statistical test (wilcox, MAST, DESeq2, roc, etc.)

• logfc.threshold

  : Minimum fold change (log2 scale)

• min.pct

  : Minimum percentage of cells expressing gene

• min.diff.pct

  : Minimum difference in detection between groups

• only.pos

  : Return only positive markers (higher in ident.1)

Enrichment Databases

• "KEGG_2021_Human"

  ,

  "KEGG"

  : KEGG pathways

• "MSigDB_Hallmark_2020"

  ,

  "Hallmark"

  : MSigDB Hallmark

• "GO_Biological_Process_2025"

  : GO Biological Process

• "Reactome_Pathways_2024"

  ,

  "Reactome"

  : Reactome

• "WikiPathways_2024_Human"

  ,

  "WikiPathways"

  : WikiPathways

Full list: https://maayanlab.cloud/Enrichr/#libraries

Configuration Examples

Minimal Configuration

[MarkersFinder]
[MarkersFinder.in]
srtobj = ["SeuratClustering"]
[MarkersFinder.envs]
group_by = "seurat_clusters"

Cluster-to-Cluster Comparison

[MarkersFinder.envs]
group_by = "seurat_clusters"
ident_1 = "c1"
ident_2 = "c3"
logfc.threshold = 0.25
sigmarkers = "p_val_adj < 0.05 & avg_log2FC > 0"

Condition Comparison within Cell Type

[MarkersFinder.envs]
group_by = "condition"
ident_1 = "treatment"
ident_2 = "control"
subset = "celltype == 'T cells'"
test.use = "MAST"

Multiple Comparison Cases

[MarkersFinder.envs.cases."T_vs_B"]
group_by = "celltype"
ident_1 = "T cells"
ident_2 = "B cells"
[MarkersFinder.envs.cases."CD4_vs_CD8"]
group_by = "subtype"
ident_1 = "CD4+ T"
ident_2 = "CD8+ T"
subset = "celltype == 'T cells'"

Cross-Sample Comparison (Using

each

)

[MarkersFinder.envs]
group_by = "seurat_clusters"
ident_1 = "c1"
ident_2 = "c2"
each = "Sample"

Common Patterns

Pattern 1: Specific Cluster Pair

[MarkersFinder.envs]
group_by = "seurat_clusters"
ident_1 = "c1"
ident_2 = "c3"
logfc.threshold = 0.25
sigmarkers = "p_val_adj < 0.05 & avg_log2FC > 0"

Pattern 2: Treatment Effect per Cell Type

[MarkersFinder.envs.cases."Treatment_Tcells"]
group_by = "condition"
ident_1 = "treatment"
ident_2 = "control"
subset = "celltype == 'T cells'"
[MarkersFinder.envs.cases."Treatment_Bcells"]
group_by = "condition"
ident_1 = "treatment"
ident_2 = "control"
subset = "celltype == 'B cells'"

Pattern 3: Multiple Contrasts

[MarkersFinder.envs.cases."T_vs_B"]
group_by = "celltype"
ident_1 = "T cells"
ident_2 = "B cells"
[MarkersFinder.envs.cases."CD4_vs_CD8"]
group_by = "subtype"
ident_1 = "CD4+ T"
ident_2 = "CD8+ T"
subset = "celltype == 'T cells'"

Pattern 4: All Clusters vs Rest (Like ClusterMarkers)

[MarkersFinder.envs]
group_by = "seurat_clusters"

Pattern 5: Cross-Batch Comparison with

each

[MarkersFinder.envs]
group_by = "seurat_clusters"
ident_1 = "c1"
ident_2 = "c2"
each = "Batch"
overlaps = {"Batch_Overlap": {plot_type = "venn"}}

Difference from ClusterMarkers

Feature	ClusterMarkers	MarkersFinder
Default behavior	All clusters vs all other clusters	Customizable comparisons
Group specification	Fixed to seurat_clusters	Any metadata column
Comparisons	All-vs-all matrix	Targeted pairs or groups vs rest
Multiple cases	Single comparison set	Multiple custom cases
Use case	Cluster annotation	Targeted differential expression

When to use which:

• ClusterMarkers: Standard cluster identification, all-vs-all comparisons, quick cluster annotation
• MarkersFinder: Custom comparisons, condition effects, cell type-specific DE, multi-factor designs

Dependencies

• Upstream:

  SeuratClustering

  (provides cluster assignments and metadata)
• Downstream: Custom differential expression analysis, cell type annotation
• Related:

  ClusterMarkers

  (simpler all-vs-all),

  PseudoBulkDEG

  (bulk-like DE)

Validation Rules

• group_by

  must be valid column in Seurat object metadata

• ident_1

  and

  ident_2

  must exist in

  group_by

  column if specified
• Groups must have ≥

  min.cells.group

  cells (default: 3)
• Genes must be expressed in ≥

  min.cells.feature

  cells (default: 3)
• For

  each

  : creates separate case for each unique value in column

• sigmarkers

  must be valid R/dplyr expression with available variables:

  p_val

  ,

  avg_log2FC

  ,

  pct.1

  ,

  pct.2

  ,

  p_val_adj

Troubleshooting

Issue: Group Not Found

Symptoms: Error "ident.1 not found" Solution: Verify

group_by

column name and

ident_1

/

ident_2

values match Seurat object metadata exactly (case-sensitive)

Issue: Insufficient Cells in Groups

Symptoms: No markers found or cell count error Solution: Reduce

min.cells.group

and

min.cells.feature

to 1, or combine similar groups via

mutaters

Issue: No Significant Markers Found

Symptoms: Empty marker tables Solution: Loosen thresholds:

logfc.threshold = 0.1

,

min.pct = 0.05

,

sigmarkers = "p_val_adj < 0.1 & avg_log2FC > 0"

Issue: Too Many Markers Found

Symptoms: Thousands of markers, computationally expensive Solution: Tighten thresholds:

logfc.threshold = 0.58

(1.5-fold),

min.pct = 0.25

,

sigmarkers = "p_val_adj < 0.01 & avg_log2FC > 1"

Issue: Enrichment Analysis Returns No Results

Symptoms: Empty enrichment tables Solution: Loosen

sigmarkers

filter and add more databases:

dbs = ["KEGG_2021_Human", "MSigDB_Hallmark_2020", "Reactome_Pathways_2024"]