UDON: Unsupervised Discovery of Novel Disease Programs

UDON is a Python package for unsupervised discovery of disease subtypes from patient scRNA-seq data.
It leverages control-normalized pseudobulk expression and sparse NMF to identify stable cell-state perturbations.

UDON includes:

• SATAY-UDON for metadata enrichment
• SASHIMI-UDON for cohorts with limited controls (coming soon!)

🚀 Installation

Create a virtual environment and install UDON from PyPI:

conda create -n udon_env python=3.10
conda activate udon_env

pip install py-udon

📂 Input Requirements

UDON currently supports h5ad format and human scRNA-seq data.

• If your data is in Seurat, convert it to .h5ad (AnnData) format using one of:

  • SeuratDisk
  • sceasy

• Alternatively, generate an AnnData object directly using Scanpy.

• For non-human datasets, please reach out by opening a GitHub issue. I’ll help set up the appropriate database for your species.

🛠 Usage and Documentation

1. Download the database files

   • Download the database files attached as zip file here.
   • Please unzip the database folder and note the path to the folder and its contents. UDON requires access to this folder when running.

2. Run the example dataset

   • Download the example dataset: SJIA cohort (GSE207633)
   • Tutorial can be found at run_example_dataset.py

3. Ensure input normalization
   UDON expects normalized expression values in adata.X.

   • In a Seurat object:

     NormalizeData(object)
     

   • In an Scanpy h5ad:

     sc.pp.normalize_total(adata, target_sum=1e4)
     sc.pp.log1p(adata)
     

4. Prepare donor metadata

   • UDON requires a donor-level metadata file.
   • Example: donor_metadata.xlsx
   • Make sure your metadata follows this structure.