Compositional Analysis

Overview

This block analyzes changes in cell type proportions across experimental conditions. If replicates are too few, it calculates fold changes and generates exploratory visualizations. When replicates are sufficient, it uses scCODA to perform a Bayesian compositional analysis, identifying statistically credible shifts in cell populations.

Pipeline context

This block requires cell type annotations to analyze compositional changes. It can follow either Leiden Clustering (if using clusters as cell types) or Cell Type Annotation.

 Blocks                                 Result pool
                                       ┌───────────
             ┌─────────────────────────┤
             │                         │
             v                         │
 ╔═══════════════════════════╗ exports │
 ║ Leiden Clustering /       ║────->─-─┤ Cell group assignments
 ║ Cell Type Annotation      ║         │ ----------------------
 ╚═══════════════════════════╝         │
                                       ├ [sampleId][cellId] -> groupId
             ┌─────────────────────────┤
             │                         │
             v                         │
 ╔═══════════════════════════╗ exports │
 ║  Compositional Analysis   ║────->─-─┤ Log2FC, q-values per group
 ╚═══════════════════════════╝         │ --------------------------
                                       │
                                       ├ [contrast][cellGroup] -> log2FC, q-value
             ┌─────────────────────────┤
             │                         │
             v                         │
 ╔═══════════════════════╗             │
 ║  Downstream Analysis  ║             │
 ╚═══════════════════════╝             │

Core structure: axes and p-columns

The block consumes cell type or cluster annotations along with sample metadata and produces a p-frame containing the results of the compositional analysis.

Input p-columns

The block requires two main inputs: a p-column with cell cluster/type assignments and one or more metadata p-columns describing the experimental design.

1. Cell Group Annotation

• P-column name: pl7.app/rna-seq/leidencluster or pl7.app/rna-seq/cellType
• Description: The cluster or cell type assignment for each cell.
• Requirement: Required.

# --- Example spec for leidencluster ---
name: pl7.app/rna-seq/leidencluster
valueType: String
axesSpec:
  - name: pl7.app/sampleId
    type: String
  - name: pl7.app/cellId
    type: String

2. Metadata / Covariates

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

# --- Example spec for a treatment covariate ---
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 main statistical results of the compositional analysis.

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/cellGroup
    type: String
    domain:
      pl7.app/blockId: "..." # blockId from this block run
    annotations:
      pl7.app/label": "Cell group"

1. Log2 Fold Change

• P-column name: pl7.app/rna-seq/log2foldchange
• Description: The log2 fold change in the proportion of a cell group for a given contrast.
• Specification:

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

2. q-value

• P-column name: pl7.app/rna-seq/qvalue
• Description: The q-value (FDR-adjusted p-value) for the change in proportion. This column is only produced when there are sufficient replicates for statistical testing.
• Specification:

name: pl7.app/rna-seq/qvalue
valueType: Double
annotations:
  pl7.app/label: "q-value"

Summary of Exported P-Columns

P-Column Name	Description	Axes	Requirement
pl7.app/rna-seq/log2foldchange	Log2 fold change in proportion.	[contrastGroup][cellGroup]	Required
pl7.app/rna-seq/qvalue	Statistical significance.	[contrastGroup][cellGroup]	Conditional