KaryoMetab

KaryoMetab is an R package providing a reproducible computational workflow for the joint inference of chromosomal instability (CIN) patterns and metabolic states from single-cell RNA-seq data. The core idea is that tumor cells within the same sample/patient often carry distinct chromosomal copy number alterations, and these karyotypic differences may drive — or at least be associated with — specific metabolic reprogramming. KaryoMetab provides a structured and streamlined set of tools to investigate this hypothesis systematically across single or multiple patient cohorts.

The workflow proceeds in four steps, starting from preprocessed and quality-filtered single-cell data (e.g., following standard Seurat QC and normalization steps):

1. CNV subcluster annotation — Infer copy number alterations using InferCNV and stratify malignant cells into karyotype-specific subpopulations, assigning each cell a unique, run-prefixed identifier. Cells are then grouped by their predicted karyotypic profile (e.g. chromosome 7 gain, euploid, other alterations).
2. Differential expression and GSEA — Compare karyotypically distinct subpopulations using differential expression (DE) and gene set enrichment analysis with fgsea, to characterize the transcriptional differences associated with specific aneuploidy patterns.
3. UCell metabolic scoring — Score cells for a curated panel of metabolic pathway signatures using UCell, a rank-based method robust to batch effects, and visualize metabolic activity differences across karyotype groups with heatmaps and boxplots.
4. COMPASS metabolic flux analysis — Run COMPASS on the karyotype-specific cell groups to infer pathway-level metabolic activities from gene expression data, then perform differential metabolic activity analysis between groups using Wilcoxon rank-sum tests at the reaction level. KaryoMetab provides dedicated functions to process COMPASS outputs, perform statistical comparisons, and generate visualizations.

For a complete walkthrough, see the package vignette.

---

Installation

You can install KaryoMetab from GitHub using devtools:

# Install devtools if needed
install.packages("devtools")

devtools::install_github("RodriguezColmanLab/KaryoMetab")

---

Requirements

KaryoMetab has two categories of dependencies: those that are installed automatically and those that require manual setup.

Automatically installed

All packages listed below are declared as dependencies of KaryoMetab and will be installed automatically when you run devtools::install_github():

dplyr, Seurat, ggplot2, ggpubr, ggrepel, grid, tibble, tidyr, stringr, magrittr, patchwork, RColorBrewer, fgsea, GenomicRanges, IRanges, S4Vectors, rlang, ComplexHeatmap, circlize, msigdbr, MAST, UCell, glue, Matrix

Require manual installation

The following packages must be installed separately before installing KaryoMetab, as they are hosted on GitHub or have specific system-level requirements that prevent automatic installation.

compassR

compassR is a GitHub-only package required for the COMPASS analysis module. Install it before installing KaryoMetab:

devtools::install_github("YosefLab/compassR")

InferCNV (required for CNV inference)

InferCNV must be installed from Bioconductor and requires a Java runtime. Please refer to the InferCNV GitHub page for full installation instructions.

BiocManager::install("infercnv")

COMPASS (required for metabolic flux module)

The COMPASS module of KaryoMetab uses the COMPASS tool (Wagner et al.) for metabolic flux estimation. COMPASS is a Python-based command-line tool that requires:

• A working Python environment
• A valid Gurobi license (free academic licenses are available at gurobi.com)

Please refer COMPASS documentation for detailed instructions on Gurobi license setup and COMPASS installation.

---

Citation

If you use KaryoMetab in your work, please cite this repository:

Broglia G. (2026). KaryoMetab: From InferCNV to Metabolic Signatures. GitHub: https://github.com/RodriguezColmanLab/KaryoMetab

Please also cite the tools used internally:

• InferCNV: Tickle et al., inferCNV of the Trinity CTAT Project, github.com/broadinstitute/inferCNV
• UCell: Andreatta & Carmona (2021), Bioinformatics
• COMPASS: Wagner et al. (2021), Cell Systems
• fgsea: Korotkevich et al. (2021), bioRxiv
• Seurat: Hao et al. (2023), Nature Biotechnology

---

License

This project is licensed under the MIT License — see the LICENSE file for details.