Single-Cell Differential Expression

Overview

This block compares gene expression between two groups of single cells (e.g., genotypes or treatments), identifies differentially expressed genes using the Wilcoxon test, and outputs a full result table. Results are visualized with a volcano plot.

Pipeline context

This block requires a count matrix and cell annotations (either clusters or cell types) to define the groups for comparison.

 Blocks                                 Result pool
                                       ┌───────────
             ┌─────────────────────────┤
             │                         │
             v                         │
 ╔═══════════════════════════╗ exports │
 ║ scRNA-seq Preprocessing / ║────->─-─┤ Counts & Annotations
 ║ Leiden Clustering /       ║         │ --------------------
 ║ Cell Type Annotation      ║         │
 ╚═══════════════════════════╝         │
                                       ├ [sampleId][cellId][geneId] -> count
                                       ├ [sampleId][cellId] -> groupId
             ┌─────────────────────────┤
             │                         │
             v                         │
 ╔═══════════════════════════╗ exports │
 ║  Differential Expression  ║────->─-─┤ DE statistics
 ╚═══════════════════════════╝         │ ---------------
                                       │
                                       ├ [contrast][geneId] -> log2FC, q-value
             ┌─────────────────────────┤
             │                         │
             v                         │
 ╔═══════════════════════╗             │
 ║  Downstream Analysis  ║             │
 ╚═══════════════════════╝             │

Core structure: axes and p-columns

The block consumes a count matrix and metadata to perform differential expression analysis, producing a p-frame with detailed statistics for each gene.

Input p-columns

1. Raw Counts

• P-column name: pl7.app/rna-seq/countMatrix
• Description: The raw number of reads (or UMIs) for each gene in each cell.
• Requirement: Required.

name: pl7.app/rna-seq/countMatrix
valueType: Long
axesSpec:
  - name: pl7.app/sampleId
    type: String
  - name: pl7.app/sc/cellId
    type: String
  - name: pl7.app/geneId
    type: String
domain:
  pl7.app/rna-seq/normalized: "false"
annotations:
  pl7.app/label: "Raw Count Matrix"

2. Metadata / Covariates

• P-column name: pl7.app/metadata
• Description: Describes experimental variables for each sample (e.g., treatment, timepoint, donor), used to define the comparison groups.
• Requirement: Required.

name: pl7.app/metadata
valueType: String
axesSpec:
  - name: pl7.app/sampleId
    type: String
domain:
    pl7.app/metadata/key: "treatment"

Exported P-Columns

The block exports a single p-frame containing the full, unfiltered differential expression results.

Common Axes Specification: All exported p-columns in this p-frame share the following axes:

# --- Axes ---
axesSpec:
  - name: pl7.app/rna-seq/contrastGroup
    type: String
    domain:
      pl7.app/blockId: "..." # blockId from this block run
    annotations:
      pl7.app/label: "Contrast"
  - name: pl7.app/rna-seq/geneId
    type: String
    domain:
      pl7.app/species: "..." # e.g., "mus_musculus"
    annotations:
      pl7.app/label": "Ensembl Id"

1. Log2 Fold Change

• P-column name: pl7.app/rna-seq/log2foldchange
• Description: The log2 fold change of gene expression between the two groups.
• Specification:

name: pl7.app/rna-seq/log2foldchange
valueType: Double
annotations:
  pl7.app/label: "Log2FC"

2. Adjusted p-value

• P-column name: pl7.app/rna-seq/padj
• Description: The adjusted p-value from the Wilcoxon rank-sum test.
• Specification:

name: pl7.app/rna-seq/padj
valueType: Double
annotations:
  pl7.app/label: "Adjusted p-value"

3. -log10 Adjusted p-value

• P-column name: pl7.app/rna-seq/minlog10padj
• Description: The negative log10 of the adjusted p-value, used for visualization in volcano plots.
• Specification:

name: pl7.app/rna-seq/minlog10padj
valueType: Double
annotations:
  pl7.app/label: "-log10 adjusted p-value"

4. Regulation Direction

• P-column name: pl7.app/rna-seq/regulationDirection
• Description: Indicates whether the gene is "Up"-regulated, "Down"-regulated, or "NS" (not significant) based on the provided thresholds.
• Specification:

name: pl7.app/rna-seq/regulationDirection
valueType: String
annotations:
  pl7.app/label: "Regulation direction"

Summary of Exported P-Columns

P-Column Name	Description	Axes	Requirement
pl7.app/rna-seq/log2foldchange	Log2 fold change of gene expression.	[contrastGroup][geneId]	Required
pl7.app/rna-seq/padj	Adjusted p-value.	[contrastGroup][geneId]	Required
pl7.app/rna-seq/minlog10padj	-log10 of the adjusted p-value.	[contrastGroup][geneId]	Required
pl7.app/rna-seq/regulationDirection	Regulation direction ("Up", "Down", "NS").	[contrastGroup][geneId]	Required