User Guide

This guide covers single-modal GEDI and joint MultiGEDI integration for single-cell count and indicator modalities.

Tutorials

Overview

multigedi uses Gene Expression Decomposition for Integration to learn a shared latent space across samples. MultiGEDI couples modality-specific spokes through shared cell factors.

The GEDI Model

GEDI models gene expression as:

$$Y_i = ZDB_i + Q_i B_i + \mathbf{1}s_i^T + o_i\mathbf{1}^T + o\mathbf{1}^T + \epsilon$$

Where:

  • $Y_i$ is the log-transformed expression matrix for sample $i$

  • $Z$ is the shared metagene matrix (genes × latent factors)

  • $D$ is a diagonal scaling matrix

  • $B_i$ is the sample-specific cell factor matrix

  • $Q_i$ captures sample-specific deviations

  • $s_i$ and $o_i$ are cell and gene offsets

  • $o$ is the global gene offset

Workflow

A typical multigedi workflow consists of:

  1. Load data - Read H5AD files or other formats

  2. Preprocess - Filter features/cells while retaining raw counts for M and M_list inputs; GEDI performs its observation transform internally

  3. Run GEDI/MultiGEDI - Train the model to learn latent factors

  4. Analyze - Compute projections, embeddings, differential expression

  5. Visualize - Plot results using multigedi or scanpy

API Convention

multigedi follows the scanpy API convention:

import multigedi as gd

# Tools module (gd.tl)
gd.tl.gedi(adata, ...)        # Run GEDI
gd.tl.multigedi(mdata, ...)   # Run joint MultiGEDI
gd.tl.umap(adata, ...)        # Compute UMAP

# Plotting module (gd.pl)
gd.pl.embedding(adata, ...)   # Plot embeddings
gd.pl.convergence(adata, ...) # Plot convergence

# I/O module (gd.io)
gd.read_h5ad(...)             # Read data
gd.write_h5ad(...)            # Write data

Results are stored in the AnnData object:

  • adata.obsm['X_gedi'] - Cell embeddings (DB projection)

  • adata.varm['gedi_Z'] - Gene loadings (Z matrix)

  • adata.uns['gedi'] - Model parameters and metadata

Joint MultiGEDI results use mdata.uns['multigedi']; row-aligned PCA coordinates are written to every participating modality’s obsm['X_multigedi_pca'].

Next Steps